From f59dfb4fca92d713657c649ce095ffcf52953fbd Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 21:44:06 -0700
Subject: [PATCH 001/108] start: #1 The first release, v0.1.0


From 224052705a85b72fbaf75a653617bc7d2747cb49 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:02:26 -0700
Subject: [PATCH 002/108] #1 .kit: the delivered tree

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md             |  78 ++++++++++++
 .kit/bash/1st.sh        | 129 ++++++++++++++++++++
 .kit/bash/gh.sh         | 223 ++++++++++++++++++++++++++++++++++
 .kit/bash/git.sh        | 262 ++++++++++++++++++++++++++++++++++++++++
 .kit/ci.yml             | 141 +++++++++++++++++++++
 .kit/hooks/pre-commit   |  85 +++++++++++++
 .kit/hooks/pre-rebase   |  46 +++++++
 .kit/kit.just           |  67 ++++++++++
 .kit/rules/bash.md      |  43 +++++++
 .kit/rules/gitignore.md |  24 ++++
 .kit/rules/json.md      |  21 ++++
 .kit/rules/just.md      |  44 +++++++
 .kit/rules/markdown.md  |  39 ++++++
 .kit/rules/yaml.md      |  29 +++++
 .kit/settings.json      |  12 ++
 .kit/version            |   1 +
 16 files changed, 1244 insertions(+)
 create mode 100644 .kit/1st.md
 create mode 100644 .kit/bash/1st.sh
 create mode 100644 .kit/bash/gh.sh
 create mode 100644 .kit/bash/git.sh
 create mode 100644 .kit/ci.yml
 create mode 100755 .kit/hooks/pre-commit
 create mode 100755 .kit/hooks/pre-rebase
 create mode 100644 .kit/kit.just
 create mode 100644 .kit/rules/bash.md
 create mode 100644 .kit/rules/gitignore.md
 create mode 100644 .kit/rules/json.md
 create mode 100644 .kit/rules/just.md
 create mode 100644 .kit/rules/markdown.md
 create mode 100644 .kit/rules/yaml.md
 create mode 100644 .kit/settings.json
 create mode 100644 .kit/version

diff --git a/.kit/1st.md b/.kit/1st.md
new file mode 100644
index 0000000..e51c83d
--- /dev/null
+++ b/.kit/1st.md
@@ -0,0 +1,78 @@
+# Read this first
+
+This file is the kit's entry. It binds every agent and every session in a repository that carries `.kit/`, and
+the repository's own rules in `AGENTS.md` bind beside it. Where the two differ, the repository's rule wins.
+
+## Integrity
+
+1. Report only what happened. Write "done", "passing", or "verified" only for what ran and held.
+2. A skip is a skip. A check not run, not implemented, or not implementable is reported as exactly that. It
+   clears no gate and earns no credit.
+3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
+4. Being wrong is recoverable. Misreporting is not.
+
+## `main` is the human's desk
+
+The checkout at the repository root stays on the default branch. It is where the human types, reviews, and
+leaves work in progress. Never check out, reset, rebase, or otherwise change it in place. Work happens in a
+worktree under `worktrees/`, one per issue, and reaches `main` only through a merged pull request.
+
+## The loop
+
+1. An issue exists. A change without an issue has not started.
+2. `just kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a
+   draft pull request. It never switches the checkout it is run from.
+3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`.
+4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
+   and how, and what was left out and why.
+5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
+   observed.
+
+## Plans are prose
+
+A design, a spec, or a plan is the body of an issue, written in prose. It is never a committed file. When
+the design is written, the issue is the deliverable, and the loop above starts from it.
+
+## The worker contract
+
+A worker is whoever implements one issue in the worktree that issue names.
+
+1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints `<N>-`.
+2. Do every command from there. Never touch the repository root checkout.
+3. Never run `just kit issue`, make a branch, or make a worktree. Those were done before the handoff.
+4. Implement what the issue asks and nothing beside it.
+5. Push as you go.
+6. Run the repository's gate before calling anything done, and run it through the pinned toolchain.
+7. End with `gh pr ready` and the report in the pull request body.
+8. If the gate fails or the work is partial, leave the pull request a draft and say why.
+9. Never merge.
+10. Report what ran and what it printed, nothing more.
+
+## Rules by file type
+
+Each file kind has a rule file under `.kit/rules/`. A harness that loads rules by path finds the same text
+under `.claude/rules/kit-<kind>.md`. Read the rule for a kind before writing a file of that kind.
+
+| Kind | Paths | Rule |
+| --- | --- | --- |
+| Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
+| Bash | `*.sh`, `*.bash`, `.kit/hooks/*` | [rules/bash.md](rules/bash.md) |
+| Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
+| YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
+| JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
+| Ignore lists | `.gitignore` | [rules/gitignore.md](rules/gitignore.md) |
+
+## What the kit carries
+
+- `.kit/kit.just`, a just module. The consumer's root justfile takes it with `mod kit ".kit/kit.just"`,
+  which gives `just kit issue`, `just kit tidy`, and `just kit status`. The bash behind them is `.kit/bash/`.
+- `.kit/hooks/pre-rebase` refuses a rebase of the default branch. `.kit/hooks/pre-commit` lints the staged
+  paths. `kit install` sets `core.hooksPath` to `.kit/hooks`.
+- `.kit/settings.json`, deny rules for Claude Code that `kit install` merges into `.claude/settings.json`.
+  The kit owns only the entries it writes; the consumer may add its own.
+- `.kit/ci.yml`, placed as `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
+  runs `kit check`, and refuses a pull request not linked to an open issue.
+- `.kit/manifest`, written by `kit install`: the release version and a checksum per delivered file.
+
+`kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
+new release and running `kit update`, never by editing them in place.
diff --git a/.kit/bash/1st.sh b/.kit/bash/1st.sh
new file mode 100644
index 0000000..89d94e8
--- /dev/null
+++ b/.kit/bash/1st.sh
@@ -0,0 +1,129 @@
+# shellcheck shell=bash
+# 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Sourced into every recipe body of .kit/kit.just through BASH_ENV, and by bin/kit and the hooks that need a
+# verb. It defines functions only and sets no shell option, so the caller's options stand. A module under
+# .kit/bash/ is loaded on first use with `use <module>`, and each exported function has a stub here so a
+# caller never has to load it by hand.
+#
+# Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
+# NO_COLOR is set. Under GitHub Actions, warn and error also emit the matching workflow command.
+
+kit_bash_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+declare -gr kit_bash_dir
+declare -Ag kit_modules=([1st]=1)
+
+# use <module>… loads .kit/bash/<module>.sh once. An unknown module is a bug in the caller, so it is fatal.
+use() {
+  local module
+  for module in "$@"
+  do
+    [[ ${kit_modules[${module}]+x} ]] && continue
+    if [[ ! -f "${kit_bash_dir}/${module}.sh" ]]
+    then
+      error "no such kit bash module: ${module} (looked in ${kit_bash_dir})"
+      return 2
+    fi
+    kit_modules[${module}]=1
+    # shellcheck disable=SC1090  # the path is computed from the module name
+    source "${kit_bash_dir}/${module}.sh"
+  done
+}
+
+if [[ -n "${NO_COLOR:-}" ]]
+then
+  declare -gr out_color=0
+elif [[ -t 2 ]]
+then
+  declare -gr out_color=1
+else
+  declare -gr out_color=0
+fi
+
+out:sgr() {
+  (( out_color )) && printf '\x1b[%sm' "$1"
+  return 0
+}
+
+# out:emit <icon> <sgr> <message>… prints one line to stderr.
+out:emit() {
+  local icon=$1 sgr=$2
+  shift 2
+  printf '%s%s %s%s\n' "$(out:sgr "${sgr}")" "${icon}" "$*" "$(out:sgr 0)" >&2
+}
+
+info()    { out:emit '•' '' "$@"; }
+step()    { out:emit '→' '36' "$@"; }
+ok()      { out:emit '✅' '32' "$@"; }
+section() { out:emit '' '1' "── $* ──"; }
+
+warn() {
+  out:emit '⚠️' '33' "$@"
+  [[ -n "${GITHUB_ACTIONS:-}" ]] && echo "::warning::$*" >&2
+  return 0
+}
+
+error() {
+  out:emit '❌' '31' "$@"
+  [[ -n "${GITHUB_ACTIONS:-}" ]] && echo "::error::$*" >&2
+  return 0
+}
+
+# guard:require <predicate>… returns non-zero on the first predicate that does not hold, with the remedy.
+#   gh           gh is usably authenticated (a real API call, since a revoked token still passes gh auth status)
+#   signing-key  git user.signingkey is set
+#   tool:<name>  <name> is on PATH
+guard:require() {
+  local predicate
+  for predicate in "$@"
+  do
+    case "${predicate}" in
+      (gh)
+        if ! gh api user --jq '.login' >/dev/null 2>&1
+        then
+          error "run: gh auth login (the GitHub CLI is not authenticated)"
+          return 1
+        fi
+        ;;
+      (signing-key)
+        if [[ -z "$(git config user.signingkey 2>/dev/null)" ]]
+        then
+          error "run: git config user.signingkey <key> (every commit here is signed, and none is configured)"
+          return 1
+        fi
+        ;;
+      (tool:*)
+        local tool=${predicate#tool:}
+        if ! command -v "${tool}" >/dev/null 2>&1
+        then
+          error "run: mise install (${tool} is not on PATH)"
+          return 1
+        fi
+        ;;
+      (*)
+        error "guard:require: unknown predicate '${predicate}'"
+        return 1
+    esac
+  done
+}
+
+# git:default-branch prints the default branch: origin/HEAD, with main as the fallback.
+git:default-branch() {
+  local branch
+  branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+  [[ -n "${branch}" ]] || branch=main
+  printf '%s\n' "${branch}"
+}
+
+# git:main-root prints the root of the main checkout, the first entry of the worktree list. worktrees/ lives
+# under it whether the caller stands in the main checkout or in a linked worktree.
+git:main-root() {
+  git worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
+}
+
+gh:issue()  { use gh && gh:issue "$@"; }
+git:tidy()  { use git && git:tidy "$@"; }
+git:status() { use git && git:status "$@"; }
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/bash/gh.sh b/.kit/bash/gh.sh
new file mode 100644
index 0000000..c0e8f49
--- /dev/null
+++ b/.kit/bash/gh.sh
@@ -0,0 +1,223 @@
+# shellcheck shell=bash
+# gh.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft pull request (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# gh:issue [<number>…] is the one command the loop needs and no vendor provides. The first number is the
+# primary issue, linked to the branch under Development by `gh issue develop`, which closes it on merge. Any
+# further number is a secondary, closed by a `Closes #N` line in the pull request body. Every listed issue is
+# assigned to the caller.
+#
+# It never switches the checkout it is run from. The branch is checked out in worktrees/<N>-<slug> under the
+# main checkout's root, and an existing branch, worktree, or pull request is reused, so a re-run reconciles
+# rather than duplicates.
+#
+# With no argument and a terminal on stdin it asks for a title, creates the issue, and continues. Without a
+# terminal the usage error stands, so an agent never hangs on a prompt.
+#
+# If the invoking checkout is on the default branch and carries uncommitted changes, they are swept into the
+# new worktree as uncommitted changes and the invoking checkout is left clean, then fast-forwarded to origin.
+# The sweep runs only from the default-branch checkout: inside another worktree, dirty files are that issue's
+# own work and are never moved. A sweep that cannot apply leaves the stash in place and stops, so nothing is
+# lost.
+
+gh:issue() {
+  if (( $# == 0 ))
+  then
+    if [[ ! -t 0 ]]
+    then
+      error "usage: just kit issue <issue-number> [<issue-number>…]"
+      return 2
+    fi
+    guard:require gh || return 1
+    local new_title new_number
+    read -r -p "Issue title: " new_title
+    if [[ -z "${new_title}" ]]
+    then
+      error "an issue title is required"
+      return 2
+    fi
+    new_number=$(gh issue create --title "${new_title}" --body "" 2>/dev/null | sed -n 's@.*/issues/@@p')
+    if [[ ! "${new_number}" =~ ^[0-9]+$ ]]
+    then
+      error "run: gh auth status (the issue could not be created)"
+      return 1
+    fi
+    ok "Created #${new_number}: ${new_title}"
+    set -- "${new_number}"
+  fi
+
+  local n
+  for n in "$@"
+  do
+    if [[ ! "${n}" =~ ^[0-9]+$ ]]
+    then
+      error "not an issue number: '${n}'"
+      return 2
+    fi
+  done
+  local primary=$1
+
+  guard:require gh || return 1
+  git fetch --quiet --prune origin
+
+  local default_branch main_root invoking_root invoking_branch
+  default_branch=$(git:default-branch)
+  main_root=$(git:main-root)
+  invoking_root=$(git rev-parse --show-toplevel)
+  invoking_branch=$(git -C "${invoking_root}" rev-parse --abbrev-ref HEAD)
+
+  local do_sweep=false stash_ref=""
+  if [[ "${invoking_branch}" == "${default_branch}" && -n "$(git -C "${invoking_root}" status --porcelain)" ]]
+  then
+    do_sweep=true
+  fi
+
+  local title
+  title=$(gh issue view "${primary}" --json title --jq '.title')
+  if [[ -z "${title}" ]]
+  then
+    error "run: gh auth status (the title of #${primary} could not be read)"
+    return 1
+  fi
+
+  local me assignees
+  me=$(gh api user --jq '.login')
+  if [[ -z "${me}" ]]
+  then
+    error "run: gh auth status (the current user could not be read)"
+    return 1
+  fi
+  for n in "$@"
+  do
+    assignees=$(gh issue view "${n}" --json assignees --jq '[.assignees[].login] | join(" ")')
+    [[ " ${assignees} " == *" ${me} "* ]] && continue
+    if [[ -n "${assignees}" ]]
+    then
+      warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
+    fi
+    if ! gh issue edit "${n}" --add-assignee "${me}" >/dev/null 2>&1
+    then
+      warn "#${n} could not be assigned to ${me}; assign it by hand."
+    fi
+  done
+
+  section "Starting #${primary}: ${title}"
+
+  # The branch gh made for the issue, found by an open pull request's head, then by the remote ref. Any hit is
+  # reused, so a second run never forks a <N>-<slug>-1 duplicate.
+  local branch
+  branch=$(gh pr list --state open --json headRefName \
+    --jq "[.[] | select(.headRefName | test(\"^${primary}-\"))] | .[0].headRefName // empty" 2>/dev/null || true)
+  [[ -n "${branch}" ]] || branch=$(git ls-remote --heads origin "${primary}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+  if [[ -z "${branch}" ]]
+  then
+    step "Linking a branch to #${primary} (gh issue develop)"
+    gh issue develop "${primary}" --base "${default_branch}" >/dev/null
+    git fetch --quiet origin
+    branch=$(git ls-remote --heads origin "${primary}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+    if [[ -z "${branch}" ]]
+    then
+      error "the branch gh made for #${primary} could not be found; run: gh issue develop ${primary} --list"
+      return 1
+    fi
+  fi
+
+  if [[ "${do_sweep}" == true ]]
+  then
+    step "Sweeping the uncommitted work on ${default_branch} into the worktree"
+    if ! git -C "${invoking_root}" stash push --include-untracked --message "kit issue #${primary} → ${branch}" >/dev/null
+    then
+      error "the uncommitted work on ${default_branch} could not be stashed; resolve it by hand and re-run."
+      return 1
+    fi
+    stash_ref=$(git -C "${invoking_root}" rev-parse 'stash@{0}')
+  fi
+
+  local wt
+  wt=$(git worktree list --porcelain 2>/dev/null \
+    | awk -v b="branch refs/heads/${branch}" '/^worktree /{w=substr($0,10)} $0==b{print w; exit}')
+  if [[ -n "${wt}" ]]
+  then
+    step "Reusing worktree ${wt}"
+  else
+    wt="${main_root}/worktrees/${branch}"
+    if [[ -e "${wt}" ]]
+    then
+      error "${wt} exists but is not a worktree of ${branch}; remove it (or run: just kit tidy) and re-run."
+      return 2
+    fi
+    step "Creating worktree ${wt}"
+    mkdir -p "${main_root}/worktrees"
+    if git show-ref --verify --quiet "refs/heads/${branch}"
+    then
+      git worktree add --quiet "${wt}" "${branch}"
+    else
+      git worktree add --quiet "${wt}" -b "${branch}" "origin/${branch}"
+    fi
+  fi
+
+  if [[ "$(git config core.hooksPath 2>/dev/null)" != .kit/hooks ]]
+  then
+    warn "run: kit install (core.hooksPath is not .kit/hooks, so the desk guard is off in this clone)"
+  fi
+
+  # GitHub cannot open a pull request on a branch with nothing to compare, so the first commit is an empty one.
+  if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
+  then
+    step "Adding the start commit"
+    git -C "${wt}" commit --quiet --allow-empty --message "start: #${primary} ${title}"
+  fi
+  git -C "${wt}" push --quiet --set-upstream origin "${branch}"
+
+  if [[ -n "${stash_ref}" ]]
+  then
+    if git -C "${wt}" stash apply "${stash_ref}" >/dev/null 2>&1
+    then
+      local slot
+      slot=$(git -C "${invoking_root}" stash list --format='%gd %H' | awk -v h="${stash_ref}" '$2==h{print $1; exit}')
+      [[ -n "${slot}" ]] && git -C "${invoking_root}" stash drop "${slot}" >/dev/null
+      ok "Swept the work into ${wt}, uncommitted; commit it there with a real message."
+      if ! git -C "${invoking_root}" merge --ff-only "origin/${default_branch}" >/dev/null 2>&1
+      then
+        warn "${default_branch} could not fast-forward to origin; it is left as it was."
+      fi
+    else
+      error "the swept work conflicts in ${wt}. It is kept in the stash: git stash apply ${stash_ref}"
+      return 1
+    fi
+  fi
+
+  local pr
+  pr=$(gh pr list --head "${branch}" --state open --json number --jq '.[0].number // empty')
+  if [[ -z "${pr}" ]]
+  then
+    step "Opening a draft pull request"
+    gh pr create --draft --base "${default_branch}" --head "${branch}" --title "${title}" --body "" >/dev/null
+    pr=$(gh pr list --head "${branch}" --state open --json number --jq '.[0].number')
+  fi
+
+  if (( $# > 1 ))
+  then
+    local body changed=false
+    body=$(gh pr view "${pr}" --json body --jq '.body // ""')
+    for n in "${@:2}"
+    do
+      if ! grep --quiet --ignore-case --extended-regexp "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
+      then
+        body="${body}"$'\n'"Closes #${n}"
+        changed=true
+      fi
+    done
+    if [[ "${changed}" == true ]]
+    then
+      step "Linking the secondary issues in the pull request body"
+      gh pr edit "${pr}" --body "${body}" >/dev/null
+    fi
+  fi
+
+  ok "Draft pull request #${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
+  ok "Worktree ready: ${wt}"
+  step "cd '${wt}'    # do all work there; this checkout stays on ${default_branch}"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/bash/git.sh b/.kit/bash/git.sh
new file mode 100644
index 0000000..a8544b8
--- /dev/null
+++ b/.kit/bash/git.sh
@@ -0,0 +1,262 @@
+# shellcheck shell=bash
+# git.sh - the picture of the worktrees, and the sweep that returns a checkout to pristine (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# git:status [--no-fetch] renders the main checkout on one line and one block per worktree under worktrees/
+# with its branch, pull request, and dirty or clean state, then the local branches whose upstream is gone. It
+# changes nothing.
+#
+# git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, prunes
+# the worktree bookkeeping, and deletes every local branch whose upstream is gone. It never touches the default
+# branch, a branch checked out in a live worktree, a dirty worktree, or the worktree it runs in. --dry-run
+# prints what a sweep would do and changes nothing.
+
+# git:pr-summary <branch> prints "<number>\t<Draft|Ready>" for the open pull request on <branch>, or nothing.
+git:pr-summary() {
+  gh pr list --head "$1" --state open --json number,isDraft \
+    --jq '.[0] | select(.number) | "\(.number)\t\(if .isDraft then "Draft" else "Ready" end)"' 2>/dev/null || true
+}
+
+# git:gone-branches prints every local branch whose upstream no longer exists.
+git:gone-branches() {
+  git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/ | awk '$2=="[gone]"{print $1}'
+}
+
+# git:each-worktree <callback> calls <callback> <path> <branch> <detached> for every linked worktree under
+# worktrees/. <branch> is empty and <detached> is true for a detached checkout.
+git:each-worktree() {
+  local callback=$1 worktree_root path="" branch="" detached=false line
+  worktree_root="$(git:main-root)/worktrees"
+  while IFS= read -r line
+  do
+    case "${line}" in
+      (worktree\ *)
+        path=${line#worktree }
+        branch=""
+        detached=false
+        ;;
+      (branch\ refs/heads/*)
+        branch=${line#branch refs/heads/}
+        ;;
+      (detached)
+        detached=true
+        ;;
+      ("")
+        [[ -n "${path}" ]] || continue
+        case "${path}" in
+          ("${worktree_root}"/*)
+            "${callback}" "${path}" "${branch}" "${detached}"
+        esac
+        path=""
+    esac
+  done < <(git worktree list --porcelain; printf '\n')
+}
+
+# git:status-block <path> <branch> <detached> renders one worktree. git:status sets found, main_root, and
+# default_branch before calling it through git:each-worktree.
+git:status-block() {
+  local path=$1 branch=$2 rel pr ahead_behind porcelain
+  found=true
+  rel=${path#"${main_root}"/}
+  step "${rel}"
+  info "  branch  ${branch:-(detached)}"
+  if [[ -n "${branch}" ]]
+  then
+    pr=$(git:pr-summary "${branch}")
+    ahead_behind=$(git rev-list --left-right --count "${branch}...${default_branch}" 2>/dev/null || printf '0\t0')
+    if [[ -n "${pr}" ]]
+    then
+      info "  pr      #${pr%%$'\t'*} ${pr##*$'\t'} · ↑${ahead_behind%%$'\t'*} ↓${ahead_behind##*$'\t'} vs ${default_branch}"
+    else
+      info "  pr      (none open) · ↑${ahead_behind%%$'\t'*} ↓${ahead_behind##*$'\t'} vs ${default_branch}"
+    fi
+  else
+    info "  pr      (no branch)"
+  fi
+  porcelain=$(git -C "${path}" status --porcelain 2>/dev/null || true)
+  if [[ -z "${porcelain}" ]]
+  then
+    info "  status  clean"
+  else
+    info "  status  $(grep --count . <<<"${porcelain}") file(s) modified"
+  fi
+}
+
+# git:tidy-worktree <path> <branch> <detached> decides one worktree. git:tidy sets found, self_root, dry_run,
+# removed_worktrees, and freed before calling it through git:each-worktree.
+git:tidy-worktree() {
+  local path=$1 branch=$2 detached=$3 state="" number
+  found=true
+  if [[ "${path}" == "${self_root}" ]]
+  then
+    step "keeping ${path} (this command runs in it)"
+    return 0
+  fi
+  if [[ -n "${branch}" ]]
+  then
+    state=$(gh pr list --head "${branch}" --state all --json state --jq '.[0].state // empty' 2>/dev/null || true)
+    if [[ -z "${state}" && "${branch}" =~ ^([0-9]+)- ]]
+    then
+      number=${BASH_REMATCH[1]}
+      [[ "$(gh issue view "${number}" --json state --jq .state 2>/dev/null)" == CLOSED ]] && state=CLOSED
+    fi
+  elif [[ "${detached}" == true && -z "$(git -C "${path}" status --porcelain 2>/dev/null)" ]]
+  then
+    state=DETACHED
+  fi
+  case "${state}" in
+    (MERGED | CLOSED | DETACHED)
+      if [[ -n "$(git -C "${path}" status --porcelain 2>/dev/null)" ]]
+      then
+        step "keeping ${path} (${state}, but it has uncommitted changes)"
+        return 0
+      fi
+      if [[ "${dry_run}" == true ]]
+      then
+        step "would remove ${path} (${branch:-detached}, ${state})"
+      else
+        step "removing ${path} (${branch:-detached}, ${state})"
+        git worktree remove "${path}"
+      fi
+      [[ -n "${branch}" ]] && freed[${branch}]=1
+      (( ++removed_worktrees ))
+      ;;
+    (*)
+      step "keeping ${path} (${branch:-detached}, pull request ${state:-open or unknown})"
+  esac
+  return 0
+}
+
+git:status() {
+  local no_fetch=false arg
+  for arg in "$@"
+  do
+    case "${arg}" in
+      (--no-fetch)
+        no_fetch=true
+        ;;
+      (*)
+        error "unknown flag '${arg}' (only --no-fetch is recognized)"
+        return 2
+    esac
+  done
+  if [[ "${no_fetch}" != true ]]
+  then
+    git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
+  fi
+
+  local main_branch main_dirty counts
+  main_root=$(git:main-root)
+  default_branch=$(git:default-branch)
+  main_branch=$(git -C "${main_root}" rev-parse --abbrev-ref HEAD 2>/dev/null || printf '?')
+  main_dirty=clean
+  [[ -z "$(git -C "${main_root}" status --porcelain 2>/dev/null)" ]] || main_dirty=dirty
+  counts=$(git -C "${main_root}" rev-list --left-right --count "HEAD...origin/${default_branch}" 2>/dev/null || printf '0\t0')
+  section "${main_root##*/}  (${main_branch}, ${main_dirty}, ↑${counts%%$'\t'*} ↓${counts##*$'\t'} vs origin/${default_branch})"
+
+  section "worktrees/"
+  found=false
+  git:each-worktree git:status-block
+  [[ "${found}" == true ]] || ok "none"
+
+  section "branches whose upstream is gone (tidy removes these)"
+  local gone
+  gone=$(git:gone-branches)
+  if [[ -n "${gone}" ]]
+  then
+    while IFS= read -r branch
+    do
+      info "${branch}"
+    done <<<"${gone}"
+  else
+    ok "none"
+  fi
+}
+
+git:tidy() {
+  local dry_run=false flag
+  for flag in "$@"
+  do
+    case "${flag}" in
+      (--dry-run)
+        dry_run=true
+        ;;
+      (*)
+        error "unknown flag '${flag}' (only --dry-run is recognized)"
+        return 2
+    esac
+  done
+  guard:require gh || return 1
+
+  local repo
+  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || true)
+  if [[ -z "${repo}" ]]
+  then
+    error "this checkout does not resolve to a GitHub repository (run: gh repo view), so nothing is swept."
+    return 1
+  fi
+  if [[ "${dry_run}" == true ]]
+  then
+    section "kit tidy, dry run: nothing is changed"
+  else
+    section "kit tidy: sweeping ${repo} back to pristine"
+  fi
+
+  default_branch=$(git:default-branch)
+  self_root=$(git rev-parse --show-toplevel)
+  if [[ "${dry_run}" == true ]]
+  then
+    step "would run: git fetch --prune origin"
+  else
+    step "git fetch --prune origin"
+    git fetch --quiet --prune origin
+  fi
+
+  section "worktrees whose pull request is merged or closed"
+  removed_worktrees=0
+  found=false
+  declare -A freed=()
+  git:each-worktree git:tidy-worktree
+  [[ "${found}" == true ]] || ok "none"
+
+  section "worktree bookkeeping"
+  if [[ "${dry_run}" == true ]]
+  then
+    git worktree prune --verbose --dry-run || true
+  else
+    git worktree prune --verbose || true
+  fi
+  ok "pruned"
+
+  section "local branches whose upstream is gone"
+  local removed_branches=0 checked_out branch
+  checked_out=$(git worktree list --porcelain | sed -n 's@^branch refs/heads/@@p')
+  while IFS= read -r branch
+  do
+    [[ -n "${branch}" ]] || continue
+    [[ "${branch}" == "${default_branch}" ]] && continue
+    if [[ -z "${freed[${branch}]+x}" ]] && grep --quiet --line-regexp --fixed-strings "${branch}" <<<"${checked_out}"
+    then
+      step "keeping ${branch} (checked out in a worktree)"
+      continue
+    fi
+    if [[ "${dry_run}" == true ]]
+    then
+      step "would delete ${branch}"
+    else
+      step "deleting ${branch}"
+      git branch -D "${branch}" >/dev/null
+    fi
+    (( ++removed_branches ))
+  done <<<"$(git:gone-branches)"
+  (( removed_branches > 0 )) || ok "none"
+
+  if [[ "${dry_run}" == true ]]
+  then
+    ok "Dry run: would remove ${removed_worktrees} worktree(s) and ${removed_branches} branch(es)."
+  else
+    ok "Tidied ${repo}: removed ${removed_worktrees} worktree(s) and ${removed_branches} branch(es)."
+  fi
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/ci.yml b/.kit/ci.yml
new file mode 100644
index 0000000..dd0e5f0
--- /dev/null
+++ b/.kit/ci.yml
@@ -0,0 +1,141 @@
+# kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# One job, CI, which is the check name a ruleset requires. Three steps: the repository's `just ci` when its
+# root justfile has one, `kit check` against the release mise pins, and a refusal of a pull request that is
+# not linked to an open issue of this repository under Development. The last two run even when an earlier step
+# refused, so one run reports every finding.
+#
+# This file is placed by `kit install` and verified by `kit check`. Change it by pinning a new release.
+#
+# see: .kit/1st.md
+
+name: kit
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+jobs:
+  CI:
+    if: github.event.pull_request.base.ref == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      # Every tool below comes from mise.toml, the kit included.
+      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
+
+      - name: gate
+        run: |
+          set -o errexit -o nounset -o pipefail
+          if [[ ! -f justfile ]] || ! just --show ci >/dev/null 2>&1
+          then
+            echo "::warning::the root justfile has no ci recipe, so the gate was skipped"
+            printf '⚠️ The gate was skipped: the root justfile has no ci recipe.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+          else
+            just ci
+            printf '✅ just ci passed.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+          fi
+
+      - name: kit-check
+        if: ${{ !cancelled() }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+          if command -v kit >/dev/null 2>&1
+          then
+            kit check
+          elif [[ -x bin/kit ]]
+          then
+            bin/kit check
+          else
+            echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'
+            printf '### ❌ kit is not on PATH\n\nPin the release in mise.toml under [tools]: "github:empowerite/kit" = "<version>".\n' \
+              | tee --append "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          fi
+          printf '✅ Every delivered file matches the pinned kit release.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+
+      - name: linked-open-issue
+        if: ${{ !cancelled() }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+
+          repo_slug="${GITHUB_REPOSITORY}"
+          pr=$(jq --raw-output '.pull_request.number' "${GITHUB_EVENT_PATH}")
+          pull="${GITHUB_SERVER_URL}/${repo_slug}/pull/${pr}"
+          run="${GITHUB_SERVER_URL}/${repo_slug}/actions/runs/${GITHUB_RUN_ID}"
+
+          remedy=$(cat <<REMEDY
+          Link an open issue of this repository under **Development** in [the sidebar](${pull}):
+
+          1. click the gear (⚙) beside **Development**
+          2. pick one or more open issues
+          3. [re-run this check](${run}): linking fires no event, so it does not re-run on its own
+
+          \`just kit issue <N>\` makes this link when it starts the work.
+          REMEDY
+          )
+
+          refuse() {
+            echo "::error::$1"
+            printf '### ❌ %s\n\n%s\n' "${1^}" "${remedy}" | tee --append "${GITHUB_STEP_SUMMARY}"
+            return 1
+          }
+
+          query=$(cat <<'GRAPHQL'
+          query($owner: String!, $name: String!, $number: Int!) {
+            repository(owner: $owner, name: $name) {
+              pullRequest(number: $number) {
+                closingIssuesReferences(first: 100) {
+                  nodes { number state repository { nameWithOwner } }
+                }
+              }
+            }
+          }
+          GRAPHQL
+          )
+          refs=$(gh api graphql \
+            --field owner="${repo_slug%%/*}" \
+            --field name="${repo_slug#*/}" \
+            --field number="${pr}" \
+            --raw-field query="${query}" \
+            --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
+                  | "\(.number) \(.state) \(.repository.nameWithOwner)"')
+
+          if [[ -z "${refs}" ]]
+          then
+            refuse 'this pull request is not linked to any issue'
+          else
+            open_local=0
+            while read -r n state repo
+            do
+              if [[ "${repo}" != "${repo_slug}" ]]
+              then
+                echo "::warning::skipping ${repo}#${n}: it belongs to another repository"
+                continue
+              fi
+              if [[ "${state}" != OPEN ]]
+              then
+                echo "::warning::${repo}#${n} is ${state}; merging will not change it"
+                continue
+              fi
+              open_local=$(( open_local + 1 ))
+            done <<< "${refs}"
+            if (( open_local == 0 ))
+            then
+              refuse 'every issue this pull request is linked to is closed or belongs to another repository'
+            else
+              closes=$(cut --delimiter=' ' --fields=1 <<< "${refs}" | sed 's/^/#/' | paste --serial --delimiters=' ')
+              printf '✅ Linked to %s.\n' "${closes}" | tee --append "${GITHUB_STEP_SUMMARY}"
+            fi
+          fi
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/hooks/pre-commit b/.kit/hooks/pre-commit
new file mode 100755
index 0000000..f84188a
--- /dev/null
+++ b/.kit/hooks/pre-commit
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# pre-commit - lint the staged paths and refuse the commit on a finding (executed git hook, fails open)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Each linter runs over the staged paths of its own kind, when the linter is on PATH: shellcheck over bash,
+# actionlint over workflows, and markdownlint-cli2 over markdown when the repository carries a config for it.
+# A linter that is not on PATH is a reported skip, never a silent pass and never a refusal: lint is not the
+# enforcement of record, and a GUI client with a short PATH must still be able to commit.
+#
+# The working tree's copy of each path is linted, not the staged blob, so a partial add can be told about a line
+# the commit does not carry. The escape hatch is git's own: git commit --no-verify
+
+set -o nounset -o pipefail
+
+staged=()
+while IFS= read -r -d '' path
+do
+  [[ -f "${path}" ]] && staged+=("${path}")
+done < <(git diff --cached --name-only --diff-filter=ACMR -z 2>/dev/null)
+(( ${#staged[@]} )) || exit 0
+
+bash_paths=()
+workflow_paths=()
+markdown_paths=()
+for path in "${staged[@]}"
+do
+  case "${path}" in
+    (*.sh | *.bash | .kit/hooks/*)
+      bash_paths+=("${path}")
+      ;;
+    (.github/workflows/*.yml | .github/workflows/*.yaml)
+      workflow_paths+=("${path}")
+      ;;
+    (*.md)
+      markdown_paths+=("${path}")
+  esac
+done
+
+findings=0
+skip() {
+  printf '\xe2\x9a\xa0\xef\xb8\x8f  %s is not on PATH, so the staged %s were NOT linted.\n' "$1" "$2" >&2
+}
+
+if (( ${#bash_paths[@]} ))
+then
+  if command -v shellcheck >/dev/null 2>&1
+  then
+    shellcheck --shell=bash --external-sources "${bash_paths[@]}" || findings=1
+  else
+    skip shellcheck "bash files"
+  fi
+fi
+
+if (( ${#workflow_paths[@]} ))
+then
+  if command -v actionlint >/dev/null 2>&1
+  then
+    actionlint "${workflow_paths[@]}" || findings=1
+  else
+    skip actionlint workflows
+  fi
+fi
+
+if (( ${#markdown_paths[@]} )) && compgen -G ".markdownlint-cli2.*" >/dev/null
+then
+  if command -v markdownlint-cli2 >/dev/null 2>&1
+  then
+    markdownlint-cli2 "${markdown_paths[@]}" || findings=1
+  else
+    skip markdownlint-cli2 "markdown files"
+  fi
+fi
+
+if (( findings ))
+then
+  cat >&2 <<'MESSAGE'
+
+❌ refusing the commit: a linter found something in the staged paths. Each finding above names the file and line.
+   Fix it and commit again. If you mean it anyway, the escape hatch is git's own: git commit --no-verify
+MESSAGE
+  exit 1
+fi
+exit 0
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/hooks/pre-rebase b/.kit/hooks/pre-rebase
new file mode 100755
index 0000000..240bc3e
--- /dev/null
+++ b/.kit/hooks/pre-rebase
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# pre-rebase - refuse a rebase of the default branch (executed git hook, fails open)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# git runs this before every rebase, however it was spelled: git rebase, git pull --rebase, an editor's button.
+# It refuses one thing, a rebase whose branch is the default branch, because that branch is the human's desk and
+# a rebase rewrites it. A rebase in worktrees/<N>-<slug> is on an issue branch and passes.
+#
+# It fails open: a rung that cannot tell whether the branch is the default branch exits 0, since refusing every
+# worktree rebase in a clone that cannot answer would be worse than the gap. The one exception is below.
+#
+# git passes <upstream> as $1, and <branch> as $2 only for `git rebase <upstream> <branch>`; an empty $2 means
+# the branch checked out here.
+
+set -o nounset -o pipefail
+
+upstream=${1:-}
+branch=${2:-}
+[[ -n "${branch}" ]] || branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+[[ -n "${branch}" ]] || exit 0
+
+default_branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+[[ -n "${default_branch}" ]] || default_branch=main
+[[ "${branch}" == "${default_branch}" ]] || exit 0
+
+# A branch with no commit of its own has nothing a rebase would replay: it is a fast-forward, and passes. Once
+# the branch is known to be the default branch, an <upstream> that cannot be resolved is refused, not passed:
+# this is the one rung where "cannot tell" means no.
+if [[ -n "${upstream}" ]]
+then
+  unique=$(git rev-list --count "${upstream}..${branch}" 2>/dev/null) && (( unique == 0 )) && exit 0
+fi
+
+# The branch name goes through printf, never into the heredoc, since a ref may carry a backtick or a dollar.
+printf '\xe2\x9d\x8c refusing to rebase %s: it is the default branch, and the default branch is never rebased.\n' \
+  "'${branch}'" >&2
+cat >&2 <<'MESSAGE'
+
+   The default branch is the human's desk. It advances by fast-forward: git pull --ff-only
+   A worktree's branch is rebased in that worktree: git -C worktrees/<N>-<slug> rebase main
+
+   If you mean it, the escape hatch is git's own, on the rebase itself: git rebase --no-verify <upstream>
+MESSAGE
+exit 1
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/kit.just b/.kit/kit.just
new file mode 100644
index 0000000..ecb46dc
--- /dev/null
+++ b/.kit/kit.just
@@ -0,0 +1,67 @@
+# kit.just - see: https://just.systems/man/en/
+# ----------------------------------------------------------------------------------------------------------------------
+# The kit's just module. A consumer's root justfile takes it with `mod kit ".kit/kit.just"`, which gives
+# `just kit issue`, `just kit tidy`, and `just kit status`. Each recipe carries [no-cd] so its body runs
+# from the checkout it was invoked in, and the bash behind each lives in .kit/bash/, loaded through BASH_ENV.
+#
+# A root justfile that wants the bare spelling adds its own veneer:
+#
+#   issue *numbers:
+#     just kit issue "$@"
+
+set dotenv-load := true
+set fallback := true
+set positional-arguments := true
+
+export BASH_ENV := source_directory() / "bash/1st.sh"
+
+# Default recipe: list this justfile's recipes.
+_: help
+
+# List recipes in this justfile.
+[no-exit-message]
+@help *options:
+  just --justfile "{{source_file()}}" --list
+
+set export := true
+
+# Start, or return to, work on an issue: a branch linked to it under Development, a worktree at
+# worktrees/<N>-<slug>, a start commit, and a draft pull request. Further numbers are secondary issues the
+# pull request closes. Safe to re-run; it never switches the checkout it runs from.
+#
+#   just kit issue 42        # start #42
+#   just kit issue 42 43     # start #42, and close #43 with it
+#   just kit issue           # ask for a title, create the issue, and start it (needs a terminal)
+[doc("🌿 Start or resume an issue: linked branch, worktree, start commit, draft pull request")]
+[no-cd]
+issue *numbers:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  gh:issue "$@"
+
+# Sweep the checkout back to pristine: remove worktrees whose pull request is merged or closed, prune the
+# bookkeeping, and delete local branches whose upstream is gone. The default branch, a dirty worktree, and the
+# worktree this runs in are never touched.
+#
+#   just kit tidy            # sweep
+#   just kit tidy --dry-run  # say what a sweep would do
+[doc("🧹 Remove merged worktrees and gone branches")]
+[no-cd]
+tidy *flags:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  git:tidy "$@"
+
+# Show the main checkout and every worktree under worktrees/: branch, pull request, and dirty or clean. Reads
+# only.
+#
+#   just kit status            # fetch --prune, then render
+#   just kit status --no-fetch # render from the current remote-tracking refs
+[doc("📊 Show every worktree with its branch, pull request, and state")]
+[no-cd]
+status *flags:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  git:status "$@"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
new file mode 100644
index 0000000..786ba9c
--- /dev/null
+++ b/.kit/rules/bash.md
@@ -0,0 +1,43 @@
+# Bash
+
+Applies to `*.sh`, `*.bash`, `.kit/hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+workflows.
+
+## Shape
+
+1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner, a rule of dashes to
+   column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
+   would change the caller's.
+3. A git hook that must fail open sets `-o nounset -o pipefail` and no `errexit`, and says so in its banner.
+4. The file closes with the same rule of dashes.
+
+## Style
+
+1. `then`, `do`, and `else` go on their own line, never after a semicolon.
+2. Spell `set` options out: `set -o errexit`, never `set -e`.
+3. Spell command options out: `--raw-output`, `--field`, `--delimiter`, never a one-letter flag in a script.
+   Where BSD and GNU differ, use the form both accept: `sed -n`, `head -n 1`, `mkdir -p`.
+4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
+5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
+6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
+7. Quote every expansion outside `[[ ]]` and `(( ))`.
+8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename.
+9. A function private to one executed script is bare kebab-case.
+
+## Behavior
+
+1. An error message is one line, names the remedy first, and is the same wherever the same condition arises.
+2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
+3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
+4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
+5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
+   to do, and a `--dry-run` where the mutation is a sweep.
+6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
+7. shellcheck passes with no directive, or the directive carries the reason on the same line.
+
+## Comments
+
+1. A comment states what the code does and the non-obvious why. It carries no history and defends no obvious
+   choice.
+2. A pointer is `# see: <ref>`, on its own line after the comment it supports.
diff --git a/.kit/rules/gitignore.md b/.kit/rules/gitignore.md
new file mode 100644
index 0000000..bc034de
--- /dev/null
+++ b/.kit/rules/gitignore.md
@@ -0,0 +1,24 @@
+# Ignore lists
+
+Applies to `.gitignore` at any depth.
+
+## Shape
+
+1. The file opens with `# .gitignore - untracked files and folders`, a rule of dashes to column 120, and a
+   blank line.
+2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
+   line.
+3. The file closes with a rule of dashes.
+
+## Entries
+
+1. Every entry names a file the repository itself produces. Editor and operating-system files belong in the
+   user's global ignore list, not here.
+2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
+   repository.
+3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
+4. `worktrees/` is ignored at the root: it is where the loop checks out a branch per issue.
+
+## Adding one
+
+Ask what produces the file. If nothing in the repository does, do not add it.
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
new file mode 100644
index 0000000..b11ca35
--- /dev/null
+++ b/.kit/rules/json.md
@@ -0,0 +1,21 @@
+# JSON
+
+Applies to `*.json` and `*.jsonc`.
+
+## Shape
+
+1. Two-space indentation. Keys in a stable order: the order the consuming tool documents, else alphabetical.
+2. One trailing newline. No trailing commas in `.json`.
+3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where
+   it reads plain JSON, the reason for a setting lives in the document that describes the file.
+
+## Settings
+
+1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
+2. A tool's settings file that the kit writes into is merged by key. The kit owns only the keys and entries
+   it writes, and anything else in the file is the repository's.
+
+## Comments
+
+1. A comment states what the entry does and the non-obvious why. It carries no history.
+2. A pointer is `// see: <ref>`.
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
new file mode 100644
index 0000000..fe8b9a1
--- /dev/null
+++ b/.kit/rules/just.md
@@ -0,0 +1,44 @@
+# Just
+
+Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
+applies to it as well.
+
+## Shape
+
+1. A module file opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120, and
+   a description of what the file is and who imports it.
+2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
+   root, which has no parent), `set positional-arguments := true`, and `set export := true`.
+3. Every justfile carries the default-and-help pair:
+
+   ```just
+   # Default recipe: list this justfile's recipes.
+   _: help
+
+   # List recipes in this justfile.
+   [no-exit-message]
+   @help *options:
+     just --justfile "{{source_file()}}" --list
+   ```
+
+4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
+   the invoking root rather than the module's directory.
+5. The file closes with a rule of dashes.
+
+## Recipes
+
+1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
+2. A comment block precedes every recipe: usage lines, then a paragraph of intent. It answers what the recipe
+   does, when to run it, and what it produces.
+3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
+4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
+5. Recipe bodies use `${var}`, never `{{var}}` mixed in. `set export := true` makes parameters available.
+6. Two-space indentation inside a body. Never a tab.
+7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
+8. Comments wrap at 118 columns. Bodies do not wrap.
+
+## Invocation
+
+1. The idiom is the space form, `just kit issue 42`, never `just kit/issue` and never `kit::issue` outside a
+   dependency list.
+2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
new file mode 100644
index 0000000..8f8da0e
--- /dev/null
+++ b/.kit/rules/markdown.md
@@ -0,0 +1,39 @@
+# Markdown
+
+Applies to `*.md`.
+
+## Prose
+
+1. Write plain declarative sentences with the thing under discussion as the subject.
+2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
+3. Use a list where the content is a list. Use a table where the content has columns.
+4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
+5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
+6. Use the serial comma in every list of three or more.
+7. Expand an uncommon acronym the first time it appears.
+8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
+   when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
+
+## Layout
+
+1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
+   per nesting level, to a limit of 12.
+2. Balance the wrap: no line, in particular the last, reads as a stub.
+3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
+4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
+5. Headings are ATX (`#`). One `#` heading per file, at the top.
+6. Fenced code blocks declare a language and have a blank line on each side.
+7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
+
+## Links
+
+1. Use inline links with descriptive text, never a bare URL in angle brackets.
+2. Use the same anchor text every time the same URL appears in a file.
+3. When a label and the link text would say the same thing, make the label the link.
+4. A relative link resolves from the file that carries it, and it resolves: a check reads them.
+
+## Files
+
+1. Name an index file `1st.md`. It lists its siblings and says what each is for.
+2. A file says what its subject is in its first paragraph, before how to use it.
+3. No file names another repository as the source of a rule.
diff --git a/.kit/rules/yaml.md b/.kit/rules/yaml.md
new file mode 100644
index 0000000..b39eca6
--- /dev/null
+++ b/.kit/rules/yaml.md
@@ -0,0 +1,29 @@
+# YAML
+
+Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
+
+## Shape
+
+1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
+   reader would not guess from the keys.
+2. Two-space indentation. No tabs. No trailing whitespace.
+3. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
+4. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
+   breaks the requirement.
+5. `permissions` is declared at the top and names the least the jobs need.
+
+## Steps
+
+1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. A step has a `name` that is the policy it enforces, in kebab-case.
+3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
+4. A refusal prints `::error::<message>`, writes `### ❌ <Message>` and a remedy to `${GITHUB_STEP_SUMMARY}`,
+   and returns non-zero. The remedy is the action to take, with a link that is that action.
+5. A pass writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
+7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
+
+## Comments
+
+1. A comment states the non-obvious why. It carries no history.
+2. A pointer is `# see: <ref>`.
diff --git a/.kit/settings.json b/.kit/settings.json
new file mode 100644
index 0000000..7911d58
--- /dev/null
+++ b/.kit/settings.json
@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(git checkout main *)",
+      "Bash(git switch main *)",
+      "Bash(git reset --hard *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git worktree remove --force *)"
+    ]
+  }
+}
diff --git a/.kit/version b/.kit/version
new file mode 100644
index 0000000..6e8bf73
--- /dev/null
+++ b/.kit/version
@@ -0,0 +1 @@
+0.1.0

From ed72ef71c289bda4960eb51c7b6bb0cfb853a737 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:02:27 -0700
Subject: [PATCH 003/108] #1 bin/kit: install, update, and check

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/kit | 302 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 302 insertions(+)
 create mode 100755 bin/kit

diff --git a/bin/kit b/bin/kit
new file mode 100755
index 0000000..4b6c59f
--- /dev/null
+++ b/bin/kit
@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+# kit - install, update, and check the kit in a repository (executed entrypoint)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+#   kit install    copy this release into the repository and write .kit/manifest
+#   kit update     after the pin is bumped: replace unchanged files, three-way merge changed ones
+#   kit check      fail when a delivered file differs from this release
+#   kit version    print this release's version
+#
+# KIT_BASE=<dir> names the previous release's root for \`kit update\` on a machine without mise.
+#
+# The release this command belongs to is the directory above bin/: its .kit/ is the payload. The repository is
+# the git checkout the command runs in. A delivered file is one of: every file under .kit/, except manifest;
+# .claude/rules/kit-<kind>.md, each the rule file of that kind with a paths: header so a harness loads it by
+# path; and .github/workflows/kit-ci.yml, which is .kit/ci.yml placed where GitHub reads it. .claude/settings.json
+# is shared with the repository, so it is merged by key: the kit owns only the deny entries it writes.
+#
+# see: .kit/1st.md
+
+set -o errexit -o nounset -o pipefail
+
+kit_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+payload="${kit_root}/.kit"
+# shellcheck source=.kit/bash/1st.sh
+source "${payload}/bash/1st.sh"
+
+usage() {
+  sed -n '5,8p' "${BASH_SOURCE[0]}" | sed 's/^# *//' >&2
+}
+
+# digest prints the sha256 of stdin, by whichever tool the machine carries.
+digest() {
+  if command -v sha256sum >/dev/null 2>&1
+  then
+    sha256sum | cut -d ' ' -f 1
+  else
+    shasum -a 256 | cut -d ' ' -f 1
+  fi
+}
+
+# rule-paths <kind> prints the paths: globs a harness loads the rule of <kind> for, one per line.
+rule-paths() {
+  case "$1" in
+    (markdown)  printf '%s\n' '**/*.md' ;;
+    (bash)      printf '%s\n' '**/*.sh' '**/*.bash' '.kit/hooks/*' ;;
+    (just)      printf '%s\n' 'justfile' '**/justfile' '**/*.just' ;;
+    (yaml)      printf '%s\n' '**/*.yml' '**/*.yaml' ;;
+    (json)      printf '%s\n' '**/*.json' '**/*.jsonc' ;;
+    (gitignore) printf '%s\n' '.gitignore' '**/.gitignore' ;;
+    (*)         printf '%s\n' "**/*.$1"
+  esac
+}
+
+# delivered-paths <payload> prints every repository path the release at <payload> delivers.
+delivered-paths() {
+  local root=$1 file
+  while IFS= read -r file
+  do
+    [[ "${file}" == manifest ]] && continue
+    printf '.kit/%s\n' "${file}"
+  done < <(cd "${root}" && find . -type f | sed 's@^\./@@' | sort)
+  for file in "${root}"/rules/*.md
+  do
+    printf '.claude/rules/kit-%s\n' "$(basename "${file}")"
+  done
+  printf '.github/workflows/kit-ci.yml\n'
+}
+
+# expected <payload> <path> prints the content the release at <payload> delivers at repository <path>.
+expected() {
+  local root=$1 path=$2 kind glob
+  case "${path}" in
+    (.kit/*)
+      cat "${root}/${path#.kit/}"
+      ;;
+    (.claude/rules/kit-*.md)
+      kind=${path#.claude/rules/kit-}
+      kind=${kind%.md}
+      printf -- '---\npaths:\n'
+      while IFS= read -r glob
+      do
+        printf '  - "%s"\n' "${glob}"
+      done < <(rule-paths "${kind}")
+      printf -- '---\n'
+      cat "${root}/rules/${kind}.md"
+      ;;
+    (.github/workflows/kit-ci.yml)
+      cat "${root}/ci.yml"
+      ;;
+    (*)
+      error "kit: '${path}' is not a delivered path"
+      return 2
+  esac
+}
+
+# write-expected <payload> <path> writes the delivered content at <path>, making its directory.
+write-expected() {
+  mkdir -p "$(dirname "$2")"
+  expected "$1" "$2" > "$2.kit-new"
+  mv "$2.kit-new" "$2"
+  [[ "$2" == .kit/hooks/* ]] && chmod +x "$2"
+  return 0
+}
+
+# merge-settings <new-payload> [<base-payload>] merges the deny entries into .claude/settings.json: the base
+# release's entries go, the new release's come, and everything else in the file stays as it was.
+merge-settings() {
+  local new_root=$1 base_root=${2:-} base_deny='[]'
+  [[ -n "${base_root}" && -f "${base_root}/settings.json" ]] && base_deny=$(jq '.permissions.deny // []' "${base_root}/settings.json")
+  mkdir -p .claude
+  [[ -f .claude/settings.json ]] || printf '{}\n' > .claude/settings.json
+  jq --indent 2 \
+    --argjson base "${base_deny}" \
+    --argjson new "$(jq '.permissions.deny // []' "${new_root}/settings.json")" \
+    '.permissions.deny = (((.permissions.deny // []) - $base) as $kept | $kept + ($new - $kept))' \
+    .claude/settings.json > .claude/settings.json.kit-new
+  mv .claude/settings.json.kit-new .claude/settings.json
+}
+
+# ensure-ignored makes sure worktrees/ is ignored at the root, the way the loop needs.
+ensure-ignored() {
+  local separator=""
+  if [[ -f .gitignore ]] && grep --quiet --line-regexp --extended-regexp '/?worktrees/' .gitignore
+  then
+    return 0
+  fi
+  [[ -f .gitignore && -s .gitignore ]] && separator=$'\n'
+  printf '%s# the per-issue worktrees of the loop; see: .kit/1st.md\n/worktrees/\n' "${separator}" >> .gitignore
+}
+
+# write-manifest records the release version and, per delivered path, the digest of the release's own content
+# for it, never of the file as written: a later update tells an untouched file from an edited one by comparing
+# the file to this, so a merge that kept a repository's edit is not mistaken for the release's text.
+write-manifest() {
+  local path
+  {
+    printf 'version %s\n' "$(cat "${payload}/version")"
+    while IFS= read -r path
+    do
+      printf '%s  %s\n' "$(expected "${payload}" "${path}" | digest)" "${path}"
+    done < <(delivered-paths "${payload}")
+  } > .kit/manifest
+}
+
+# finish sets the clone's hooks path and reports.
+finish() {
+  git config core.hooksPath .kit/hooks
+  ok "kit $(cat "${payload}/version") is installed: core.hooksPath is .kit/hooks, and .kit/manifest is written."
+  step "Commit the delivered files. The loop is in .kit/1st.md."
+}
+
+cmd-install() {
+  guard:require tool:jq tool:git
+  if [[ -f .kit/manifest ]]
+  then
+    error "run: kit update (this repository already carries kit $(sed -n 's/^version //p' .kit/manifest))"
+    return 1
+  fi
+  section "kit install $(cat "${payload}/version")"
+  local path
+  while IFS= read -r path
+  do
+    step "${path}"
+    write-expected "${payload}" "${path}"
+  done < <(delivered-paths "${payload}")
+  merge-settings "${payload}"
+  ensure-ignored
+  write-manifest
+  finish
+}
+
+cmd-update() {
+  guard:require tool:jq tool:git
+  if [[ ! -f .kit/manifest ]]
+  then
+    error "run: kit install (this repository carries no .kit/manifest)"
+    return 1
+  fi
+  local previous current base_root="" path recorded actual conflicts=0
+  previous=$(sed -n 's/^version //p' .kit/manifest)
+  current=$(cat "${payload}/version")
+  section "kit update ${previous} → ${current}"
+
+  # The previous release is the base of every three-way merge. KIT_BASE names its root directly; otherwise
+  # mise keeps it where it installed it.
+  if [[ -n "${KIT_BASE:-}" ]]
+  then
+    base_root=${KIT_BASE}
+  elif [[ "${previous}" != "${current}" ]] && command -v mise >/dev/null 2>&1
+  then
+    base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
+    if [[ -z "${base_root}" ]] && mise install --quiet "github:empowerite/kit@${previous}" 2>/dev/null
+    then
+      base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
+    fi
+  fi
+  [[ -n "${base_root}" ]] && base_root="${base_root}/.kit"
+
+  while IFS= read -r path
+  do
+    if [[ ! -f "${path}" ]]
+    then
+      step "${path}: missing, written"
+      write-expected "${payload}" "${path}"
+      continue
+    fi
+    recorded=$(awk -v p="${path}" '$2==p{print $1}' .kit/manifest)
+    actual=$(digest < "${path}")
+    if [[ -z "${recorded}" || "${recorded}" == "${actual}" ]]
+    then
+      step "${path}: unchanged since ${previous}, replaced"
+      write-expected "${payload}" "${path}"
+      continue
+    fi
+    if [[ -z "${base_root}" || ! -d "${base_root}" ]]
+    then
+      error "${path} was edited and the base release ${previous} is not installed; run: mise install github:empowerite/kit@${previous}"
+      conflicts=$(( conflicts + 1 ))
+      continue
+    fi
+    step "${path}: edited since ${previous}, three-way merged"
+    expected "${base_root}" "${path}" > "${path}.kit-base"
+    expected "${payload}" "${path}" > "${path}.kit-new"
+    if ! git merge-file --marker-size 7 "${path}" "${path}.kit-base" "${path}.kit-new"
+    then
+      warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
+      conflicts=$(( conflicts + 1 ))
+    fi
+    rm -f "${path}.kit-base" "${path}.kit-new"
+  done < <(delivered-paths "${payload}")
+
+  merge-settings "${payload}" "${base_root}"
+  ensure-ignored
+  write-manifest
+  if (( conflicts > 0 ))
+  then
+    error "${conflicts} file(s) need a hand; see above."
+    return 1
+  fi
+  finish
+}
+
+cmd-check() {
+  local path findings=0 version
+  if [[ ! -f .kit/manifest ]]
+  then
+    error "run: kit install (this repository carries no .kit/manifest)"
+    return 1
+  fi
+  version=$(sed -n 's/^version //p' .kit/manifest)
+  if [[ "${version}" != "$(cat "${payload}/version")" ]]
+  then
+    error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${payload}/version"); run: kit update"
+    findings=$(( findings + 1 ))
+  fi
+  while IFS= read -r path
+  do
+    if [[ ! -f "${path}" ]]
+    then
+      error "${path} is missing"
+      findings=$(( findings + 1 ))
+    elif ! expected "${payload}" "${path}" | cmp --silent - "${path}"
+    then
+      error "${path} differs from the pinned release"
+      findings=$(( findings + 1 ))
+    fi
+  done < <(delivered-paths "${payload}")
+  if [[ ! -f .claude/settings.json ]]
+  then
+    error ".claude/settings.json is missing; run: kit update"
+    findings=$(( findings + 1 ))
+  elif ! command -v jq >/dev/null 2>&1
+  then
+    error "run: mise install (jq is not on PATH, so .claude/settings.json could not be read)"
+    findings=$(( findings + 1 ))
+  elif (( $(jq --argjson new "$(jq '.permissions.deny // []' "${payload}/settings.json")" \
+      '($new - (.permissions.deny // [])) | length' .claude/settings.json) > 0 ))
+  then
+    error ".claude/settings.json is missing a deny entry the kit writes; run: kit update"
+    findings=$(( findings + 1 ))
+  fi
+  if (( findings > 0 ))
+  then
+    error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
+    return 1
+  fi
+  ok "kit ${version}: every delivered file matches the pinned release."
+}
+
+case "${1:-}" in
+  (install) cmd-install ;;
+  (update)  cmd-update ;;
+  (check)   cmd-check ;;
+  (version) cat "${payload}/version" ;;
+  (-h | --help | help | "") usage; [[ -n "${1:-}" ]] ;;
+  (*)
+    error "kit: unknown command '$1'"
+    usage
+    exit 2
+esac
+
+# ----------------------------------------------------------------------------------------------------------------------

From fe4d123fa81f569bf62ef6490c86ba0965d86561 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:02:27 -0700
Subject: [PATCH 004/108] #1 .github/workflows/release.yml: a tag on main
 becomes a release

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 69 +++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 .github/workflows/release.yml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..fbf936c
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,69 @@
+# release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/ and .kit/, the layout
+# a consumer's mise unpacks and puts on PATH. Two refusals: a tag whose commit is not on main, and a tag whose
+# version is not the one .kit/version records, so the release's version and the kit's own agree.
+#
+# see: .kit/1st.md
+
+name: release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: tag-is-on-main
+        run: |
+          set -o errexit -o nounset -o pipefail
+          default_branch=$(jq --raw-output '.repository.default_branch' "${GITHUB_EVENT_PATH}")
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/${default_branch}"
+          then
+            echo "::error::${GITHUB_REF_NAME} is not on ${default_branch}; delete the tag and tag a commit on ${default_branch}"
+            exit 1
+          fi
+          echo "✅ ${GITHUB_REF_NAME} is on ${default_branch}."
+
+      - name: tag-matches-version
+        run: |
+          set -o errexit -o nounset -o pipefail
+          tag_version=${GITHUB_REF_NAME#v}
+          file_version=$(cat .kit/version)
+          if [[ "${tag_version}" != "${file_version}" ]]
+          then
+            echo "::error::the tag says ${tag_version} and .kit/version says ${file_version}; set .kit/version on main first, then tag"
+            exit 1
+          fi
+          echo "✅ .kit/version is ${file_version}."
+
+      - name: pack-and-release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+          version=${GITHUB_REF_NAME#v}
+          staging=$(mktemp --directory)
+          mkdir "${staging}/kit-${version}"
+          cp --recursive bin .kit "${staging}/kit-${version}/"
+          rm --force "${staging}/kit-${version}/.kit/manifest"
+          tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
+          sha256sum "kit-${version}.tar.gz" > "kit-${version}.tar.gz.sha256"
+          notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\nThen, in the repository: kit install\n' "${version}")
+          flags=()
+          [[ "${version}" == *-* ]] && flags+=(--prerelease)
+          gh release create "${GITHUB_REF_NAME}" "kit-${version}.tar.gz" "kit-${version}.tar.gz.sha256" \
+            --title "kit ${version}" --notes "${notes}" "${flags[@]}"
+          echo "✅ Released kit ${version}."
+
+# ----------------------------------------------------------------------------------------------------------------------

From 9a430d2b38a9f272781eee5dc4814b22f446f021 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:02:27 -0700
Subject: [PATCH 005/108] #1 justfile, mise.toml, tests: the gate

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 justfile           |  50 ++++++++++
 mise.lock          | 230 +++++++++++++++++++++++++++++++++++++++++++++
 mise.toml          |  16 ++++
 tests/hooks.bats   |  67 +++++++++++++
 tests/kit.bats     | 137 +++++++++++++++++++++++++++
 tests/release.bats |  35 +++++++
 6 files changed, 535 insertions(+)
 create mode 100644 justfile
 create mode 100644 mise.lock
 create mode 100644 mise.toml
 create mode 100644 tests/hooks.bats
 create mode 100644 tests/kit.bats
 create mode 100644 tests/release.bats

diff --git a/justfile b/justfile
new file mode 100644
index 0000000..7b6b2d1
--- /dev/null
+++ b/justfile
@@ -0,0 +1,50 @@
+#!/usr/bin/env just --justfile
+# justfile - see: https://just.systems/man/en/
+# ----------------------------------------------------------------------------------------------------------------------
+# The root justfile: the kit's own module, taken the way a consumer takes it, and the gate.
+
+set dotenv-load := true
+set positional-arguments := true
+
+# Default recipe: list this justfile's recipes.
+_: help
+
+# List recipes in this justfile.
+[no-exit-message]
+@help *options:
+  just --justfile "{{source_file()}}" --list
+
+set export := true
+
+[doc("📁 The kit's recipes: issue, tidy, status (invoke as `just kit <recipe>`)")]
+mod kit ".kit/kit.just"
+
+# The gate a pull request passes: shellcheck over every bash file, actionlint over every workflow, the bats
+# suite over bin/kit, and bin/kit check over this repository's installed copy of its own kit. Every tool comes
+# from mise.toml.
+#
+#   just ci
+[doc("🚦 Run the gate: shellcheck, actionlint, bats, kit check")]
+ci:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  mise exec -- shellcheck --shell=bash --external-sources bin/kit .kit/bash/*.sh .kit/hooks/*
+  mise exec -- actionlint
+  mise exec -- bats --print-output-on-failure tests/
+  bin/kit check
+  echo "✅ ci passed"
+
+# Reinstall this repository's own kit from its source. Here the source under .kit/ is the payload, so an edit to
+# a delivered file is an edit to the release, not a consumer's drift: the installed copies, .claude/settings.json
+# (which carries only the kit's entries here), and .kit/manifest are rewritten from it. Run after changing any
+# delivered file, and commit the result with the change.
+#
+#   just refresh
+[doc("🔁 Reinstall this repository's own kit from .kit/ and bin/kit")]
+refresh:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  rm -f .kit/manifest .claude/settings.json
+  bin/kit install
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/mise.lock b/mise.lock
new file mode 100644
index 0000000..9537f2b
--- /dev/null
+++ b/mise.lock
@@ -0,0 +1,230 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+
+lockfile_version = 3
+
+[[tools.actionlint]]
+version = "1.7.12"
+backend = "aqua:rhysd/actionlint"
+specifiers = ["1.7"]
+
+[tools.actionlint."platforms.linux-arm64"]
+checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-arm64-musl"]
+checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-x64"]
+checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-x64-musl"]
+checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-arm64"]
+checksum = "sha256:aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924893"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-x64"]
+checksum = "sha256:5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924880"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.windows-x64"]
+checksum = "sha256:6e7241b51e6817ea6a047693d8e6fed13b31819c9a0dd6c5a726e1592d22f6e9"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_windows_amd64.zip"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924919"
+provenance = "github-attestations"
+
+[[tools.gh]]
+version = "2.103.0"
+backend = "aqua:cli/cli"
+specifiers = ["2.103"]
+
+[tools.gh."platforms.linux-arm64"]
+checksum = "sha256:7f322df34e624d14f5ec0c4acb121fd6dfa14392fdbbd1066aa8e0a05ac3721e"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956401"
+provenance = "github-attestations"
+
+[tools.gh."platforms.linux-arm64-musl"]
+checksum = "sha256:7f322df34e624d14f5ec0c4acb121fd6dfa14392fdbbd1066aa8e0a05ac3721e"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956401"
+provenance = "github-attestations"
+
+[tools.gh."platforms.linux-x64"]
+checksum = "sha256:fdd768eb70f6409f80fcfa9f3a1c0adf0fc98d827ab3ce0bed2ac22762c5d786"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956379"
+provenance = "github-attestations"
+
+[tools.gh."platforms.linux-x64-musl"]
+checksum = "sha256:fdd768eb70f6409f80fcfa9f3a1c0adf0fc98d827ab3ce0bed2ac22762c5d786"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956379"
+provenance = "github-attestations"
+
+[tools.gh."platforms.macos-arm64"]
+checksum = "sha256:54be566e9f614bea5de8021e95b9ad33dfee3b9d2ea120c9c294c00defaa5014"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_macOS_arm64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956481"
+provenance = "github-attestations"
+
+[tools.gh."platforms.macos-x64"]
+checksum = "sha256:64d1734941f104f996271c820daa50e96902c2618f9b4c1e63c41519517a9c6b"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_macOS_amd64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956458"
+provenance = "github-attestations"
+
+[tools.gh."platforms.windows-x64"]
+checksum = "sha256:80c846a5b8432672ca6373b34ce9de998c9686aaa1885c845f2e1ee81f713726"
+url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_windows_amd64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956535"
+provenance = "github-attestations"
+
+[[tools.jq]]
+version = "1.8.2"
+backend = "aqua:jqlang/jq"
+specifiers = ["1.8"]
+
+[tools.jq."platforms.linux-arm64"]
+checksum = "sha256:8b85c817833814ddca00a144c33705546355afccf0cf39b188f3cdb48b852309"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-arm64"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012756"
+provenance = "github-attestations"
+
+[tools.jq."platforms.linux-arm64-musl"]
+checksum = "sha256:8b85c817833814ddca00a144c33705546355afccf0cf39b188f3cdb48b852309"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-arm64"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012756"
+provenance = "github-attestations"
+
+[tools.jq."platforms.linux-x64"]
+checksum = "sha256:b1c22172dd303f3be49e935aa56aa48a8b7a46e0bc838b4997d3bb451495870f"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-amd64"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012752"
+provenance = "github-attestations"
+
+[tools.jq."platforms.linux-x64-musl"]
+checksum = "sha256:b1c22172dd303f3be49e935aa56aa48a8b7a46e0bc838b4997d3bb451495870f"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-amd64"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012752"
+provenance = "github-attestations"
+
+[tools.jq."platforms.macos-arm64"]
+checksum = "sha256:2d75340ba57a4b4b4c8708a21c2dc8e958a48aaa8bba13b27f77f6e4c0eca07e"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-macos-arm64"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012783"
+provenance = "github-attestations"
+
+[tools.jq."platforms.macos-x64"]
+checksum = "sha256:e94b266e3c26690550006abe63152b782280f4e14374accdf04cbde844f00bc0"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-macos-amd64"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012782"
+provenance = "github-attestations"
+
+[tools.jq."platforms.windows-x64"]
+checksum = "sha256:a6fc67fedaf9128a3309a1e2ebb8b986aeccf70122ee46d2cb4849e423f0c627"
+url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-windows-amd64.exe"
+url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012788"
+provenance = "github-attestations"
+
+[[tools.just]]
+version = "1.59.0"
+backend = "aqua:casey/just"
+specifiers = ["1.59"]
+
+[tools.just."platforms.linux-arm64"]
+checksum = "sha256:23871b1702bfd550fb5f901778fd4290ecf2ee034a45a889fbe96d89b188086d"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-aarch64-unknown-linux-musl.tar.gz"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/642950086"
+
+[tools.just."platforms.linux-arm64-musl"]
+checksum = "sha256:23871b1702bfd550fb5f901778fd4290ecf2ee034a45a889fbe96d89b188086d"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-aarch64-unknown-linux-musl.tar.gz"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/642950086"
+
+[tools.just."platforms.linux-x64"]
+checksum = "sha256:409044617b6f06517c1035e55ca38c8c856ff8b650e41bc2aa1ef82d5903a23e"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-unknown-linux-musl.tar.gz"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/642949555"
+
+[tools.just."platforms.linux-x64-musl"]
+checksum = "sha256:409044617b6f06517c1035e55ca38c8c856ff8b650e41bc2aa1ef82d5903a23e"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-unknown-linux-musl.tar.gz"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/642949555"
+
+[tools.just."platforms.macos-arm64"]
+checksum = "sha256:6574cea774ed4cae12e24b6aa11857de33e80dab4667cf628fd5840df96a2a9d"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-aarch64-apple-darwin.tar.gz"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/643129724"
+
+[tools.just."platforms.macos-x64"]
+checksum = "sha256:036ead9df9bc31dbae9934ae3b4236ed124d0bafcffd33439460ae084d5c9cb7"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-apple-darwin.tar.gz"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/643131819"
+
+[tools.just."platforms.windows-x64"]
+checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea9c0"
+url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
+url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
+
+[[tools."npm:bats"]]
+version = "1.13.0"
+aube = { path = ".mise/locks/npm-bats/1.13.0", digest = "sha256:b3795a7982457f07d0e04a547944558c3571830dd86994d282099c4c27082169" }
+backend = "npm:bats"
+specifiers = ["1.13"]
+
+[[tools.shellcheck]]
+version = "0.11.0"
+backend = "aqua:koalaman/shellcheck"
+specifiers = ["0.11"]
+
+[tools.shellcheck."platforms.linux-arm64"]
+checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056934"
+
+[tools.shellcheck."platforms.linux-arm64-musl"]
+checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056934"
+
+[tools.shellcheck."platforms.linux-x64"]
+checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056942"
+
+[tools.shellcheck."platforms.linux-x64-musl"]
+checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056942"
+
+[tools.shellcheck."platforms.macos-arm64"]
+checksum = "sha256:56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.aarch64.tar.xz"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056932"
+
+[tools.shellcheck."platforms.macos-x64"]
+checksum = "sha256:3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.x86_64.tar.xz"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056930"
+
+[tools.shellcheck."platforms.windows-x64"]
+checksum = "sha256:8a4e35ab0b331c85d73567b12f2a444df187f483e5079ceffa6bda1faa2e740e"
+url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.zip"
+url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056944"
diff --git a/mise.toml b/mise.toml
new file mode 100644
index 0000000..3b0f587
--- /dev/null
+++ b/mise.toml
@@ -0,0 +1,16 @@
+# mise.toml - the pinned toolchain; see: https://mise.jdx.dev/configuration.html
+#
+# Every tool this repository runs, at one version, installed the same way on a desk (`mise install`) and on a
+# runner (`jdx/mise-action`). `lockfile = true` records each pin's exact resolution in mise.lock. git and bash
+# come from the machine.
+
+[settings]
+lockfile = true
+
+[tools]
+actionlint = "1.7"
+gh = "2.103"
+jq = "1.8"
+just = "1.59"
+shellcheck = "0.11"
+"npm:bats" = "1.13"
diff --git a/tests/hooks.bats b/tests/hooks.bats
new file mode 100644
index 0000000..faccb2d
--- /dev/null
+++ b/tests/hooks.bats
@@ -0,0 +1,67 @@
+#!/usr/bin/env bats
+# hooks.bats - the desk guard: pre-rebase refuses the default branch, pre-commit refuses a lint finding
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  git config core.hooksPath "${kit_checkout}/.kit/hooks"
+  printf 'one\n' > a && git add a && git commit --quiet --message one
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+@test "pre-rebase refuses a rebase of main that would rewrite a commit, and allows one in a branch" {
+  git switch --quiet --create feature
+  printf 'two\n' > b && git add b && git commit --quiet --message two
+  git switch --quiet main
+  printf 'three\n' > c && git add c && git commit --quiet --message three
+  run git rebase feature
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"refusing to rebase 'main'"* ]]
+  git switch --quiet feature
+  run git rebase main
+  [ "$status" -eq 0 ]
+}
+
+@test "pre-rebase lets main fast-forward" {
+  git switch --quiet --create feature
+  printf 'two\n' > b && git add b && git commit --quiet --message two
+  git switch --quiet main
+  run git rebase feature
+  [ "$status" -eq 0 ]
+}
+
+@test "pre-commit refuses a bash file shellcheck faults, and passes a clean one" {
+  printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
+  git add bad.sh
+  run git commit --quiet --message bad
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"SC2086"* ]]
+  [[ "$output" == *"refusing the commit"* ]]
+  printf '#!/usr/bin/env bash\necho "${x:-}"\n' > bad.sh
+  git add bad.sh
+  run git commit --quiet --message good
+  [ "$status" -eq 0 ]
+}
+
+@test "pre-commit reports a skip when the linter is not on PATH" {
+  printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
+  git add bad.sh
+  # a PATH without any directory that carries a shellcheck
+  without=""
+  while IFS= read -r dir
+  do
+    [[ -n "${dir}" && ! -x "${dir}/shellcheck" ]] && without="${without:+${without}:}${dir}"
+  done < <(printf '%s' "${PATH}" | tr ':' '\n')
+  run env PATH="${without}" git commit --quiet --message bad
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"NOT linted"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
new file mode 100644
index 0000000..3da2a8f
--- /dev/null
+++ b/tests/kit.bats
@@ -0,0 +1,137 @@
+#!/usr/bin/env bats
+# kit.bats - bin/kit install, check, and update against a fresh repository
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Each test gets an empty git repository under a temporary directory and runs the kit from this checkout against
+# it. The update tests build a second, later payload from the first so the three-way merge has a base.
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  repo=$(mktemp -d)
+  git -C "${repo}" init --quiet --initial-branch=main
+  cd "${repo}"
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+# later-release <dir> copies this checkout's kit to <dir> as version 9.9.9 with one changed rule line.
+later-release() {
+  mkdir -p "$1"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/.kit" "$1/"
+  rm -f "$1/.kit/manifest"
+  printf '9.9.9\n' > "$1/.kit/version"
+  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/.kit/rules/json.md"
+}
+
+@test "install writes the delivered tree, the mirrors, the workflow, the settings, and the manifest" {
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ -f .kit/1st.md ]
+  [ -x .kit/hooks/pre-commit ]
+  [ -f .claude/rules/kit-markdown.md ]
+  head -n 1 .claude/rules/kit-bash.md | grep --quiet --line-regexp -- '---'
+  grep --quiet '"\*\*/\*\.sh"' .claude/rules/kit-bash.md
+  [ -f .github/workflows/kit-ci.yml ]
+  jq --exit-status '.permissions.deny | index("Bash(git push --force *)")' .claude/settings.json >/dev/null
+  grep --quiet --line-regexp '/worktrees/' .gitignore
+  grep --quiet '^version 0.1.0$' .kit/manifest
+  [ "$(git config core.hooksPath)" = ".kit/hooks" ]
+}
+
+@test "install keeps the repository's own settings keys and deny entries" {
+  mkdir .claude
+  printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
+  "${kit_checkout}/bin/kit" install
+  [ "$(jq --raw-output .model .claude/settings.json)" = "x" ]
+  jq --exit-status '.permissions.deny | index("Bash(rm -rf /)")' .claude/settings.json >/dev/null
+  jq --exit-status '.permissions.deny | index("Bash(git switch main *)")' .claude/settings.json >/dev/null
+}
+
+@test "install refuses a second time and names update" {
+  "${kit_checkout}/bin/kit" install
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"run: kit update"* ]]
+}
+
+@test "check passes after install and fails on a drifted, a missing, and a lost deny entry" {
+  "${kit_checkout}/bin/kit" install
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  printf 'edited\n' >> .kit/rules/yaml.md
+  rm .claude/rules/kit-json.md
+  jq '.permissions.deny -= ["Bash(git reset --hard *)"]' .claude/settings.json > s && mv s .claude/settings.json
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/rules/yaml.md differs"* ]]
+  [[ "$output" == *".claude/rules/kit-json.md is missing"* ]]
+  [[ "$output" == *"missing a deny entry"* ]]
+  [[ "$output" == *"3 finding(s)"* ]]
+}
+
+@test "check refuses without a manifest and names install" {
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"run: kit install"* ]]
+}
+
+@test "update replaces unchanged files, merges an edited one, and records the release's digests" {
+  "${kit_checkout}/bin/kit" install
+  later-release "${repo}.later"
+  # a consumer edit to a file the later release also changes, on a different line
+  sed -i.bak '1s/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 0 ]
+  grep --quiet '^version 9.9.9$' .kit/manifest
+  grep --quiet '^# JSON (ours)$' .kit/rules/json.md
+  grep --quiet '^## Added in 9.9.9$' .kit/rules/json.md
+  grep --quiet '^## Added in 9.9.9$' .claude/rules/kit-json.md
+  # the manifest carries the release's digest, so the edit still reads as an edit
+  release_digest=$(shasum -a 256 "${repo}.later/.kit/rules/json.md" | cut -d ' ' -f 1)
+  grep --quiet "^${release_digest}  .kit/rules/json.md$" .kit/manifest
+  # and check names the one file that still differs from the release
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/rules/json.md differs"* ]]
+  [[ "$output" == *"1 finding(s)"* ]]
+  rm -rf "${repo}.later"
+}
+
+@test "update of an untouched install leaves check green" {
+  "${kit_checkout}/bin/kit" install
+  later-release "${repo}.later"
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 0 ]
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 0 ]
+  rm -rf "${repo}.later"
+}
+
+@test "update leaves conflict markers and fails when the same lines changed" {
+  "${kit_checkout}/bin/kit" install
+  later-release "${repo}.later"
+  printf '9.9.9\n' > "${repo}.later/.kit/version"
+  sed -i.bak '1s/^# JSON$/# JSON (theirs)/' "${repo}.later/.kit/rules/json.md" && rm "${repo}.later/.kit/rules/json.md.bak"
+  sed -i.bak '1s/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 1 ]
+  grep --quiet '^<<<<<<<' .kit/rules/json.md
+  [[ "$output" == *"conflict markers"* ]]
+  rm -rf "${repo}.later"
+}
+
+@test "update without the base release refuses an edited file and names the base" {
+  "${kit_checkout}/bin/kit" install
+  later-release "${repo}.later"
+  printf 'edited\n' >> .kit/rules/bash.md
+  # a mise that answers nothing, ahead of the real one
+  mkdir shims && printf '#!/usr/bin/env bash\nexit 1\n' > shims/mise && chmod +x shims/mise
+  run env PATH="${PWD}/shims:${PATH}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"base release 0.1.0 is not installed"* ]]
+  rm -rf "${repo}.later"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/release.bats b/tests/release.bats
new file mode 100644
index 0000000..e5a0494
--- /dev/null
+++ b/tests/release.bats
@@ -0,0 +1,35 @@
+#!/usr/bin/env bats
+# release.bats - a release packed the way the workflow packs it installs from its unpacked directory
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  work=$(mktemp -d)
+  cd "${work}"
+}
+
+teardown() {
+  rm -rf "${work}"
+}
+
+@test "the tarball holds one directory with bin/ and .kit/, no manifest, and installs a fresh repository" {
+  version=$(cat "${kit_checkout}/.kit/version")
+  mkdir "kit-${version}"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/.kit" "kit-${version}/"
+  rm -f "kit-${version}/.kit/manifest"
+  tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
+  rm -rf "kit-${version}"
+  mkdir unpacked && tar --extract --gzip --file "kit-${version}.tar.gz" --directory unpacked
+  [ "$(ls unpacked)" = "kit-${version}" ]
+  [ -x "unpacked/kit-${version}/bin/kit" ]
+  [ ! -e "unpacked/kit-${version}/.kit/manifest" ]
+  mkdir fresh && git -C fresh init --quiet --initial-branch=main
+  cd fresh
+  run "${work}/unpacked/kit-${version}/bin/kit" install
+  [ "$status" -eq 0 ]
+  run "${work}/unpacked/kit-${version}/bin/kit" check
+  [ "$status" -eq 0 ]
+  [ "$("${work}/unpacked/kit-${version}/bin/kit" version)" = "${version}" ]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------

From 39a380e083ff083f5708f4de7f43ce6e78d7984c Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:02:27 -0700
Subject: [PATCH 006/108] #1 README.md, AGENTS.md: the kit uses its own kit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md      |  49 ++++++++++++
 .claude/rules/kit-gitignore.md |  29 +++++++
 .claude/rules/kit-json.md      |  26 ++++++
 .claude/rules/kit-just.md      |  50 ++++++++++++
 .claude/rules/kit-markdown.md  |  43 ++++++++++
 .claude/rules/kit-yaml.md      |  34 ++++++++
 .claude/settings.json          |  12 +++
 .github/workflows/kit-ci.yml   | 141 +++++++++++++++++++++++++++++++++
 .gitignore                     |   7 ++
 .kit/manifest                  |  24 ++++++
 AGENTS.md                      |  15 ++++
 README.md                      |  56 ++++++++++---
 12 files changed, 475 insertions(+), 11 deletions(-)
 create mode 100644 .claude/rules/kit-bash.md
 create mode 100644 .claude/rules/kit-gitignore.md
 create mode 100644 .claude/rules/kit-json.md
 create mode 100644 .claude/rules/kit-just.md
 create mode 100644 .claude/rules/kit-markdown.md
 create mode 100644 .claude/rules/kit-yaml.md
 create mode 100644 .claude/settings.json
 create mode 100644 .github/workflows/kit-ci.yml
 create mode 100644 .gitignore
 create mode 100644 .kit/manifest
 create mode 100644 AGENTS.md

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
new file mode 100644
index 0000000..dbecf1c
--- /dev/null
+++ b/.claude/rules/kit-bash.md
@@ -0,0 +1,49 @@
+---
+paths:
+  - "**/*.sh"
+  - "**/*.bash"
+  - ".kit/hooks/*"
+---
+# Bash
+
+Applies to `*.sh`, `*.bash`, `.kit/hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+workflows.
+
+## Shape
+
+1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner, a rule of dashes to
+   column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
+   would change the caller's.
+3. A git hook that must fail open sets `-o nounset -o pipefail` and no `errexit`, and says so in its banner.
+4. The file closes with the same rule of dashes.
+
+## Style
+
+1. `then`, `do`, and `else` go on their own line, never after a semicolon.
+2. Spell `set` options out: `set -o errexit`, never `set -e`.
+3. Spell command options out: `--raw-output`, `--field`, `--delimiter`, never a one-letter flag in a script.
+   Where BSD and GNU differ, use the form both accept: `sed -n`, `head -n 1`, `mkdir -p`.
+4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
+5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
+6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
+7. Quote every expansion outside `[[ ]]` and `(( ))`.
+8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename.
+9. A function private to one executed script is bare kebab-case.
+
+## Behavior
+
+1. An error message is one line, names the remedy first, and is the same wherever the same condition arises.
+2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
+3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
+4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
+5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
+   to do, and a `--dry-run` where the mutation is a sweep.
+6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
+7. shellcheck passes with no directive, or the directive carries the reason on the same line.
+
+## Comments
+
+1. A comment states what the code does and the non-obvious why. It carries no history and defends no obvious
+   choice.
+2. A pointer is `# see: <ref>`, on its own line after the comment it supports.
diff --git a/.claude/rules/kit-gitignore.md b/.claude/rules/kit-gitignore.md
new file mode 100644
index 0000000..41b87e4
--- /dev/null
+++ b/.claude/rules/kit-gitignore.md
@@ -0,0 +1,29 @@
+---
+paths:
+  - ".gitignore"
+  - "**/.gitignore"
+---
+# Ignore lists
+
+Applies to `.gitignore` at any depth.
+
+## Shape
+
+1. The file opens with `# .gitignore - untracked files and folders`, a rule of dashes to column 120, and a
+   blank line.
+2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
+   line.
+3. The file closes with a rule of dashes.
+
+## Entries
+
+1. Every entry names a file the repository itself produces. Editor and operating-system files belong in the
+   user's global ignore list, not here.
+2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
+   repository.
+3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
+4. `worktrees/` is ignored at the root: it is where the loop checks out a branch per issue.
+
+## Adding one
+
+Ask what produces the file. If nothing in the repository does, do not add it.
diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
new file mode 100644
index 0000000..9d0859d
--- /dev/null
+++ b/.claude/rules/kit-json.md
@@ -0,0 +1,26 @@
+---
+paths:
+  - "**/*.json"
+  - "**/*.jsonc"
+---
+# JSON
+
+Applies to `*.json` and `*.jsonc`.
+
+## Shape
+
+1. Two-space indentation. Keys in a stable order: the order the consuming tool documents, else alphabetical.
+2. One trailing newline. No trailing commas in `.json`.
+3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where
+   it reads plain JSON, the reason for a setting lives in the document that describes the file.
+
+## Settings
+
+1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
+2. A tool's settings file that the kit writes into is merged by key. The kit owns only the keys and entries
+   it writes, and anything else in the file is the repository's.
+
+## Comments
+
+1. A comment states what the entry does and the non-obvious why. It carries no history.
+2. A pointer is `// see: <ref>`.
diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
new file mode 100644
index 0000000..0958e80
--- /dev/null
+++ b/.claude/rules/kit-just.md
@@ -0,0 +1,50 @@
+---
+paths:
+  - "justfile"
+  - "**/justfile"
+  - "**/*.just"
+---
+# Just
+
+Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
+applies to it as well.
+
+## Shape
+
+1. A module file opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120, and
+   a description of what the file is and who imports it.
+2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
+   root, which has no parent), `set positional-arguments := true`, and `set export := true`.
+3. Every justfile carries the default-and-help pair:
+
+   ```just
+   # Default recipe: list this justfile's recipes.
+   _: help
+
+   # List recipes in this justfile.
+   [no-exit-message]
+   @help *options:
+     just --justfile "{{source_file()}}" --list
+   ```
+
+4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
+   the invoking root rather than the module's directory.
+5. The file closes with a rule of dashes.
+
+## Recipes
+
+1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
+2. A comment block precedes every recipe: usage lines, then a paragraph of intent. It answers what the recipe
+   does, when to run it, and what it produces.
+3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
+4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
+5. Recipe bodies use `${var}`, never `{{var}}` mixed in. `set export := true` makes parameters available.
+6. Two-space indentation inside a body. Never a tab.
+7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
+8. Comments wrap at 118 columns. Bodies do not wrap.
+
+## Invocation
+
+1. The idiom is the space form, `just kit issue 42`, never `just kit/issue` and never `kit::issue` outside a
+   dependency list.
+2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
new file mode 100644
index 0000000..43d822f
--- /dev/null
+++ b/.claude/rules/kit-markdown.md
@@ -0,0 +1,43 @@
+---
+paths:
+  - "**/*.md"
+---
+# Markdown
+
+Applies to `*.md`.
+
+## Prose
+
+1. Write plain declarative sentences with the thing under discussion as the subject.
+2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
+3. Use a list where the content is a list. Use a table where the content has columns.
+4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
+5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
+6. Use the serial comma in every list of three or more.
+7. Expand an uncommon acronym the first time it appears.
+8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
+   when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
+
+## Layout
+
+1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
+   per nesting level, to a limit of 12.
+2. Balance the wrap: no line, in particular the last, reads as a stub.
+3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
+4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
+5. Headings are ATX (`#`). One `#` heading per file, at the top.
+6. Fenced code blocks declare a language and have a blank line on each side.
+7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
+
+## Links
+
+1. Use inline links with descriptive text, never a bare URL in angle brackets.
+2. Use the same anchor text every time the same URL appears in a file.
+3. When a label and the link text would say the same thing, make the label the link.
+4. A relative link resolves from the file that carries it, and it resolves: a check reads them.
+
+## Files
+
+1. Name an index file `1st.md`. It lists its siblings and says what each is for.
+2. A file says what its subject is in its first paragraph, before how to use it.
+3. No file names another repository as the source of a rule.
diff --git a/.claude/rules/kit-yaml.md b/.claude/rules/kit-yaml.md
new file mode 100644
index 0000000..69fe17c
--- /dev/null
+++ b/.claude/rules/kit-yaml.md
@@ -0,0 +1,34 @@
+---
+paths:
+  - "**/*.yml"
+  - "**/*.yaml"
+---
+# YAML
+
+Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
+
+## Shape
+
+1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
+   reader would not guess from the keys.
+2. Two-space indentation. No tabs. No trailing whitespace.
+3. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
+4. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
+   breaks the requirement.
+5. `permissions` is declared at the top and names the least the jobs need.
+
+## Steps
+
+1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. A step has a `name` that is the policy it enforces, in kebab-case.
+3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
+4. A refusal prints `::error::<message>`, writes `### ❌ <Message>` and a remedy to `${GITHUB_STEP_SUMMARY}`,
+   and returns non-zero. The remedy is the action to take, with a link that is that action.
+5. A pass writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
+7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
+
+## Comments
+
+1. A comment states the non-obvious why. It carries no history.
+2. A pointer is `# see: <ref>`.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..7911d58
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(git checkout main *)",
+      "Bash(git switch main *)",
+      "Bash(git reset --hard *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git worktree remove --force *)"
+    ]
+  }
+}
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
new file mode 100644
index 0000000..dd0e5f0
--- /dev/null
+++ b/.github/workflows/kit-ci.yml
@@ -0,0 +1,141 @@
+# kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# One job, CI, which is the check name a ruleset requires. Three steps: the repository's `just ci` when its
+# root justfile has one, `kit check` against the release mise pins, and a refusal of a pull request that is
+# not linked to an open issue of this repository under Development. The last two run even when an earlier step
+# refused, so one run reports every finding.
+#
+# This file is placed by `kit install` and verified by `kit check`. Change it by pinning a new release.
+#
+# see: .kit/1st.md
+
+name: kit
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+jobs:
+  CI:
+    if: github.event.pull_request.base.ref == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      # Every tool below comes from mise.toml, the kit included.
+      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
+
+      - name: gate
+        run: |
+          set -o errexit -o nounset -o pipefail
+          if [[ ! -f justfile ]] || ! just --show ci >/dev/null 2>&1
+          then
+            echo "::warning::the root justfile has no ci recipe, so the gate was skipped"
+            printf '⚠️ The gate was skipped: the root justfile has no ci recipe.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+          else
+            just ci
+            printf '✅ just ci passed.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+          fi
+
+      - name: kit-check
+        if: ${{ !cancelled() }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+          if command -v kit >/dev/null 2>&1
+          then
+            kit check
+          elif [[ -x bin/kit ]]
+          then
+            bin/kit check
+          else
+            echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'
+            printf '### ❌ kit is not on PATH\n\nPin the release in mise.toml under [tools]: "github:empowerite/kit" = "<version>".\n' \
+              | tee --append "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          fi
+          printf '✅ Every delivered file matches the pinned kit release.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+
+      - name: linked-open-issue
+        if: ${{ !cancelled() }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+
+          repo_slug="${GITHUB_REPOSITORY}"
+          pr=$(jq --raw-output '.pull_request.number' "${GITHUB_EVENT_PATH}")
+          pull="${GITHUB_SERVER_URL}/${repo_slug}/pull/${pr}"
+          run="${GITHUB_SERVER_URL}/${repo_slug}/actions/runs/${GITHUB_RUN_ID}"
+
+          remedy=$(cat <<REMEDY
+          Link an open issue of this repository under **Development** in [the sidebar](${pull}):
+
+          1. click the gear (⚙) beside **Development**
+          2. pick one or more open issues
+          3. [re-run this check](${run}): linking fires no event, so it does not re-run on its own
+
+          \`just kit issue <N>\` makes this link when it starts the work.
+          REMEDY
+          )
+
+          refuse() {
+            echo "::error::$1"
+            printf '### ❌ %s\n\n%s\n' "${1^}" "${remedy}" | tee --append "${GITHUB_STEP_SUMMARY}"
+            return 1
+          }
+
+          query=$(cat <<'GRAPHQL'
+          query($owner: String!, $name: String!, $number: Int!) {
+            repository(owner: $owner, name: $name) {
+              pullRequest(number: $number) {
+                closingIssuesReferences(first: 100) {
+                  nodes { number state repository { nameWithOwner } }
+                }
+              }
+            }
+          }
+          GRAPHQL
+          )
+          refs=$(gh api graphql \
+            --field owner="${repo_slug%%/*}" \
+            --field name="${repo_slug#*/}" \
+            --field number="${pr}" \
+            --raw-field query="${query}" \
+            --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
+                  | "\(.number) \(.state) \(.repository.nameWithOwner)"')
+
+          if [[ -z "${refs}" ]]
+          then
+            refuse 'this pull request is not linked to any issue'
+          else
+            open_local=0
+            while read -r n state repo
+            do
+              if [[ "${repo}" != "${repo_slug}" ]]
+              then
+                echo "::warning::skipping ${repo}#${n}: it belongs to another repository"
+                continue
+              fi
+              if [[ "${state}" != OPEN ]]
+              then
+                echo "::warning::${repo}#${n} is ${state}; merging will not change it"
+                continue
+              fi
+              open_local=$(( open_local + 1 ))
+            done <<< "${refs}"
+            if (( open_local == 0 ))
+            then
+              refuse 'every issue this pull request is linked to is closed or belongs to another repository'
+            else
+              closes=$(cut --delimiter=' ' --fields=1 <<< "${refs}" | sed 's/^/#/' | paste --serial --delimiters=' ')
+              printf '✅ Linked to %s.\n' "${closes}" | tee --append "${GITHUB_STEP_SUMMARY}"
+            fi
+          fi
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2fb096f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,7 @@
+# .gitignore - untracked files and folders
+# ----------------------------------------------------------------------------------------------------------------------
+
+# the per-issue worktrees of the loop; see: .kit/1st.md
+/worktrees/
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/manifest b/.kit/manifest
new file mode 100644
index 0000000..51c397d
--- /dev/null
+++ b/.kit/manifest
@@ -0,0 +1,24 @@
+version 0.1.0
+367c3c2d28f51dbe2549803e113ad45db507aa68afc1997f3d5b20f94796ec6f  .kit/1st.md
+a36a18081eb7515871bc01b7b22372c1545d99d8b393fb386c78128f73c8dbb5  .kit/bash/1st.sh
+6944cdb161e68bf5d2355c6ee48fe7bfd25d8ffa1e6edef218af123e5edf5f7c  .kit/bash/gh.sh
+051cab217451a69c6f73545fe3e68fb2316e0be57004030159fe299d7f510436  .kit/bash/git.sh
+8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .kit/ci.yml
+1ab629cb79710438fb15fd2fcbadf94ce125f4d3c26bf22def6d35c8c414dbb1  .kit/hooks/pre-commit
+414bb9a82191060489213823e98828a64d166c53109c64cdf600fdd3d5c64205  .kit/hooks/pre-rebase
+47919ba1fabfc077ff3950f2743d94d016d58350cfe36cf97d2130419de6b6c6  .kit/kit.just
+cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bash.md
+5c3667b1282bf6afe6cebc401e99faa2ba52e4a4873bbec9a6368a4623277f2d  .kit/rules/gitignore.md
+6ddb651356399b10dc33858cdf38fe111aa8803cde1d499135faa0e196f74f97  .kit/rules/json.md
+dd88591e25a0df6a039f5183f0e573e35c53b9903f04cc879b743a715f8e6559  .kit/rules/just.md
+df7388a40e037d82f77d92f0dfe0deed55184c4a8bf869dbce86986673ebeab5  .kit/rules/markdown.md
+52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
+617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .kit/settings.json
+e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
+1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .claude/rules/kit-bash.md
+4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
+1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
+3547ea76e2711f003da90817292e48cec55926e95ae2a06dc53de0954ab38508  .claude/rules/kit-just.md
+13fff95ff67775bebb820d10dbd73f4f5eb23571f0619462fa5abb1b8c6b42c6  .claude/rules/kit-markdown.md
+4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
+8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .github/workflows/kit-ci.yml
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c6faa17
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,15 @@
+@.kit/1st.md
+
+Read .kit/1st.md first. It is the kit's entry file, and this repository uses its own kit.
+
+## This repository's own rules
+
+- The delivered tree is `.kit/` and `bin/kit`. Everything in it is written for a consumer: no file names a
+  consumer, a person, or another repository as the source of a rule.
+- `.kit/version` is the release version. A release is a commit on `main` that sets it, then the tag `v<version>`
+  on that commit. The release workflow refuses a tag whose version differs from the file, or whose commit is not
+  on `main`.
+- `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
+  this repository's installed copies of its own kit. Change a delivered file at its source under `.kit/`, then
+  run `just refresh` to rewrite the copies, and commit both.
+- `just ci` is the gate: shellcheck, actionlint, the bats suite, and `bin/kit check`.
diff --git a/README.md b/README.md
index cda6989..a661029 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,38 @@
 kit is the agentic guardrails a repository takes as a versioned mixin: the policy text an agent reads first, the
 rules that bind each kind of file, the guard that keeps `main` as the human's desk, and the one command no harness
 provides, the issue-to-worktree on-ramp. A tag on `main` publishes a release. A consumer pins it in `mise.toml`,
-installs it with `kit install`, and keeps rules of its own beside it. What the first release delivers, and what the
-kit is not, is [#1](https://github.com/empowerite/kit/issues/1).
+installs it with `kit install`, and keeps rules of its own beside it. The design is
+[#1](https://github.com/empowerite/kit/issues/1), and the entry file every agent reads is [.kit/1st.md](.kit/1st.md).
+
+## Take the kit
+
+Pin a release in the repository's `mise.toml`, then install it:
+
+```toml
+[tools]
+"github:empowerite/kit" = "0.1.0"
+```
+
+```sh
+mise install
+kit install
+```
+
+`kit install` copies `.kit/` into the repository, places `.claude/rules/kit-*.md` and
+`.github/workflows/kit-ci.yml`, merges its deny rules into `.claude/settings.json`, ignores `worktrees/`, points
+`core.hooksPath` at `.kit/hooks`, and writes `.kit/manifest`. Commit what it wrote. Then:
+
+- Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
+- Add `mod kit ".kit/kit.just"` to the root justfile for `just kit issue`, `just kit tidy`, and `just kit status`.
+- Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
+  request not linked to an open issue.
+
+To move to a new release, bump the pin, run `mise install`, then `kit update`: a delivered file you left alone is
+replaced, one you edited is three-way merged with the previous release as the base, and your own deny entries
+and settings keys stay. `kit check` fails, locally and in `CI`, when a delivered file differs from the pinned
+release.
+
+The kit needs bash 4 or later, git, `gh`, and `jq`. macOS ships bash 3.2; `brew install bash` gives a current one.
 
 ## Setup
 
@@ -16,19 +46,23 @@ git config user.signingkey <a key GitHub verifies for you>
 git config commit.gpgsign true
 ```
 
+Then `mise install` for the pinned tools, and `bin/kit install` is already done: this repository carries the
+installed copy of its own kit, which `just ci` checks.
+
 ## Getting started
 
-Work here moves by the loop the kit itself delivers. An issue exists. A branch is checked out in a worktree under
-`worktrees/`, linked to the issue under Development, with a draft pull request. Commits are signed, and their
-subject is `#<N> <area>: <subject>`. `gh pr ready` says the work is done, and the pull request body is the report.
-A human merges. Nothing reaches `main` any other way.
+Work here moves by the loop in [.kit/1st.md](.kit/1st.md). An issue exists. `just kit issue <N>` makes
+`worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a draft pull request. Commits
+are signed, and their subject is `#<N> <area>: <subject>`. `gh pr ready` says the work is done, and the pull
+request body is the report. A human merges.
 
-Until the kit can run itself, those steps are taken by hand. The first thing #1 delivers is the command that takes
-them.
+`just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
+`bin/kit check`.
 
-## Status
+## Release
 
-Pre-alpha. There is no code yet, so nothing here builds, tests, or runs. The repository will use its own kit as soon
-as the kit exists.
+A release is two steps on `main`: a pull request that sets `.kit/version`, then the tag `v<version>` on its merge
+commit. The release workflow packs `bin/` and `.kit/` into `kit-<version>.tar.gz` and publishes the GitHub
+release. It refuses a tag that is not on `main` or whose version differs from the file.
 
 Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf

From a2553e38910ea5a267aaa5f4aa937b92fd894c54 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:03:41 -0700
Subject: [PATCH 007/108] #1 .mise/locks: the npm lock sidecar mise install
 --locked reads

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .mise/locks/npm-bats/1.13.0/aube-lock.yaml | 23 ++++++++++++++++++++++
 .mise/locks/npm-bats/1.13.0/package.json   |  7 +++++++
 2 files changed, 30 insertions(+)
 create mode 100644 .mise/locks/npm-bats/1.13.0/aube-lock.yaml
 create mode 100644 .mise/locks/npm-bats/1.13.0/package.json

diff --git a/.mise/locks/npm-bats/1.13.0/aube-lock.yaml b/.mise/locks/npm-bats/1.13.0/aube-lock.yaml
new file mode 100644
index 0000000..0bae35d
--- /dev/null
+++ b/.mise/locks/npm-bats/1.13.0/aube-lock.yaml
@@ -0,0 +1,23 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      bats:
+        specifier: 1.13.0
+        version: 1.13.0
+
+packages:
+
+  bats@1.13.0:
+    resolution: {integrity: sha512-giSYKGTOcPZyJDbfbTtzAedLcNWdjCLbXYU3/MwPnjyvDXzu6Dgw8d2M+8jHhZXSmsCMSQqCp+YBsJ603UO4vQ==}
+    hasBin: true
+
+snapshots:
+
+  bats@1.13.0: {}
diff --git a/.mise/locks/npm-bats/1.13.0/package.json b/.mise/locks/npm-bats/1.13.0/package.json
new file mode 100644
index 0000000..43bd251
--- /dev/null
+++ b/.mise/locks/npm-bats/1.13.0/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "mise-npm-install",
+  "private": true,
+  "dependencies": {
+    "bats": "1.13.0"
+  }
+}

From a71f945f70dd2c53f084de2068750777a3113f26 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:05:42 -0700
Subject: [PATCH 008/108] #1 mise.toml: bats from the aqua backend, not npm

The npm backend's bats could not exec on a Linux runner; the aqua backend fetches the release archive and needs no node.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .mise/locks/npm-bats/1.13.0/aube-lock.yaml | 23 -----------------
 .mise/locks/npm-bats/1.13.0/package.json   |  7 -----
 mise.lock                                  | 30 ++++++++++++++++++++++
 mise.toml                                  |  2 +-
 4 files changed, 31 insertions(+), 31 deletions(-)
 delete mode 100644 .mise/locks/npm-bats/1.13.0/aube-lock.yaml
 delete mode 100644 .mise/locks/npm-bats/1.13.0/package.json

diff --git a/.mise/locks/npm-bats/1.13.0/aube-lock.yaml b/.mise/locks/npm-bats/1.13.0/aube-lock.yaml
deleted file mode 100644
index 0bae35d..0000000
--- a/.mise/locks/npm-bats/1.13.0/aube-lock.yaml
+++ /dev/null
@@ -1,23 +0,0 @@
-lockfileVersion: '9.0'
-
-settings:
-  autoInstallPeers: true
-  excludeLinksFromLockfile: false
-
-importers:
-
-  .:
-    dependencies:
-      bats:
-        specifier: 1.13.0
-        version: 1.13.0
-
-packages:
-
-  bats@1.13.0:
-    resolution: {integrity: sha512-giSYKGTOcPZyJDbfbTtzAedLcNWdjCLbXYU3/MwPnjyvDXzu6Dgw8d2M+8jHhZXSmsCMSQqCp+YBsJ603UO4vQ==}
-    hasBin: true
-
-snapshots:
-
-  bats@1.13.0: {}
diff --git a/.mise/locks/npm-bats/1.13.0/package.json b/.mise/locks/npm-bats/1.13.0/package.json
deleted file mode 100644
index 43bd251..0000000
--- a/.mise/locks/npm-bats/1.13.0/package.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "name": "mise-npm-install",
-  "private": true,
-  "dependencies": {
-    "bats": "1.13.0"
-  }
-}
diff --git a/mise.lock b/mise.lock
index 9537f2b..dd72d7a 100644
--- a/mise.lock
+++ b/mise.lock
@@ -49,6 +49,36 @@ url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_
 url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924919"
 provenance = "github-attestations"
 
+[[tools.bats]]
+version = "1.13.0"
+backend = "aqua:bats-core/bats-core"
+specifiers = ["1.13"]
+
+[tools.bats."platforms.linux-arm64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+
+[tools.bats."platforms.linux-arm64-musl"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+
+[tools.bats."platforms.linux-x64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+
+[tools.bats."platforms.linux-x64-musl"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+
+[tools.bats."platforms.macos-arm64"]
+checksum = "blake3:d34af9fd0f9101d5309b2de31f3d1699e56a574d7d4b5e6380580a9e758a9744"
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+
+[tools.bats."platforms.macos-x64"]
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+
 [[tools.gh]]
 version = "2.103.0"
 backend = "aqua:cli/cli"
diff --git a/mise.toml b/mise.toml
index 3b0f587..53ce17c 100644
--- a/mise.toml
+++ b/mise.toml
@@ -13,4 +13,4 @@ gh = "2.103"
 jq = "1.8"
 just = "1.59"
 shellcheck = "0.11"
-"npm:bats" = "1.13"
+bats = "1.13"

From 0679fe4db858d77b0bc09f5feea912573d9aef63 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:08:36 -0700
Subject: [PATCH 009/108] #1 tests/hooks.bats: hide the linter without hiding
 git

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/hooks.bats | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/tests/hooks.bats b/tests/hooks.bats
index faccb2d..be264ec 100644
--- a/tests/hooks.bats
+++ b/tests/hooks.bats
@@ -53,13 +53,13 @@ teardown() {
 @test "pre-commit reports a skip when the linter is not on PATH" {
   printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
   git add bad.sh
-  # a PATH without any directory that carries a shellcheck
-  without=""
-  while IFS= read -r dir
+  # a PATH of one directory, carrying only what the hook itself runs, and no shellcheck
+  mkdir only
+  for tool in bash git env cat
   do
-    [[ -n "${dir}" && ! -x "${dir}/shellcheck" ]] && without="${without:+${without}:}${dir}"
-  done < <(printf '%s' "${PATH}" | tr ':' '\n')
-  run env PATH="${without}" git commit --quiet --message bad
+    ln -s "$(command -v "${tool}")" "only/${tool}"
+  done
+  run env PATH="${PWD}/only" git commit --quiet --message bad
   [ "$status" -eq 0 ]
   [[ "$output" == *"NOT linted"* ]]
 }

From 8c3fe7159f28cdce037d5a6c5a7b2c9e6d32ff0b Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:17:12 -0700
Subject: [PATCH 010/108] #1 .github/workflows/release.yml: only a version tag
 starts a run

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index fbf936c..e05db38 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -2,8 +2,9 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/ and .kit/, the layout
-# a consumer's mise unpacks and puts on PATH. Two refusals: a tag whose commit is not on main, and a tag whose
-# version is not the one .kit/version records, so the release's version and the kit's own agree.
+# a consumer's mise unpacks and puts on PATH. Only a version tag starts a run, and the run refuses a tag whose
+# commit is not on main (any commit on main, not only its head), a tag that is not v<major>.<minor>.<patch> with an
+# optional pre-release suffix, and a tag whose version is not the one .kit/version records at that commit.
 #
 # see: .kit/1st.md
 
@@ -11,7 +12,7 @@ name: release
 
 on:
   push:
-    tags: ['v*']
+    tags: ['v[0-9]*']
 
 permissions:
   contents: write
@@ -39,6 +40,11 @@ jobs:
         run: |
           set -o errexit -o nounset -o pipefail
           tag_version=${GITHUB_REF_NAME#v}
+          if [[ ! "${tag_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
+          then
+            echo "::error::${GITHUB_REF_NAME} is not a version tag; a release tag is v<major>.<minor>.<patch>, with an optional -<pre-release>"
+            exit 1
+          fi
           file_version=$(cat .kit/version)
           if [[ "${tag_version}" != "${file_version}" ]]
           then

From 83522783560a0b3c4159f1f23d9eab8e77ec86f1 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:19:32 -0700
Subject: [PATCH 011/108] #1 .github/workflows/release.yml: a pre-release is
 tagged off main, a release on it

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 45 +++++++++++++++++++++++++----------
 AGENTS.md                     |  6 ++---
 README.md                     |  9 ++++---
 3 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e05db38..432d02f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -2,9 +2,11 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/ and .kit/, the layout
-# a consumer's mise unpacks and puts on PATH. Only a version tag starts a run, and the run refuses a tag whose
-# commit is not on main (any commit on main, not only its head), a tag that is not v<major>.<minor>.<patch> with an
-# optional pre-release suffix, and a tag whose version is not the one .kit/version records at that commit.
+# a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
+# is tagged on main (any commit on main, not only its head). A pre-release, the same with a -<suffix>, is tagged on
+# a commit that is not on main, and is published as a GitHub pre-release. Either way .kit/version at the tagged
+# commit is the version without the suffix, the one under development, and the packed kit carries the tag's full
+# version so a consumer pinning a pre-release sees it in kit version and .kit/manifest.
 #
 # see: .kit/1st.md
 
@@ -25,30 +27,45 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: tag-is-on-main
+      - name: tag-is-a-version
         run: |
           set -o errexit -o nounset -o pipefail
-          default_branch=$(jq --raw-output '.repository.default_branch' "${GITHUB_EVENT_PATH}")
-          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/${default_branch}"
+          tag_version=${GITHUB_REF_NAME#v}
+          if [[ ! "${tag_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
           then
-            echo "::error::${GITHUB_REF_NAME} is not on ${default_branch}; delete the tag and tag a commit on ${default_branch}"
+            echo "::error::${GITHUB_REF_NAME} is not a version tag; a release is v<major>.<minor>.<patch>, a pre-release the same with -<suffix>"
             exit 1
           fi
-          echo "✅ ${GITHUB_REF_NAME} is on ${default_branch}."
+          echo "✅ ${GITHUB_REF_NAME} is a version tag."
 
-      - name: tag-matches-version
+      - name: tag-is-on-the-right-side-of-main
         run: |
           set -o errexit -o nounset -o pipefail
           tag_version=${GITHUB_REF_NAME#v}
-          if [[ ! "${tag_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
+          default_branch=$(jq --raw-output '.repository.default_branch' "${GITHUB_EVENT_PATH}")
+          on_main=false
+          git merge-base --is-ancestor "${GITHUB_SHA}" "origin/${default_branch}" && on_main=true
+          if [[ "${tag_version}" == *-* && "${on_main}" == true ]]
+          then
+            echo "::error::${GITHUB_REF_NAME} is a pre-release tag on ${default_branch}; a pre-release is tagged on a branch commit, and a release on ${default_branch} carries no suffix"
+            exit 1
+          fi
+          if [[ "${tag_version}" != *-* && "${on_main}" == false ]]
           then
-            echo "::error::${GITHUB_REF_NAME} is not a version tag; a release tag is v<major>.<minor>.<patch>, with an optional -<pre-release>"
+            echo "::error::${GITHUB_REF_NAME} is not on ${default_branch}; a release is tagged on ${default_branch}, and a branch commit takes a pre-release tag with a -<suffix>"
             exit 1
           fi
+          echo "✅ ${GITHUB_REF_NAME} is on the right side of ${default_branch} (on it: ${on_main})."
+
+      - name: tag-matches-version
+        run: |
+          set -o errexit -o nounset -o pipefail
+          tag_version=${GITHUB_REF_NAME#v}
+          base_version=${tag_version%%-*}
           file_version=$(cat .kit/version)
-          if [[ "${tag_version}" != "${file_version}" ]]
+          if [[ "${base_version}" != "${file_version}" ]]
           then
-            echo "::error::the tag says ${tag_version} and .kit/version says ${file_version}; set .kit/version on main first, then tag"
+            echo "::error::the tag says ${base_version} and .kit/version says ${file_version}; set .kit/version at the tagged commit first"
             exit 1
           fi
           echo "✅ .kit/version is ${file_version}."
@@ -63,6 +80,8 @@ jobs:
           mkdir "${staging}/kit-${version}"
           cp --recursive bin .kit "${staging}/kit-${version}/"
           rm --force "${staging}/kit-${version}/.kit/manifest"
+          # the packed kit carries the tag's full version, suffix included; the repository file carries the base
+          printf '%s\n' "${version}" > "${staging}/kit-${version}/.kit/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
           sha256sum "kit-${version}.tar.gz" > "kit-${version}.tar.gz.sha256"
           notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\nThen, in the repository: kit install\n' "${version}")
diff --git a/AGENTS.md b/AGENTS.md
index c6faa17..06f6e6c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,9 +6,9 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
 
 - The delivered tree is `.kit/` and `bin/kit`. Everything in it is written for a consumer: no file names a
   consumer, a person, or another repository as the source of a rule.
-- `.kit/version` is the release version. A release is a commit on `main` that sets it, then the tag `v<version>`
-  on that commit. The release workflow refuses a tag whose version differs from the file, or whose commit is not
-  on `main`.
+- `.kit/version` is the version under development, with no suffix. A release is the tag `v<version>` on a commit on
+  `main`. A pre-release is `v<version>-<suffix>` on a commit that is not on `main`. The release workflow refuses any
+  other pairing, and a tag whose base version differs from the file.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
   this repository's installed copies of its own kit. Change a delivered file at its source under `.kit/`, then
   run `just refresh` to rewrite the copies, and commit both.
diff --git a/README.md b/README.md
index a661029..2d2a4a6 100644
--- a/README.md
+++ b/README.md
@@ -61,8 +61,11 @@ request body is the report. A human merges.
 
 ## Release
 
-A release is two steps on `main`: a pull request that sets `.kit/version`, then the tag `v<version>` on its merge
-commit. The release workflow packs `bin/` and `.kit/` into `kit-<version>.tar.gz` and publishes the GitHub
-release. It refuses a tag that is not on `main` or whose version differs from the file.
+`.kit/version` carries the version under development, without a suffix. A release is the tag `v<version>` on a
+commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`, say `v0.1.0-rc.1`, on a commit that is
+not on `main`, and it is published as a GitHub pre-release. In both cases the workflow packs `bin/` and `.kit/` into
+`kit-<version>.tar.gz` with the tag's full version stamped into the packed `.kit/version`, and publishes the release.
+It refuses a tag that is not a version, a release tag off `main`, a pre-release tag on `main`, and a tag whose base
+version is not `.kit/version`.
 
 Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf

From f9304f5eec6f30dd6a2541317925409d53670936 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:24:12 -0700
Subject: [PATCH 012/108] #1 justfile, .kit/kit.just: no {{...}} interpolation;
 the path is an exported variable

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-just.md | 11 ++++++++---
 .kit/kit.just             |  5 ++++-
 .kit/manifest             |  6 +++---
 .kit/rules/just.md        | 11 ++++++++---
 justfile                  |  5 ++++-
 5 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
index 0958e80..8044078 100644
--- a/.claude/rules/kit-just.md
+++ b/.claude/rules/kit-just.md
@@ -15,16 +15,19 @@ applies to it as well.
    a description of what the file is and who imports it.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
    root, which has no parent), `set positional-arguments := true`, and `set export := true`.
-3. Every justfile carries the default-and-help pair:
+3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
+   # This file's own path, assigned at parse time so the body below needs no interpolation.
+   export <name>_justfile := source_file()
+
    # Default recipe: list this justfile's recipes.
    _: help
 
    # List recipes in this justfile.
    [no-exit-message]
    @help *options:
-     just --justfile "{{source_file()}}" --list
+     just --justfile "${<name>_justfile}" --list
    ```
 
 4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
@@ -38,7 +41,9 @@ applies to it as well.
    does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
 4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
-5. Recipe bodies use `${var}`, never `{{var}}` mixed in. `set export := true` makes parameters available.
+5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
+   variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
+   `${name}` and nothing else.
 6. Two-space indentation inside a body. Never a tab.
 7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
 8. Comments wrap at 118 columns. Bodies do not wrap.
diff --git a/.kit/kit.just b/.kit/kit.just
index ecb46dc..bc35653 100644
--- a/.kit/kit.just
+++ b/.kit/kit.just
@@ -15,13 +15,16 @@ set positional-arguments := true
 
 export BASH_ENV := source_directory() / "bash/1st.sh"
 
+# This file's own path, assigned at parse time so the body below needs no interpolation.
+export kit_justfile := source_file()
+
 # Default recipe: list this justfile's recipes.
 _: help
 
 # List recipes in this justfile.
 [no-exit-message]
 @help *options:
-  just --justfile "{{source_file()}}" --list
+  just --justfile "${kit_justfile}" --list
 
 set export := true
 
diff --git a/.kit/manifest b/.kit/manifest
index 51c397d..887c8f2 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -6,11 +6,11 @@ a36a18081eb7515871bc01b7b22372c1545d99d8b393fb386c78128f73c8dbb5  .kit/bash/1st.
 8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .kit/ci.yml
 1ab629cb79710438fb15fd2fcbadf94ce125f4d3c26bf22def6d35c8c414dbb1  .kit/hooks/pre-commit
 414bb9a82191060489213823e98828a64d166c53109c64cdf600fdd3d5c64205  .kit/hooks/pre-rebase
-47919ba1fabfc077ff3950f2743d94d016d58350cfe36cf97d2130419de6b6c6  .kit/kit.just
+b68c1bc8ba4a142f9a585b7fb58d833e5b3c0476fb629c7a45e67e8e6cb507fc  .kit/kit.just
 cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bash.md
 5c3667b1282bf6afe6cebc401e99faa2ba52e4a4873bbec9a6368a4623277f2d  .kit/rules/gitignore.md
 6ddb651356399b10dc33858cdf38fe111aa8803cde1d499135faa0e196f74f97  .kit/rules/json.md
-dd88591e25a0df6a039f5183f0e573e35c53b9903f04cc879b743a715f8e6559  .kit/rules/just.md
+26e6ddb46be1adeda8ea76d77112096771147821594a89cc14ff8dbf7148d939  .kit/rules/just.md
 df7388a40e037d82f77d92f0dfe0deed55184c4a8bf869dbce86986673ebeab5  .kit/rules/markdown.md
 52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
 617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .kit/settings.json
@@ -18,7 +18,7 @@ e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
 1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .claude/rules/kit-bash.md
 4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
 1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
-3547ea76e2711f003da90817292e48cec55926e95ae2a06dc53de0954ab38508  .claude/rules/kit-just.md
+96d16e8c1d3889909bbc13d6690b07a6d7c47aa2e7d62ff87f4cbc0068f385c7  .claude/rules/kit-just.md
 13fff95ff67775bebb820d10dbd73f4f5eb23571f0619462fa5abb1b8c6b42c6  .claude/rules/kit-markdown.md
 4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
 8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .github/workflows/kit-ci.yml
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index fe8b9a1..d47b1c7 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -9,16 +9,19 @@ applies to it as well.
    a description of what the file is and who imports it.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
    root, which has no parent), `set positional-arguments := true`, and `set export := true`.
-3. Every justfile carries the default-and-help pair:
+3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
+   # This file's own path, assigned at parse time so the body below needs no interpolation.
+   export <name>_justfile := source_file()
+
    # Default recipe: list this justfile's recipes.
    _: help
 
    # List recipes in this justfile.
    [no-exit-message]
    @help *options:
-     just --justfile "{{source_file()}}" --list
+     just --justfile "${<name>_justfile}" --list
    ```
 
 4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
@@ -32,7 +35,9 @@ applies to it as well.
    does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
 4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
-5. Recipe bodies use `${var}`, never `{{var}}` mixed in. `set export := true` makes parameters available.
+5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
+   variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
+   `${name}` and nothing else.
 6. Two-space indentation inside a body. Never a tab.
 7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
 8. Comments wrap at 118 columns. Bodies do not wrap.
diff --git a/justfile b/justfile
index 7b6b2d1..508e024 100644
--- a/justfile
+++ b/justfile
@@ -6,13 +6,16 @@
 set dotenv-load := true
 set positional-arguments := true
 
+# This file's own path, assigned at parse time so the body below needs no interpolation.
+export root_justfile := source_file()
+
 # Default recipe: list this justfile's recipes.
 _: help
 
 # List recipes in this justfile.
 [no-exit-message]
 @help *options:
-  just --justfile "{{source_file()}}" --list
+  just --justfile "${root_justfile}" --list
 
 set export := true
 

From d0dd43cc9d7ae6ee064a4771d162e6fb201bb75f Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 22:40:44 -0700
Subject: [PATCH 013/108] #1 bin/kit: a repository takes only the targets it
 names

A target is a harness that insists on files outside .kit/. kit install names them, the manifest records them, and update and check honor the same set. claude is the one target this release knows; kit target add and remove change the set later.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md    |  13 ++-
 .kit/manifest  |   5 +-
 README.md      |  15 +--
 bin/kit        | 277 +++++++++++++++++++++++++++++++++++++------------
 justfile       |   2 +-
 tests/kit.bats |  62 +++++++++--
 6 files changed, 289 insertions(+), 85 deletions(-)

diff --git a/.kit/1st.md b/.kit/1st.md
index e51c83d..bd476fd 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -51,7 +51,8 @@ A worker is whoever implements one issue in the worktree that issue names.
 ## Rules by file type
 
 Each file kind has a rule file under `.kit/rules/`. A harness that loads rules by path finds the same text
-under `.claude/rules/kit-<kind>.md`. Read the rule for a kind before writing a file of that kind.
+under its own rules directory when the repository takes that target, `.claude/rules/kit-<kind>.md` for Claude
+Code. Read the rule for a kind before writing a file of that kind.
 
 | Kind | Paths | Rule |
 | --- | --- | --- |
@@ -68,11 +69,15 @@ under `.claude/rules/kit-<kind>.md`. Read the rule for a kind before writing a f
   which gives `just kit issue`, `just kit tidy`, and `just kit status`. The bash behind them is `.kit/bash/`.
 - `.kit/hooks/pre-rebase` refuses a rebase of the default branch. `.kit/hooks/pre-commit` lints the staged
   paths. `kit install` sets `core.hooksPath` to `.kit/hooks`.
-- `.kit/settings.json`, deny rules for Claude Code that `kit install` merges into `.claude/settings.json`.
-  The kit owns only the entries it writes; the consumer may add its own.
+- Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the
+  targets it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
+  `.claude/rules/kit-<kind>.md` and merges `.kit/settings.json`, six deny rules, into `.claude/settings.json`.
+  The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
+  back out.
 - `.kit/ci.yml`, placed as `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
   runs `kit check`, and refuses a pull request not linked to an open issue.
-- `.kit/manifest`, written by `kit install`: the release version and a checksum per delivered file.
+- `.kit/manifest`, written by `kit install`: the release version, the targets taken, and a checksum per
+  delivered file.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/manifest b/.kit/manifest
index 887c8f2..2ee9056 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,5 +1,6 @@
 version 0.1.0
-367c3c2d28f51dbe2549803e113ad45db507aa68afc1997f3d5b20f94796ec6f  .kit/1st.md
+targets claude
+f2c1c377f15a35b03ffcbffc4122b36bf11409f83805087a06e3f06646d51f26  .kit/1st.md
 a36a18081eb7515871bc01b7b22372c1545d99d8b393fb386c78128f73c8dbb5  .kit/bash/1st.sh
 6944cdb161e68bf5d2355c6ee48fe7bfd25d8ffa1e6edef218af123e5edf5f7c  .kit/bash/gh.sh
 051cab217451a69c6f73545fe3e68fb2316e0be57004030159fe299d7f510436  .kit/bash/git.sh
@@ -15,10 +16,10 @@ df7388a40e037d82f77d92f0dfe0deed55184c4a8bf869dbce86986673ebeab5  .kit/rules/mar
 52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
 617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .kit/settings.json
 e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
+8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .github/workflows/kit-ci.yml
 1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .claude/rules/kit-bash.md
 4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
 1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
 96d16e8c1d3889909bbc13d6690b07a6d7c47aa2e7d62ff87f4cbc0068f385c7  .claude/rules/kit-just.md
 13fff95ff67775bebb820d10dbd73f4f5eb23571f0619462fa5abb1b8c6b42c6  .claude/rules/kit-markdown.md
 4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
-8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .github/workflows/kit-ci.yml
diff --git a/README.md b/README.md
index 2d2a4a6..7108db0 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ installs it with `kit install`, and keeps rules of its own beside it. The design
 
 ## Take the kit
 
-Pin a release in the repository's `mise.toml`, then install it:
+Pin a release in the repository's `mise.toml`, then install it, naming the harnesses the team uses:
 
 ```toml
 [tools]
@@ -17,12 +17,15 @@ Pin a release in the repository's `mise.toml`, then install it:
 
 ```sh
 mise install
-kit install
+kit install claude
 ```
 
-`kit install` copies `.kit/` into the repository, places `.claude/rules/kit-*.md` and
-`.github/workflows/kit-ci.yml`, merges its deny rules into `.claude/settings.json`, ignores `worktrees/`, points
-`core.hooksPath` at `.kit/hooks`, and writes `.kit/manifest`. Commit what it wrote. Then:
+`kit install` copies `.kit/` into the repository, places `.github/workflows/kit-ci.yml`, ignores `worktrees/`,
+points `core.hooksPath` at `.kit/hooks`, and writes `.kit/manifest`. Each target named adds what that harness
+insists on having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and merges the kit's deny rules into
+`.claude/settings.json`. A repository with no target installed still binds every agent that reads `AGENTS.md`,
+through the rules table in `.kit/1st.md`. `kit target add` and `kit target remove` change the set later, and
+`kit target list` prints it. Commit what it wrote. Then:
 
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
 - Add `mod kit ".kit/kit.just"` to the root justfile for `just kit issue`, `just kit tidy`, and `just kit status`.
@@ -46,7 +49,7 @@ git config user.signingkey <a key GitHub verifies for you>
 git config commit.gpgsign true
 ```
 
-Then `mise install` for the pinned tools, and `bin/kit install` is already done: this repository carries the
+Then `mise install` for the pinned tools. `bin/kit install claude` is already done: this repository carries the
 installed copy of its own kit, which `just ci` checks.
 
 ## Getting started
diff --git a/bin/kit b/bin/kit
index 4b6c59f..1f538ab 100755
--- a/bin/kit
+++ b/bin/kit
@@ -2,18 +2,26 @@
 # kit - install, update, and check the kit in a repository (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-#   kit install    copy this release into the repository and write .kit/manifest
-#   kit update     after the pin is bumped: replace unchanged files, three-way merge changed ones
-#   kit check      fail when a delivered file differs from this release
-#   kit version    print this release's version
+#   kit install [<target>…]     copy this release into the repository, place the files each named target needs,
+#                               and write .kit/manifest
+#   kit update                  after the pin is bumped: replace unchanged files, three-way merge changed ones
+#   kit check                   fail when a delivered file differs from this release
+#   kit target list             print the targets this repository takes
+#   kit target add <target>…    take a target: place its files and record it
+#   kit target remove <target>… drop a target: remove its files and the kit's entries from its settings
+#   kit version                 print this release's version
 #
-# KIT_BASE=<dir> names the previous release's root for \`kit update\` on a machine without mise.
+# A target is a harness that insists on files placed outside .kit/. The one this release knows is claude:
+# .claude/rules/kit-<kind>.md, each the rule file of that kind with a paths: header, and the kit's deny entries
+# merged into .claude/settings.json. A repository takes only the targets it names, and .kit/manifest records them
+# so update and check honor the same set.
+#
+# KIT_BASE=<dir> names the previous release's root for `kit update` on a machine without mise.
 #
 # The release this command belongs to is the directory above bin/: its .kit/ is the payload. The repository is
-# the git checkout the command runs in. A delivered file is one of: every file under .kit/, except manifest;
-# .claude/rules/kit-<kind>.md, each the rule file of that kind with a paths: header so a harness loads it by
-# path; and .github/workflows/kit-ci.yml, which is .kit/ci.yml placed where GitHub reads it. .claude/settings.json
-# is shared with the repository, so it is merged by key: the kit owns only the deny entries it writes.
+# the git checkout the command runs in. A delivered file is every file under .kit/ except manifest, the CI
+# workflow .kit/ci.yml placed as .github/workflows/kit-ci.yml, and the placed files of each target taken.
+# A shared settings file is merged by key: the kit owns only the entries it writes.
 #
 # see: .kit/1st.md
 
@@ -24,8 +32,10 @@ payload="${kit_root}/.kit"
 # shellcheck source=.kit/bash/1st.sh
 source "${payload}/bash/1st.sh"
 
+known_targets=(claude)
+
 usage() {
-  sed -n '5,8p' "${BASH_SOURCE[0]}" | sed 's/^# *//' >&2
+  sed -n '5,12p' "${BASH_SOURCE[0]}" | sed 's/^#//; s/^ //' >&2
 }
 
 # digest prints the sha256 of stdin, by whichever tool the machine carries.
@@ -38,6 +48,33 @@ digest() {
   fi
 }
 
+# known-target <name> is true when this release knows the target.
+known-target() {
+  local t
+  for t in "${known_targets[@]}"
+  do
+    [[ "$1" == "${t}" ]] && return 0
+  done
+  return 1
+}
+
+# require-targets <name>… refuses an unknown target, naming the known ones.
+require-targets() {
+  local t
+  for t in "$@"
+  do
+    if ! known-target "${t}"
+    then
+      error "'${t}' is not a target this release knows; the targets are: ${known_targets[*]}"
+      return 2
+    fi
+  done
+}
+
+# manifest-version and manifest-targets read .kit/manifest.
+manifest-version() { sed -n 's/^version //p' .kit/manifest; }
+manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
+
 # rule-paths <kind> prints the paths: globs a harness loads the rule of <kind> for, one per line.
 rule-paths() {
   case "$1" in
@@ -51,19 +88,39 @@ rule-paths() {
   esac
 }
 
-# delivered-paths <payload> prints every repository path the release at <payload> delivers.
-delivered-paths() {
+# target-paths <payload> <target> prints the repository paths a target places.
+target-paths() {
   local root=$1 file
+  case "$2" in
+    (claude)
+      for file in "${root}"/rules/*.md
+      do
+        printf '.claude/rules/kit-%s\n' "$(basename "${file}")"
+      done
+  esac
+}
+
+# target-settings <target> prints the settings file a target shares with the repository, or nothing.
+target-settings() {
+  case "$1" in
+    (claude) printf '.claude/settings.json\n'
+  esac
+}
+
+# delivered-paths <payload> [<target>…] prints every repository path the release delivers for those targets.
+delivered-paths() {
+  local root=$1 file t
+  shift
   while IFS= read -r file
   do
     [[ "${file}" == manifest ]] && continue
     printf '.kit/%s\n' "${file}"
   done < <(cd "${root}" && find . -type f | sed 's@^\./@@' | sort)
-  for file in "${root}"/rules/*.md
+  printf '.github/workflows/kit-ci.yml\n'
+  for t in "$@"
   do
-    printf '.claude/rules/kit-%s\n' "$(basename "${file}")"
+    target-paths "${root}" "${t}"
   done
-  printf '.github/workflows/kit-ci.yml\n'
 }
 
 # expected <payload> <path> prints the content the release at <payload> delivers at repository <path>.
@@ -102,19 +159,21 @@ write-expected() {
   return 0
 }
 
-# merge-settings <new-payload> [<base-payload>] merges the deny entries into .claude/settings.json: the base
-# release's entries go, the new release's come, and everything else in the file stays as it was.
+# merge-settings <target> <new-payload> [<base-payload>] merges the kit's deny entries into the target's settings
+# file: the base release's entries go, the new release's come, and everything else in the file stays. An empty
+# <new-payload> takes the kit's entries out and adds none.
 merge-settings() {
-  local new_root=$1 base_root=${2:-} base_deny='[]'
-  [[ -n "${base_root}" && -f "${base_root}/settings.json" ]] && base_deny=$(jq '.permissions.deny // []' "${base_root}/settings.json")
-  mkdir -p .claude
-  [[ -f .claude/settings.json ]] || printf '{}\n' > .claude/settings.json
-  jq --indent 2 \
-    --argjson base "${base_deny}" \
-    --argjson new "$(jq '.permissions.deny // []' "${new_root}/settings.json")" \
+  local file new_deny='[]' base_deny='[]'
+  file=$(target-settings "$1")
+  [[ -n "${file}" ]] || return 0
+  [[ -n "$2" && -f "$2/settings.json" ]] && new_deny=$(jq '.permissions.deny // []' "$2/settings.json")
+  [[ -n "${3:-}" && -f "$3/settings.json" ]] && base_deny=$(jq '.permissions.deny // []' "$3/settings.json")
+  mkdir -p "$(dirname "${file}")"
+  [[ -f "${file}" ]] || printf '{}\n' > "${file}"
+  jq --indent 2 --argjson base "${base_deny}" --argjson new "${new_deny}" \
     '.permissions.deny = (((.permissions.deny // []) - $base) as $kept | $kept + ($new - $kept))' \
-    .claude/settings.json > .claude/settings.json.kit-new
-  mv .claude/settings.json.kit-new .claude/settings.json
+    "${file}" > "${file}.kit-new"
+  mv "${file}.kit-new" "${file}"
 }
 
 # ensure-ignored makes sure worktrees/ is ignored at the root, the way the loop needs.
@@ -128,45 +187,51 @@ ensure-ignored() {
   printf '%s# the per-issue worktrees of the loop; see: .kit/1st.md\n/worktrees/\n' "${separator}" >> .gitignore
 }
 
-# write-manifest records the release version and, per delivered path, the digest of the release's own content
-# for it, never of the file as written: a later update tells an untouched file from an edited one by comparing
-# the file to this, so a merge that kept a repository's edit is not mistaken for the release's text.
+# write-manifest [<target>…] records the release version, the targets taken, and, per delivered path, the
+# digest of the release's own content for it, never of the file as written: a later update tells an untouched
+# file from an edited one by comparing the file to this, so a merge that kept a repository's edit is not mistaken
+# for the release's text.
 write-manifest() {
   local path
   {
     printf 'version %s\n' "$(cat "${payload}/version")"
+    printf 'targets%s\n' "${*:+ $*}"
     while IFS= read -r path
     do
       printf '%s  %s\n' "$(expected "${payload}" "${path}" | digest)" "${path}"
-    done < <(delivered-paths "${payload}")
+    done < <(delivered-paths "${payload}" "$@")
   } > .kit/manifest
 }
 
 # finish sets the clone's hooks path and reports.
 finish() {
   git config core.hooksPath .kit/hooks
-  ok "kit $(cat "${payload}/version") is installed: core.hooksPath is .kit/hooks, and .kit/manifest is written."
+  ok "kit $(cat "${payload}/version") is installed, targets: ${*:-none}. core.hooksPath is .kit/hooks, and .kit/manifest is written."
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
 
 cmd-install() {
   guard:require tool:jq tool:git
+  require-targets "$@"
   if [[ -f .kit/manifest ]]
   then
-    error "run: kit update (this repository already carries kit $(sed -n 's/^version //p' .kit/manifest))"
+    error "run: kit update (this repository already carries kit $(manifest-version))"
     return 1
   fi
-  section "kit install $(cat "${payload}/version")"
-  local path
+  section "kit install $(cat "${payload}/version")${*:+, targets: $*}"
+  local path t
   while IFS= read -r path
   do
     step "${path}"
     write-expected "${payload}" "${path}"
-  done < <(delivered-paths "${payload}")
-  merge-settings "${payload}"
+  done < <(delivered-paths "${payload}" "$@")
+  for t in "$@"
+  do
+    merge-settings "${t}" "${payload}"
+  done
   ensure-ignored
-  write-manifest
-  finish
+  write-manifest "$@"
+  finish "$@"
 }
 
 cmd-update() {
@@ -176,10 +241,12 @@ cmd-update() {
     error "run: kit install (this repository carries no .kit/manifest)"
     return 1
   fi
-  local previous current base_root="" path recorded actual conflicts=0
-  previous=$(sed -n 's/^version //p' .kit/manifest)
+  local previous current base_root="" path recorded actual conflicts=0 t
+  local -a targets
+  read -r -a targets <<<"$(manifest-targets)"
+  previous=$(manifest-version)
   current=$(cat "${payload}/version")
-  section "kit update ${previous} → ${current}"
+  section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
 
   # The previous release is the base of every three-way merge. KIT_BASE names its root directly; otherwise
   # mise keeps it where it installed it.
@@ -227,27 +294,32 @@ cmd-update() {
       conflicts=$(( conflicts + 1 ))
     fi
     rm -f "${path}.kit-base" "${path}.kit-new"
-  done < <(delivered-paths "${payload}")
+  done < <(delivered-paths "${payload}" "${targets[@]}")
 
-  merge-settings "${payload}" "${base_root}"
+  for t in "${targets[@]}"
+  do
+    merge-settings "${t}" "${payload}" "${base_root}"
+  done
   ensure-ignored
-  write-manifest
+  write-manifest "${targets[@]}"
   if (( conflicts > 0 ))
   then
     error "${conflicts} file(s) need a hand; see above."
     return 1
   fi
-  finish
+  finish "${targets[@]}"
 }
 
 cmd-check() {
-  local path findings=0 version
+  local path findings=0 version t file
+  local -a targets
   if [[ ! -f .kit/manifest ]]
   then
     error "run: kit install (this repository carries no .kit/manifest)"
     return 1
   fi
-  version=$(sed -n 's/^version //p' .kit/manifest)
+  read -r -a targets <<<"$(manifest-targets)"
+  version=$(manifest-version)
   if [[ "${version}" != "$(cat "${payload}/version")" ]]
   then
     error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${payload}/version"); run: kit update"
@@ -264,33 +336,110 @@ cmd-check() {
       error "${path} differs from the pinned release"
       findings=$(( findings + 1 ))
     fi
-  done < <(delivered-paths "${payload}")
-  if [[ ! -f .claude/settings.json ]]
-  then
-    error ".claude/settings.json is missing; run: kit update"
-    findings=$(( findings + 1 ))
-  elif ! command -v jq >/dev/null 2>&1
-  then
-    error "run: mise install (jq is not on PATH, so .claude/settings.json could not be read)"
-    findings=$(( findings + 1 ))
-  elif (( $(jq --argjson new "$(jq '.permissions.deny // []' "${payload}/settings.json")" \
-      '($new - (.permissions.deny // [])) | length' .claude/settings.json) > 0 ))
-  then
-    error ".claude/settings.json is missing a deny entry the kit writes; run: kit update"
-    findings=$(( findings + 1 ))
-  fi
+  done < <(delivered-paths "${payload}" "${targets[@]}")
+  for t in "${targets[@]}"
+  do
+    file=$(target-settings "${t}")
+    [[ -n "${file}" ]] || continue
+    if [[ ! -f "${file}" ]]
+    then
+      error "${file} is missing; run: kit update"
+      findings=$(( findings + 1 ))
+    elif ! command -v jq >/dev/null 2>&1
+    then
+      error "run: mise install (jq is not on PATH, so ${file} could not be read)"
+      findings=$(( findings + 1 ))
+    elif (( $(jq --argjson new "$(jq '.permissions.deny // []' "${payload}/settings.json")" \
+        '($new - (.permissions.deny // [])) | length' "${file}") > 0 ))
+    then
+      error "${file} is missing a deny entry the kit writes; run: kit update"
+      findings=$(( findings + 1 ))
+    fi
+  done
   if (( findings > 0 ))
   then
     error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
     return 1
   fi
-  ok "kit ${version}: every delivered file matches the pinned release."
+  ok "kit ${version}, targets ${targets[*]:-none}: every delivered file matches the pinned release."
+}
+
+cmd-target() {
+  local verb=${1:-list} t path
+  local -a targets kept
+  shift || true
+  if [[ ! -f .kit/manifest ]]
+  then
+    error "run: kit install (this repository carries no .kit/manifest)"
+    return 1
+  fi
+  read -r -a targets <<<"$(manifest-targets)"
+  case "${verb}" in
+    (list)
+      printf '%s\n' "${targets[@]}"
+      ;;
+    (add)
+      (( $# > 0 )) || { error "usage: kit target add <target>…"; return 2; }
+      guard:require tool:jq tool:git
+      require-targets "$@"
+      for t in "$@"
+      do
+        if [[ " ${targets[*]} " == *" ${t} "* ]]
+        then
+          step "${t}: already taken"
+          continue
+        fi
+        section "kit target add ${t}"
+        while IFS= read -r path
+        do
+          step "${path}"
+          write-expected "${payload}" "${path}"
+        done < <(target-paths "${payload}" "${t}")
+        merge-settings "${t}" "${payload}"
+        targets+=("${t}")
+      done
+      write-manifest "${targets[@]}"
+      ok "targets: ${targets[*]}"
+      ;;
+    (remove)
+      (( $# > 0 )) || { error "usage: kit target remove <target>…"; return 2; }
+      guard:require tool:jq tool:git
+      require-targets "$@"
+      for t in "$@"
+      do
+        if [[ " ${targets[*]} " != *" ${t} "* ]]
+        then
+          step "${t}: not taken"
+          continue
+        fi
+        section "kit target remove ${t}"
+        while IFS= read -r path
+        do
+          step "removing ${path}"
+          rm -f "${path}"
+        done < <(target-paths "${payload}" "${t}")
+        [[ -f "$(target-settings "${t}")" ]] && merge-settings "${t}" "" "${payload}"
+        kept=()
+        for path in "${targets[@]}"
+        do
+          [[ "${path}" == "${t}" ]] || kept+=("${path}")
+        done
+        targets=("${kept[@]+"${kept[@]}"}")
+      done
+      write-manifest "${targets[@]+"${targets[@]}"}"
+      ok "targets: ${targets[*]:-none}"
+      ;;
+    (*)
+      error "kit target: unknown verb '${verb}' (list, add, remove)"
+      return 2
+  esac
 }
 
 case "${1:-}" in
-  (install) cmd-install ;;
+  (install) shift; cmd-install "$@" ;;
   (update)  cmd-update ;;
   (check)   cmd-check ;;
+  (target)  shift; cmd-target "$@" ;;
   (version) cat "${payload}/version" ;;
   (-h | --help | help | "") usage; [[ -n "${1:-}" ]] ;;
   (*)
diff --git a/justfile b/justfile
index 508e024..3b378f2 100644
--- a/justfile
+++ b/justfile
@@ -48,6 +48,6 @@ refresh:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
   rm -f .kit/manifest .claude/settings.json
-  bin/kit install
+  bin/kit install claude
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 3da2a8f..7b47795 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -25,8 +25,8 @@ later-release() {
   printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/.kit/rules/json.md"
 }
 
-@test "install writes the delivered tree, the mirrors, the workflow, the settings, and the manifest" {
-  run "${kit_checkout}/bin/kit" install
+@test "install with the claude target writes the tree, the mirrors, the workflow, the settings, and the manifest" {
+  run "${kit_checkout}/bin/kit" install claude
   [ "$status" -eq 0 ]
   [ -f .kit/1st.md ]
   [ -x .kit/hooks/pre-commit ]
@@ -37,13 +37,59 @@ later-release() {
   jq --exit-status '.permissions.deny | index("Bash(git push --force *)")' .claude/settings.json >/dev/null
   grep --quiet --line-regexp '/worktrees/' .gitignore
   grep --quiet '^version 0.1.0$' .kit/manifest
+  grep --quiet '^targets claude$' .kit/manifest
   [ "$(git config core.hooksPath)" = ".kit/hooks" ]
 }
 
-@test "install keeps the repository's own settings keys and deny entries" {
+@test "install with no target writes the neutral tree and nothing under .claude" {
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ -f .kit/1st.md ]
+  [ -f .github/workflows/kit-ci.yml ]
+  [ ! -e .claude ]
+  grep --quiet '^targets$' .kit/manifest
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  # a stray file under a target not taken is nobody's business
+  mkdir -p .claude/rules && printf 'theirs\n' > .claude/rules/kit-json.md
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+}
+
+@test "install refuses a target this release does not know and names the known ones" {
+  run "${kit_checkout}/bin/kit" install gemini
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"the targets are: claude"* ]]
+  [ ! -e .kit/manifest ]
+}
+
+@test "target add places a target's files, and target remove takes them and the kit's entries back out" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
   "${kit_checkout}/bin/kit" install
+  [ "$("${kit_checkout}/bin/kit" target list)" = "" ]
+  run "${kit_checkout}/bin/kit" target add claude
+  [ "$status" -eq 0 ]
+  [ "$("${kit_checkout}/bin/kit" target list)" = "claude" ]
+  [ -f .claude/rules/kit-bash.md ]
+  jq --exit-status '.permissions.deny | index("Bash(git switch main *)")' .claude/settings.json >/dev/null
+  grep --quiet '^targets claude$' .kit/manifest
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  run "${kit_checkout}/bin/kit" target remove claude
+  [ "$status" -eq 0 ]
+  [ ! -e .claude/rules/kit-bash.md ]
+  [ "$(jq --raw-output .model .claude/settings.json)" = "x" ]
+  jq --exit-status '.permissions.deny == ["Bash(rm -rf /)"]' .claude/settings.json >/dev/null
+  grep --quiet '^targets$' .kit/manifest
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+}
+
+@test "install keeps the repository's own settings keys and deny entries" {
+  mkdir .claude
+  printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
+  "${kit_checkout}/bin/kit" install claude
   [ "$(jq --raw-output .model .claude/settings.json)" = "x" ]
   jq --exit-status '.permissions.deny | index("Bash(rm -rf /)")' .claude/settings.json >/dev/null
   jq --exit-status '.permissions.deny | index("Bash(git switch main *)")' .claude/settings.json >/dev/null
@@ -57,7 +103,7 @@ later-release() {
 }
 
 @test "check passes after install and fails on a drifted, a missing, and a lost deny entry" {
-  "${kit_checkout}/bin/kit" install
+  "${kit_checkout}/bin/kit" install claude
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   printf 'edited\n' >> .kit/rules/yaml.md
@@ -78,7 +124,7 @@ later-release() {
 }
 
 @test "update replaces unchanged files, merges an edited one, and records the release's digests" {
-  "${kit_checkout}/bin/kit" install
+  "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
   # a consumer edit to a file the later release also changes, on a different line
   sed -i.bak '1s/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
@@ -100,7 +146,7 @@ later-release() {
 }
 
 @test "update of an untouched install leaves check green" {
-  "${kit_checkout}/bin/kit" install
+  "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 0 ]
@@ -110,7 +156,7 @@ later-release() {
 }
 
 @test "update leaves conflict markers and fails when the same lines changed" {
-  "${kit_checkout}/bin/kit" install
+  "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
   printf '9.9.9\n' > "${repo}.later/.kit/version"
   sed -i.bak '1s/^# JSON$/# JSON (theirs)/' "${repo}.later/.kit/rules/json.md" && rm "${repo}.later/.kit/rules/json.md.bak"
@@ -123,7 +169,7 @@ later-release() {
 }
 
 @test "update without the base release refuses an edited file and names the base" {
-  "${kit_checkout}/bin/kit" install
+  "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
   printf 'edited\n' >> .kit/rules/bash.md
   # a mise that answers nothing, ahead of the real one

From bfdf43e79e27469680f2ccf3e9e634519c3f9b82 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:03:08 -0700
Subject: [PATCH 014/108] #1 README.md: a link for a signing key, a pasteable
 setup, and the loop as a list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 7108db0..bee69b9 100644
--- a/README.md
+++ b/README.md
@@ -41,26 +41,32 @@ The kit needs bash 4 or later, git, `gh`, and `jq`. macOS ships bash 3.2; `brew
 
 ## Setup
 
-Every commit is signed, and the branch ruleset refuses one that is not. Once per clone:
+Every commit is signed, and the branch ruleset refuses one that is not. If you have no signing key GitHub
+verifies, make one and register it, following [generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
+and [adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account).
+Then, once per clone, with the key's id in `signing_key`:
 
 ```sh
 git config gpg.format openpgp
-git config user.signingkey <a key GitHub verifies for you>
+git config user.signingkey "${signing_key}"
 git config commit.gpgsign true
+mise install
 ```
 
-Then `mise install` for the pinned tools. `bin/kit install claude` is already done: this repository carries the
-installed copy of its own kit, which `just ci` checks.
+This repository carries the installed copy of its own kit, and `just ci` checks it.
 
 ## Getting started
 
-Work here moves by the loop in [.kit/1st.md](.kit/1st.md). An issue exists. `just kit issue <N>` makes
-`worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a draft pull request. Commits
-are signed, and their subject is `#<N> <area>: <subject>`. `gh pr ready` says the work is done, and the pull
-request body is the report. A human merges.
+Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
-`just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
-`bin/kit check`.
+- An issue exists. A change without an issue has not started.
+- `just kit issue <N>` makes `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a
+  draft pull request. It never switches the checkout it runs from.
+- Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`.
+- `just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
+  `bin/kit check`.
+- `gh pr ready` says the work is done, and the pull request body is the report.
+- A human merges. `just kit tidy` then removes the worktree and its branch.
 
 ## Release
 

From 9d6854ef79acdb8d006baafac5a4a500de223c8c Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:03:54 -0700
Subject: [PATCH 015/108] #1 .kit/rules/markdown.md: snippets take a shell
 variable, and a prerequisite gets its link

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-markdown.md | 6 ++++++
 .kit/manifest                 | 4 ++--
 .kit/rules/markdown.md        | 6 ++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
index 43d822f..b0b3b80 100644
--- a/.claude/rules/kit-markdown.md
+++ b/.claude/rules/kit-markdown.md
@@ -18,6 +18,12 @@ Applies to `*.md`.
 8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
    when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
 
+## Snippets
+
+1. A value the reader supplies is a shell variable the prose names, `"${signing_key}"`, never an angle-bracket
+   placeholder, so the block pastes after one export.
+2. Where a reader may lack a prerequisite, link the page that creates it beside the command that uses it.
+
 ## Layout
 
 1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
diff --git a/.kit/manifest b/.kit/manifest
index 2ee9056..78c2c4e 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -12,7 +12,7 @@ cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bas
 5c3667b1282bf6afe6cebc401e99faa2ba52e4a4873bbec9a6368a4623277f2d  .kit/rules/gitignore.md
 6ddb651356399b10dc33858cdf38fe111aa8803cde1d499135faa0e196f74f97  .kit/rules/json.md
 26e6ddb46be1adeda8ea76d77112096771147821594a89cc14ff8dbf7148d939  .kit/rules/just.md
-df7388a40e037d82f77d92f0dfe0deed55184c4a8bf869dbce86986673ebeab5  .kit/rules/markdown.md
+b65054b62fc294525a5448bca8ac6bfe8be2d1aab0a74495c16b0f229104c2e7  .kit/rules/markdown.md
 52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
 617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .kit/settings.json
 e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
@@ -21,5 +21,5 @@ e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
 4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
 1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
 96d16e8c1d3889909bbc13d6690b07a6d7c47aa2e7d62ff87f4cbc0068f385c7  .claude/rules/kit-just.md
-13fff95ff67775bebb820d10dbd73f4f5eb23571f0619462fa5abb1b8c6b42c6  .claude/rules/kit-markdown.md
+b10e9ddcd41ca3fea52b0233f94e26437bd6977b4c64b8461e63599d9bd7faaf  .claude/rules/kit-markdown.md
 4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index 8f8da0e..996f6ff 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -14,6 +14,12 @@ Applies to `*.md`.
 8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
    when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
 
+## Snippets
+
+1. A value the reader supplies is a shell variable the prose names, `"${signing_key}"`, never an angle-bracket
+   placeholder, so the block pastes after one export.
+2. Where a reader may lack a prerequisite, link the page that creates it beside the command that uses it.
+
 ## Layout
 
 1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns

From c77adfed69d74e3d9552021497e701f03b43c981 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:07:21 -0700
Subject: [PATCH 016/108] #1 .kit/1st.md: a rule lives in the repository, never
 in a session's memory

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-markdown.md | 7 +++++--
 .kit/1st.md                   | 2 ++
 .kit/manifest                 | 6 +++---
 .kit/rules/markdown.md        | 7 +++++--
 4 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
index b0b3b80..53c613f 100644
--- a/.claude/rules/kit-markdown.md
+++ b/.claude/rules/kit-markdown.md
@@ -10,7 +10,8 @@ Applies to `*.md`.
 
 1. Write plain declarative sentences with the thing under discussion as the subject.
 2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
-3. Use a list where the content is a list. Use a table where the content has columns.
+3. Use a list where the content is a list, and for a procedure or a loop, so it scans. Use a table where the
+   content has columns.
 4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
 5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
 6. Use the serial comma in every list of three or more.
@@ -46,4 +47,6 @@ Applies to `*.md`.
 
 1. Name an index file `1st.md`. It lists its siblings and says what each is for.
 2. A file says what its subject is in its first paragraph, before how to use it.
-3. No file names another repository as the source of a rule.
+3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
+   what the repository is.
+4. No file names another repository as the source of a rule.
diff --git a/.kit/1st.md b/.kit/1st.md
index bd476fd..b401ebb 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -10,6 +10,8 @@ the repository's own rules in `AGENTS.md` bind beside it. Where the two differ,
    clears no gate and earns no credit.
 3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
 4. Being wrong is recoverable. Misreporting is not.
+5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
+   written into a rule file or `AGENTS.md` through the loop, where every agent and every person reads it.
 
 ## `main` is the human's desk
 
diff --git a/.kit/manifest b/.kit/manifest
index 78c2c4e..89fb15c 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,6 +1,6 @@
 version 0.1.0
 targets claude
-f2c1c377f15a35b03ffcbffc4122b36bf11409f83805087a06e3f06646d51f26  .kit/1st.md
+9f794eb95cdbcaf5a938a1444b705a44d539bf998535396c1798d028afb77435  .kit/1st.md
 a36a18081eb7515871bc01b7b22372c1545d99d8b393fb386c78128f73c8dbb5  .kit/bash/1st.sh
 6944cdb161e68bf5d2355c6ee48fe7bfd25d8ffa1e6edef218af123e5edf5f7c  .kit/bash/gh.sh
 051cab217451a69c6f73545fe3e68fb2316e0be57004030159fe299d7f510436  .kit/bash/git.sh
@@ -12,7 +12,7 @@ cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bas
 5c3667b1282bf6afe6cebc401e99faa2ba52e4a4873bbec9a6368a4623277f2d  .kit/rules/gitignore.md
 6ddb651356399b10dc33858cdf38fe111aa8803cde1d499135faa0e196f74f97  .kit/rules/json.md
 26e6ddb46be1adeda8ea76d77112096771147821594a89cc14ff8dbf7148d939  .kit/rules/just.md
-b65054b62fc294525a5448bca8ac6bfe8be2d1aab0a74495c16b0f229104c2e7  .kit/rules/markdown.md
+5e4ee708d4be30009de264ddf5a18df1d1257faee8ba18ca8fd703c1eb6e8a85  .kit/rules/markdown.md
 52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
 617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .kit/settings.json
 e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
@@ -21,5 +21,5 @@ e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
 4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
 1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
 96d16e8c1d3889909bbc13d6690b07a6d7c47aa2e7d62ff87f4cbc0068f385c7  .claude/rules/kit-just.md
-b10e9ddcd41ca3fea52b0233f94e26437bd6977b4c64b8461e63599d9bd7faaf  .claude/rules/kit-markdown.md
+a495ae7a54188bb82b73d50925012f9611af58396fa82c72c71d8a337c1bccf6  .claude/rules/kit-markdown.md
 4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index 996f6ff..ce54df8 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -6,7 +6,8 @@ Applies to `*.md`.
 
 1. Write plain declarative sentences with the thing under discussion as the subject.
 2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
-3. Use a list where the content is a list. Use a table where the content has columns.
+3. Use a list where the content is a list, and for a procedure or a loop, so it scans. Use a table where the
+   content has columns.
 4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
 5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
 6. Use the serial comma in every list of three or more.
@@ -42,4 +43,6 @@ Applies to `*.md`.
 
 1. Name an index file `1st.md`. It lists its siblings and says what each is for.
 2. A file says what its subject is in its first paragraph, before how to use it.
-3. No file names another repository as the source of a rule.
+3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
+   what the repository is.
+4. No file names another repository as the source of a rule.

From 8fc7cfd9ca334178917faa97c3cbd1c612b28dae Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:22:28 -0700
Subject: [PATCH 017/108] #1 bin/kit: the repository carries the text, the
 release the machinery

kit install copies .kit/1st.md and .kit/rules/ and writes the manifest; the bash and the hooks stay in the installed release, reached through kit issue, kit tidy, kit status, and core.hooksPath, which kit setup wires per clone. .kit/kit.just is gone; a root justfile adds veneers, as this one does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-just.md    |  2 +-
 .github/workflows/kit-ci.yml |  2 +-
 .kit/1st.md                  | 29 +++++++--------
 .kit/bash/1st.sh             |  2 +-
 .kit/bash/gh.sh              |  9 ++---
 .kit/ci.yml                  |  2 +-
 .kit/kit.just                | 70 ------------------------------------
 .kit/manifest                | 17 +++------
 .kit/rules/just.md           |  2 +-
 README.md                    | 26 ++++++++------
 bin/kit                      | 69 +++++++++++++++++++++++++----------
 justfile                     | 31 ++++++++++++++--
 tests/kit.bats               | 16 +++++++--
 tests/release.bats           |  2 ++
 14 files changed, 139 insertions(+), 140 deletions(-)
 delete mode 100644 .kit/kit.just

diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
index 8044078..9505c0c 100644
--- a/.claude/rules/kit-just.md
+++ b/.claude/rules/kit-just.md
@@ -50,6 +50,6 @@ applies to it as well.
 
 ## Invocation
 
-1. The idiom is the space form, `just kit issue 42`, never `just kit/issue` and never `kit::issue` outside a
+1. The idiom is the space form, `just tools check`, never `just tools/check` and never `tools::check` outside a
    dependency list.
 2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index dd0e5f0..d72042d 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -80,7 +80,7 @@ jobs:
           2. pick one or more open issues
           3. [re-run this check](${run}): linking fires no event, so it does not re-run on its own
 
-          \`just kit issue <N>\` makes this link when it starts the work.
+          \`kit issue <N>\` makes this link when it starts the work.
           REMEDY
           )
 
diff --git a/.kit/1st.md b/.kit/1st.md
index b401ebb..5f99747 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -22,8 +22,8 @@ worktree under `worktrees/`, one per issue, and reaches `main` only through a me
 ## The loop
 
 1. An issue exists. A change without an issue has not started.
-2. `just kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a
-   draft pull request. It never switches the checkout it is run from.
+2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
+   pull request. It never switches the checkout it is run from.
 3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`.
 4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
    and how, and what was left out and why.
@@ -41,7 +41,7 @@ A worker is whoever implements one issue in the worktree that issue names.
 
 1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints `<N>-`.
 2. Do every command from there. Never touch the repository root checkout.
-3. Never run `just kit issue`, make a branch, or make a worktree. Those were done before the handoff.
+3. Never run `kit issue`, make a branch, or make a worktree. Those were done before the handoff.
 4. Implement what the issue asks and nothing beside it.
 5. Push as you go.
 6. Run the repository's gate before calling anything done, and run it through the pinned toolchain.
@@ -67,19 +67,20 @@ Code. Read the rule for a kind before writing a file of that kind.
 
 ## What the kit carries
 
-- `.kit/kit.just`, a just module. The consumer's root justfile takes it with `mod kit ".kit/kit.just"`,
-  which gives `just kit issue`, `just kit tidy`, and `just kit status`. The bash behind them is `.kit/bash/`.
-- `.kit/hooks/pre-rebase` refuses a rebase of the default branch. `.kit/hooks/pre-commit` lints the staged
-  paths. `kit install` sets `core.hooksPath` to `.kit/hooks`.
-- Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the
-  targets it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
-  `.claude/rules/kit-<kind>.md` and merges `.kit/settings.json`, six deny rules, into `.claude/settings.json`.
-  The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
-  back out.
+The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
+release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
+carries the machinery, reached through the `kit` command on `PATH`:
+
+- `kit issue`, `kit tidy`, and `kit status`, the loop's commands. A root justfile that wants `just issue 42` adds
+  a veneer recipe over `kit issue`.
+- Two hooks. `pre-rebase` refuses a rebase of the default branch. `pre-commit` lints the staged paths. `kit install`
+  points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
+- Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
+  it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
+  `.claude/rules/kit-<kind>.md` and merges six deny rules into `.claude/settings.json`. The kit owns only the
+  entries it writes; the repository may add its own. `kit target remove` takes a target back out.
 - `.kit/ci.yml`, placed as `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
   runs `kit check`, and refuses a pull request not linked to an open issue.
-- `.kit/manifest`, written by `kit install`: the release version, the targets taken, and a checksum per
-  delivered file.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/bash/1st.sh b/.kit/bash/1st.sh
index 89d94e8..40299dc 100644
--- a/.kit/bash/1st.sh
+++ b/.kit/bash/1st.sh
@@ -2,7 +2,7 @@
 # 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Sourced into every recipe body of .kit/kit.just through BASH_ENV, and by bin/kit and the hooks that need a
+# Sourced by bin/kit, whose issue, tidy, and status run the bash under .kit/bash/, and by the hooks that need a
 # verb. It defines functions only and sets no shell option, so the caller's options stand. A module under
 # .kit/bash/ is loaded on first use with `use <module>`, and each exported function has a stub here so a
 # caller never has to load it by hand.
diff --git a/.kit/bash/gh.sh b/.kit/bash/gh.sh
index c0e8f49..2367961 100644
--- a/.kit/bash/gh.sh
+++ b/.kit/bash/gh.sh
@@ -25,7 +25,7 @@ gh:issue() {
   then
     if [[ ! -t 0 ]]
     then
-      error "usage: just kit issue <issue-number> [<issue-number>…]"
+      error "usage: kit issue <issue-number> [<issue-number>…]"
       return 2
     fi
     guard:require gh || return 1
@@ -143,7 +143,7 @@ gh:issue() {
     wt="${main_root}/worktrees/${branch}"
     if [[ -e "${wt}" ]]
     then
-      error "${wt} exists but is not a worktree of ${branch}; remove it (or run: just kit tidy) and re-run."
+      error "${wt} exists but is not a worktree of ${branch}; remove it (or run: kit tidy) and re-run."
       return 2
     fi
     step "Creating worktree ${wt}"
@@ -156,9 +156,10 @@ gh:issue() {
     fi
   fi
 
-  if [[ "$(git config core.hooksPath 2>/dev/null)" != .kit/hooks ]]
+  # shellcheck disable=SC2154  # kit_bash_dir is set by the loader, 1st.sh, which sources this file
+  if [[ "$(git config core.hooksPath 2>/dev/null)" != "$(cd "${kit_bash_dir}/.." && pwd)/hooks" ]]
   then
-    warn "run: kit install (core.hooksPath is not .kit/hooks, so the desk guard is off in this clone)"
+    warn "run: kit setup (core.hooksPath does not name this release's hooks, so the desk guard is off in this clone)"
   fi
 
   # GitHub cannot open a pull request on a branch with nothing to compare, so the first commit is an empty one.
diff --git a/.kit/ci.yml b/.kit/ci.yml
index dd0e5f0..d72042d 100644
--- a/.kit/ci.yml
+++ b/.kit/ci.yml
@@ -80,7 +80,7 @@ jobs:
           2. pick one or more open issues
           3. [re-run this check](${run}): linking fires no event, so it does not re-run on its own
 
-          \`just kit issue <N>\` makes this link when it starts the work.
+          \`kit issue <N>\` makes this link when it starts the work.
           REMEDY
           )
 
diff --git a/.kit/kit.just b/.kit/kit.just
deleted file mode 100644
index bc35653..0000000
--- a/.kit/kit.just
+++ /dev/null
@@ -1,70 +0,0 @@
-# kit.just - see: https://just.systems/man/en/
-# ----------------------------------------------------------------------------------------------------------------------
-# The kit's just module. A consumer's root justfile takes it with `mod kit ".kit/kit.just"`, which gives
-# `just kit issue`, `just kit tidy`, and `just kit status`. Each recipe carries [no-cd] so its body runs
-# from the checkout it was invoked in, and the bash behind each lives in .kit/bash/, loaded through BASH_ENV.
-#
-# A root justfile that wants the bare spelling adds its own veneer:
-#
-#   issue *numbers:
-#     just kit issue "$@"
-
-set dotenv-load := true
-set fallback := true
-set positional-arguments := true
-
-export BASH_ENV := source_directory() / "bash/1st.sh"
-
-# This file's own path, assigned at parse time so the body below needs no interpolation.
-export kit_justfile := source_file()
-
-# Default recipe: list this justfile's recipes.
-_: help
-
-# List recipes in this justfile.
-[no-exit-message]
-@help *options:
-  just --justfile "${kit_justfile}" --list
-
-set export := true
-
-# Start, or return to, work on an issue: a branch linked to it under Development, a worktree at
-# worktrees/<N>-<slug>, a start commit, and a draft pull request. Further numbers are secondary issues the
-# pull request closes. Safe to re-run; it never switches the checkout it runs from.
-#
-#   just kit issue 42        # start #42
-#   just kit issue 42 43     # start #42, and close #43 with it
-#   just kit issue           # ask for a title, create the issue, and start it (needs a terminal)
-[doc("🌿 Start or resume an issue: linked branch, worktree, start commit, draft pull request")]
-[no-cd]
-issue *numbers:
-  #!/usr/bin/env bash
-  set -o errexit -o nounset -o pipefail
-  gh:issue "$@"
-
-# Sweep the checkout back to pristine: remove worktrees whose pull request is merged or closed, prune the
-# bookkeeping, and delete local branches whose upstream is gone. The default branch, a dirty worktree, and the
-# worktree this runs in are never touched.
-#
-#   just kit tidy            # sweep
-#   just kit tidy --dry-run  # say what a sweep would do
-[doc("🧹 Remove merged worktrees and gone branches")]
-[no-cd]
-tidy *flags:
-  #!/usr/bin/env bash
-  set -o errexit -o nounset -o pipefail
-  git:tidy "$@"
-
-# Show the main checkout and every worktree under worktrees/: branch, pull request, and dirty or clean. Reads
-# only.
-#
-#   just kit status            # fetch --prune, then render
-#   just kit status --no-fetch # render from the current remote-tracking refs
-[doc("📊 Show every worktree with its branch, pull request, and state")]
-[no-cd]
-status *flags:
-  #!/usr/bin/env bash
-  set -o errexit -o nounset -o pipefail
-  git:status "$@"
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/manifest b/.kit/manifest
index 89fb15c..1aa0c6e 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,25 +1,16 @@
 version 0.1.0
 targets claude
-9f794eb95cdbcaf5a938a1444b705a44d539bf998535396c1798d028afb77435  .kit/1st.md
-a36a18081eb7515871bc01b7b22372c1545d99d8b393fb386c78128f73c8dbb5  .kit/bash/1st.sh
-6944cdb161e68bf5d2355c6ee48fe7bfd25d8ffa1e6edef218af123e5edf5f7c  .kit/bash/gh.sh
-051cab217451a69c6f73545fe3e68fb2316e0be57004030159fe299d7f510436  .kit/bash/git.sh
-8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .kit/ci.yml
-1ab629cb79710438fb15fd2fcbadf94ce125f4d3c26bf22def6d35c8c414dbb1  .kit/hooks/pre-commit
-414bb9a82191060489213823e98828a64d166c53109c64cdf600fdd3d5c64205  .kit/hooks/pre-rebase
-b68c1bc8ba4a142f9a585b7fb58d833e5b3c0476fb629c7a45e67e8e6cb507fc  .kit/kit.just
+46949c8976de559ef2d07573a2924a44d29a814980e5e8de1e84f275030b67bd  .kit/1st.md
 cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bash.md
 5c3667b1282bf6afe6cebc401e99faa2ba52e4a4873bbec9a6368a4623277f2d  .kit/rules/gitignore.md
 6ddb651356399b10dc33858cdf38fe111aa8803cde1d499135faa0e196f74f97  .kit/rules/json.md
-26e6ddb46be1adeda8ea76d77112096771147821594a89cc14ff8dbf7148d939  .kit/rules/just.md
+84943496f3c31932bd0eeb84a7c0b6f83a69b877f38435fbcf9dedd02e723a5e  .kit/rules/just.md
 5e4ee708d4be30009de264ddf5a18df1d1257faee8ba18ca8fd703c1eb6e8a85  .kit/rules/markdown.md
 52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
-617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .kit/settings.json
-e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67  .kit/version
-8f05739376491c844a1ee63303a421a0bb87169d0544462a9f9f3ab735d7f7ef  .github/workflows/kit-ci.yml
+75318ea548c175eeffcdedb521ac41061baab6ea3bedf3f85fcaa06ad8f61b6f  .github/workflows/kit-ci.yml
 1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .claude/rules/kit-bash.md
 4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
 1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
-96d16e8c1d3889909bbc13d6690b07a6d7c47aa2e7d62ff87f4cbc0068f385c7  .claude/rules/kit-just.md
+a79bd22a451fb8b1d118f0921c3b3e1bf2bef8ff0ae496891227e22353b98e44  .claude/rules/kit-just.md
 a495ae7a54188bb82b73d50925012f9611af58396fa82c72c71d8a337c1bccf6  .claude/rules/kit-markdown.md
 4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index d47b1c7..5ce5ec2 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -44,6 +44,6 @@ applies to it as well.
 
 ## Invocation
 
-1. The idiom is the space form, `just kit issue 42`, never `just kit/issue` and never `kit::issue` outside a
+1. The idiom is the space form, `just tools check`, never `just tools/check` and never `tools::check` outside a
    dependency list.
 2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/README.md b/README.md
index bee69b9..7bd82da 100644
--- a/README.md
+++ b/README.md
@@ -20,17 +20,22 @@ mise install
 kit install claude
 ```
 
-`kit install` copies `.kit/` into the repository, places `.github/workflows/kit-ci.yml`, ignores `worktrees/`,
-points `core.hooksPath` at `.kit/hooks`, and writes `.kit/manifest`. Each target named adds what that harness
-insists on having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and merges the kit's deny rules into
-`.claude/settings.json`. A repository with no target installed still binds every agent that reads `AGENTS.md`,
-through the rules table in `.kit/1st.md`. `kit target add` and `kit target remove` change the set later, and
-`kit target list` prints it. Commit what it wrote. Then:
+`kit install` copies `.kit/1st.md` and `.kit/rules/` into the repository, places `.github/workflows/kit-ci.yml`,
+ignores `worktrees/`, points this clone's `core.hooksPath` at the release's hooks, and writes `.kit/manifest`. Each
+target named adds what that harness insists on having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and
+merges the kit's deny rules into `.claude/settings.json`. A repository with no target installed still binds every
+agent that reads `AGENTS.md`, through the rules table in `.kit/1st.md`. `kit target add` and `kit target remove`
+change the set later, and `kit target list` prints it. Commit what it wrote. Then:
 
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
-- Add `mod kit ".kit/kit.just"` to the root justfile for `just kit issue`, `just kit tidy`, and `just kit status`.
 - Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
   request not linked to an open issue.
+- For `just issue 42`, add a veneer recipe over `kit issue` to the root justfile; `kit issue 42` works as it is.
+- In every other clone, run `kit setup` once to wire the hooks.
+
+The machinery, the `kit` command, the bash behind `kit issue`, `kit tidy`, and `kit status`, and the hooks, stays
+in the release where mise installed it; the repository carries the text an agent reads and the record of what it
+took.
 
 To move to a new release, bump the pin, run `mise install`, then `kit update`: a delivered file you left alone is
 replaced, one you edited is three-way merged with the previous release as the base, and your own deny entries
@@ -51,6 +56,7 @@ git config gpg.format openpgp
 git config user.signingkey "${signing_key}"
 git config commit.gpgsign true
 mise install
+bin/kit setup
 ```
 
 This repository carries the installed copy of its own kit, and `just ci` checks it.
@@ -60,13 +66,13 @@ This repository carries the installed copy of its own kit, and `just ci` checks
 Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 - An issue exists. A change without an issue has not started.
-- `just kit issue <N>` makes `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a
-  draft pull request. It never switches the checkout it runs from.
+- `just issue <N>`, a veneer over `kit issue`, makes `worktrees/<N>-<slug>`, links the branch to the issue under
+  Development, and opens a draft pull request. It never switches the checkout it runs from.
 - Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`.
 - `just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
   `bin/kit check`.
 - `gh pr ready` says the work is done, and the pull request body is the report.
-- A human merges. `just kit tidy` then removes the worktree and its branch.
+- A human merges. `just tidy` then removes the worktree and its branch.
 
 ## Release
 
diff --git a/bin/kit b/bin/kit
index 1f538ab..5fab173 100755
--- a/bin/kit
+++ b/bin/kit
@@ -2,27 +2,32 @@
 # kit - install, update, and check the kit in a repository (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-#   kit install [<target>…]     copy this release into the repository, place the files each named target needs,
-#                               and write .kit/manifest
+#   kit install [<target>…]     copy this release's text into the repository, place the files each named target
+#                               needs, wire this clone's hooks, and write .kit/manifest
 #   kit update                  after the pin is bumped: replace unchanged files, three-way merge changed ones
 #   kit check                   fail when a delivered file differs from this release
+#   kit setup                   wire this clone: core.hooksPath to this release's hooks
 #   kit target list             print the targets this repository takes
 #   kit target add <target>…    take a target: place its files and record it
 #   kit target remove <target>… drop a target: remove its files and the kit's entries from its settings
+#   kit issue [<number>…]       start or resume an issue: linked branch, worktree, start commit, draft pull request
+#   kit tidy [--dry-run]        remove worktrees whose pull request is merged or closed, and gone branches
+#   kit status [--no-fetch]     show every worktree with its branch, pull request, and state
 #   kit version                 print this release's version
 #
+# The repository carries the text an agent reads, .kit/1st.md and .kit/rules/, the CI workflow .kit/ci.yml placed
+# as .github/workflows/kit-ci.yml, the placed files of each target taken, and .kit/manifest, which records the
+# release version, the targets, and a digest per delivered path. The machinery stays in the release where mise
+# installed it: this command, the bash behind issue, tidy, and status, and the hooks, which a clone reaches through
+# core.hooksPath.
+#
 # A target is a harness that insists on files placed outside .kit/. The one this release knows is claude:
 # .claude/rules/kit-<kind>.md, each the rule file of that kind with a paths: header, and the kit's deny entries
-# merged into .claude/settings.json. A repository takes only the targets it names, and .kit/manifest records them
-# so update and check honor the same set.
+# merged into .claude/settings.json. A repository takes only the targets it names. A shared settings file is
+# merged by key: the kit owns only the entries it writes.
 #
 # KIT_BASE=<dir> names the previous release's root for `kit update` on a machine without mise.
 #
-# The release this command belongs to is the directory above bin/: its .kit/ is the payload. The repository is
-# the git checkout the command runs in. A delivered file is every file under .kit/ except manifest, the CI
-# workflow .kit/ci.yml placed as .github/workflows/kit-ci.yml, and the placed files of each target taken.
-# A shared settings file is merged by key: the kit owns only the entries it writes.
-#
 # see: .kit/1st.md
 
 set -o errexit -o nounset -o pipefail
@@ -35,7 +40,7 @@ source "${payload}/bash/1st.sh"
 known_targets=(claude)
 
 usage() {
-  sed -n '5,12p' "${BASH_SOURCE[0]}" | sed 's/^#//; s/^ //' >&2
+  sed -n '5,16p' "${BASH_SOURCE[0]}" | sed 's/^#//; s/^ //' >&2
 }
 
 # digest prints the sha256 of stdin, by whichever tool the machine carries.
@@ -111,11 +116,11 @@ target-settings() {
 delivered-paths() {
   local root=$1 file t
   shift
-  while IFS= read -r file
+  printf '.kit/1st.md\n'
+  for file in "${root}"/rules/*.md
   do
-    [[ "${file}" == manifest ]] && continue
-    printf '.kit/%s\n' "${file}"
-  done < <(cd "${root}" && find . -type f | sed 's@^\./@@' | sort)
+    printf '.kit/rules/%s\n' "$(basename "${file}")"
+  done
   printf '.github/workflows/kit-ci.yml\n'
   for t in "$@"
   do
@@ -155,8 +160,6 @@ write-expected() {
   mkdir -p "$(dirname "$2")"
   expected "$1" "$2" > "$2.kit-new"
   mv "$2.kit-new" "$2"
-  [[ "$2" == .kit/hooks/* ]] && chmod +x "$2"
-  return 0
 }
 
 # merge-settings <target> <new-payload> [<base-payload>] merges the kit's deny entries into the target's settings
@@ -203,13 +206,39 @@ write-manifest() {
   } > .kit/manifest
 }
 
-# finish sets the clone's hooks path and reports.
+# wire-hooks points this clone's core.hooksPath at the release's hooks.
+wire-hooks() {
+  git config core.hooksPath "${payload}/hooks"
+}
+
+# finish wires the clone and reports.
 finish() {
-  git config core.hooksPath .kit/hooks
-  ok "kit $(cat "${payload}/version") is installed, targets: ${*:-none}. core.hooksPath is .kit/hooks, and .kit/manifest is written."
+  wire-hooks
+  ok "kit $(cat "${payload}/version") is installed, targets: ${*:-none}. core.hooksPath is ${payload}/hooks, and .kit/manifest is written."
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
 
+cmd-setup() {
+  guard:require tool:git
+  wire-hooks
+  ok "core.hooksPath is ${payload}/hooks"
+  if [[ -z "$(git config user.signingkey 2>/dev/null)" ]]
+  then
+    warn "no signing key is configured in this clone, and the ruleset refuses an unsigned commit; see README.md § Setup"
+  fi
+}
+
+# cmd-loop <verb> <args>… runs one of the loop's commands from the release's bash.
+cmd-loop() {
+  local verb=$1
+  shift
+  case "${verb}" in
+    (issue)  gh:issue "$@" ;;
+    (tidy)   git:tidy "$@" ;;
+    (status) git:status "$@" ;;
+  esac
+}
+
 cmd-install() {
   guard:require tool:jq tool:git
   require-targets "$@"
@@ -439,7 +468,9 @@ case "${1:-}" in
   (install) shift; cmd-install "$@" ;;
   (update)  cmd-update ;;
   (check)   cmd-check ;;
+  (setup)   cmd-setup ;;
   (target)  shift; cmd-target "$@" ;;
+  (issue | tidy | status) cmd-loop "$@" ;;
   (version) cat "${payload}/version" ;;
   (-h | --help | help | "") usage; [[ -n "${1:-}" ]] ;;
   (*)
diff --git a/justfile b/justfile
index 3b378f2..145d2c4 100644
--- a/justfile
+++ b/justfile
@@ -1,7 +1,8 @@
 #!/usr/bin/env just --justfile
 # justfile - see: https://just.systems/man/en/
 # ----------------------------------------------------------------------------------------------------------------------
-# The root justfile: the kit's own module, taken the way a consumer takes it, and the gate.
+# The root justfile: the loop's three commands as veneers over bin/kit, the way a consumer adds them over the kit
+# on its PATH, the gate, and the refresh of this repository's own installed copy.
 
 set dotenv-load := true
 set positional-arguments := true
@@ -19,8 +20,32 @@ _: help
 
 set export := true
 
-[doc("📁 The kit's recipes: issue, tidy, status (invoke as `just kit <recipe>`)")]
-mod kit ".kit/kit.just"
+# The loop's three commands, each a veneer over bin/kit. A consumer that wants the same spelling writes the same
+# three recipes over the `kit` on its PATH.
+#
+#   just issue 42        # start #42
+#   just issue 42 43     # start #42, and close #43 with it
+[doc("🌿 Start or resume an issue: linked branch, worktree, start commit, draft pull request")]
+issue *numbers:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  bin/kit issue "$@"
+
+#   just tidy            # sweep
+#   just tidy --dry-run  # say what a sweep would do
+[doc("🧹 Remove merged worktrees and gone branches")]
+tidy *flags:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  bin/kit tidy "$@"
+
+#   just status            # fetch --prune, then render
+#   just status --no-fetch # render from the current remote-tracking refs
+[doc("📊 Show every worktree with its branch, pull request, and state")]
+status *flags:
+  #!/usr/bin/env bash
+  set -o errexit -o nounset -o pipefail
+  bin/kit status "$@"
 
 # The gate a pull request passes: shellcheck over every bash file, actionlint over every workflow, the bats
 # suite over bin/kit, and bin/kit check over this repository's installed copy of its own kit. Every tool comes
diff --git a/tests/kit.bats b/tests/kit.bats
index 7b47795..15da482 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -29,7 +29,10 @@ later-release() {
   run "${kit_checkout}/bin/kit" install claude
   [ "$status" -eq 0 ]
   [ -f .kit/1st.md ]
-  [ -x .kit/hooks/pre-commit ]
+  [ -f .kit/rules/bash.md ]
+  [ ! -e .kit/bash ]
+  [ ! -e .kit/hooks ]
+  [ ! -e .kit/ci.yml ]
   [ -f .claude/rules/kit-markdown.md ]
   head -n 1 .claude/rules/kit-bash.md | grep --quiet --line-regexp -- '---'
   grep --quiet '"\*\*/\*\.sh"' .claude/rules/kit-bash.md
@@ -38,7 +41,16 @@ later-release() {
   grep --quiet --line-regexp '/worktrees/' .gitignore
   grep --quiet '^version 0.1.0$' .kit/manifest
   grep --quiet '^targets claude$' .kit/manifest
-  [ "$(git config core.hooksPath)" = ".kit/hooks" ]
+  [ "$(git config core.hooksPath)" = "${kit_checkout}/.kit/hooks" ]
+}
+
+@test "setup wires a clone's hooks to the release, and issue without a terminal prints usage" {
+  run "${kit_checkout}/bin/kit" setup
+  [ "$status" -eq 0 ]
+  [ "$(git config core.hooksPath)" = "${kit_checkout}/.kit/hooks" ]
+  run "${kit_checkout}/bin/kit" issue
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"usage: kit issue"* ]]
 }
 
 @test "install with no target writes the neutral tree and nothing under .claude" {
diff --git a/tests/release.bats b/tests/release.bats
index e5a0494..64935df 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -29,6 +29,8 @@ teardown() {
   [ "$status" -eq 0 ]
   run "${work}/unpacked/kit-${version}/bin/kit" check
   [ "$status" -eq 0 ]
+  [ "$(git config core.hooksPath)" = "${work}/unpacked/kit-${version}/.kit/hooks" ]
+  [ ! -e .kit/bash ]
   [ "$("${work}/unpacked/kit-${version}/bin/kit" version)" = "${version}" ]
 }
 

From 88b6b1065cc9e10d81c1c28f268af4b7e7462cda Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:34:55 -0700
Subject: [PATCH 018/108] #1 README.md: a Maintaining section, and the placed
 copies say so

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md      |  2 ++
 .claude/rules/kit-gitignore.md |  2 ++
 .claude/rules/kit-json.md      |  2 ++
 .claude/rules/kit-just.md      |  2 ++
 .claude/rules/kit-markdown.md  |  2 ++
 .claude/rules/kit-yaml.md      |  2 ++
 .kit/manifest                  | 13 +++++++------
 AGENTS.md                      |  4 ++--
 README.md                      | 18 ++++++++++++++++++
 bin/kit                        |  6 +++++-
 10 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
index dbecf1c..339d791 100644
--- a/.claude/rules/kit-bash.md
+++ b/.claude/rules/kit-bash.md
@@ -1,4 +1,6 @@
 ---
+# Placed by kit install from the release's rules/bash.md, and held to it by kit check. A delivered file is
+# changed by pinning a new release and running kit update, never in place.
 paths:
   - "**/*.sh"
   - "**/*.bash"
diff --git a/.claude/rules/kit-gitignore.md b/.claude/rules/kit-gitignore.md
index 41b87e4..a9ab4e1 100644
--- a/.claude/rules/kit-gitignore.md
+++ b/.claude/rules/kit-gitignore.md
@@ -1,4 +1,6 @@
 ---
+# Placed by kit install from the release's rules/gitignore.md, and held to it by kit check. A delivered file is
+# changed by pinning a new release and running kit update, never in place.
 paths:
   - ".gitignore"
   - "**/.gitignore"
diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
index 9d0859d..390b0c9 100644
--- a/.claude/rules/kit-json.md
+++ b/.claude/rules/kit-json.md
@@ -1,4 +1,6 @@
 ---
+# Placed by kit install from the release's rules/json.md, and held to it by kit check. A delivered file is
+# changed by pinning a new release and running kit update, never in place.
 paths:
   - "**/*.json"
   - "**/*.jsonc"
diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
index 9505c0c..41ffc35 100644
--- a/.claude/rules/kit-just.md
+++ b/.claude/rules/kit-just.md
@@ -1,4 +1,6 @@
 ---
+# Placed by kit install from the release's rules/just.md, and held to it by kit check. A delivered file is
+# changed by pinning a new release and running kit update, never in place.
 paths:
   - "justfile"
   - "**/justfile"
diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
index 53c613f..8609837 100644
--- a/.claude/rules/kit-markdown.md
+++ b/.claude/rules/kit-markdown.md
@@ -1,4 +1,6 @@
 ---
+# Placed by kit install from the release's rules/markdown.md, and held to it by kit check. A delivered file is
+# changed by pinning a new release and running kit update, never in place.
 paths:
   - "**/*.md"
 ---
diff --git a/.claude/rules/kit-yaml.md b/.claude/rules/kit-yaml.md
index 69fe17c..8948004 100644
--- a/.claude/rules/kit-yaml.md
+++ b/.claude/rules/kit-yaml.md
@@ -1,4 +1,6 @@
 ---
+# Placed by kit install from the release's rules/yaml.md, and held to it by kit check. A delivered file is
+# changed by pinning a new release and running kit update, never in place.
 paths:
   - "**/*.yml"
   - "**/*.yaml"
diff --git a/.kit/manifest b/.kit/manifest
index 1aa0c6e..569d275 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,3 +1,4 @@
+# .kit/manifest - written by kit install, update, and target; never edited by hand
 version 0.1.0
 targets claude
 46949c8976de559ef2d07573a2924a44d29a814980e5e8de1e84f275030b67bd  .kit/1st.md
@@ -8,9 +9,9 @@ cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bas
 5e4ee708d4be30009de264ddf5a18df1d1257faee8ba18ca8fd703c1eb6e8a85  .kit/rules/markdown.md
 52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
 75318ea548c175eeffcdedb521ac41061baab6ea3bedf3f85fcaa06ad8f61b6f  .github/workflows/kit-ci.yml
-1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .claude/rules/kit-bash.md
-4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .claude/rules/kit-gitignore.md
-1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .claude/rules/kit-json.md
-a79bd22a451fb8b1d118f0921c3b3e1bf2bef8ff0ae496891227e22353b98e44  .claude/rules/kit-just.md
-a495ae7a54188bb82b73d50925012f9611af58396fa82c72c71d8a337c1bccf6  .claude/rules/kit-markdown.md
-4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .claude/rules/kit-yaml.md
+1b174f1aa06216c0fb7f8956097b46e2ffd83645d08858b084055d79a6ac4dee  .claude/rules/kit-bash.md
+c458cb28cf792ff71196c42ce9f7ed53f089fcfe3fe434481750651c2feaf27c  .claude/rules/kit-gitignore.md
+e62643c3beef3ebbe9c762a469b9d1250cea32519ade0b600a1911e2a65ae2d0  .claude/rules/kit-json.md
+370c3a2fc4c36435969fb2c9c79f6bb472832f3e50edea9b0edd27f819365433  .claude/rules/kit-just.md
+00b26e882f08950b432b475a0e23e17a24638447e7b2e2b74ce4671bd528b2f0  .claude/rules/kit-markdown.md
+44aaf9ecd3caa8dd7ce975c89842322e5efba14ead64550bc8b314382a6f7b71  .claude/rules/kit-yaml.md
diff --git a/AGENTS.md b/AGENTS.md
index 06f6e6c..557c911 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,6 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
   `main`. A pre-release is `v<version>-<suffix>` on a commit that is not on `main`. The release workflow refuses any
   other pairing, and a tag whose base version differs from the file.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
-  this repository's installed copies of its own kit. Change a delivered file at its source under `.kit/`, then
-  run `just refresh` to rewrite the copies, and commit both.
+  this repository's installed copies of its own kit, written by `just refresh` from the source under `.kit/`; see
+  [README.md](README.md) § Maintaining. Edit the source, run `just refresh`, and commit both.
 - `just ci` is the gate: shellcheck, actionlint, the bats suite, and `bin/kit check`.
diff --git a/README.md b/README.md
index 7bd82da..dbeefe6 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,24 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 - `gh pr ready` says the work is done, and the pull request body is the report.
 - A human merges. `just tidy` then removes the worktree and its branch.
 
+## Maintaining
+
+This repository is both the source of the kit and a consumer of it, so some committed files are written by
+`bin/kit install` from others and are not edited by hand:
+
+| Installed copy | Written from |
+| --- | --- |
+| `.claude/rules/kit-<kind>.md` | `.kit/rules/<kind>.md`, with the `paths:` header the `claude` target adds |
+| `.claude/settings.json` | `.kit/settings.json`, merged by key; here it carries only the kit's entries |
+| `.github/workflows/kit-ci.yml` | `.kit/ci.yml` |
+| `.kit/manifest` | the release version, the targets taken, and a digest per delivered path |
+
+Everything else is source, all of `.kit/` included: `1st.md`, `rules/`, `bash/`, `hooks/`, `ci.yml`,
+`settings.json`, and `version`, together with `bin/kit`, the two workflows, and `tests/`. After changing a source
+file under `.kit/`, run `just refresh`, which reinstalls the kit into this repository, and commit the result with
+the change. `bin/kit check`, which `just ci` runs, names any installed copy that no longer matches its source. The
+copies that can carry a comment say they are placed; `settings.json` cannot, so this table is its notice.
+
 ## Release
 
 `.kit/version` carries the version under development, without a suffix. A release is the tag `v<version>` on a
diff --git a/bin/kit b/bin/kit
index 5fab173..034d2e7 100755
--- a/bin/kit
+++ b/bin/kit
@@ -138,7 +138,10 @@ expected() {
     (.claude/rules/kit-*.md)
       kind=${path#.claude/rules/kit-}
       kind=${kind%.md}
-      printf -- '---\npaths:\n'
+      printf -- '---\n'
+      printf '# Placed by kit install from the release'"'"'s rules/%s.md, and held to it by kit check. A delivered file is\n' "${kind}"
+      printf '# changed by pinning a new release and running kit update, never in place.\n'
+      printf 'paths:\n'
       while IFS= read -r glob
       do
         printf '  - "%s"\n' "${glob}"
@@ -197,6 +200,7 @@ ensure-ignored() {
 write-manifest() {
   local path
   {
+    printf '# .kit/manifest - written by kit install, update, and target; never edited by hand\n'
     printf 'version %s\n' "$(cat "${payload}/version")"
     printf 'targets%s\n' "${*:+ $*}"
     while IFS= read -r path

From 3229eb7762f0fb3f99bf703a6472cdbcd74dd40d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:47:55 -0700
Subject: [PATCH 019/108] #1 .kit/rules: each rule names its own paths; the
 placed notice is one line

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md      |  3 +--
 .claude/rules/kit-gitignore.md |  3 +--
 .claude/rules/kit-json.md      |  3 +--
 .claude/rules/kit-just.md      |  3 +--
 .claude/rules/kit-markdown.md  |  3 +--
 .claude/rules/kit-yaml.md      |  3 +--
 .kit/1st.md                    |  7 ++++---
 .kit/manifest                  | 28 ++++++++++++++--------------
 .kit/rules/bash.md             |  6 ++++++
 .kit/rules/gitignore.md        |  5 +++++
 .kit/rules/json.md             |  5 +++++
 .kit/rules/just.md             |  6 ++++++
 .kit/rules/markdown.md         |  4 ++++
 .kit/rules/yaml.md             |  5 +++++
 README.md                      |  2 +-
 bin/kit                        | 32 ++++++--------------------------
 16 files changed, 62 insertions(+), 56 deletions(-)

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
index 339d791..3925045 100644
--- a/.claude/rules/kit-bash.md
+++ b/.claude/rules/kit-bash.md
@@ -1,6 +1,5 @@
 ---
-# Placed by kit install from the release's rules/bash.md, and held to it by kit check. A delivered file is
-# changed by pinning a new release and running kit update, never in place.
+# Placed by kit install from .kit/rules/bash.md, not edited by hand.
 paths:
   - "**/*.sh"
   - "**/*.bash"
diff --git a/.claude/rules/kit-gitignore.md b/.claude/rules/kit-gitignore.md
index a9ab4e1..564abb7 100644
--- a/.claude/rules/kit-gitignore.md
+++ b/.claude/rules/kit-gitignore.md
@@ -1,6 +1,5 @@
 ---
-# Placed by kit install from the release's rules/gitignore.md, and held to it by kit check. A delivered file is
-# changed by pinning a new release and running kit update, never in place.
+# Placed by kit install from .kit/rules/gitignore.md, not edited by hand.
 paths:
   - ".gitignore"
   - "**/.gitignore"
diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
index 390b0c9..2bfa91d 100644
--- a/.claude/rules/kit-json.md
+++ b/.claude/rules/kit-json.md
@@ -1,6 +1,5 @@
 ---
-# Placed by kit install from the release's rules/json.md, and held to it by kit check. A delivered file is
-# changed by pinning a new release and running kit update, never in place.
+# Placed by kit install from .kit/rules/json.md, not edited by hand.
 paths:
   - "**/*.json"
   - "**/*.jsonc"
diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
index 41ffc35..b2873d8 100644
--- a/.claude/rules/kit-just.md
+++ b/.claude/rules/kit-just.md
@@ -1,6 +1,5 @@
 ---
-# Placed by kit install from the release's rules/just.md, and held to it by kit check. A delivered file is
-# changed by pinning a new release and running kit update, never in place.
+# Placed by kit install from .kit/rules/just.md, not edited by hand.
 paths:
   - "justfile"
   - "**/justfile"
diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
index 8609837..acd24ed 100644
--- a/.claude/rules/kit-markdown.md
+++ b/.claude/rules/kit-markdown.md
@@ -1,6 +1,5 @@
 ---
-# Placed by kit install from the release's rules/markdown.md, and held to it by kit check. A delivered file is
-# changed by pinning a new release and running kit update, never in place.
+# Placed by kit install from .kit/rules/markdown.md, not edited by hand.
 paths:
   - "**/*.md"
 ---
diff --git a/.claude/rules/kit-yaml.md b/.claude/rules/kit-yaml.md
index 8948004..006d844 100644
--- a/.claude/rules/kit-yaml.md
+++ b/.claude/rules/kit-yaml.md
@@ -1,6 +1,5 @@
 ---
-# Placed by kit install from the release's rules/yaml.md, and held to it by kit check. A delivered file is
-# changed by pinning a new release and running kit update, never in place.
+# Placed by kit install from .kit/rules/yaml.md, not edited by hand.
 paths:
   - "**/*.yml"
   - "**/*.yaml"
diff --git a/.kit/1st.md b/.kit/1st.md
index 5f99747..f32f7a4 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -52,9 +52,10 @@ A worker is whoever implements one issue in the worktree that issue names.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`. A harness that loads rules by path finds the same text
-under its own rules directory when the repository takes that target, `.claude/rules/kit-<kind>.md` for Claude
-Code. Read the rule for a kind before writing a file of that kind.
+Each file kind has a rule file under `.kit/rules/`, and each rule file names the paths it binds in its `paths:`
+header. A harness that loads rules by path finds a copy under its own rules directory when the repository takes
+that target, `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of
+that kind.
 
 | Kind | Paths | Rule |
 | --- | --- | --- |
diff --git a/.kit/manifest b/.kit/manifest
index 569d275..895dffc 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,17 +1,17 @@
-# .kit/manifest - written by kit install, update, and target; never edited by hand
+# .kit/manifest - written by kit, not by hand
 version 0.1.0
 targets claude
-46949c8976de559ef2d07573a2924a44d29a814980e5e8de1e84f275030b67bd  .kit/1st.md
-cb95242d5caeee5651433a7ed8fad571bbca45f2f07a07cf4feb1f7371867402  .kit/rules/bash.md
-5c3667b1282bf6afe6cebc401e99faa2ba52e4a4873bbec9a6368a4623277f2d  .kit/rules/gitignore.md
-6ddb651356399b10dc33858cdf38fe111aa8803cde1d499135faa0e196f74f97  .kit/rules/json.md
-84943496f3c31932bd0eeb84a7c0b6f83a69b877f38435fbcf9dedd02e723a5e  .kit/rules/just.md
-5e4ee708d4be30009de264ddf5a18df1d1257faee8ba18ca8fd703c1eb6e8a85  .kit/rules/markdown.md
-52c854d31381d85c01ffd5cdb10ba1dfd8081ad80ff1a8108cf42b5e77d42bc8  .kit/rules/yaml.md
+700cd37d14cf16d80adf4a96c1ef1037f0956d513d39e0682903625ecec4e32d  .kit/1st.md
+1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .kit/rules/bash.md
+4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .kit/rules/gitignore.md
+1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .kit/rules/json.md
+a79bd22a451fb8b1d118f0921c3b3e1bf2bef8ff0ae496891227e22353b98e44  .kit/rules/just.md
+a495ae7a54188bb82b73d50925012f9611af58396fa82c72c71d8a337c1bccf6  .kit/rules/markdown.md
+4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .kit/rules/yaml.md
 75318ea548c175eeffcdedb521ac41061baab6ea3bedf3f85fcaa06ad8f61b6f  .github/workflows/kit-ci.yml
-1b174f1aa06216c0fb7f8956097b46e2ffd83645d08858b084055d79a6ac4dee  .claude/rules/kit-bash.md
-c458cb28cf792ff71196c42ce9f7ed53f089fcfe3fe434481750651c2feaf27c  .claude/rules/kit-gitignore.md
-e62643c3beef3ebbe9c762a469b9d1250cea32519ade0b600a1911e2a65ae2d0  .claude/rules/kit-json.md
-370c3a2fc4c36435969fb2c9c79f6bb472832f3e50edea9b0edd27f819365433  .claude/rules/kit-just.md
-00b26e882f08950b432b475a0e23e17a24638447e7b2e2b74ce4671bd528b2f0  .claude/rules/kit-markdown.md
-44aaf9ecd3caa8dd7ce975c89842322e5efba14ead64550bc8b314382a6f7b71  .claude/rules/kit-yaml.md
+7fbc4682444cb12618109d35e70d4fe8b44800ea3c8a9650990600de377da743  .claude/rules/kit-bash.md
+aa929618fa9c7f7453f1c6a2ada1a4cdb438ec75d5b27545bc3408e91009f9a4  .claude/rules/kit-gitignore.md
+ca53518000325e42ca47f288277127ea3c4f7f6bcb8592b0a385e042831a3d63  .claude/rules/kit-json.md
+57a57fd00cbd259373db63e925a565326a598946f68d96d17840e6d6a788968e  .claude/rules/kit-just.md
+ad78f52fbcc9aca6bc9c3a42b439376ae85bbe32323194571a309ac106e459cc  .claude/rules/kit-markdown.md
+416a84c9dabb8eacbcd5e2cfa4a3b22fe034d368263a43097f08d0a9a29b547c  .claude/rules/kit-yaml.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index 786ba9c..dbecf1c 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.sh"
+  - "**/*.bash"
+  - ".kit/hooks/*"
+---
 # Bash
 
 Applies to `*.sh`, `*.bash`, `.kit/hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
diff --git a/.kit/rules/gitignore.md b/.kit/rules/gitignore.md
index bc034de..41b87e4 100644
--- a/.kit/rules/gitignore.md
+++ b/.kit/rules/gitignore.md
@@ -1,3 +1,8 @@
+---
+paths:
+  - ".gitignore"
+  - "**/.gitignore"
+---
 # Ignore lists
 
 Applies to `.gitignore` at any depth.
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
index b11ca35..9d0859d 100644
--- a/.kit/rules/json.md
+++ b/.kit/rules/json.md
@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.json"
+  - "**/*.jsonc"
+---
 # JSON
 
 Applies to `*.json` and `*.jsonc`.
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index 5ce5ec2..9505c0c 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -1,3 +1,9 @@
+---
+paths:
+  - "justfile"
+  - "**/justfile"
+  - "**/*.just"
+---
 # Just
 
 Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index ce54df8..53c613f 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -1,3 +1,7 @@
+---
+paths:
+  - "**/*.md"
+---
 # Markdown
 
 Applies to `*.md`.
diff --git a/.kit/rules/yaml.md b/.kit/rules/yaml.md
index b39eca6..69fe17c 100644
--- a/.kit/rules/yaml.md
+++ b/.kit/rules/yaml.md
@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.yml"
+  - "**/*.yaml"
+---
 # YAML
 
 Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
diff --git a/README.md b/README.md
index dbeefe6..caeb611 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ This repository is both the source of the kit and a consumer of it, so some comm
 
 | Installed copy | Written from |
 | --- | --- |
-| `.claude/rules/kit-<kind>.md` | `.kit/rules/<kind>.md`, with the `paths:` header the `claude` target adds |
+| `.claude/rules/kit-<kind>.md` | `.kit/rules/<kind>.md`, header and all, with a one-line notice |
 | `.claude/settings.json` | `.kit/settings.json`, merged by key; here it carries only the kit's entries |
 | `.github/workflows/kit-ci.yml` | `.kit/ci.yml` |
 | `.kit/manifest` | the release version, the targets taken, and a digest per delivered path |
diff --git a/bin/kit b/bin/kit
index 034d2e7..5864fdb 100755
--- a/bin/kit
+++ b/bin/kit
@@ -22,7 +22,7 @@
 # core.hooksPath.
 #
 # A target is a harness that insists on files placed outside .kit/. The one this release knows is claude:
-# .claude/rules/kit-<kind>.md, each the rule file of that kind with a paths: header, and the kit's deny entries
+# .claude/rules/kit-<kind>.md, a copy of each rule file, whose own paths: header the harness loads it by, and the deny entries
 # merged into .claude/settings.json. A repository takes only the targets it names. A shared settings file is
 # merged by key: the kit owns only the entries it writes.
 #
@@ -80,19 +80,6 @@ require-targets() {
 manifest-version() { sed -n 's/^version //p' .kit/manifest; }
 manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
 
-# rule-paths <kind> prints the paths: globs a harness loads the rule of <kind> for, one per line.
-rule-paths() {
-  case "$1" in
-    (markdown)  printf '%s\n' '**/*.md' ;;
-    (bash)      printf '%s\n' '**/*.sh' '**/*.bash' '.kit/hooks/*' ;;
-    (just)      printf '%s\n' 'justfile' '**/justfile' '**/*.just' ;;
-    (yaml)      printf '%s\n' '**/*.yml' '**/*.yaml' ;;
-    (json)      printf '%s\n' '**/*.json' '**/*.jsonc' ;;
-    (gitignore) printf '%s\n' '.gitignore' '**/.gitignore' ;;
-    (*)         printf '%s\n' "**/*.$1"
-  esac
-}
-
 # target-paths <payload> <target> prints the repository paths a target places.
 target-paths() {
   local root=$1 file
@@ -130,24 +117,17 @@ delivered-paths() {
 
 # expected <payload> <path> prints the content the release at <payload> delivers at repository <path>.
 expected() {
-  local root=$1 path=$2 kind glob
+  local root=$1 path=$2 kind
   case "${path}" in
     (.kit/*)
       cat "${root}/${path#.kit/}"
       ;;
     (.claude/rules/kit-*.md)
+      # The rule file as it is, its paths: header included, with a one-line notice inside the header.
       kind=${path#.claude/rules/kit-}
       kind=${kind%.md}
-      printf -- '---\n'
-      printf '# Placed by kit install from the release'"'"'s rules/%s.md, and held to it by kit check. A delivered file is\n' "${kind}"
-      printf '# changed by pinning a new release and running kit update, never in place.\n'
-      printf 'paths:\n'
-      while IFS= read -r glob
-      do
-        printf '  - "%s"\n' "${glob}"
-      done < <(rule-paths "${kind}")
-      printf -- '---\n'
-      cat "${root}/rules/${kind}.md"
+      printf -- '---\n# Placed by kit install from .kit/rules/%s.md, not edited by hand.\n' "${kind}"
+      tail -n +2 "${root}/rules/${kind}.md"
       ;;
     (.github/workflows/kit-ci.yml)
       cat "${root}/ci.yml"
@@ -200,7 +180,7 @@ ensure-ignored() {
 write-manifest() {
   local path
   {
-    printf '# .kit/manifest - written by kit install, update, and target; never edited by hand\n'
+    printf '# .kit/manifest - written by kit, not by hand\n'
     printf 'version %s\n' "$(cat "${payload}/version")"
     printf 'targets%s\n' "${*:+ $*}"
     while IFS= read -r path

From 29dea0fa2df96accf2b18f1db2d672692c433676 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:56:20 -0700
Subject: [PATCH 020/108] #1 bin/kit: a release is a tree mirrored at the root;
 the only rule is a merge for json

The release root holds tree/, mirrored verbatim at a consumer's root; targets/<name>/, mirrored when the target is taken; and bash/, hooks/, and version, the machinery. bin/kit walks those directories and copies what it finds, a symlink as the file it points at, so the Claude mirrors are links into tree/.kit/rules/ and a new rule is one file and one link. A .json destination is merged by key with one jq definition. Notices live in the delivered files themselves.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md                     |   6 +-
 .claude/rules/kit-gitignore.md                |   2 +-
 .claude/rules/kit-json.md                     |   2 +-
 .claude/rules/kit-just.md                     |   2 +-
 .claude/rules/kit-markdown.md                 |   2 +-
 .claude/rules/kit-yaml.md                     |   2 +-
 .github/workflows/kit-ci.yml                  |   2 +-
 .github/workflows/release.yml                 |  17 +-
 .kit/1st.md                                   |  11 +-
 .kit/manifest                                 |  29 +-
 .kit/rules/bash.md                            |   5 +-
 .kit/rules/gitignore.md                       |   1 +
 .kit/rules/json.md                            |   1 +
 .kit/rules/just.md                            |   1 +
 .kit/rules/markdown.md                        |   1 +
 .kit/rules/yaml.md                            |   1 +
 AGENTS.md                                     |   8 +-
 README.md                                     |  36 +-
 {.kit/bash => bash}/1st.sh                    |   7 +-
 {.kit/bash => bash}/gh.sh                     |   4 +
 {.kit/bash => bash}/git.sh                    |   0
 bin/kit                                       | 460 +++++++++---------
 {.kit/hooks => hooks}/pre-commit              |   2 +-
 {.kit/hooks => hooks}/pre-rebase              |   0
 justfile                                      |   8 +-
 targets/claude/.claude/rules/kit-bash.md      |   1 +
 targets/claude/.claude/rules/kit-gitignore.md |   1 +
 targets/claude/.claude/rules/kit-json.md      |   1 +
 targets/claude/.claude/rules/kit-just.md      |   1 +
 targets/claude/.claude/rules/kit-markdown.md  |   1 +
 targets/claude/.claude/rules/kit-yaml.md      |   1 +
 .../claude/.claude}/settings.json             |   0
 tests/hooks.bats                              |   2 +-
 tests/kit.bats                                |  28 +-
 tests/release.bats                            |  16 +-
 .../.github/workflows/kit-ci.yml              |   2 +-
 tree/.kit/1st.md                              |  90 ++++
 tree/.kit/rules/bash.md                       |  50 ++
 tree/.kit/rules/gitignore.md                  |  30 ++
 tree/.kit/rules/json.md                       |  27 +
 tree/.kit/rules/just.md                       |  56 +++
 tree/.kit/rules/markdown.md                   |  53 ++
 tree/.kit/rules/yaml.md                       |  35 ++
 .kit/version => version                       |   0
 44 files changed, 671 insertions(+), 334 deletions(-)
 rename {.kit/bash => bash}/1st.sh (91%)
 rename {.kit/bash => bash}/gh.sh (97%)
 rename {.kit/bash => bash}/git.sh (100%)
 rename {.kit/hooks => hooks}/pre-commit (98%)
 rename {.kit/hooks => hooks}/pre-rebase (100%)
 create mode 120000 targets/claude/.claude/rules/kit-bash.md
 create mode 120000 targets/claude/.claude/rules/kit-gitignore.md
 create mode 120000 targets/claude/.claude/rules/kit-json.md
 create mode 120000 targets/claude/.claude/rules/kit-just.md
 create mode 120000 targets/claude/.claude/rules/kit-markdown.md
 create mode 120000 targets/claude/.claude/rules/kit-yaml.md
 rename {.kit => targets/claude/.claude}/settings.json (100%)
 rename .kit/ci.yml => tree/.github/workflows/kit-ci.yml (98%)
 create mode 100644 tree/.kit/1st.md
 create mode 100644 tree/.kit/rules/bash.md
 create mode 100644 tree/.kit/rules/gitignore.md
 create mode 100644 tree/.kit/rules/json.md
 create mode 100644 tree/.kit/rules/just.md
 create mode 100644 tree/.kit/rules/markdown.md
 create mode 100644 tree/.kit/rules/yaml.md
 rename .kit/version => version (100%)

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
index 3925045..86d45e8 100644
--- a/.claude/rules/kit-bash.md
+++ b/.claude/rules/kit-bash.md
@@ -1,13 +1,13 @@
 ---
-# Placed by kit install from .kit/rules/bash.md, not edited by hand.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.sh"
   - "**/*.bash"
-  - ".kit/hooks/*"
+  - "**/hooks/*"
 ---
 # Bash
 
-Applies to `*.sh`, `*.bash`, `.kit/hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+Applies to `*.sh`, `*.bash`, `hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
 workflows.
 
 ## Shape
diff --git a/.claude/rules/kit-gitignore.md b/.claude/rules/kit-gitignore.md
index 564abb7..7465b65 100644
--- a/.claude/rules/kit-gitignore.md
+++ b/.claude/rules/kit-gitignore.md
@@ -1,5 +1,5 @@
 ---
-# Placed by kit install from .kit/rules/gitignore.md, not edited by hand.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - ".gitignore"
   - "**/.gitignore"
diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
index 2bfa91d..692c8aa 100644
--- a/.claude/rules/kit-json.md
+++ b/.claude/rules/kit-json.md
@@ -1,5 +1,5 @@
 ---
-# Placed by kit install from .kit/rules/json.md, not edited by hand.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.json"
   - "**/*.jsonc"
diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
index b2873d8..0698212 100644
--- a/.claude/rules/kit-just.md
+++ b/.claude/rules/kit-just.md
@@ -1,5 +1,5 @@
 ---
-# Placed by kit install from .kit/rules/just.md, not edited by hand.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "justfile"
   - "**/justfile"
diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
index acd24ed..d830ce3 100644
--- a/.claude/rules/kit-markdown.md
+++ b/.claude/rules/kit-markdown.md
@@ -1,5 +1,5 @@
 ---
-# Placed by kit install from .kit/rules/markdown.md, not edited by hand.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.md"
 ---
diff --git a/.claude/rules/kit-yaml.md b/.claude/rules/kit-yaml.md
index 006d844..3e5795c 100644
--- a/.claude/rules/kit-yaml.md
+++ b/.claude/rules/kit-yaml.md
@@ -1,5 +1,5 @@
 ---
-# Placed by kit install from .kit/rules/yaml.md, not edited by hand.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.yml"
   - "**/*.yaml"
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index d72042d..c4cb81d 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -6,7 +6,7 @@
 # not linked to an open issue of this repository under Development. The last two run even when an earlier step
 # refused, so one run reports every finding.
 #
-# This file is placed by `kit install` and verified by `kit check`. Change it by pinning a new release.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
 # see: .kit/1st.md
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 432d02f..189a2cb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,10 +1,10 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/ and .kit/, the layout
-# a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, bash/,
+# hooks/, and version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
 # is tagged on main (any commit on main, not only its head). A pre-release, the same with a -<suffix>, is tagged on
-# a commit that is not on main, and is published as a GitHub pre-release. Either way .kit/version at the tagged
+# a commit that is not on main, and is published as a GitHub pre-release. Either way the file version at the tagged
 # commit is the version without the suffix, the one under development, and the packed kit carries the tag's full
 # version so a consumer pinning a pre-release sees it in kit version and .kit/manifest.
 #
@@ -62,13 +62,13 @@ jobs:
           set -o errexit -o nounset -o pipefail
           tag_version=${GITHUB_REF_NAME#v}
           base_version=${tag_version%%-*}
-          file_version=$(cat .kit/version)
+          file_version=$(cat version)
           if [[ "${base_version}" != "${file_version}" ]]
           then
-            echo "::error::the tag says ${base_version} and .kit/version says ${file_version}; set .kit/version at the tagged commit first"
+            echo "::error::the tag says ${base_version} and version says ${file_version}; set version at the tagged commit first"
             exit 1
           fi
-          echo "✅ .kit/version is ${file_version}."
+          echo "✅ version is ${file_version}."
 
       - name: pack-and-release
         env:
@@ -78,10 +78,9 @@ jobs:
           version=${GITHUB_REF_NAME#v}
           staging=$(mktemp --directory)
           mkdir "${staging}/kit-${version}"
-          cp --recursive bin .kit "${staging}/kit-${version}/"
-          rm --force "${staging}/kit-${version}/.kit/manifest"
+          cp --recursive --no-dereference bin tree targets bash hooks version "${staging}/kit-${version}/"
           # the packed kit carries the tag's full version, suffix included; the repository file carries the base
-          printf '%s\n' "${version}" > "${staging}/kit-${version}/.kit/version"
+          printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
           sha256sum "kit-${version}.tar.gz" > "kit-${version}.tar.gz.sha256"
           notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\nThen, in the repository: kit install\n' "${version}")
diff --git a/.kit/1st.md b/.kit/1st.md
index f32f7a4..db363e7 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -1,3 +1,4 @@
+<!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
 # Read this first
 
 This file is the kit's entry. It binds every agent and every session in a repository that carries `.kit/`, and
@@ -60,7 +61,7 @@ that kind.
 | Kind | Paths | Rule |
 | --- | --- | --- |
 | Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
-| Bash | `*.sh`, `*.bash`, `.kit/hooks/*` | [rules/bash.md](rules/bash.md) |
+| Bash | `*.sh`, `*.bash`, `hooks/*` | [rules/bash.md](rules/bash.md) |
 | Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
 | YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
 | JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
@@ -70,7 +71,9 @@ that kind.
 
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
 release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
-carries the machinery, reached through the `kit` command on `PATH`:
+carries the machinery, reached through the `kit` command on `PATH`. A release mirrors its `tree/` at the
+repository root, and `targets/<name>/` for each target taken; a `.json` destination is merged by key, everything
+else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands. A root justfile that wants `just issue 42` adds
   a veneer recipe over `kit issue`.
@@ -78,9 +81,9 @@ carries the machinery, reached through the `kit` command on `PATH`:
   points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
-  `.claude/rules/kit-<kind>.md` and merges six deny rules into `.claude/settings.json`. The kit owns only the
+  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges six deny rules into `.claude/settings.json`. The kit owns only the
   entries it writes; the repository may add its own. `kit target remove` takes a target back out.
-- `.kit/ci.yml`, placed as `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
+- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
   runs `kit check`, and refuses a pull request not linked to an open issue.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
diff --git a/.kit/manifest b/.kit/manifest
index 895dffc..e395d5b 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,17 +1,18 @@
 # .kit/manifest - written by kit, not by hand
 version 0.1.0
 targets claude
-700cd37d14cf16d80adf4a96c1ef1037f0956d513d39e0682903625ecec4e32d  .kit/1st.md
-1af539b255a7e6110a5a35d64f6c804441354ea444fecd13e5bbb3086ddeee87  .kit/rules/bash.md
-4c856c8a5e76aa7fe464f3ec3444a9607f653454ce1c1fc75d6e85ca3e67b35f  .kit/rules/gitignore.md
-1c3d02d2f022abecd49c6b4a38294e37e0df8cc97dbac0558a4f25595fb139d5  .kit/rules/json.md
-a79bd22a451fb8b1d118f0921c3b3e1bf2bef8ff0ae496891227e22353b98e44  .kit/rules/just.md
-a495ae7a54188bb82b73d50925012f9611af58396fa82c72c71d8a337c1bccf6  .kit/rules/markdown.md
-4f2d5c15ec02e7549df338ff3ed51d5ebaf702b749dc078ae34392b04fb21c47  .kit/rules/yaml.md
-75318ea548c175eeffcdedb521ac41061baab6ea3bedf3f85fcaa06ad8f61b6f  .github/workflows/kit-ci.yml
-7fbc4682444cb12618109d35e70d4fe8b44800ea3c8a9650990600de377da743  .claude/rules/kit-bash.md
-aa929618fa9c7f7453f1c6a2ada1a4cdb438ec75d5b27545bc3408e91009f9a4  .claude/rules/kit-gitignore.md
-ca53518000325e42ca47f288277127ea3c4f7f6bcb8592b0a385e042831a3d63  .claude/rules/kit-json.md
-57a57fd00cbd259373db63e925a565326a598946f68d96d17840e6d6a788968e  .claude/rules/kit-just.md
-ad78f52fbcc9aca6bc9c3a42b439376ae85bbe32323194571a309ac106e459cc  .claude/rules/kit-markdown.md
-416a84c9dabb8eacbcd5e2cfa4a3b22fe034d368263a43097f08d0a9a29b547c  .claude/rules/kit-yaml.md
+04543fa071df19f28e15f62b678881660391b1c620b001af7932822c7183f774  .claude/rules/kit-bash.md
+0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
+1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .claude/rules/kit-json.md
+98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .claude/rules/kit-just.md
+15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
+03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
+617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .claude/settings.json
+b9a38f19b571c70bb4ef7d3f25fd2b56ac0f6fc076cbcc8e318d22ad3ffe594f  .github/workflows/kit-ci.yml
+c65a92daf5acfe3ed1bd93e263594f6932321d2c4d8cec71521046a8dd137aa6  .kit/1st.md
+04543fa071df19f28e15f62b678881660391b1c620b001af7932822c7183f774  .kit/rules/bash.md
+0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
+1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
+98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .kit/rules/just.md
+15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .kit/rules/markdown.md
+03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .kit/rules/yaml.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index dbecf1c..86d45e8 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -1,12 +1,13 @@
 ---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.sh"
   - "**/*.bash"
-  - ".kit/hooks/*"
+  - "**/hooks/*"
 ---
 # Bash
 
-Applies to `*.sh`, `*.bash`, `.kit/hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+Applies to `*.sh`, `*.bash`, `hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
 workflows.
 
 ## Shape
diff --git a/.kit/rules/gitignore.md b/.kit/rules/gitignore.md
index 41b87e4..7465b65 100644
--- a/.kit/rules/gitignore.md
+++ b/.kit/rules/gitignore.md
@@ -1,4 +1,5 @@
 ---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - ".gitignore"
   - "**/.gitignore"
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
index 9d0859d..692c8aa 100644
--- a/.kit/rules/json.md
+++ b/.kit/rules/json.md
@@ -1,4 +1,5 @@
 ---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.json"
   - "**/*.jsonc"
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index 9505c0c..0698212 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -1,4 +1,5 @@
 ---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "justfile"
   - "**/justfile"
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index 53c613f..d830ce3 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -1,4 +1,5 @@
 ---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.md"
 ---
diff --git a/.kit/rules/yaml.md b/.kit/rules/yaml.md
index 69fe17c..3e5795c 100644
--- a/.kit/rules/yaml.md
+++ b/.kit/rules/yaml.md
@@ -1,4 +1,5 @@
 ---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.yml"
   - "**/*.yaml"
diff --git a/AGENTS.md b/AGENTS.md
index 557c911..e3b1109 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,12 +4,12 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
 
 ## This repository's own rules
 
-- The delivered tree is `.kit/` and `bin/kit`. Everything in it is written for a consumer: no file names a
-  consumer, a person, or another repository as the source of a rule.
-- `.kit/version` is the version under development, with no suffix. A release is the tag `v<version>` on a commit on
+- The release is `bin/`, `tree/`, `targets/`, `bash/`, `hooks/`, and `version`. Everything in it is written for a
+  consumer: no file names a consumer, a person, or another repository as the source of a rule.
+- `version` is the version under development, with no suffix. A release is the tag `v<version>` on a commit on
   `main`. A pre-release is `v<version>-<suffix>` on a commit that is not on `main`. The release workflow refuses any
   other pairing, and a tag whose base version differs from the file.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
-  this repository's installed copies of its own kit, written by `just refresh` from the source under `.kit/`; see
+  this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
   [README.md](README.md) § Maintaining. Edit the source, run `just refresh`, and commit both.
 - `just ci` is the gate: shellcheck, actionlint, the bats suite, and `bin/kit check`.
diff --git a/README.md b/README.md
index caeb611..25d85ee 100644
--- a/README.md
+++ b/README.md
@@ -35,14 +35,14 @@ change the set later, and `kit target list` prints it. Commit what it wrote. The
 
 The machinery, the `kit` command, the bash behind `kit issue`, `kit tidy`, and `kit status`, and the hooks, stays
 in the release where mise installed it; the repository carries the text an agent reads and the record of what it
-took.
+took. The kit needs bash 4.4 or later, git, `gh`, and `jq`.
 
 To move to a new release, bump the pin, run `mise install`, then `kit update`: a delivered file you left alone is
 replaced, one you edited is three-way merged with the previous release as the base, and your own deny entries
 and settings keys stay. `kit check` fails, locally and in `CI`, when a delivered file differs from the pinned
 release.
 
-The kit needs bash 4 or later, git, `gh`, and `jq`. macOS ships bash 3.2; `brew install bash` gives a current one.
+macOS ships bash 3.2; `brew install bash` gives a current one.
 
 ## Setup
 
@@ -76,29 +76,33 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 ## Maintaining
 
-This repository is both the source of the kit and a consumer of it, so some committed files are written by
-`bin/kit install` from others and are not edited by hand:
+This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
+every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
+the same way; `bash/`, `hooks/`, and `version` are the machinery `bin/kit` runs. A symlink under `targets/` is
+delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
+
+The installed copies are written by `bin/kit install` and not edited by hand:
 
 | Installed copy | Written from |
 | --- | --- |
-| `.claude/rules/kit-<kind>.md` | `.kit/rules/<kind>.md`, header and all, with a one-line notice |
-| `.claude/settings.json` | `.kit/settings.json`, merged by key; here it carries only the kit's entries |
-| `.github/workflows/kit-ci.yml` | `.kit/ci.yml` |
+| `.kit/1st.md`, `.kit/rules/` | `tree/.kit/` |
+| `.github/workflows/kit-ci.yml` | `tree/.github/workflows/kit-ci.yml` |
+| `.claude/rules/kit-<kind>.md` | `targets/claude/.claude/rules/`, links into `tree/.kit/rules/` |
+| `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here it carries only the kit's entries |
 | `.kit/manifest` | the release version, the targets taken, and a digest per delivered path |
 
-Everything else is source, all of `.kit/` included: `1st.md`, `rules/`, `bash/`, `hooks/`, `ci.yml`,
-`settings.json`, and `version`, together with `bin/kit`, the two workflows, and `tests/`. After changing a source
-file under `.kit/`, run `just refresh`, which reinstalls the kit into this repository, and commit the result with
-the change. `bin/kit check`, which `just ci` runs, names any installed copy that no longer matches its source. The
-copies that can carry a comment say they are placed; `settings.json` cannot, so this table is its notice.
+After changing a file under `tree/` or `targets/`, run `just refresh`, which reinstalls the kit into this
+repository, and commit the result with the change. `bin/kit check`, which `just ci` runs, names any installed copy
+that no longer matches its source. Each delivered text file says in its header that it is delivered by kit;
+`settings.json` cannot, so this table is its notice.
 
 ## Release
 
-`.kit/version` carries the version under development, without a suffix. A release is the tag `v<version>` on a
+`version` carries the version under development, without a suffix. A release is the tag `v<version>` on a
 commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`, say `v0.1.0-rc.1`, on a commit that is
-not on `main`, and it is published as a GitHub pre-release. In both cases the workflow packs `bin/` and `.kit/` into
-`kit-<version>.tar.gz` with the tag's full version stamped into the packed `.kit/version`, and publishes the release.
+not on `main`, and it is published as a GitHub pre-release. In both cases the workflow packs the release into
+`kit-<version>.tar.gz` with the tag's full version stamped into the packed `version`, and publishes the release.
 It refuses a tag that is not a version, a release tag off `main`, a pre-release tag on `main`, and a tag whose base
-version is not `.kit/version`.
+version is not `version`.
 
 Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf
diff --git a/.kit/bash/1st.sh b/bash/1st.sh
similarity index 91%
rename from .kit/bash/1st.sh
rename to bash/1st.sh
index 40299dc..e7dcd0b 100644
--- a/.kit/bash/1st.sh
+++ b/bash/1st.sh
@@ -2,9 +2,8 @@
 # 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Sourced by bin/kit, whose issue, tidy, and status run the bash under .kit/bash/, and by the hooks that need a
-# verb. It defines functions only and sets no shell option, so the caller's options stand. A module under
-# .kit/bash/ is loaded on first use with `use <module>`, and each exported function has a stub here so a
+# Sourced by bin/kit, whose issue, tidy, and status run the bash under bash/, and by the hooks that need a verb. It defines functions only and sets no shell option, so the caller's options stand. A module under
+# bash/ is loaded on first use with `use <module>`, and each exported function has a stub here so a
 # caller never has to load it by hand.
 #
 # Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
@@ -14,7 +13,7 @@ kit_bash_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 declare -gr kit_bash_dir
 declare -Ag kit_modules=([1st]=1)
 
-# use <module>… loads .kit/bash/<module>.sh once. An unknown module is a bug in the caller, so it is fatal.
+# use <module>… loads bash/<module>.sh once. An unknown module is a bug in the caller, so it is fatal.
 use() {
   local module
   for module in "$@"
diff --git a/.kit/bash/gh.sh b/bash/gh.sh
similarity index 97%
rename from .kit/bash/gh.sh
rename to bash/gh.sh
index 2367961..e79a1fe 100644
--- a/.kit/bash/gh.sh
+++ b/bash/gh.sh
@@ -161,6 +161,10 @@ gh:issue() {
   then
     warn "run: kit setup (core.hooksPath does not name this release's hooks, so the desk guard is off in this clone)"
   fi
+  if ! git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null
+  then
+    warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a status or a commit"
+  fi
 
   # GitHub cannot open a pull request on a branch with nothing to compare, so the first commit is an empty one.
   if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
diff --git a/.kit/bash/git.sh b/bash/git.sh
similarity index 100%
rename from .kit/bash/git.sh
rename to bash/git.sh
diff --git a/bin/kit b/bin/kit
index 5864fdb..637a891 100755
--- a/bin/kit
+++ b/bin/kit
@@ -1,227 +1,203 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
 # kit - install, update, and check the kit in a repository (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-#   kit install [<target>…]     copy this release's text into the repository, place the files each named target
-#                               needs, wire this clone's hooks, and write .kit/manifest
-#   kit update                  after the pin is bumped: replace unchanged files, three-way merge changed ones
-#   kit check                   fail when a delivered file differs from this release
-#   kit setup                   wire this clone: core.hooksPath to this release's hooks
-#   kit target list             print the targets this repository takes
-#   kit target add <target>…    take a target: place its files and record it
-#   kit target remove <target>… drop a target: remove its files and the kit's entries from its settings
-#   kit issue [<number>…]       start or resume an issue: linked branch, worktree, start commit, draft pull request
-#   kit tidy [--dry-run]        remove worktrees whose pull request is merged or closed, and gone branches
-#   kit status [--no-fetch]     show every worktree with its branch, pull request, and state
-#   kit version                 print this release's version
+# The release is the directory above bin/. Its tree/ is mirrored at the repository root, verbatim, and so is
+# targets/<name>/ for each target the repository takes; a symlink in either is copied as the file it points at.
+# bash/, hooks/, and version are the machinery and stay in the release. The one exception to a verbatim copy is a
+# destination ending in .json, which is merged by key: the kit's keys are set, the kit's array entries are added,
+# and on update or removal only the entries the previous release wrote are taken out, so the rest of the file is
+# the repository's.
 #
-# The repository carries the text an agent reads, .kit/1st.md and .kit/rules/, the CI workflow .kit/ci.yml placed
-# as .github/workflows/kit-ci.yml, the placed files of each target taken, and .kit/manifest, which records the
-# release version, the targets, and a digest per delivered path. The machinery stays in the release where mise
-# installed it: this command, the bash behind issue, tidy, and status, and the hooks, which a clone reaches through
-# core.hooksPath.
-#
-# A target is a harness that insists on files placed outside .kit/. The one this release knows is claude:
-# .claude/rules/kit-<kind>.md, a copy of each rule file, whose own paths: header the harness loads it by, and the deny entries
-# merged into .claude/settings.json. A repository takes only the targets it names. A shared settings file is
-# merged by key: the kit owns only the entries it writes.
-#
-# KIT_BASE=<dir> names the previous release's root for `kit update` on a machine without mise.
+# .kit/manifest records the release version, the targets taken, and the release's digest for every delivered
+# path. An update tells an untouched file from an edited one by that digest, and merges the edited one with the
+# previous release as the base. KIT_BASE=<dir> names that release's root on a machine without mise.
 #
 # see: .kit/1st.md
 
 set -o errexit -o nounset -o pipefail
 
-kit_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
-payload="${kit_root}/.kit"
-# shellcheck source=.kit/bash/1st.sh
-source "${payload}/bash/1st.sh"
+if (( BASH_VERSINFO[0] < 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] < 4) ))
+then
+  echo "kit needs bash 4.4 or later; this is ${BASH_VERSION}" >&2
+  exit 1
+fi
 
-known_targets=(claude)
+kit_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+# shellcheck source=bash/1st.sh
+source "${kit_root}/bash/1st.sh"
 
 usage() {
-  sed -n '5,16p' "${BASH_SOURCE[0]}" | sed 's/^#//; s/^ //' >&2
-}
+  cat >&2 <<'USAGE'
+usage: kit <command>
 
-# digest prints the sha256 of stdin, by whichever tool the machine carries.
-digest() {
-  if command -v sha256sum >/dev/null 2>&1
-  then
-    sha256sum | cut -d ' ' -f 1
-  else
-    shasum -a 256 | cut -d ' ' -f 1
-  fi
+  install [<target>…]     mirror tree/ and each named target into the repository, wire this clone's hooks,
+                          and write .kit/manifest
+  update                  after the pin is bumped: replace unchanged files, three-way merge changed ones
+  check                   fail when a delivered file differs from this release
+  setup                   wire this clone: core.hooksPath to this release's hooks
+  target list             print the targets this repository takes
+  target add <target>…    take a target: mirror its directory and record it
+  target remove <target>… drop a target: remove its files and the kit's entries from its settings
+  issue [<number>…]       start or resume an issue: linked branch, worktree, start commit, draft pull request
+  tidy [--dry-run]        remove worktrees whose pull request is merged or closed, and gone branches
+  status [--no-fetch]     show every worktree with its branch, pull request, and state
+  version                 print this release's version
+USAGE
 }
 
-# known-target <name> is true when this release knows the target.
-known-target() {
-  local t
-  for t in "${known_targets[@]}"
+# ── the release's layout ───────────────────────────────────────────────────────────────────────────────────────────────
+
+# layers <root> <target>… prints the directories mirrored at the repository root, tree first.
+layers() {
+  local root=$1 t
+  shift
+  printf '%s\n' "${root}/tree"
+  for t in "$@"
   do
-    [[ "$1" == "${t}" ]] && return 0
+    printf '%s\n' "${root}/targets/${t}"
   done
-  return 1
 }
 
-# require-targets <name>… refuses an unknown target, naming the known ones.
+# delivered <root> <target>… prints every repository path the release at <root> delivers for those targets.
+delivered() {
+  local layer
+  while IFS= read -r layer
+  do
+    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@')
+  done < <(layers "$@") | sort --unique
+}
+
+# source-of <root> <path> <target>… prints the release file behind a repository path, the last layer winning.
+source-of() {
+  local root=$1 path=$2 layer found=""
+  shift 2
+  while IFS= read -r layer
+  do
+    [[ -e "${layer}/${path}" ]] && found="${layer}/${path}"
+  done < <(layers "${root}" "$@")
+  [[ -n "${found}" ]] && printf '%s\n' "${found}"
+}
+
+# known-targets prints the targets this release carries.
+known-targets() {
+  (cd "${kit_root}/targets" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
+}
+
+# require-targets <name>… refuses a target this release does not carry, naming the ones it does.
 require-targets() {
   local t
   for t in "$@"
   do
-    if ! known-target "${t}"
+    if [[ ! -d "${kit_root}/targets/${t}" ]]
     then
-      error "'${t}' is not a target this release knows; the targets are: ${known_targets[*]}"
+      error "'${t}' is not a target this release knows; the targets are: $(known-targets | paste -s -d ' ' -)"
       return 2
     fi
   done
 }
 
-# manifest-version and manifest-targets read .kit/manifest.
-manifest-version() { sed -n 's/^version //p' .kit/manifest; }
-manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
-
-# target-paths <payload> <target> prints the repository paths a target places.
-target-paths() {
-  local root=$1 file
-  case "$2" in
-    (claude)
-      for file in "${root}"/rules/*.md
-      do
-        printf '.claude/rules/kit-%s\n' "$(basename "${file}")"
-      done
-  esac
+# target-only <target> prints the paths the target delivers that tree/ does not.
+target-only() {
+  comm -13 <(delivered "${kit_root}") <(delivered "${kit_root}" "$1")
 }
 
-# target-settings <target> prints the settings file a target shares with the repository, or nothing.
-target-settings() {
-  case "$1" in
-    (claude) printf '.claude/settings.json\n'
-  esac
-}
+merged() { [[ "$1" == *.json ]]; }
 
-# delivered-paths <payload> [<target>…] prints every repository path the release delivers for those targets.
-delivered-paths() {
-  local root=$1 file t
-  shift
-  printf '.kit/1st.md\n'
-  for file in "${root}"/rules/*.md
-  do
-    printf '.kit/rules/%s\n' "$(basename "${file}")"
-  done
-  printf '.github/workflows/kit-ci.yml\n'
-  for t in "$@"
-  do
-    target-paths "${root}" "${t}"
-  done
-}
+# ── the one merge rule, for a .json destination ─────────────────────────────────────────────────────────────────────────
 
-# expected <payload> <path> prints the content the release at <payload> delivers at repository <path>.
-expected() {
-  local root=$1 path=$2 kind
-  case "${path}" in
-    (.kit/*)
-      cat "${root}/${path#.kit/}"
-      ;;
-    (.claude/rules/kit-*.md)
-      # The rule file as it is, its paths: header included, with a one-line notice inside the header.
-      kind=${path#.claude/rules/kit-}
-      kind=${kind%.md}
-      printf -- '---\n# Placed by kit install from .kit/rules/%s.md, not edited by hand.\n' "${kind}"
-      tail -n +2 "${root}/rules/${kind}.md"
-      ;;
-    (.github/workflows/kit-ci.yml)
-      cat "${root}/ci.yml"
-      ;;
-    (*)
-      error "kit: '${path}' is not a delivered path"
-      return 2
-  esac
-}
+# The parameters are values ($), not filters: a filter parameter is re-read against the input at each use, which
+# inside the recursion is the wrong level of the object.
+jq_lib='
+  def merge($cur; $base; $new):
+    if ($new | type) == "object" then
+      reduce ($new | keys[]) as $k ($cur // {}; .[$k] = merge(($cur // {})[$k]; ($base // {})[$k]; $new[$k]))
+    elif ($new | type) == "array" then
+      ((($cur // []) - ($base // [])) as $kept | $kept + ($new - $kept))
+    else $new end;
+  def unmerge($cur; $base):
+    if ($base | type) == "object" then
+      reduce ($base | keys[]) as $k ($cur; if has($k) then .[$k] = unmerge($cur[$k]; $base[$k]) else . end)
+    elif ($base | type) == "array" then ($cur // []) - $base
+    else $cur end;
+  def holds($cur; $new):
+    if ($new | type) == "object" then
+      all($new | keys[]; . as $k | ($cur | type) == "object" and ($cur | has($k)) and holds($cur[$k]; $new[$k]))
+    elif ($new | type) == "array" then all($new[]; . as $e | any(($cur // [])[]; . == $e))
+    else $cur == $new end;
+'
 
-# write-expected <payload> <path> writes the delivered content at <path>, making its directory.
-write-expected() {
-  mkdir -p "$(dirname "$2")"
-  expected "$1" "$2" > "$2.kit-new"
-  mv "$2.kit-new" "$2"
+# json-write <path> <filter> rewrites the JSON at <path> through <filter>, making the file if it is missing.
+json-write() {
+  local path=$1 filter=$2
+  shift 2
+  mkdir -p "$(dirname "${path}")"
+  [[ -f "${path}" ]] || printf '{}\n' > "${path}"
+  jq --indent 2 "${jq_lib} ${filter}" "$@" "${path}" > "${path}.kit-new"
+  mv "${path}.kit-new" "${path}"
 }
 
-# merge-settings <target> <new-payload> [<base-payload>] merges the kit's deny entries into the target's settings
-# file: the base release's entries go, the new release's come, and everything else in the file stays. An empty
-# <new-payload> takes the kit's entries out and adds none.
-merge-settings() {
-  local file new_deny='[]' base_deny='[]'
-  file=$(target-settings "$1")
-  [[ -n "${file}" ]] || return 0
-  [[ -n "$2" && -f "$2/settings.json" ]] && new_deny=$(jq '.permissions.deny // []' "$2/settings.json")
-  [[ -n "${3:-}" && -f "$3/settings.json" ]] && base_deny=$(jq '.permissions.deny // []' "$3/settings.json")
-  mkdir -p "$(dirname "${file}")"
-  [[ -f "${file}" ]] || printf '{}\n' > "${file}"
-  jq --indent 2 --argjson base "${base_deny}" --argjson new "${new_deny}" \
-    '.permissions.deny = (((.permissions.deny // []) - $base) as $kept | $kept + ($new - $kept))' \
-    "${file}" > "${file}.kit-new"
-  mv "${file}.kit-new" "${file}"
+# ── placing, recording, wiring ──────────────────────────────────────────────────────────────────────────────────────────
+
+digest() {
+  if command -v sha256sum >/dev/null 2>&1
+  then
+    sha256sum | cut -d ' ' -f 1
+  else
+    shasum -a 256 | cut -d ' ' -f 1
+  fi
 }
 
-# ensure-ignored makes sure worktrees/ is ignored at the root, the way the loop needs.
-ensure-ignored() {
-  local separator=""
-  if [[ -f .gitignore ]] && grep --quiet --line-regexp --extended-regexp '/?worktrees/' .gitignore
+# place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, a copy otherwise.
+place() {
+  local src=$1 path=$2 base=${3:-/dev/null}
+  if merged "${path}"
   then
-    return 0
+    json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
+  else
+    mkdir -p "$(dirname "${path}")"
+    cat "${src}" > "${path}.kit-new"
+    mv "${path}.kit-new" "${path}"
   fi
-  [[ -f .gitignore && -s .gitignore ]] && separator=$'\n'
-  printf '%s# the per-issue worktrees of the loop; see: .kit/1st.md\n/worktrees/\n' "${separator}" >> .gitignore
 }
 
-# write-manifest [<target>…] records the release version, the targets taken, and, per delivered path, the
-# digest of the release's own content for it, never of the file as written: a later update tells an untouched
-# file from an edited one by comparing the file to this, so a merge that kept a repository's edit is not mistaken
-# for the release's text.
+# write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
 write-manifest() {
   local path
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
-    printf 'version %s\n' "$(cat "${payload}/version")"
+    printf 'version %s\n' "$(cat "${kit_root}/version")"
     printf 'targets%s\n' "${*:+ $*}"
     while IFS= read -r path
     do
-      printf '%s  %s\n' "$(expected "${payload}" "${path}" | digest)" "${path}"
-    done < <(delivered-paths "${payload}" "$@")
+      printf '%s  %s\n' "$(digest < "$(source-of "${kit_root}" "${path}" "$@")")" "${path}"
+    done < <(delivered "${kit_root}" "$@")
   } > .kit/manifest
 }
 
-# wire-hooks points this clone's core.hooksPath at the release's hooks.
+manifest-version() { sed -n 's/^version //p' .kit/manifest; }
+manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
+
+require-manifest() {
+  if [[ ! -f .kit/manifest ]]
+  then
+    error "run: kit install (this repository carries no .kit/manifest)"
+    return 1
+  fi
+}
+
 wire-hooks() {
-  git config core.hooksPath "${payload}/hooks"
+  git config core.hooksPath "${kit_root}/hooks"
 }
 
-# finish wires the clone and reports.
 finish() {
   wire-hooks
-  ok "kit $(cat "${payload}/version") is installed, targets: ${*:-none}. core.hooksPath is ${payload}/hooks, and .kit/manifest is written."
+  ok "kit $(cat "${kit_root}/version") is installed, targets: ${*:-none}. core.hooksPath is ${kit_root}/hooks, and .kit/manifest is written."
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
 
-cmd-setup() {
-  guard:require tool:git
-  wire-hooks
-  ok "core.hooksPath is ${payload}/hooks"
-  if [[ -z "$(git config user.signingkey 2>/dev/null)" ]]
-  then
-    warn "no signing key is configured in this clone, and the ruleset refuses an unsigned commit; see README.md § Setup"
-  fi
-}
-
-# cmd-loop <verb> <args>… runs one of the loop's commands from the release's bash.
-cmd-loop() {
-  local verb=$1
-  shift
-  case "${verb}" in
-    (issue)  gh:issue "$@" ;;
-    (tidy)   git:tidy "$@" ;;
-    (status) git:status "$@" ;;
-  esac
-}
+# ── commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 cmd-install() {
   guard:require tool:jq tool:git
@@ -231,38 +207,28 @@ cmd-install() {
     error "run: kit update (this repository already carries kit $(manifest-version))"
     return 1
   fi
-  section "kit install $(cat "${payload}/version")${*:+, targets: $*}"
-  local path t
+  section "kit install $(cat "${kit_root}/version")${*:+, targets: $*}"
+  local path
   while IFS= read -r path
   do
     step "${path}"
-    write-expected "${payload}" "${path}"
-  done < <(delivered-paths "${payload}" "$@")
-  for t in "$@"
-  do
-    merge-settings "${t}" "${payload}"
-  done
-  ensure-ignored
+    place "$(source-of "${kit_root}" "${path}" "$@")" "${path}"
+  done < <(delivered "${kit_root}" "$@")
   write-manifest "$@"
   finish "$@"
 }
 
 cmd-update() {
   guard:require tool:jq tool:git
-  if [[ ! -f .kit/manifest ]]
-  then
-    error "run: kit install (this repository carries no .kit/manifest)"
-    return 1
-  fi
-  local previous current base_root="" path recorded actual conflicts=0 t
+  require-manifest
+  local previous current base_root="" path src base recorded conflicts=0
   local -a targets
   read -r -a targets <<<"$(manifest-targets)"
   previous=$(manifest-version)
-  current=$(cat "${payload}/version")
+  current=$(cat "${kit_root}/version")
   section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
 
-  # The previous release is the base of every three-way merge. KIT_BASE names its root directly; otherwise
-  # mise keeps it where it installed it.
+  # The previous release is the base of every merge. KIT_BASE names its root; otherwise mise knows where it is.
   if [[ -n "${KIT_BASE:-}" ]]
   then
     base_root=${KIT_BASE}
@@ -274,46 +240,45 @@ cmd-update() {
       base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
     fi
   fi
-  [[ -n "${base_root}" ]] && base_root="${base_root}/.kit"
 
   while IFS= read -r path
   do
+    src=$(source-of "${kit_root}" "${path}" "${targets[@]}")
+    base=""
+    [[ -n "${base_root}" ]] && base=$(source-of "${base_root}" "${path}" "${targets[@]}" || true)
+    if merged "${path}"
+    then
+      step "${path}: merged by key"
+      place "${src}" "${path}" "${base}"
+      continue
+    fi
     if [[ ! -f "${path}" ]]
     then
       step "${path}: missing, written"
-      write-expected "${payload}" "${path}"
+      place "${src}" "${path}"
       continue
     fi
     recorded=$(awk -v p="${path}" '$2==p{print $1}' .kit/manifest)
-    actual=$(digest < "${path}")
-    if [[ -z "${recorded}" || "${recorded}" == "${actual}" ]]
+    if [[ -z "${recorded}" || "${recorded}" == "$(digest < "${path}")" ]]
     then
       step "${path}: unchanged since ${previous}, replaced"
-      write-expected "${payload}" "${path}"
+      place "${src}" "${path}"
       continue
     fi
-    if [[ -z "${base_root}" || ! -d "${base_root}" ]]
+    if [[ -z "${base}" ]]
     then
       error "${path} was edited and the base release ${previous} is not installed; run: mise install github:empowerite/kit@${previous}"
       conflicts=$(( conflicts + 1 ))
       continue
     fi
     step "${path}: edited since ${previous}, three-way merged"
-    expected "${base_root}" "${path}" > "${path}.kit-base"
-    expected "${payload}" "${path}" > "${path}.kit-new"
-    if ! git merge-file --marker-size 7 "${path}" "${path}.kit-base" "${path}.kit-new"
+    if ! git merge-file --marker-size 7 "${path}" "${base}" "${src}"
     then
       warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
       conflicts=$(( conflicts + 1 ))
     fi
-    rm -f "${path}.kit-base" "${path}.kit-new"
-  done < <(delivered-paths "${payload}" "${targets[@]}")
+  done < <(delivered "${kit_root}" "${targets[@]}")
 
-  for t in "${targets[@]}"
-  do
-    merge-settings "${t}" "${payload}" "${base_root}"
-  done
-  ensure-ignored
   write-manifest "${targets[@]}"
   if (( conflicts > 0 ))
   then
@@ -324,51 +289,40 @@ cmd-update() {
 }
 
 cmd-check() {
-  local path findings=0 version t file
+  require-manifest
+  local path src findings=0 version
   local -a targets
-  if [[ ! -f .kit/manifest ]]
-  then
-    error "run: kit install (this repository carries no .kit/manifest)"
-    return 1
-  fi
   read -r -a targets <<<"$(manifest-targets)"
   version=$(manifest-version)
-  if [[ "${version}" != "$(cat "${payload}/version")" ]]
+  if [[ "${version}" != "$(cat "${kit_root}/version")" ]]
   then
-    error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${payload}/version"); run: kit update"
+    error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${kit_root}/version"); run: kit update"
     findings=$(( findings + 1 ))
   fi
   while IFS= read -r path
   do
+    src=$(source-of "${kit_root}" "${path}" "${targets[@]}")
     if [[ ! -f "${path}" ]]
     then
       error "${path} is missing"
       findings=$(( findings + 1 ))
-    elif ! expected "${payload}" "${path}" | cmp --silent - "${path}"
-    then
-      error "${path} differs from the pinned release"
-      findings=$(( findings + 1 ))
-    fi
-  done < <(delivered-paths "${payload}" "${targets[@]}")
-  for t in "${targets[@]}"
-  do
-    file=$(target-settings "${t}")
-    [[ -n "${file}" ]] || continue
-    if [[ ! -f "${file}" ]]
+    elif merged "${path}"
     then
-      error "${file} is missing; run: kit update"
-      findings=$(( findings + 1 ))
-    elif ! command -v jq >/dev/null 2>&1
+      if ! command -v jq >/dev/null 2>&1
+      then
+        error "run: mise install (jq is not on PATH, so ${path} could not be read)"
+        findings=$(( findings + 1 ))
+      elif ! jq --exit-status "${jq_lib} holds(.; \$new[0])" --slurpfile new "${src}" "${path}" >/dev/null
+      then
+        error "${path} is missing an entry the kit writes; run: kit update"
+        findings=$(( findings + 1 ))
+      fi
+    elif ! cmp --silent "${src}" "${path}"
     then
-      error "run: mise install (jq is not on PATH, so ${file} could not be read)"
-      findings=$(( findings + 1 ))
-    elif (( $(jq --argjson new "$(jq '.permissions.deny // []' "${payload}/settings.json")" \
-        '($new - (.permissions.deny // [])) | length' "${file}") > 0 ))
-    then
-      error "${file} is missing a deny entry the kit writes; run: kit update"
+      error "${path} differs from the pinned release"
       findings=$(( findings + 1 ))
     fi
-  done
+  done < <(delivered "${kit_root}" "${targets[@]}")
   if (( findings > 0 ))
   then
     error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
@@ -377,15 +331,21 @@ cmd-check() {
   ok "kit ${version}, targets ${targets[*]:-none}: every delivered file matches the pinned release."
 }
 
+cmd-setup() {
+  guard:require tool:git
+  wire-hooks
+  ok "core.hooksPath is ${kit_root}/hooks"
+  if [[ -z "$(git config user.signingkey 2>/dev/null)" ]]
+  then
+    warn "no signing key is configured in this clone, and the ruleset refuses an unsigned commit; see README.md § Setup"
+  fi
+}
+
 cmd-target() {
-  local verb=${1:-list} t path
+  local verb=${1:-list} t path src
   local -a targets kept
   shift || true
-  if [[ ! -f .kit/manifest ]]
-  then
-    error "run: kit install (this repository carries no .kit/manifest)"
-    return 1
-  fi
+  require-manifest
   read -r -a targets <<<"$(manifest-targets)"
   case "${verb}" in
     (list)
@@ -406,9 +366,8 @@ cmd-target() {
         while IFS= read -r path
         do
           step "${path}"
-          write-expected "${payload}" "${path}"
-        done < <(target-paths "${payload}" "${t}")
-        merge-settings "${t}" "${payload}"
+          place "${kit_root}/targets/${t}/${path}" "${path}"
+        done < <(target-only "${t}")
         targets+=("${t}")
       done
       write-manifest "${targets[@]}"
@@ -428,18 +387,25 @@ cmd-target() {
         section "kit target remove ${t}"
         while IFS= read -r path
         do
-          step "removing ${path}"
-          rm -f "${path}"
-        done < <(target-paths "${payload}" "${t}")
-        [[ -f "$(target-settings "${t}")" ]] && merge-settings "${t}" "" "${payload}"
+          src="${kit_root}/targets/${t}/${path}"
+          if merged "${path}"
+          then
+            [[ -f "${path}" ]] || continue
+            step "${path}: the kit's entries taken out"
+            json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
+          else
+            step "removing ${path}"
+            rm -f "${path}"
+          fi
+        done < <(target-only "${t}")
         kept=()
         for path in "${targets[@]}"
         do
           [[ "${path}" == "${t}" ]] || kept+=("${path}")
         done
-        targets=("${kept[@]+"${kept[@]}"}")
+        targets=("${kept[@]}")
       done
-      write-manifest "${targets[@]+"${targets[@]}"}"
+      write-manifest "${targets[@]}"
       ok "targets: ${targets[*]:-none}"
       ;;
     (*)
@@ -448,6 +414,16 @@ cmd-target() {
   esac
 }
 
+cmd-loop() {
+  local verb=$1
+  shift
+  case "${verb}" in
+    (issue)  gh:issue "$@" ;;
+    (tidy)   git:tidy "$@" ;;
+    (status) git:status "$@" ;;
+  esac
+}
+
 case "${1:-}" in
   (install) shift; cmd-install "$@" ;;
   (update)  cmd-update ;;
@@ -455,7 +431,7 @@ case "${1:-}" in
   (setup)   cmd-setup ;;
   (target)  shift; cmd-target "$@" ;;
   (issue | tidy | status) cmd-loop "$@" ;;
-  (version) cat "${payload}/version" ;;
+  (version) cat "${kit_root}/version" ;;
   (-h | --help | help | "") usage; [[ -n "${1:-}" ]] ;;
   (*)
     error "kit: unknown command '$1'"
diff --git a/.kit/hooks/pre-commit b/hooks/pre-commit
similarity index 98%
rename from .kit/hooks/pre-commit
rename to hooks/pre-commit
index f84188a..35c3163 100755
--- a/.kit/hooks/pre-commit
+++ b/hooks/pre-commit
@@ -25,7 +25,7 @@ markdown_paths=()
 for path in "${staged[@]}"
 do
   case "${path}" in
-    (*.sh | *.bash | .kit/hooks/*)
+    (*.sh | *.bash | hooks/*)
       bash_paths+=("${path}")
       ;;
     (.github/workflows/*.yml | .github/workflows/*.yaml)
diff --git a/.kit/hooks/pre-rebase b/hooks/pre-rebase
similarity index 100%
rename from .kit/hooks/pre-rebase
rename to hooks/pre-rebase
diff --git a/justfile b/justfile
index 145d2c4..3dc1496 100644
--- a/justfile
+++ b/justfile
@@ -56,19 +56,19 @@ status *flags:
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  mise exec -- shellcheck --shell=bash --external-sources bin/kit .kit/bash/*.sh .kit/hooks/*
+  mise exec -- shellcheck --shell=bash --external-sources bin/kit bash/*.sh hooks/*
   mise exec -- actionlint
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
 
-# Reinstall this repository's own kit from its source. Here the source under .kit/ is the payload, so an edit to
-# a delivered file is an edit to the release, not a consumer's drift: the installed copies, .claude/settings.json
+# Reinstall this repository's own kit from its source. Here the checkout is the release, so an edit to a file under
+# tree/ or targets/ is an edit to the release, not a consumer's drift: the installed copies, .claude/settings.json
 # (which carries only the kit's entries here), and .kit/manifest are rewritten from it. Run after changing any
 # delivered file, and commit the result with the change.
 #
 #   just refresh
-[doc("🔁 Reinstall this repository's own kit from .kit/ and bin/kit")]
+[doc("🔁 Reinstall this repository's own kit from tree/, targets/, and bin/kit")]
 refresh:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
diff --git a/targets/claude/.claude/rules/kit-bash.md b/targets/claude/.claude/rules/kit-bash.md
new file mode 120000
index 0000000..bb642e0
--- /dev/null
+++ b/targets/claude/.claude/rules/kit-bash.md
@@ -0,0 +1 @@
+../../../../tree/.kit/rules/bash.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-gitignore.md b/targets/claude/.claude/rules/kit-gitignore.md
new file mode 120000
index 0000000..1a1c591
--- /dev/null
+++ b/targets/claude/.claude/rules/kit-gitignore.md
@@ -0,0 +1 @@
+../../../../tree/.kit/rules/gitignore.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-json.md b/targets/claude/.claude/rules/kit-json.md
new file mode 120000
index 0000000..d4e607d
--- /dev/null
+++ b/targets/claude/.claude/rules/kit-json.md
@@ -0,0 +1 @@
+../../../../tree/.kit/rules/json.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-just.md b/targets/claude/.claude/rules/kit-just.md
new file mode 120000
index 0000000..2b2f173
--- /dev/null
+++ b/targets/claude/.claude/rules/kit-just.md
@@ -0,0 +1 @@
+../../../../tree/.kit/rules/just.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-markdown.md b/targets/claude/.claude/rules/kit-markdown.md
new file mode 120000
index 0000000..8d735ea
--- /dev/null
+++ b/targets/claude/.claude/rules/kit-markdown.md
@@ -0,0 +1 @@
+../../../../tree/.kit/rules/markdown.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-yaml.md b/targets/claude/.claude/rules/kit-yaml.md
new file mode 120000
index 0000000..d91b5eb
--- /dev/null
+++ b/targets/claude/.claude/rules/kit-yaml.md
@@ -0,0 +1 @@
+../../../../tree/.kit/rules/yaml.md
\ No newline at end of file
diff --git a/.kit/settings.json b/targets/claude/.claude/settings.json
similarity index 100%
rename from .kit/settings.json
rename to targets/claude/.claude/settings.json
diff --git a/tests/hooks.bats b/tests/hooks.bats
index be264ec..7559eae 100644
--- a/tests/hooks.bats
+++ b/tests/hooks.bats
@@ -8,7 +8,7 @@ setup() {
   cd "${repo}"
   git init --quiet --initial-branch=main
   git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
-  git config core.hooksPath "${kit_checkout}/.kit/hooks"
+  git config core.hooksPath "${kit_checkout}/hooks"
   printf 'one\n' > a && git add a && git commit --quiet --message one
 }
 
diff --git a/tests/kit.bats b/tests/kit.bats
index 15da482..c1c16b8 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -16,13 +16,12 @@ teardown() {
   rm -rf "${repo}"
 }
 
-# later-release <dir> copies this checkout's kit to <dir> as version 9.9.9 with one changed rule line.
+# later-release <dir> copies this checkout's release to <dir> as version 9.9.9 with one changed rule line.
 later-release() {
   mkdir -p "$1"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/.kit" "$1/"
-  rm -f "$1/.kit/manifest"
-  printf '9.9.9\n' > "$1/.kit/version"
-  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/.kit/rules/json.md"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "${kit_checkout}/hooks" "$1/"
+  printf '9.9.9\n' > "$1/version"
+  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/tree/.kit/rules/json.md"
 }
 
 @test "install with the claude target writes the tree, the mirrors, the workflow, the settings, and the manifest" {
@@ -32,22 +31,22 @@ later-release() {
   [ -f .kit/rules/bash.md ]
   [ ! -e .kit/bash ]
   [ ! -e .kit/hooks ]
-  [ ! -e .kit/ci.yml ]
   [ -f .claude/rules/kit-markdown.md ]
+  [ ! -L .claude/rules/kit-markdown.md ]
+  cmp --silent .claude/rules/kit-markdown.md .kit/rules/markdown.md
   head -n 1 .claude/rules/kit-bash.md | grep --quiet --line-regexp -- '---'
   grep --quiet '"\*\*/\*\.sh"' .claude/rules/kit-bash.md
   [ -f .github/workflows/kit-ci.yml ]
   jq --exit-status '.permissions.deny | index("Bash(git push --force *)")' .claude/settings.json >/dev/null
-  grep --quiet --line-regexp '/worktrees/' .gitignore
   grep --quiet '^version 0.1.0$' .kit/manifest
   grep --quiet '^targets claude$' .kit/manifest
-  [ "$(git config core.hooksPath)" = "${kit_checkout}/.kit/hooks" ]
+  [ "$(git config core.hooksPath)" = "${kit_checkout}/hooks" ]
 }
 
 @test "setup wires a clone's hooks to the release, and issue without a terminal prints usage" {
   run "${kit_checkout}/bin/kit" setup
   [ "$status" -eq 0 ]
-  [ "$(git config core.hooksPath)" = "${kit_checkout}/.kit/hooks" ]
+  [ "$(git config core.hooksPath)" = "${kit_checkout}/hooks" ]
   run "${kit_checkout}/bin/kit" issue
   [ "$status" -eq 2 ]
   [[ "$output" == *"usage: kit issue"* ]]
@@ -125,7 +124,7 @@ later-release() {
   [ "$status" -eq 1 ]
   [[ "$output" == *".kit/rules/yaml.md differs"* ]]
   [[ "$output" == *".claude/rules/kit-json.md is missing"* ]]
-  [[ "$output" == *"missing a deny entry"* ]]
+  [[ "$output" == *"missing an entry the kit writes"* ]]
   [[ "$output" == *"3 finding(s)"* ]]
 }
 
@@ -139,7 +138,7 @@ later-release() {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
   # a consumer edit to a file the later release also changes, on a different line
-  sed -i.bak '1s/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
+  sed -i.bak 's/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 0 ]
   grep --quiet '^version 9.9.9$' .kit/manifest
@@ -147,7 +146,7 @@ later-release() {
   grep --quiet '^## Added in 9.9.9$' .kit/rules/json.md
   grep --quiet '^## Added in 9.9.9$' .claude/rules/kit-json.md
   # the manifest carries the release's digest, so the edit still reads as an edit
-  release_digest=$(shasum -a 256 "${repo}.later/.kit/rules/json.md" | cut -d ' ' -f 1)
+  release_digest=$(shasum -a 256 "${repo}.later/tree/.kit/rules/json.md" | cut -d ' ' -f 1)
   grep --quiet "^${release_digest}  .kit/rules/json.md$" .kit/manifest
   # and check names the one file that still differs from the release
   run "${repo}.later/bin/kit" check
@@ -170,9 +169,8 @@ later-release() {
 @test "update leaves conflict markers and fails when the same lines changed" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
-  printf '9.9.9\n' > "${repo}.later/.kit/version"
-  sed -i.bak '1s/^# JSON$/# JSON (theirs)/' "${repo}.later/.kit/rules/json.md" && rm "${repo}.later/.kit/rules/json.md.bak"
-  sed -i.bak '1s/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
+  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${repo}.later/tree/.kit/rules/json.md" && rm "${repo}.later/tree/.kit/rules/json.md.bak"
+  sed -i.bak 's/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
   grep --quiet '^<<<<<<<' .kit/rules/json.md
diff --git a/tests/release.bats b/tests/release.bats
index 64935df..5667467 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -12,26 +12,26 @@ teardown() {
   rm -rf "${work}"
 }
 
-@test "the tarball holds one directory with bin/ and .kit/, no manifest, and installs a fresh repository" {
-  version=$(cat "${kit_checkout}/.kit/version")
+@test "the tarball holds one directory with the release's layout, and installs a fresh repository" {
+  version=$(cat "${kit_checkout}/version")
   mkdir "kit-${version}"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/.kit" "kit-${version}/"
-  rm -f "kit-${version}/.kit/manifest"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "${kit_checkout}/hooks" "${kit_checkout}/version" "kit-${version}/"
   tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
   rm -rf "kit-${version}"
   mkdir unpacked && tar --extract --gzip --file "kit-${version}.tar.gz" --directory unpacked
   [ "$(ls unpacked)" = "kit-${version}" ]
   [ -x "unpacked/kit-${version}/bin/kit" ]
-  [ ! -e "unpacked/kit-${version}/.kit/manifest" ]
+  [ -L "unpacked/kit-${version}/targets/claude/.claude/rules/kit-bash.md" ]
   mkdir fresh && git -C fresh init --quiet --initial-branch=main
   cd fresh
-  run "${work}/unpacked/kit-${version}/bin/kit" install
+  run "${work}/unpacked/kit-${version}/bin/kit" install claude
   [ "$status" -eq 0 ]
   run "${work}/unpacked/kit-${version}/bin/kit" check
   [ "$status" -eq 0 ]
-  [ "$(git config core.hooksPath)" = "${work}/unpacked/kit-${version}/.kit/hooks" ]
-  [ ! -e .kit/bash ]
   [ "$("${work}/unpacked/kit-${version}/bin/kit" version)" = "${version}" ]
+  [ "$(git config core.hooksPath)" = "${work}/unpacked/kit-${version}/hooks" ]
+  [ ! -L .claude/rules/kit-bash.md ]
+  [ ! -e .kit/bash ]
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/ci.yml b/tree/.github/workflows/kit-ci.yml
similarity index 98%
rename from .kit/ci.yml
rename to tree/.github/workflows/kit-ci.yml
index d72042d..c4cb81d 100644
--- a/.kit/ci.yml
+++ b/tree/.github/workflows/kit-ci.yml
@@ -6,7 +6,7 @@
 # not linked to an open issue of this repository under Development. The last two run even when an earlier step
 # refused, so one run reports every finding.
 #
-# This file is placed by `kit install` and verified by `kit check`. Change it by pinning a new release.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
 # see: .kit/1st.md
 
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
new file mode 100644
index 0000000..db363e7
--- /dev/null
+++ b/tree/.kit/1st.md
@@ -0,0 +1,90 @@
+<!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
+# Read this first
+
+This file is the kit's entry. It binds every agent and every session in a repository that carries `.kit/`, and
+the repository's own rules in `AGENTS.md` bind beside it. Where the two differ, the repository's rule wins.
+
+## Integrity
+
+1. Report only what happened. Write "done", "passing", or "verified" only for what ran and held.
+2. A skip is a skip. A check not run, not implemented, or not implementable is reported as exactly that. It
+   clears no gate and earns no credit.
+3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
+4. Being wrong is recoverable. Misreporting is not.
+5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
+   written into a rule file or `AGENTS.md` through the loop, where every agent and every person reads it.
+
+## `main` is the human's desk
+
+The checkout at the repository root stays on the default branch. It is where the human types, reviews, and
+leaves work in progress. Never check out, reset, rebase, or otherwise change it in place. Work happens in a
+worktree under `worktrees/`, one per issue, and reaches `main` only through a merged pull request.
+
+## The loop
+
+1. An issue exists. A change without an issue has not started.
+2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
+   pull request. It never switches the checkout it is run from.
+3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`.
+4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
+   and how, and what was left out and why.
+5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
+   observed.
+
+## Plans are prose
+
+A design, a spec, or a plan is the body of an issue, written in prose. It is never a committed file. When
+the design is written, the issue is the deliverable, and the loop above starts from it.
+
+## The worker contract
+
+A worker is whoever implements one issue in the worktree that issue names.
+
+1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints `<N>-`.
+2. Do every command from there. Never touch the repository root checkout.
+3. Never run `kit issue`, make a branch, or make a worktree. Those were done before the handoff.
+4. Implement what the issue asks and nothing beside it.
+5. Push as you go.
+6. Run the repository's gate before calling anything done, and run it through the pinned toolchain.
+7. End with `gh pr ready` and the report in the pull request body.
+8. If the gate fails or the work is partial, leave the pull request a draft and say why.
+9. Never merge.
+10. Report what ran and what it printed, nothing more.
+
+## Rules by file type
+
+Each file kind has a rule file under `.kit/rules/`, and each rule file names the paths it binds in its `paths:`
+header. A harness that loads rules by path finds a copy under its own rules directory when the repository takes
+that target, `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of
+that kind.
+
+| Kind | Paths | Rule |
+| --- | --- | --- |
+| Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
+| Bash | `*.sh`, `*.bash`, `hooks/*` | [rules/bash.md](rules/bash.md) |
+| Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
+| YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
+| JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
+| Ignore lists | `.gitignore` | [rules/gitignore.md](rules/gitignore.md) |
+
+## What the kit carries
+
+The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
+release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
+carries the machinery, reached through the `kit` command on `PATH`. A release mirrors its `tree/` at the
+repository root, and `targets/<name>/` for each target taken; a `.json` destination is merged by key, everything
+else is copied as it is.
+
+- `kit issue`, `kit tidy`, and `kit status`, the loop's commands. A root justfile that wants `just issue 42` adds
+  a veneer recipe over `kit issue`.
+- Two hooks. `pre-rebase` refuses a rebase of the default branch. `pre-commit` lints the staged paths. `kit install`
+  points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
+- Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
+  it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
+  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges six deny rules into `.claude/settings.json`. The kit owns only the
+  entries it writes; the repository may add its own. `kit target remove` takes a target back out.
+- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
+  runs `kit check`, and refuses a pull request not linked to an open issue.
+
+`kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
+new release and running `kit update`, never by editing them in place.
diff --git a/tree/.kit/rules/bash.md b/tree/.kit/rules/bash.md
new file mode 100644
index 0000000..86d45e8
--- /dev/null
+++ b/tree/.kit/rules/bash.md
@@ -0,0 +1,50 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - "**/*.sh"
+  - "**/*.bash"
+  - "**/hooks/*"
+---
+# Bash
+
+Applies to `*.sh`, `*.bash`, `hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+workflows.
+
+## Shape
+
+1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner, a rule of dashes to
+   column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
+   would change the caller's.
+3. A git hook that must fail open sets `-o nounset -o pipefail` and no `errexit`, and says so in its banner.
+4. The file closes with the same rule of dashes.
+
+## Style
+
+1. `then`, `do`, and `else` go on their own line, never after a semicolon.
+2. Spell `set` options out: `set -o errexit`, never `set -e`.
+3. Spell command options out: `--raw-output`, `--field`, `--delimiter`, never a one-letter flag in a script.
+   Where BSD and GNU differ, use the form both accept: `sed -n`, `head -n 1`, `mkdir -p`.
+4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
+5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
+6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
+7. Quote every expansion outside `[[ ]]` and `(( ))`.
+8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename.
+9. A function private to one executed script is bare kebab-case.
+
+## Behavior
+
+1. An error message is one line, names the remedy first, and is the same wherever the same condition arises.
+2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
+3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
+4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
+5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
+   to do, and a `--dry-run` where the mutation is a sweep.
+6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
+7. shellcheck passes with no directive, or the directive carries the reason on the same line.
+
+## Comments
+
+1. A comment states what the code does and the non-obvious why. It carries no history and defends no obvious
+   choice.
+2. A pointer is `# see: <ref>`, on its own line after the comment it supports.
diff --git a/tree/.kit/rules/gitignore.md b/tree/.kit/rules/gitignore.md
new file mode 100644
index 0000000..7465b65
--- /dev/null
+++ b/tree/.kit/rules/gitignore.md
@@ -0,0 +1,30 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - ".gitignore"
+  - "**/.gitignore"
+---
+# Ignore lists
+
+Applies to `.gitignore` at any depth.
+
+## Shape
+
+1. The file opens with `# .gitignore - untracked files and folders`, a rule of dashes to column 120, and a
+   blank line.
+2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
+   line.
+3. The file closes with a rule of dashes.
+
+## Entries
+
+1. Every entry names a file the repository itself produces. Editor and operating-system files belong in the
+   user's global ignore list, not here.
+2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
+   repository.
+3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
+4. `worktrees/` is ignored at the root: it is where the loop checks out a branch per issue.
+
+## Adding one
+
+Ask what produces the file. If nothing in the repository does, do not add it.
diff --git a/tree/.kit/rules/json.md b/tree/.kit/rules/json.md
new file mode 100644
index 0000000..692c8aa
--- /dev/null
+++ b/tree/.kit/rules/json.md
@@ -0,0 +1,27 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - "**/*.json"
+  - "**/*.jsonc"
+---
+# JSON
+
+Applies to `*.json` and `*.jsonc`.
+
+## Shape
+
+1. Two-space indentation. Keys in a stable order: the order the consuming tool documents, else alphabetical.
+2. One trailing newline. No trailing commas in `.json`.
+3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where
+   it reads plain JSON, the reason for a setting lives in the document that describes the file.
+
+## Settings
+
+1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
+2. A tool's settings file that the kit writes into is merged by key. The kit owns only the keys and entries
+   it writes, and anything else in the file is the repository's.
+
+## Comments
+
+1. A comment states what the entry does and the non-obvious why. It carries no history.
+2. A pointer is `// see: <ref>`.
diff --git a/tree/.kit/rules/just.md b/tree/.kit/rules/just.md
new file mode 100644
index 0000000..0698212
--- /dev/null
+++ b/tree/.kit/rules/just.md
@@ -0,0 +1,56 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - "justfile"
+  - "**/justfile"
+  - "**/*.just"
+---
+# Just
+
+Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
+applies to it as well.
+
+## Shape
+
+1. A module file opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120, and
+   a description of what the file is and who imports it.
+2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
+   root, which has no parent), `set positional-arguments := true`, and `set export := true`.
+3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
+
+   ```just
+   # This file's own path, assigned at parse time so the body below needs no interpolation.
+   export <name>_justfile := source_file()
+
+   # Default recipe: list this justfile's recipes.
+   _: help
+
+   # List recipes in this justfile.
+   [no-exit-message]
+   @help *options:
+     just --justfile "${<name>_justfile}" --list
+   ```
+
+4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
+   the invoking root rather than the module's directory.
+5. The file closes with a rule of dashes.
+
+## Recipes
+
+1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
+2. A comment block precedes every recipe: usage lines, then a paragraph of intent. It answers what the recipe
+   does, when to run it, and what it produces.
+3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
+4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
+5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
+   variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
+   `${name}` and nothing else.
+6. Two-space indentation inside a body. Never a tab.
+7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
+8. Comments wrap at 118 columns. Bodies do not wrap.
+
+## Invocation
+
+1. The idiom is the space form, `just tools check`, never `just tools/check` and never `tools::check` outside a
+   dependency list.
+2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/tree/.kit/rules/markdown.md b/tree/.kit/rules/markdown.md
new file mode 100644
index 0000000..d830ce3
--- /dev/null
+++ b/tree/.kit/rules/markdown.md
@@ -0,0 +1,53 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - "**/*.md"
+---
+# Markdown
+
+Applies to `*.md`.
+
+## Prose
+
+1. Write plain declarative sentences with the thing under discussion as the subject.
+2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
+3. Use a list where the content is a list, and for a procedure or a loop, so it scans. Use a table where the
+   content has columns.
+4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
+5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
+6. Use the serial comma in every list of three or more.
+7. Expand an uncommon acronym the first time it appears.
+8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
+   when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
+
+## Snippets
+
+1. A value the reader supplies is a shell variable the prose names, `"${signing_key}"`, never an angle-bracket
+   placeholder, so the block pastes after one export.
+2. Where a reader may lack a prerequisite, link the page that creates it beside the command that uses it.
+
+## Layout
+
+1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
+   per nesting level, to a limit of 12.
+2. Balance the wrap: no line, in particular the last, reads as a stub.
+3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
+4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
+5. Headings are ATX (`#`). One `#` heading per file, at the top.
+6. Fenced code blocks declare a language and have a blank line on each side.
+7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
+
+## Links
+
+1. Use inline links with descriptive text, never a bare URL in angle brackets.
+2. Use the same anchor text every time the same URL appears in a file.
+3. When a label and the link text would say the same thing, make the label the link.
+4. A relative link resolves from the file that carries it, and it resolves: a check reads them.
+
+## Files
+
+1. Name an index file `1st.md`. It lists its siblings and says what each is for.
+2. A file says what its subject is in its first paragraph, before how to use it.
+3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
+   what the repository is.
+4. No file names another repository as the source of a rule.
diff --git a/tree/.kit/rules/yaml.md b/tree/.kit/rules/yaml.md
new file mode 100644
index 0000000..3e5795c
--- /dev/null
+++ b/tree/.kit/rules/yaml.md
@@ -0,0 +1,35 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - "**/*.yml"
+  - "**/*.yaml"
+---
+# YAML
+
+Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
+
+## Shape
+
+1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
+   reader would not guess from the keys.
+2. Two-space indentation. No tabs. No trailing whitespace.
+3. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
+4. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
+   breaks the requirement.
+5. `permissions` is declared at the top and names the least the jobs need.
+
+## Steps
+
+1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. A step has a `name` that is the policy it enforces, in kebab-case.
+3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
+4. A refusal prints `::error::<message>`, writes `### ❌ <Message>` and a remedy to `${GITHUB_STEP_SUMMARY}`,
+   and returns non-zero. The remedy is the action to take, with a link that is that action.
+5. A pass writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
+7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
+
+## Comments
+
+1. A comment states the non-obvious why. It carries no history.
+2. A pointer is `# see: <ref>`.
diff --git a/.kit/version b/version
similarity index 100%
rename from .kit/version
rename to version

From 36044f83694804947bd0702d8a29aa83f0b0e405 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Fri, 23 Oct 2026 23:57:30 -0700
Subject: [PATCH 021/108] #1 justfile: no veneers; the loop's commands are kit
 issue, tidy, and status

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md      |  3 +--
 .kit/manifest    |  2 +-
 README.md        |  5 ++---
 justfile         | 31 ++-----------------------------
 tree/.kit/1st.md |  3 +--
 5 files changed, 7 insertions(+), 37 deletions(-)

diff --git a/.kit/1st.md b/.kit/1st.md
index db363e7..e1ad167 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -75,8 +75,7 @@ carries the machinery, reached through the `kit` command on `PATH`. A release mi
 repository root, and `targets/<name>/` for each target taken; a `.json` destination is merged by key, everything
 else is copied as it is.
 
-- `kit issue`, `kit tidy`, and `kit status`, the loop's commands. A root justfile that wants `just issue 42` adds
-  a veneer recipe over `kit issue`.
+- `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
 - Two hooks. `pre-rebase` refuses a rebase of the default branch. `pre-commit` lints the staged paths. `kit install`
   points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
diff --git a/.kit/manifest b/.kit/manifest
index e395d5b..ae36234 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -9,7 +9,7 @@ targets claude
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .claude/settings.json
 b9a38f19b571c70bb4ef7d3f25fd2b56ac0f6fc076cbcc8e318d22ad3ffe594f  .github/workflows/kit-ci.yml
-c65a92daf5acfe3ed1bd93e263594f6932321d2c4d8cec71521046a8dd137aa6  .kit/1st.md
+1ff42ec67c8ccbb02fcca51db20d0d6661205701689252d33909fcffa1597562  .kit/1st.md
 04543fa071df19f28e15f62b678881660391b1c620b001af7932822c7183f774  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
diff --git a/README.md b/README.md
index 25d85ee..be62678 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,6 @@ change the set later, and `kit target list` prints it. Commit what it wrote. The
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
 - Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
   request not linked to an open issue.
-- For `just issue 42`, add a veneer recipe over `kit issue` to the root justfile; `kit issue 42` works as it is.
 - In every other clone, run `kit setup` once to wire the hooks.
 
 The machinery, the `kit` command, the bash behind `kit issue`, `kit tidy`, and `kit status`, and the hooks, stays
@@ -66,13 +65,13 @@ This repository carries the installed copy of its own kit, and `just ci` checks
 Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 - An issue exists. A change without an issue has not started.
-- `just issue <N>`, a veneer over `kit issue`, makes `worktrees/<N>-<slug>`, links the branch to the issue under
+- `kit issue <N>`, here `bin/kit issue <N>`, makes `worktrees/<N>-<slug>`, links the branch to the issue under
   Development, and opens a draft pull request. It never switches the checkout it runs from.
 - Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`.
 - `just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
   `bin/kit check`.
 - `gh pr ready` says the work is done, and the pull request body is the report.
-- A human merges. `just tidy` then removes the worktree and its branch.
+- A human merges. `kit tidy` then removes the worktree and its branch.
 
 ## Maintaining
 
diff --git a/justfile b/justfile
index 3dc1496..8beb849 100644
--- a/justfile
+++ b/justfile
@@ -1,8 +1,8 @@
 #!/usr/bin/env just --justfile
 # justfile - see: https://just.systems/man/en/
 # ----------------------------------------------------------------------------------------------------------------------
-# The root justfile: the loop's three commands as veneers over bin/kit, the way a consumer adds them over the kit
-# on its PATH, the gate, and the refresh of this repository's own installed copy.
+# The root justfile: the gate, and the refresh of this repository's own installed copy. The loop's commands are
+# bin/kit issue, tidy, and status, spelled that way and no other.
 
 set dotenv-load := true
 set positional-arguments := true
@@ -20,33 +20,6 @@ _: help
 
 set export := true
 
-# The loop's three commands, each a veneer over bin/kit. A consumer that wants the same spelling writes the same
-# three recipes over the `kit` on its PATH.
-#
-#   just issue 42        # start #42
-#   just issue 42 43     # start #42, and close #43 with it
-[doc("🌿 Start or resume an issue: linked branch, worktree, start commit, draft pull request")]
-issue *numbers:
-  #!/usr/bin/env bash
-  set -o errexit -o nounset -o pipefail
-  bin/kit issue "$@"
-
-#   just tidy            # sweep
-#   just tidy --dry-run  # say what a sweep would do
-[doc("🧹 Remove merged worktrees and gone branches")]
-tidy *flags:
-  #!/usr/bin/env bash
-  set -o errexit -o nounset -o pipefail
-  bin/kit tidy "$@"
-
-#   just status            # fetch --prune, then render
-#   just status --no-fetch # render from the current remote-tracking refs
-[doc("📊 Show every worktree with its branch, pull request, and state")]
-status *flags:
-  #!/usr/bin/env bash
-  set -o errexit -o nounset -o pipefail
-  bin/kit status "$@"
-
 # The gate a pull request passes: shellcheck over every bash file, actionlint over every workflow, the bats
 # suite over bin/kit, and bin/kit check over this repository's installed copy of its own kit. Every tool comes
 # from mise.toml.
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index db363e7..e1ad167 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -75,8 +75,7 @@ carries the machinery, reached through the `kit` command on `PATH`. A release mi
 repository root, and `targets/<name>/` for each target taken; a `.json` destination is merged by key, everything
 else is copied as it is.
 
-- `kit issue`, `kit tidy`, and `kit status`, the loop's commands. A root justfile that wants `just issue 42` adds
-  a veneer recipe over `kit issue`.
+- `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
 - Two hooks. `pre-rebase` refuses a rebase of the default branch. `pre-commit` lints the staged paths. `kit install`
   points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets

From 6d832bed299ba1abf28a30940adcfab88dffc2b9 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:22:51 -0700
Subject: [PATCH 022/108] #1 bin/kit: a dispatcher; one bin/kit-<verb>.bash per
 verb; kit lint and kit rebase replace the hooks

bin/kit resolves the release and execs bin/kit-<verb>.bash. The hooks are gone: kit lint is the body of a pre-commit hook, run by Lefthook through the delivered .kit/lefthook.yml, which a repository takes with extends; kit rebase refuses the default branch and otherwise rebases a worktree's branch onto origin/main and pushes it, and 1st.md names it as the spelling an agent uses, with git rebase added to the deny list. The human's desk is no longer bound by a hook. bash/kit.sh holds the layout and the merge rule the four install verbs share.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md            |   3 +-
 .claude/settings.json                |   1 +
 .github/workflows/release.yml        |   6 +-
 .kit/1st.md                          |  22 +-
 .kit/lefthook.yml                    |  11 +
 .kit/manifest                        |   9 +-
 .kit/rules/bash.md                   |   3 +-
 AGENTS.md                            |   2 +-
 README.md                            |  36 ++-
 bash/1st.sh                          |   2 +-
 bash/gh.sh                           |   5 -
 bash/kit.sh                          | 161 ++++++++++
 bin/kit                              | 452 ++-------------------------
 bin/kit-check.bash                   |  58 ++++
 bin/kit-install.bash                 |  34 ++
 bin/kit-issue.bash                   |  20 ++
 bin/kit-lint.bash                    |  68 ++++
 bin/kit-rebase.bash                  |  47 +++
 bin/kit-status.bash                  |  20 ++
 bin/kit-target.bash                  |  87 ++++++
 bin/kit-tidy.bash                    |  20 ++
 bin/kit-update.bash                  |  89 ++++++
 bin/kit-version.bash                 |   8 +
 hooks/pre-commit                     |  85 -----
 hooks/pre-rebase                     |  46 ---
 justfile                             |   4 +-
 lefthook.yml                         |   8 +
 mise.lock                            |   5 +
 mise.toml                            |   5 +
 targets/claude/.claude/settings.json |   1 +
 tests/hooks.bats                     |  67 ----
 tests/kit.bats                       |  16 +-
 tests/lint.bats                      |  47 +++
 tests/rebase.bats                    |  54 ++++
 tests/release.bats                   |   4 +-
 tree/.kit/1st.md                     |  22 +-
 tree/.kit/lefthook.yml               |  11 +
 tree/.kit/rules/bash.md              |   3 +-
 38 files changed, 862 insertions(+), 680 deletions(-)
 create mode 100644 .kit/lefthook.yml
 create mode 100644 bash/kit.sh
 create mode 100755 bin/kit-check.bash
 create mode 100755 bin/kit-install.bash
 create mode 100755 bin/kit-issue.bash
 create mode 100755 bin/kit-lint.bash
 create mode 100755 bin/kit-rebase.bash
 create mode 100755 bin/kit-status.bash
 create mode 100755 bin/kit-target.bash
 create mode 100755 bin/kit-tidy.bash
 create mode 100755 bin/kit-update.bash
 create mode 100755 bin/kit-version.bash
 delete mode 100755 hooks/pre-commit
 delete mode 100755 hooks/pre-rebase
 create mode 100644 lefthook.yml
 delete mode 100644 tests/hooks.bats
 create mode 100644 tests/lint.bats
 create mode 100644 tests/rebase.bats
 create mode 100644 tree/.kit/lefthook.yml

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
index 86d45e8..92d176e 100644
--- a/.claude/rules/kit-bash.md
+++ b/.claude/rules/kit-bash.md
@@ -3,11 +3,10 @@
 paths:
   - "**/*.sh"
   - "**/*.bash"
-  - "**/hooks/*"
 ---
 # Bash
 
-Applies to `*.sh`, `*.bash`, `hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+Applies to `*.sh` and `*.bash`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
 workflows.
 
 ## Shape
diff --git a/.claude/settings.json b/.claude/settings.json
index 7911d58..fde98cf 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -3,6 +3,7 @@
     "deny": [
       "Bash(git checkout main *)",
       "Bash(git switch main *)",
+      "Bash(git rebase *)",
       "Bash(git reset --hard *)",
       "Bash(git push --force *)",
       "Bash(git push -f *)",
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 189a2cb..707dd83 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,8 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, bash/,
-# hooks/, and version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, bash/, and
+# version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
 # is tagged on main (any commit on main, not only its head). A pre-release, the same with a -<suffix>, is tagged on
 # a commit that is not on main, and is published as a GitHub pre-release. Either way the file version at the tagged
 # commit is the version without the suffix, the one under development, and the packed kit carries the tag's full
@@ -78,7 +78,7 @@ jobs:
           version=${GITHUB_REF_NAME#v}
           staging=$(mktemp --directory)
           mkdir "${staging}/kit-${version}"
-          cp --recursive --no-dereference bin tree targets bash hooks version "${staging}/kit-${version}/"
+          cp --recursive --no-dereference bin tree targets bash version "${staging}/kit-${version}/"
           # the packed kit carries the tag's full version, suffix included; the repository file carries the base
           printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
diff --git a/.kit/1st.md b/.kit/1st.md
index e1ad167..24e573c 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -25,12 +25,25 @@ worktree under `worktrees/`, one per issue, and reaches `main` only through a me
 1. An issue exists. A change without an issue has not started.
 2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
    pull request. It never switches the checkout it is run from.
-3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`.
+3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`. `kit rebase`
+   brings the branch up to date with `main` and pushes it.
 4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
    and how, and what was left out and why.
 5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
    observed.
 
+## Spellings an agent uses
+
+Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. The rule runs inside
+it, and a harness that can refuse the raw spelling does.
+
+- `kit rebase`, never `git rebase`. It refuses the default branch and otherwise rebases the worktree's branch onto
+  `origin/main` and pushes it.
+- `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
+- `kit tidy`, never `git worktree remove` or `git branch -D`.
+
+The human at the desk is not bound by this; `main` is theirs to rebase.
+
 ## Plans are prose
 
 A design, a spec, or a plan is the body of an issue, written in prose. It is never a committed file. When
@@ -61,7 +74,7 @@ that kind.
 | Kind | Paths | Rule |
 | --- | --- | --- |
 | Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
-| Bash | `*.sh`, `*.bash`, `hooks/*` | [rules/bash.md](rules/bash.md) |
+| Bash | `*.sh`, `*.bash` | [rules/bash.md](rules/bash.md) |
 | Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
 | YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
 | JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
@@ -76,8 +89,9 @@ repository root, and `targets/<name>/` for each target taken; a `.json` destinat
 else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
-- Two hooks. `pre-rebase` refuses a rebase of the default branch. `pre-commit` lints the staged paths. `kit install`
-  points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
+- `kit lint`, the body of a pre-commit hook: shellcheck, actionlint, and markdownlint-cli2 when the repository
+  configures it, over the staged paths, with a missing linter reported as a skip. `.kit/lefthook.yml` runs it;
+  a repository's `lefthook.yml` takes that with `extends` and adds hooks of its own.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
   `.claude/rules/kit-<kind>.md`, copies of the rules, and merges six deny rules into `.claude/settings.json`. The kit owns only the
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
new file mode 100644
index 0000000..882d7cf
--- /dev/null
+++ b/.kit/lefthook.yml
@@ -0,0 +1,11 @@
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+#
+# The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]` and adds hooks and commands of its
+# own; Lefthook merges them under the same hook names. Once per clone: lefthook install
+#
+# see: https://lefthook.dev
+
+pre-commit:
+  commands:
+    kit-lint:
+      run: kit lint {staged_files}
diff --git a/.kit/manifest b/.kit/manifest
index ae36234..be6b454 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,16 +1,17 @@
 # .kit/manifest - written by kit, not by hand
 version 0.1.0
 targets claude
-04543fa071df19f28e15f62b678881660391b1c620b001af7932822c7183f774  .claude/rules/kit-bash.md
+389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .claude/rules/kit-bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .claude/rules/kit-json.md
 98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .claude/rules/kit-just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
-617c2e4ca3a72ae59ee898db2120519624a1ad58df5136d0d6f88df96ffdc13a  .claude/settings.json
+100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
 b9a38f19b571c70bb4ef7d3f25fd2b56ac0f6fc076cbcc8e318d22ad3ffe594f  .github/workflows/kit-ci.yml
-1ff42ec67c8ccbb02fcca51db20d0d6661205701689252d33909fcffa1597562  .kit/1st.md
-04543fa071df19f28e15f62b678881660391b1c620b001af7932822c7183f774  .kit/rules/bash.md
+a39770f43e77f4e8ab7e97b5f56c5993e84f3e6778cff1e1e52296ce72b978c3  .kit/1st.md
+e1282bfb261b23acad7d368ca8c2a3e47e728708eee16cb85e54a070f8b96381  .kit/lefthook.yml
+389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
 98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .kit/rules/just.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index 86d45e8..92d176e 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -3,11 +3,10 @@
 paths:
   - "**/*.sh"
   - "**/*.bash"
-  - "**/hooks/*"
 ---
 # Bash
 
-Applies to `*.sh`, `*.bash`, `hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+Applies to `*.sh` and `*.bash`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
 workflows.
 
 ## Shape
diff --git a/AGENTS.md b/AGENTS.md
index e3b1109..0f814a0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
 
 ## This repository's own rules
 
-- The release is `bin/`, `tree/`, `targets/`, `bash/`, `hooks/`, and `version`. Everything in it is written for a
+- The release is `bin/`, `tree/`, `targets/`, `bash/`, and `version`. Everything in it is written for a
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
 - `version` is the version under development, with no suffix. A release is the tag `v<version>` on a commit on
   `main`. A pre-release is `v<version>-<suffix>` on a commit that is not on `main`. The release workflow refuses any
diff --git a/README.md b/README.md
index be62678..7dee207 100644
--- a/README.md
+++ b/README.md
@@ -20,21 +20,23 @@ mise install
 kit install claude
 ```
 
-`kit install` copies `.kit/1st.md` and `.kit/rules/` into the repository, places `.github/workflows/kit-ci.yml`,
-ignores `worktrees/`, points this clone's `core.hooksPath` at the release's hooks, and writes `.kit/manifest`. Each
-target named adds what that harness insists on having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and
-merges the kit's deny rules into `.claude/settings.json`. A repository with no target installed still binds every
-agent that reads `AGENTS.md`, through the rules table in `.kit/1st.md`. `kit target add` and `kit target remove`
-change the set later, and `kit target list` prints it. Commit what it wrote. Then:
+`kit install` copies `.kit/1st.md`, `.kit/rules/`, and `.kit/lefthook.yml` into the repository, places
+`.github/workflows/kit-ci.yml`, and writes `.kit/manifest`. Each target named adds what that harness insists on
+having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and merges the kit's deny rules into
+`.claude/settings.json`. A repository with no target installed still binds every agent that reads `AGENTS.md`,
+through the rules table in `.kit/1st.md`. `kit target add` and `kit target remove` change the set later, and
+`kit target list` prints it. Commit what it wrote. Then:
 
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
 - Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
   request not linked to an open issue.
-- In every other clone, run `kit setup` once to wire the hooks.
+- Pin `lefthook` in `mise.toml`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run `lefthook install`
+  once per clone. That runs `kit lint` over the staged paths before each commit, beside any hooks of your own. A
+  repository on another hook manager runs `kit lint` from it instead.
 
-The machinery, the `kit` command, the bash behind `kit issue`, `kit tidy`, and `kit status`, and the hooks, stays
-in the release where mise installed it; the repository carries the text an agent reads and the record of what it
-took. The kit needs bash 4.4 or later, git, `gh`, and `jq`.
+The machinery, the `kit` command and the bash behind its verbs, stays in the release where mise installed it; the
+repository carries the text an agent reads and the record of what it took. The kit needs bash 4.4 or later, git,
+`gh`, and `jq`.
 
 To move to a new release, bump the pin, run `mise install`, then `kit update`: a delivered file you left alone is
 replaced, one you edited is three-way merged with the previous release as the base, and your own deny entries
@@ -55,7 +57,7 @@ git config gpg.format openpgp
 git config user.signingkey "${signing_key}"
 git config commit.gpgsign true
 mise install
-bin/kit setup
+lefthook install
 ```
 
 This repository carries the installed copy of its own kit, and `just ci` checks it.
@@ -65,9 +67,10 @@ This repository carries the installed copy of its own kit, and `just ci` checks
 Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 - An issue exists. A change without an issue has not started.
-- `kit issue <N>`, here `bin/kit issue <N>`, makes `worktrees/<N>-<slug>`, links the branch to the issue under
-  Development, and opens a draft pull request. It never switches the checkout it runs from.
-- Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`.
+- `kit issue <N>` makes `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a
+  draft pull request. It never switches the checkout it runs from.
+- Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`. `kit rebase`
+  brings the branch up to date with `main` and pushes it.
 - `just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
   `bin/kit check`.
 - `gh pr ready` says the work is done, and the pull request body is the report.
@@ -77,14 +80,15 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
 every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
-the same way; `bash/`, `hooks/`, and `version` are the machinery `bin/kit` runs. A symlink under `targets/` is
+the same way; `bin/`, `bash/`, and `version` are the machinery: `bin/kit` dispatches to one `bin/kit-<verb>.bash`
+per verb, and `bash/` holds the modules they source. A symlink under `targets/` is
 delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
 
 The installed copies are written by `bin/kit install` and not edited by hand:
 
 | Installed copy | Written from |
 | --- | --- |
-| `.kit/1st.md`, `.kit/rules/` | `tree/.kit/` |
+| `.kit/1st.md`, `.kit/rules/`, `.kit/lefthook.yml` | `tree/.kit/` |
 | `.github/workflows/kit-ci.yml` | `tree/.github/workflows/kit-ci.yml` |
 | `.claude/rules/kit-<kind>.md` | `targets/claude/.claude/rules/`, links into `tree/.kit/rules/` |
 | `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here it carries only the kit's entries |
diff --git a/bash/1st.sh b/bash/1st.sh
index e7dcd0b..2632223 100644
--- a/bash/1st.sh
+++ b/bash/1st.sh
@@ -2,7 +2,7 @@
 # 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Sourced by bin/kit, whose issue, tidy, and status run the bash under bash/, and by the hooks that need a verb. It defines functions only and sets no shell option, so the caller's options stand. A module under
+# Sourced by every verb, bin/kit-<verb>.bash, which bin/kit dispatches to with kit_root exported. It defines functions only and sets no shell option, so the caller's options stand. A module under
 # bash/ is loaded on first use with `use <module>`, and each exported function has a stub here so a
 # caller never has to load it by hand.
 #
diff --git a/bash/gh.sh b/bash/gh.sh
index e79a1fe..a4ef4b3 100644
--- a/bash/gh.sh
+++ b/bash/gh.sh
@@ -156,11 +156,6 @@ gh:issue() {
     fi
   fi
 
-  # shellcheck disable=SC2154  # kit_bash_dir is set by the loader, 1st.sh, which sources this file
-  if [[ "$(git config core.hooksPath 2>/dev/null)" != "$(cd "${kit_bash_dir}/.." && pwd)/hooks" ]]
-  then
-    warn "run: kit setup (core.hooksPath does not name this release's hooks, so the desk guard is off in this clone)"
-  fi
   if ! git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null
   then
     warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a status or a commit"
diff --git a/bash/kit.sh b/bash/kit.sh
new file mode 100644
index 0000000..6dfc7ae
--- /dev/null
+++ b/bash/kit.sh
@@ -0,0 +1,161 @@
+# shellcheck shell=bash
+# shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
+# shellcheck disable=SC2154  # kit_root is exported by bin/kit
+# kit.sh - the release's layout, the one merge rule, and the manifest (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# A release mirrors its tree/ at the repository root, and targets/<name>/ for each target taken; a symlink in
+# either is delivered as the file it points at. A destination ending in .json is merged by key, with the kit's
+# keys set, the kit's array entries added, and on update or removal only the previous release's entries taken
+# out. .kit/manifest records the version, the targets, and the release's digest for every delivered path.
+#
+# Every function reads the release from kit_root, exported by bin/kit.
+
+# kit:layers <root> <target>… prints the directories mirrored at the repository root, tree first.
+kit:layers() {
+  local root=$1 t
+  shift
+  printf '%s\n' "${root}/tree"
+  for t in "$@"
+  do
+    printf '%s\n' "${root}/targets/${t}"
+  done
+}
+
+# kit:delivered <root> <target>… prints every repository path the release at <root> delivers for those targets.
+kit:delivered() {
+  local layer
+  while IFS= read -r layer
+  do
+    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@')
+  done < <(kit:layers "$@") | sort --unique
+}
+
+# kit:source-of <root> <path> <target>… prints the release file behind a repository path, the last layer winning.
+kit:source-of() {
+  local root=$1 path=$2 layer found=""
+  shift 2
+  while IFS= read -r layer
+  do
+    [[ -e "${layer}/${path}" ]] && found="${layer}/${path}"
+  done < <(kit:layers "${root}" "$@")
+  [[ -n "${found}" ]] && printf '%s\n' "${found}"
+}
+
+# kit:target-only <target> prints the paths the target delivers that tree/ does not.
+kit:target-only() {
+  comm -13 <(kit:delivered "${kit_root}") <(kit:delivered "${kit_root}" "$1")
+}
+
+# kit:known-targets prints the targets this release carries.
+kit:known-targets() {
+  (cd "${kit_root}/targets" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
+}
+
+# kit:require-targets <name>… refuses a target this release does not carry, naming the ones it does.
+kit:require-targets() {
+  local t
+  for t in "$@"
+  do
+    if [[ ! -d "${kit_root}/targets/${t}" ]]
+    then
+      error "'${t}' is not a target this release knows; the targets are: $(kit:known-targets | paste -s -d ' ' -)"
+      return 2
+    fi
+  done
+}
+
+kit:merged() { [[ "$1" == *.json ]]; }
+
+# The parameters are values ($), not filters: a filter parameter is re-read against the input at each use, which
+# inside the recursion is the wrong level of the object.
+kit_jq='
+  def merge($cur; $base; $new):
+    if ($new | type) == "object" then
+      reduce ($new | keys[]) as $k ($cur // {}; .[$k] = merge(($cur // {})[$k]; ($base // {})[$k]; $new[$k]))
+    elif ($new | type) == "array" then
+      ((($cur // []) - ($base // [])) as $kept | $kept + ($new - $kept))
+    else $new end;
+  def unmerge($cur; $base):
+    if ($base | type) == "object" then
+      reduce ($base | keys[]) as $k ($cur; if has($k) then .[$k] = unmerge($cur[$k]; $base[$k]) else . end)
+    elif ($base | type) == "array" then ($cur // []) - $base
+    else $cur end;
+  def holds($cur; $new):
+    if ($new | type) == "object" then
+      all($new | keys[]; . as $k | ($cur | type) == "object" and ($cur | has($k)) and holds($cur[$k]; $new[$k]))
+    elif ($new | type) == "array" then all($new[]; . as $e | any(($cur // [])[]; . == $e))
+    else $cur == $new end;
+'
+
+# kit:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if missing.
+kit:json-write() {
+  local path=$1 filter=$2
+  shift 2
+  mkdir -p "$(dirname "${path}")"
+  [[ -f "${path}" ]] || printf '{}\n' > "${path}"
+  jq --indent 2 "${kit_jq} ${filter}" "$@" "${path}" > "${path}.kit-new"
+  mv "${path}.kit-new" "${path}"
+}
+
+# kit:json-holds <path> <source> is true when the JSON at <path> carries every entry the release's <source> writes.
+kit:json-holds() {
+  jq --exit-status "${kit_jq} holds(.; \$new[0])" --slurpfile new "$2" "$1" >/dev/null
+}
+
+# kit:digest prints the sha256 of stdin, by whichever tool the machine carries.
+kit:digest() {
+  if command -v sha256sum >/dev/null 2>&1
+  then
+    sha256sum | cut -d ' ' -f 1
+  else
+    shasum -a 256 | cut -d ' ' -f 1
+  fi
+}
+
+# kit:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, a copy otherwise.
+kit:place() {
+  local src=$1 path=$2 base=${3:-/dev/null}
+  if kit:merged "${path}"
+  then
+    kit:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
+  else
+    mkdir -p "$(dirname "${path}")"
+    cat "${src}" > "${path}.kit-new"
+    mv "${path}.kit-new" "${path}"
+  fi
+}
+
+# kit:write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
+kit:write-manifest() {
+  local path
+  {
+    printf '# .kit/manifest - written by kit, not by hand\n'
+    printf 'version %s\n' "$(cat "${kit_root}/version")"
+    printf 'targets%s\n' "${*:+ $*}"
+    while IFS= read -r path
+    do
+      printf '%s  %s\n' "$(kit:digest < "$(kit:source-of "${kit_root}" "${path}" "$@")")" "${path}"
+    done < <(kit:delivered "${kit_root}" "$@")
+  } > .kit/manifest
+}
+
+kit:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
+kit:manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
+
+# kit:require-manifest refuses to go on in a repository that never took the kit.
+kit:require-manifest() {
+  if [[ ! -f .kit/manifest ]]
+  then
+    error "run: kit install (this repository carries no .kit/manifest)"
+    return 1
+  fi
+}
+
+# kit:finish <target>… reports a completed install or update.
+kit:finish() {
+  ok "kit $(cat "${kit_root}/version") is installed, targets: ${*:-none}; .kit/manifest is written."
+  step "Commit the delivered files. The loop is in .kit/1st.md."
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit b/bin/kit
index 637a891..1d4e3bc 100755
--- a/bin/kit
+++ b/bin/kit
@@ -1,18 +1,9 @@
 #!/usr/bin/env bash
-# shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
-# kit - install, update, and check the kit in a repository (executed entrypoint)
+# kit - the kit's command: each verb is the executable bin/kit-<verb>.bash beside it (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The release is the directory above bin/. Its tree/ is mirrored at the repository root, verbatim, and so is
-# targets/<name>/ for each target the repository takes; a symlink in either is copied as the file it points at.
-# bash/, hooks/, and version are the machinery and stay in the release. The one exception to a verbatim copy is a
-# destination ending in .json, which is merged by key: the kit's keys are set, the kit's array entries are added,
-# and on update or removal only the entries the previous release wrote are taken out, so the rest of the file is
-# the repository's.
-#
-# .kit/manifest records the release version, the targets taken, and the release's digest for every delivered
-# path. An update tells an untouched file from an edited one by that digest, and merges the edited one with the
-# previous release as the base. KIT_BASE=<dir> names that release's root on a machine without mise.
+# The release is the directory above bin/. This file resolves it, exports it as kit_root, and hands the verb its
+# arguments. Everything else, the usage text included, lives with the verb.
 #
 # see: .kit/1st.md
 
@@ -25,418 +16,37 @@ then
 fi
 
 kit_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
-# shellcheck source=bash/1st.sh
-source "${kit_root}/bash/1st.sh"
-
-usage() {
-  cat >&2 <<'USAGE'
-usage: kit <command>
-
-  install [<target>…]     mirror tree/ and each named target into the repository, wire this clone's hooks,
-                          and write .kit/manifest
-  update                  after the pin is bumped: replace unchanged files, three-way merge changed ones
-  check                   fail when a delivered file differs from this release
-  setup                   wire this clone: core.hooksPath to this release's hooks
-  target list             print the targets this repository takes
-  target add <target>…    take a target: mirror its directory and record it
-  target remove <target>… drop a target: remove its files and the kit's entries from its settings
-  issue [<number>…]       start or resume an issue: linked branch, worktree, start commit, draft pull request
-  tidy [--dry-run]        remove worktrees whose pull request is merged or closed, and gone branches
-  status [--no-fetch]     show every worktree with its branch, pull request, and state
-  version                 print this release's version
+export kit_root
+
+verb=${1:-help}
+case "${verb}" in
+  (help | -h | --help)
+    cat <<'USAGE'
+usage: kit <verb> [<argument>…]
+
+  install [<target>…]   mirror the release into the repository, take the named targets, write .kit/manifest
+  update                after the pin is bumped: replace unchanged files, three-way merge changed ones
+  check                 fail when a delivered file differs from the pinned release
+  target <list|add|remove> [<target>…]
+                        the targets this repository takes
+  issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
+  rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the default branch
+  tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
+  status [--no-fetch]   show every worktree with its branch, pull request, and state
+  lint [<path>…]        lint the staged paths, or the paths given; a missing linter is a reported skip
+  version               print this release's version
+
+Each verb answers --help.
 USAGE
-}
-
-# ── the release's layout ───────────────────────────────────────────────────────────────────────────────────────────────
-
-# layers <root> <target>… prints the directories mirrored at the repository root, tree first.
-layers() {
-  local root=$1 t
-  shift
-  printf '%s\n' "${root}/tree"
-  for t in "$@"
-  do
-    printf '%s\n' "${root}/targets/${t}"
-  done
-}
-
-# delivered <root> <target>… prints every repository path the release at <root> delivers for those targets.
-delivered() {
-  local layer
-  while IFS= read -r layer
-  do
-    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@')
-  done < <(layers "$@") | sort --unique
-}
-
-# source-of <root> <path> <target>… prints the release file behind a repository path, the last layer winning.
-source-of() {
-  local root=$1 path=$2 layer found=""
-  shift 2
-  while IFS= read -r layer
-  do
-    [[ -e "${layer}/${path}" ]] && found="${layer}/${path}"
-  done < <(layers "${root}" "$@")
-  [[ -n "${found}" ]] && printf '%s\n' "${found}"
-}
-
-# known-targets prints the targets this release carries.
-known-targets() {
-  (cd "${kit_root}/targets" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
-}
-
-# require-targets <name>… refuses a target this release does not carry, naming the ones it does.
-require-targets() {
-  local t
-  for t in "$@"
-  do
-    if [[ ! -d "${kit_root}/targets/${t}" ]]
-    then
-      error "'${t}' is not a target this release knows; the targets are: $(known-targets | paste -s -d ' ' -)"
-      return 2
-    fi
-  done
-}
-
-# target-only <target> prints the paths the target delivers that tree/ does not.
-target-only() {
-  comm -13 <(delivered "${kit_root}") <(delivered "${kit_root}" "$1")
-}
-
-merged() { [[ "$1" == *.json ]]; }
-
-# ── the one merge rule, for a .json destination ─────────────────────────────────────────────────────────────────────────
-
-# The parameters are values ($), not filters: a filter parameter is re-read against the input at each use, which
-# inside the recursion is the wrong level of the object.
-jq_lib='
-  def merge($cur; $base; $new):
-    if ($new | type) == "object" then
-      reduce ($new | keys[]) as $k ($cur // {}; .[$k] = merge(($cur // {})[$k]; ($base // {})[$k]; $new[$k]))
-    elif ($new | type) == "array" then
-      ((($cur // []) - ($base // [])) as $kept | $kept + ($new - $kept))
-    else $new end;
-  def unmerge($cur; $base):
-    if ($base | type) == "object" then
-      reduce ($base | keys[]) as $k ($cur; if has($k) then .[$k] = unmerge($cur[$k]; $base[$k]) else . end)
-    elif ($base | type) == "array" then ($cur // []) - $base
-    else $cur end;
-  def holds($cur; $new):
-    if ($new | type) == "object" then
-      all($new | keys[]; . as $k | ($cur | type) == "object" and ($cur | has($k)) and holds($cur[$k]; $new[$k]))
-    elif ($new | type) == "array" then all($new[]; . as $e | any(($cur // [])[]; . == $e))
-    else $cur == $new end;
-'
-
-# json-write <path> <filter> rewrites the JSON at <path> through <filter>, making the file if it is missing.
-json-write() {
-  local path=$1 filter=$2
-  shift 2
-  mkdir -p "$(dirname "${path}")"
-  [[ -f "${path}" ]] || printf '{}\n' > "${path}"
-  jq --indent 2 "${jq_lib} ${filter}" "$@" "${path}" > "${path}.kit-new"
-  mv "${path}.kit-new" "${path}"
-}
-
-# ── placing, recording, wiring ──────────────────────────────────────────────────────────────────────────────────────────
-
-digest() {
-  if command -v sha256sum >/dev/null 2>&1
-  then
-    sha256sum | cut -d ' ' -f 1
-  else
-    shasum -a 256 | cut -d ' ' -f 1
-  fi
-}
-
-# place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, a copy otherwise.
-place() {
-  local src=$1 path=$2 base=${3:-/dev/null}
-  if merged "${path}"
-  then
-    json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
-  else
-    mkdir -p "$(dirname "${path}")"
-    cat "${src}" > "${path}.kit-new"
-    mv "${path}.kit-new" "${path}"
-  fi
-}
-
-# write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
-write-manifest() {
-  local path
-  {
-    printf '# .kit/manifest - written by kit, not by hand\n'
-    printf 'version %s\n' "$(cat "${kit_root}/version")"
-    printf 'targets%s\n' "${*:+ $*}"
-    while IFS= read -r path
-    do
-      printf '%s  %s\n' "$(digest < "$(source-of "${kit_root}" "${path}" "$@")")" "${path}"
-    done < <(delivered "${kit_root}" "$@")
-  } > .kit/manifest
-}
-
-manifest-version() { sed -n 's/^version //p' .kit/manifest; }
-manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
-
-require-manifest() {
-  if [[ ! -f .kit/manifest ]]
-  then
-    error "run: kit install (this repository carries no .kit/manifest)"
-    return 1
-  fi
-}
-
-wire-hooks() {
-  git config core.hooksPath "${kit_root}/hooks"
-}
-
-finish() {
-  wire-hooks
-  ok "kit $(cat "${kit_root}/version") is installed, targets: ${*:-none}. core.hooksPath is ${kit_root}/hooks, and .kit/manifest is written."
-  step "Commit the delivered files. The loop is in .kit/1st.md."
-}
-
-# ── commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-cmd-install() {
-  guard:require tool:jq tool:git
-  require-targets "$@"
-  if [[ -f .kit/manifest ]]
-  then
-    error "run: kit update (this repository already carries kit $(manifest-version))"
-    return 1
-  fi
-  section "kit install $(cat "${kit_root}/version")${*:+, targets: $*}"
-  local path
-  while IFS= read -r path
-  do
-    step "${path}"
-    place "$(source-of "${kit_root}" "${path}" "$@")" "${path}"
-  done < <(delivered "${kit_root}" "$@")
-  write-manifest "$@"
-  finish "$@"
-}
-
-cmd-update() {
-  guard:require tool:jq tool:git
-  require-manifest
-  local previous current base_root="" path src base recorded conflicts=0
-  local -a targets
-  read -r -a targets <<<"$(manifest-targets)"
-  previous=$(manifest-version)
-  current=$(cat "${kit_root}/version")
-  section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
-
-  # The previous release is the base of every merge. KIT_BASE names its root; otherwise mise knows where it is.
-  if [[ -n "${KIT_BASE:-}" ]]
-  then
-    base_root=${KIT_BASE}
-  elif [[ "${previous}" != "${current}" ]] && command -v mise >/dev/null 2>&1
-  then
-    base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
-    if [[ -z "${base_root}" ]] && mise install --quiet "github:empowerite/kit@${previous}" 2>/dev/null
-    then
-      base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
-    fi
-  fi
-
-  while IFS= read -r path
-  do
-    src=$(source-of "${kit_root}" "${path}" "${targets[@]}")
-    base=""
-    [[ -n "${base_root}" ]] && base=$(source-of "${base_root}" "${path}" "${targets[@]}" || true)
-    if merged "${path}"
-    then
-      step "${path}: merged by key"
-      place "${src}" "${path}" "${base}"
-      continue
-    fi
-    if [[ ! -f "${path}" ]]
-    then
-      step "${path}: missing, written"
-      place "${src}" "${path}"
-      continue
-    fi
-    recorded=$(awk -v p="${path}" '$2==p{print $1}' .kit/manifest)
-    if [[ -z "${recorded}" || "${recorded}" == "$(digest < "${path}")" ]]
-    then
-      step "${path}: unchanged since ${previous}, replaced"
-      place "${src}" "${path}"
-      continue
-    fi
-    if [[ -z "${base}" ]]
-    then
-      error "${path} was edited and the base release ${previous} is not installed; run: mise install github:empowerite/kit@${previous}"
-      conflicts=$(( conflicts + 1 ))
-      continue
-    fi
-    step "${path}: edited since ${previous}, three-way merged"
-    if ! git merge-file --marker-size 7 "${path}" "${base}" "${src}"
-    then
-      warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
-      conflicts=$(( conflicts + 1 ))
-    fi
-  done < <(delivered "${kit_root}" "${targets[@]}")
-
-  write-manifest "${targets[@]}"
-  if (( conflicts > 0 ))
-  then
-    error "${conflicts} file(s) need a hand; see above."
-    return 1
-  fi
-  finish "${targets[@]}"
-}
-
-cmd-check() {
-  require-manifest
-  local path src findings=0 version
-  local -a targets
-  read -r -a targets <<<"$(manifest-targets)"
-  version=$(manifest-version)
-  if [[ "${version}" != "$(cat "${kit_root}/version")" ]]
-  then
-    error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${kit_root}/version"); run: kit update"
-    findings=$(( findings + 1 ))
-  fi
-  while IFS= read -r path
-  do
-    src=$(source-of "${kit_root}" "${path}" "${targets[@]}")
-    if [[ ! -f "${path}" ]]
-    then
-      error "${path} is missing"
-      findings=$(( findings + 1 ))
-    elif merged "${path}"
-    then
-      if ! command -v jq >/dev/null 2>&1
-      then
-        error "run: mise install (jq is not on PATH, so ${path} could not be read)"
-        findings=$(( findings + 1 ))
-      elif ! jq --exit-status "${jq_lib} holds(.; \$new[0])" --slurpfile new "${src}" "${path}" >/dev/null
-      then
-        error "${path} is missing an entry the kit writes; run: kit update"
-        findings=$(( findings + 1 ))
-      fi
-    elif ! cmp --silent "${src}" "${path}"
+    ;;
+  (*)
+    if [[ ! -x "${kit_root}/bin/kit-${verb}.bash" ]]
     then
-      error "${path} differs from the pinned release"
-      findings=$(( findings + 1 ))
+      echo "kit: unknown verb '${verb}'; run: kit help" >&2
+      exit 2
     fi
-  done < <(delivered "${kit_root}" "${targets[@]}")
-  if (( findings > 0 ))
-  then
-    error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
-    return 1
-  fi
-  ok "kit ${version}, targets ${targets[*]:-none}: every delivered file matches the pinned release."
-}
-
-cmd-setup() {
-  guard:require tool:git
-  wire-hooks
-  ok "core.hooksPath is ${kit_root}/hooks"
-  if [[ -z "$(git config user.signingkey 2>/dev/null)" ]]
-  then
-    warn "no signing key is configured in this clone, and the ruleset refuses an unsigned commit; see README.md § Setup"
-  fi
-}
-
-cmd-target() {
-  local verb=${1:-list} t path src
-  local -a targets kept
-  shift || true
-  require-manifest
-  read -r -a targets <<<"$(manifest-targets)"
-  case "${verb}" in
-    (list)
-      printf '%s\n' "${targets[@]}"
-      ;;
-    (add)
-      (( $# > 0 )) || { error "usage: kit target add <target>…"; return 2; }
-      guard:require tool:jq tool:git
-      require-targets "$@"
-      for t in "$@"
-      do
-        if [[ " ${targets[*]} " == *" ${t} "* ]]
-        then
-          step "${t}: already taken"
-          continue
-        fi
-        section "kit target add ${t}"
-        while IFS= read -r path
-        do
-          step "${path}"
-          place "${kit_root}/targets/${t}/${path}" "${path}"
-        done < <(target-only "${t}")
-        targets+=("${t}")
-      done
-      write-manifest "${targets[@]}"
-      ok "targets: ${targets[*]}"
-      ;;
-    (remove)
-      (( $# > 0 )) || { error "usage: kit target remove <target>…"; return 2; }
-      guard:require tool:jq tool:git
-      require-targets "$@"
-      for t in "$@"
-      do
-        if [[ " ${targets[*]} " != *" ${t} "* ]]
-        then
-          step "${t}: not taken"
-          continue
-        fi
-        section "kit target remove ${t}"
-        while IFS= read -r path
-        do
-          src="${kit_root}/targets/${t}/${path}"
-          if merged "${path}"
-          then
-            [[ -f "${path}" ]] || continue
-            step "${path}: the kit's entries taken out"
-            json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
-          else
-            step "removing ${path}"
-            rm -f "${path}"
-          fi
-        done < <(target-only "${t}")
-        kept=()
-        for path in "${targets[@]}"
-        do
-          [[ "${path}" == "${t}" ]] || kept+=("${path}")
-        done
-        targets=("${kept[@]}")
-      done
-      write-manifest "${targets[@]}"
-      ok "targets: ${targets[*]:-none}"
-      ;;
-    (*)
-      error "kit target: unknown verb '${verb}' (list, add, remove)"
-      return 2
-  esac
-}
-
-cmd-loop() {
-  local verb=$1
-  shift
-  case "${verb}" in
-    (issue)  gh:issue "$@" ;;
-    (tidy)   git:tidy "$@" ;;
-    (status) git:status "$@" ;;
-  esac
-}
-
-case "${1:-}" in
-  (install) shift; cmd-install "$@" ;;
-  (update)  cmd-update ;;
-  (check)   cmd-check ;;
-  (setup)   cmd-setup ;;
-  (target)  shift; cmd-target "$@" ;;
-  (issue | tidy | status) cmd-loop "$@" ;;
-  (version) cat "${kit_root}/version" ;;
-  (-h | --help | help | "") usage; [[ -n "${1:-}" ]] ;;
-  (*)
-    error "kit: unknown command '$1'"
-    usage
-    exit 2
+    shift
+    exec "${kit_root}/bin/kit-${verb}.bash" "$@"
 esac
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-check.bash b/bin/kit-check.bash
new file mode 100755
index 0000000..6225b80
--- /dev/null
+++ b/bin/kit-check.bash
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# kit-check - fail when a delivered file differs from the pinned release (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bash/kit.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use kit
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit check" >&2
+  exit 0
+fi
+
+kit:require-manifest
+read -r -a targets <<<"$(kit:manifest-targets)"
+version=$(kit:manifest-version)
+findings=0
+if [[ "${version}" != "$(cat "${kit_root}/version")" ]]
+then
+  error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${kit_root}/version"); run: kit update"
+  findings=$(( findings + 1 ))
+fi
+while IFS= read -r path
+do
+  src=$(kit:source-of "${kit_root}" "${path}" "${targets[@]}")
+  if [[ ! -f "${path}" ]]
+  then
+    error "${path} is missing"
+    findings=$(( findings + 1 ))
+  elif kit:merged "${path}"
+  then
+    if ! command -v jq >/dev/null 2>&1
+    then
+      error "run: mise install (jq is not on PATH, so ${path} could not be read)"
+      findings=$(( findings + 1 ))
+    elif ! kit:json-holds "${path}" "${src}"
+    then
+      error "${path} is missing an entry the kit writes; run: kit update"
+      findings=$(( findings + 1 ))
+    fi
+  elif ! cmp --silent "${src}" "${path}"
+  then
+    error "${path} differs from the pinned release"
+    findings=$(( findings + 1 ))
+  fi
+done < <(kit:delivered "${kit_root}" "${targets[@]}")
+if (( findings > 0 ))
+then
+  error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
+  exit 1
+fi
+ok "kit ${version}, targets ${targets[*]:-none}: every delivered file matches the pinned release."
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-install.bash b/bin/kit-install.bash
new file mode 100755
index 0000000..5bbfa87
--- /dev/null
+++ b/bin/kit-install.bash
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# kit-install - mirror the release into the repository, take the named targets, and write .kit/manifest (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bash/kit.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use kit
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit install [<target>…]" >&2
+  exit 0
+fi
+
+guard:require tool:jq tool:git
+kit:require-targets "$@"
+if [[ -f .kit/manifest ]]
+then
+  error "run: kit update (this repository already carries kit $(kit:manifest-version))"
+  exit 1
+fi
+section "kit install $(cat "${kit_root}/version")${*:+, targets: $*}"
+while IFS= read -r path
+do
+  step "${path}"
+  kit:place "$(kit:source-of "${kit_root}" "${path}" "$@")" "${path}"
+done < <(kit:delivered "${kit_root}" "$@")
+kit:write-manifest "$@"
+kit:finish "$@"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-issue.bash b/bin/kit-issue.bash
new file mode 100755
index 0000000..422d993
--- /dev/null
+++ b/bin/kit-issue.bash
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# kit-issue - start or resume an issue: linked branch, worktree, start commit, draft pull request (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bash/gh.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use gh
+
+if [[ "${1:-}" == --help ]]
+then
+  sed -n '2s/^# kit-[a-z]* - \(.*\) (kit verb, run through bin/kit)$/\1/p' "${BASH_SOURCE[0]}" >&2
+  exit 0
+fi
+
+gh:issue "$@"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-lint.bash b/bin/kit-lint.bash
new file mode 100755
index 0000000..62d85de
--- /dev/null
+++ b/bin/kit-lint.bash
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# kit-lint - lint the staged paths, or the paths given; a missing linter is a reported skip (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The body of a pre-commit hook, whatever runs the hook: shellcheck over bash, actionlint over workflows, and
+# markdownlint-cli2 over markdown when the repository carries a config for it. A linter that is not on PATH is a
+# reported skip, never a silent pass and never a refusal: lint is not the enforcement of record. The working
+# tree's copy of each path is linted, so a partial add can be told about a line the commit does not carry.
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit lint [<path>…]    (no path: the staged paths)" >&2
+  exit 0
+fi
+
+paths=()
+if (( $# > 0 ))
+then
+  paths=("$@")
+else
+  while IFS= read -r -d '' path
+  do
+    paths+=("${path}")
+  done < <(git diff --cached --name-only --diff-filter=ACMR -z)
+fi
+
+bash_paths=()
+workflow_paths=()
+markdown_paths=()
+for path in "${paths[@]}"
+do
+  [[ -f "${path}" ]] || continue
+  case "${path}" in
+    (*.sh | *.bash) bash_paths+=("${path}") ;;
+    (.github/workflows/*.yml | .github/workflows/*.yaml) workflow_paths+=("${path}") ;;
+    (*.md) markdown_paths+=("${path}")
+  esac
+done
+
+findings=0
+run-linter() {  # <linter> <what> <path>…  runs the linter over the paths, or reports the skip
+  local linter=$1 what=$2
+  shift 2
+  if ! command -v "${linter}" >/dev/null 2>&1
+  then
+    warn "${linter} is not on PATH, so the ${what} were NOT linted"
+    return 0
+  fi
+  "${linter}" "$@" || findings=$(( findings + 1 ))
+}
+(( ${#bash_paths[@]} == 0 ))     || run-linter shellcheck "bash files" --shell=bash --external-sources "${bash_paths[@]}"
+(( ${#workflow_paths[@]} == 0 )) || run-linter actionlint workflows "${workflow_paths[@]}"
+if (( ${#markdown_paths[@]} > 0 )) && compgen -G ".markdownlint-cli2.*" >/dev/null
+then
+  run-linter markdownlint-cli2 "markdown files" "${markdown_paths[@]}"
+fi
+
+if (( findings > 0 ))
+then
+  error "a linter found something in ${findings} group(s) of paths; each finding above names the file and line."
+  exit 1
+fi
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-rebase.bash b/bin/kit-rebase.bash
new file mode 100755
index 0000000..ce17251
--- /dev/null
+++ b/bin/kit-rebase.bash
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# kit-rebase - rebase a worktree's branch onto the default branch and push it; never the default branch (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The default branch is the human's desk and is never rebased by an agent: this verb refuses it, and 1st.md says an
+# agent spells a rebase this way and no other. Any other branch is rebased onto origin/<default> and pushed with
+# --force-with-lease, which fails rather than overwrite a push that landed since. On a conflict the rebase is
+# aborted and the worktree left as it was.
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit rebase [<path>]    (no path: the checkout this runs in)" >&2
+  exit 0
+fi
+
+guard:require tool:git
+worktree=${1:-.}
+branch=$(git -C "${worktree}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+if [[ -z "${branch}" ]]
+then
+  error "${worktree} has no branch checked out, so there is nothing to rebase"
+  exit 1
+fi
+default_branch=$(git -C "${worktree}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+[[ -n "${default_branch}" ]] || default_branch=main
+if [[ "${branch}" == "${default_branch}" ]]
+then
+  error "refusing to rebase ${branch}: it is the default branch, the human's desk. It advances by fast-forward: git pull --ff-only"
+  exit 1
+fi
+
+section "kit rebase ${branch} onto origin/${default_branch}"
+git -C "${worktree}" fetch --quiet --prune origin
+if ! git -C "${worktree}" rebase --quiet "origin/${default_branch}"
+then
+  git -C "${worktree}" rebase --abort
+  error "${branch} conflicts with origin/${default_branch}; the rebase was aborted and the worktree is as it was. Resolve by hand."
+  exit 1
+fi
+git -C "${worktree}" push --quiet --force-with-lease
+ok "${branch} is rebased onto origin/${default_branch} and pushed."
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-status.bash b/bin/kit-status.bash
new file mode 100755
index 0000000..2e48cb2
--- /dev/null
+++ b/bin/kit-status.bash
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# kit-status - show every worktree with its branch, pull request, and state (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bash/git.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use git
+
+if [[ "${1:-}" == --help ]]
+then
+  sed -n '2s/^# kit-[a-z]* - \(.*\) (kit verb, run through bin/kit)$/\1/p' "${BASH_SOURCE[0]}" >&2
+  exit 0
+fi
+
+git:status "$@"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-target.bash b/bin/kit-target.bash
new file mode 100755
index 0000000..05a3aa2
--- /dev/null
+++ b/bin/kit-target.bash
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# kit-target - list, take, or drop the targets this repository takes (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bash/kit.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use kit
+
+usage() { echo "usage: kit target list | kit target add <target>… | kit target remove <target>…" >&2; }
+
+verb=${1:-list}
+shift || true
+case "${verb}" in
+  (--help) usage; exit 0 ;;
+  (list | add | remove) ;;
+  (*) usage; exit 2
+esac
+kit:require-manifest
+read -r -a targets <<<"$(kit:manifest-targets)"
+
+case "${verb}" in
+  (list)
+    printf '%s\n' "${targets[@]}"
+    ;;
+  (add)
+    (( $# > 0 )) || { usage; exit 2; }
+    guard:require tool:jq tool:git
+    kit:require-targets "$@"
+    for t in "$@"
+    do
+      if [[ " ${targets[*]} " == *" ${t} "* ]]
+      then
+        step "${t}: already taken"
+        continue
+      fi
+      section "kit target add ${t}"
+      while IFS= read -r path
+      do
+        step "${path}"
+        kit:place "${kit_root}/targets/${t}/${path}" "${path}"
+      done < <(kit:target-only "${t}")
+      targets+=("${t}")
+    done
+    kit:write-manifest "${targets[@]}"
+    ok "targets: ${targets[*]}"
+    ;;
+  (remove)
+    (( $# > 0 )) || { usage; exit 2; }
+    guard:require tool:jq tool:git
+    kit:require-targets "$@"
+    for t in "$@"
+    do
+      if [[ " ${targets[*]} " != *" ${t} "* ]]
+      then
+        step "${t}: not taken"
+        continue
+      fi
+      section "kit target remove ${t}"
+      while IFS= read -r path
+      do
+        src="${kit_root}/targets/${t}/${path}"
+        if kit:merged "${path}"
+        then
+          [[ -f "${path}" ]] || continue
+          step "${path}: the kit's entries taken out"
+          # shellcheck disable=SC2016  # a jq filter, with jq variables
+          kit:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
+        else
+          step "removing ${path}"
+          rm -f "${path}"
+        fi
+      done < <(kit:target-only "${t}")
+      kept=()
+      for path in "${targets[@]}"
+      do
+        [[ "${path}" == "${t}" ]] || kept+=("${path}")
+      done
+      targets=("${kept[@]}")
+    done
+    kit:write-manifest "${targets[@]}"
+    ok "targets: ${targets[*]:-none}"
+esac
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-tidy.bash b/bin/kit-tidy.bash
new file mode 100755
index 0000000..fd2e5e1
--- /dev/null
+++ b/bin/kit-tidy.bash
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# kit-tidy - remove worktrees whose pull request is merged or closed, and gone branches (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bash/git.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use git
+
+if [[ "${1:-}" == --help ]]
+then
+  sed -n '2s/^# kit-[a-z]* - \(.*\) (kit verb, run through bin/kit)$/\1/p' "${BASH_SOURCE[0]}" >&2
+  exit 0
+fi
+
+git:tidy "$@"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-update.bash b/bin/kit-update.bash
new file mode 100755
index 0000000..9e0a4bb
--- /dev/null
+++ b/bin/kit-update.bash
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# kit-update - after the pin is bumped: replace unchanged files, three-way merge changed ones (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# An untouched file is one whose digest still matches the manifest, which records the previous release's own
+# content; it is replaced. An edited one is merged with the previous release as the base: KIT_BASE=<dir> names
+# that release's root, otherwise mise knows where it installed it.
+#
+# see: bash/kit.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bash/1st.sh
+source "${kit_root:?run through bin/kit}/bash/1st.sh"
+use kit
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit update" >&2
+  exit 0
+fi
+
+guard:require tool:jq tool:git
+kit:require-manifest
+read -r -a targets <<<"$(kit:manifest-targets)"
+previous=$(kit:manifest-version)
+current=$(cat "${kit_root}/version")
+section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
+
+base_root=""
+if [[ -n "${KIT_BASE:-}" ]]
+then
+  base_root=${KIT_BASE}
+elif [[ "${previous}" != "${current}" ]] && command -v mise >/dev/null 2>&1
+then
+  base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
+  if [[ -z "${base_root}" ]] && mise install --quiet "github:empowerite/kit@${previous}" 2>/dev/null
+  then
+    base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
+  fi
+fi
+
+conflicts=0
+while IFS= read -r path
+do
+  src=$(kit:source-of "${kit_root}" "${path}" "${targets[@]}")
+  base=""
+  [[ -n "${base_root}" ]] && base=$(kit:source-of "${base_root}" "${path}" "${targets[@]}" || true)
+  if kit:merged "${path}"
+  then
+    step "${path}: merged by key"
+    kit:place "${src}" "${path}" "${base}"
+    continue
+  fi
+  if [[ ! -f "${path}" ]]
+  then
+    step "${path}: missing, written"
+    kit:place "${src}" "${path}"
+    continue
+  fi
+  recorded=$(awk -v p="${path}" '$2==p{print $1}' .kit/manifest)
+  if [[ -z "${recorded}" || "${recorded}" == "$(kit:digest < "${path}")" ]]
+  then
+    step "${path}: unchanged since ${previous}, replaced"
+    kit:place "${src}" "${path}"
+    continue
+  fi
+  if [[ -z "${base}" ]]
+  then
+    error "${path} was edited and the base release ${previous} is not installed; run: mise install github:empowerite/kit@${previous}"
+    conflicts=$(( conflicts + 1 ))
+    continue
+  fi
+  step "${path}: edited since ${previous}, three-way merged"
+  if ! git merge-file --marker-size 7 "${path}" "${base}" "${src}"
+  then
+    warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
+    conflicts=$(( conflicts + 1 ))
+  fi
+done < <(kit:delivered "${kit_root}" "${targets[@]}")
+
+kit:write-manifest "${targets[@]}"
+if (( conflicts > 0 ))
+then
+  error "${conflicts} file(s) need a hand; see above."
+  exit 1
+fi
+kit:finish "${targets[@]}"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-version.bash b/bin/kit-version.bash
new file mode 100755
index 0000000..14b2081
--- /dev/null
+++ b/bin/kit-version.bash
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# kit-version - print this release's version (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+
+set -o errexit -o nounset -o pipefail
+cat "${kit_root:?run through bin/kit}/version"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/hooks/pre-commit b/hooks/pre-commit
deleted file mode 100755
index 35c3163..0000000
--- a/hooks/pre-commit
+++ /dev/null
@@ -1,85 +0,0 @@
-#!/usr/bin/env bash
-# pre-commit - lint the staged paths and refuse the commit on a finding (executed git hook, fails open)
-# ----------------------------------------------------------------------------------------------------------------------
-#
-# Each linter runs over the staged paths of its own kind, when the linter is on PATH: shellcheck over bash,
-# actionlint over workflows, and markdownlint-cli2 over markdown when the repository carries a config for it.
-# A linter that is not on PATH is a reported skip, never a silent pass and never a refusal: lint is not the
-# enforcement of record, and a GUI client with a short PATH must still be able to commit.
-#
-# The working tree's copy of each path is linted, not the staged blob, so a partial add can be told about a line
-# the commit does not carry. The escape hatch is git's own: git commit --no-verify
-
-set -o nounset -o pipefail
-
-staged=()
-while IFS= read -r -d '' path
-do
-  [[ -f "${path}" ]] && staged+=("${path}")
-done < <(git diff --cached --name-only --diff-filter=ACMR -z 2>/dev/null)
-(( ${#staged[@]} )) || exit 0
-
-bash_paths=()
-workflow_paths=()
-markdown_paths=()
-for path in "${staged[@]}"
-do
-  case "${path}" in
-    (*.sh | *.bash | hooks/*)
-      bash_paths+=("${path}")
-      ;;
-    (.github/workflows/*.yml | .github/workflows/*.yaml)
-      workflow_paths+=("${path}")
-      ;;
-    (*.md)
-      markdown_paths+=("${path}")
-  esac
-done
-
-findings=0
-skip() {
-  printf '\xe2\x9a\xa0\xef\xb8\x8f  %s is not on PATH, so the staged %s were NOT linted.\n' "$1" "$2" >&2
-}
-
-if (( ${#bash_paths[@]} ))
-then
-  if command -v shellcheck >/dev/null 2>&1
-  then
-    shellcheck --shell=bash --external-sources "${bash_paths[@]}" || findings=1
-  else
-    skip shellcheck "bash files"
-  fi
-fi
-
-if (( ${#workflow_paths[@]} ))
-then
-  if command -v actionlint >/dev/null 2>&1
-  then
-    actionlint "${workflow_paths[@]}" || findings=1
-  else
-    skip actionlint workflows
-  fi
-fi
-
-if (( ${#markdown_paths[@]} )) && compgen -G ".markdownlint-cli2.*" >/dev/null
-then
-  if command -v markdownlint-cli2 >/dev/null 2>&1
-  then
-    markdownlint-cli2 "${markdown_paths[@]}" || findings=1
-  else
-    skip markdownlint-cli2 "markdown files"
-  fi
-fi
-
-if (( findings ))
-then
-  cat >&2 <<'MESSAGE'
-
-❌ refusing the commit: a linter found something in the staged paths. Each finding above names the file and line.
-   Fix it and commit again. If you mean it anyway, the escape hatch is git's own: git commit --no-verify
-MESSAGE
-  exit 1
-fi
-exit 0
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/hooks/pre-rebase b/hooks/pre-rebase
deleted file mode 100755
index 240bc3e..0000000
--- a/hooks/pre-rebase
+++ /dev/null
@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-# pre-rebase - refuse a rebase of the default branch (executed git hook, fails open)
-# ----------------------------------------------------------------------------------------------------------------------
-#
-# git runs this before every rebase, however it was spelled: git rebase, git pull --rebase, an editor's button.
-# It refuses one thing, a rebase whose branch is the default branch, because that branch is the human's desk and
-# a rebase rewrites it. A rebase in worktrees/<N>-<slug> is on an issue branch and passes.
-#
-# It fails open: a rung that cannot tell whether the branch is the default branch exits 0, since refusing every
-# worktree rebase in a clone that cannot answer would be worse than the gap. The one exception is below.
-#
-# git passes <upstream> as $1, and <branch> as $2 only for `git rebase <upstream> <branch>`; an empty $2 means
-# the branch checked out here.
-
-set -o nounset -o pipefail
-
-upstream=${1:-}
-branch=${2:-}
-[[ -n "${branch}" ]] || branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
-[[ -n "${branch}" ]] || exit 0
-
-default_branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
-[[ -n "${default_branch}" ]] || default_branch=main
-[[ "${branch}" == "${default_branch}" ]] || exit 0
-
-# A branch with no commit of its own has nothing a rebase would replay: it is a fast-forward, and passes. Once
-# the branch is known to be the default branch, an <upstream> that cannot be resolved is refused, not passed:
-# this is the one rung where "cannot tell" means no.
-if [[ -n "${upstream}" ]]
-then
-  unique=$(git rev-list --count "${upstream}..${branch}" 2>/dev/null) && (( unique == 0 )) && exit 0
-fi
-
-# The branch name goes through printf, never into the heredoc, since a ref may carry a backtick or a dollar.
-printf '\xe2\x9d\x8c refusing to rebase %s: it is the default branch, and the default branch is never rebased.\n' \
-  "'${branch}'" >&2
-cat >&2 <<'MESSAGE'
-
-   The default branch is the human's desk. It advances by fast-forward: git pull --ff-only
-   A worktree's branch is rebased in that worktree: git -C worktrees/<N>-<slug> rebase main
-
-   If you mean it, the escape hatch is git's own, on the rebase itself: git rebase --no-verify <upstream>
-MESSAGE
-exit 1
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/justfile b/justfile
index 8beb849..17444db 100644
--- a/justfile
+++ b/justfile
@@ -2,7 +2,7 @@
 # justfile - see: https://just.systems/man/en/
 # ----------------------------------------------------------------------------------------------------------------------
 # The root justfile: the gate, and the refresh of this repository's own installed copy. The loop's commands are
-# bin/kit issue, tidy, and status, spelled that way and no other.
+# kit issue, rebase, tidy, and status, spelled that way and no other; mise.toml puts bin/ on PATH.
 
 set dotenv-load := true
 set positional-arguments := true
@@ -29,7 +29,7 @@ set export := true
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  mise exec -- shellcheck --shell=bash --external-sources bin/kit bash/*.sh hooks/*
+  mise exec -- shellcheck --shell=bash --external-sources bin/kit bin/kit-*.bash bash/*.sh
   mise exec -- actionlint
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
diff --git a/lefthook.yml b/lefthook.yml
new file mode 100644
index 0000000..23ab42d
--- /dev/null
+++ b/lefthook.yml
@@ -0,0 +1,8 @@
+# lefthook.yml - this repository's git hooks; see: https://lefthook.dev
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The kit's own hooks come from its installed fragment, the way a consumer takes them. Once per clone:
+# lefthook install
+
+extends:
+  - .kit/lefthook.yml
diff --git a/mise.lock b/mise.lock
index dd72d7a..bcae003 100644
--- a/mise.lock
+++ b/mise.lock
@@ -213,6 +213,11 @@ checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
 
+[[tools.lefthook]]
+version = "2.2.2"
+backend = "aqua:evilmartians/lefthook"
+specifiers = ["2.2"]
+
 [[tools."npm:bats"]]
 version = "1.13.0"
 aube = { path = ".mise/locks/npm-bats/1.13.0", digest = "sha256:b3795a7982457f07d0e04a547944558c3571830dd86994d282099c4c27082169" }
diff --git a/mise.toml b/mise.toml
index 53ce17c..0d4b438 100644
--- a/mise.toml
+++ b/mise.toml
@@ -7,10 +7,15 @@
 [settings]
 lockfile = true
 
+# bin/ on PATH, so `kit` is spelled here as a consumer spells it.
+[env]
+_.path = ["bin"]
+
 [tools]
 actionlint = "1.7"
 gh = "2.103"
 jq = "1.8"
 just = "1.59"
+lefthook = "2.2"
 shellcheck = "0.11"
 bats = "1.13"
diff --git a/targets/claude/.claude/settings.json b/targets/claude/.claude/settings.json
index 7911d58..fde98cf 100644
--- a/targets/claude/.claude/settings.json
+++ b/targets/claude/.claude/settings.json
@@ -3,6 +3,7 @@
     "deny": [
       "Bash(git checkout main *)",
       "Bash(git switch main *)",
+      "Bash(git rebase *)",
       "Bash(git reset --hard *)",
       "Bash(git push --force *)",
       "Bash(git push -f *)",
diff --git a/tests/hooks.bats b/tests/hooks.bats
deleted file mode 100644
index 7559eae..0000000
--- a/tests/hooks.bats
+++ /dev/null
@@ -1,67 +0,0 @@
-#!/usr/bin/env bats
-# hooks.bats - the desk guard: pre-rebase refuses the default branch, pre-commit refuses a lint finding
-# ----------------------------------------------------------------------------------------------------------------------
-
-setup() {
-  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
-  repo=$(mktemp -d)
-  cd "${repo}"
-  git init --quiet --initial-branch=main
-  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
-  git config core.hooksPath "${kit_checkout}/hooks"
-  printf 'one\n' > a && git add a && git commit --quiet --message one
-}
-
-teardown() {
-  rm -rf "${repo}"
-}
-
-@test "pre-rebase refuses a rebase of main that would rewrite a commit, and allows one in a branch" {
-  git switch --quiet --create feature
-  printf 'two\n' > b && git add b && git commit --quiet --message two
-  git switch --quiet main
-  printf 'three\n' > c && git add c && git commit --quiet --message three
-  run git rebase feature
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"refusing to rebase 'main'"* ]]
-  git switch --quiet feature
-  run git rebase main
-  [ "$status" -eq 0 ]
-}
-
-@test "pre-rebase lets main fast-forward" {
-  git switch --quiet --create feature
-  printf 'two\n' > b && git add b && git commit --quiet --message two
-  git switch --quiet main
-  run git rebase feature
-  [ "$status" -eq 0 ]
-}
-
-@test "pre-commit refuses a bash file shellcheck faults, and passes a clean one" {
-  printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
-  git add bad.sh
-  run git commit --quiet --message bad
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"SC2086"* ]]
-  [[ "$output" == *"refusing the commit"* ]]
-  printf '#!/usr/bin/env bash\necho "${x:-}"\n' > bad.sh
-  git add bad.sh
-  run git commit --quiet --message good
-  [ "$status" -eq 0 ]
-}
-
-@test "pre-commit reports a skip when the linter is not on PATH" {
-  printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
-  git add bad.sh
-  # a PATH of one directory, carrying only what the hook itself runs, and no shellcheck
-  mkdir only
-  for tool in bash git env cat
-  do
-    ln -s "$(command -v "${tool}")" "only/${tool}"
-  done
-  run env PATH="${PWD}/only" git commit --quiet --message bad
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"NOT linted"* ]]
-}
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index c1c16b8..71b182a 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -19,7 +19,7 @@ teardown() {
 # later-release <dir> copies this checkout's release to <dir> as version 9.9.9 with one changed rule line.
 later-release() {
   mkdir -p "$1"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "${kit_checkout}/hooks" "$1/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "$1/"
   printf '9.9.9\n' > "$1/version"
   printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/tree/.kit/rules/json.md"
 }
@@ -30,26 +30,16 @@ later-release() {
   [ -f .kit/1st.md ]
   [ -f .kit/rules/bash.md ]
   [ ! -e .kit/bash ]
-  [ ! -e .kit/hooks ]
+  [ -f .kit/lefthook.yml ]
   [ -f .claude/rules/kit-markdown.md ]
   [ ! -L .claude/rules/kit-markdown.md ]
   cmp --silent .claude/rules/kit-markdown.md .kit/rules/markdown.md
   head -n 1 .claude/rules/kit-bash.md | grep --quiet --line-regexp -- '---'
   grep --quiet '"\*\*/\*\.sh"' .claude/rules/kit-bash.md
   [ -f .github/workflows/kit-ci.yml ]
-  jq --exit-status '.permissions.deny | index("Bash(git push --force *)")' .claude/settings.json >/dev/null
+  jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   grep --quiet '^version 0.1.0$' .kit/manifest
   grep --quiet '^targets claude$' .kit/manifest
-  [ "$(git config core.hooksPath)" = "${kit_checkout}/hooks" ]
-}
-
-@test "setup wires a clone's hooks to the release, and issue without a terminal prints usage" {
-  run "${kit_checkout}/bin/kit" setup
-  [ "$status" -eq 0 ]
-  [ "$(git config core.hooksPath)" = "${kit_checkout}/hooks" ]
-  run "${kit_checkout}/bin/kit" issue
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"usage: kit issue"* ]]
 }
 
 @test "install with no target writes the neutral tree and nothing under .claude" {
diff --git a/tests/lint.bats b/tests/lint.bats
new file mode 100644
index 0000000..06a3239
--- /dev/null
+++ b/tests/lint.bats
@@ -0,0 +1,47 @@
+#!/usr/bin/env bats
+# lint.bats - kit lint over given paths and over the staged set, and its reported skip
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+  printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
+  printf '#!/usr/bin/env bash\necho "${x:-}"\n' > good.sh
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+@test "lint refuses a bash file shellcheck faults, and passes a clean one" {
+  run "${kit_checkout}/bin/kit" lint bad.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"SC2086"* ]]
+  run "${kit_checkout}/bin/kit" lint good.sh
+  [ "$status" -eq 0 ]
+}
+
+@test "lint with no path reads the staged set" {
+  git add bad.sh
+  run "${kit_checkout}/bin/kit" lint
+  [ "$status" -eq 1 ]
+  git reset --quiet && git add good.sh
+  run "${kit_checkout}/bin/kit" lint
+  [ "$status" -eq 0 ]
+}
+
+@test "lint reports a skip when the linter is not on PATH" {
+  # a PATH of one directory, carrying only what the verb itself runs, and no shellcheck
+  mkdir only
+  for tool in bash git env cat sed dirname
+  do
+    ln -s "$(command -v "${tool}")" "only/${tool}"
+  done
+  run env PATH="${PWD}/only" "${kit_checkout}/bin/kit" lint bad.sh
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"NOT linted"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/rebase.bats b/tests/rebase.bats
new file mode 100644
index 0000000..1aa67bb
--- /dev/null
+++ b/tests/rebase.bats
@@ -0,0 +1,54 @@
+#!/usr/bin/env bats
+# rebase.bats - kit rebase refuses the default branch and brings a worktree's branch up to date
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  work=$(mktemp -d)
+  cd "${work}"
+  git init --quiet --bare origin.git
+  git clone --quiet origin.git desk 2>/dev/null
+  cd desk
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  printf 'one\n' > a && git add a && git commit --quiet --message one && git push --quiet origin main
+  git remote set-head origin main
+}
+
+teardown() {
+  rm -rf "${work}"
+}
+
+worktree() {  # a worktree on branch 1-x, configured to commit
+  git worktree add --quiet ../wt -b 1-x
+  git -C ../wt config user.name t && git -C ../wt config user.email t@example.com && git -C ../wt config commit.gpgsign false
+}
+
+@test "rebase refuses the default branch" {
+  run "${kit_checkout}/bin/kit" rebase
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"refusing to rebase main"* ]]
+}
+
+@test "rebase moves a worktree's branch onto origin/main and pushes it" {
+  worktree
+  printf 'two\n' > ../wt/b && git -C ../wt add b && git -C ../wt commit --quiet --message two && git -C ../wt push --quiet --set-upstream origin 1-x
+  printf 'three\n' > c && git add c && git commit --quiet --message three && git push --quiet origin main
+  run "${kit_checkout}/bin/kit" rebase ../wt
+  [ "$status" -eq 0 ]
+  [ "$(git -C ../wt rev-parse HEAD~1)" = "$(git rev-parse origin/main)" ]
+  [ "$(git -C ../wt rev-parse HEAD)" = "$(git -C ../wt rev-parse origin/1-x)" ]
+}
+
+@test "rebase aborts on a conflict and leaves the worktree as it was" {
+  worktree
+  printf 'theirs\n' > ../wt/a && git -C ../wt commit --quiet --all --message theirs && git -C ../wt push --quiet --set-upstream origin 1-x
+  printf 'ours\n' > a && git commit --quiet --all --message ours && git push --quiet origin main
+  before=$(git -C ../wt rev-parse HEAD)
+  run "${kit_checkout}/bin/kit" rebase ../wt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"conflicts with origin/main"* ]]
+  [ "$(git -C ../wt rev-parse HEAD)" = "${before}" ]
+  [ -z "$(git -C ../wt status --porcelain)" ]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/release.bats b/tests/release.bats
index 5667467..e4af478 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -15,12 +15,13 @@ teardown() {
 @test "the tarball holds one directory with the release's layout, and installs a fresh repository" {
   version=$(cat "${kit_checkout}/version")
   mkdir "kit-${version}"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "${kit_checkout}/hooks" "${kit_checkout}/version" "kit-${version}/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "${kit_checkout}/version" "kit-${version}/"
   tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
   rm -rf "kit-${version}"
   mkdir unpacked && tar --extract --gzip --file "kit-${version}.tar.gz" --directory unpacked
   [ "$(ls unpacked)" = "kit-${version}" ]
   [ -x "unpacked/kit-${version}/bin/kit" ]
+  [ -x "unpacked/kit-${version}/bin/kit-install.bash" ]
   [ -L "unpacked/kit-${version}/targets/claude/.claude/rules/kit-bash.md" ]
   mkdir fresh && git -C fresh init --quiet --initial-branch=main
   cd fresh
@@ -29,7 +30,6 @@ teardown() {
   run "${work}/unpacked/kit-${version}/bin/kit" check
   [ "$status" -eq 0 ]
   [ "$("${work}/unpacked/kit-${version}/bin/kit" version)" = "${version}" ]
-  [ "$(git config core.hooksPath)" = "${work}/unpacked/kit-${version}/hooks" ]
   [ ! -L .claude/rules/kit-bash.md ]
   [ ! -e .kit/bash ]
 }
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index e1ad167..24e573c 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -25,12 +25,25 @@ worktree under `worktrees/`, one per issue, and reaches `main` only through a me
 1. An issue exists. A change without an issue has not started.
 2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
    pull request. It never switches the checkout it is run from.
-3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`.
+3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`. `kit rebase`
+   brings the branch up to date with `main` and pushes it.
 4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
    and how, and what was left out and why.
 5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
    observed.
 
+## Spellings an agent uses
+
+Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. The rule runs inside
+it, and a harness that can refuse the raw spelling does.
+
+- `kit rebase`, never `git rebase`. It refuses the default branch and otherwise rebases the worktree's branch onto
+  `origin/main` and pushes it.
+- `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
+- `kit tidy`, never `git worktree remove` or `git branch -D`.
+
+The human at the desk is not bound by this; `main` is theirs to rebase.
+
 ## Plans are prose
 
 A design, a spec, or a plan is the body of an issue, written in prose. It is never a committed file. When
@@ -61,7 +74,7 @@ that kind.
 | Kind | Paths | Rule |
 | --- | --- | --- |
 | Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
-| Bash | `*.sh`, `*.bash`, `hooks/*` | [rules/bash.md](rules/bash.md) |
+| Bash | `*.sh`, `*.bash` | [rules/bash.md](rules/bash.md) |
 | Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
 | YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
 | JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
@@ -76,8 +89,9 @@ repository root, and `targets/<name>/` for each target taken; a `.json` destinat
 else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
-- Two hooks. `pre-rebase` refuses a rebase of the default branch. `pre-commit` lints the staged paths. `kit install`
-  points a clone's `core.hooksPath` at them, and every other clone runs `kit setup` once.
+- `kit lint`, the body of a pre-commit hook: shellcheck, actionlint, and markdownlint-cli2 when the repository
+  configures it, over the staged paths, with a missing linter reported as a skip. `.kit/lefthook.yml` runs it;
+  a repository's `lefthook.yml` takes that with `extends` and adds hooks of its own.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
   `.claude/rules/kit-<kind>.md`, copies of the rules, and merges six deny rules into `.claude/settings.json`. The kit owns only the
diff --git a/tree/.kit/lefthook.yml b/tree/.kit/lefthook.yml
new file mode 100644
index 0000000..882d7cf
--- /dev/null
+++ b/tree/.kit/lefthook.yml
@@ -0,0 +1,11 @@
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+#
+# The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]` and adds hooks and commands of its
+# own; Lefthook merges them under the same hook names. Once per clone: lefthook install
+#
+# see: https://lefthook.dev
+
+pre-commit:
+  commands:
+    kit-lint:
+      run: kit lint {staged_files}
diff --git a/tree/.kit/rules/bash.md b/tree/.kit/rules/bash.md
index 86d45e8..92d176e 100644
--- a/tree/.kit/rules/bash.md
+++ b/tree/.kit/rules/bash.md
@@ -3,11 +3,10 @@
 paths:
   - "**/*.sh"
   - "**/*.bash"
-  - "**/hooks/*"
 ---
 # Bash
 
-Applies to `*.sh`, `*.bash`, `hooks/*`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
+Applies to `*.sh` and `*.bash`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
 workflows.
 
 ## Shape

From 000a240a5eeca99261015f13bde40131301ecd6b Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:25:15 -0700
Subject: [PATCH 023/108] #1 mise.desk.toml: a desk-only tool is pinned where
 only a desk reads it; one way into a bash module

Lefthook moves to mise.desk.toml, read when MISE_ENV=desk, which a desk exports and a runner never sets; the Mac-written lock had no Linux entry for it and the runner has no use for it. lockfile_platforms makes the lock carry the runner's platform from now on. The loader's autoload stubs go: a verb says use <module>, and that is the one mechanism.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md      | 13 +++++++++----
 bash/1st.sh    |  7 +------
 mise.desk.lock | 32 ++++++++++++++++++++++++++++++++
 mise.desk.toml |  7 +++++++
 mise.lock      | 11 -----------
 mise.toml      | 12 +++++++-----
 6 files changed, 56 insertions(+), 26 deletions(-)
 create mode 100644 mise.desk.lock
 create mode 100644 mise.desk.toml

diff --git a/README.md b/README.md
index 7dee207..58bb79b 100644
--- a/README.md
+++ b/README.md
@@ -30,9 +30,10 @@ through the rules table in `.kit/1st.md`. `kit target add` and `kit target remov
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
 - Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
   request not linked to an open issue.
-- Pin `lefthook` in `mise.toml`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run `lefthook install`
-  once per clone. That runs `kit lint` over the staged paths before each commit, beside any hooks of your own. A
-  repository on another hook manager runs `kit lint` from it instead.
+- Pin `lefthook` in `mise.desk.toml`, the file mise reads when `MISE_ENV=desk`, put
+  `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run `lefthook install` once per clone. That runs
+  `kit lint` over the staged paths before each commit, beside any hooks of your own. A repository on another hook
+  manager runs `kit lint` from it instead.
 
 The machinery, the `kit` command and the bash behind its verbs, stays in the release where mise installed it; the
 repository carries the text an agent reads and the record of what it took. The kit needs bash 4.4 or later, git,
@@ -56,10 +57,14 @@ Then, once per clone, with the key's id in `signing_key`:
 git config gpg.format openpgp
 git config user.signingkey "${signing_key}"
 git config commit.gpgsign true
+export MISE_ENV=desk
 mise install
 lefthook install
 ```
 
+`MISE_ENV=desk` belongs in your shell profile: it makes mise read `mise.desk.toml`, the tools only a desk runs,
+on top of `mise.toml`, the tools a desk and a CI runner share. A runner leaves it unset.
+
 This repository carries the installed copy of its own kit, and `just ci` checks it.
 
 ## Getting started
@@ -91,7 +96,7 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.kit/1st.md`, `.kit/rules/`, `.kit/lefthook.yml` | `tree/.kit/` |
 | `.github/workflows/kit-ci.yml` | `tree/.github/workflows/kit-ci.yml` |
 | `.claude/rules/kit-<kind>.md` | `targets/claude/.claude/rules/`, links into `tree/.kit/rules/` |
-| `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here it carries only the kit's entries |
+| `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version, the targets taken, and a digest per delivered path |
 
 After changing a file under `tree/` or `targets/`, run `just refresh`, which reinstalls the kit into this
diff --git a/bash/1st.sh b/bash/1st.sh
index 2632223..d0cd39c 100644
--- a/bash/1st.sh
+++ b/bash/1st.sh
@@ -3,8 +3,7 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # Sourced by every verb, bin/kit-<verb>.bash, which bin/kit dispatches to with kit_root exported. It defines functions only and sets no shell option, so the caller's options stand. A module under
-# bash/ is loaded on first use with `use <module>`, and each exported function has a stub here so a
-# caller never has to load it by hand.
+# bash/ is loaded with `use <module>`, once, by the verb that needs it; there is no other way in.
 #
 # Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
 # NO_COLOR is set. Under GitHub Actions, warn and error also emit the matching workflow command.
@@ -121,8 +120,4 @@ git:main-root() {
   git worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
 }
 
-gh:issue()  { use gh && gh:issue "$@"; }
-git:tidy()  { use git && git:tidy "$@"; }
-git:status() { use git && git:status "$@"; }
-
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/mise.desk.lock b/mise.desk.lock
new file mode 100644
index 0000000..dc8663d
--- /dev/null
+++ b/mise.desk.lock
@@ -0,0 +1,32 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+
+lockfile_version = 3
+
+[[tools.lefthook]]
+version = "2.2.2"
+backend = "aqua:evilmartians/lefthook"
+specifiers = ["2.2"]
+
+[tools.lefthook."platforms.linux-arm64"]
+checksum = "sha256:5e11944542e9889078d2300495882aa854d63854a664d09c5637df0bbc21c0e1"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_aarch64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518953"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.linux-x64"]
+checksum = "sha256:2b8d7fd52771f26d7a50260ef10cd6fe704d66f60102e566362b84da09884ab7"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_x86_64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518865"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.macos-arm64"]
+checksum = "sha256:aef03ff2faaf87594068ec3ab794dcc1acd8d64f2aa3109785244c8359fbf15b"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_arm64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518817"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.macos-x64"]
+checksum = "sha256:016e560b0cc982f45df14c301509e05b5c4265655eea996495093cd0c632063a"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_x86_64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518821"
+provenance = "github-attestations"
diff --git a/mise.desk.toml b/mise.desk.toml
new file mode 100644
index 0000000..3a368bd
--- /dev/null
+++ b/mise.desk.toml
@@ -0,0 +1,7 @@
+# mise.desk.toml - the tools only a desk runs; see: https://mise.jdx.dev/configuration/environments.html
+#
+# Read when MISE_ENV=desk, which a desk exports in its shell profile and a CI runner never sets. Lefthook runs the
+# pre-commit hook, and a runner commits nothing.
+
+[tools]
+lefthook = "2.2"
diff --git a/mise.lock b/mise.lock
index bcae003..e63f25e 100644
--- a/mise.lock
+++ b/mise.lock
@@ -213,17 +213,6 @@ checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
 
-[[tools.lefthook]]
-version = "2.2.2"
-backend = "aqua:evilmartians/lefthook"
-specifiers = ["2.2"]
-
-[[tools."npm:bats"]]
-version = "1.13.0"
-aube = { path = ".mise/locks/npm-bats/1.13.0", digest = "sha256:b3795a7982457f07d0e04a547944558c3571830dd86994d282099c4c27082169" }
-backend = "npm:bats"
-specifiers = ["1.13"]
-
 [[tools.shellcheck]]
 version = "0.11.0"
 backend = "aqua:koalaman/shellcheck"
diff --git a/mise.toml b/mise.toml
index 0d4b438..f0d2d40 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,11 +1,14 @@
-# mise.toml - the pinned toolchain; see: https://mise.jdx.dev/configuration.html
+# mise.toml - the pinned toolchain a desk and a runner share; see: https://mise.jdx.dev/configuration.html
 #
-# Every tool this repository runs, at one version, installed the same way on a desk (`mise install`) and on a
-# runner (`jdx/mise-action`). `lockfile = true` records each pin's exact resolution in mise.lock. git and bash
-# come from the machine.
+# Every tool both a desk and a CI runner run, at one version, installed the same way by `mise install` and by
+# `jdx/mise-action`. A tool only a desk runs is pinned in mise.desk.toml, which mise reads when MISE_ENV=desk, and
+# a desk sets that in its shell profile; a runner leaves it unset. `lockfile = true` records each pin's exact
+# resolution in mise.lock. git and bash come from the machine.
 
 [settings]
 lockfile = true
+# A lock written on a desk carries the runner's platform too; see: https://mise.jdx.dev/dev-tools/mise-lock.html
+lockfile_platforms = ["linux-x64", "linux-arm64", "macos-arm64", "macos-x64"]
 
 # bin/ on PATH, so `kit` is spelled here as a consumer spells it.
 [env]
@@ -16,6 +19,5 @@ actionlint = "1.7"
 gh = "2.103"
 jq = "1.8"
 just = "1.59"
-lefthook = "2.2"
 shellcheck = "0.11"
 bats = "1.13"

From 374af01b49440dd3e2c6fcbc7a438672463d899e Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:26:20 -0700
Subject: [PATCH 024/108] #1 tests/rebase.bats: the bare origin starts on main
 whatever the machine's default

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/rebase.bats | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/rebase.bats b/tests/rebase.bats
index 1aa67bb..571f696 100644
--- a/tests/rebase.bats
+++ b/tests/rebase.bats
@@ -6,7 +6,7 @@ setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
   work=$(mktemp -d)
   cd "${work}"
-  git init --quiet --bare origin.git
+  git init --quiet --bare --initial-branch=main origin.git
   git clone --quiet origin.git desk 2>/dev/null
   cd desk
   git config user.name t && git config user.email t@example.com && git config commit.gpgsign false

From a4d3fcbb3d28df19f633b35fae17e2e1366118cf Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:34:19 -0700
Subject: [PATCH 025/108] #1 .kit/lefthook.yml: the linters are declared where
 the hook manager reads them; kit lint runs that hook

The fragment names which linter runs over which paths, a repository's lefthook.yml extends it, and kit lint is lefthook run pre-commit, over the staged paths or with --all-files over every tracked path, which is also the gate's spelling. Lefthook is back in mise.toml, since a runner runs the same linters; nothing is desk-only today, and the README says where a desk-only tool would go.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md            | 11 ++++----
 .kit/lefthook.yml      | 14 +++++++---
 .kit/manifest          |  4 +--
 README.md              | 13 +++++-----
 bin/kit                |  2 +-
 bin/kit-lint.bash      | 59 +++++-------------------------------------
 justfile               | 11 ++++----
 lefthook.yml           | 10 +++++--
 mise.desk.lock         | 32 -----------------------
 mise.desk.toml         |  7 -----
 mise.toml              |  5 ++--
 tests/lint.bats        | 31 +++++++++-------------
 tree/.kit/1st.md       | 11 ++++----
 tree/.kit/lefthook.yml | 14 +++++++---
 14 files changed, 75 insertions(+), 149 deletions(-)
 delete mode 100644 mise.desk.lock
 delete mode 100644 mise.desk.toml

diff --git a/.kit/1st.md b/.kit/1st.md
index 24e573c..4cc2154 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -89,13 +89,14 @@ repository root, and `targets/<name>/` for each target taken; a `.json` destinat
 else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
-- `kit lint`, the body of a pre-commit hook: shellcheck, actionlint, and markdownlint-cli2 when the repository
-  configures it, over the staged paths, with a missing linter reported as a skip. `.kit/lefthook.yml` runs it;
-  a repository's `lefthook.yml` takes that with `extends` and adds hooks of its own.
+- `.kit/lefthook.yml`, which linter runs over which paths before a commit. A repository's `lefthook.yml` takes it
+  with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand, over the staged paths
+  or every path.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
-  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges six deny rules into `.claude/settings.json`. The kit owns only the
-  entries it writes; the repository may add its own. `kit target remove` takes a target back out.
+  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
+  The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
+  back out.
 - `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
   runs `kit check`, and refuses a pull request not linked to an open issue.
 
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index 882d7cf..aea7ecf 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -1,11 +1,17 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]` and adds hooks and commands of its
-# own; Lefthook merges them under the same hook names. Once per clone: lefthook install
+# Which linter runs over which paths. The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]`
+# and adds commands of its own under the same hook, or any other; Lefthook merges them by name, so a command named
+# here is overridden by one of the same name there. `kit lint` runs this hook by hand, over the staged paths or,
+# with --all-files, over every path. Once per clone: lefthook install
 #
 # see: https://lefthook.dev
 
 pre-commit:
   commands:
-    kit-lint:
-      run: kit lint {staged_files}
+    shellcheck:
+      glob: "*.{sh,bash}"
+      run: shellcheck --shell=bash --external-sources {staged_files}
+    actionlint:
+      glob: ".github/workflows/*.{yml,yaml}"
+      run: actionlint {staged_files}
diff --git a/.kit/manifest b/.kit/manifest
index be6b454..57409ac 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -9,8 +9,8 @@ targets claude
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
 b9a38f19b571c70bb4ef7d3f25fd2b56ac0f6fc076cbcc8e318d22ad3ffe594f  .github/workflows/kit-ci.yml
-a39770f43e77f4e8ab7e97b5f56c5993e84f3e6778cff1e1e52296ce72b978c3  .kit/1st.md
-e1282bfb261b23acad7d368ca8c2a3e47e728708eee16cb85e54a070f8b96381  .kit/lefthook.yml
+f69ed575255ca7403c9daa1801058986d9e4845df581b05096c2aae6220d3d90  .kit/1st.md
+4460940e906891560f03ee5a5c2b2a61e9f814b05cf32a5917933e902a6ed45c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
diff --git a/README.md b/README.md
index 58bb79b..3c5c0c2 100644
--- a/README.md
+++ b/README.md
@@ -30,10 +30,10 @@ through the rules table in `.kit/1st.md`. `kit target add` and `kit target remov
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
 - Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
   request not linked to an open issue.
-- Pin `lefthook` in `mise.desk.toml`, the file mise reads when `MISE_ENV=desk`, put
-  `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run `lefthook install` once per clone. That runs
-  `kit lint` over the staged paths before each commit, beside any hooks of your own. A repository on another hook
-  manager runs `kit lint` from it instead.
+- Pin `lefthook` in `mise.toml`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run `lefthook install`
+  once per clone. The fragment says which linter runs over which paths before a commit, and your `lefthook.yml`
+  adds commands of its own. `kit lint` runs the same hook by hand, and `kit lint --all-files` is the gate's
+  spelling of it.
 
 The machinery, the `kit` command and the bash behind its verbs, stays in the release where mise installed it; the
 repository carries the text an agent reads and the record of what it took. The kit needs bash 4.4 or later, git,
@@ -57,13 +57,12 @@ Then, once per clone, with the key's id in `signing_key`:
 git config gpg.format openpgp
 git config user.signingkey "${signing_key}"
 git config commit.gpgsign true
-export MISE_ENV=desk
 mise install
 lefthook install
 ```
 
-`MISE_ENV=desk` belongs in your shell profile: it makes mise read `mise.desk.toml`, the tools only a desk runs,
-on top of `mise.toml`, the tools a desk and a CI runner share. A runner leaves it unset.
+A tool only a desk runs, should one arrive, is pinned in `mise.desk.toml`, which mise reads on top of `mise.toml`
+when `MISE_ENV=desk` is set; a desk exports that in its shell profile, and a runner leaves it unset.
 
 This repository carries the installed copy of its own kit, and `just ci` checks it.
 
diff --git a/bin/kit b/bin/kit
index 1d4e3bc..e7c90fa 100755
--- a/bin/kit
+++ b/bin/kit
@@ -33,7 +33,7 @@ usage: kit <verb> [<argument>…]
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the default branch
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
   status [--no-fetch]   show every worktree with its branch, pull request, and state
-  lint [<path>…]        lint the staged paths, or the paths given; a missing linter is a reported skip
+  lint [--all-files]    run the pre-commit hook's linters by hand, over the staged paths or every path
   version               print this release's version
 
 Each verb answers --help.
diff --git a/bin/kit-lint.bash b/bin/kit-lint.bash
index 62d85de..f07f516 100755
--- a/bin/kit-lint.bash
+++ b/bin/kit-lint.bash
@@ -1,11 +1,9 @@
 #!/usr/bin/env bash
-# kit-lint - lint the staged paths, or the paths given; a missing linter is a reported skip (kit verb, run through bin/kit)
+# kit-lint - run the pre-commit hook by hand: the linters .kit/lefthook.yml and lefthook.yml declare (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The body of a pre-commit hook, whatever runs the hook: shellcheck over bash, actionlint over workflows, and
-# markdownlint-cli2 over markdown when the repository carries a config for it. A linter that is not on PATH is a
-# reported skip, never a silent pass and never a refusal: lint is not the enforcement of record. The working
-# tree's copy of each path is linted, so a partial add can be told about a line the commit does not carry.
+# An alias for `lefthook run pre-commit`, so the linters a commit meets are the ones this runs, over the staged
+# paths, or over every path with --all-files. The arguments are Lefthook's.
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bash/1st.sh
@@ -13,56 +11,11 @@ source "${kit_root:?run through bin/kit}/bash/1st.sh"
 
 if [[ "${1:-}" == --help ]]
 then
-  echo "usage: kit lint [<path>…]    (no path: the staged paths)" >&2
+  echo "usage: kit lint [--all-files] [<lefthook run option>…]" >&2
   exit 0
 fi
 
-paths=()
-if (( $# > 0 ))
-then
-  paths=("$@")
-else
-  while IFS= read -r -d '' path
-  do
-    paths+=("${path}")
-  done < <(git diff --cached --name-only --diff-filter=ACMR -z)
-fi
-
-bash_paths=()
-workflow_paths=()
-markdown_paths=()
-for path in "${paths[@]}"
-do
-  [[ -f "${path}" ]] || continue
-  case "${path}" in
-    (*.sh | *.bash) bash_paths+=("${path}") ;;
-    (.github/workflows/*.yml | .github/workflows/*.yaml) workflow_paths+=("${path}") ;;
-    (*.md) markdown_paths+=("${path}")
-  esac
-done
-
-findings=0
-run-linter() {  # <linter> <what> <path>…  runs the linter over the paths, or reports the skip
-  local linter=$1 what=$2
-  shift 2
-  if ! command -v "${linter}" >/dev/null 2>&1
-  then
-    warn "${linter} is not on PATH, so the ${what} were NOT linted"
-    return 0
-  fi
-  "${linter}" "$@" || findings=$(( findings + 1 ))
-}
-(( ${#bash_paths[@]} == 0 ))     || run-linter shellcheck "bash files" --shell=bash --external-sources "${bash_paths[@]}"
-(( ${#workflow_paths[@]} == 0 )) || run-linter actionlint workflows "${workflow_paths[@]}"
-if (( ${#markdown_paths[@]} > 0 )) && compgen -G ".markdownlint-cli2.*" >/dev/null
-then
-  run-linter markdownlint-cli2 "markdown files" "${markdown_paths[@]}"
-fi
-
-if (( findings > 0 ))
-then
-  error "a linter found something in ${findings} group(s) of paths; each finding above names the file and line."
-  exit 1
-fi
+guard:require tool:lefthook
+exec lefthook run pre-commit "$@"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/justfile b/justfile
index 17444db..005cf21 100644
--- a/justfile
+++ b/justfile
@@ -20,17 +20,16 @@ _: help
 
 set export := true
 
-# The gate a pull request passes: shellcheck over every bash file, actionlint over every workflow, the bats
-# suite over bin/kit, and bin/kit check over this repository's installed copy of its own kit. Every tool comes
-# from mise.toml.
+# The gate a pull request passes: the linters lefthook.yml declares, over every path, so a runner and a desk's
+# pre-commit hook agree; the bats suite; and bin/kit check over this repository's installed copy of its own kit.
+# Every tool comes from mise.toml.
 #
 #   just ci
-[doc("🚦 Run the gate: shellcheck, actionlint, bats, kit check")]
+[doc("🚦 Run the gate: the linters over every path, bats, kit check")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  mise exec -- shellcheck --shell=bash --external-sources bin/kit bin/kit-*.bash bash/*.sh
-  mise exec -- actionlint
+  mise exec -- lefthook run pre-commit --all-files
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
diff --git a/lefthook.yml b/lefthook.yml
index 23ab42d..b1677f2 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,8 +1,14 @@
 # lefthook.yml - this repository's git hooks; see: https://lefthook.dev
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The kit's own hooks come from its installed fragment, the way a consumer takes them. Once per clone:
-# lefthook install
+# The kit's own linters come from its installed fragment, the way a consumer takes them, and the dispatcher, which
+# carries no extension, is added here. Once per clone: lefthook install
 
 extends:
   - .kit/lefthook.yml
+
+pre-commit:
+  commands:
+    shellcheck-dispatcher:
+      glob: "bin/kit"
+      run: shellcheck --shell=bash --external-sources {staged_files}
diff --git a/mise.desk.lock b/mise.desk.lock
deleted file mode 100644
index dc8663d..0000000
--- a/mise.desk.lock
+++ /dev/null
@@ -1,32 +0,0 @@
-# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
-
-lockfile_version = 3
-
-[[tools.lefthook]]
-version = "2.2.2"
-backend = "aqua:evilmartians/lefthook"
-specifiers = ["2.2"]
-
-[tools.lefthook."platforms.linux-arm64"]
-checksum = "sha256:5e11944542e9889078d2300495882aa854d63854a664d09c5637df0bbc21c0e1"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_aarch64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518953"
-provenance = "github-attestations"
-
-[tools.lefthook."platforms.linux-x64"]
-checksum = "sha256:2b8d7fd52771f26d7a50260ef10cd6fe704d66f60102e566362b84da09884ab7"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_x86_64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518865"
-provenance = "github-attestations"
-
-[tools.lefthook."platforms.macos-arm64"]
-checksum = "sha256:aef03ff2faaf87594068ec3ab794dcc1acd8d64f2aa3109785244c8359fbf15b"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_arm64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518817"
-provenance = "github-attestations"
-
-[tools.lefthook."platforms.macos-x64"]
-checksum = "sha256:016e560b0cc982f45df14c301509e05b5c4265655eea996495093cd0c632063a"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_x86_64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518821"
-provenance = "github-attestations"
diff --git a/mise.desk.toml b/mise.desk.toml
deleted file mode 100644
index 3a368bd..0000000
--- a/mise.desk.toml
+++ /dev/null
@@ -1,7 +0,0 @@
-# mise.desk.toml - the tools only a desk runs; see: https://mise.jdx.dev/configuration/environments.html
-#
-# Read when MISE_ENV=desk, which a desk exports in its shell profile and a CI runner never sets. Lefthook runs the
-# pre-commit hook, and a runner commits nothing.
-
-[tools]
-lefthook = "2.2"
diff --git a/mise.toml b/mise.toml
index f0d2d40..dc9c9b7 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,8 +1,8 @@
 # mise.toml - the pinned toolchain a desk and a runner share; see: https://mise.jdx.dev/configuration.html
 #
 # Every tool both a desk and a CI runner run, at one version, installed the same way by `mise install` and by
-# `jdx/mise-action`. A tool only a desk runs is pinned in mise.desk.toml, which mise reads when MISE_ENV=desk, and
-# a desk sets that in its shell profile; a runner leaves it unset. `lockfile = true` records each pin's exact
+# `jdx/mise-action`. A tool only a desk runs would go in mise.desk.toml, which mise reads when MISE_ENV=desk; a desk
+# sets that in its shell profile and a runner leaves it unset. Nothing is desk-only today. `lockfile = true` records each pin's exact
 # resolution in mise.lock. git and bash come from the machine.
 
 [settings]
@@ -19,5 +19,6 @@ actionlint = "1.7"
 gh = "2.103"
 jq = "1.8"
 just = "1.59"
+lefthook = "2.2"
 shellcheck = "0.11"
 bats = "1.13"
diff --git a/tests/lint.bats b/tests/lint.bats
index 06a3239..86cdc4b 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# lint.bats - kit lint over given paths and over the staged set, and its reported skip
+# lint.bats - kit lint runs the linters the delivered fragment declares, over the staged paths or every path
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -7,6 +7,8 @@ setup() {
   repo=$(mktemp -d)
   cd "${repo}"
   git init --quiet --initial-branch=main
+  "${kit_checkout}/bin/kit" install >/dev/null
+  printf 'extends:\n  - .kit/lefthook.yml\n' > lefthook.yml
   printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
   printf '#!/usr/bin/env bash\necho "${x:-}"\n' > good.sh
 }
@@ -15,33 +17,24 @@ teardown() {
   rm -rf "${repo}"
 }
 
-@test "lint refuses a bash file shellcheck faults, and passes a clean one" {
-  run "${kit_checkout}/bin/kit" lint bad.sh
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"SC2086"* ]]
-  run "${kit_checkout}/bin/kit" lint good.sh
-  [ "$status" -eq 0 ]
-}
-
-@test "lint with no path reads the staged set" {
+@test "lint refuses a staged bash file shellcheck faults, and passes a clean one" {
   git add bad.sh
   run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 1 ]
+  [[ "$output" == *"SC2086"* ]]
   git reset --quiet && git add good.sh
   run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 0 ]
 }
 
-@test "lint reports a skip when the linter is not on PATH" {
-  # a PATH of one directory, carrying only what the verb itself runs, and no shellcheck
-  mkdir only
-  for tool in bash git env cat sed dirname
-  do
-    ln -s "$(command -v "${tool}")" "only/${tool}"
-  done
-  run env PATH="${PWD}/only" "${kit_checkout}/bin/kit" lint bad.sh
+@test "lint --all-files reads every tracked path, where lint alone reads only the staged ones" {
+  git -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false add bad.sh
+  git -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false commit --quiet --no-verify --message bad
+  run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 0 ]
-  [[ "$output" == *"NOT linted"* ]]
+  run "${kit_checkout}/bin/kit" lint --all-files
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"bad.sh"* ]]
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index 24e573c..4cc2154 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -89,13 +89,14 @@ repository root, and `targets/<name>/` for each target taken; a `.json` destinat
 else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
-- `kit lint`, the body of a pre-commit hook: shellcheck, actionlint, and markdownlint-cli2 when the repository
-  configures it, over the staged paths, with a missing linter reported as a skip. `.kit/lefthook.yml` runs it;
-  a repository's `lefthook.yml` takes that with `extends` and adds hooks of its own.
+- `.kit/lefthook.yml`, which linter runs over which paths before a commit. A repository's `lefthook.yml` takes it
+  with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand, over the staged paths
+  or every path.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
-  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges six deny rules into `.claude/settings.json`. The kit owns only the
-  entries it writes; the repository may add its own. `kit target remove` takes a target back out.
+  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
+  The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
+  back out.
 - `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
   runs `kit check`, and refuses a pull request not linked to an open issue.
 
diff --git a/tree/.kit/lefthook.yml b/tree/.kit/lefthook.yml
index 882d7cf..aea7ecf 100644
--- a/tree/.kit/lefthook.yml
+++ b/tree/.kit/lefthook.yml
@@ -1,11 +1,17 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]` and adds hooks and commands of its
-# own; Lefthook merges them under the same hook names. Once per clone: lefthook install
+# Which linter runs over which paths. The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]`
+# and adds commands of its own under the same hook, or any other; Lefthook merges them by name, so a command named
+# here is overridden by one of the same name there. `kit lint` runs this hook by hand, over the staged paths or,
+# with --all-files, over every path. Once per clone: lefthook install
 #
 # see: https://lefthook.dev
 
 pre-commit:
   commands:
-    kit-lint:
-      run: kit lint {staged_files}
+    shellcheck:
+      glob: "*.{sh,bash}"
+      run: shellcheck --shell=bash --external-sources {staged_files}
+    actionlint:
+      glob: ".github/workflows/*.{yml,yaml}"
+      run: actionlint {staged_files}

From 188ee3ef2b999ea5c5cfc9fa14c20264e31899d9 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:35:03 -0700
Subject: [PATCH 026/108] #1 mise.lock: lefthook, for every platform the lock
 covers

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 mise.lock | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/mise.lock b/mise.lock
index e63f25e..74927b8 100644
--- a/mise.lock
+++ b/mise.lock
@@ -213,6 +213,35 @@ checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
 
+[[tools.lefthook]]
+version = "2.2.2"
+backend = "aqua:evilmartians/lefthook"
+specifiers = ["2.2"]
+
+[tools.lefthook."platforms.linux-arm64"]
+checksum = "sha256:5e11944542e9889078d2300495882aa854d63854a664d09c5637df0bbc21c0e1"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_aarch64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518953"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.linux-x64"]
+checksum = "sha256:2b8d7fd52771f26d7a50260ef10cd6fe704d66f60102e566362b84da09884ab7"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_x86_64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518865"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.macos-arm64"]
+checksum = "sha256:aef03ff2faaf87594068ec3ab794dcc1acd8d64f2aa3109785244c8359fbf15b"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_arm64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518817"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.macos-x64"]
+checksum = "sha256:016e560b0cc982f45df14c301509e05b5c4265655eea996495093cd0c632063a"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_x86_64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518821"
+provenance = "github-attestations"
+
 [[tools.shellcheck]]
 version = "0.11.0"
 backend = "aqua:koalaman/shellcheck"

From 96d3fcadb5934f7badf06a0f43989cccd6e2e722 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:39:06 -0700
Subject: [PATCH 027/108] #1 bin: verbs are kit-<verb>.sh, the modules sit
 beside them, and rebase lives in the git module

bash/ is gone: a module is a sourced <module>.sh in bin/, loaded with use; a verb is an executable kit-<verb>.sh there. The layout module is release.sh, so nothing is named kit.sh beside kit. git:default-branch and git:main-root move into git.sh, and git:rebase joins them, so kit rebase is one call like tidy and status. Each verb's --help is a plain line.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml            |  5 +-
 AGENTS.md                                |  2 +-
 README.md                                |  4 +-
 {bash => bin}/1st.sh                     | 31 +++------
 {bash => bin}/gh.sh                      |  1 +
 {bash => bin}/git.sh                     | 47 +++++++++++++-
 bin/kit                                  |  6 +-
 bin/{kit-check.bash => kit-check.sh}     | 22 +++----
 bin/{kit-install.bash => kit-install.sh} | 20 +++---
 bin/{kit-issue.bash => kit-issue.sh}     |  8 +--
 bin/{kit-lint.bash => kit-lint.sh}       |  4 +-
 bin/kit-rebase.bash                      | 47 --------------
 bin/kit-rebase.sh                        | 21 ++++++
 bin/{kit-status.bash => kit-status.sh}   |  8 +--
 bin/{kit-target.bash => kit-target.sh}   | 30 ++++-----
 bin/{kit-tidy.bash => kit-tidy.sh}       |  8 +--
 bin/{kit-update.bash => kit-update.sh}   | 34 +++++-----
 bin/{kit-version.bash => kit-version.sh} |  0
 bash/kit.sh => bin/release.sh            | 82 ++++++++++++------------
 tests/kit.bats                           |  2 +-
 tests/release.bats                       |  4 +-
 21 files changed, 196 insertions(+), 190 deletions(-)
 rename {bash => bin}/1st.sh (70%)
 rename {bash => bin}/gh.sh (99%)
 rename {bash => bin}/git.sh (79%)
 rename bin/{kit-check.bash => kit-check.sh} (77%)
 rename bin/{kit-install.bash => kit-install.sh} (69%)
 rename bin/{kit-issue.bash => kit-issue.sh} (70%)
 rename bin/{kit-lint.bash => kit-lint.sh} (90%)
 delete mode 100755 bin/kit-rebase.bash
 create mode 100755 bin/kit-rebase.sh
 rename bin/{kit-status.bash => kit-status.sh} (70%)
 rename bin/{kit-target.bash => kit-target.sh} (75%)
 rename bin/{kit-tidy.bash => kit-tidy.sh} (70%)
 rename bin/{kit-update.bash => kit-update.sh} (75%)
 rename bin/{kit-version.bash => kit-version.sh} (100%)
 rename bash/kit.sh => bin/release.sh (58%)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 707dd83..85bd9cf 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,7 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, bash/, and
-# version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, and version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
 # is tagged on main (any commit on main, not only its head). A pre-release, the same with a -<suffix>, is tagged on
 # a commit that is not on main, and is published as a GitHub pre-release. Either way the file version at the tagged
 # commit is the version without the suffix, the one under development, and the packed kit carries the tag's full
@@ -78,7 +77,7 @@ jobs:
           version=${GITHUB_REF_NAME#v}
           staging=$(mktemp --directory)
           mkdir "${staging}/kit-${version}"
-          cp --recursive --no-dereference bin tree targets bash version "${staging}/kit-${version}/"
+          cp --recursive --no-dereference bin tree targets version "${staging}/kit-${version}/"
           # the packed kit carries the tag's full version, suffix included; the repository file carries the base
           printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
diff --git a/AGENTS.md b/AGENTS.md
index 0f814a0..34c98a2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
 
 ## This repository's own rules
 
-- The release is `bin/`, `tree/`, `targets/`, `bash/`, and `version`. Everything in it is written for a
+- The release is `bin/`, `tree/`, `targets/`, and `version`. Everything in it is written for a
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
 - `version` is the version under development, with no suffix. A release is the tag `v<version>` on a commit on
   `main`. A pre-release is `v<version>-<suffix>` on a commit that is not on `main`. The release workflow refuses any
diff --git a/README.md b/README.md
index 3c5c0c2..002145e 100644
--- a/README.md
+++ b/README.md
@@ -84,8 +84,8 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
 every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
-the same way; `bin/`, `bash/`, and `version` are the machinery: `bin/kit` dispatches to one `bin/kit-<verb>.bash`
-per verb, and `bash/` holds the modules they source. A symlink under `targets/` is
+the same way; `bin/` and `version` are the machinery: `bin/kit` dispatches to one executable `bin/kit-<verb>.sh`
+per verb, and the verbs source the modules beside them, `1st.sh`, `gh.sh`, `git.sh`, and `release.sh`. A symlink under `targets/` is
 delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
 
 The installed copies are written by `bin/kit install` and not edited by hand:
diff --git a/bash/1st.sh b/bin/1st.sh
similarity index 70%
rename from bash/1st.sh
rename to bin/1st.sh
index d0cd39c..8a8e904 100644
--- a/bash/1st.sh
+++ b/bin/1st.sh
@@ -2,30 +2,31 @@
 # 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Sourced by every verb, bin/kit-<verb>.bash, which bin/kit dispatches to with kit_root exported. It defines functions only and sets no shell option, so the caller's options stand. A module under
-# bash/ is loaded with `use <module>`, once, by the verb that needs it; there is no other way in.
+# Sourced by every verb, bin/kit-<verb>.sh, which bin/kit dispatches to with kit_root exported. It defines functions only and sets no shell option, so the caller's options stand. A module is a
+# sourced <module>.sh beside this file, loaded with `use <module>`, once, by the verb or module that needs it; there
+# is no other way in. A verb is an executable kit-<verb>.sh beside it.
 #
 # Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
 # NO_COLOR is set. Under GitHub Actions, warn and error also emit the matching workflow command.
 
-kit_bash_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-declare -gr kit_bash_dir
+kit_bin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+declare -gr kit_bin_dir
 declare -Ag kit_modules=([1st]=1)
 
-# use <module>… loads bash/<module>.sh once. An unknown module is a bug in the caller, so it is fatal.
+# use <module>… loads bin/<module>.sh once. An unknown module is a bug in the caller, so it is fatal.
 use() {
   local module
   for module in "$@"
   do
     [[ ${kit_modules[${module}]+x} ]] && continue
-    if [[ ! -f "${kit_bash_dir}/${module}.sh" ]]
+    if [[ ! -f "${kit_bin_dir}/${module}.sh" ]]
     then
-      error "no such kit bash module: ${module} (looked in ${kit_bash_dir})"
+      error "no such kit bash module: ${module} (looked in ${kit_bin_dir})"
       return 2
     fi
     kit_modules[${module}]=1
     # shellcheck disable=SC1090  # the path is computed from the module name
-    source "${kit_bash_dir}/${module}.sh"
+    source "${kit_bin_dir}/${module}.sh"
   done
 }
 
@@ -106,18 +107,4 @@ guard:require() {
   done
 }
 
-# git:default-branch prints the default branch: origin/HEAD, with main as the fallback.
-git:default-branch() {
-  local branch
-  branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
-  [[ -n "${branch}" ]] || branch=main
-  printf '%s\n' "${branch}"
-}
-
-# git:main-root prints the root of the main checkout, the first entry of the worktree list. worktrees/ lives
-# under it whether the caller stands in the main checkout or in a linked worktree.
-git:main-root() {
-  git worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
-}
-
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bash/gh.sh b/bin/gh.sh
similarity index 99%
rename from bash/gh.sh
rename to bin/gh.sh
index a4ef4b3..42ff316 100644
--- a/bash/gh.sh
+++ b/bin/gh.sh
@@ -21,6 +21,7 @@
 # lost.
 
 gh:issue() {
+  use git
   if (( $# == 0 ))
   then
     if [[ ! -t 0 ]]
diff --git a/bash/git.sh b/bin/git.sh
similarity index 79%
rename from bash/git.sh
rename to bin/git.sh
index a8544b8..9feac52 100644
--- a/bash/git.sh
+++ b/bin/git.sh
@@ -1,5 +1,5 @@
 # shellcheck shell=bash
-# git.sh - the picture of the worktrees, and the sweep that returns a checkout to pristine (sourced module)
+# git.sh - the default branch and the main root, the picture of the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # git:status [--no-fetch] renders the main checkout on one line and one block per worktree under worktrees/
@@ -10,6 +10,24 @@
 # the worktree bookkeeping, and deletes every local branch whose upstream is gone. It never touches the default
 # branch, a branch checked out in a live worktree, a dirty worktree, or the worktree it runs in. --dry-run
 # prints what a sweep would do and changes nothing.
+#
+# git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto
+# origin/<default> and pushes it with --force-with-lease. It refuses the default branch, the human's desk; on a
+# conflict it aborts and leaves the worktree as it was.
+
+# git:default-branch prints the default branch: origin/HEAD, with main as the fallback.
+git:default-branch() {
+  local branch
+  branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+  [[ -n "${branch}" ]] || branch=main
+  printf '%s\n' "${branch}"
+}
+
+# git:main-root prints the root of the main checkout, the first entry of the worktree list. worktrees/ lives
+# under it whether the caller stands in the main checkout or in a linked worktree.
+git:main-root() {
+  git worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
+}
 
 # git:pr-summary <branch> prints "<number>\t<Draft|Ready>" for the open pull request on <branch>, or nothing.
 git:pr-summary() {
@@ -259,4 +277,31 @@ git:tidy() {
   fi
 }
 
+git:rebase() {
+  local worktree=${1:-.} branch default_branch
+  branch=$(git -C "${worktree}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+  if [[ -z "${branch}" ]]
+  then
+    error "${worktree} has no branch checked out, so there is nothing to rebase"
+    return 1
+  fi
+  default_branch=$(git -C "${worktree}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+  [[ -n "${default_branch}" ]] || default_branch=main
+  if [[ "${branch}" == "${default_branch}" ]]
+  then
+    error "refusing to rebase ${branch}: it is the default branch, the human's desk. It advances by fast-forward: git pull --ff-only"
+    return 1
+  fi
+  section "kit rebase ${branch} onto origin/${default_branch}"
+  git -C "${worktree}" fetch --quiet --prune origin
+  if ! git -C "${worktree}" rebase --quiet "origin/${default_branch}"
+  then
+    git -C "${worktree}" rebase --abort
+    error "${branch} conflicts with origin/${default_branch}; the rebase was aborted and the worktree is as it was. Resolve by hand."
+    return 1
+  fi
+  git -C "${worktree}" push --quiet --force-with-lease
+  ok "${branch} is rebased onto origin/${default_branch} and pushed."
+}
+
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit b/bin/kit
index e7c90fa..d786a21 100755
--- a/bin/kit
+++ b/bin/kit
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit - the kit's command: each verb is the executable bin/kit-<verb>.bash beside it (executed entrypoint)
+# kit - the kit's command: each verb is the executable bin/kit-<verb>.sh beside it (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # The release is the directory above bin/. This file resolves it, exports it as kit_root, and hands the verb its
@@ -40,13 +40,13 @@ Each verb answers --help.
 USAGE
     ;;
   (*)
-    if [[ ! -x "${kit_root}/bin/kit-${verb}.bash" ]]
+    if [[ ! -x "${kit_root}/bin/kit-${verb}.sh" ]]
     then
       echo "kit: unknown verb '${verb}'; run: kit help" >&2
       exit 2
     fi
     shift
-    exec "${kit_root}/bin/kit-${verb}.bash" "$@"
+    exec "${kit_root}/bin/kit-${verb}.sh" "$@"
 esac
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-check.bash b/bin/kit-check.sh
similarity index 77%
rename from bin/kit-check.bash
rename to bin/kit-check.sh
index 6225b80..f549188 100755
--- a/bin/kit-check.bash
+++ b/bin/kit-check.sh
@@ -2,12 +2,12 @@
 # kit-check - fail when a delivered file differs from the pinned release (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bash/kit.sh
+# see: bin/release.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
-use kit
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
 
 if [[ "${1:-}" == --help ]]
 then
@@ -15,9 +15,9 @@ then
   exit 0
 fi
 
-kit:require-manifest
-read -r -a targets <<<"$(kit:manifest-targets)"
-version=$(kit:manifest-version)
+release:require-manifest
+read -r -a targets <<<"$(release:manifest-targets)"
+version=$(release:manifest-version)
 findings=0
 if [[ "${version}" != "$(cat "${kit_root}/version")" ]]
 then
@@ -26,18 +26,18 @@ then
 fi
 while IFS= read -r path
 do
-  src=$(kit:source-of "${kit_root}" "${path}" "${targets[@]}")
+  src=$(release:source-of "${kit_root}" "${path}" "${targets[@]}")
   if [[ ! -f "${path}" ]]
   then
     error "${path} is missing"
     findings=$(( findings + 1 ))
-  elif kit:merged "${path}"
+  elif release:merged "${path}"
   then
     if ! command -v jq >/dev/null 2>&1
     then
       error "run: mise install (jq is not on PATH, so ${path} could not be read)"
       findings=$(( findings + 1 ))
-    elif ! kit:json-holds "${path}" "${src}"
+    elif ! release:json-holds "${path}" "${src}"
     then
       error "${path} is missing an entry the kit writes; run: kit update"
       findings=$(( findings + 1 ))
@@ -47,7 +47,7 @@ do
     error "${path} differs from the pinned release"
     findings=$(( findings + 1 ))
   fi
-done < <(kit:delivered "${kit_root}" "${targets[@]}")
+done < <(release:delivered "${kit_root}" "${targets[@]}")
 if (( findings > 0 ))
 then
   error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
diff --git a/bin/kit-install.bash b/bin/kit-install.sh
similarity index 69%
rename from bin/kit-install.bash
rename to bin/kit-install.sh
index 5bbfa87..7f83e57 100755
--- a/bin/kit-install.bash
+++ b/bin/kit-install.sh
@@ -2,12 +2,12 @@
 # kit-install - mirror the release into the repository, take the named targets, and write .kit/manifest (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bash/kit.sh
+# see: bin/release.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
-use kit
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
 
 if [[ "${1:-}" == --help ]]
 then
@@ -16,19 +16,19 @@ then
 fi
 
 guard:require tool:jq tool:git
-kit:require-targets "$@"
+release:require-targets "$@"
 if [[ -f .kit/manifest ]]
 then
-  error "run: kit update (this repository already carries kit $(kit:manifest-version))"
+  error "run: kit update (this repository already carries kit $(release:manifest-version))"
   exit 1
 fi
 section "kit install $(cat "${kit_root}/version")${*:+, targets: $*}"
 while IFS= read -r path
 do
   step "${path}"
-  kit:place "$(kit:source-of "${kit_root}" "${path}" "$@")" "${path}"
-done < <(kit:delivered "${kit_root}" "$@")
-kit:write-manifest "$@"
-kit:finish "$@"
+  release:place "$(release:source-of "${kit_root}" "${path}" "$@")" "${path}"
+done < <(release:delivered "${kit_root}" "$@")
+release:write-manifest "$@"
+release:finish "$@"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-issue.bash b/bin/kit-issue.sh
similarity index 70%
rename from bin/kit-issue.bash
rename to bin/kit-issue.sh
index 422d993..90edef1 100755
--- a/bin/kit-issue.bash
+++ b/bin/kit-issue.sh
@@ -2,16 +2,16 @@
 # kit-issue - start or resume an issue: linked branch, worktree, start commit, draft pull request (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bash/gh.sh
+# see: bin/gh.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
 use gh
 
 if [[ "${1:-}" == --help ]]
 then
-  sed -n '2s/^# kit-[a-z]* - \(.*\) (kit verb, run through bin/kit)$/\1/p' "${BASH_SOURCE[0]}" >&2
+  echo "usage: kit issue [<number>…]    (no number, at a terminal: ask for a title and create the issue)" >&2
   exit 0
 fi
 
diff --git a/bin/kit-lint.bash b/bin/kit-lint.sh
similarity index 90%
rename from bin/kit-lint.bash
rename to bin/kit-lint.sh
index f07f516..c4a04aa 100755
--- a/bin/kit-lint.bash
+++ b/bin/kit-lint.sh
@@ -6,8 +6,8 @@
 # paths, or over every path with --all-files. The arguments are Lefthook's.
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
 
 if [[ "${1:-}" == --help ]]
 then
diff --git a/bin/kit-rebase.bash b/bin/kit-rebase.bash
deleted file mode 100755
index ce17251..0000000
--- a/bin/kit-rebase.bash
+++ /dev/null
@@ -1,47 +0,0 @@
-#!/usr/bin/env bash
-# kit-rebase - rebase a worktree's branch onto the default branch and push it; never the default branch (kit verb, run through bin/kit)
-# ----------------------------------------------------------------------------------------------------------------------
-#
-# The default branch is the human's desk and is never rebased by an agent: this verb refuses it, and 1st.md says an
-# agent spells a rebase this way and no other. Any other branch is rebased onto origin/<default> and pushed with
-# --force-with-lease, which fails rather than overwrite a push that landed since. On a conflict the rebase is
-# aborted and the worktree left as it was.
-
-set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
-
-if [[ "${1:-}" == --help ]]
-then
-  echo "usage: kit rebase [<path>]    (no path: the checkout this runs in)" >&2
-  exit 0
-fi
-
-guard:require tool:git
-worktree=${1:-.}
-branch=$(git -C "${worktree}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
-if [[ -z "${branch}" ]]
-then
-  error "${worktree} has no branch checked out, so there is nothing to rebase"
-  exit 1
-fi
-default_branch=$(git -C "${worktree}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
-[[ -n "${default_branch}" ]] || default_branch=main
-if [[ "${branch}" == "${default_branch}" ]]
-then
-  error "refusing to rebase ${branch}: it is the default branch, the human's desk. It advances by fast-forward: git pull --ff-only"
-  exit 1
-fi
-
-section "kit rebase ${branch} onto origin/${default_branch}"
-git -C "${worktree}" fetch --quiet --prune origin
-if ! git -C "${worktree}" rebase --quiet "origin/${default_branch}"
-then
-  git -C "${worktree}" rebase --abort
-  error "${branch} conflicts with origin/${default_branch}; the rebase was aborted and the worktree is as it was. Resolve by hand."
-  exit 1
-fi
-git -C "${worktree}" push --quiet --force-with-lease
-ok "${branch} is rebased onto origin/${default_branch} and pushed."
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-rebase.sh b/bin/kit-rebase.sh
new file mode 100755
index 0000000..4cb80e6
--- /dev/null
+++ b/bin/kit-rebase.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# kit-rebase - rebase a worktree's branch onto the default branch and push it; never the default branch (kit verb, run through bin/kit)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bin/git.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use git
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit rebase [<path>]    (no path: the checkout this runs in)" >&2
+  exit 0
+fi
+
+guard:require tool:git
+git:rebase "$@"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-status.bash b/bin/kit-status.sh
similarity index 70%
rename from bin/kit-status.bash
rename to bin/kit-status.sh
index 2e48cb2..2345130 100755
--- a/bin/kit-status.bash
+++ b/bin/kit-status.sh
@@ -2,16 +2,16 @@
 # kit-status - show every worktree with its branch, pull request, and state (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bash/git.sh
+# see: bin/git.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
 use git
 
 if [[ "${1:-}" == --help ]]
 then
-  sed -n '2s/^# kit-[a-z]* - \(.*\) (kit verb, run through bin/kit)$/\1/p' "${BASH_SOURCE[0]}" >&2
+  echo "usage: kit status [--no-fetch]" >&2
   exit 0
 fi
 
diff --git a/bin/kit-target.bash b/bin/kit-target.sh
similarity index 75%
rename from bin/kit-target.bash
rename to bin/kit-target.sh
index 05a3aa2..1281aab 100755
--- a/bin/kit-target.bash
+++ b/bin/kit-target.sh
@@ -2,12 +2,12 @@
 # kit-target - list, take, or drop the targets this repository takes (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bash/kit.sh
+# see: bin/release.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
-use kit
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
 
 usage() { echo "usage: kit target list | kit target add <target>… | kit target remove <target>…" >&2; }
 
@@ -18,8 +18,8 @@ case "${verb}" in
   (list | add | remove) ;;
   (*) usage; exit 2
 esac
-kit:require-manifest
-read -r -a targets <<<"$(kit:manifest-targets)"
+release:require-manifest
+read -r -a targets <<<"$(release:manifest-targets)"
 
 case "${verb}" in
   (list)
@@ -28,7 +28,7 @@ case "${verb}" in
   (add)
     (( $# > 0 )) || { usage; exit 2; }
     guard:require tool:jq tool:git
-    kit:require-targets "$@"
+    release:require-targets "$@"
     for t in "$@"
     do
       if [[ " ${targets[*]} " == *" ${t} "* ]]
@@ -40,17 +40,17 @@ case "${verb}" in
       while IFS= read -r path
       do
         step "${path}"
-        kit:place "${kit_root}/targets/${t}/${path}" "${path}"
-      done < <(kit:target-only "${t}")
+        release:place "${kit_root}/targets/${t}/${path}" "${path}"
+      done < <(release:target-only "${t}")
       targets+=("${t}")
     done
-    kit:write-manifest "${targets[@]}"
+    release:write-manifest "${targets[@]}"
     ok "targets: ${targets[*]}"
     ;;
   (remove)
     (( $# > 0 )) || { usage; exit 2; }
     guard:require tool:jq tool:git
-    kit:require-targets "$@"
+    release:require-targets "$@"
     for t in "$@"
     do
       if [[ " ${targets[*]} " != *" ${t} "* ]]
@@ -62,17 +62,17 @@ case "${verb}" in
       while IFS= read -r path
       do
         src="${kit_root}/targets/${t}/${path}"
-        if kit:merged "${path}"
+        if release:merged "${path}"
         then
           [[ -f "${path}" ]] || continue
           step "${path}: the kit's entries taken out"
           # shellcheck disable=SC2016  # a jq filter, with jq variables
-          kit:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
+          release:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
         else
           step "removing ${path}"
           rm -f "${path}"
         fi
-      done < <(kit:target-only "${t}")
+      done < <(release:target-only "${t}")
       kept=()
       for path in "${targets[@]}"
       do
@@ -80,7 +80,7 @@ case "${verb}" in
       done
       targets=("${kept[@]}")
     done
-    kit:write-manifest "${targets[@]}"
+    release:write-manifest "${targets[@]}"
     ok "targets: ${targets[*]:-none}"
 esac
 
diff --git a/bin/kit-tidy.bash b/bin/kit-tidy.sh
similarity index 70%
rename from bin/kit-tidy.bash
rename to bin/kit-tidy.sh
index fd2e5e1..2ac2bea 100755
--- a/bin/kit-tidy.bash
+++ b/bin/kit-tidy.sh
@@ -2,16 +2,16 @@
 # kit-tidy - remove worktrees whose pull request is merged or closed, and gone branches (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bash/git.sh
+# see: bin/git.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
 use git
 
 if [[ "${1:-}" == --help ]]
 then
-  sed -n '2s/^# kit-[a-z]* - \(.*\) (kit verb, run through bin/kit)$/\1/p' "${BASH_SOURCE[0]}" >&2
+  echo "usage: kit tidy [--dry-run]" >&2
   exit 0
 fi
 
diff --git a/bin/kit-update.bash b/bin/kit-update.sh
similarity index 75%
rename from bin/kit-update.bash
rename to bin/kit-update.sh
index 9e0a4bb..1580695 100755
--- a/bin/kit-update.bash
+++ b/bin/kit-update.sh
@@ -6,12 +6,12 @@
 # content; it is replaced. An edited one is merged with the previous release as the base: KIT_BASE=<dir> names
 # that release's root, otherwise mise knows where it installed it.
 #
-# see: bash/kit.sh
+# see: bin/release.sh
 
 set -o errexit -o nounset -o pipefail
-# shellcheck source=bash/1st.sh
-source "${kit_root:?run through bin/kit}/bash/1st.sh"
-use kit
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
 
 if [[ "${1:-}" == --help ]]
 then
@@ -20,9 +20,9 @@ then
 fi
 
 guard:require tool:jq tool:git
-kit:require-manifest
-read -r -a targets <<<"$(kit:manifest-targets)"
-previous=$(kit:manifest-version)
+release:require-manifest
+read -r -a targets <<<"$(release:manifest-targets)"
+previous=$(release:manifest-version)
 current=$(cat "${kit_root}/version")
 section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
 
@@ -42,26 +42,26 @@ fi
 conflicts=0
 while IFS= read -r path
 do
-  src=$(kit:source-of "${kit_root}" "${path}" "${targets[@]}")
+  src=$(release:source-of "${kit_root}" "${path}" "${targets[@]}")
   base=""
-  [[ -n "${base_root}" ]] && base=$(kit:source-of "${base_root}" "${path}" "${targets[@]}" || true)
-  if kit:merged "${path}"
+  [[ -n "${base_root}" ]] && base=$(release:source-of "${base_root}" "${path}" "${targets[@]}" || true)
+  if release:merged "${path}"
   then
     step "${path}: merged by key"
-    kit:place "${src}" "${path}" "${base}"
+    release:place "${src}" "${path}" "${base}"
     continue
   fi
   if [[ ! -f "${path}" ]]
   then
     step "${path}: missing, written"
-    kit:place "${src}" "${path}"
+    release:place "${src}" "${path}"
     continue
   fi
   recorded=$(awk -v p="${path}" '$2==p{print $1}' .kit/manifest)
-  if [[ -z "${recorded}" || "${recorded}" == "$(kit:digest < "${path}")" ]]
+  if [[ -z "${recorded}" || "${recorded}" == "$(release:digest < "${path}")" ]]
   then
     step "${path}: unchanged since ${previous}, replaced"
-    kit:place "${src}" "${path}"
+    release:place "${src}" "${path}"
     continue
   fi
   if [[ -z "${base}" ]]
@@ -76,14 +76,14 @@ do
     warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
     conflicts=$(( conflicts + 1 ))
   fi
-done < <(kit:delivered "${kit_root}" "${targets[@]}")
+done < <(release:delivered "${kit_root}" "${targets[@]}")
 
-kit:write-manifest "${targets[@]}"
+release:write-manifest "${targets[@]}"
 if (( conflicts > 0 ))
 then
   error "${conflicts} file(s) need a hand; see above."
   exit 1
 fi
-kit:finish "${targets[@]}"
+release:finish "${targets[@]}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-version.bash b/bin/kit-version.sh
similarity index 100%
rename from bin/kit-version.bash
rename to bin/kit-version.sh
diff --git a/bash/kit.sh b/bin/release.sh
similarity index 58%
rename from bash/kit.sh
rename to bin/release.sh
index 6dfc7ae..16c8a15 100644
--- a/bash/kit.sh
+++ b/bin/release.sh
@@ -1,7 +1,7 @@
 # shellcheck shell=bash
 # shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
-# kit.sh - the release's layout, the one merge rule, and the manifest (sourced module)
+# release.sh - the release's layout, the one merge rule, and the manifest (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A release mirrors its tree/ at the repository root, and targets/<name>/ for each target taken; a symlink in
@@ -11,8 +11,8 @@
 #
 # Every function reads the release from kit_root, exported by bin/kit.
 
-# kit:layers <root> <target>… prints the directories mirrored at the repository root, tree first.
-kit:layers() {
+# release:layers <root> <target>… prints the directories mirrored at the repository root, tree first.
+release:layers() {
   local root=$1 t
   shift
   printf '%s\n' "${root}/tree"
@@ -22,54 +22,54 @@ kit:layers() {
   done
 }
 
-# kit:delivered <root> <target>… prints every repository path the release at <root> delivers for those targets.
-kit:delivered() {
+# release:delivered <root> <target>… prints every repository path the release at <root> delivers for those targets.
+release:delivered() {
   local layer
   while IFS= read -r layer
   do
     (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@')
-  done < <(kit:layers "$@") | sort --unique
+  done < <(release:layers "$@") | sort --unique
 }
 
-# kit:source-of <root> <path> <target>… prints the release file behind a repository path, the last layer winning.
-kit:source-of() {
+# release:source-of <root> <path> <target>… prints the release file behind a repository path, the last layer winning.
+release:source-of() {
   local root=$1 path=$2 layer found=""
   shift 2
   while IFS= read -r layer
   do
     [[ -e "${layer}/${path}" ]] && found="${layer}/${path}"
-  done < <(kit:layers "${root}" "$@")
+  done < <(release:layers "${root}" "$@")
   [[ -n "${found}" ]] && printf '%s\n' "${found}"
 }
 
-# kit:target-only <target> prints the paths the target delivers that tree/ does not.
-kit:target-only() {
-  comm -13 <(kit:delivered "${kit_root}") <(kit:delivered "${kit_root}" "$1")
+# release:target-only <target> prints the paths the target delivers that tree/ does not.
+release:target-only() {
+  comm -13 <(release:delivered "${kit_root}") <(release:delivered "${kit_root}" "$1")
 }
 
-# kit:known-targets prints the targets this release carries.
-kit:known-targets() {
+# release:known-targets prints the targets this release carries.
+release:known-targets() {
   (cd "${kit_root}/targets" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
 }
 
-# kit:require-targets <name>… refuses a target this release does not carry, naming the ones it does.
-kit:require-targets() {
+# release:require-targets <name>… refuses a target this release does not carry, naming the ones it does.
+release:require-targets() {
   local t
   for t in "$@"
   do
     if [[ ! -d "${kit_root}/targets/${t}" ]]
     then
-      error "'${t}' is not a target this release knows; the targets are: $(kit:known-targets | paste -s -d ' ' -)"
+      error "'${t}' is not a target this release knows; the targets are: $(release:known-targets | paste -s -d ' ' -)"
       return 2
     fi
   done
 }
 
-kit:merged() { [[ "$1" == *.json ]]; }
+release:merged() { [[ "$1" == *.json ]]; }
 
 # The parameters are values ($), not filters: a filter parameter is re-read against the input at each use, which
 # inside the recursion is the wrong level of the object.
-kit_jq='
+release_jq='
   def merge($cur; $base; $new):
     if ($new | type) == "object" then
       reduce ($new | keys[]) as $k ($cur // {}; .[$k] = merge(($cur // {})[$k]; ($base // {})[$k]; $new[$k]))
@@ -88,23 +88,23 @@ kit_jq='
     else $cur == $new end;
 '
 
-# kit:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if missing.
-kit:json-write() {
+# release:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if missing.
+release:json-write() {
   local path=$1 filter=$2
   shift 2
   mkdir -p "$(dirname "${path}")"
   [[ -f "${path}" ]] || printf '{}\n' > "${path}"
-  jq --indent 2 "${kit_jq} ${filter}" "$@" "${path}" > "${path}.kit-new"
+  jq --indent 2 "${release_jq} ${filter}" "$@" "${path}" > "${path}.kit-new"
   mv "${path}.kit-new" "${path}"
 }
 
-# kit:json-holds <path> <source> is true when the JSON at <path> carries every entry the release's <source> writes.
-kit:json-holds() {
-  jq --exit-status "${kit_jq} holds(.; \$new[0])" --slurpfile new "$2" "$1" >/dev/null
+# release:json-holds <path> <source> is true when the JSON at <path> carries every entry the release's <source> writes.
+release:json-holds() {
+  jq --exit-status "${release_jq} holds(.; \$new[0])" --slurpfile new "$2" "$1" >/dev/null
 }
 
-# kit:digest prints the sha256 of stdin, by whichever tool the machine carries.
-kit:digest() {
+# release:digest prints the sha256 of stdin, by whichever tool the machine carries.
+release:digest() {
   if command -v sha256sum >/dev/null 2>&1
   then
     sha256sum | cut -d ' ' -f 1
@@ -113,12 +113,12 @@ kit:digest() {
   fi
 }
 
-# kit:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, a copy otherwise.
-kit:place() {
+# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, a copy otherwise.
+release:place() {
   local src=$1 path=$2 base=${3:-/dev/null}
-  if kit:merged "${path}"
+  if release:merged "${path}"
   then
-    kit:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
+    release:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
   else
     mkdir -p "$(dirname "${path}")"
     cat "${src}" > "${path}.kit-new"
@@ -126,8 +126,8 @@ kit:place() {
   fi
 }
 
-# kit:write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
-kit:write-manifest() {
+# release:write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
+release:write-manifest() {
   local path
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
@@ -135,16 +135,16 @@ kit:write-manifest() {
     printf 'targets%s\n' "${*:+ $*}"
     while IFS= read -r path
     do
-      printf '%s  %s\n' "$(kit:digest < "$(kit:source-of "${kit_root}" "${path}" "$@")")" "${path}"
-    done < <(kit:delivered "${kit_root}" "$@")
+      printf '%s  %s\n' "$(release:digest < "$(release:source-of "${kit_root}" "${path}" "$@")")" "${path}"
+    done < <(release:delivered "${kit_root}" "$@")
   } > .kit/manifest
 }
 
-kit:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
-kit:manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
+release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
+release:manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
 
-# kit:require-manifest refuses to go on in a repository that never took the kit.
-kit:require-manifest() {
+# release:require-manifest refuses to go on in a repository that never took the kit.
+release:require-manifest() {
   if [[ ! -f .kit/manifest ]]
   then
     error "run: kit install (this repository carries no .kit/manifest)"
@@ -152,8 +152,8 @@ kit:require-manifest() {
   fi
 }
 
-# kit:finish <target>… reports a completed install or update.
-kit:finish() {
+# release:finish <target>… reports a completed install or update.
+release:finish() {
   ok "kit $(cat "${kit_root}/version") is installed, targets: ${*:-none}; .kit/manifest is written."
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
diff --git a/tests/kit.bats b/tests/kit.bats
index 71b182a..1902d2d 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -19,7 +19,7 @@ teardown() {
 # later-release <dir> copies this checkout's release to <dir> as version 9.9.9 with one changed rule line.
 later-release() {
   mkdir -p "$1"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "$1/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "$1/"
   printf '9.9.9\n' > "$1/version"
   printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/tree/.kit/rules/json.md"
 }
diff --git a/tests/release.bats b/tests/release.bats
index e4af478..a437c5d 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -15,13 +15,13 @@ teardown() {
 @test "the tarball holds one directory with the release's layout, and installs a fresh repository" {
   version=$(cat "${kit_checkout}/version")
   mkdir "kit-${version}"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/bash" "${kit_checkout}/version" "kit-${version}/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/version" "kit-${version}/"
   tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
   rm -rf "kit-${version}"
   mkdir unpacked && tar --extract --gzip --file "kit-${version}.tar.gz" --directory unpacked
   [ "$(ls unpacked)" = "kit-${version}" ]
   [ -x "unpacked/kit-${version}/bin/kit" ]
-  [ -x "unpacked/kit-${version}/bin/kit-install.bash" ]
+  [ -x "unpacked/kit-${version}/bin/kit-install.sh" ]
   [ -L "unpacked/kit-${version}/targets/claude/.claude/rules/kit-bash.md" ]
   mkdir fresh && git -C fresh init --quiet --initial-branch=main
   cd fresh

From 8ae181e42f417f7d616545e36b7c0bef2118e98d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:45:52 -0700
Subject: [PATCH 028/108] #1 mise.desk.toml, mise.ci.toml: a tool is pinned in
 the file of whoever runs it

Lefthook is a desk's, in mise.desk.toml under MISE_ENV=desk; actionlint is the runner's, in mise.ci.toml under MISE_ENV=ci, which the delivered CI job sets. just ci is the runner's gate, run on a desk as MISE_ENV=ci just ci, and the pre-commit hook is the narrower check the fragment declares. The lint tests skip where Lefthook does not answer.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml      |  3 ++
 .kit/1st.md                       |  5 +-
 .kit/lefthook.yml                 |  3 --
 .kit/manifest                     |  6 +--
 README.md                         | 18 ++++----
 justfile                          | 14 +++---
 mise.ci.lock                      | 32 +++++++++++++
 mise.ci.toml                      |  6 +++
 mise.desk.lock                    | 32 +++++++++++++
 mise.desk.toml                    |  6 +++
 mise.lock                         | 76 -------------------------------
 mise.toml                         | 13 +++---
 tests/lint.bats                   |  1 +
 tree/.github/workflows/kit-ci.yml |  3 ++
 tree/.kit/1st.md                  |  5 +-
 tree/.kit/lefthook.yml            |  3 --
 16 files changed, 114 insertions(+), 112 deletions(-)
 create mode 100644 mise.ci.lock
 create mode 100644 mise.ci.toml
 create mode 100644 mise.desk.lock
 create mode 100644 mise.desk.toml

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index c4cb81d..b4752d6 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -25,6 +25,9 @@ jobs:
   CI:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
     runs-on: ubuntu-latest
+    env:
+      # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
+      MISE_ENV: ci
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
diff --git a/.kit/1st.md b/.kit/1st.md
index 4cc2154..b17c5cc 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -89,9 +89,8 @@ repository root, and `targets/<name>/` for each target taken; a `.json` destinat
 else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
-- `.kit/lefthook.yml`, which linter runs over which paths before a commit. A repository's `lefthook.yml` takes it
-  with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand, over the staged paths
-  or every path.
+- `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
+  `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
   `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index aea7ecf..bd0f61d 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -12,6 +12,3 @@ pre-commit:
     shellcheck:
       glob: "*.{sh,bash}"
       run: shellcheck --shell=bash --external-sources {staged_files}
-    actionlint:
-      glob: ".github/workflows/*.{yml,yaml}"
-      run: actionlint {staged_files}
diff --git a/.kit/manifest b/.kit/manifest
index 57409ac..00e5bd7 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -8,9 +8,9 @@ targets claude
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
-b9a38f19b571c70bb4ef7d3f25fd2b56ac0f6fc076cbcc8e318d22ad3ffe594f  .github/workflows/kit-ci.yml
-f69ed575255ca7403c9daa1801058986d9e4845df581b05096c2aae6220d3d90  .kit/1st.md
-4460940e906891560f03ee5a5c2b2a61e9f814b05cf32a5917933e902a6ed45c  .kit/lefthook.yml
+5d6f7c4590fe03be20b8208a14539203ee252fe74012f7796a2c1e9bcc42be08  .github/workflows/kit-ci.yml
+a8bc796a9e2a6c907ca61e59f02946dca1cb03833c01f34da6fbdc091e604d23  .kit/1st.md
+dc9d98436a1f4ac03a7b92cc844d7a2064fbca89ebe21bc8ff243e25f8d0225c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
diff --git a/README.md b/README.md
index 002145e..2c086c5 100644
--- a/README.md
+++ b/README.md
@@ -30,10 +30,10 @@ through the rules table in `.kit/1st.md`. `kit target add` and `kit target remov
 - Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
 - Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
   request not linked to an open issue.
-- Pin `lefthook` in `mise.toml`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run `lefthook install`
-  once per clone. The fragment says which linter runs over which paths before a commit, and your `lefthook.yml`
-  adds commands of its own. `kit lint` runs the same hook by hand, and `kit lint --all-files` is the gate's
-  spelling of it.
+- Pin `lefthook` in `mise.desk.toml`, which mise reads when `MISE_ENV=desk`, put `extends: [.kit/lefthook.yml]`
+  in `lefthook.yml`, and run `lefthook install` once per clone. The fragment says which linter runs over which
+  paths before a commit, and your `lefthook.yml` adds commands of its own. `kit lint` runs the same hook by hand.
+  The delivered `CI` job sets `MISE_ENV=ci`, so a tool only the runner needs is pinned in `mise.ci.toml`.
 
 The machinery, the `kit` command and the bash behind its verbs, stays in the release where mise installed it; the
 repository carries the text an agent reads and the record of what it took. The kit needs bash 4.4 or later, git,
@@ -57,12 +57,14 @@ Then, once per clone, with the key's id in `signing_key`:
 git config gpg.format openpgp
 git config user.signingkey "${signing_key}"
 git config commit.gpgsign true
+export MISE_ENV=desk
 mise install
 lefthook install
 ```
 
-A tool only a desk runs, should one arrive, is pinned in `mise.desk.toml`, which mise reads on top of `mise.toml`
-when `MISE_ENV=desk` is set; a desk exports that in its shell profile, and a runner leaves it unset.
+`MISE_ENV=desk` belongs in your shell profile. mise reads `mise.toml` always, `mise.desk.toml` on top of it when
+`MISE_ENV=desk`, and `mise.ci.toml` when `MISE_ENV=ci`, which the CI workflow sets: a tool goes in the file of
+whoever runs it. Lefthook is a desk's; actionlint is the runner's.
 
 This repository carries the installed copy of its own kit, and `just ci` checks it.
 
@@ -85,8 +87,8 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
 every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
 the same way; `bin/` and `version` are the machinery: `bin/kit` dispatches to one executable `bin/kit-<verb>.sh`
-per verb, and the verbs source the modules beside them, `1st.sh`, `gh.sh`, `git.sh`, and `release.sh`. A symlink under `targets/` is
-delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
+per verb, and the verbs source the modules beside them, `1st.sh`, `gh.sh`, `git.sh`, and `release.sh`. A symlink
+under `targets/` is delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
 
 The installed copies are written by `bin/kit install` and not edited by hand:
 
diff --git a/justfile b/justfile
index 005cf21..f06328f 100644
--- a/justfile
+++ b/justfile
@@ -20,16 +20,18 @@ _: help
 
 set export := true
 
-# The gate a pull request passes: the linters lefthook.yml declares, over every path, so a runner and a desk's
-# pre-commit hook agree; the bats suite; and bin/kit check over this repository's installed copy of its own kit.
-# Every tool comes from mise.toml.
+# The runner's gate, run with MISE_ENV=ci so mise.ci.toml's tools are on hand: shellcheck over every bash file,
+# actionlint over every workflow, the bats suite, and bin/kit check over this repository's installed copy of its
+# own kit. A desk runs it the same way: MISE_ENV=ci just ci. The pre-commit hook on a desk is the narrower,
+# faster check lefthook.yml declares.
 #
-#   just ci
-[doc("🚦 Run the gate: the linters over every path, bats, kit check")]
+#   MISE_ENV=ci just ci
+[doc("🚦 The runner's gate: shellcheck, actionlint, bats, kit check (MISE_ENV=ci)")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  mise exec -- lefthook run pre-commit --all-files
+  mise exec -- shellcheck --shell=bash --external-sources bin/kit bin/*.sh
+  mise exec -- actionlint
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
diff --git a/mise.ci.lock b/mise.ci.lock
new file mode 100644
index 0000000..6d43300
--- /dev/null
+++ b/mise.ci.lock
@@ -0,0 +1,32 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+
+lockfile_version = 3
+
+[[tools.actionlint]]
+version = "1.7.12"
+backend = "aqua:rhysd/actionlint"
+specifiers = ["1.7"]
+
+[tools.actionlint."platforms.linux-arm64"]
+checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-x64"]
+checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-arm64"]
+checksum = "sha256:aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924893"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-x64"]
+checksum = "sha256:5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924880"
+provenance = "github-attestations"
diff --git a/mise.ci.toml b/mise.ci.toml
new file mode 100644
index 0000000..face1c9
--- /dev/null
+++ b/mise.ci.toml
@@ -0,0 +1,6 @@
+# mise.ci.toml - the tools only a runner runs, read when MISE_ENV=ci; see: mise.toml
+#
+# actionlint checks the workflows, which only the runner executes; a desk runs it with MISE_ENV=ci when it wants to.
+
+[tools]
+actionlint = "1.7"
diff --git a/mise.desk.lock b/mise.desk.lock
new file mode 100644
index 0000000..dc8663d
--- /dev/null
+++ b/mise.desk.lock
@@ -0,0 +1,32 @@
+# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+
+lockfile_version = 3
+
+[[tools.lefthook]]
+version = "2.2.2"
+backend = "aqua:evilmartians/lefthook"
+specifiers = ["2.2"]
+
+[tools.lefthook."platforms.linux-arm64"]
+checksum = "sha256:5e11944542e9889078d2300495882aa854d63854a664d09c5637df0bbc21c0e1"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_aarch64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518953"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.linux-x64"]
+checksum = "sha256:2b8d7fd52771f26d7a50260ef10cd6fe704d66f60102e566362b84da09884ab7"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_x86_64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518865"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.macos-arm64"]
+checksum = "sha256:aef03ff2faaf87594068ec3ab794dcc1acd8d64f2aa3109785244c8359fbf15b"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_arm64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518817"
+provenance = "github-attestations"
+
+[tools.lefthook."platforms.macos-x64"]
+checksum = "sha256:016e560b0cc982f45df14c301509e05b5c4265655eea996495093cd0c632063a"
+url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_x86_64.gz"
+url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518821"
+provenance = "github-attestations"
diff --git a/mise.desk.toml b/mise.desk.toml
new file mode 100644
index 0000000..968a865
--- /dev/null
+++ b/mise.desk.toml
@@ -0,0 +1,6 @@
+# mise.desk.toml - the tools only a desk runs, read when MISE_ENV=desk; see: mise.toml
+#
+# Lefthook runs the pre-commit hook, and a runner commits nothing.
+
+[tools]
+lefthook = "2.2"
diff --git a/mise.lock b/mise.lock
index 74927b8..7a2a4a8 100644
--- a/mise.lock
+++ b/mise.lock
@@ -2,53 +2,6 @@
 
 lockfile_version = 3
 
-[[tools.actionlint]]
-version = "1.7.12"
-backend = "aqua:rhysd/actionlint"
-specifiers = ["1.7"]
-
-[tools.actionlint."platforms.linux-arm64"]
-checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.linux-arm64-musl"]
-checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.linux-x64"]
-checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.linux-x64-musl"]
-checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.macos-arm64"]
-checksum = "sha256:aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_arm64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924893"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.macos-x64"]
-checksum = "sha256:5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_amd64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924880"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.windows-x64"]
-checksum = "sha256:6e7241b51e6817ea6a047693d8e6fed13b31819c9a0dd6c5a726e1592d22f6e9"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_windows_amd64.zip"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924919"
-provenance = "github-attestations"
-
 [[tools.bats]]
 version = "1.13.0"
 backend = "aqua:bats-core/bats-core"
@@ -213,35 +166,6 @@ checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
 
-[[tools.lefthook]]
-version = "2.2.2"
-backend = "aqua:evilmartians/lefthook"
-specifiers = ["2.2"]
-
-[tools.lefthook."platforms.linux-arm64"]
-checksum = "sha256:5e11944542e9889078d2300495882aa854d63854a664d09c5637df0bbc21c0e1"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_aarch64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518953"
-provenance = "github-attestations"
-
-[tools.lefthook."platforms.linux-x64"]
-checksum = "sha256:2b8d7fd52771f26d7a50260ef10cd6fe704d66f60102e566362b84da09884ab7"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_Linux_x86_64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518865"
-provenance = "github-attestations"
-
-[tools.lefthook."platforms.macos-arm64"]
-checksum = "sha256:aef03ff2faaf87594068ec3ab794dcc1acd8d64f2aa3109785244c8359fbf15b"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_arm64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518817"
-provenance = "github-attestations"
-
-[tools.lefthook."platforms.macos-x64"]
-checksum = "sha256:016e560b0cc982f45df14c301509e05b5c4265655eea996495093cd0c632063a"
-url = "https://github.com/evilmartians/lefthook/releases/download/v2.2.2/lefthook_2.2.2_MacOS_x86_64.gz"
-url_api = "https://api.github.com/repos/evilmartians/lefthook/releases/assets/636518821"
-provenance = "github-attestations"
-
 [[tools.shellcheck]]
 version = "0.11.0"
 backend = "aqua:koalaman/shellcheck"
diff --git a/mise.toml b/mise.toml
index dc9c9b7..98f3348 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,9 +1,10 @@
-# mise.toml - the pinned toolchain a desk and a runner share; see: https://mise.jdx.dev/configuration.html
+# mise.toml - the pinned tools a desk and a runner share; see: https://mise.jdx.dev/configuration/environments.html
 #
-# Every tool both a desk and a CI runner run, at one version, installed the same way by `mise install` and by
-# `jdx/mise-action`. A tool only a desk runs would go in mise.desk.toml, which mise reads when MISE_ENV=desk; a desk
-# sets that in its shell profile and a runner leaves it unset. Nothing is desk-only today. `lockfile = true` records each pin's exact
-# resolution in mise.lock. git and bash come from the machine.
+# Three files, one mechanism: mise reads this one always, mise.desk.toml on top of it when MISE_ENV=desk, which a
+# desk exports in its shell profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in
+# the file of whoever runs it. `lockfile = true` records each pin's exact resolution in a lock beside its file,
+# and lockfile_platforms makes a lock written on a desk carry the runner's platform. git and bash come from the
+# machine.
 
 [settings]
 lockfile = true
@@ -15,10 +16,8 @@ lockfile_platforms = ["linux-x64", "linux-arm64", "macos-arm64", "macos-x64"]
 _.path = ["bin"]
 
 [tools]
-actionlint = "1.7"
 gh = "2.103"
 jq = "1.8"
 just = "1.59"
-lefthook = "2.2"
 shellcheck = "0.11"
 bats = "1.13"
diff --git a/tests/lint.bats b/tests/lint.bats
index 86cdc4b..96aa0cd 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -3,6 +3,7 @@
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
+  lefthook version >/dev/null 2>&1 || skip "lefthook is a desk tool (mise.desk.toml, MISE_ENV=desk)"
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
   repo=$(mktemp -d)
   cd "${repo}"
diff --git a/tree/.github/workflows/kit-ci.yml b/tree/.github/workflows/kit-ci.yml
index c4cb81d..b4752d6 100644
--- a/tree/.github/workflows/kit-ci.yml
+++ b/tree/.github/workflows/kit-ci.yml
@@ -25,6 +25,9 @@ jobs:
   CI:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
     runs-on: ubuntu-latest
+    env:
+      # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
+      MISE_ENV: ci
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index 4cc2154..b17c5cc 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -89,9 +89,8 @@ repository root, and `targets/<name>/` for each target taken; a `.json` destinat
 else is copied as it is.
 
 - `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
-- `.kit/lefthook.yml`, which linter runs over which paths before a commit. A repository's `lefthook.yml` takes it
-  with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand, over the staged paths
-  or every path.
+- `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
+  `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
   it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
   `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
diff --git a/tree/.kit/lefthook.yml b/tree/.kit/lefthook.yml
index aea7ecf..bd0f61d 100644
--- a/tree/.kit/lefthook.yml
+++ b/tree/.kit/lefthook.yml
@@ -12,6 +12,3 @@ pre-commit:
     shellcheck:
       glob: "*.{sh,bash}"
       run: shellcheck --shell=bash --external-sources {staged_files}
-    actionlint:
-      glob: ".github/workflows/*.{yml,yaml}"
-      run: actionlint {staged_files}

From 0d9a53305c5113f866b74b7f310b9d76dea01fc0 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:49:10 -0700
Subject: [PATCH 029/108] #1 version: the tag is the version; no file carries
 it

The release workflow stamps the tag's version into the packed kit, which is the only copy: kit version prints it, the manifest records it, and kit update names it to mise for the base of a merge. A checkout reports unreleased. The tag-matches-version check goes, and with it the bump-then-tag two-step; a published release is immutable, so a tag is never reused.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 26 +++++++-------------------
 .kit/manifest                 |  2 +-
 AGENTS.md                     |  8 ++++----
 README.md                     | 16 ++++++++--------
 bin/kit-check.sh              |  4 ++--
 bin/kit-install.sh            |  2 +-
 bin/kit-update.sh             |  4 ++--
 bin/kit-version.sh            |  5 ++++-
 bin/release.sh                | 10 ++++++++--
 tests/kit.bats                |  4 ++--
 tests/release.bats            |  6 ++++--
 version                       |  1 -
 12 files changed, 43 insertions(+), 45 deletions(-)
 delete mode 100644 version

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 85bd9cf..8dafe85 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,11 +1,12 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, and version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, and a stamped version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
 # is tagged on main (any commit on main, not only its head). A pre-release, the same with a -<suffix>, is tagged on
-# a commit that is not on main, and is published as a GitHub pre-release. Either way the file version at the tagged
-# commit is the version without the suffix, the one under development, and the packed kit carries the tag's full
-# version so a consumer pinning a pre-release sees it in kit version and .kit/manifest.
+# a commit that is not on main, and is published as a GitHub pre-release. The tag is the version: the repository
+# carries no version file, and the one in the packed kit is stamped here from the tag, so a consumer sees it in
+# kit version and .kit/manifest and kit update can name the previous release to mise. A release, once published,
+# is immutable, so a tag is never reused.
 #
 # see: .kit/1st.md
 
@@ -56,19 +57,6 @@ jobs:
           fi
           echo "✅ ${GITHUB_REF_NAME} is on the right side of ${default_branch} (on it: ${on_main})."
 
-      - name: tag-matches-version
-        run: |
-          set -o errexit -o nounset -o pipefail
-          tag_version=${GITHUB_REF_NAME#v}
-          base_version=${tag_version%%-*}
-          file_version=$(cat version)
-          if [[ "${base_version}" != "${file_version}" ]]
-          then
-            echo "::error::the tag says ${base_version} and version says ${file_version}; set version at the tagged commit first"
-            exit 1
-          fi
-          echo "✅ version is ${file_version}."
-
       - name: pack-and-release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -77,8 +65,8 @@ jobs:
           version=${GITHUB_REF_NAME#v}
           staging=$(mktemp --directory)
           mkdir "${staging}/kit-${version}"
-          cp --recursive --no-dereference bin tree targets version "${staging}/kit-${version}/"
-          # the packed kit carries the tag's full version, suffix included; the repository file carries the base
+          cp --recursive --no-dereference bin tree targets "${staging}/kit-${version}/"
+          # the packed kit's version is the tag's, suffix included
           printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
           sha256sum "kit-${version}.tar.gz" > "kit-${version}.tar.gz.sha256"
diff --git a/.kit/manifest b/.kit/manifest
index 00e5bd7..ba6e89f 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,5 +1,5 @@
 # .kit/manifest - written by kit, not by hand
-version 0.1.0
+version unreleased
 targets claude
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .claude/rules/kit-bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
diff --git a/AGENTS.md b/AGENTS.md
index 34c98a2..b369027 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,11 +4,11 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
 
 ## This repository's own rules
 
-- The release is `bin/`, `tree/`, `targets/`, and `version`. Everything in it is written for a
+- The release is `bin/`, `tree/`, and `targets/`. Everything in it is written for a
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
-- `version` is the version under development, with no suffix. A release is the tag `v<version>` on a commit on
-  `main`. A pre-release is `v<version>-<suffix>` on a commit that is not on `main`. The release workflow refuses any
-  other pairing, and a tag whose base version differs from the file.
+- A release is the tag `v<version>` on a commit on `main`; a pre-release is `v<version>-<suffix>` on a commit that is
+  not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
+  published release is immutable, so a tag is never reused.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
   this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
   [README.md](README.md) § Maintaining. Edit the source, run `just refresh`, and commit both.
diff --git a/README.md b/README.md
index 2c086c5..3f41014 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
 every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
-the same way; `bin/` and `version` are the machinery: `bin/kit` dispatches to one executable `bin/kit-<verb>.sh`
+the same way; `bin/` is the machinery: `bin/kit` dispatches to one executable `bin/kit-<verb>.sh`
 per verb, and the verbs source the modules beside them, `1st.sh`, `gh.sh`, `git.sh`, and `release.sh`. A symlink
 under `targets/` is delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
 
@@ -98,7 +98,7 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.github/workflows/kit-ci.yml` | `tree/.github/workflows/kit-ci.yml` |
 | `.claude/rules/kit-<kind>.md` | `targets/claude/.claude/rules/`, links into `tree/.kit/rules/` |
 | `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here only the kit's entries |
-| `.kit/manifest` | the release version, the targets taken, and a digest per delivered path |
+| `.kit/manifest` | the release version (`unreleased` here), the targets taken, and a digest per delivered path |
 
 After changing a file under `tree/` or `targets/`, run `just refresh`, which reinstalls the kit into this
 repository, and commit the result with the change. `bin/kit check`, which `just ci` runs, names any installed copy
@@ -107,11 +107,11 @@ that no longer matches its source. Each delivered text file says in its header t
 
 ## Release
 
-`version` carries the version under development, without a suffix. A release is the tag `v<version>` on a
-commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`, say `v0.1.0-rc.1`, on a commit that is
-not on `main`, and it is published as a GitHub pre-release. In both cases the workflow packs the release into
-`kit-<version>.tar.gz` with the tag's full version stamped into the packed `version`, and publishes the release.
-It refuses a tag that is not a version, a release tag off `main`, a pre-release tag on `main`, and a tag whose base
-version is not `version`.
+A release is the tag `v<version>` on a commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`,
+say `v0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a GitHub pre-release. The tag is the
+version: the repository carries no version file, the workflow stamps the tag's version into the packed kit, and a
+published release is immutable, so a tag is never reused. The workflow packs `bin/`, `tree/`, and `targets/` into
+`kit-<version>.tar.gz` and publishes the release; it refuses a tag that is not a version, a release tag off
+`main`, and a pre-release tag on `main`.
 
 Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index f549188..0cb5f12 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -19,9 +19,9 @@ release:require-manifest
 read -r -a targets <<<"$(release:manifest-targets)"
 version=$(release:manifest-version)
 findings=0
-if [[ "${version}" != "$(cat "${kit_root}/version")" ]]
+if [[ "${version}" != "$(release:version)" ]]
 then
-  error ".kit/manifest records kit ${version}, and the pinned release is $(cat "${kit_root}/version"); run: kit update"
+  error ".kit/manifest records kit ${version}, and the pinned release is $(release:version); run: kit update"
   findings=$(( findings + 1 ))
 fi
 while IFS= read -r path
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index 7f83e57..69f27bb 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -22,7 +22,7 @@ then
   error "run: kit update (this repository already carries kit $(release:manifest-version))"
   exit 1
 fi
-section "kit install $(cat "${kit_root}/version")${*:+, targets: $*}"
+section "kit install $(release:version)${*:+, targets: $*}"
 while IFS= read -r path
 do
   step "${path}"
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 1580695..3552913 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -23,14 +23,14 @@ guard:require tool:jq tool:git
 release:require-manifest
 read -r -a targets <<<"$(release:manifest-targets)"
 previous=$(release:manifest-version)
-current=$(cat "${kit_root}/version")
+current=$(release:version)
 section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
 
 base_root=""
 if [[ -n "${KIT_BASE:-}" ]]
 then
   base_root=${KIT_BASE}
-elif [[ "${previous}" != "${current}" ]] && command -v mise >/dev/null 2>&1
+elif [[ "${previous}" != "${current}" && "${previous}" != unreleased ]] && command -v mise >/dev/null 2>&1
 then
   base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
   if [[ -z "${base_root}" ]] && mise install --quiet "github:empowerite/kit@${previous}" 2>/dev/null
diff --git a/bin/kit-version.sh b/bin/kit-version.sh
index 14b2081..0895204 100755
--- a/bin/kit-version.sh
+++ b/bin/kit-version.sh
@@ -3,6 +3,9 @@
 # ----------------------------------------------------------------------------------------------------------------------
 
 set -o errexit -o nounset -o pipefail
-cat "${kit_root:?run through bin/kit}/version"
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
+release:version
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/release.sh b/bin/release.sh
index 16c8a15..2ddbc54 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -11,6 +11,12 @@
 #
 # Every function reads the release from kit_root, exported by bin/kit.
 
+# release:version prints this release's version: the file the release workflow stamps from the tag, and
+# "unreleased" in a checkout, which is what this repository's own installed copy records.
+release:version() {
+  cat "${kit_root}/version" 2>/dev/null || printf 'unreleased\n'
+}
+
 # release:layers <root> <target>… prints the directories mirrored at the repository root, tree first.
 release:layers() {
   local root=$1 t
@@ -131,7 +137,7 @@ release:write-manifest() {
   local path
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
-    printf 'version %s\n' "$(cat "${kit_root}/version")"
+    printf 'version %s\n' "$(release:version)"
     printf 'targets%s\n' "${*:+ $*}"
     while IFS= read -r path
     do
@@ -154,7 +160,7 @@ release:require-manifest() {
 
 # release:finish <target>… reports a completed install or update.
 release:finish() {
-  ok "kit $(cat "${kit_root}/version") is installed, targets: ${*:-none}; .kit/manifest is written."
+  ok "kit $(release:version) is installed, targets: ${*:-none}; .kit/manifest is written."
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
 
diff --git a/tests/kit.bats b/tests/kit.bats
index 1902d2d..55ba6cb 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -38,7 +38,7 @@ later-release() {
   grep --quiet '"\*\*/\*\.sh"' .claude/rules/kit-bash.md
   [ -f .github/workflows/kit-ci.yml ]
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
-  grep --quiet '^version 0.1.0$' .kit/manifest
+  grep --quiet '^version unreleased$' .kit/manifest
   grep --quiet '^targets claude$' .kit/manifest
 }
 
@@ -176,7 +176,7 @@ later-release() {
   mkdir shims && printf '#!/usr/bin/env bash\nexit 1\n' > shims/mise && chmod +x shims/mise
   run env PATH="${PWD}/shims:${PATH}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
-  [[ "$output" == *"base release 0.1.0 is not installed"* ]]
+  [[ "$output" == *"base release unreleased is not installed"* ]]
   rm -rf "${repo}.later"
 }
 
diff --git a/tests/release.bats b/tests/release.bats
index a437c5d..6da12a3 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -13,9 +13,11 @@ teardown() {
 }
 
 @test "the tarball holds one directory with the release's layout, and installs a fresh repository" {
-  version=$(cat "${kit_checkout}/version")
+  # packed the way the workflow packs it, with the tag's version stamped in
+  version=9.9.9
   mkdir "kit-${version}"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "${kit_checkout}/version" "kit-${version}/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "kit-${version}/"
+  printf '%s\n' "${version}" > "kit-${version}/version"
   tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
   rm -rf "kit-${version}"
   mkdir unpacked && tar --extract --gzip --file "kit-${version}.tar.gz" --directory unpacked
diff --git a/version b/version
deleted file mode 100644
index 6e8bf73..0000000
--- a/version
+++ /dev/null
@@ -1 +0,0 @@
-0.1.0

From 4bbed00a79d6751b3ee6013ddbaf77803ae7576f Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:52:55 -0700
Subject: [PATCH 030/108] #1 .github/workflows/release.yml: a release retires
 its pre-releases, tags and all

Checked by hand on this repository: an immutable pre-release deletes with its tag, and the tag name can never be reused. The step runs only for a release, never a pre-release.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 21 ++++++++++++++++++++-
 AGENTS.md                     |  2 +-
 README.md                     |  2 +-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8dafe85..30e7211 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -6,7 +6,8 @@
 # a commit that is not on main, and is published as a GitHub pre-release. The tag is the version: the repository
 # carries no version file, and the one in the packed kit is stamped here from the tag, so a consumer sees it in
 # kit version and .kit/manifest and kit update can name the previous release to mise. A release, once published,
-# is immutable, so a tag is never reused.
+# is immutable, so a tag is never reused. A release retires its pre-releases: every v<version>-<suffix> goes, tag
+# and all, since the release is what they led to; a consumer still pinned to one re-pins to the release.
 #
 # see: .kit/1st.md
 
@@ -77,4 +78,22 @@ jobs:
             --title "kit ${version}" --notes "${notes}" "${flags[@]}"
           echo "✅ Released kit ${version}."
 
+      - name: retire-pre-releases
+        if: ${{ !contains(github.ref_name, '-') }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+          version=${GITHUB_REF_NAME#v}
+          retired=0
+          while IFS= read -r tag
+          do
+            [[ -n "${tag}" ]] || continue
+            gh release delete "${tag}" --cleanup-tag --yes
+            echo "retired ${tag}"
+            retired=$(( retired + 1 ))
+          done < <(gh release list --json tagName,isPrerelease \
+            --jq ".[] | select(.isPrerelease and (.tagName | startswith(\"v${version}-\"))) | .tagName")
+          echo "✅ Retired ${retired} pre-release(s) of ${version}."
+
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/AGENTS.md b/AGENTS.md
index b369027..d54c444 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
 - A release is the tag `v<version>` on a commit on `main`; a pre-release is `v<version>-<suffix>` on a commit that is
   not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
-  published release is immutable, so a tag is never reused.
+  published release is immutable, so a tag is never reused. A release retires its pre-releases, tags and all.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
   this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
   [README.md](README.md) § Maintaining. Edit the source, run `just refresh`, and commit both.
diff --git a/README.md b/README.md
index 3f41014..a81f4b9 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,6 @@ say `v0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a G
 version: the repository carries no version file, the workflow stamps the tag's version into the packed kit, and a
 published release is immutable, so a tag is never reused. The workflow packs `bin/`, `tree/`, and `targets/` into
 `kit-<version>.tar.gz` and publishes the release; it refuses a tag that is not a version, a release tag off
-`main`, and a pre-release tag on `main`.
+`main`, and a pre-release tag on `main`. A release retires its pre-releases, `v<version>-*`, tags and all.
 
 Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf

From 28d246eca5e767b1efb8c32607b83b943df404c7 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:54:59 -0700
Subject: [PATCH 031/108] #1 .github/workflows/retire-pre-releases.yml: a
 pre-release lives as long as its branch

A release is permanent. On a branch deletion, every pre-release whose commit no remaining branch reaches is deleted with its tag. The release workflow no longer touches pre-releases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml             | 22 +--------
 .github/workflows/retire-pre-releases.yml | 58 +++++++++++++++++++++++
 AGENTS.md                                 |  2 +-
 README.md                                 |  3 +-
 4 files changed, 63 insertions(+), 22 deletions(-)
 create mode 100644 .github/workflows/retire-pre-releases.yml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 30e7211..6bf2899 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -6,8 +6,8 @@
 # a commit that is not on main, and is published as a GitHub pre-release. The tag is the version: the repository
 # carries no version file, and the one in the packed kit is stamped here from the tag, so a consumer sees it in
 # kit version and .kit/manifest and kit update can name the previous release to mise. A release, once published,
-# is immutable, so a tag is never reused. A release retires its pre-releases: every v<version>-<suffix> goes, tag
-# and all, since the release is what they led to; a consumer still pinned to one re-pins to the release.
+# is immutable, so a tag is never reused. A pre-release lives as long as the branch it was tagged on; see:
+# .github/workflows/retire-pre-releases.yml
 #
 # see: .kit/1st.md
 
@@ -78,22 +78,4 @@ jobs:
             --title "kit ${version}" --notes "${notes}" "${flags[@]}"
           echo "✅ Released kit ${version}."
 
-      - name: retire-pre-releases
-        if: ${{ !contains(github.ref_name, '-') }}
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-          version=${GITHUB_REF_NAME#v}
-          retired=0
-          while IFS= read -r tag
-          do
-            [[ -n "${tag}" ]] || continue
-            gh release delete "${tag}" --cleanup-tag --yes
-            echo "retired ${tag}"
-            retired=$(( retired + 1 ))
-          done < <(gh release list --json tagName,isPrerelease \
-            --jq ".[] | select(.isPrerelease and (.tagName | startswith(\"v${version}-\"))) | .tagName")
-          echo "✅ Retired ${retired} pre-release(s) of ${version}."
-
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
new file mode 100644
index 0000000..8229061
--- /dev/null
+++ b/.github/workflows/retire-pre-releases.yml
@@ -0,0 +1,58 @@
+# retire-pre-releases.yml - a pre-release lives as long as the branch it was tagged on
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# A pre-release is tagged on a commit that is not on main, and main takes a branch by squash, so once the branch is
+# deleted its commits are reachable from nothing but the pre-release's own tag. This runs on every branch deletion
+# and retires, tag and all, each pre-release whose commit no remaining branch reaches. A release is never touched:
+# it is on main, which is never deleted. A deleted tag is a delete event too, and that one is ignored here.
+#
+# Checked by hand: an immutable pre-release deletes with its tag, and the tag name can never be reused.
+#
+# see: .github/workflows/release.yml
+
+name: retire-pre-releases
+
+on:
+  delete:
+
+permissions:
+  contents: write
+
+jobs:
+  retire:
+    if: github.event.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: retire-unreachable-pre-releases
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -o errexit -o nounset -o pipefail
+          git fetch --quiet --tags origin
+          deleted=$(jq --raw-output '.ref' "${GITHUB_EVENT_PATH}")
+          retired=0
+          while IFS= read -r tag
+          do
+            [[ -n "${tag}" ]] || continue
+            commit=$(git rev-parse --verify --quiet "${tag}^{commit}" || true)
+            if [[ -z "${commit}" ]]
+            then
+              echo "::warning::${tag} has no commit here; leaving it"
+              continue
+            fi
+            if git branch --remotes --contains "${commit}" | grep --quiet --invert-match 'origin/HEAD'
+            then
+              echo "keeping ${tag}: a branch still reaches ${commit:0:7}"
+              continue
+            fi
+            gh release delete "${tag}" --cleanup-tag --yes
+            echo "retired ${tag}: no branch reaches ${commit:0:7} since ${deleted} was deleted"
+            retired=$(( retired + 1 ))
+          done < <(gh release list --json tagName,isPrerelease --jq '.[] | select(.isPrerelease) | .tagName')
+          echo "✅ Retired ${retired} pre-release(s)."
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/AGENTS.md b/AGENTS.md
index d54c444..a670656 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
 - A release is the tag `v<version>` on a commit on `main`; a pre-release is `v<version>-<suffix>` on a commit that is
   not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
-  published release is immutable, so a tag is never reused. A release retires its pre-releases, tags and all.
+  published release is immutable, so a tag is never reused. A release is permanent; a pre-release is retired when the branch it was tagged on is deleted.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
   this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
   [README.md](README.md) § Maintaining. Edit the source, run `just refresh`, and commit both.
diff --git a/README.md b/README.md
index a81f4b9..9dcb06a 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,7 @@ say `v0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a G
 version: the repository carries no version file, the workflow stamps the tag's version into the packed kit, and a
 published release is immutable, so a tag is never reused. The workflow packs `bin/`, `tree/`, and `targets/` into
 `kit-<version>.tar.gz` and publishes the release; it refuses a tag that is not a version, a release tag off
-`main`, and a pre-release tag on `main`. A release retires its pre-releases, `v<version>-*`, tags and all.
+`main`, and a pre-release tag on `main`. A release is permanent. A pre-release is retired, tag and all, when the
+branch it was tagged on is deleted and no other branch reaches its commit.
 
 Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf

From 76f202c0c1bae1e790661627127faa666af6c369 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 00:58:07 -0700
Subject: [PATCH 032/108] #1 bin/gh.sh, bin/git.sh, kit-ci.yml: three findings
 from review

The start commit is made with --only, so work already staged in a reused worktree stays in the index. A clean detached worktree is residue only when origin/main already has its commit; otherwise tidy keeps it. The delivered gate fails when the root justfile cannot be read, and skips only when the recipe is absent.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml      | 12 +++++++-
 .kit/manifest                     |  2 +-
 bin/gh.sh                         |  3 +-
 bin/git.sh                        | 17 ++++++++---
 tests/tidy.bats                   | 51 +++++++++++++++++++++++++++++++
 tree/.github/workflows/kit-ci.yml | 12 +++++++-
 6 files changed, 89 insertions(+), 8 deletions(-)
 create mode 100644 tests/tidy.bats

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index b4752d6..5b3b9de 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -37,7 +37,17 @@ jobs:
       - name: gate
         run: |
           set -o errexit -o nounset -o pipefail
-          if [[ ! -f justfile ]] || ! just --show ci >/dev/null 2>&1
+          # A missing recipe is a skip; a justfile that cannot be read is a failure, never a silent skip.
+          if [[ ! -f justfile ]]
+          then
+            echo "::warning::there is no root justfile, so the gate was skipped"
+            printf '⚠️ The gate was skipped: there is no root justfile.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+          elif ! recipes=$(just --summary 2>&1)
+          then
+            echo "::error::the root justfile could not be read: ${recipes}"
+            printf '### ❌ The root justfile could not be read\n\n%s\n' "${recipes}" | tee --append "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          elif ! tr ' ' '\n' <<< "${recipes}" | grep --quiet --line-regexp ci
           then
             echo "::warning::the root justfile has no ci recipe, so the gate was skipped"
             printf '⚠️ The gate was skipped: the root justfile has no ci recipe.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
diff --git a/.kit/manifest b/.kit/manifest
index ba6e89f..d9696d9 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -8,7 +8,7 @@ targets claude
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
-5d6f7c4590fe03be20b8208a14539203ee252fe74012f7796a2c1e9bcc42be08  .github/workflows/kit-ci.yml
+54014b457cbb469ee2d47d80edd5bc74cb1670afc235fc223d1f4e77ea78e859  .github/workflows/kit-ci.yml
 a8bc796a9e2a6c907ca61e59f02946dca1cb03833c01f34da6fbdc091e604d23  .kit/1st.md
 dc9d98436a1f4ac03a7b92cc844d7a2064fbca89ebe21bc8ff243e25f8d0225c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
diff --git a/bin/gh.sh b/bin/gh.sh
index 42ff316..368870b 100644
--- a/bin/gh.sh
+++ b/bin/gh.sh
@@ -163,10 +163,11 @@ gh:issue() {
   fi
 
   # GitHub cannot open a pull request on a branch with nothing to compare, so the first commit is an empty one.
+  # --only keeps it empty: work already staged in a reused worktree stays in the index, not in this commit.
   if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
   then
     step "Adding the start commit"
-    git -C "${wt}" commit --quiet --allow-empty --message "start: #${primary} ${title}"
+    git -C "${wt}" commit --quiet --allow-empty --only --message "start: #${primary} ${title}"
   fi
   git -C "${wt}" push --quiet --set-upstream origin "${branch}"
 
diff --git a/bin/git.sh b/bin/git.sh
index 9feac52..4738cd0 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -6,9 +6,10 @@
 # with its branch, pull request, and dirty or clean state, then the local branches whose upstream is gone. It
 # changes nothing.
 #
-# git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, prunes
-# the worktree bookkeeping, and deletes every local branch whose upstream is gone. It never touches the default
-# branch, a branch checked out in a live worktree, a dirty worktree, or the worktree it runs in. --dry-run
+# git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
+# detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
+# every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a live
+# worktree, a dirty worktree, a detached worktree whose commit nothing else reaches, or the worktree it runs in. --dry-run
 # prints what a sweep would do and changes nothing.
 #
 # git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto
@@ -120,7 +121,15 @@ git:tidy-worktree() {
     fi
   elif [[ "${detached}" == true && -z "$(git -C "${path}" status --porcelain 2>/dev/null)" ]]
   then
-    state=DETACHED
+    # A clean detached checkout is residue only when its commit is already on the default branch; otherwise its
+    # HEAD may be the only thing that reaches that commit, and removing the worktree would lose it.
+    if git -C "${path}" merge-base --is-ancestor HEAD "origin/${default_branch}" 2>/dev/null
+    then
+      state=DETACHED
+    else
+      step "keeping ${path} (detached at a commit origin/${default_branch} does not reach)"
+      return 0
+    fi
   fi
   case "${state}" in
     (MERGED | CLOSED | DETACHED)
diff --git a/tests/tidy.bats b/tests/tidy.bats
new file mode 100644
index 0000000..285e523
--- /dev/null
+++ b/tests/tidy.bats
@@ -0,0 +1,51 @@
+#!/usr/bin/env bats
+# tidy.bats - the one decision in tidy that needs no GitHub: a clean detached worktree is residue only when the
+# default branch already has its commit
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  export kit_root
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  work=$(mktemp -d)
+  cd "${work}"
+  git init --quiet --bare --initial-branch=main origin.git
+  git clone --quiet origin.git desk 2>/dev/null
+  cd desk
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  printf 'one\n' > a && git add a && git commit --quiet --message one && git push --quiet origin main
+  git remote set-head origin main
+  mkdir worktrees
+}
+
+teardown() {
+  rm -rf "${work}"
+}
+
+# decide <path> runs tidy's per-worktree decision on <path>, a detached checkout, with tidy's globals in place.
+decide() {
+  bash -c '
+    source "${kit_root}/bin/1st.sh" && use git
+    found=false; dry_run=false; removed_worktrees=0; declare -A freed=()
+    self_root=$(git rev-parse --show-toplevel); default_branch=main
+    git:tidy-worktree "$1" "" true
+  ' _ "$1"
+}
+
+@test "a clean detached worktree at a commit on main is removed" {
+  git worktree add --quiet --detach worktrees/old HEAD
+  run decide "${PWD}/worktrees/old"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"removing"* ]]
+  [ ! -e worktrees/old ]
+}
+
+@test "a clean detached worktree at a commit main does not reach is kept" {
+  git worktree add --quiet --detach worktrees/only HEAD
+  printf 'two\n' > worktrees/only/b && git -C worktrees/only add b && git -C worktrees/only commit --quiet --message two
+  run decide "${PWD}/worktrees/only"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"keeping"* ]]
+  [ -e worktrees/only ]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tree/.github/workflows/kit-ci.yml b/tree/.github/workflows/kit-ci.yml
index b4752d6..5b3b9de 100644
--- a/tree/.github/workflows/kit-ci.yml
+++ b/tree/.github/workflows/kit-ci.yml
@@ -37,7 +37,17 @@ jobs:
       - name: gate
         run: |
           set -o errexit -o nounset -o pipefail
-          if [[ ! -f justfile ]] || ! just --show ci >/dev/null 2>&1
+          # A missing recipe is a skip; a justfile that cannot be read is a failure, never a silent skip.
+          if [[ ! -f justfile ]]
+          then
+            echo "::warning::there is no root justfile, so the gate was skipped"
+            printf '⚠️ The gate was skipped: there is no root justfile.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+          elif ! recipes=$(just --summary 2>&1)
+          then
+            echo "::error::the root justfile could not be read: ${recipes}"
+            printf '### ❌ The root justfile could not be read\n\n%s\n' "${recipes}" | tee --append "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          elif ! tr ' ' '\n' <<< "${recipes}" | grep --quiet --line-regexp ci
           then
             echo "::warning::the root justfile has no ci recipe, so the gate was skipped"
             printf '⚠️ The gate was skipped: the root justfile has no ci recipe.\n' | tee --append "${GITHUB_STEP_SUMMARY}"

From 070a500c563a52a60b40799c3ffb5f6fd18687eb Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:04:15 -0700
Subject: [PATCH 033/108] #1 lefthook.yml: a commit that changes a delivered
 file's source refreshes the installed copies

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 AGENTS.md               |  6 ++++--
 README.md               |  5 +++--
 lefthook.yml            | 11 +++++++++--
 tree/.kit/rules/json.md |  2 ++
 4 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index a670656..d73b5d2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,8 +8,10 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
 - A release is the tag `v<version>` on a commit on `main`; a pre-release is `v<version>-<suffix>` on a commit that is
   not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
-  published release is immutable, so a tag is never reused. A release is permanent; a pre-release is retired when the branch it was tagged on is deleted.
+  published release is immutable, so a tag is never reused. A release is permanent; a pre-release is retired when
+  the branch it was tagged on is deleted.
 - `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
   this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
-  [README.md](README.md) § Maintaining. Edit the source, run `just refresh`, and commit both.
+  [README.md](README.md) § Maintaining. Edit the source; the pre-commit hook refreshes the copies into the same
+  commit, and a desk without the hook runs `just refresh` and commits both.
 - `just ci` is the gate: shellcheck, actionlint, the bats suite, and `bin/kit check`.
diff --git a/README.md b/README.md
index 9dcb06a..1a24c47 100644
--- a/README.md
+++ b/README.md
@@ -100,8 +100,9 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version (`unreleased` here), the targets taken, and a digest per delivered path |
 
-After changing a file under `tree/` or `targets/`, run `just refresh`, which reinstalls the kit into this
-repository, and commit the result with the change. `bin/kit check`, which `just ci` runs, names any installed copy
+A commit that changes a file under `tree/` or `targets/` rewrites the installed copies in the same commit: the
+pre-commit hook runs `just refresh` and stages what it rewrote. On a desk without the hook, run `just refresh`
+by hand and commit the result with the change. `bin/kit check`, which `just ci` runs, names any installed copy
 that no longer matches its source. Each delivered text file says in its header that it is delivered by kit;
 `settings.json` cannot, so this table is its notice.
 
diff --git a/lefthook.yml b/lefthook.yml
index b1677f2..6d163c4 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,8 +1,9 @@
 # lefthook.yml - this repository's git hooks; see: https://lefthook.dev
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The kit's own linters come from its installed fragment, the way a consumer takes them, and the dispatcher, which
-# carries no extension, is added here. Once per clone: lefthook install
+# The kit's own linters come from its installed fragment, the way a consumer takes them; the dispatcher, which
+# carries no extension, and the refresh of the installed copies are this repository's own. Once per clone:
+# lefthook install
 
 extends:
   - .kit/lefthook.yml
@@ -12,3 +13,9 @@ pre-commit:
     shellcheck-dispatcher:
       glob: "bin/kit"
       run: shellcheck --shell=bash --external-sources {staged_files}
+    # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, so
+    # nobody remembers just refresh. stage_fixed adds what the refresh rewrote to the commit.
+    refresh:
+      glob: "{tree,targets}/**"
+      run: just refresh
+      stage_fixed: true
diff --git a/tree/.kit/rules/json.md b/tree/.kit/rules/json.md
index 692c8aa..18391b6 100644
--- a/tree/.kit/rules/json.md
+++ b/tree/.kit/rules/json.md
@@ -25,3 +25,5 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
+
+<!-- refresh-proof -->

From 0f750556715c893a877c5c1bb27066d9b4385799 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:04:16 -0700
Subject: [PATCH 034/108] #1 tree/.kit/rules/json.md: the proof line goes

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tree/.kit/rules/json.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tree/.kit/rules/json.md b/tree/.kit/rules/json.md
index 18391b6..692c8aa 100644
--- a/tree/.kit/rules/json.md
+++ b/tree/.kit/rules/json.md
@@ -25,5 +25,3 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
-
-<!-- refresh-proof -->

From fc04e3d0faf28007900ba1e3fdcd450e7629d92d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:05:27 -0700
Subject: [PATCH 035/108] #1 lefthook.yml: the refresh stages the copies it
 rewrote

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-json.md | 2 ++
 .kit/manifest             | 4 ++--
 .kit/rules/json.md        | 2 ++
 lefthook.yml              | 6 +++---
 tree/.kit/rules/json.md   | 2 ++
 5 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
index 692c8aa..18391b6 100644
--- a/.claude/rules/kit-json.md
+++ b/.claude/rules/kit-json.md
@@ -25,3 +25,5 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
+
+<!-- refresh-proof -->
diff --git a/.kit/manifest b/.kit/manifest
index d9696d9..28e8b54 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,7 +3,7 @@ version unreleased
 targets claude
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .claude/rules/kit-bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
-1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .claude/rules/kit-json.md
+85506123b2e18da1ecca6f4342c344667fe2f1bfb185dc78bc76958ead1fb7c6  .claude/rules/kit-json.md
 98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .claude/rules/kit-just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
@@ -13,7 +13,7 @@ a8bc796a9e2a6c907ca61e59f02946dca1cb03833c01f34da6fbdc091e604d23  .kit/1st.md
 dc9d98436a1f4ac03a7b92cc844d7a2064fbca89ebe21bc8ff243e25f8d0225c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
-1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
+85506123b2e18da1ecca6f4342c344667fe2f1bfb185dc78bc76958ead1fb7c6  .kit/rules/json.md
 98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .kit/rules/just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .kit/rules/markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .kit/rules/yaml.md
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
index 692c8aa..18391b6 100644
--- a/.kit/rules/json.md
+++ b/.kit/rules/json.md
@@ -25,3 +25,5 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
+
+<!-- refresh-proof -->
diff --git a/lefthook.yml b/lefthook.yml
index 6d163c4..a348d5f 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -14,8 +14,8 @@ pre-commit:
       glob: "bin/kit"
       run: shellcheck --shell=bash --external-sources {staged_files}
     # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, so
-    # nobody remembers just refresh. stage_fixed adds what the refresh rewrote to the commit.
+    # nobody remembers just refresh. The command stages what it rewrote itself: stage_fixed would re-stage only
+    # the source paths it was handed, and the copies live elsewhere.
     refresh:
       glob: "{tree,targets}/**"
-      run: just refresh
-      stage_fixed: true
+      run: just refresh && git add .kit .claude .github/workflows/kit-ci.yml
diff --git a/tree/.kit/rules/json.md b/tree/.kit/rules/json.md
index 692c8aa..18391b6 100644
--- a/tree/.kit/rules/json.md
+++ b/tree/.kit/rules/json.md
@@ -25,3 +25,5 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
+
+<!-- refresh-proof -->

From 030ef20c00ae51fb0cdca0f6a9210603d72edeb0 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:05:27 -0700
Subject: [PATCH 036/108] #1 tree/.kit/rules/json.md: the proof line goes

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-json.md | 2 --
 .kit/manifest             | 4 ++--
 .kit/rules/json.md        | 2 --
 tree/.kit/rules/json.md   | 2 --
 4 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
index 18391b6..692c8aa 100644
--- a/.claude/rules/kit-json.md
+++ b/.claude/rules/kit-json.md
@@ -25,5 +25,3 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
-
-<!-- refresh-proof -->
diff --git a/.kit/manifest b/.kit/manifest
index 28e8b54..d9696d9 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,7 +3,7 @@ version unreleased
 targets claude
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .claude/rules/kit-bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
-85506123b2e18da1ecca6f4342c344667fe2f1bfb185dc78bc76958ead1fb7c6  .claude/rules/kit-json.md
+1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .claude/rules/kit-json.md
 98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .claude/rules/kit-just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
@@ -13,7 +13,7 @@ a8bc796a9e2a6c907ca61e59f02946dca1cb03833c01f34da6fbdc091e604d23  .kit/1st.md
 dc9d98436a1f4ac03a7b92cc844d7a2064fbca89ebe21bc8ff243e25f8d0225c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
-85506123b2e18da1ecca6f4342c344667fe2f1bfb185dc78bc76958ead1fb7c6  .kit/rules/json.md
+1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
 98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .kit/rules/just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .kit/rules/markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .kit/rules/yaml.md
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
index 18391b6..692c8aa 100644
--- a/.kit/rules/json.md
+++ b/.kit/rules/json.md
@@ -25,5 +25,3 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
-
-<!-- refresh-proof -->
diff --git a/tree/.kit/rules/json.md b/tree/.kit/rules/json.md
index 18391b6..692c8aa 100644
--- a/tree/.kit/rules/json.md
+++ b/tree/.kit/rules/json.md
@@ -25,5 +25,3 @@ Applies to `*.json` and `*.jsonc`.
 
 1. A comment states what the entry does and the non-obvious why. It carries no history.
 2. A pointer is `// see: <ref>`.
-
-<!-- refresh-proof -->

From fa8881916611a90067e10ae662ed3d4c75b916ae Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:07:35 -0700
Subject: [PATCH 037/108] #1 mise.toml: actionlint runs on a desk too, so it is
 shared and mise.ci.toml goes

actionlint reads workflow files and needs no runner. It is pinned with the shared tools, back in the pre-commit fragment over the workflows, and the gate is just ci wherever it runs. MISE_ENV=ci stays in the delivered job for a consumer with a runner-only tool.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/lefthook.yml      |  3 +++
 .kit/manifest          |  2 +-
 README.md              |  2 +-
 justfile               | 11 +++++------
 mise.ci.lock           | 32 --------------------------------
 mise.ci.toml           |  6 ------
 mise.lock              | 29 +++++++++++++++++++++++++++++
 mise.toml              |  7 ++++---
 tree/.kit/lefthook.yml |  3 +++
 9 files changed, 46 insertions(+), 49 deletions(-)
 delete mode 100644 mise.ci.lock
 delete mode 100644 mise.ci.toml

diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index bd0f61d..aea7ecf 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -12,3 +12,6 @@ pre-commit:
     shellcheck:
       glob: "*.{sh,bash}"
       run: shellcheck --shell=bash --external-sources {staged_files}
+    actionlint:
+      glob: ".github/workflows/*.{yml,yaml}"
+      run: actionlint {staged_files}
diff --git a/.kit/manifest b/.kit/manifest
index d9696d9..7e1a54a 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -10,7 +10,7 @@ targets claude
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
 54014b457cbb469ee2d47d80edd5bc74cb1670afc235fc223d1f4e77ea78e859  .github/workflows/kit-ci.yml
 a8bc796a9e2a6c907ca61e59f02946dca1cb03833c01f34da6fbdc091e604d23  .kit/1st.md
-dc9d98436a1f4ac03a7b92cc844d7a2064fbca89ebe21bc8ff243e25f8d0225c  .kit/lefthook.yml
+4460940e906891560f03ee5a5c2b2a61e9f814b05cf32a5917933e902a6ed45c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
diff --git a/README.md b/README.md
index 1a24c47..7b705bc 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ lefthook install
 
 `MISE_ENV=desk` belongs in your shell profile. mise reads `mise.toml` always, `mise.desk.toml` on top of it when
 `MISE_ENV=desk`, and `mise.ci.toml` when `MISE_ENV=ci`, which the CI workflow sets: a tool goes in the file of
-whoever runs it. Lefthook is a desk's; actionlint is the runner's.
+whoever runs it. Lefthook is a desk's; nothing here is the runner's alone.
 
 This repository carries the installed copy of its own kit, and `just ci` checks it.
 
diff --git a/justfile b/justfile
index f06328f..04a8e40 100644
--- a/justfile
+++ b/justfile
@@ -20,13 +20,12 @@ _: help
 
 set export := true
 
-# The runner's gate, run with MISE_ENV=ci so mise.ci.toml's tools are on hand: shellcheck over every bash file,
-# actionlint over every workflow, the bats suite, and bin/kit check over this repository's installed copy of its
-# own kit. A desk runs it the same way: MISE_ENV=ci just ci. The pre-commit hook on a desk is the narrower,
-# faster check lefthook.yml declares.
+# The gate: shellcheck over every bash file, actionlint over every workflow, the bats suite, and bin/kit check over
+# this repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
+# same way; the pre-commit hook is the narrower, faster check over the staged paths.
 #
-#   MISE_ENV=ci just ci
-[doc("🚦 The runner's gate: shellcheck, actionlint, bats, kit check (MISE_ENV=ci)")]
+#   just ci
+[doc("🚦 The gate: shellcheck, actionlint, bats, kit check")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
diff --git a/mise.ci.lock b/mise.ci.lock
deleted file mode 100644
index 6d43300..0000000
--- a/mise.ci.lock
+++ /dev/null
@@ -1,32 +0,0 @@
-# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
-
-lockfile_version = 3
-
-[[tools.actionlint]]
-version = "1.7.12"
-backend = "aqua:rhysd/actionlint"
-specifiers = ["1.7"]
-
-[tools.actionlint."platforms.linux-arm64"]
-checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.linux-x64"]
-checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.macos-arm64"]
-checksum = "sha256:aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_arm64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924893"
-provenance = "github-attestations"
-
-[tools.actionlint."platforms.macos-x64"]
-checksum = "sha256:5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644"
-url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_amd64.tar.gz"
-url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924880"
-provenance = "github-attestations"
diff --git a/mise.ci.toml b/mise.ci.toml
deleted file mode 100644
index face1c9..0000000
--- a/mise.ci.toml
+++ /dev/null
@@ -1,6 +0,0 @@
-# mise.ci.toml - the tools only a runner runs, read when MISE_ENV=ci; see: mise.toml
-#
-# actionlint checks the workflows, which only the runner executes; a desk runs it with MISE_ENV=ci when it wants to.
-
-[tools]
-actionlint = "1.7"
diff --git a/mise.lock b/mise.lock
index 7a2a4a8..9ad23a6 100644
--- a/mise.lock
+++ b/mise.lock
@@ -2,6 +2,35 @@
 
 lockfile_version = 3
 
+[[tools.actionlint]]
+version = "1.7.12"
+backend = "aqua:rhysd/actionlint"
+specifiers = ["1.7"]
+
+[tools.actionlint."platforms.linux-arm64"]
+checksum = "sha256:325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924897"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.linux-x64"]
+checksum = "sha256:8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924896"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-arm64"]
+checksum = "sha256:aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_arm64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924893"
+provenance = "github-attestations"
+
+[tools.actionlint."platforms.macos-x64"]
+checksum = "sha256:5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644"
+url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_darwin_amd64.tar.gz"
+url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/384924880"
+provenance = "github-attestations"
+
 [[tools.bats]]
 version = "1.13.0"
 backend = "aqua:bats-core/bats-core"
diff --git a/mise.toml b/mise.toml
index 98f3348..9b061db 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,8 +1,8 @@
 # mise.toml - the pinned tools a desk and a runner share; see: https://mise.jdx.dev/configuration/environments.html
 #
-# Three files, one mechanism: mise reads this one always, mise.desk.toml on top of it when MISE_ENV=desk, which a
-# desk exports in its shell profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in
-# the file of whoever runs it. `lockfile = true` records each pin's exact resolution in a lock beside its file,
+# One mechanism: mise reads this file always, mise.desk.toml on top of it when MISE_ENV=desk, which a desk exports
+# in its shell profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in the file of
+# whoever runs it; today only Lefthook is a desk's alone, and nothing is the runner's alone. `lockfile = true` records each pin's exact resolution in a lock beside its file,
 # and lockfile_platforms makes a lock written on a desk carry the runner's platform. git and bash come from the
 # machine.
 
@@ -20,4 +20,5 @@ gh = "2.103"
 jq = "1.8"
 just = "1.59"
 shellcheck = "0.11"
+actionlint = "1.7"
 bats = "1.13"
diff --git a/tree/.kit/lefthook.yml b/tree/.kit/lefthook.yml
index bd0f61d..aea7ecf 100644
--- a/tree/.kit/lefthook.yml
+++ b/tree/.kit/lefthook.yml
@@ -12,3 +12,6 @@ pre-commit:
     shellcheck:
       glob: "*.{sh,bash}"
       run: shellcheck --shell=bash --external-sources {staged_files}
+    actionlint:
+      glob: ".github/workflows/*.{yml,yaml}"
+      run: actionlint {staged_files}

From a3ff18b396aa024b41346d2ee125be37335e022a Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:10:02 -0700
Subject: [PATCH 038/108] #1 markdownlint, .editorconfig, dependabot: the
 repository's own gates and upkeep

markdownlint-cli2 over every markdown file, in the pre-commit hook and the gate, with the rule state in .markdownlint.jsonc naming the convention behind each entry. .editorconfig for editors. Dependabot for the SHA-pinned actions, weekly; mise outdated answers for the tools.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .editorconfig                                 |  18 +
 .github/dependabot.yml                        |  18 +
 .markdownlint-cli2.jsonc                      |  10 +
 .markdownlint.jsonc                           |  23 +
 .../0.24.0/aube-lock.yaml                     | 735 ++++++++++++++++++
 .../npm-markdownlint-cli2/0.24.0/package.json |   7 +
 justfile                                      |   6 +-
 lefthook.yml                                  |   3 +
 mise.lock                                     |   6 +
 mise.toml                                     |   1 +
 10 files changed, 825 insertions(+), 2 deletions(-)
 create mode 100644 .editorconfig
 create mode 100644 .github/dependabot.yml
 create mode 100644 .markdownlint-cli2.jsonc
 create mode 100644 .markdownlint.jsonc
 create mode 100644 .mise/locks/npm-markdownlint-cli2/0.24.0/aube-lock.yaml
 create mode 100644 .mise/locks/npm-markdownlint-cli2/0.24.0/package.json

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..f5a3108
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,18 @@
+# .editorconfig - see: https://editorconfig.org
+# ----------------------------------------------------------------------------------------------------------------------
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# a trailing double space is a hard break
+[*.md]
+trim_trailing_whitespace = false
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..4fa4348
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,18 @@
+# dependabot.yml - keeps the SHA-pinned actions in the workflows current
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Every `uses:` in .github/workflows/ is pinned to a full commit SHA with the version as a trailing comment, and a
+# SHA never advances on its own. Dependabot's github-actions ecosystem opens a pull request that moves the SHA and
+# the comment together, weekly. The tools come from mise.toml, which Dependabot does not read; `mise outdated`
+# answers for those.
+#
+# see: https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
new file mode 100644
index 0000000..c676c99
--- /dev/null
+++ b/.markdownlint-cli2.jsonc
@@ -0,0 +1,10 @@
+// .markdownlint-cli2.jsonc - markdownlint-cli2 options: what the linter scopes in and out
+//
+// Rule configuration lives in .markdownlint.jsonc; this file defines scope. The repository's .gitignore files are
+// the source of truth for exclusions, so worktrees/ is never linted, and the glob form scopes to ignore files
+// inside the tree being linted, so a per-issue worktree lints identically to the repository root checkout.
+//
+// see: https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2jsonc
+{
+  "gitignore": "**/.gitignore"
+}
diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
new file mode 100644
index 0000000..53d88f5
--- /dev/null
+++ b/.markdownlint.jsonc
@@ -0,0 +1,23 @@
+// .markdownlint.jsonc - markdownlint rule configuration: which built-in rules this repository turns off or tightens
+//
+// Scope lives in .markdownlint-cli2.jsonc; this file carries only rule state. A rule is off because it collides
+// with a convention the markdown rule states its own way, so every entry names the rule and the convention; a
+// rule is tightened where the default is looser than the convention.
+//
+// see: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+// see: tree/.kit/rules/markdown.md
+{
+  // MD003 heading-style, tightened: the markdown rule says ATX, and "consistent" would accept a setext file.
+  "MD003": { "style": "atx" },
+
+  // MD013 line-length: the 120-column ceiling the markdown rule sets; fenced code and tables do not wrap.
+  "MD013": { "line_length": 120, "code_blocks": false, "tables": false },
+
+  // MD041 first-line-heading: AGENTS.md opens with the `@.kit/1st.md` import, and a delivered file opens with its
+  // notice; the title follows.
+  "MD041": false,
+
+  // MD060 table-column-style: the markdown rule asks for ` | ` around each pipe and nothing about column widths,
+  // which this rule's aligned default would fight column by column.
+  "MD060": false
+}
diff --git a/.mise/locks/npm-markdownlint-cli2/0.24.0/aube-lock.yaml b/.mise/locks/npm-markdownlint-cli2/0.24.0/aube-lock.yaml
new file mode 100644
index 0000000..4a6b0cf
--- /dev/null
+++ b/.mise/locks/npm-markdownlint-cli2/0.24.0/aube-lock.yaml
@@ -0,0 +1,735 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      markdownlint-cli2:
+        specifier: 0.24.0
+        version: 0.24.0
+
+packages:
+
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
+    engines: {node: '>= 8'}
+
+  '@sindresorhus/merge-streams@4.0.0':
+    resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
+    engines: {node: '>=18'}
+
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
+  '@types/katex@0.16.8':
+    resolution: {integrity: sha512-trgaNyfU+Xh2Tc+ABIb44a5AYUpicB3uwirOioeOkNPPbmgRNtcWyDeeFRzjPZENO9Vq8gvVqfhaaXWLlevVwg==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  ansi-regex@6.4.0:
+    resolution: {integrity: sha512-KzTVk2tCWAHtYrvvvaP8bJKJq2pVinhLcGEQdtLIYPbmNGNyYe8QwNaTUYQp2J7/vIsUKt5QCqAfUkYyG9DkOw==}
+    engines: {node: '>=12'}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  argparse@3.0.3:
+    resolution: {integrity: sha512-Sn98ftV3KfsO8xfLPHG6oT8y+b0yvbrLgZjgPDXsharNY15tTAjqIsIju4S32nl6/iEUNNE4v+yL2Zhm8ooP3w==}
+
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
+  commander@8.3.0:
+    resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
+    engines: {node: '>= 12'}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
+  entities@8.1.0:
+    resolution: {integrity: sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==}
+    engines: {node: '>=20.19.0'}
+
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
+    engines: {node: '>=8.6.0'}
+
+  fastq@1.20.3:
+    resolution: {integrity: sha512-XKv5nnLs6nLF71NgiKJLIZFLkPyIEuOselLG7ujZnGrRfQK8HpvY+WqKhAJUAdLomwVHErVS4LfxFlPq0/FTAw==}
+
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
+  get-east-asian-width@1.7.0:
+    resolution: {integrity: sha512-XjH1AECxf0giL2V1aU8vKyRR2ppRUb5c0EvT7zuJTokQ74bNo52zOtghqdWIqrhUD79fo3x0WfKZdOqxF6LG1Q==}
+    engines: {node: '>=18'}
+
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
+    engines: {node: '>= 6'}
+
+  globby@16.2.4:
+    resolution: {integrity: sha512-c8B/VNLmxRcmqqenRA9t+9IyOjf9+V6lTxPaUJLqOCONdQkWZ0ETYgX0qbtJqPsgCNusT9MZ5Jeidw8Eb9tn2g==}
+    engines: {node: '>=20'}
+
+  ignore@7.0.13:
+    resolution: {integrity: sha512-2E8Q6rh+1RRSq/YdaGsNfXsEZy9FVqv6BSSrkmZJP7BnaoPnRfKL+YaofPvP+5rzdk144qSm6i4+hvPgUcbV4Q==}
+    engines: {node: '>= 4'}
+
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-path-inside@4.0.0:
+    resolution: {integrity: sha512-lJJV/5dYS+RcL8uQdBDW9c9uWFLLBNRyFhnAKXw5tVqLlKZ4RMGZKv+YQ/IA3OhD+RpbJa1LLFM1FQPGyIXvOA==}
+    engines: {node: '>=12'}
+
+  js-yaml@5.4.3:
+    resolution: {integrity: sha512-yzzNtgczwgoVHNigCyKTXcQJU4Y8t/ikU4UxXW0BvrLfHTGWZhsNcOT2s/a7vn81/4KqVnNmHjaUEPlvWnNwVw==}
+    hasBin: true
+
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
+  jsonpointer@5.0.1:
+    resolution: {integrity: sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==}
+    engines: {node: '>=0.10.0'}
+
+  katex@0.16.47:
+    resolution: {integrity: sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==}
+    hasBin: true
+
+  linkify-it@6.1.0:
+    resolution: {integrity: sha512-wJ/TwpSDTLepCrQoYWYIExIKg5Zchex2Nn5yk2mFnB+6PtdkHtyLx742md9csRjjOnGkKIS/RrbY7l8D6gT9Vw==}
+
+  markdown-it@15.0.3:
+    resolution: {integrity: sha512-+Az7Ojz3iRGu8KYMvJ6xVhvrxP3eE+vEtJX75Ow88XBpcQNV/0lGX5ZynIIBftREo4DC2jsveAMDaeltmm8QvQ==}
+    hasBin: true
+
+  markdownlint-cli2-formatter-default@0.0.6:
+    resolution: {integrity: sha512-VVDGKsq9sgzu378swJ0fcHfSicUnMxnL8gnLm/Q4J/xsNJ4e5bA6lvAz7PCzIl0/No0lHyaWdqVD2jotxOSFMQ==}
+    peerDependencies:
+      markdownlint-cli2: '>=0.0.4'
+
+  markdownlint-cli2@0.24.0:
+    resolution: {integrity: sha512-c5hU2MDoTlS230MLzdNlkIyxImXq5acxGKz4nYz4aDhH/2BgFtpsA7iK9/OoTHMgZ4FuR0wedTQA31K6Lp9I/Q==}
+    engines: {node: '>=22'}
+    hasBin: true
+
+  markdownlint@0.42.0:
+    resolution: {integrity: sha512-kzsCV/rPWRFn3jUhcB919YF4Qgeh0g9tcogoXFadGSo6Zxj6662YOqWXv0jDn8nv5KCCxDfMKJZv6N4HkNkvTg==}
+    engines: {node: '>=22'}
+
+  mdurl@2.1.0:
+    resolution: {integrity: sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
+    engines: {node: '>= 8'}
+
+  micromark-core-commonmark@2.0.4:
+    resolution: {integrity: sha512-wxEeE8v8XVvOrxn1TZj74qYhAtTQsSqufHVS3uNVyT1MupXxhyaHk8/9xDNPh9BmL77QNDgWTkZ3RsYHB2ry7w==}
+
+  micromark-extension-directive@4.0.0:
+    resolution: {integrity: sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-table@2.1.2:
+    resolution: {integrity: sha512-pRzm4kDTu0MjlmBkxmS9yYhw60nncfcEwu9NNdPFSQEFXS95ZKyIIyTSHu/o3ReBUrLKYEq+7YaXCRn/bPB4MA==}
+
+  micromark-extension-math@3.1.0:
+    resolution: {integrity: sha512-lvEqd+fHjATVs+2v/8kg9i5Q0AP2k85H0WUOwpIVvUML8BapsMvh1XAogmQjOCsLpoKRCVQqEkQBB3NhVBcsOg==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-space@2.1.0:
+    resolution: {integrity: sha512-fS8hnLIjnjvdQIj39Geug8wWsR0HrYZ43KShKxNfwT7t2LOHo/LbWZEzEaSOjwtjdCsjoE6syHhonEzW0zv0+Q==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-edit-map@1.0.0:
+    resolution: {integrity: sha512-Pa2ljlsEL6sVwFaYeyrOLSYbQt73JvGbPOYFq+9AElXiSnfI5Q4465RRZ1sHv7lDjDOnGRDDaqPXqClqWK/q1Q==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.3:
+    resolution: {integrity: sha512-oxB2Ik03hI0gv+VNn9tnh1t1YEe9MDPptViAEgfdf3YQHsn0pzGTgCdlSCJXcwhqm8phaEuM7zeEu3QQzVBrPg==}
+
+  micromark@4.0.3:
+    resolution: {integrity: sha512-oGYfQzHSG5dOMovQcJ3fyTmZlWAWpi0XA0sJwJs+i6OT88o1+Jtw/8z0CmdowSLxGhhFK89rQ/oXph/wN02PNw==}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
+    engines: {node: '>=8.6'}
+
+  punycode.js@2.3.1:
+    resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
+    engines: {node: '>=6'}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
+
+  re2js@2.8.6:
+    resolution: {integrity: sha512-xLgQil4kIUCrAzVk9fRSkxkFNwmygLFjVxXrLc65aE1F0+Zsb8rxumFBy4XKyvgMCTL6kilDq3EZ0piE2dP/Dg==}
+    engines: {node: '>=18.0.0'}
+
+  reusify@1.1.0:
+    resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
+    engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
+
+  slash@5.1.0:
+    resolution: {integrity: sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==}
+    engines: {node: '>=14.16'}
+
+  smol-toml@1.9.1:
+    resolution: {integrity: sha512-j7WyPdf0CJoutMzMoPLF/bVXHtKZIT9Rb4eGeEbWw8X2t5oirjPgpL+OpaENZrILYaXqYwnVH+qgUwVbl+pUJQ==}
+    engines: {node: '>= 18'}
+
+  string-width@8.3.0:
+    resolution: {integrity: sha512-ZbmZM0JCihQN91dWnxoipT2KOEyHqEyfRXUyjuRhW8b/xnqPDoq4gWEVApTVa9db2wN8mmoikgFBbjh71+cGeQ==}
+    engines: {node: '>=20'}
+
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
+  uc.micro@3.0.0:
+    resolution: {integrity: sha512-U3PppEkleoTnIfi8BozMx3yju3qc/L6SwqWo2Sw+54PX+PX0q9I+r1Um5HCmqD7n9VDX5/v3vQH/AjA6deDdtw==}
+
+  unicorn-magic@0.4.1:
+    resolution: {integrity: sha512-lzlXPoVB0Uy/FvTaUgX39RbixYiSKoc3JSoSf01+0c2B6FR3qdYIPN7Qjo/AV7n6sqLCk0509cT3LRj1oSZ1+A==}
+    engines: {node: '>=20'}
+
+snapshots:
+
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.3
+
+  '@sindresorhus/merge-streams@4.0.0': {}
+
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
+  '@types/katex@0.16.8': {}
+
+  '@types/ms@2.1.0': {}
+
+  '@types/unist@2.0.11': {}
+
+  ansi-regex@6.4.0: {}
+
+  argparse@2.0.1: {}
+
+  argparse@3.0.3: {}
+
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
+  commander@8.3.0: {}
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
+  dequal@2.0.3: {}
+
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
+  entities@8.1.0: {}
+
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fastq@1.20.3:
+    dependencies:
+      reusify: 1.1.0
+
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  get-east-asian-width@1.7.0: {}
+
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  globby@16.2.4:
+    dependencies:
+      '@sindresorhus/merge-streams': 4.0.0
+      fast-glob: 3.3.3
+      ignore: 7.0.13
+      is-path-inside: 4.0.0
+      micromatch: 4.0.8
+      slash: 5.1.0
+      unicorn-magic: 0.4.1
+
+  ignore@7.0.13: {}
+
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
+  is-decimal@2.0.1: {}
+
+  is-extglob@2.1.1: {}
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-hexadecimal@2.0.1: {}
+
+  is-number@7.0.0: {}
+
+  is-path-inside@4.0.0: {}
+
+  js-yaml@5.4.3:
+    dependencies:
+      argparse: 2.0.1
+
+  jsonc-parser@3.3.1: {}
+
+  jsonpointer@5.0.1: {}
+
+  katex@0.16.47:
+    dependencies:
+      commander: 8.3.0
+
+  linkify-it@6.1.0:
+    dependencies:
+      uc.micro: 3.0.0
+
+  markdown-it@15.0.3:
+    dependencies:
+      argparse: 3.0.3
+      entities: 8.1.0
+      linkify-it: 6.1.0
+      mdurl: 2.1.0
+      punycode.js: 2.3.1
+      uc.micro: 3.0.0
+
+  markdownlint-cli2-formatter-default@0.0.6(markdownlint-cli2@0.24.0):
+    dependencies:
+      markdownlint-cli2: 0.24.0
+
+  markdownlint-cli2@0.24.0:
+    dependencies:
+      globby: 16.2.4
+      js-yaml: 5.4.3
+      jsonc-parser: 3.3.1
+      jsonpointer: 5.0.1
+      markdown-it: 15.0.3
+      markdownlint: 0.42.0
+      markdownlint-cli2-formatter-default: 0.0.6(markdownlint-cli2@0.24.0)
+      micromatch: 4.0.8
+      smol-toml: 1.9.1
+    transitivePeerDependencies:
+      - supports-color
+
+  markdownlint@0.42.0:
+    dependencies:
+      micromark: 4.0.3
+      micromark-core-commonmark: 2.0.4
+      micromark-extension-directive: 4.0.0
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-table: 2.1.2
+      micromark-extension-math: 3.1.0
+      micromark-util-types: 2.0.3
+      re2js: 2.8.6
+      string-width: 8.3.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdurl@2.1.0: {}
+
+  merge2@1.4.1: {}
+
+  micromark-core-commonmark@2.0.4:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.1.0
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-edit-map: 1.0.0
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-extension-directive@4.0.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.1.0
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+      parse-entities: 4.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.4
+      micromark-factory-space: 2.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-extension-gfm-table@2.1.2:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-extension-math@3.1.0:
+    dependencies:
+      '@types/katex': 0.16.8
+      devlop: 1.1.0
+      katex: 0.16.47
+      micromark-factory-space: 2.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-factory-space@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.3
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-edit-map@1.0.0:
+    dependencies:
+      micromark-util-types: 2.0.3
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.3
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.3: {}
+
+  micromark@4.0.3:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.4
+      micromark-factory-space: 2.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-edit-map: 1.0.0
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.2
+
+  ms@2.1.3: {}
+
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
+  picomatch@2.3.2: {}
+
+  punycode.js@2.3.1: {}
+
+  queue-microtask@1.2.3: {}
+
+  re2js@2.8.6: {}
+
+  reusify@1.1.0: {}
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
+  slash@5.1.0: {}
+
+  smol-toml@1.9.1: {}
+
+  string-width@8.3.0:
+    dependencies:
+      get-east-asian-width: 1.7.0
+      strip-ansi: 7.2.0
+
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.4.0
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  uc.micro@3.0.0: {}
+
+  unicorn-magic@0.4.1: {}
diff --git a/.mise/locks/npm-markdownlint-cli2/0.24.0/package.json b/.mise/locks/npm-markdownlint-cli2/0.24.0/package.json
new file mode 100644
index 0000000..52130b8
--- /dev/null
+++ b/.mise/locks/npm-markdownlint-cli2/0.24.0/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "mise-npm-install",
+  "private": true,
+  "dependencies": {
+    "markdownlint-cli2": "0.24.0"
+  }
+}
diff --git a/justfile b/justfile
index 04a8e40..c0d6a74 100644
--- a/justfile
+++ b/justfile
@@ -20,17 +20,19 @@ _: help
 
 set export := true
 
-# The gate: shellcheck over every bash file, actionlint over every workflow, the bats suite, and bin/kit check over
+# The gate: shellcheck over every bash file, actionlint over every workflow, markdownlint over every markdown file,
+# the bats suite, and bin/kit check over
 # this repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
 # same way; the pre-commit hook is the narrower, faster check over the staged paths.
 #
 #   just ci
-[doc("🚦 The gate: shellcheck, actionlint, bats, kit check")]
+[doc("🚦 The gate: shellcheck, actionlint, markdownlint, bats, kit check")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
   mise exec -- shellcheck --shell=bash --external-sources bin/kit bin/*.sh
   mise exec -- actionlint
+  mise exec -- markdownlint-cli2 '**/*.md'
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
diff --git a/lefthook.yml b/lefthook.yml
index a348d5f..a9a1ced 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -13,6 +13,9 @@ pre-commit:
     shellcheck-dispatcher:
       glob: "bin/kit"
       run: shellcheck --shell=bash --external-sources {staged_files}
+    markdownlint:
+      glob: "*.md"
+      run: markdownlint-cli2 {staged_files}
     # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, so
     # nobody remembers just refresh. The command stages what it rewrote itself: stage_fixed would re-stage only
     # the source paths it was handed, and the copies live elsewhere.
diff --git a/mise.lock b/mise.lock
index 9ad23a6..67b6288 100644
--- a/mise.lock
+++ b/mise.lock
@@ -195,6 +195,12 @@ checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
 
+[[tools."npm:markdownlint-cli2"]]
+version = "0.24.0"
+aube = { path = ".mise/locks/npm-markdownlint-cli2/0.24.0", digest = "sha256:689e86a3f956c317400e5d3bcf0915902a43dbbb8aeec7210a3aa3efb6859684" }
+backend = "npm:markdownlint-cli2"
+specifiers = ["0.24"]
+
 [[tools.shellcheck]]
 version = "0.11.0"
 backend = "aqua:koalaman/shellcheck"
diff --git a/mise.toml b/mise.toml
index 9b061db..ee6ed0c 100644
--- a/mise.toml
+++ b/mise.toml
@@ -18,6 +18,7 @@ _.path = ["bin"]
 [tools]
 gh = "2.103"
 jq = "1.8"
+"npm:markdownlint-cli2" = "0.24"
 just = "1.59"
 shellcheck = "0.11"
 actionlint = "1.7"

From 3d2aeab68958d759740bf3cab0cd74605c051fbd Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:15:20 -0700
Subject: [PATCH 039/108] #1 mise.toml, mise.desk.toml: every tool at its
 newest release

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 mise.lock | 74 ++++++++++++++++++-------------------------------------
 mise.toml |  2 +-
 2 files changed, 25 insertions(+), 51 deletions(-)

diff --git a/mise.lock b/mise.lock
index 67b6288..937bbd2 100644
--- a/mise.lock
+++ b/mise.lock
@@ -32,80 +32,54 @@ url_api = "https://api.github.com/repos/rhysd/actionlint/releases/assets/3849248
 provenance = "github-attestations"
 
 [[tools.bats]]
-version = "1.13.0"
+version = "1.14.0"
 backend = "aqua:bats-core/bats-core"
-specifiers = ["1.13"]
+specifiers = ["1.14"]
 
 [tools.bats."platforms.linux-arm64"]
-url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
-url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
-
-[tools.bats."platforms.linux-arm64-musl"]
-url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
-url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
 [tools.bats."platforms.linux-x64"]
-url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
-url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
-
-[tools.bats."platforms.linux-x64-musl"]
-url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
-url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
 [tools.bats."platforms.macos-arm64"]
-checksum = "blake3:d34af9fd0f9101d5309b2de31f3d1699e56a574d7d4b5e6380580a9e758a9744"
-url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
-url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+checksum = "blake3:9b3dc5d296f3da85ce1062c7f9648c979cf2b982f0151f785eaa84d448dec779"
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
 [tools.bats."platforms.macos-x64"]
-url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.13.0.tar.gz"
-url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.13.0"
+url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
+url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
 [[tools.gh]]
-version = "2.103.0"
+version = "2.103.2"
 backend = "aqua:cli/cli"
 specifiers = ["2.103"]
 
 [tools.gh."platforms.linux-arm64"]
-checksum = "sha256:7f322df34e624d14f5ec0c4acb121fd6dfa14392fdbbd1066aa8e0a05ac3721e"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_arm64.tar.gz"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956401"
-provenance = "github-attestations"
-
-[tools.gh."platforms.linux-arm64-musl"]
-checksum = "sha256:7f322df34e624d14f5ec0c4acb121fd6dfa14392fdbbd1066aa8e0a05ac3721e"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_arm64.tar.gz"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956401"
+checksum = "sha256:4c3e99a50bd8b181a3fe9d69b25dd978bac768148d88f01507c6b4d1ef61a443"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305069"
 provenance = "github-attestations"
 
 [tools.gh."platforms.linux-x64"]
-checksum = "sha256:fdd768eb70f6409f80fcfa9f3a1c0adf0fc98d827ab3ce0bed2ac22762c5d786"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_amd64.tar.gz"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956379"
-provenance = "github-attestations"
-
-[tools.gh."platforms.linux-x64-musl"]
-checksum = "sha256:fdd768eb70f6409f80fcfa9f3a1c0adf0fc98d827ab3ce0bed2ac22762c5d786"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_linux_amd64.tar.gz"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956379"
+checksum = "sha256:62ccf747115ddc61237efffdde66a3c8f70ba249433dc64f70801089b59c59c8"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_linux_amd64.tar.gz"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305062"
 provenance = "github-attestations"
 
 [tools.gh."platforms.macos-arm64"]
-checksum = "sha256:54be566e9f614bea5de8021e95b9ad33dfee3b9d2ea120c9c294c00defaa5014"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_macOS_arm64.zip"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956481"
+checksum = "sha256:5416000f5d17580a187339e0c4068a01ca5c87f7d4fe6ca64933696f967bc418"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_macOS_arm64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305145"
 provenance = "github-attestations"
 
 [tools.gh."platforms.macos-x64"]
-checksum = "sha256:64d1734941f104f996271c820daa50e96902c2618f9b4c1e63c41519517a9c6b"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_macOS_amd64.zip"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956458"
-provenance = "github-attestations"
-
-[tools.gh."platforms.windows-x64"]
-checksum = "sha256:80c846a5b8432672ca6373b34ce9de998c9686aaa1885c845f2e1ee81f713726"
-url = "https://github.com/cli/cli/releases/download/v2.103.0/gh_2.103.0_windows_amd64.zip"
-url_api = "https://api.github.com/repos/cli/cli/releases/assets/662956535"
+checksum = "sha256:2dc7f1fc4761f96732995f6e4f4c6b4d705f2635da4126620c8b30eaa67b9c98"
+url = "https://github.com/cli/cli/releases/download/v2.103.2/gh_2.103.2_macOS_amd64.zip"
+url_api = "https://api.github.com/repos/cli/cli/releases/assets/670305131"
 provenance = "github-attestations"
 
 [[tools.jq]]
diff --git a/mise.toml b/mise.toml
index ee6ed0c..00c0da8 100644
--- a/mise.toml
+++ b/mise.toml
@@ -22,4 +22,4 @@ jq = "1.8"
 just = "1.59"
 shellcheck = "0.11"
 actionlint = "1.7"
-bats = "1.13"
+bats = "1.14"

From a6e5177f56a8943d7defd29d9c4b4ad8553c665d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:16:38 -0700
Subject: [PATCH 040/108] #1 README.md: a range pin sees a new kit a day late
 unless the kit is excluded from the release-age hold

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 7b705bc..b890439 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,10 @@ mise install
 kit install claude
 ```
 
+An exact pin installs the minute a release exists. If you pin a range instead, add
+`minimum_release_age_excludes = ["github:empowerite/kit"]` under `[settings]`, or `mise outdated` and
+`mise upgrade` offer a new kit only a day after it ships.
+
 `kit install` copies `.kit/1st.md`, `.kit/rules/`, and `.kit/lefthook.yml` into the repository, places
 `.github/workflows/kit-ci.yml`, and writes `.kit/manifest`. Each target named adds what that harness insists on
 having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and merges the kit's deny rules into

From c1fd8d76f6e9b1cdd573e04551682053976e8bb1 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:29:29 -0700
Subject: [PATCH 041/108] #1 bin: four defects from review

kit update refuses a path new in the release where the repository already has a different file, and refuses to update any file the previous release delivered without that release as the base, so a merged .json never keeps stale entries. A dangling link in the release is refused where it is found. kit version answers --help. The retire workflow lists every release, not thirty. release:delivered prints path and source together, so the layers are walked once.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/retire-pre-releases.yml |  2 +-
 .gitignore                                |  2 +-
 bin/kit-check.sh                          |  3 +-
 bin/kit-install.sh                        |  4 +-
 bin/kit-update.sh                         | 71 ++++++++++++++---------
 bin/kit-version.sh                        |  7 +++
 bin/release.sh                            | 46 +++++++++------
 tests/kit.bats                            | 14 ++++-
 8 files changed, 97 insertions(+), 52 deletions(-)

diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
index 8229061..891c73a 100644
--- a/.github/workflows/retire-pre-releases.yml
+++ b/.github/workflows/retire-pre-releases.yml
@@ -52,7 +52,7 @@ jobs:
             gh release delete "${tag}" --cleanup-tag --yes
             echo "retired ${tag}: no branch reaches ${commit:0:7} since ${deleted} was deleted"
             retired=$(( retired + 1 ))
-          done < <(gh release list --json tagName,isPrerelease --jq '.[] | select(.isPrerelease) | .tagName')
+          done < <(gh release list --limit 1000 --json tagName,isPrerelease --jq '.[] | select(.isPrerelease) | .tagName')
           echo "✅ Retired ${retired} pre-release(s)."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.gitignore b/.gitignore
index 2fb096f..ba8b0d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,7 @@
 # .gitignore - untracked files and folders
 # ----------------------------------------------------------------------------------------------------------------------
 
-# the per-issue worktrees of the loop; see: .kit/1st.md
+# per-issue worktrees for agents; see: .kit/1st.md
 /worktrees/
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index 0cb5f12..257c13a 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -24,9 +24,8 @@ then
   error ".kit/manifest records kit ${version}, and the pinned release is $(release:version); run: kit update"
   findings=$(( findings + 1 ))
 fi
-while IFS= read -r path
+while IFS=$'\t' read -r path src
 do
-  src=$(release:source-of "${kit_root}" "${path}" "${targets[@]}")
   if [[ ! -f "${path}" ]]
   then
     error "${path} is missing"
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index 69f27bb..eb0ed00 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -23,10 +23,10 @@ then
   exit 1
 fi
 section "kit install $(release:version)${*:+, targets: $*}"
-while IFS= read -r path
+while IFS=$'\t' read -r path src
 do
   step "${path}"
-  release:place "$(release:source-of "${kit_root}" "${path}" "$@")" "${path}"
+  release:place "${src}" "${path}"
 done < <(release:delivered "${kit_root}" "$@")
 release:write-manifest "$@"
 release:finish "$@"
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 3552913..88eb004 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -2,9 +2,9 @@
 # kit-update - after the pin is bumped: replace unchanged files, three-way merge changed ones (kit verb, run through bin/kit)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# An untouched file is one whose digest still matches the manifest, which records the previous release's own
-# content; it is replaced. An edited one is merged with the previous release as the base: KIT_BASE=<dir> names
-# that release's root, otherwise mise knows where it installed it.
+# A file whose digest still matches the manifest, which records the previous release's own content, is replaced.
+# An edited one is three-way merged with the previous release as the base. A path the previous release did not
+# deliver is written only where the repository has nothing, or the same thing, there.
 #
 # see: bin/release.sh
 
@@ -26,11 +26,14 @@ previous=$(release:manifest-version)
 current=$(release:version)
 section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
 
+# The previous release is the base of every merge, and a merge is needed only when the release changed. KIT_BASE
+# names the base's root; otherwise mise knows where it installed it.
 base_root=""
+# shellcheck disable=SC2154  # release_unreleased is declared by bin/release.sh, which use loaded above
 if [[ -n "${KIT_BASE:-}" ]]
 then
   base_root=${KIT_BASE}
-elif [[ "${previous}" != "${current}" && "${previous}" != unreleased ]] && command -v mise >/dev/null 2>&1
+elif [[ "${previous}" != "${current}" && "${previous}" != "${release_unreleased}" ]] && command -v mise >/dev/null 2>&1
 then
   base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
   if [[ -z "${base_root}" ]] && mise install --quiet "github:empowerite/kit@${previous}" 2>/dev/null
@@ -38,43 +41,57 @@ then
     base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
   fi
 fi
+needs_base=false
+[[ "${previous}" != "${current}" ]] && needs_base=true
 
 conflicts=0
-while IFS= read -r path
+while IFS=$'\t' read -r path src
 do
-  src=$(release:source-of "${kit_root}" "${path}" "${targets[@]}")
+  recorded=$(awk -v p="${path}" '$2 == p { print $1 }' .kit/manifest)
+  if [[ -z "${recorded}" ]]
+  then
+    # A path the previous release did not deliver: written where the repository has nothing, or the same thing.
+    if release:merged "${path}" || [[ ! -f "${path}" ]]
+    then
+      step "${path}: new in ${current}, written"
+      release:place "${src}" "${path}"
+    elif cmp --silent "${src}" "${path}"
+    then
+      step "${path}: new in ${current}, and already as the release has it"
+    else
+      error "${path} is new in ${current} and the repository has a file there; move yours aside, then run: kit update"
+      conflicts=$(( conflicts + 1 ))
+    fi
+    continue
+  fi
   base=""
-  [[ -n "${base_root}" ]] && base=$(release:source-of "${base_root}" "${path}" "${targets[@]}" || true)
+  [[ -n "${base_root}" ]] && base=$(release:source-of "${base_root}" "${path}" "${targets[@]}")
+  if [[ "${needs_base}" == true && -z "${base}" ]]
+  then
+    # Without the base, neither a merge nor the removal of the previous release's entries is possible.
+    error "${path} cannot be updated without the base release ${previous}; run: mise install github:empowerite/kit@${previous}"
+    conflicts=$(( conflicts + 1 ))
+    continue
+  fi
   if release:merged "${path}"
   then
     step "${path}: merged by key"
     release:place "${src}" "${path}" "${base}"
-    continue
-  fi
-  if [[ ! -f "${path}" ]]
+  elif [[ ! -f "${path}" ]]
   then
     step "${path}: missing, written"
     release:place "${src}" "${path}"
-    continue
-  fi
-  recorded=$(awk -v p="${path}" '$2==p{print $1}' .kit/manifest)
-  if [[ -z "${recorded}" || "${recorded}" == "$(release:digest < "${path}")" ]]
+  elif [[ "${recorded}" == "$(release:digest < "${path}")" ]]
   then
     step "${path}: unchanged since ${previous}, replaced"
     release:place "${src}" "${path}"
-    continue
-  fi
-  if [[ -z "${base}" ]]
-  then
-    error "${path} was edited and the base release ${previous} is not installed; run: mise install github:empowerite/kit@${previous}"
-    conflicts=$(( conflicts + 1 ))
-    continue
-  fi
-  step "${path}: edited since ${previous}, three-way merged"
-  if ! git merge-file --marker-size 7 "${path}" "${base}" "${src}"
-  then
-    warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
-    conflicts=$(( conflicts + 1 ))
+  else
+    step "${path}: edited since ${previous}, three-way merged"
+    if ! git merge-file --marker-size 7 "${path}" "${base}" "${src}"
+    then
+      warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
+      conflicts=$(( conflicts + 1 ))
+    fi
   fi
 done < <(release:delivered "${kit_root}" "${targets[@]}")
 
diff --git a/bin/kit-version.sh b/bin/kit-version.sh
index 0895204..f4e07e3 100755
--- a/bin/kit-version.sh
+++ b/bin/kit-version.sh
@@ -6,6 +6,13 @@ set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
 use release
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit version" >&2
+  exit 0
+fi
+
 release:version
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/release.sh b/bin/release.sh
index 2ddbc54..a4d7663 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -11,10 +11,13 @@
 #
 # Every function reads the release from kit_root, exported by bin/kit.
 
-# release:version prints this release's version: the file the release workflow stamps from the tag, and
-# "unreleased" in a checkout, which is what this repository's own installed copy records.
+# A release carries a version file the release workflow stamps from the tag; a checkout carries none and is
+# "unreleased", the one version kit update never asks mise for.
+declare -gr release_unreleased=unreleased
+
+# release:version prints this release's version.
 release:version() {
-  cat "${kit_root}/version" 2>/dev/null || printf 'unreleased\n'
+  cat "${kit_root}/version" 2>/dev/null || printf '%s\n' "${release_unreleased}"
 }
 
 # release:layers <root> <target>… prints the directories mirrored at the repository root, tree first.
@@ -28,29 +31,36 @@ release:layers() {
   done
 }
 
-# release:delivered <root> <target>… prints every repository path the release at <root> delivers for those targets.
+# release:delivered <root> <target>… prints "<path>\t<source>" for every repository path the release at <root>
+# delivers for those targets, sorted by path, the last layer winning. A symlink is a source only when it points
+# at a file; a dangling one is refused here, where it is found.
 release:delivered() {
-  local layer
+  local layer path src
   while IFS= read -r layer
   do
-    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@')
-  done < <(release:layers "$@") | sort --unique
+    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@' | awk -v l="${layer}" '{ print $0 "\t" l "/" $0 }')
+  done < <(release:layers "$@") | awk -F '\t' '{ src[$1] = $2 } END { for (p in src) print p "\t" src[p] }' | sort \
+    | while IFS=$'\t' read -r path src
+  do
+    if [[ -L "${src}" && ! -e "${src}" ]]
+    then
+      error "${src} is a link to nothing; the release is broken"
+      return 1
+    fi
+    printf '%s\t%s\n' "${path}" "${src}"
+  done
 }
 
-# release:source-of <root> <path> <target>… prints the release file behind a repository path, the last layer winning.
+# release:source-of <root> <path> <target>… prints the release file behind one repository path, or nothing.
 release:source-of() {
-  local root=$1 path=$2 layer found=""
+  local root=$1 path=$2
   shift 2
-  while IFS= read -r layer
-  do
-    [[ -e "${layer}/${path}" ]] && found="${layer}/${path}"
-  done < <(release:layers "${root}" "$@")
-  [[ -n "${found}" ]] && printf '%s\n' "${found}"
+  release:delivered "${root}" "$@" | awk -F '\t' -v p="${path}" '$1 == p { print $2 }'
 }
 
 # release:target-only <target> prints the paths the target delivers that tree/ does not.
 release:target-only() {
-  comm -13 <(release:delivered "${kit_root}") <(release:delivered "${kit_root}" "$1")
+  comm -13 <(release:delivered "${kit_root}" | cut -f 1) <(release:delivered "${kit_root}" "$1" | cut -f 1)
 }
 
 # release:known-targets prints the targets this release carries.
@@ -134,14 +144,14 @@ release:place() {
 
 # release:write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
 release:write-manifest() {
-  local path
+  local path src
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
     printf 'version %s\n' "$(release:version)"
     printf 'targets%s\n' "${*:+ $*}"
-    while IFS= read -r path
+    while IFS=$'\t' read -r path src
     do
-      printf '%s  %s\n' "$(release:digest < "$(release:source-of "${kit_root}" "${path}" "$@")")" "${path}"
+      printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
     done < <(release:delivered "${kit_root}" "$@")
   } > .kit/manifest
 }
diff --git a/tests/kit.bats b/tests/kit.bats
index 55ba6cb..75b5e02 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -146,6 +146,18 @@ later-release() {
   rm -rf "${repo}.later"
 }
 
+@test "update refuses a path new in the release where the repository already has a different file" {
+  "${kit_checkout}/bin/kit" install claude
+  later-release "${repo}.later"
+  printf 'new rule\n' > "${repo}.later/tree/.kit/rules/toml.md"
+  printf 'mine\n' > .kit/rules/toml.md
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/rules/toml.md is new in 9.9.9"* ]]
+  [ "$(cat .kit/rules/toml.md)" = "mine" ]
+  rm -rf "${repo}.later"
+}
+
 @test "update of an untouched install leaves check green" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
@@ -176,7 +188,7 @@ later-release() {
   mkdir shims && printf '#!/usr/bin/env bash\nexit 1\n' > shims/mise && chmod +x shims/mise
   run env PATH="${PWD}/shims:${PATH}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
-  [[ "$output" == *"base release unreleased is not installed"* ]]
+  [[ "$output" == *"cannot be updated without the base release unreleased"* ]]
   rm -rf "${repo}.later"
 }
 

From 71d3cca5a94d4ec37c9b82fcb77aca86175acea6 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:31:05 -0700
Subject: [PATCH 042/108] #1 bin/git.sh: no state shared through dynamic scope

git:worktrees prints one record per linked worktree and the callers loop over it. git:status-block and git:tidy-worktree take what they need as arguments; tidy-worktree answers with its status, and the caller counts and records what was freed. git:default-branch and git:main-root take a path, so git:rebase no longer re-derives the default branch. The tidy test calls the decision directly.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/git.sh      | 163 ++++++++++++++++++++++++------------------------
 tests/tidy.bats |  11 +---
 2 files changed, 85 insertions(+), 89 deletions(-)

diff --git a/bin/git.sh b/bin/git.sh
index 4738cd0..6e7cec1 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -1,50 +1,39 @@
 # shellcheck shell=bash
-# git.sh - the default branch and the main root, the picture of the worktrees, the sweep, and the rebase (sourced module)
+# git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# git:status [--no-fetch] renders the main checkout on one line and one block per worktree under worktrees/
-# with its branch, pull request, and dirty or clean state, then the local branches whose upstream is gone. It
-# changes nothing.
+# git:status [--no-fetch] renders the main checkout on one line and one block per worktree under worktrees/, with
+# its branch, pull request, and dirty or clean state, then the local branches whose upstream is gone. It changes
+# nothing.
 #
 # git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
 # detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
-# every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a live
-# worktree, a dirty worktree, a detached worktree whose commit nothing else reaches, or the worktree it runs in. --dry-run
-# prints what a sweep would do and changes nothing.
+# every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a
+# live worktree, a dirty worktree, a detached worktree whose commit nothing else reaches, or the worktree it
+# runs in. --dry-run says what a sweep would do and changes nothing.
 #
 # git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto
-# origin/<default> and pushes it with --force-with-lease. It refuses the default branch, the human's desk; on a
-# conflict it aborts and leaves the worktree as it was.
+# origin/<default> and pushes it with --force-with-lease. It refuses the default branch, the human's desk, and
+# on a conflict aborts and leaves the worktree as it was.
 
-# git:default-branch prints the default branch: origin/HEAD, with main as the fallback.
+# git:default-branch [<path>] prints the default branch of the repository at <path>: origin/HEAD, else main.
 git:default-branch() {
   local branch
-  branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+  branch=$(git -C "${1:-.}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
   [[ -n "${branch}" ]] || branch=main
   printf '%s\n' "${branch}"
 }
 
-# git:main-root prints the root of the main checkout, the first entry of the worktree list. worktrees/ lives
-# under it whether the caller stands in the main checkout or in a linked worktree.
+# git:main-root [<path>] prints the root of the main checkout, the first entry of the worktree list. worktrees/
+# lives under it whether the caller stands in the main checkout or in a linked worktree.
 git:main-root() {
-  git worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
+  git -C "${1:-.}" worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
 }
 
-# git:pr-summary <branch> prints "<number>\t<Draft|Ready>" for the open pull request on <branch>, or nothing.
-git:pr-summary() {
-  gh pr list --head "$1" --state open --json number,isDraft \
-    --jq '.[0] | select(.number) | "\(.number)\t\(if .isDraft then "Draft" else "Ready" end)"' 2>/dev/null || true
-}
-
-# git:gone-branches prints every local branch whose upstream no longer exists.
-git:gone-branches() {
-  git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/ | awk '$2=="[gone]"{print $1}'
-}
-
-# git:each-worktree <callback> calls <callback> <path> <branch> <detached> for every linked worktree under
-# worktrees/. <branch> is empty and <detached> is true for a detached checkout.
-git:each-worktree() {
-  local callback=$1 worktree_root path="" branch="" detached=false line
+# git:worktrees prints "<path>\t<branch>\t<detached>" for every linked worktree under worktrees/; <branch> is
+# empty and <detached> is true for a detached checkout.
+git:worktrees() {
+  local worktree_root path="" branch="" detached=false line
   worktree_root="$(git:main-root)/worktrees"
   while IFS= read -r line
   do
@@ -61,23 +50,33 @@ git:each-worktree() {
         detached=true
         ;;
       ("")
-        [[ -n "${path}" ]] || continue
-        case "${path}" in
-          ("${worktree_root}"/*)
-            "${callback}" "${path}" "${branch}" "${detached}"
-        esac
+        # git ends every record with a blank line; the printf below adds one so the last record ends too.
+        [[ "${path}" == "${worktree_root}"/* ]] && printf '%s\t%s\t%s\n' "${path}" "${branch}" "${detached}"
         path=""
     esac
   done < <(git worktree list --porcelain; printf '\n')
 }
 
-# git:status-block <path> <branch> <detached> renders one worktree. git:status sets found, main_root, and
-# default_branch before calling it through git:each-worktree.
+# git:pr-summary <branch> prints "<number>\t<Draft|Ready>" for the open pull request on <branch>, or nothing.
+git:pr-summary() {
+  gh pr list --head "$1" --state open --json number,isDraft \
+    --jq '.[0] | select(.number) | "\(.number)\t\(if .isDraft then "Draft" else "Ready" end)"' 2>/dev/null || true
+}
+
+# git:gone-branches prints every local branch whose upstream no longer exists.
+git:gone-branches() {
+  git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/ | awk '$2 == "[gone]" { print $1 }'
+}
+
+# git:clean <path> is true when the checkout at <path> has no uncommitted change.
+git:clean() {
+  [[ -z "$(git -C "$1" status --porcelain 2>/dev/null)" ]]
+}
+
+# git:status-block <path> <branch> <main-root> <default-branch> renders one worktree.
 git:status-block() {
-  local path=$1 branch=$2 rel pr ahead_behind porcelain
-  found=true
-  rel=${path#"${main_root}"/}
-  step "${rel}"
+  local path=$1 branch=$2 main_root=$3 default_branch=$4 pr ahead_behind
+  step "${path#"${main_root}"/}"
   info "  branch  ${branch:-(detached)}"
   if [[ -n "${branch}" ]]
   then
@@ -85,31 +84,35 @@ git:status-block() {
     ahead_behind=$(git rev-list --left-right --count "${branch}...${default_branch}" 2>/dev/null || printf '0\t0')
     if [[ -n "${pr}" ]]
     then
-      info "  pr      #${pr%%$'\t'*} ${pr##*$'\t'} · ↑${ahead_behind%%$'\t'*} ↓${ahead_behind##*$'\t'} vs ${default_branch}"
+      pr="#${pr%%$'\t'*} ${pr##*$'\t'}"
     else
-      info "  pr      (none open) · ↑${ahead_behind%%$'\t'*} ↓${ahead_behind##*$'\t'} vs ${default_branch}"
+      pr="(none open)"
     fi
+    info "  pr      ${pr} · ↑${ahead_behind%%$'\t'*} ↓${ahead_behind##*$'\t'} vs ${default_branch}"
   else
     info "  pr      (no branch)"
   fi
-  porcelain=$(git -C "${path}" status --porcelain 2>/dev/null || true)
-  if [[ -z "${porcelain}" ]]
+  if git:clean "${path}"
   then
     info "  status  clean"
   else
-    info "  status  $(grep --count . <<<"${porcelain}") file(s) modified"
+    info "  status  $(git -C "${path}" status --porcelain | grep --count .) file(s) modified"
   fi
 }
 
-# git:tidy-worktree <path> <branch> <detached> decides one worktree. git:tidy sets found, self_root, dry_run,
-# removed_worktrees, and freed before calling it through git:each-worktree.
+# git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides one worktree and
+# says why. It returns 0 when the worktree was removed, or would be under a dry run, and 1 when it is kept.
 git:tidy-worktree() {
-  local path=$1 branch=$2 detached=$3 state="" number
-  found=true
+  local path=$1 branch=$2 detached=$3 default_branch=$4 self_root=$5 dry_run=$6 state="" number
   if [[ "${path}" == "${self_root}" ]]
   then
     step "keeping ${path} (this command runs in it)"
-    return 0
+    return 1
+  fi
+  if ! git:clean "${path}"
+  then
+    step "keeping ${path} (${branch:-detached}, it has uncommitted changes)"
+    return 1
   fi
   if [[ -n "${branch}" ]]
   then
@@ -119,25 +122,20 @@ git:tidy-worktree() {
       number=${BASH_REMATCH[1]}
       [[ "$(gh issue view "${number}" --json state --jq .state 2>/dev/null)" == CLOSED ]] && state=CLOSED
     fi
-  elif [[ "${detached}" == true && -z "$(git -C "${path}" status --porcelain 2>/dev/null)" ]]
+  elif [[ "${detached}" == true ]]
   then
-    # A clean detached checkout is residue only when its commit is already on the default branch; otherwise its
-    # HEAD may be the only thing that reaches that commit, and removing the worktree would lose it.
+    # A detached checkout is residue only when its commit is already on the default branch; otherwise its HEAD
+    # may be the only thing that reaches that commit.
     if git -C "${path}" merge-base --is-ancestor HEAD "origin/${default_branch}" 2>/dev/null
     then
       state=DETACHED
     else
       step "keeping ${path} (detached at a commit origin/${default_branch} does not reach)"
-      return 0
+      return 1
     fi
   fi
   case "${state}" in
     (MERGED | CLOSED | DETACHED)
-      if [[ -n "$(git -C "${path}" status --porcelain 2>/dev/null)" ]]
-      then
-        step "keeping ${path} (${state}, but it has uncommitted changes)"
-        return 0
-      fi
       if [[ "${dry_run}" == true ]]
       then
         step "would remove ${path} (${branch:-detached}, ${state})"
@@ -145,17 +143,16 @@ git:tidy-worktree() {
         step "removing ${path} (${branch:-detached}, ${state})"
         git worktree remove "${path}"
       fi
-      [[ -n "${branch}" ]] && freed[${branch}]=1
-      (( ++removed_worktrees ))
+      return 0
       ;;
     (*)
       step "keeping ${path} (${branch:-detached}, pull request ${state:-open or unknown})"
+      return 1
   esac
-  return 0
 }
 
 git:status() {
-  local no_fetch=false arg
+  local no_fetch=false arg main_root default_branch main_branch main_dirty counts found=false path branch detached gone
   for arg in "$@"
   do
     case "${arg}" in
@@ -172,22 +169,23 @@ git:status() {
     git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
   fi
 
-  local main_branch main_dirty counts
   main_root=$(git:main-root)
   default_branch=$(git:default-branch)
   main_branch=$(git -C "${main_root}" rev-parse --abbrev-ref HEAD 2>/dev/null || printf '?')
-  main_dirty=clean
-  [[ -z "$(git -C "${main_root}" status --porcelain 2>/dev/null)" ]] || main_dirty=dirty
+  main_dirty=dirty
+  git:clean "${main_root}" && main_dirty=clean
   counts=$(git -C "${main_root}" rev-list --left-right --count "HEAD...origin/${default_branch}" 2>/dev/null || printf '0\t0')
   section "${main_root##*/}  (${main_branch}, ${main_dirty}, ↑${counts%%$'\t'*} ↓${counts##*$'\t'} vs origin/${default_branch})"
 
   section "worktrees/"
-  found=false
-  git:each-worktree git:status-block
+  while IFS=$'\t' read -r path branch detached
+  do
+    found=true
+    git:status-block "${path}" "${branch}" "${main_root}" "${default_branch}"
+  done < <(git:worktrees)
   [[ "${found}" == true ]] || ok "none"
 
   section "branches whose upstream is gone (tidy removes these)"
-  local gone
   gone=$(git:gone-branches)
   if [[ -n "${gone}" ]]
   then
@@ -201,7 +199,9 @@ git:status() {
 }
 
 git:tidy() {
-  local dry_run=false flag
+  local dry_run=false flag repo default_branch self_root found=false path branch detached
+  local removed_worktrees=0 removed_branches=0 checked_out
+  local -A freed=()
   for flag in "$@"
   do
     case "${flag}" in
@@ -214,8 +214,6 @@ git:tidy() {
     esac
   done
   guard:require gh || return 1
-
-  local repo
   repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || true)
   if [[ -z "${repo}" ]]
   then
@@ -240,10 +238,15 @@ git:tidy() {
   fi
 
   section "worktrees whose pull request is merged or closed"
-  removed_worktrees=0
-  found=false
-  declare -A freed=()
-  git:each-worktree git:tidy-worktree
+  while IFS=$'\t' read -r path branch detached
+  do
+    found=true
+    if git:tidy-worktree "${path}" "${branch}" "${detached}" "${default_branch}" "${self_root}" "${dry_run}"
+    then
+      (( ++removed_worktrees ))
+      [[ -n "${branch}" ]] && freed[${branch}]=1
+    fi
+  done < <(git:worktrees)
   [[ "${found}" == true ]] || ok "none"
 
   section "worktree bookkeeping"
@@ -256,7 +259,6 @@ git:tidy() {
   ok "pruned"
 
   section "local branches whose upstream is gone"
-  local removed_branches=0 checked_out branch
   checked_out=$(git worktree list --porcelain | sed -n 's@^branch refs/heads/@@p')
   while IFS= read -r branch
   do
@@ -294,11 +296,10 @@ git:rebase() {
     error "${worktree} has no branch checked out, so there is nothing to rebase"
     return 1
   fi
-  default_branch=$(git -C "${worktree}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
-  [[ -n "${default_branch}" ]] || default_branch=main
+  default_branch=$(git:default-branch "${worktree}")
   if [[ "${branch}" == "${default_branch}" ]]
   then
-    error "refusing to rebase ${branch}: it is the default branch, the human's desk. It advances by fast-forward: git pull --ff-only"
+    error "refusing to rebase ${branch}: it is the default branch, the human's desk; it advances by: git pull --ff-only"
     return 1
   fi
   section "kit rebase ${branch} onto origin/${default_branch}"
@@ -306,7 +307,7 @@ git:rebase() {
   if ! git -C "${worktree}" rebase --quiet "origin/${default_branch}"
   then
     git -C "${worktree}" rebase --abort
-    error "${branch} conflicts with origin/${default_branch}; the rebase was aborted and the worktree is as it was. Resolve by hand."
+    error "${branch} conflicts with origin/${default_branch}; the rebase was aborted and the worktree is as it was"
     return 1
   fi
   git -C "${worktree}" push --quiet --force-with-lease
diff --git a/tests/tidy.bats b/tests/tidy.bats
index 285e523..5815f8d 100644
--- a/tests/tidy.bats
+++ b/tests/tidy.bats
@@ -21,14 +21,9 @@ teardown() {
   rm -rf "${work}"
 }
 
-# decide <path> runs tidy's per-worktree decision on <path>, a detached checkout, with tidy's globals in place.
+# decide <path> runs tidy's decision on <path>, a detached checkout, with main as the default branch and no dry run.
 decide() {
-  bash -c '
-    source "${kit_root}/bin/1st.sh" && use git
-    found=false; dry_run=false; removed_worktrees=0; declare -A freed=()
-    self_root=$(git rev-parse --show-toplevel); default_branch=main
-    git:tidy-worktree "$1" "" true
-  ' _ "$1"
+  bash -c 'source "${kit_root}/bin/1st.sh" && use git && git:tidy-worktree "$1" "" true main "$(git rev-parse --show-toplevel)" false' _ "$1"
 }
 
 @test "a clean detached worktree at a commit on main is removed" {
@@ -43,7 +38,7 @@ decide() {
   git worktree add --quiet --detach worktrees/only HEAD
   printf 'two\n' > worktrees/only/b && git -C worktrees/only add b && git -C worktrees/only commit --quiet --message two
   run decide "${PWD}/worktrees/only"
-  [ "$status" -eq 0 ]
+  [ "$status" -eq 1 ]
   [[ "$output" == *"keeping"* ]]
   [ -e worktrees/only ]
 }

From af51d2b82436f8eeae244a4eb7055f1fea1fc7c8 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:32:30 -0700
Subject: [PATCH 043/108] #1 bin/gh.sh: the on-ramp as named steps

gh:issue orchestrates gh:me, gh:issue-create, gh:assign, gh:issue-branch, gh:worktree, gh:start-commit, gh:sweep-push, gh:sweep-apply, gh:pull-request, and gh:link-secondaries, each printing its one result. The user is read once. kit target uses release:among and release:without instead of two inline idioms.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/gh.sh         | 309 +++++++++++++++++++++++++---------------------
 bin/kit-target.sh |  11 +-
 bin/release.sh    |  21 ++++
 3 files changed, 189 insertions(+), 152 deletions(-)

diff --git a/bin/gh.sh b/bin/gh.sh
index 368870b..e097d06 100644
--- a/bin/gh.sh
+++ b/bin/gh.sh
@@ -2,141 +2,91 @@
 # gh.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft pull request (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# gh:issue [<number>…] is the one command the loop needs and no vendor provides. The first number is the
-# primary issue, linked to the branch under Development by `gh issue develop`, which closes it on merge. Any
-# further number is a secondary, closed by a `Closes #N` line in the pull request body. Every listed issue is
-# assigned to the caller.
+# gh:issue [<number>…] is the one command the loop needs and no vendor provides. The first number is the primary
+# issue, linked to the branch under Development by `gh issue develop`, which closes it on merge; any further
+# number is a secondary, closed by a `Closes #N` line in the pull request body. Every listed issue is assigned to
+# the caller. It never switches the checkout it runs from: the branch is checked out in worktrees/<N>-<slug>
+# under the main checkout, and an existing branch, worktree, or pull request is reused, so a re-run reconciles.
 #
-# It never switches the checkout it is run from. The branch is checked out in worktrees/<N>-<slug> under the
-# main checkout's root, and an existing branch, worktree, or pull request is reused, so a re-run reconciles
-# rather than duplicates.
+# With no argument and a terminal on stdin it asks for a title and creates the issue; without a terminal the
+# usage error stands, so an agent never hangs on a prompt. Uncommitted work on the default branch is swept into
+# the new worktree, uncommitted, and the desk is left clean and fast-forwarded; inside any other checkout, dirty
+# files are that issue's own and stay. A sweep that cannot apply leaves the stash in place and stops.
 #
-# With no argument and a terminal on stdin it asks for a title, creates the issue, and continues. Without a
-# terminal the usage error stands, so an agent never hangs on a prompt.
-#
-# If the invoking checkout is on the default branch and carries uncommitted changes, they are swept into the
-# new worktree as uncommitted changes and the invoking checkout is left clean, then fast-forwarded to origin.
-# The sweep runs only from the default-branch checkout: inside another worktree, dirty files are that issue's
-# own work and are never moved. A sweep that cannot apply leaves the stash in place and stops, so nothing is
-# lost.
-
-gh:issue() {
-  use git
-  if (( $# == 0 ))
-  then
-    if [[ ! -t 0 ]]
-    then
-      error "usage: kit issue <issue-number> [<issue-number>…]"
-      return 2
-    fi
-    guard:require gh || return 1
-    local new_title new_number
-    read -r -p "Issue title: " new_title
-    if [[ -z "${new_title}" ]]
-    then
-      error "an issue title is required"
-      return 2
-    fi
-    new_number=$(gh issue create --title "${new_title}" --body "" 2>/dev/null | sed -n 's@.*/issues/@@p')
-    if [[ ! "${new_number}" =~ ^[0-9]+$ ]]
-    then
-      error "run: gh auth status (the issue could not be created)"
-      return 1
-    fi
-    ok "Created #${new_number}: ${new_title}"
-    set -- "${new_number}"
-  fi
-
-  local n
-  for n in "$@"
-  do
-    if [[ ! "${n}" =~ ^[0-9]+$ ]]
-    then
-      error "not an issue number: '${n}'"
-      return 2
-    fi
-  done
-  local primary=$1
-
-  guard:require gh || return 1
-  git fetch --quiet --prune origin
+# Each step below prints its one result on stdout and talks on stderr, so gh:issue reads them in order.
 
-  local default_branch main_root invoking_root invoking_branch
-  default_branch=$(git:default-branch)
-  main_root=$(git:main-root)
-  invoking_root=$(git rev-parse --show-toplevel)
-  invoking_branch=$(git -C "${invoking_root}" rev-parse --abbrev-ref HEAD)
-
-  local do_sweep=false stash_ref=""
-  if [[ "${invoking_branch}" == "${default_branch}" && -n "$(git -C "${invoking_root}" status --porcelain)" ]]
+# gh:me prints the authenticated login. A revoked token passes `gh auth status`, so this is the real probe.
+gh:me() {
+  local me
+  me=$(gh api user --jq '.login' 2>/dev/null || true)
+  if [[ -z "${me}" ]]
   then
-    do_sweep=true
+    error "run: gh auth login (the GitHub CLI is not authenticated)"
+    return 1
   fi
+  printf '%s\n' "${me}"
+}
 
-  local title
-  title=$(gh issue view "${primary}" --json title --jq '.title')
+# gh:issue-create asks for a title at the terminal and prints the number of the issue it creates.
+gh:issue-create() {
+  local title number
+  read -r -p "Issue title: " title
   if [[ -z "${title}" ]]
   then
-    error "run: gh auth status (the title of #${primary} could not be read)"
-    return 1
+    error "an issue title is required"
+    return 2
   fi
-
-  local me assignees
-  me=$(gh api user --jq '.login')
-  if [[ -z "${me}" ]]
+  number=$(gh issue create --title "${title}" --body "" 2>/dev/null | sed -n 's@.*/issues/@@p')
+  if [[ ! "${number}" =~ ^[0-9]+$ ]]
   then
-    error "run: gh auth status (the current user could not be read)"
+    error "run: gh auth status (the issue could not be created)"
     return 1
   fi
+  ok "Created #${number}: ${title}"
+  printf '%s\n' "${number}"
+}
+
+# gh:assign <me> <number>… adds <me> to each issue's assignees, warning where someone else is there already.
+gh:assign() {
+  local me=$1 n assignees
+  shift
   for n in "$@"
   do
     assignees=$(gh issue view "${n}" --json assignees --jq '[.assignees[].login] | join(" ")')
     [[ " ${assignees} " == *" ${me} "* ]] && continue
-    if [[ -n "${assignees}" ]]
-    then
-      warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
-    fi
-    if ! gh issue edit "${n}" --add-assignee "${me}" >/dev/null 2>&1
-    then
-      warn "#${n} could not be assigned to ${me}; assign it by hand."
-    fi
+    [[ -z "${assignees}" ]] || warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
+    gh issue edit "${n}" --add-assignee "${me}" >/dev/null 2>&1 || warn "#${n} could not be assigned to ${me}; assign it by hand."
   done
+}
 
-  section "Starting #${primary}: ${title}"
-
-  # The branch gh made for the issue, found by an open pull request's head, then by the remote ref. Any hit is
-  # reused, so a second run never forks a <N>-<slug>-1 duplicate.
-  local branch
+# gh:issue-branch <number> <default-branch> prints the branch linked to the issue, making and linking one if none
+# exists. An existing one is found by an open pull request's head, then by the remote ref, so a second run never
+# forks a <N>-<slug>-1 duplicate.
+gh:issue-branch() {
+  local number=$1 default_branch=$2 branch
   branch=$(gh pr list --state open --json headRefName \
-    --jq "[.[] | select(.headRefName | test(\"^${primary}-\"))] | .[0].headRefName // empty" 2>/dev/null || true)
-  [[ -n "${branch}" ]] || branch=$(git ls-remote --heads origin "${primary}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+    --jq "[.[] | select(.headRefName | test(\"^${number}-\"))] | .[0].headRefName // empty" 2>/dev/null || true)
+  [[ -n "${branch}" ]] || branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
   if [[ -z "${branch}" ]]
   then
-    step "Linking a branch to #${primary} (gh issue develop)"
-    gh issue develop "${primary}" --base "${default_branch}" >/dev/null
+    step "Linking a branch to #${number} (gh issue develop)"
+    gh issue develop "${number}" --base "${default_branch}" >/dev/null
     git fetch --quiet origin
-    branch=$(git ls-remote --heads origin "${primary}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+    branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
     if [[ -z "${branch}" ]]
     then
-      error "the branch gh made for #${primary} could not be found; run: gh issue develop ${primary} --list"
-      return 1
-    fi
-  fi
-
-  if [[ "${do_sweep}" == true ]]
-  then
-    step "Sweeping the uncommitted work on ${default_branch} into the worktree"
-    if ! git -C "${invoking_root}" stash push --include-untracked --message "kit issue #${primary} → ${branch}" >/dev/null
-    then
-      error "the uncommitted work on ${default_branch} could not be stashed; resolve it by hand and re-run."
+      error "the branch gh made for #${number} could not be found; run: gh issue develop ${number} --list"
       return 1
     fi
-    stash_ref=$(git -C "${invoking_root}" rev-parse 'stash@{0}')
   fi
+  printf '%s\n' "${branch}"
+}
 
-  local wt
+# gh:worktree <main-root> <branch> prints the worktree the branch is checked out in, making it if there is none.
+gh:worktree() {
+  local main_root=$1 branch=$2 wt
   wt=$(git worktree list --porcelain 2>/dev/null \
-    | awk -v b="branch refs/heads/${branch}" '/^worktree /{w=substr($0,10)} $0==b{print w; exit}')
+    | awk -v b="branch refs/heads/${branch}" '/^worktree / { w = substr($0, 10) } $0 == b { print w; exit }')
   if [[ -n "${wt}" ]]
   then
     step "Reusing worktree ${wt}"
@@ -156,40 +106,53 @@ gh:issue() {
       git worktree add --quiet "${wt}" -b "${branch}" "origin/${branch}"
     fi
   fi
+  printf '%s\n' "${wt}"
+}
 
-  if ! git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null
+# gh:start-commit <worktree> <default-branch> <number> <title> gives the branch its first commit when it has
+# none: GitHub cannot open a pull request with nothing to compare. --only keeps the commit empty, so work already
+# staged in a reused worktree stays in the index.
+gh:start-commit() {
+  local wt=$1 default_branch=$2 number=$3 title=$4
+  if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
   then
-    warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a status or a commit"
+    step "Adding the start commit"
+    git -C "${wt}" commit --quiet --allow-empty --only --message "start: #${number} ${title}"
   fi
+}
 
-  # GitHub cannot open a pull request on a branch with nothing to compare, so the first commit is an empty one.
-  # --only keeps it empty: work already staged in a reused worktree stays in the index, not in this commit.
-  if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
+# gh:sweep-push <root> <message> stashes everything uncommitted at <root>, untracked files included, and prints the
+# stash's commit, which stays valid however the stash list shifts.
+gh:sweep-push() {
+  local root=$1 message=$2
+  if ! git -C "${root}" stash push --include-untracked --message "${message}" >/dev/null
   then
-    step "Adding the start commit"
-    git -C "${wt}" commit --quiet --allow-empty --only --message "start: #${primary} ${title}"
+    error "the uncommitted work at ${root} could not be stashed; resolve it by hand and re-run."
+    return 1
   fi
-  git -C "${wt}" push --quiet --set-upstream origin "${branch}"
+  git -C "${root}" rev-parse 'stash@{0}'
+}
 
-  if [[ -n "${stash_ref}" ]]
+# gh:sweep-apply <root> <worktree> <stash> <default-branch> lands the stash in the worktree, uncommitted, drops it,
+# and fast-forwards the now-clean desk. On a conflict the stash is kept and the caller stops.
+gh:sweep-apply() {
+  local root=$1 wt=$2 stash=$3 default_branch=$4 slot
+  if ! git -C "${wt}" stash apply "${stash}" >/dev/null 2>&1
   then
-    if git -C "${wt}" stash apply "${stash_ref}" >/dev/null 2>&1
-    then
-      local slot
-      slot=$(git -C "${invoking_root}" stash list --format='%gd %H' | awk -v h="${stash_ref}" '$2==h{print $1; exit}')
-      [[ -n "${slot}" ]] && git -C "${invoking_root}" stash drop "${slot}" >/dev/null
-      ok "Swept the work into ${wt}, uncommitted; commit it there with a real message."
-      if ! git -C "${invoking_root}" merge --ff-only "origin/${default_branch}" >/dev/null 2>&1
-      then
-        warn "${default_branch} could not fast-forward to origin; it is left as it was."
-      fi
-    else
-      error "the swept work conflicts in ${wt}. It is kept in the stash: git stash apply ${stash_ref}"
-      return 1
-    fi
+    error "the swept work conflicts in ${wt}. It is kept in the stash: git stash apply ${stash}"
+    return 1
   fi
+  slot=$(git -C "${root}" stash list --format='%gd %H' | awk -v h="${stash}" '$2 == h { print $1; exit }')
+  [[ -n "${slot}" ]] && git -C "${root}" stash drop "${slot}" >/dev/null
+  ok "Swept the work into ${wt}, uncommitted; commit it there with a real message."
+  git -C "${root}" merge --ff-only "origin/${default_branch}" >/dev/null 2>&1 \
+    || warn "${default_branch} could not fast-forward to origin; it is left as it was."
+}
 
-  local pr
+# gh:pull-request <branch> <default-branch> <title> prints the number of the open pull request for the branch,
+# opening a draft if there is none.
+gh:pull-request() {
+  local branch=$1 default_branch=$2 title=$3 pr
   pr=$(gh pr list --head "${branch}" --state open --json number --jq '.[0].number // empty')
   if [[ -z "${pr}" ]]
   then
@@ -197,25 +160,83 @@ gh:issue() {
     gh pr create --draft --base "${default_branch}" --head "${branch}" --title "${title}" --body "" >/dev/null
     pr=$(gh pr list --head "${branch}" --state open --json number --jq '.[0].number')
   fi
+  printf '%s\n' "${pr}"
+}
+
+# gh:link-secondaries <pr> <number>… adds a `Closes #N` line to the pull request body for each number not there.
+gh:link-secondaries() {
+  local pr=$1 n body changed=false
+  shift
+  body=$(gh pr view "${pr}" --json body --jq '.body // ""')
+  for n in "$@"
+  do
+    if ! grep --quiet --ignore-case --extended-regexp "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
+    then
+      body="${body}"$'\n'"Closes #${n}"
+      changed=true
+    fi
+  done
+  if [[ "${changed}" == true ]]
+  then
+    step "Linking the secondary issues in the pull request body"
+    gh pr edit "${pr}" --body "${body}" >/dev/null
+  fi
+}
 
-  if (( $# > 1 ))
+gh:issue() {
+  use git
+  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr
+  me=$(gh:me) || return 1
+  if (( $# == 0 ))
   then
-    local body changed=false
-    body=$(gh pr view "${pr}" --json body --jq '.body // ""')
-    for n in "${@:2}"
-    do
-      if ! grep --quiet --ignore-case --extended-regexp "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
-      then
-        body="${body}"$'\n'"Closes #${n}"
-        changed=true
-      fi
-    done
-    if [[ "${changed}" == true ]]
+    if [[ ! -t 0 ]]
     then
-      step "Linking the secondary issues in the pull request body"
-      gh pr edit "${pr}" --body "${body}" >/dev/null
+      error "usage: kit issue <issue-number> [<issue-number>…]"
+      return 2
+    fi
+    set -- "$(gh:issue-create)" || return
+  fi
+  for n in "$@"
+  do
+    if [[ ! "${n}" =~ ^[0-9]+$ ]]
+    then
+      error "not an issue number: '${n}'"
+      return 2
     fi
+  done
+  primary=$1
+
+  git fetch --quiet --prune origin
+  default_branch=$(git:default-branch)
+  main_root=$(git:main-root)
+  desk=$(git rev-parse --show-toplevel)
+  desk_branch=$(git -C "${desk}" rev-parse --abbrev-ref HEAD)
+  title=$(gh issue view "${primary}" --json title --jq '.title')
+  if [[ -z "${title}" ]]
+  then
+    error "run: gh auth status (the title of #${primary} could not be read)"
+    return 1
+  fi
+  gh:assign "${me}" "$@"
+  section "Starting #${primary}: ${title}"
+
+  branch=$(gh:issue-branch "${primary}" "${default_branch}") || return
+  if [[ "${desk_branch}" == "${default_branch}" ]] && ! git:clean "${desk}"
+  then
+    step "Sweeping the uncommitted work on ${default_branch} into the worktree"
+    stash=$(gh:sweep-push "${desk}" "kit issue #${primary} → ${branch}") || return
+  fi
+  wt=$(gh:worktree "${main_root}" "${branch}") || return
+  git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null \
+    || warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a status or a commit"
+  gh:start-commit "${wt}" "${default_branch}" "${primary}" "${title}"
+  git -C "${wt}" push --quiet --set-upstream origin "${branch}"
+  if [[ -n "${stash}" ]]
+  then
+    gh:sweep-apply "${desk}" "${wt}" "${stash}" "${default_branch}" || return
   fi
+  pr=$(gh:pull-request "${branch}" "${default_branch}" "${title}")
+  (( $# > 1 )) && gh:link-secondaries "${pr}" "${@:2}"
 
   ok "Draft pull request #${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
   ok "Worktree ready: ${wt}"
diff --git a/bin/kit-target.sh b/bin/kit-target.sh
index 1281aab..9d27907 100755
--- a/bin/kit-target.sh
+++ b/bin/kit-target.sh
@@ -31,7 +31,7 @@ case "${verb}" in
     release:require-targets "$@"
     for t in "$@"
     do
-      if [[ " ${targets[*]} " == *" ${t} "* ]]
+      if release:among "${t}" "${targets[@]}"
       then
         step "${t}: already taken"
         continue
@@ -53,7 +53,7 @@ case "${verb}" in
     release:require-targets "$@"
     for t in "$@"
     do
-      if [[ " ${targets[*]} " != *" ${t} "* ]]
+      if ! release:among "${t}" "${targets[@]}"
       then
         step "${t}: not taken"
         continue
@@ -73,12 +73,7 @@ case "${verb}" in
           rm -f "${path}"
         fi
       done < <(release:target-only "${t}")
-      kept=()
-      for path in "${targets[@]}"
-      do
-        [[ "${path}" == "${t}" ]] || kept+=("${path}")
-      done
-      targets=("${kept[@]}")
+      read -r -a targets <<<"$(release:without "${t}" "${targets[@]}" | paste -s -d ' ' -)"
     done
     release:write-manifest "${targets[@]}"
     ok "targets: ${targets[*]:-none}"
diff --git a/bin/release.sh b/bin/release.sh
index a4d7663..8a71577 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -83,6 +83,27 @@ release:require-targets() {
 
 release:merged() { [[ "$1" == *.json ]]; }
 
+# release:among <name> <name>… is true when the first name is among the rest.
+release:among() {
+  local needle=$1 item
+  shift
+  for item in "$@"
+  do
+    [[ "${item}" == "${needle}" ]] && return 0
+  done
+  return 1
+}
+
+# release:without <name> <name>… prints the rest without the first name, one per line.
+release:without() {
+  local needle=$1 item
+  shift
+  for item in "$@"
+  do
+    [[ "${item}" == "${needle}" ]] || printf '%s\n' "${item}"
+  done
+}
+
 # The parameters are values ($), not filters: a filter parameter is re-read against the input at each use, which
 # inside the recursion is the wrong level of the object.
 release_jq='

From 388233438fdb8aa1e5aa8d37de80580e34de9c22 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:34:12 -0700
Subject: [PATCH 044/108] #1 justfile, kit-ci.yml, 1st.md: three couplings
 undone

just refresh reads the targets and the paths from the manifest, drops and retakes the targets, and stages every path either manifest names, so the hook only calls it and nothing else knows what install delivers. The delivered workflow no longer carries a bin/kit fallback for this repository; mise.toml puts bin/ on PATH here. The rules table names each rule and no longer restates its paths header.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml      | 16 ++++++----------
 .kit/1st.md                       | 16 ++++++++--------
 .kit/manifest                     |  4 ++--
 justfile                          | 22 +++++++++++++++-------
 lefthook.yml                      |  6 +++---
 tree/.github/workflows/kit-ci.yml | 16 ++++++----------
 tree/.kit/1st.md                  | 16 ++++++++--------
 7 files changed, 48 insertions(+), 48 deletions(-)

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 5b3b9de..3cf9a98 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -2,9 +2,9 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # One job, CI, which is the check name a ruleset requires. Three steps: the repository's `just ci` when its
-# root justfile has one, `kit check` against the release mise pins, and a refusal of a pull request that is
-# not linked to an open issue of this repository under Development. The last two run even when an earlier step
-# refused, so one run reports every finding.
+# root justfile has one, `kit check` with the kit mise pins, and a refusal of a pull request not linked to an
+# open issue of this repository under Development. The last two run even when an earlier step refused, so one
+# run reports every finding.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
@@ -31,7 +31,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      # Every tool below comes from mise.toml, the kit included.
+      # Every tool below comes from mise.toml, the kit included; this repository's mise.toml puts bin/ on PATH.
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
 
       - name: gate
@@ -60,18 +60,14 @@ jobs:
         if: ${{ !cancelled() }}
         run: |
           set -o errexit -o nounset -o pipefail
-          if command -v kit >/dev/null 2>&1
+          if ! command -v kit >/dev/null 2>&1
           then
-            kit check
-          elif [[ -x bin/kit ]]
-          then
-            bin/kit check
-          else
             echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'
             printf '### ❌ kit is not on PATH\n\nPin the release in mise.toml under [tools]: "github:empowerite/kit" = "<version>".\n' \
               | tee --append "${GITHUB_STEP_SUMMARY}"
             exit 1
           fi
+          kit check
           printf '✅ Every delivered file matches the pinned kit release.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
 
       - name: linked-open-issue
diff --git a/.kit/1st.md b/.kit/1st.md
index b17c5cc..f03805a 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -71,14 +71,14 @@ header. A harness that loads rules by path finds a copy under its own rules dire
 that target, `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of
 that kind.
 
-| Kind | Paths | Rule |
-| --- | --- | --- |
-| Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
-| Bash | `*.sh`, `*.bash` | [rules/bash.md](rules/bash.md) |
-| Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
-| YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
-| JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
-| Ignore lists | `.gitignore` | [rules/gitignore.md](rules/gitignore.md) |
+| Kind | Rule |
+| --- | --- |
+| Markdown | [rules/markdown.md](rules/markdown.md) |
+| Bash | [rules/bash.md](rules/bash.md) |
+| Just | [rules/just.md](rules/just.md) |
+| YAML | [rules/yaml.md](rules/yaml.md) |
+| JSON | [rules/json.md](rules/json.md) |
+| Ignore lists | [rules/gitignore.md](rules/gitignore.md) |
 
 ## What the kit carries
 
diff --git a/.kit/manifest b/.kit/manifest
index 7e1a54a..0153712 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -8,8 +8,8 @@ targets claude
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
-54014b457cbb469ee2d47d80edd5bc74cb1670afc235fc223d1f4e77ea78e859  .github/workflows/kit-ci.yml
-a8bc796a9e2a6c907ca61e59f02946dca1cb03833c01f34da6fbdc091e604d23  .kit/1st.md
+f03e0fa3ae07c74235558bffc38d5cb24c388c7c440e469cf8a8e58604edfc4b  .github/workflows/kit-ci.yml
+9fe231c16440c5346c9ed4fe2ef21e893d9e9048e507dd3b805c44b8c27624dc  .kit/1st.md
 4460940e906891560f03ee5a5c2b2a61e9f814b05cf32a5917933e902a6ed45c  .kit/lefthook.yml
 389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
diff --git a/justfile b/justfile
index c0d6a74..ed56571 100644
--- a/justfile
+++ b/justfile
@@ -37,17 +37,25 @@ ci:
   bin/kit check
   echo "✅ ci passed"
 
-# Reinstall this repository's own kit from its source. Here the checkout is the release, so an edit to a file under
-# tree/ or targets/ is an edit to the release, not a consumer's drift: the installed copies, .claude/settings.json
-# (which carries only the kit's entries here), and .kit/manifest are rewritten from it. Run after changing any
-# delivered file, and commit the result with the change.
+# Reinstall this repository's own kit from its source and stage the result. Here the checkout is the release, so an
+# edit under tree/ or targets/ is an edit to the release, not a consumer's drift: the targets the manifest names
+# are dropped and taken again, so the installed copies and .kit/manifest are rewritten from the source, and every
+# path the old or the new manifest names is staged. The pre-commit hook runs this on a commit that touches the
+# source; by hand it is for a desk without the hook.
 #
 #   just refresh
-[doc("🔁 Reinstall this repository's own kit from tree/, targets/, and bin/kit")]
+[doc("🔁 Reinstall this repository's own kit from tree/ and targets/, and stage the result")]
 refresh:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  rm -f .kit/manifest .claude/settings.json
-  bin/kit install claude
+  # a delivered path's line is a 64-hex digest, two spaces, the path; the version and targets lines are not
+  readarray -t before < <(awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest)
+  read -r -a targets <<<"$(sed -n 's/^targets *//p' .kit/manifest)"
+  (( ${#targets[@]} == 0 )) || bin/kit target remove "${targets[@]}" >/dev/null
+  rm -f .kit/manifest
+  bin/kit install "${targets[@]}" >/dev/null
+  readarray -t after < <(awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest)
+  git add --all -- "${before[@]}" "${after[@]}" .kit/manifest
+  echo "✅ refreshed and staged: ${#after[@]} delivered paths, targets ${targets[*]:-none}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/lefthook.yml b/lefthook.yml
index a9a1ced..ab8ed6c 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -17,8 +17,8 @@ pre-commit:
       glob: "*.md"
       run: markdownlint-cli2 {staged_files}
     # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, so
-    # nobody remembers just refresh. The command stages what it rewrote itself: stage_fixed would re-stage only
-    # the source paths it was handed, and the copies live elsewhere.
+    # nobody remembers just refresh. The recipe stages what it rewrote; stage_fixed would re-stage only the
+    # source paths it was handed.
     refresh:
       glob: "{tree,targets}/**"
-      run: just refresh && git add .kit .claude .github/workflows/kit-ci.yml
+      run: just refresh
diff --git a/tree/.github/workflows/kit-ci.yml b/tree/.github/workflows/kit-ci.yml
index 5b3b9de..3cf9a98 100644
--- a/tree/.github/workflows/kit-ci.yml
+++ b/tree/.github/workflows/kit-ci.yml
@@ -2,9 +2,9 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # One job, CI, which is the check name a ruleset requires. Three steps: the repository's `just ci` when its
-# root justfile has one, `kit check` against the release mise pins, and a refusal of a pull request that is
-# not linked to an open issue of this repository under Development. The last two run even when an earlier step
-# refused, so one run reports every finding.
+# root justfile has one, `kit check` with the kit mise pins, and a refusal of a pull request not linked to an
+# open issue of this repository under Development. The last two run even when an earlier step refused, so one
+# run reports every finding.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
@@ -31,7 +31,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      # Every tool below comes from mise.toml, the kit included.
+      # Every tool below comes from mise.toml, the kit included; this repository's mise.toml puts bin/ on PATH.
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
 
       - name: gate
@@ -60,18 +60,14 @@ jobs:
         if: ${{ !cancelled() }}
         run: |
           set -o errexit -o nounset -o pipefail
-          if command -v kit >/dev/null 2>&1
+          if ! command -v kit >/dev/null 2>&1
           then
-            kit check
-          elif [[ -x bin/kit ]]
-          then
-            bin/kit check
-          else
             echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'
             printf '### ❌ kit is not on PATH\n\nPin the release in mise.toml under [tools]: "github:empowerite/kit" = "<version>".\n' \
               | tee --append "${GITHUB_STEP_SUMMARY}"
             exit 1
           fi
+          kit check
           printf '✅ Every delivered file matches the pinned kit release.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
 
       - name: linked-open-issue
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index b17c5cc..f03805a 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -71,14 +71,14 @@ header. A harness that loads rules by path finds a copy under its own rules dire
 that target, `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of
 that kind.
 
-| Kind | Paths | Rule |
-| --- | --- | --- |
-| Markdown | `*.md` | [rules/markdown.md](rules/markdown.md) |
-| Bash | `*.sh`, `*.bash` | [rules/bash.md](rules/bash.md) |
-| Just | `justfile`, `*.just` | [rules/just.md](rules/just.md) |
-| YAML | `*.yml`, `*.yaml` | [rules/yaml.md](rules/yaml.md) |
-| JSON | `*.json`, `*.jsonc` | [rules/json.md](rules/json.md) |
-| Ignore lists | `.gitignore` | [rules/gitignore.md](rules/gitignore.md) |
+| Kind | Rule |
+| --- | --- |
+| Markdown | [rules/markdown.md](rules/markdown.md) |
+| Bash | [rules/bash.md](rules/bash.md) |
+| Just | [rules/just.md](rules/just.md) |
+| YAML | [rules/yaml.md](rules/yaml.md) |
+| JSON | [rules/json.md](rules/json.md) |
+| Ignore lists | [rules/gitignore.md](rules/gitignore.md) |
 
 ## What the kit carries
 

From 0337c0a79d1e73ae30f258f803a8a9d8ce378991 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:35:00 -0700
Subject: [PATCH 045/108] #1 .kit/rules: the rules say what the code does

The bash rule allows the short option where only the short one is portable and names the loader's bare verbs as the exception; the item about fail-open hooks goes with the hooks. The just rule says every justfile, puts set export after the default-and-help pair, and puts intent before usage, as both justfiles do. The retire workflow's header no longer narrates its own verification.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md                 | 15 ++++++++-------
 .claude/rules/kit-just.md                 | 12 +++++++-----
 .github/workflows/retire-pre-releases.yml |  5 ++---
 .kit/manifest                             |  8 ++++----
 .kit/rules/bash.md                        | 15 ++++++++-------
 .kit/rules/just.md                        | 12 +++++++-----
 tree/.kit/rules/bash.md                   | 15 ++++++++-------
 tree/.kit/rules/just.md                   | 12 +++++++-----
 8 files changed, 51 insertions(+), 43 deletions(-)

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
index 92d176e..33b1128 100644
--- a/.claude/rules/kit-bash.md
+++ b/.claude/rules/kit-bash.md
@@ -11,24 +11,25 @@ workflows.
 
 ## Shape
 
-1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner, a rule of dashes to
-   column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
+   rule of dashes to column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
 2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
    would change the caller's.
-3. A git hook that must fail open sets `-o nounset -o pipefail` and no `errexit`, and says so in its banner.
-4. The file closes with the same rule of dashes.
+3. The file closes with the same rule of dashes.
 
 ## Style
 
 1. `then`, `do`, and `else` go on their own line, never after a semicolon.
 2. Spell `set` options out: `set -o errexit`, never `set -e`.
-3. Spell command options out: `--raw-output`, `--field`, `--delimiter`, never a one-letter flag in a script.
-   Where BSD and GNU differ, use the form both accept: `sed -n`, `head -n 1`, `mkdir -p`.
+3. Spell a tool's options out where every platform accepts the long form: `--raw-output`, `--field`,
+   `--quiet`. Where BSD and GNU differ, use the form both accept, which is the short one: `sed -n`, `head -n 1`,
+   `mkdir -p`, `rm -f`, `cut -d`, `cp -R`, `find -type`, `read -r`, and `git -C`.
 4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
 5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
 6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
-8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename.
+8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
+   loader's own verbs are the exception and stay bare: `use`, `info`, `step`, `ok`, `section`, `warn`, `error`.
 9. A function private to one executed script is bare kebab-case.
 
 ## Behavior
diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
index 0698212..d91dd1f 100644
--- a/.claude/rules/kit-just.md
+++ b/.claude/rules/kit-just.md
@@ -12,10 +12,12 @@ applies to it as well.
 
 ## Shape
 
-1. A module file opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120, and
-   a description of what the file is and who imports it.
+1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120,
+   and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
+   --justfile` shebang above that; a module does not.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), `set positional-arguments := true`, and `set export := true`.
+   root, which has no parent), and `set positional-arguments := true`. `set export := true` comes after the
+   default-and-help pair, so that pair reads the same in every justfile.
 3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
@@ -38,8 +40,8 @@ applies to it as well.
 ## Recipes
 
 1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
-2. A comment block precedes every recipe: usage lines, then a paragraph of intent. It answers what the recipe
-   does, when to run it, and what it produces.
+2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
+   recipe does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
 4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
index 891c73a..a6d2ecd 100644
--- a/.github/workflows/retire-pre-releases.yml
+++ b/.github/workflows/retire-pre-releases.yml
@@ -4,9 +4,8 @@
 # A pre-release is tagged on a commit that is not on main, and main takes a branch by squash, so once the branch is
 # deleted its commits are reachable from nothing but the pre-release's own tag. This runs on every branch deletion
 # and retires, tag and all, each pre-release whose commit no remaining branch reaches. A release is never touched:
-# it is on main, which is never deleted. A deleted tag is a delete event too, and that one is ignored here.
-#
-# Checked by hand: an immutable pre-release deletes with its tag, and the tag name can never be reused.
+# it is on main, which is never deleted. A deleted tag is a delete event too, and that one is ignored here. An
+# immutable release deletes with its tag, and its tag name can never be reused.
 #
 # see: .github/workflows/release.yml
 
diff --git a/.kit/manifest b/.kit/manifest
index 0153712..079b546 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,19 +1,19 @@
 # .kit/manifest - written by kit, not by hand
 version unreleased
 targets claude
-389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .claude/rules/kit-bash.md
+b7f7f37d89165d6364fbb4e91c0c637eeb26fa72391a76f3419926efb7923522  .claude/rules/kit-bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .claude/rules/kit-json.md
-98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .claude/rules/kit-just.md
+edcd5198f76362ef2890f2dfa5ca2df1a81bce27864dc7c19fd64a683e040e23  .claude/rules/kit-just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
 f03e0fa3ae07c74235558bffc38d5cb24c388c7c440e469cf8a8e58604edfc4b  .github/workflows/kit-ci.yml
 9fe231c16440c5346c9ed4fe2ef21e893d9e9048e507dd3b805c44b8c27624dc  .kit/1st.md
 4460940e906891560f03ee5a5c2b2a61e9f814b05cf32a5917933e902a6ed45c  .kit/lefthook.yml
-389d14279648d69dbb1bf5454d22467f0f2d3aeec6b1844b01b2f2aeeaaeb9f5  .kit/rules/bash.md
+b7f7f37d89165d6364fbb4e91c0c637eeb26fa72391a76f3419926efb7923522  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
-98eb71bb5e6b885d5168ec1f47177c39d8bff3da720545c27e6995581e97ad12  .kit/rules/just.md
+edcd5198f76362ef2890f2dfa5ca2df1a81bce27864dc7c19fd64a683e040e23  .kit/rules/just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .kit/rules/markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .kit/rules/yaml.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index 92d176e..33b1128 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -11,24 +11,25 @@ workflows.
 
 ## Shape
 
-1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner, a rule of dashes to
-   column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
+   rule of dashes to column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
 2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
    would change the caller's.
-3. A git hook that must fail open sets `-o nounset -o pipefail` and no `errexit`, and says so in its banner.
-4. The file closes with the same rule of dashes.
+3. The file closes with the same rule of dashes.
 
 ## Style
 
 1. `then`, `do`, and `else` go on their own line, never after a semicolon.
 2. Spell `set` options out: `set -o errexit`, never `set -e`.
-3. Spell command options out: `--raw-output`, `--field`, `--delimiter`, never a one-letter flag in a script.
-   Where BSD and GNU differ, use the form both accept: `sed -n`, `head -n 1`, `mkdir -p`.
+3. Spell a tool's options out where every platform accepts the long form: `--raw-output`, `--field`,
+   `--quiet`. Where BSD and GNU differ, use the form both accept, which is the short one: `sed -n`, `head -n 1`,
+   `mkdir -p`, `rm -f`, `cut -d`, `cp -R`, `find -type`, `read -r`, and `git -C`.
 4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
 5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
 6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
-8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename.
+8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
+   loader's own verbs are the exception and stay bare: `use`, `info`, `step`, `ok`, `section`, `warn`, `error`.
 9. A function private to one executed script is bare kebab-case.
 
 ## Behavior
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index 0698212..d91dd1f 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -12,10 +12,12 @@ applies to it as well.
 
 ## Shape
 
-1. A module file opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120, and
-   a description of what the file is and who imports it.
+1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120,
+   and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
+   --justfile` shebang above that; a module does not.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), `set positional-arguments := true`, and `set export := true`.
+   root, which has no parent), and `set positional-arguments := true`. `set export := true` comes after the
+   default-and-help pair, so that pair reads the same in every justfile.
 3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
@@ -38,8 +40,8 @@ applies to it as well.
 ## Recipes
 
 1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
-2. A comment block precedes every recipe: usage lines, then a paragraph of intent. It answers what the recipe
-   does, when to run it, and what it produces.
+2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
+   recipe does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
 4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
diff --git a/tree/.kit/rules/bash.md b/tree/.kit/rules/bash.md
index 92d176e..33b1128 100644
--- a/tree/.kit/rules/bash.md
+++ b/tree/.kit/rules/bash.md
@@ -11,24 +11,25 @@ workflows.
 
 ## Shape
 
-1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner, a rule of dashes to
-   column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
+   rule of dashes to column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
 2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
    would change the caller's.
-3. A git hook that must fail open sets `-o nounset -o pipefail` and no `errexit`, and says so in its banner.
-4. The file closes with the same rule of dashes.
+3. The file closes with the same rule of dashes.
 
 ## Style
 
 1. `then`, `do`, and `else` go on their own line, never after a semicolon.
 2. Spell `set` options out: `set -o errexit`, never `set -e`.
-3. Spell command options out: `--raw-output`, `--field`, `--delimiter`, never a one-letter flag in a script.
-   Where BSD and GNU differ, use the form both accept: `sed -n`, `head -n 1`, `mkdir -p`.
+3. Spell a tool's options out where every platform accepts the long form: `--raw-output`, `--field`,
+   `--quiet`. Where BSD and GNU differ, use the form both accept, which is the short one: `sed -n`, `head -n 1`,
+   `mkdir -p`, `rm -f`, `cut -d`, `cp -R`, `find -type`, `read -r`, and `git -C`.
 4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
 5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
 6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
-8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename.
+8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
+   loader's own verbs are the exception and stay bare: `use`, `info`, `step`, `ok`, `section`, `warn`, `error`.
 9. A function private to one executed script is bare kebab-case.
 
 ## Behavior
diff --git a/tree/.kit/rules/just.md b/tree/.kit/rules/just.md
index 0698212..d91dd1f 100644
--- a/tree/.kit/rules/just.md
+++ b/tree/.kit/rules/just.md
@@ -12,10 +12,12 @@ applies to it as well.
 
 ## Shape
 
-1. A module file opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120, and
-   a description of what the file is and who imports it.
+1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120,
+   and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
+   --justfile` shebang above that; a module does not.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), `set positional-arguments := true`, and `set export := true`.
+   root, which has no parent), and `set positional-arguments := true`. `set export := true` comes after the
+   default-and-help pair, so that pair reads the same in every justfile.
 3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
@@ -38,8 +40,8 @@ applies to it as well.
 ## Recipes
 
 1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
-2. A comment block precedes every recipe: usage lines, then a paragraph of intent. It answers what the recipe
-   does, when to run it, and what it produces.
+2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
+   recipe does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
 4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported

From a3902287abead6c4555bf6cb5c60745a37fb9ffc Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:36:21 -0700
Subject: [PATCH 046/108] #1 documentation: banners, headers, and one
 description of the gate

Every verb's banner fits a line and its summary moves below the rule; the loader's and release workflow's run-together headers are rewrapped; mise.toml's header reads in order and its tools are alphabetical; the justfile's gate comment wraps where it should; the fragment says every tracked path; the entry file names all five loop commands and loses a comma splice; AGENTS.md points at the justfile for what the gate runs; the tests lose a stale assertion, a pointless -c, and three over-long chains. guard:require tool:git goes: nothing here runs without git.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 15 ++++++++-------
 .kit/1st.md                   | 17 +++++++++--------
 .kit/lefthook.yml             |  8 ++++----
 .kit/manifest                 |  4 ++--
 AGENTS.md                     |  2 +-
 bin/1st.sh                    |  7 ++++---
 bin/kit-check.sh              |  2 +-
 bin/kit-install.sh            |  6 ++++--
 bin/kit-issue.sh              |  4 +++-
 bin/kit-lint.sh               |  2 +-
 bin/kit-rebase.sh             |  4 +++-
 bin/kit-status.sh             |  2 +-
 bin/kit-target.sh             |  6 +++---
 bin/kit-tidy.sh               |  2 +-
 bin/kit-update.sh             |  4 ++--
 bin/kit-version.sh            |  2 +-
 bin/release.sh                |  2 +-
 justfile                      |  8 ++++----
 mise.toml                     | 15 +++++++--------
 tests/lint.bats               |  2 +-
 tests/rebase.bats             | 22 ++++++++++++++++------
 tests/release.bats            |  1 -
 tree/.kit/1st.md              | 17 +++++++++--------
 tree/.kit/lefthook.yml        |  8 ++++----
 24 files changed, 90 insertions(+), 72 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 6bf2899..b78d5a6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,13 +1,14 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, and a stamped version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A release, v<major>.<minor>.<patch>,
-# is tagged on main (any commit on main, not only its head). A pre-release, the same with a -<suffix>, is tagged on
-# a commit that is not on main, and is published as a GitHub pre-release. The tag is the version: the repository
-# carries no version file, and the one in the packed kit is stamped here from the tag, so a consumer sees it in
-# kit version and .kit/manifest and kit update can name the previous release to mise. A release, once published,
-# is immutable, so a tag is never reused. A pre-release lives as long as the branch it was tagged on; see:
-# .github/workflows/retire-pre-releases.yml
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, and a
+# stamped version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A
+# release, v<major>.<minor>.<patch>, is tagged on main, any commit on main and not only its head. A pre-release,
+# the same with a -<suffix>, is tagged on a commit that is not on main and is published as a GitHub pre-release.
+# The tag is the version: the repository carries no version file, and the one in the packed kit is stamped here
+# from the tag, so a consumer sees it in kit version and .kit/manifest, and kit update can name the previous
+# release to mise. A published release is immutable, so a tag is never reused. A pre-release lives as long as
+# the branch it was tagged on; see: .github/workflows/retire-pre-releases.yml
 #
 # see: .kit/1st.md
 
diff --git a/.kit/1st.md b/.kit/1st.md
index f03805a..cf4b2a1 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -66,10 +66,10 @@ A worker is whoever implements one issue in the worktree that issue names.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`, and each rule file names the paths it binds in its `paths:`
-header. A harness that loads rules by path finds a copy under its own rules directory when the repository takes
-that target, `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of
-that kind.
+Each file kind has a rule file under `.kit/rules/`, and each rule file's `paths:` header names the paths it
+binds. A harness that loads rules by path gets a copy in its own rules directory when the repository takes that
+target: `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of that
+kind.
 
 | Kind | Rule |
 | --- | --- |
@@ -85,10 +85,11 @@ that kind.
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
 release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
 carries the machinery, reached through the `kit` command on `PATH`. A release mirrors its `tree/` at the
-repository root, and `targets/<name>/` for each target taken; a `.json` destination is merged by key, everything
+repository root, and `targets/<name>/` for each target taken. A `.json` destination is merged by key; everything
 else is copied as it is.
 
-- `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
+- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, and `kit lint`, spelled that way and
+  no other.
 - `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
@@ -96,8 +97,8 @@ else is copied as it is.
   `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
   The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
   back out.
-- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
-  runs `kit check`, and refuses a pull request not linked to an open issue.
+- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`, runs `kit check`, and refuses
+  a pull request not linked to an open issue.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index aea7ecf..c0b9cfc 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -1,9 +1,9 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# Which linter runs over which paths. The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]`
-# and adds commands of its own under the same hook, or any other; Lefthook merges them by name, so a command named
-# here is overridden by one of the same name there. `kit lint` runs this hook by hand, over the staged paths or,
-# with --all-files, over every path. Once per clone: lefthook install
+# Which linter runs over which paths before a commit. The repository's lefthook.yml takes this with
+# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name, so a command of the same
+# name there overrides one here. `kit lint` runs this hook by hand, over the staged paths or, with --all-files,
+# over every tracked path. Once per clone: lefthook install
 #
 # see: https://lefthook.dev
 
diff --git a/.kit/manifest b/.kit/manifest
index 079b546..4ba3e5c 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -9,8 +9,8 @@ edcd5198f76362ef2890f2dfa5ca2df1a81bce27864dc7c19fd64a683e040e23  .claude/rules/
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
 f03e0fa3ae07c74235558bffc38d5cb24c388c7c440e469cf8a8e58604edfc4b  .github/workflows/kit-ci.yml
-9fe231c16440c5346c9ed4fe2ef21e893d9e9048e507dd3b805c44b8c27624dc  .kit/1st.md
-4460940e906891560f03ee5a5c2b2a61e9f814b05cf32a5917933e902a6ed45c  .kit/lefthook.yml
+22275196b95f53fe4b0bef7d309748161fcd2ede466a0ab3b67265fc2fa6814c  .kit/1st.md
+953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 b7f7f37d89165d6364fbb4e91c0c637eeb26fa72391a76f3419926efb7923522  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
diff --git a/AGENTS.md b/AGENTS.md
index d73b5d2..536a177 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,4 +14,4 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
   this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
   [README.md](README.md) § Maintaining. Edit the source; the pre-commit hook refreshes the copies into the same
   commit, and a desk without the hook runs `just refresh` and commits both.
-- `just ci` is the gate: shellcheck, actionlint, the bats suite, and `bin/kit check`.
+- `just ci` is the gate; the justfile says what it runs.
diff --git a/bin/1st.sh b/bin/1st.sh
index 8a8e904..3425cad 100644
--- a/bin/1st.sh
+++ b/bin/1st.sh
@@ -2,9 +2,10 @@
 # 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Sourced by every verb, bin/kit-<verb>.sh, which bin/kit dispatches to with kit_root exported. It defines functions only and sets no shell option, so the caller's options stand. A module is a
-# sourced <module>.sh beside this file, loaded with `use <module>`, once, by the verb or module that needs it; there
-# is no other way in. A verb is an executable kit-<verb>.sh beside it.
+# Sourced by every verb, bin/kit-<verb>.sh, which bin/kit dispatches to with kit_root exported. It defines
+# functions only and sets no shell option, so the caller's options stand. A module is a sourced <module>.sh
+# beside this file, loaded once with `use <module>` by the verb or module that needs it; there is no other way
+# in. A verb is an executable kit-<verb>.sh beside it.
 #
 # Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
 # NO_COLOR is set. Under GitHub Actions, warn and error also emit the matching workflow command.
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index 257c13a..732c1c3 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-check - fail when a delivered file differs from the pinned release (kit verb, run through bin/kit)
+# kit-check - fail when a delivered file differs from the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # see: bin/release.sh
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index eb0ed00..4ee448c 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-# kit-install - mirror the release into the repository, take the named targets, and write .kit/manifest (kit verb, run through bin/kit)
+# kit-install - mirror the release into the repository (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# Takes the named targets and writes .kit/manifest.
+#
 # see: bin/release.sh
 
 set -o errexit -o nounset -o pipefail
@@ -15,7 +17,7 @@ then
   exit 0
 fi
 
-guard:require tool:jq tool:git
+guard:require tool:jq
 release:require-targets "$@"
 if [[ -f .kit/manifest ]]
 then
diff --git a/bin/kit-issue.sh b/bin/kit-issue.sh
index 90edef1..b59451f 100755
--- a/bin/kit-issue.sh
+++ b/bin/kit-issue.sh
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-# kit-issue - start or resume an issue: linked branch, worktree, start commit, draft pull request (kit verb, run through bin/kit)
+# kit-issue - start or resume an issue (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# A linked branch, a worktree, a start commit, and a draft pull request.
+#
 # see: bin/gh.sh
 
 set -o errexit -o nounset -o pipefail
diff --git a/bin/kit-lint.sh b/bin/kit-lint.sh
index c4a04aa..5b7fd7d 100755
--- a/bin/kit-lint.sh
+++ b/bin/kit-lint.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-lint - run the pre-commit hook by hand: the linters .kit/lefthook.yml and lefthook.yml declare (kit verb)
+# kit-lint - run the pre-commit hook's linters by hand (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # An alias for `lefthook run pre-commit`, so the linters a commit meets are the ones this runs, over the staged
diff --git a/bin/kit-rebase.sh b/bin/kit-rebase.sh
index 4cb80e6..649451c 100755
--- a/bin/kit-rebase.sh
+++ b/bin/kit-rebase.sh
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-# kit-rebase - rebase a worktree's branch onto the default branch and push it; never the default branch (kit verb, run through bin/kit)
+# kit-rebase - rebase a worktree's branch onto the default branch and push it (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# Never the default branch itself.
+#
 # see: bin/git.sh
 
 set -o errexit -o nounset -o pipefail
diff --git a/bin/kit-status.sh b/bin/kit-status.sh
index 2345130..ac38f9b 100755
--- a/bin/kit-status.sh
+++ b/bin/kit-status.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-status - show every worktree with its branch, pull request, and state (kit verb, run through bin/kit)
+# kit-status - show every worktree with its branch, pull request, and state (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # see: bin/git.sh
diff --git a/bin/kit-target.sh b/bin/kit-target.sh
index 9d27907..1d770ef 100755
--- a/bin/kit-target.sh
+++ b/bin/kit-target.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-target - list, take, or drop the targets this repository takes (kit verb, run through bin/kit)
+# kit-target - list, take, or drop the targets this repository takes (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # see: bin/release.sh
@@ -27,7 +27,7 @@ case "${verb}" in
     ;;
   (add)
     (( $# > 0 )) || { usage; exit 2; }
-    guard:require tool:jq tool:git
+    guard:require tool:jq
     release:require-targets "$@"
     for t in "$@"
     do
@@ -49,7 +49,7 @@ case "${verb}" in
     ;;
   (remove)
     (( $# > 0 )) || { usage; exit 2; }
-    guard:require tool:jq tool:git
+    guard:require tool:jq
     release:require-targets "$@"
     for t in "$@"
     do
diff --git a/bin/kit-tidy.sh b/bin/kit-tidy.sh
index 2ac2bea..d604c9a 100755
--- a/bin/kit-tidy.sh
+++ b/bin/kit-tidy.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-tidy - remove worktrees whose pull request is merged or closed, and gone branches (kit verb, run through bin/kit)
+# kit-tidy - remove merged worktrees and gone branches (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # see: bin/git.sh
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 88eb004..40ced66 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-update - after the pin is bumped: replace unchanged files, three-way merge changed ones (kit verb, run through bin/kit)
+# kit-update - move the repository to the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A file whose digest still matches the manifest, which records the previous release's own content, is replaced.
@@ -19,7 +19,7 @@ then
   exit 0
 fi
 
-guard:require tool:jq tool:git
+guard:require tool:jq
 release:require-manifest
 read -r -a targets <<<"$(release:manifest-targets)"
 previous=$(release:manifest-version)
diff --git a/bin/kit-version.sh b/bin/kit-version.sh
index f4e07e3..5f2e04a 100755
--- a/bin/kit-version.sh
+++ b/bin/kit-version.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-version - print this release's version (kit verb, run through bin/kit)
+# kit-version - print this release's version (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 
 set -o errexit -o nounset -o pipefail
diff --git a/bin/release.sh b/bin/release.sh
index 8a71577..36be28c 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -150,7 +150,7 @@ release:digest() {
   fi
 }
 
-# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, a copy otherwise.
+# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, else a copy.
 release:place() {
   local src=$1 path=$2 base=${3:-/dev/null}
   if release:merged "${path}"
diff --git a/justfile b/justfile
index ed56571..83ab83c 100644
--- a/justfile
+++ b/justfile
@@ -20,10 +20,10 @@ _: help
 
 set export := true
 
-# The gate: shellcheck over every bash file, actionlint over every workflow, markdownlint over every markdown file,
-# the bats suite, and bin/kit check over
-# this repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
-# same way; the pre-commit hook is the narrower, faster check over the staged paths.
+# The gate: shellcheck over every bash file, actionlint over every workflow, markdownlint over every markdown
+# file, the bats suite, and bin/kit check over this repository's installed copy of its own kit. The runner runs
+# it on every pull request, and a desk runs it the same way; the pre-commit hook is the narrower, faster check
+# over the staged paths.
 #
 #   just ci
 [doc("🚦 The gate: shellcheck, actionlint, markdownlint, bats, kit check")]
diff --git a/mise.toml b/mise.toml
index 00c0da8..a5ead37 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,10 +1,9 @@
 # mise.toml - the pinned tools a desk and a runner share; see: https://mise.jdx.dev/configuration/environments.html
 #
-# One mechanism: mise reads this file always, mise.desk.toml on top of it when MISE_ENV=desk, which a desk exports
-# in its shell profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in the file of
-# whoever runs it; today only Lefthook is a desk's alone, and nothing is the runner's alone. `lockfile = true` records each pin's exact resolution in a lock beside its file,
-# and lockfile_platforms makes a lock written on a desk carry the runner's platform. git and bash come from the
-# machine.
+# mise reads this file always, mise.desk.toml on top of it when MISE_ENV=desk, which a desk exports in its shell
+# profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in the file of whoever runs
+# it; today Lefthook is a desk's alone, and nothing is the runner's alone. `lockfile = true` records each pin's
+# exact resolution in a lock beside its file. git and bash come from the machine.
 
 [settings]
 lockfile = true
@@ -16,10 +15,10 @@ lockfile_platforms = ["linux-x64", "linux-arm64", "macos-arm64", "macos-x64"]
 _.path = ["bin"]
 
 [tools]
+actionlint = "1.7"
+bats = "1.14"
 gh = "2.103"
 jq = "1.8"
-"npm:markdownlint-cli2" = "0.24"
 just = "1.59"
+"npm:markdownlint-cli2" = "0.24"
 shellcheck = "0.11"
-actionlint = "1.7"
-bats = "1.14"
diff --git a/tests/lint.bats b/tests/lint.bats
index 96aa0cd..461fb11 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -29,7 +29,7 @@ teardown() {
 }
 
 @test "lint --all-files reads every tracked path, where lint alone reads only the staged ones" {
-  git -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false add bad.sh
+  git add bad.sh
   git -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false commit --quiet --no-verify --message bad
   run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 0 ]
diff --git a/tests/rebase.bats b/tests/rebase.bats
index 571f696..fbb922b 100644
--- a/tests/rebase.bats
+++ b/tests/rebase.bats
@@ -18,9 +18,19 @@ teardown() {
   rm -rf "${work}"
 }
 
-worktree() {  # a worktree on branch 1-x, configured to commit
+# worktree makes a worktree on branch 1-x beside the desk, configured to commit.
+worktree() {
   git worktree add --quiet ../wt -b 1-x
-  git -C ../wt config user.name t && git -C ../wt config user.email t@example.com && git -C ../wt config commit.gpgsign false
+  git -C ../wt config user.name t
+  git -C ../wt config user.email t@example.com
+  git -C ../wt config commit.gpgsign false
+}
+
+# commit-in <checkout> <file> <content> writes the file and commits it there.
+commit-in() {
+  printf '%s\n' "$3" > "$1/$2"
+  git -C "$1" add "$2"
+  git -C "$1" commit --quiet --message "$2"
 }
 
 @test "rebase refuses the default branch" {
@@ -31,8 +41,8 @@ worktree() {  # a worktree on branch 1-x, configured to commit
 
 @test "rebase moves a worktree's branch onto origin/main and pushes it" {
   worktree
-  printf 'two\n' > ../wt/b && git -C ../wt add b && git -C ../wt commit --quiet --message two && git -C ../wt push --quiet --set-upstream origin 1-x
-  printf 'three\n' > c && git add c && git commit --quiet --message three && git push --quiet origin main
+  commit-in ../wt b two && git -C ../wt push --quiet --set-upstream origin 1-x
+  commit-in . c three && git push --quiet origin main
   run "${kit_checkout}/bin/kit" rebase ../wt
   [ "$status" -eq 0 ]
   [ "$(git -C ../wt rev-parse HEAD~1)" = "$(git rev-parse origin/main)" ]
@@ -41,8 +51,8 @@ worktree() {  # a worktree on branch 1-x, configured to commit
 
 @test "rebase aborts on a conflict and leaves the worktree as it was" {
   worktree
-  printf 'theirs\n' > ../wt/a && git -C ../wt commit --quiet --all --message theirs && git -C ../wt push --quiet --set-upstream origin 1-x
-  printf 'ours\n' > a && git commit --quiet --all --message ours && git push --quiet origin main
+  commit-in ../wt a theirs && git -C ../wt push --quiet --set-upstream origin 1-x
+  commit-in . a ours && git push --quiet origin main
   before=$(git -C ../wt rev-parse HEAD)
   run "${kit_checkout}/bin/kit" rebase ../wt
   [ "$status" -eq 1 ]
diff --git a/tests/release.bats b/tests/release.bats
index 6da12a3..ba5c9e3 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -33,7 +33,6 @@ teardown() {
   [ "$status" -eq 0 ]
   [ "$("${work}/unpacked/kit-${version}/bin/kit" version)" = "${version}" ]
   [ ! -L .claude/rules/kit-bash.md ]
-  [ ! -e .kit/bash ]
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index f03805a..cf4b2a1 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -66,10 +66,10 @@ A worker is whoever implements one issue in the worktree that issue names.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`, and each rule file names the paths it binds in its `paths:`
-header. A harness that loads rules by path finds a copy under its own rules directory when the repository takes
-that target, `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of
-that kind.
+Each file kind has a rule file under `.kit/rules/`, and each rule file's `paths:` header names the paths it
+binds. A harness that loads rules by path gets a copy in its own rules directory when the repository takes that
+target: `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of that
+kind.
 
 | Kind | Rule |
 | --- | --- |
@@ -85,10 +85,11 @@ that kind.
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
 release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
 carries the machinery, reached through the `kit` command on `PATH`. A release mirrors its `tree/` at the
-repository root, and `targets/<name>/` for each target taken; a `.json` destination is merged by key, everything
+repository root, and `targets/<name>/` for each target taken. A `.json` destination is merged by key; everything
 else is copied as it is.
 
-- `kit issue`, `kit tidy`, and `kit status`, the loop's commands, spelled that way and no other.
+- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, and `kit lint`, spelled that way and
+  no other.
 - `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
@@ -96,8 +97,8 @@ else is copied as it is.
   `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
   The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
   back out.
-- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`,
-  runs `kit check`, and refuses a pull request not linked to an open issue.
+- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`, runs `kit check`, and refuses
+  a pull request not linked to an open issue.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/tree/.kit/lefthook.yml b/tree/.kit/lefthook.yml
index aea7ecf..c0b9cfc 100644
--- a/tree/.kit/lefthook.yml
+++ b/tree/.kit/lefthook.yml
@@ -1,9 +1,9 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# Which linter runs over which paths. The repository's lefthook.yml takes this with `extends: [.kit/lefthook.yml]`
-# and adds commands of its own under the same hook, or any other; Lefthook merges them by name, so a command named
-# here is overridden by one of the same name there. `kit lint` runs this hook by hand, over the staged paths or,
-# with --all-files, over every path. Once per clone: lefthook install
+# Which linter runs over which paths before a commit. The repository's lefthook.yml takes this with
+# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name, so a command of the same
+# name there overrides one here. `kit lint` runs this hook by hand, over the staged paths or, with --all-files,
+# over every tracked path. Once per clone: lefthook install
 #
 # see: https://lefthook.dev
 

From bdadcf4218a5931af194dc74b2574cc6abf4640a Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:50:56 -0700
Subject: [PATCH 047/108] #1 justfile: refresh generates from the index after
 removing the old copies

The copies are made from what the commit will carry, never the working tree, so a half-staged edit cannot put a copy into a commit that lacks its source. Every path the old manifest lists is removed before the new release is installed, so a deleted source leaves no copy and a retired entry does not survive in a merged .json. This repository keeps nothing of its own in a delivered path, which makes the removal safe here.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 justfile     | 31 ++++++++++++++++++-------------
 lefthook.yml |  6 +++---
 2 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/justfile b/justfile
index 83ab83c..eee51c1 100644
--- a/justfile
+++ b/justfile
@@ -37,25 +37,30 @@ ci:
   bin/kit check
   echo "✅ ci passed"
 
-# Reinstall this repository's own kit from its source and stage the result. Here the checkout is the release, so an
-# edit under tree/ or targets/ is an edit to the release, not a consumer's drift: the targets the manifest names
-# are dropped and taken again, so the installed copies and .kit/manifest are rewritten from the source, and every
-# path the old or the new manifest names is staged. The pre-commit hook runs this on a commit that touches the
-# source; by hand it is for a desk without the hook.
+# Reinstall this repository's own kit from the index and stage the result. Here the checkout is the release, so an
+# edit under tree/ or targets/ is an edit to the release, not a consumer's drift. The copies are made from the
+# index, what the commit will carry, never from the working tree, so a half-staged edit cannot put a copy into a
+# commit that lacks its source. Every path the old manifest lists is removed first and written again from the
+# new release: a source that was deleted leaves no copy behind, and an entry that was retired does not survive
+# in a merged .json. This repository keeps nothing of its own in a delivered path, which is what makes that
+# removal safe here. The pre-commit hook runs this on a commit that touches the source; by hand it is for a desk
+# without the hook.
 #
 #   just refresh
-[doc("🔁 Reinstall this repository's own kit from tree/ and targets/, and stage the result")]
+[doc("🔁 Reinstall this repository's own kit from the index, and stage the result")]
 refresh:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  # a delivered path's line is a 64-hex digest, two spaces, the path; the version and targets lines are not
-  readarray -t before < <(awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest)
+  paths() { awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest; }
+  readarray -t before < <(paths)
   read -r -a targets <<<"$(sed -n 's/^targets *//p' .kit/manifest)"
-  (( ${#targets[@]} == 0 )) || bin/kit target remove "${targets[@]}" >/dev/null
-  rm -f .kit/manifest
-  bin/kit install "${targets[@]}" >/dev/null
-  readarray -t after < <(awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest)
+  index=$(mktemp -d)
+  trap 'rm -rf "${index}"' EXIT
+  git checkout-index --all --prefix="${index}/"
+  rm -f "${before[@]}" .kit/manifest
+  "${index}/bin/kit" install "${targets[@]}" >/dev/null
+  readarray -t after < <(paths)
   git add --all -- "${before[@]}" "${after[@]}" .kit/manifest
-  echo "✅ refreshed and staged: ${#after[@]} delivered paths, targets ${targets[*]:-none}"
+  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, targets ${targets[*]:-none}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/lefthook.yml b/lefthook.yml
index ab8ed6c..840a2a8 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -16,9 +16,9 @@ pre-commit:
     markdownlint:
       glob: "*.md"
       run: markdownlint-cli2 {staged_files}
-    # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, so
-    # nobody remembers just refresh. The recipe stages what it rewrote; stage_fixed would re-stage only the
-    # source paths it was handed.
+    # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, from
+    # the index, so nobody remembers just refresh. The recipe stages what it rewrote; stage_fixed would re-stage
+    # only the source paths it was handed.
     refresh:
       glob: "{tree,targets}/**"
       run: just refresh

From 8ced48412a8baaf9783c8dd85fbfc5706692ef3d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:53:21 -0700
Subject: [PATCH 048/108] #1 README.md: keep it trustworthy

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b890439..f4c2063 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# kit
+# empowerite/kit: **k**eep **i**t **t**rustworthy
 
 kit is the agentic guardrails a repository takes as a versioned mixin: the policy text an agent reads first, the
 rules that bind each kind of file, the guard that keeps `main` as the human's desk, and the one command no harness

From 32994b84f7e1afc87ea8a202aea91e587089963f Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 01:53:39 -0700
Subject: [PATCH 049/108] #1 README.md: the three steps first, and each thing
 said once

Take the kit leads with the pin, the install, and the AGENTS.md lines; what install writes is said in Maintaining; the bash note joins its sentence; the MISE_ENV mechanism is explained in one place; the gate is described in the justfile alone; Maintaining says the copies come from the index.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 67 ++++++++++++++++++++++++-------------------------------
 1 file changed, 29 insertions(+), 38 deletions(-)

diff --git a/README.md b/README.md
index f4c2063..ceff989 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ installs it with `kit install`, and keeps rules of its own beside it. The design
 
 ## Take the kit
 
-Pin a release in the repository's `mise.toml`, then install it, naming the harnesses the team uses:
+Pin a release in `mise.toml`, install it, and point `AGENTS.md` at it:
 
 ```toml
 [tools]
@@ -20,35 +20,30 @@ mise install
 kit install claude
 ```
 
-An exact pin installs the minute a release exists. If you pin a range instead, add
-`minimum_release_age_excludes = ["github:empowerite/kit"]` under `[settings]`, or `mise outdated` and
-`mise upgrade` offer a new kit only a day after it ships.
-
-`kit install` copies `.kit/1st.md`, `.kit/rules/`, and `.kit/lefthook.yml` into the repository, places
-`.github/workflows/kit-ci.yml`, and writes `.kit/manifest`. Each target named adds what that harness insists on
-having outside `.kit/`; `claude` places `.claude/rules/kit-*.md` and merges the kit's deny rules into
-`.claude/settings.json`. A repository with no target installed still binds every agent that reads `AGENTS.md`,
-through the rules table in `.kit/1st.md`. `kit target add` and `kit target remove` change the set later, and
-`kit target list` prints it. Commit what it wrote. Then:
-
-- Open `AGENTS.md` with `@.kit/1st.md` and the sentence "Read .kit/1st.md first." The rest of the file is yours.
-- Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it, then `kit check`, then refuses a pull
-  request not linked to an open issue.
-- Pin `lefthook` in `mise.desk.toml`, which mise reads when `MISE_ENV=desk`, put `extends: [.kit/lefthook.yml]`
-  in `lefthook.yml`, and run `lefthook install` once per clone. The fragment says which linter runs over which
-  paths before a commit, and your `lefthook.yml` adds commands of its own. `kit lint` runs the same hook by hand.
-  The delivered `CI` job sets `MISE_ENV=ci`, so a tool only the runner needs is pinned in `mise.ci.toml`.
-
-The machinery, the `kit` command and the bash behind its verbs, stays in the release where mise installed it; the
-repository carries the text an agent reads and the record of what it took. The kit needs bash 4.4 or later, git,
-`gh`, and `jq`.
+```markdown
+@.kit/1st.md
+
+Read .kit/1st.md first.
+```
+
+The rest of `AGENTS.md` is yours. `install` writes `.kit/`, the CI workflow, and the files of each target named;
+`claude` is the one target this release knows, and a repository with no target still binds every agent that
+reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the root justfile for the delivered `CI` job to
+run, and take the pre-commit linters by pinning `lefthook` in `mise.desk.toml`, putting
+`extends: [.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit target
+add`, `kit target remove`, and `kit target list` change and show the targets later.
+
+An exact pin installs the minute a release exists. A range pin sees a new kit a day after it ships unless
+`[settings]` carries `minimum_release_age_excludes = ["github:empowerite/kit"]`.
 
 To move to a new release, bump the pin, run `mise install`, then `kit update`: a delivered file you left alone is
 replaced, one you edited is three-way merged with the previous release as the base, and your own deny entries
 and settings keys stay. `kit check` fails, locally and in `CI`, when a delivered file differs from the pinned
 release.
 
-macOS ships bash 3.2; `brew install bash` gives a current one.
+The kit needs bash 4.4 or later, git, `gh`, and `jq`; macOS ships bash 3.2, and `brew install bash` gives a
+current one. The `kit` command and the bash behind its verbs stay in the release where mise installed it; the
+repository carries the text an agent reads and the record of what it took.
 
 ## Setup
 
@@ -66,11 +61,8 @@ mise install
 lefthook install
 ```
 
-`MISE_ENV=desk` belongs in your shell profile. mise reads `mise.toml` always, `mise.desk.toml` on top of it when
-`MISE_ENV=desk`, and `mise.ci.toml` when `MISE_ENV=ci`, which the CI workflow sets: a tool goes in the file of
-whoever runs it. Lefthook is a desk's; nothing here is the runner's alone.
-
-This repository carries the installed copy of its own kit, and `just ci` checks it.
+`MISE_ENV=desk` belongs in your shell profile: it makes mise read `mise.desk.toml`, the tools only a desk runs,
+on top of `mise.toml`; the delivered `CI` job sets `MISE_ENV=ci` the same way for `mise.ci.toml`.
 
 ## Getting started
 
@@ -81,8 +73,7 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
   draft pull request. It never switches the checkout it runs from.
 - Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`. `kit rebase`
   brings the branch up to date with `main` and pushes it.
-- `just ci` is the gate: shellcheck over the bash, actionlint over the workflows, the bats suite in `tests/`, and
-  `bin/kit check`.
+- `just ci` is the gate; the justfile says what it runs.
 - `gh pr ready` says the work is done, and the pull request body is the report.
 - A human merges. `kit tidy` then removes the worktree and its branch.
 
@@ -90,9 +81,9 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
 every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
-the same way; `bin/` is the machinery: `bin/kit` dispatches to one executable `bin/kit-<verb>.sh`
-per verb, and the verbs source the modules beside them, `1st.sh`, `gh.sh`, `git.sh`, and `release.sh`. A symlink
-under `targets/` is delivered as the file it points at, so a rule lives once, in `tree/.kit/rules/`.
+the same way; and `bin/` is the machinery, `bin/kit` dispatching to one executable `bin/kit-<verb>.sh` per verb,
+each sourcing the modules beside it. A symlink under `targets/` is delivered as the file it points at, so a rule
+lives once, in `tree/.kit/rules/`.
 
 The installed copies are written by `bin/kit install` and not edited by hand:
 
@@ -105,10 +96,10 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.kit/manifest` | the release version (`unreleased` here), the targets taken, and a digest per delivered path |
 
 A commit that changes a file under `tree/` or `targets/` rewrites the installed copies in the same commit: the
-pre-commit hook runs `just refresh` and stages what it rewrote. On a desk without the hook, run `just refresh`
-by hand and commit the result with the change. `bin/kit check`, which `just ci` runs, names any installed copy
-that no longer matches its source. Each delivered text file says in its header that it is delivered by kit;
-`settings.json` cannot, so this table is its notice.
+pre-commit hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk
+without the hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names
+any installed copy that no longer matches its source. Each delivered text file says in its header that it is
+delivered by kit; `settings.json` cannot, so this table is its notice.
 
 ## Release
 

From 1f36d5c39895982aa7d3bba4dc0d759ed846cbbe Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 09:51:48 -0700
Subject: [PATCH 050/108] #1 bin: kit status as a dashboard, a release root
 through a symlink, and a base fetched without mise

kit status draws the pull requests in flight: state, age, checks, the commits each carries, and the worktree it is written in with its distance from main and the size of its diff; one request to GitHub. bin/kit resolves the release through any symlink, as Homebrew links it. release:fetch finds a previous release in the kit's cache, in mise if mise is here, or downloads the GitHub release, so kit update's base needs no particular installer.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/git.sh        | 133 ++++++++++++++++++++++++++++++++++------------
 bin/kit           |   7 +--
 bin/kit-update.sh |  19 +++----
 bin/release.sh    |  32 +++++++++++
 4 files changed, 144 insertions(+), 47 deletions(-)

diff --git a/bin/git.sh b/bin/git.sh
index 6e7cec1..3f8c0e7 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -2,9 +2,10 @@
 # git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# git:status [--no-fetch] renders the main checkout on one line and one block per worktree under worktrees/, with
-# its branch, pull request, and dirty or clean state, then the local branches whose upstream is gone. It changes
-# nothing.
+# git:status [--no-fetch] draws the picture of the work in flight: the open pull requests, and under each its
+# state, age, checks, the commits it carries, and the worktree it is written in, with how far that is ahead of and
+# behind the default branch and the size of its diff; then the worktrees with no pull request; then the local
+# branches whose upstream is gone. It changes nothing, and asks GitHub once.
 #
 # git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
 # detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
@@ -73,31 +74,68 @@ git:clean() {
   [[ -z "$(git -C "$1" status --porcelain 2>/dev/null)" ]]
 }
 
-# git:status-block <path> <branch> <main-root> <default-branch> renders one worktree.
-git:status-block() {
-  local path=$1 branch=$2 main_root=$3 default_branch=$4 pr ahead_behind
-  step "${path#"${main_root}"/}"
-  info "  branch  ${branch:-(detached)}"
-  if [[ -n "${branch}" ]]
+# git:open-prs prints one line per open pull request: "<branch>\t<number>\t<Draft|Ready>\t<age in days>\t<checks>\t<title>",
+# where <checks> is "✅ n/n", "❌ k/n", "⏳ n", or "·" for none. One request, for the whole picture.
+git:open-prs() {
+  # shellcheck disable=SC2016  # a jq filter, with jq variables
+  gh pr list --state open --limit 100 --json number,title,isDraft,headRefName,createdAt,statusCheckRollup --jq '
+    .[] | [
+      .headRefName,
+      (.number | tostring),
+      (if .isDraft then "Draft" else "Ready" end),
+      (((now - (.createdAt | fromdateiso8601)) / 86400 | floor | tostring) + "d"),
+      ((.statusCheckRollup // []) as $c
+        | ($c | length) as $n
+        | ([$c[] | select(.conclusion == "SUCCESS")] | length) as $ok
+        | ([$c[] | select(.conclusion != null and .conclusion != "SUCCESS" and .conclusion != "SKIPPED" and .conclusion != "NEUTRAL")] | length) as $bad
+        | if $n == 0 then "·"
+          elif $bad > 0 then "❌ \($bad)/\($n)"
+          elif $ok == $n then "✅ \($n)/\($n)"
+          else "⏳ \($n - $ok)/\($n)" end),
+      .title
+    ] | @tsv' 2>/dev/null || true
+}
+
+# git:short <text> [<width>] prints <text> cut to <width> columns, 16 by default, with an ellipsis when cut.
+git:short() {
+  local text=$1 width=${2:-16}
+  if (( ${#text} > width ))
   then
-    pr=$(git:pr-summary "${branch}")
-    ahead_behind=$(git rev-list --left-right --count "${branch}...${default_branch}" 2>/dev/null || printf '0\t0')
-    if [[ -n "${pr}" ]]
-    then
-      pr="#${pr%%$'\t'*} ${pr##*$'\t'}"
-    else
-      pr="(none open)"
-    fi
-    info "  pr      ${pr} · ↑${ahead_behind%%$'\t'*} ↓${ahead_behind##*$'\t'} vs ${default_branch}"
+    printf '%s…\n' "${text:0:width-1}"
   else
-    info "  pr      (no branch)"
+    printf '%s\n' "${text}"
   fi
-  if git:clean "${path}"
+}
+
+# git:worktree-line <path> <branch> <main-root> <default-branch> prints the 🌿 line: the worktree's path, how far
+# its branch is ahead of and behind the default branch, and the size of its diff.
+git:worktree-line() {
+  local path=$1 branch=$2 main_root=$3 default_branch=$4 counts="0\t0" stat added=0 removed=0 dirty=""
+  if [[ -n "${branch}" ]]
   then
-    info "  status  clean"
-  else
-    info "  status  $(git -C "${path}" status --porcelain | grep --count .) file(s) modified"
+    counts=$(git rev-list --left-right --count "${branch}...origin/${default_branch}" 2>/dev/null || printf '0\t0')
+    stat=$(git diff --shortstat "origin/${default_branch}...${branch}" 2>/dev/null || true)
+    [[ "${stat}" =~ ([0-9]+)\ insertion ]] && added=${BASH_REMATCH[1]}
+    [[ "${stat}" =~ ([0-9]+)\ deletion ]] && removed=${BASH_REMATCH[1]}
   fi
+  git:clean "${path}" || dirty=" · $(git -C "${path}" status --porcelain | grep --count .) uncommitted"
+  printf '   🌿 %s   ↑%s ↓%s · +%s -%s%s\n' "$(git:short "${path#"${main_root}"/}" 40)" "${counts%%$'\t'*}" "${counts##*$'\t'}" "${added}" "${removed}" "${dirty}" >&2
+}
+
+# git:pr-block <pr-line> <path> <main-root> <default-branch> prints one pull request: its line, the commits it
+# carries over the default branch, up to ten, and its worktree's line.
+git:pr-block() {
+  local branch number state age checks title path=$2 main_root=$3 default_branch=$4 shown=0 total line
+  IFS=$'\t' read -r branch number state age checks title <<<"$1"
+  printf '🔀 #%s %-17s %-6s %4s   %s\n' "${number}" "$(git:short "${title}")" "${state}" "${age}" "${checks}" >&2
+  total=$(git rev-list --count "origin/${default_branch}..${branch}" 2>/dev/null || printf 0)
+  while IFS= read -r line
+  do
+    printf '   %s\n' "${line}" >&2
+    (( ++shown ))
+  done < <(git log --format='%h %s' --max-count 10 "origin/${default_branch}..${branch}" 2>/dev/null)
+  (( total > shown )) && printf '   … and %s more\n' "$(( total - shown ))" >&2
+  git:worktree-line "${path}" "${branch}" "${main_root}" "${default_branch}"
 }
 
 # git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides one worktree and
@@ -152,7 +190,8 @@ git:tidy-worktree() {
 }
 
 git:status() {
-  local no_fetch=false arg main_root default_branch main_branch main_dirty counts found=false path branch detached gone
+  local no_fetch=false arg main_root default_branch prs path branch detached pr_line counts gone
+  local -A worktree_of=()
   for arg in "$@"
   do
     case "${arg}" in
@@ -168,22 +207,50 @@ git:status() {
   then
     git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
   fi
-
   main_root=$(git:main-root)
   default_branch=$(git:default-branch)
-  main_branch=$(git -C "${main_root}" rev-parse --abbrev-ref HEAD 2>/dev/null || printf '?')
-  main_dirty=dirty
-  git:clean "${main_root}" && main_dirty=clean
+  prs=$(git:open-prs)
+
   counts=$(git -C "${main_root}" rev-list --left-right --count "HEAD...origin/${default_branch}" 2>/dev/null || printf '0\t0')
-  section "${main_root##*/}  (${main_branch}, ${main_dirty}, ↑${counts%%$'\t'*} ↓${counts##*$'\t'} vs origin/${default_branch})"
+  printf '📋 %s open pull request(s) · %s %s%s, ↑%s ↓%s vs origin/%s\n' \
+    "$(grep --count . <<<"${prs}" || true)" "${main_root##*/}" \
+    "$(git -C "${main_root}" rev-parse --abbrev-ref HEAD 2>/dev/null || printf '?')" \
+    "$(git:clean "${main_root}" || printf ' (dirty)')" "${counts%%$'\t'*}" "${counts##*$'\t'}" "${default_branch}" >&2
 
-  section "worktrees/"
   while IFS=$'\t' read -r path branch detached
   do
-    found=true
-    git:status-block "${path}" "${branch}" "${main_root}" "${default_branch}"
+    [[ -n "${branch}" ]] && worktree_of[${branch}]=${path}
   done < <(git:worktrees)
-  [[ "${found}" == true ]] || ok "none"
+
+  section "pull requests"
+  if [[ -n "${prs}" ]]
+  then
+    while IFS= read -r pr_line
+    do
+      branch=${pr_line%%$'\t'*}
+      if [[ -n "${worktree_of[${branch}]+x}" ]]
+      then
+        git:pr-block "${pr_line}" "${worktree_of[${branch}]}" "${main_root}" "${default_branch}"
+        unset 'worktree_of[${branch}]'
+      else
+        git:pr-block "${pr_line}" "" "${main_root}" "${default_branch}" 2>&1 | sed '$d' >&2
+        printf '   (no worktree here)\n' >&2
+      fi
+    done <<<"${prs}"
+  else
+    ok "none"
+  fi
+
+  section "worktrees with no open pull request"
+  if (( ${#worktree_of[@]} > 0 ))
+  then
+    for branch in "${!worktree_of[@]}"
+    do
+      git:worktree-line "${worktree_of[${branch}]}" "${branch}" "${main_root}" "${default_branch}"
+    done
+  else
+    ok "none"
+  fi
 
   section "branches whose upstream is gone (tidy removes these)"
   gone=$(git:gone-branches)
diff --git a/bin/kit b/bin/kit
index d786a21..87bc9cf 100755
--- a/bin/kit
+++ b/bin/kit
@@ -2,8 +2,9 @@
 # kit - the kit's command: each verb is the executable bin/kit-<verb>.sh beside it (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The release is the directory above bin/. This file resolves it, exports it as kit_root, and hands the verb its
-# arguments. Everything else, the usage text included, lives with the verb.
+# The release is the directory above bin/, found through any symlink this file is reached by, as when Homebrew
+# links it into its own bin. This file resolves it, exports it as kit_root, and hands the verb its arguments.
+# Everything else, the usage text included, lives with the verb.
 #
 # see: .kit/1st.md
 
@@ -15,7 +16,7 @@ then
   exit 1
 fi
 
-kit_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+kit_root=$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)
 export kit_root
 
 verb=${1:-help}
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 40ced66..4a3e181 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -3,8 +3,9 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A file whose digest still matches the manifest, which records the previous release's own content, is replaced.
-# An edited one is three-way merged with the previous release as the base. A path the previous release did not
-# deliver is written only where the repository has nothing, or the same thing, there.
+# An edited one is three-way merged with the previous release as the base, which release:fetch finds or fetches.
+# A path the previous release did not deliver is written only where the repository has nothing, or the same
+# thing, there.
 #
 # see: bin/release.sh
 
@@ -26,20 +27,16 @@ previous=$(release:manifest-version)
 current=$(release:version)
 section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
 
-# The previous release is the base of every merge, and a merge is needed only when the release changed. KIT_BASE
-# names the base's root; otherwise mise knows where it installed it.
+# The previous release is the base of every merge, needed only when the release changed. KIT_BASE names its
+# root; otherwise release:fetch finds or fetches it.
 base_root=""
 # shellcheck disable=SC2154  # release_unreleased is declared by bin/release.sh, which use loaded above
 if [[ -n "${KIT_BASE:-}" ]]
 then
   base_root=${KIT_BASE}
-elif [[ "${previous}" != "${current}" && "${previous}" != "${release_unreleased}" ]] && command -v mise >/dev/null 2>&1
+elif [[ "${previous}" != "${current}" && "${previous}" != "${release_unreleased}" ]]
 then
-  base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
-  if [[ -z "${base_root}" ]] && mise install --quiet "github:empowerite/kit@${previous}" 2>/dev/null
-  then
-    base_root=$(mise where "github:empowerite/kit@${previous}" 2>/dev/null || true)
-  fi
+  base_root=$(release:fetch "${previous}" || true)
 fi
 needs_base=false
 [[ "${previous}" != "${current}" ]] && needs_base=true
@@ -69,7 +66,7 @@ do
   if [[ "${needs_base}" == true && -z "${base}" ]]
   then
     # Without the base, neither a merge nor the removal of the previous release's entries is possible.
-    error "${path} cannot be updated without the base release ${previous}; run: mise install github:empowerite/kit@${previous}"
+    error "${path} cannot be updated without the base release ${previous}; set KIT_BASE to a copy of it"
     conflicts=$(( conflicts + 1 ))
     continue
   fi
diff --git a/bin/release.sh b/bin/release.sh
index 36be28c..5be9ee4 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -83,6 +83,38 @@ release:require-targets() {
 
 release:merged() { [[ "$1" == *.json ]]; }
 
+# release:fetch <version> prints the root of that release, fetching it if need be: the kit's cache first, then a
+# mise install if mise is here, then the GitHub release itself, unpacked into the cache. Nothing here assumes how
+# this release was installed.
+release:fetch() {
+  local version=$1 root cache
+  cache="${XDG_CACHE_HOME:-${HOME}/.cache}/kit/kit-${version}"
+  if [[ -x "${cache}/bin/kit" ]]
+  then
+    printf '%s\n' "${cache}"
+    return 0
+  fi
+  if command -v mise >/dev/null 2>&1
+  then
+    root=$(mise where "github:empowerite/kit@${version}" 2>/dev/null || true)
+    if [[ -x "${root}/bin/kit" ]]
+    then
+      printf '%s\n' "${root}"
+      return 0
+    fi
+  fi
+  step "Fetching kit ${version} from its GitHub release"
+  mkdir -p "${cache}"
+  if ! gh release download "v${version}" --repo empowerite/kit --pattern "kit-${version}.tar.gz" --output - 2>/dev/null \
+    | tar --extract --gzip --directory "${cache}" --strip-components 1
+  then
+    rm -rf "${cache}"
+    error "kit ${version} could not be fetched (run: gh auth status, or set KIT_BASE to a copy of it)"
+    return 1
+  fi
+  printf '%s\n' "${cache}"
+}
+
 # release:among <name> <name>… is true when the first name is among the rest.
 release:among() {
   local needle=$1 item

From 84b066adee3523dd65323d3ee43b52165ab75f1f Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 09:51:48 -0700
Subject: [PATCH 051/108] #1 README.md: why the kit exists, and three ways to
 install it

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 84 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 59 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index ceff989..4664520 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,61 @@
 # empowerite/kit: **k**eep **i**t **t**rustworthy
 
-kit is the agentic guardrails a repository takes as a versioned mixin: the policy text an agent reads first, the
-rules that bind each kind of file, the guard that keeps `main` as the human's desk, and the one command no harness
-provides, the issue-to-worktree on-ramp. A tag on `main` publishes a release. A consumer pins it in `mise.toml`,
-installs it with `kit install`, and keeps rules of its own beside it. The design is
-[#1](https://github.com/empowerite/kit/issues/1), and the entry file every agent reads is [.kit/1st.md](.kit/1st.md).
+Do you trust your agents? They were trained on the whole of what people have written, and that includes every
+shortcut anyone ever took: the "done" that was not, the test that was skipped and reported as passing, the rebase
+that quietly rewrote a colleague's branch. An agent is a tireless new colleague who has read everything and holds
+none of your house rules, unless you put them where it looks.
 
-## Take the kit
+kit is the house rules, put where agents look, as a versioned release any repository can take and keep taking.
+It is small on purpose: the text an agent reads first, a rule file per kind of file, a guard that keeps `main` as
+the human's desk, and the one command no harness provides, which turns an issue into a worktree with a draft pull
+request. A tag on `main` publishes a release. A repository pins it, installs it, and keeps rules of its own
+beside it. The design is [#1](https://github.com/empowerite/kit/issues/1), and the entry file every agent reads is
+[.kit/1st.md](.kit/1st.md).
+
+## Why a release, and not a copy
+
+A copy drifts. Six repositories with six copies of the same rules have six sets of rules within a month, and no
+one can say which is current. A release is pinned, so a repository knows which rules bind it; updated, so a
+change to the rules reaches every repository as a pull request that bumps a version; and checked, so `kit check`
+fails the build when a delivered file was edited in place. The rules a repository adds live beside the delivered
+ones, in its own files, and survive every update.
+
+## Install
+
+The `kit` command is a release: a tarball holding `bin/`, `tree/`, and `targets/`. Take it whichever way the
+repository takes its other tools.
 
-Pin a release in `mise.toml`, install it, and point `AGENTS.md` at it:
+With mise, pin it in `mise.toml` and the version is part of the repository:
 
 ```toml
 [tools]
 "github:empowerite/kit" = "0.1.0"
 ```
 
+With Homebrew, from the empowerite tap:
+
+```sh
+brew install empowerite/tap/kit
+```
+
+Or by hand, with the version in `version`: unpack the release and put its `bin/` on `PATH`:
+
+```sh
+curl --location --output "kit-${version}.tar.gz" \
+  "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz"
+tar --extract --gzip --file "kit-${version}.tar.gz"
+export PATH="${PWD}/kit-${version}/bin:${PATH}"
+```
+
+The kit needs bash 4.4 or later, git, `gh`, and `jq`. macOS ships bash 3.2, and `brew install bash` gives a
+current one. With mise, an exact pin installs the minute a release exists; a range pin sees a new kit a day after
+it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:empowerite/kit"]`.
+
+## Take the kit
+
+In the repository, install it and point `AGENTS.md` at it:
+
 ```sh
-mise install
 kit install claude
 ```
 
@@ -29,26 +68,20 @@ Read .kit/1st.md first.
 The rest of `AGENTS.md` is yours. `install` writes `.kit/`, the CI workflow, and the files of each target named;
 `claude` is the one target this release knows, and a repository with no target still binds every agent that
 reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the root justfile for the delivered `CI` job to
-run, and take the pre-commit linters by pinning `lefthook` in `mise.desk.toml`, putting
-`extends: [.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit target
-add`, `kit target remove`, and `kit target list` change and show the targets later.
-
-An exact pin installs the minute a release exists. A range pin sees a new kit a day after it ships unless
-`[settings]` carries `minimum_release_age_excludes = ["github:empowerite/kit"]`.
-
-To move to a new release, bump the pin, run `mise install`, then `kit update`: a delivered file you left alone is
-replaced, one you edited is three-way merged with the previous release as the base, and your own deny entries
-and settings keys stay. `kit check` fails, locally and in `CI`, when a delivered file differs from the pinned
-release.
+run, and take the pre-commit linters by pinning `lefthook`, putting `extends: [.kit/lefthook.yml]` in
+`lefthook.yml`, and running `lefthook install` once per clone. `kit target add`, `kit target remove`, and
+`kit target list` change and show the targets later.
 
-The kit needs bash 4.4 or later, git, `gh`, and `jq`; macOS ships bash 3.2, and `brew install bash` gives a
-current one. The `kit` command and the bash behind its verbs stay in the release where mise installed it; the
-repository carries the text an agent reads and the record of what it took.
+To move to a new release, bump the pin or reinstall, then run `kit update`: a delivered file you left alone is
+replaced, one you edited is three-way merged with the previous release as the base, which `update` fetches from
+GitHub if it is not already on the machine, and your own deny entries and settings keys stay. `kit check` fails,
+locally and in `CI`, when a delivered file differs from the pinned release.
 
 ## Setup
 
-Every commit is signed, and the branch ruleset refuses one that is not. If you have no signing key GitHub
-verifies, make one and register it, following [generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
+This repository uses its own kit, and its tools come from mise. Every commit is signed, and the branch ruleset
+refuses one that is not. If you have no signing key GitHub verifies, make one and register it, following
+[generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
 and [adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account).
 Then, once per clone, with the key's id in `signing_key`:
 
@@ -72,7 +105,8 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 - `kit issue <N>` makes `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a
   draft pull request. It never switches the checkout it runs from.
 - Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`. `kit rebase`
-  brings the branch up to date with `main` and pushes it.
+  brings the branch up to date with `main` and pushes it, and `kit status` shows every pull request in flight
+  and the worktree it is written in.
 - `just ci` is the gate; the justfile says what it runs.
 - `gh pr ready` says the work is done, and the pull request body is the report.
 - A human merges. `kit tidy` then removes the worktree and its branch.

From 9e7e3183120c9af6b23b0a10520876a2d88bb59d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 09:53:46 -0700
Subject: [PATCH 052/108] #1 bin/release.sh: a fetched version is held to a
 version's shape, and unpacked before it is placed

The version release:fetch builds a path from comes out of a manifest, which is repository content. It is now refused unless it has a version's shape, and the tarball is unpacked into a directory made here and moved into the cache only when whole, so nothing is ever removed outside what this function made.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/release.sh | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/bin/release.sh b/bin/release.sh
index 5be9ee4..755453a 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -87,7 +87,14 @@ release:merged() { [[ "$1" == *.json ]]; }
 # mise install if mise is here, then the GitHub release itself, unpacked into the cache. Nothing here assumes how
 # this release was installed.
 release:fetch() {
-  local version=$1 root cache
+  local version=$1 root cache fresh
+  # The version comes from a manifest, which is repository content, so it is held to a version's shape before it
+  # becomes part of a path; the unpack goes into a directory made here and is moved into place only when whole.
+  if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
+  then
+    error "'${version}' is not a kit version"
+    return 1
+  fi
   cache="${XDG_CACHE_HOME:-${HOME}/.cache}/kit/kit-${version}"
   if [[ -x "${cache}/bin/kit" ]]
   then
@@ -104,14 +111,16 @@ release:fetch() {
     fi
   fi
   step "Fetching kit ${version} from its GitHub release"
-  mkdir -p "${cache}"
+  fresh=$(mktemp -d)
   if ! gh release download "v${version}" --repo empowerite/kit --pattern "kit-${version}.tar.gz" --output - 2>/dev/null \
-    | tar --extract --gzip --directory "${cache}" --strip-components 1
+    | tar --extract --gzip --directory "${fresh}" --strip-components 1
   then
-    rm -rf "${cache}"
+    rm -rf "${fresh}"
     error "kit ${version} could not be fetched (run: gh auth status, or set KIT_BASE to a copy of it)"
     return 1
   fi
+  mkdir -p "$(dirname "${cache}")"
+  mv "${fresh}" "${cache}"
   printf '%s\n' "${cache}"
 }
 

From 9d3b77ac14d2b089a2cde1b81a4d6b0b7774d8e9 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 10:04:09 -0700
Subject: [PATCH 053/108] #1 bin/git.sh: kit status in the dashboard's shape

One GraphQL request fetches the open pull requests with the issues they close and their latest
commit's checks. Each pull request prints its full title in a name column sized across every row,
then its state, age, and checks; under it the linked issues and up to ten commits with dim hashes,
and its worktree with colored ahead, behind, and diff counts. Worktrees with no pull request are
rows in the same table.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/git.sh | 199 +++++++++++++++++++++++++++++++----------------------
 1 file changed, 118 insertions(+), 81 deletions(-)

diff --git a/bin/git.sh b/bin/git.sh
index 3f8c0e7..7f8a509 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -74,68 +74,111 @@ git:clean() {
   [[ -z "$(git -C "$1" status --porcelain 2>/dev/null)" ]]
 }
 
-# git:open-prs prints one line per open pull request: "<branch>\t<number>\t<Draft|Ready>\t<age in days>\t<checks>\t<title>",
-# where <checks> is "✅ n/n", "❌ k/n", "⏳ n", or "·" for none. One request, for the whole picture.
+# git:open-prs prints one record per open pull request, fields separated by tabs: branch, number, Draft or
+# Ready, age in days, checks, title, and the issues it closes as "number:title" joined by unit separators.
 git:open-prs() {
+  local repo query filter
+  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || return 0
+  # shellcheck disable=SC2016  # GraphQL variables, and a jq filter with jq variables
+  query='query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      pullRequests(states: OPEN, first: 50, orderBy: {field: CREATED_AT, direction: ASC}) {
+        nodes {
+          number title isDraft headRefName createdAt
+          closingIssuesReferences(first: 10) { nodes { number title } }
+          commits(last: 1) { nodes { commit { statusCheckRollup { contexts(first: 100) { nodes {
+            ... on CheckRun { conclusion status }
+            ... on StatusContext { state }
+          } } } } } }
+        }
+      }
+    }
+  }'
   # shellcheck disable=SC2016  # a jq filter, with jq variables
-  gh pr list --state open --limit 100 --json number,title,isDraft,headRefName,createdAt,statusCheckRollup --jq '
-    .[] | [
+  filter='
+    .data.repository.pullRequests.nodes[] | [
       .headRefName,
       (.number | tostring),
       (if .isDraft then "Draft" else "Ready" end),
       (((now - (.createdAt | fromdateiso8601)) / 86400 | floor | tostring) + "d"),
-      ((.statusCheckRollup // []) as $c
+      ((.commits.nodes[0].commit.statusCheckRollup.contexts.nodes // []) as $c
         | ($c | length) as $n
-        | ([$c[] | select(.conclusion == "SUCCESS")] | length) as $ok
-        | ([$c[] | select(.conclusion != null and .conclusion != "SUCCESS" and .conclusion != "SKIPPED" and .conclusion != "NEUTRAL")] | length) as $bad
+        | ([$c[] | select(.conclusion == "SUCCESS" or .state == "SUCCESS")] | length) as $ok
+        | ([$c[] | select((.conclusion // .state // "") as $r | $r == "FAILURE" or $r == "ERROR" or $r == "TIMED_OUT" or $r == "CANCELLED" or $r == "ACTION_REQUIRED" or $r == "STARTUP_FAILURE")] | length) as $bad
         | if $n == 0 then "·"
-          elif $bad > 0 then "❌ \($bad)/\($n)"
-          elif $ok == $n then "✅ \($n)/\($n)"
-          else "⏳ \($n - $ok)/\($n)" end),
-      .title
-    ] | @tsv' 2>/dev/null || true
+          elif $bad > 0 then "❌ \($n - $bad) / \($n)"
+          elif $ok == $n then "✅ \($n) / \($n)"
+          else "⏳ \($ok) / \($n)" end),
+      .title,
+      ([.closingIssuesReferences.nodes[] | "\(.number):\(.title)"] | join("\u001f"))
+    ] | @tsv'
+  gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
+    2>/dev/null || true
 }
 
-# git:short <text> [<width>] prints <text> cut to <width> columns, 16 by default, with an ellipsis when cut.
-git:short() {
-  local text=$1 width=${2:-16}
-  if (( ${#text} > width ))
-  then
-    printf '%s…\n' "${text:0:width-1}"
-  else
-    printf '%s\n' "${text}"
-  fi
+# git:pad <text> <width> prints <text> padded with spaces to <width> characters, counted as characters.
+git:pad() {
+  local text=$1 width=$2
+  printf '%s' "${text}"
+  (( ${#text} < width )) && printf '%*s' $(( width - ${#text} )) ''
+  return 0
 }
 
-# git:worktree-line <path> <branch> <main-root> <default-branch> prints the 🌿 line: the worktree's path, how far
-# its branch is ahead of and behind the default branch, and the size of its diff.
-git:worktree-line() {
-  local path=$1 branch=$2 main_root=$3 default_branch=$4 counts="0\t0" stat added=0 removed=0 dirty=""
-  if [[ -n "${branch}" ]]
-  then
-    counts=$(git rev-list --left-right --count "${branch}...origin/${default_branch}" 2>/dev/null || printf '0\t0')
-    stat=$(git diff --shortstat "origin/${default_branch}...${branch}" 2>/dev/null || true)
-    [[ "${stat}" =~ ([0-9]+)\ insertion ]] && added=${BASH_REMATCH[1]}
-    [[ "${stat}" =~ ([0-9]+)\ deletion ]] && removed=${BASH_REMATCH[1]}
-  fi
-  git:clean "${path}" || dirty=" · $(git -C "${path}" status --porcelain | grep --count .) uncommitted"
-  printf '   🌿 %s   ↑%s ↓%s · +%s -%s%s\n' "$(git:short "${path#"${main_root}"/}" 40)" "${counts%%$'\t'*}" "${counts##*$'\t'}" "${added}" "${removed}" "${dirty}" >&2
+# git:dim, git:red, git:green wrap a text in a color when stderr is a terminal.
+git:dim()   { printf '%s%s%s' "$(out:sgr 90)" "$*" "$(out:sgr 0)"; }
+git:red()   { printf '%s%s%s' "$(out:sgr 31)" "$*" "$(out:sgr 0)"; }
+git:green() { printf '%s%s%s' "$(out:sgr 32)" "$*" "$(out:sgr 0)"; }
+
+# git:divergence <branch> <default-branch> prints "↑a ↓b · +ins -del", colored, for the branch against origin.
+git:divergence() {
+  local branch=$1 default_branch=$2 counts stat added=0 removed=0
+  counts=$(git rev-list --left-right --count "${branch}...origin/${default_branch}" 2>/dev/null || printf '0\t0')
+  stat=$(git diff --shortstat "origin/${default_branch}...${branch}" 2>/dev/null || true)
+  [[ "${stat}" =~ ([0-9]+)\ insertion ]] && added=${BASH_REMATCH[1]}
+  [[ "${stat}" =~ ([0-9]+)\ deletion ]] && removed=${BASH_REMATCH[1]}
+  printf '%s %s · %s %s' "$(git:green "↑${counts%%$'\t'*}")" "$(git:red "↓${counts##*$'\t'}")" \
+    "$(git:green "+${added}")" "$(git:red "-${removed}")"
 }
 
-# git:pr-block <pr-line> <path> <main-root> <default-branch> prints one pull request: its line, the commits it
-# carries over the default branch, up to ten, and its worktree's line.
+# git:pr-block <record> <path> <main-root> <default-branch> <width> prints one pull request: its line, the issues
+# it closes, up to ten of the commits it carries over the default branch, and its worktree's line.
 git:pr-block() {
-  local branch number state age checks title path=$2 main_root=$3 default_branch=$4 shown=0 total line
-  IFS=$'\t' read -r branch number state age checks title <<<"$1"
-  printf '🔀 #%s %-17s %-6s %4s   %s\n' "${number}" "$(git:short "${title}")" "${state}" "${age}" "${checks}" >&2
+  local branch number state age checks title issues path=$2 main_root=$3 default_branch=$4 width=$5
+  local total shown=0 line issue colored
+  IFS=$'\t' read -r branch number state age checks title issues <<<"$1"
+  if [[ "${state}" == Draft ]]
+  then
+    colored=$(git:dim "draft")
+  else
+    colored=$(git:green "ready")
+  fi
+  printf '🔀 %s   %s   %4s   %s\n' "$(git:pad "#${number} ${title}" "${width}")" "${colored}" "${age}" "${checks}" >&2
+  if [[ -n "${issues}" ]]
+  then
+    while IFS= read -r issue
+    do
+      printf '   %s\n' "$(git:dim "#${issue%%:*} ${issue#*:}")" >&2
+    done < <(tr '\037' '\n' <<<"${issues}")
+  fi
   total=$(git rev-list --count "origin/${default_branch}..${branch}" 2>/dev/null || printf 0)
   while IFS= read -r line
   do
-    printf '   %s\n' "${line}" >&2
+    printf '   %s %s\n' "$(git:dim "${line%% *}")" "${line#* }" >&2
     (( ++shown ))
   done < <(git log --format='%h %s' --max-count 10 "origin/${default_branch}..${branch}" 2>/dev/null)
-  (( total > shown )) && printf '   … and %s more\n' "$(( total - shown ))" >&2
-  git:worktree-line "${path}" "${branch}" "${main_root}" "${default_branch}"
+  (( total > shown )) && printf '   %s\n' "$(git:dim "… and $(( total - shown )) more")" >&2
+  if [[ -n "${path}" ]]
+  then
+    printf '   🌿 %s   %s%s\n' "$(git:dim "${path#"${main_root}"/}")" "$(git:divergence "${branch}" "${default_branch}")" "$(git:uncommitted "${path}")" >&2
+  else
+    printf '   %s\n' "$(git:dim "no worktree here")" >&2
+  fi
+}
+
+# git:uncommitted <path> prints " · n uncommitted" for a dirty checkout, nothing for a clean one.
+git:uncommitted() {
+  git:clean "$1" && return 0
+  printf ' · %s' "$(git:red "$(git -C "$1" status --porcelain | grep --count .) uncommitted")"
 }
 
 # git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides one worktree and
@@ -190,7 +233,7 @@ git:tidy-worktree() {
 }
 
 git:status() {
-  local no_fetch=false arg main_root default_branch prs path branch detached pr_line counts gone
+  local no_fetch=false arg main_root default_branch prs path branch detached record width=40 text drafts total gone
   local -A worktree_of=()
   for arg in "$@"
   do
@@ -210,58 +253,52 @@ git:status() {
   main_root=$(git:main-root)
   default_branch=$(git:default-branch)
   prs=$(git:open-prs)
-
-  counts=$(git -C "${main_root}" rev-list --left-right --count "HEAD...origin/${default_branch}" 2>/dev/null || printf '0\t0')
-  printf '📋 %s open pull request(s) · %s %s%s, ↑%s ↓%s vs origin/%s\n' \
-    "$(grep --count . <<<"${prs}" || true)" "${main_root##*/}" \
-    "$(git -C "${main_root}" rev-parse --abbrev-ref HEAD 2>/dev/null || printf '?')" \
-    "$(git:clean "${main_root}" || printf ' (dirty)')" "${counts%%$'\t'*}" "${counts##*$'\t'}" "${default_branch}" >&2
-
   while IFS=$'\t' read -r path branch detached
   do
     [[ -n "${branch}" ]] && worktree_of[${branch}]=${path}
   done < <(git:worktrees)
 
-  section "pull requests"
-  if [[ -n "${prs}" ]]
-  then
-    while IFS= read -r pr_line
-    do
-      branch=${pr_line%%$'\t'*}
-      if [[ -n "${worktree_of[${branch}]+x}" ]]
-      then
-        git:pr-block "${pr_line}" "${worktree_of[${branch}]}" "${main_root}" "${default_branch}"
-        unset 'worktree_of[${branch}]'
-      else
-        git:pr-block "${pr_line}" "" "${main_root}" "${default_branch}" 2>&1 | sed '$d' >&2
-        printf '   (no worktree here)\n' >&2
-      fi
-    done <<<"${prs}"
-  else
-    ok "none"
-  fi
+  # The name column is as wide as the widest name, within what the terminal allows beside the other columns.
+  while IFS=$'\t' read -r branch text _
+  do
+    [[ -n "${branch}" ]] || continue
+    text="#${text}"
+    (( ${#text} > width )) && width=${#text}
+  done < <(awk -F '\t' '{ print $1 "\t" $2 " " $6 }' <<<"${prs}")
+  for branch in "${!worktree_of[@]}"
+  do
+    text=${worktree_of[${branch}]#"${main_root}"/}
+    (( ${#text} > width )) && width=${#text}
+  done
+  (( width > $(tput cols 2>/dev/null || echo 160) - 40 )) && width=$(( $(tput cols 2>/dev/null || echo 160) - 40 ))
 
-  section "worktrees with no open pull request"
-  if (( ${#worktree_of[@]} > 0 ))
-  then
-    for branch in "${!worktree_of[@]}"
-    do
-      git:worktree-line "${worktree_of[${branch}]}" "${branch}" "${main_root}" "${default_branch}"
-    done
-  else
-    ok "none"
-  fi
+  drafts=$(awk -F '\t' '$3 == "Draft"' <<<"${prs}" | grep --count . || true)
+  total=$(grep --count . <<<"${prs}" || true)
+  printf '📋 %s open pull request(s) · %s draft · %s ready\n' "${total}" "${drafts}" "$(( total - drafts ))" >&2
+  section "worktrees"
+  while IFS= read -r record
+  do
+    [[ -n "${record}" ]] || continue
+    branch=${record%%$'\t'*}
+    git:pr-block "${record}" "${worktree_of[${branch}]:-}" "${main_root}" "${default_branch}" "${width}"
+    unset 'worktree_of[${branch}]'
+  done <<<"${prs}"
+  for branch in $(printf '%s\n' "${!worktree_of[@]}" | sort)
+  do
+    path=${worktree_of[${branch}]}
+    printf '🌿 %s   %s   %s%s\n' "$(git:pad "${path#"${main_root}"/}" "${width}")" "$(git:dim 'no open pull request')" \
+      "$(git:divergence "${branch}" "${default_branch}")" "$(git:uncommitted "${path}")" >&2
+  done
+  [[ -n "${prs}" || ${#worktree_of[@]} -gt 0 ]] || ok "none"
 
-  section "branches whose upstream is gone (tidy removes these)"
   gone=$(git:gone-branches)
   if [[ -n "${gone}" ]]
   then
+    section "branches whose upstream is gone (tidy removes these)"
     while IFS= read -r branch
     do
       info "${branch}"
     done <<<"${gone}"
-  else
-    ok "none"
   fi
 }
 

From c3ce1012bf7c69c942ba2b2d6aacddc80e36570d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 10:24:53 -0700
Subject: [PATCH 054/108] #1 bin/status.sh: kit status drawn the way
 enchiridion's dashboard is

The rendering moves out of git.sh into its own module. One GraphQL request brings every open pull
request with the issues it closes, its review threads, and the checks on its head. Each pull request
is classified into one of eight states, in the dashboard's order, and drawn with that state's glyph
and its family's color: green for ready, yellow for a decision a human owes, blue for waiting, dim
for a draft. The check cell says how many checks passed and how long the run took, or which check
failed. Commits are listed past the branch's fork from main, with the middle elided and the oldest
kept; ahead, behind, and line counts are measured from the same fork, bold green and red when
non-zero and dim at zero. Worktrees with no pull request are rows in the same table, by issue
number, and a detached one is marked. The column widths are measured over every row and clipped to
the terminal. Four bats cases cover the cell, the commit list, and the worktree rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/git.sh        | 182 -------------------
 bin/kit-status.sh |   6 +-
 bin/status.sh     | 436 ++++++++++++++++++++++++++++++++++++++++++++++
 tests/status.bats |  65 +++++++
 4 files changed, 504 insertions(+), 185 deletions(-)
 create mode 100644 bin/status.sh
 create mode 100644 tests/status.bats

diff --git a/bin/git.sh b/bin/git.sh
index 7f8a509..4dd85e6 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -2,11 +2,6 @@
 # git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# git:status [--no-fetch] draws the picture of the work in flight: the open pull requests, and under each its
-# state, age, checks, the commits it carries, and the worktree it is written in, with how far that is ahead of and
-# behind the default branch and the size of its diff; then the worktrees with no pull request; then the local
-# branches whose upstream is gone. It changes nothing, and asks GitHub once.
-#
 # git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
 # detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
 # every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a
@@ -74,113 +69,6 @@ git:clean() {
   [[ -z "$(git -C "$1" status --porcelain 2>/dev/null)" ]]
 }
 
-# git:open-prs prints one record per open pull request, fields separated by tabs: branch, number, Draft or
-# Ready, age in days, checks, title, and the issues it closes as "number:title" joined by unit separators.
-git:open-prs() {
-  local repo query filter
-  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || return 0
-  # shellcheck disable=SC2016  # GraphQL variables, and a jq filter with jq variables
-  query='query($owner: String!, $name: String!) {
-    repository(owner: $owner, name: $name) {
-      pullRequests(states: OPEN, first: 50, orderBy: {field: CREATED_AT, direction: ASC}) {
-        nodes {
-          number title isDraft headRefName createdAt
-          closingIssuesReferences(first: 10) { nodes { number title } }
-          commits(last: 1) { nodes { commit { statusCheckRollup { contexts(first: 100) { nodes {
-            ... on CheckRun { conclusion status }
-            ... on StatusContext { state }
-          } } } } } }
-        }
-      }
-    }
-  }'
-  # shellcheck disable=SC2016  # a jq filter, with jq variables
-  filter='
-    .data.repository.pullRequests.nodes[] | [
-      .headRefName,
-      (.number | tostring),
-      (if .isDraft then "Draft" else "Ready" end),
-      (((now - (.createdAt | fromdateiso8601)) / 86400 | floor | tostring) + "d"),
-      ((.commits.nodes[0].commit.statusCheckRollup.contexts.nodes // []) as $c
-        | ($c | length) as $n
-        | ([$c[] | select(.conclusion == "SUCCESS" or .state == "SUCCESS")] | length) as $ok
-        | ([$c[] | select((.conclusion // .state // "") as $r | $r == "FAILURE" or $r == "ERROR" or $r == "TIMED_OUT" or $r == "CANCELLED" or $r == "ACTION_REQUIRED" or $r == "STARTUP_FAILURE")] | length) as $bad
-        | if $n == 0 then "·"
-          elif $bad > 0 then "❌ \($n - $bad) / \($n)"
-          elif $ok == $n then "✅ \($n) / \($n)"
-          else "⏳ \($ok) / \($n)" end),
-      .title,
-      ([.closingIssuesReferences.nodes[] | "\(.number):\(.title)"] | join("\u001f"))
-    ] | @tsv'
-  gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
-    2>/dev/null || true
-}
-
-# git:pad <text> <width> prints <text> padded with spaces to <width> characters, counted as characters.
-git:pad() {
-  local text=$1 width=$2
-  printf '%s' "${text}"
-  (( ${#text} < width )) && printf '%*s' $(( width - ${#text} )) ''
-  return 0
-}
-
-# git:dim, git:red, git:green wrap a text in a color when stderr is a terminal.
-git:dim()   { printf '%s%s%s' "$(out:sgr 90)" "$*" "$(out:sgr 0)"; }
-git:red()   { printf '%s%s%s' "$(out:sgr 31)" "$*" "$(out:sgr 0)"; }
-git:green() { printf '%s%s%s' "$(out:sgr 32)" "$*" "$(out:sgr 0)"; }
-
-# git:divergence <branch> <default-branch> prints "↑a ↓b · +ins -del", colored, for the branch against origin.
-git:divergence() {
-  local branch=$1 default_branch=$2 counts stat added=0 removed=0
-  counts=$(git rev-list --left-right --count "${branch}...origin/${default_branch}" 2>/dev/null || printf '0\t0')
-  stat=$(git diff --shortstat "origin/${default_branch}...${branch}" 2>/dev/null || true)
-  [[ "${stat}" =~ ([0-9]+)\ insertion ]] && added=${BASH_REMATCH[1]}
-  [[ "${stat}" =~ ([0-9]+)\ deletion ]] && removed=${BASH_REMATCH[1]}
-  printf '%s %s · %s %s' "$(git:green "↑${counts%%$'\t'*}")" "$(git:red "↓${counts##*$'\t'}")" \
-    "$(git:green "+${added}")" "$(git:red "-${removed}")"
-}
-
-# git:pr-block <record> <path> <main-root> <default-branch> <width> prints one pull request: its line, the issues
-# it closes, up to ten of the commits it carries over the default branch, and its worktree's line.
-git:pr-block() {
-  local branch number state age checks title issues path=$2 main_root=$3 default_branch=$4 width=$5
-  local total shown=0 line issue colored
-  IFS=$'\t' read -r branch number state age checks title issues <<<"$1"
-  if [[ "${state}" == Draft ]]
-  then
-    colored=$(git:dim "draft")
-  else
-    colored=$(git:green "ready")
-  fi
-  printf '🔀 %s   %s   %4s   %s\n' "$(git:pad "#${number} ${title}" "${width}")" "${colored}" "${age}" "${checks}" >&2
-  if [[ -n "${issues}" ]]
-  then
-    while IFS= read -r issue
-    do
-      printf '   %s\n' "$(git:dim "#${issue%%:*} ${issue#*:}")" >&2
-    done < <(tr '\037' '\n' <<<"${issues}")
-  fi
-  total=$(git rev-list --count "origin/${default_branch}..${branch}" 2>/dev/null || printf 0)
-  while IFS= read -r line
-  do
-    printf '   %s %s\n' "$(git:dim "${line%% *}")" "${line#* }" >&2
-    (( ++shown ))
-  done < <(git log --format='%h %s' --max-count 10 "origin/${default_branch}..${branch}" 2>/dev/null)
-  (( total > shown )) && printf '   %s\n' "$(git:dim "… and $(( total - shown )) more")" >&2
-  if [[ -n "${path}" ]]
-  then
-    printf '   🌿 %s   %s%s\n' "$(git:dim "${path#"${main_root}"/}")" "$(git:divergence "${branch}" "${default_branch}")" "$(git:uncommitted "${path}")" >&2
-  else
-    printf '   %s\n' "$(git:dim "no worktree here")" >&2
-  fi
-}
-
-# git:uncommitted <path> prints " · n uncommitted" for a dirty checkout, nothing for a clean one.
-git:uncommitted() {
-  git:clean "$1" && return 0
-  printf ' · %s' "$(git:red "$(git -C "$1" status --porcelain | grep --count .) uncommitted")"
-}
-
 # git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides one worktree and
 # says why. It returns 0 when the worktree was removed, or would be under a dry run, and 1 when it is kept.
 git:tidy-worktree() {
@@ -232,76 +120,6 @@ git:tidy-worktree() {
   esac
 }
 
-git:status() {
-  local no_fetch=false arg main_root default_branch prs path branch detached record width=40 text drafts total gone
-  local -A worktree_of=()
-  for arg in "$@"
-  do
-    case "${arg}" in
-      (--no-fetch)
-        no_fetch=true
-        ;;
-      (*)
-        error "unknown flag '${arg}' (only --no-fetch is recognized)"
-        return 2
-    esac
-  done
-  if [[ "${no_fetch}" != true ]]
-  then
-    git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
-  fi
-  main_root=$(git:main-root)
-  default_branch=$(git:default-branch)
-  prs=$(git:open-prs)
-  while IFS=$'\t' read -r path branch detached
-  do
-    [[ -n "${branch}" ]] && worktree_of[${branch}]=${path}
-  done < <(git:worktrees)
-
-  # The name column is as wide as the widest name, within what the terminal allows beside the other columns.
-  while IFS=$'\t' read -r branch text _
-  do
-    [[ -n "${branch}" ]] || continue
-    text="#${text}"
-    (( ${#text} > width )) && width=${#text}
-  done < <(awk -F '\t' '{ print $1 "\t" $2 " " $6 }' <<<"${prs}")
-  for branch in "${!worktree_of[@]}"
-  do
-    text=${worktree_of[${branch}]#"${main_root}"/}
-    (( ${#text} > width )) && width=${#text}
-  done
-  (( width > $(tput cols 2>/dev/null || echo 160) - 40 )) && width=$(( $(tput cols 2>/dev/null || echo 160) - 40 ))
-
-  drafts=$(awk -F '\t' '$3 == "Draft"' <<<"${prs}" | grep --count . || true)
-  total=$(grep --count . <<<"${prs}" || true)
-  printf '📋 %s open pull request(s) · %s draft · %s ready\n' "${total}" "${drafts}" "$(( total - drafts ))" >&2
-  section "worktrees"
-  while IFS= read -r record
-  do
-    [[ -n "${record}" ]] || continue
-    branch=${record%%$'\t'*}
-    git:pr-block "${record}" "${worktree_of[${branch}]:-}" "${main_root}" "${default_branch}" "${width}"
-    unset 'worktree_of[${branch}]'
-  done <<<"${prs}"
-  for branch in $(printf '%s\n' "${!worktree_of[@]}" | sort)
-  do
-    path=${worktree_of[${branch}]}
-    printf '🌿 %s   %s   %s%s\n' "$(git:pad "${path#"${main_root}"/}" "${width}")" "$(git:dim 'no open pull request')" \
-      "$(git:divergence "${branch}" "${default_branch}")" "$(git:uncommitted "${path}")" >&2
-  done
-  [[ -n "${prs}" || ${#worktree_of[@]} -gt 0 ]] || ok "none"
-
-  gone=$(git:gone-branches)
-  if [[ -n "${gone}" ]]
-  then
-    section "branches whose upstream is gone (tidy removes these)"
-    while IFS= read -r branch
-    do
-      info "${branch}"
-    done <<<"${gone}"
-  fi
-}
-
 git:tidy() {
   local dry_run=false flag repo default_branch self_root found=false path branch detached
   local removed_worktrees=0 removed_branches=0 checked_out
diff --git a/bin/kit-status.sh b/bin/kit-status.sh
index ac38f9b..a0c04a3 100755
--- a/bin/kit-status.sh
+++ b/bin/kit-status.sh
@@ -2,12 +2,12 @@
 # kit-status - show every worktree with its branch, pull request, and state (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# see: bin/git.sh
+# see: bin/status.sh
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use git
+use status
 
 if [[ "${1:-}" == --help ]]
 then
@@ -15,6 +15,6 @@ then
   exit 0
 fi
 
-git:status "$@"
+status:render "$@"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/status.sh b/bin/status.sh
new file mode 100644
index 0000000..6a00ba6
--- /dev/null
+++ b/bin/status.sh
@@ -0,0 +1,436 @@
+# shellcheck shell=bash
+# status.sh - the picture of the work in flight (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# status:render [--no-fetch] prints the open pull requests and the linked worktrees, and changes nothing. It asks
+# GitHub once, for every open pull request with the issues it closes, its review threads, and the checks on its
+# head; everything else is a local git read.
+#
+# The picture is a headline counting the pull requests by state, then three sections, each omitted when empty:
+#
+#   worktrees      — every pull request written in a worktree under worktrees/, then the worktrees with no pull
+#                    request. A pull request's block is its row, the issues it closes, up to ten of the commits it
+#                    carries past its fork from the default branch, and its worktree with how far that has moved
+#                    from the fork and the size of its diff.
+#   pull requests  — every open pull request with no worktree here, the same block without the worktree.
+#   gone branches  — every local branch whose upstream is gone, which kit tidy removes.
+#
+# A row is the title, the state with its glyph, the age, and the checks. Every state has its own glyph, so a row is
+# recognizable without reading the token. Color is by family, never by state: green when nothing is left to decide,
+# yellow when a human owes a decision, blue when the next move is a machine's or a reviewer's, dim when someone
+# already owns the work. The state is the first of these that holds:
+#
+#   draft              🔨  dim     unfinished work that belongs to someone
+#   queued             🚦  blue    a check is still running
+#   conflicted         💥  yellow  the branch does not apply cleanly to the default branch
+#   failing:gate       🔥  yellow  a check failed; the row names which
+#   no-check           📭  blue    nothing has reported on its head
+#   comments:open      💬  yellow  unresolved review threads
+#   blocked:approval   👀  blue    a review is required or requested and has not arrived
+#   ready              🛬  green   green, thread-free, approved, and mergeable
+
+use git
+
+# status_commit_cap is how many commits a block lists before eliding the rest.
+status_commit_cap=10
+
+# status:width prints the terminal's width in columns: COLUMNS, else the terminal on stderr, else 100.
+status:width() {
+  local cols=''
+  if [[ "${COLUMNS:-}" =~ ^[0-9]+$ ]]
+  then
+    cols=$(( 10#${COLUMNS} ))
+  elif [[ -t 2 ]]
+  then
+    cols=$(stty size <&2 2>/dev/null | cut -d' ' -f2 || true)
+  fi
+  if [[ "${cols}" =~ ^[0-9]+$ ]] && (( cols >= 60 ))
+  then
+    printf '%s\n' "${cols}"
+  else
+    printf '100\n'
+  fi
+}
+
+# status:cell <text> <width> prints <text> padded to <width> characters, or clipped to it with an ellipsis.
+status:cell() {
+  local text=$1 width=$2
+  if (( ${#text} > width ))
+  then
+    printf '%s…' "${text:0:width-1}"
+  else
+    printf '%s%*s' "${text}" $(( width - ${#text} )) ''
+  fi
+}
+
+# status:paint <sgr> <text> prints <text> in the color when stderr is a terminal.
+status:paint() {
+  printf '%s%s%s' "$(out:sgr "$1")" "$2" "$(out:sgr 0)"
+}
+
+# status:state-sgr <state> prints the family color of a state.
+status:state-sgr() {
+  case "$1" in
+    (ready)                                     printf '32' ;;
+    (conflicted | failing:gate | comments:open) printf '33' ;;
+    (queued | no-check | blocked:approval)      printf '34' ;;
+    (*)                                         printf '90' ;;
+  esac
+}
+
+# status:state-emoji <state> prints the glyph of a state. Every glyph is one code point drawn two columns wide, so
+# the column after it stays aligned.
+status:state-emoji() {
+  case "$1" in
+    (draft)            printf '🔨' ;;
+    (queued)           printf '🚦' ;;
+    (conflicted)       printf '💥' ;;
+    (failing:gate)     printf '🔥' ;;
+    (no-check)         printf '📭' ;;
+    (comments:open)    printf '💬' ;;
+    (blocked:approval) printf '👀' ;;
+    (ready)            printf '🛬' ;;
+    (*)                printf '🔳' ;;
+  esac
+}
+
+# status:collect prints one record per open pull request, oldest first, with the fields separated by the unit
+# separator: number, branch, title, state, age, check glyph, check text, and the issues it closes as "#n title"
+# separated by the record separator. The one request to GitHub.
+status:collect() {
+  local repo query filter
+  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || return 0
+  # shellcheck disable=SC2016  # GraphQL variables
+  query='query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      pullRequests(states: OPEN, first: 100, orderBy: {field: CREATED_AT, direction: ASC}) {
+        nodes {
+          number title isDraft headRefName createdAt mergeStateStatus reviewDecision
+          closingIssuesReferences(first: 10) { nodes { number title } }
+          reviewThreads(first: 100) { nodes { isResolved } }
+          commits(last: 1) { nodes { commit { statusCheckRollup { contexts(first: 100) { nodes {
+            __typename
+            ... on CheckRun { name status conclusion startedAt completedAt }
+            ... on StatusContext { context state createdAt }
+          } } } } } }
+        }
+      }
+    }
+  }'
+  # shellcheck disable=SC2016  # a jq filter, with jq variables
+  filter='
+    def age: if . < 120 then "\(.)s" elif . < 7200 then "\(. / 60 | floor)m"
+             elif . < 172800 then "\(. / 3600 | floor)h" else "\(. / 86400 | floor)d" end;
+    def verdict: if .__typename == "CheckRun" then (if .status == "COMPLETED" then .conclusion else "PENDING" end)
+                 else .state end;
+    def pending: IN("PENDING", "EXPECTED");
+    def passed: IN("SUCCESS", "NEUTRAL", "SKIPPED");
+    (now | floor) as $now
+    | .data.repository.pullRequests.nodes[]
+    | [.commits.nodes[0].commit.statusCheckRollup.contexts.nodes[]?] as $checks
+    | ($checks | length) as $n
+    | ([$checks[] | verdict | select(pending)] | length) as $running
+    | ([$checks[] | verdict | select(passed)] | length) as $ok
+    | ([$checks[] | select((verdict | pending or passed) | not) | (.name // .context)] | first // "") as $failing
+    | (if $n == 0 then "NONE" elif $failing != "" then "FAILURE" elif $running > 0 then "PENDING" else "SUCCESS" end)
+      as $check
+    | ([$checks[] | .startedAt // .createdAt // empty | fromdateiso8601] | min) as $started
+    | ([$checks[] | .completedAt // empty | fromdateiso8601] | max) as $completed
+    | (if $started == null then ""
+       elif $check == "PENDING" then (($now - $started) | age)
+       elif $completed == null then ""
+       else (($completed - $started) | age) end) as $took
+    | (if $check == "SUCCESS" then ["✅", "\($n) / \($n)"]
+       elif $check == "FAILURE" then ["❌", "\($failing) · \($ok) / \($n)"]
+       elif $check == "PENDING" then ["🏃", "\($n - $running) / \($n)"]
+       else ["", ""] end) as $cell
+    | ([.reviewThreads.nodes[]? | select(.isResolved | not)] | length) as $unresolved
+    | (if .isDraft then "draft"
+       elif $check == "PENDING" then "queued"
+       elif .mergeStateStatus == "DIRTY" then "conflicted"
+       elif $check == "FAILURE" then "failing:gate"
+       elif $check == "NONE" then "no-check"
+       elif $unresolved > 0 then "comments:open"
+       elif (.reviewDecision // "") | IN("REVIEW_REQUIRED", "CHANGES_REQUESTED") then "blocked:approval"
+       else "ready" end) as $state
+    | [ (.number | tostring), .headRefName, .title, $state,
+        (($now - (.createdAt | fromdateiso8601)) | age),
+        $cell[0], ($cell[1] + (if $took == "" or $cell[1] == "" then "" else " · \($took)" end)),
+        ([.closingIssuesReferences.nodes[] | "#\(.number) \(.title)"] | join("\u001e")) ]
+    | join("\u001f")'
+  gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
+    2>/dev/null || true
+}
+
+# status:fork <branch> <default-branch> prints the commit where <branch> left the default branch, or nothing.
+status:fork() {
+  git merge-base "origin/$2" "$1" 2>/dev/null || git merge-base "$2" "$1" 2>/dev/null || true
+}
+
+# status:divergence <path> <branch> <fork> prints "<ahead>\t<behind>\t<added>\t<removed>": the commits on <branch>
+# past <fork>, the commits on the default branch past it, and the lines the working tree at <path> adds and removes
+# against it. A detached checkout has no branch and no fork, and measures its lines against its own head.
+status:divergence() {
+  local path=$1 branch=$2 fork=$3 default_branch=$4 ahead=0 behind=0 added=0 removed=0 a r _
+  if [[ -n "${fork}" ]]
+  then
+    ahead=$(git rev-list --count "${fork}..${branch}" 2>/dev/null || printf 0)
+    behind=$(git rev-list --count "${fork}..origin/${default_branch}" 2>/dev/null || printf 0)
+  fi
+  while IFS=$'\t' read -r a r _
+  do
+    [[ -n "${a}" && "${a}" != '-' ]] && added=$(( added + a ))
+    [[ -n "${r}" && "${r}" != '-' ]] && removed=$(( removed + r ))
+  done < <(git -C "${path}" diff --numstat "${fork:-HEAD}" 2>/dev/null || true)
+  printf '%s\t%s\t%s\t%s\n' "${ahead}" "${behind}" "${added}" "${removed}"
+}
+
+# status:paint-counts <ahead> <behind> <added> <removed> prints "↑a ↓b · +x -y": a non-zero count in bold green or
+# bold red, a zero dim.
+status:paint-counts() {
+  local ahead=$1 behind=$2 added=$3 removed=$4
+  printf '%s %s · %s %s' \
+    "$(status:paint-count "${ahead}" '↑' '1;32')" "$(status:paint-count "${behind}" '↓' '1;31')" \
+    "$(status:paint-count "${added}" '+' '1;32')" "$(status:paint-count "${removed}" '-' '1;31')"
+}
+
+# status:paint-count <count> <sign> <sgr> prints <sign><count>, in <sgr> when the count is above zero and dim otherwise.
+status:paint-count() {
+  local count=$1 sign=$2 sgr=$3
+  (( count > 0 )) || sgr=90
+  status:paint "${sgr}" "${sign}${count}"
+}
+
+# status:commits <path> <range> prints the commits in <range>, dim hash then subject, indented under a row. Past
+# status_commit_cap, the first commits, a dim "… and N more", and the oldest.
+status:commits() {
+  local path=$1 range=$2 line total hidden=0 i
+  local -a commits=()
+  mapfile -t commits < <(git -C "${path}" log --format='%h %s' "${range}" 2>/dev/null || true)
+  total=${#commits[@]}
+  (( total > status_commit_cap + 1 )) && hidden=$(( total - status_commit_cap ))
+  for (( i = 0; i < total; i++ ))
+  do
+    if (( hidden > 0 && i == status_commit_cap - 1 ))
+    then
+      printf '   %s\n' "$(status:paint 90 "… and ${hidden} more")" >&2
+      i=$(( total - 2 ))
+      continue
+    fi
+    line=${commits[i]}
+    printf '   %s %s\n' "$(status:paint 90 "${line%% *}")" "${line#* }" >&2
+  done
+}
+
+# status:pr-block <record> <title-width> <state-width> <age-width> <path> <main-root> <default-branch> prints one
+# pull request: its row, the issues it closes, and, when <path> names its worktree, the commits it carries past its
+# fork and the worktree's line.
+status:pr-block() {
+  local title_w=$2 state_w=$3 age_w=$4 path=$5 main_root=$6 default_branch=$7
+  local number branch title state age glyph check issues issue row fork counts
+  IFS=$'\x1f' read -r number branch title state age glyph check issues <<<"$1"
+  row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
+  row+="   $(status:state-emoji "${state}") $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
+  row+="   $(status:paint 90 "$(status:cell "${age}" "${age_w}")")"
+  [[ -n "${glyph}" ]] && row+="   ${glyph} ${check}"
+  printf '%s\n' "${row}" >&2
+  if [[ -n "${issues}" ]]
+  then
+    while IFS= read -r issue
+    do
+      printf '   %s\n' "$(status:paint 90 "${issue}")" >&2
+    done < <(tr '\036' '\n' <<<"${issues}")
+  fi
+  [[ -n "${path}" ]] || return 0
+  fork=$(status:fork "${branch}" "${default_branch}")
+  [[ -n "${fork}" ]] && status:commits "${path}" "${fork}..${branch}"
+  counts=$(status:divergence "${path}" "${branch}" "${fork}" "${default_branch}")
+  # shellcheck disable=SC2086  # the four counts are tab-separated words
+  printf '   🌿 %s   %s%s\n' "$(status:paint 90 "${path#"${main_root}"/}")" "$(status:paint-counts ${counts})" \
+    "$(status:uncommitted "${path}")" >&2
+}
+
+# status:worktree-alone <path> <branch> <title-width> <main-root> <default-branch> prints a worktree with no open
+# pull request as a row: its path, why it stands alone, and its divergence.
+status:worktree-alone() {
+  local path=$1 branch=$2 title_w=$3 main_root=$4 default_branch=$5 mark fork='' counts
+  if [[ -n "${branch}" ]]
+  then
+    mark=$(status:paint 90 'no open pull request')
+    fork=$(status:fork "${branch}" "${default_branch}")
+  else
+    mark=$(status:paint 33 '❗ detached HEAD')
+  fi
+  counts=$(status:divergence "${path}" "${branch}" "${fork}" "${default_branch}")
+  # shellcheck disable=SC2086  # the four counts are tab-separated words
+  printf '🌿 %s   %s   %s%s\n' "$(status:cell "${path#"${main_root}"/}" "${title_w}")" "${mark}" \
+    "$(status:paint-counts ${counts})" "$(status:uncommitted "${path}")" >&2
+}
+
+# status:uncommitted <path> prints " · n uncommitted" for a dirty checkout, nothing for a clean one.
+status:uncommitted() {
+  git:clean "$1" && return 0
+  printf ' · %s' "$(status:paint 33 "$(git -C "$1" status --porcelain | grep --count .) uncommitted")"
+}
+
+# status:by-number <branch>… prints "<number>\t<branch>" for each branch whose worktree directory opens with an issue
+# number, 0 for one that does not, sorted by that number.
+status:by-number() {
+  local branch dir number
+  for branch in "$@"
+  do
+    dir=${worktree_of[${branch}]##*/}
+    number=${dir%%-*}
+    [[ "${number}" =~ ^[0-9]+$ ]] || number=0
+    printf '%s\t%s\n' "${number}" "${branch}"
+  done | sort -n -k1,1
+}
+
+# status:badges <state>… prints "<glyph> <count>" per state, most populous first.
+status:badges() {
+  local -A tally=()
+  local state count out=''
+  for state in "$@"
+  do
+    tally[${state}]=$(( ${tally[${state}]:-0} + 1 ))
+  done
+  while IFS=$'\t' read -r count state
+  do
+    out+="${out:+  }$(status:state-emoji "${state}") ${count}"
+  done < <(
+    for state in "${!tally[@]}"
+    do
+      printf '%s\t%s\n' "${tally[${state}]}" "${state}"
+    done | sort -t$'\t' -k1,1nr -k2,2
+  )
+  printf '%s' "${out}"
+}
+
+status:render() {
+  local no_fetch=false arg main_root default_branch records path branch record
+  for arg in "$@"
+  do
+    case "${arg}" in
+      (--no-fetch)
+        no_fetch=true
+        ;;
+      (*)
+        error "unknown flag '${arg}' (only --no-fetch is recognized)"
+        return 2
+    esac
+  done
+  if [[ "${no_fetch}" != true ]]
+  then
+    git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
+  fi
+  main_root=$(git:main-root)
+  default_branch=$(git:default-branch)
+  records=$(status:collect)
+
+  # The linked worktrees: by branch, and the detached ones.
+  local -A worktree_of=()
+  local -a detached_paths=()
+  while IFS=$'\t' read -r path branch _
+  do
+    [[ -n "${path}" ]] || continue
+    if [[ -n "${branch}" ]]
+    then
+      worktree_of[${branch}]=${path}
+    else
+      detached_paths+=("${path}")
+    fi
+  done < <(git:worktrees)
+
+  # The rows, and the width of each column across them.
+  local -a rows=() states=()
+  local -A pr_on=()
+  local number title state age glyph check issues count=0 state_w=0 age_w=0 check_w=0 title_w=0 issue
+  while IFS= read -r record
+  do
+    [[ -n "${record}" ]] || continue
+    IFS=$'\x1f' read -r number branch title state age glyph check issues <<<"${record}"
+    rows+=("${record}")
+    states+=("${state}")
+    pr_on[${branch}]=1
+    (( ${#state} > state_w )) && state_w=${#state}
+    (( ${#age} > age_w )) && age_w=${#age}
+    [[ -n "${glyph}" ]] && (( ${#check} + 3 > check_w )) && check_w=$(( ${#check} + 3 ))
+    title="#${number} ${title}"
+    (( ${#title} > title_w )) && title_w=${#title}
+    while IFS= read -r issue
+    do
+      (( ${#issue} > title_w )) && title_w=${#issue}
+    done < <(tr '\036' '\n' <<<"${issues}")
+  done <<<"${records}"
+  count=${#rows[@]}
+  for path in "${worktree_of[@]}" "${detached_paths[@]}"
+  do
+    path=${path#"${main_root}"/}
+    (( ${#path} > title_w )) && title_w=${#path}
+  done
+  local avail
+  avail=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - check_w ))
+  (( avail < 20 )) && avail=20
+  (( title_w > avail )) && title_w=${avail}
+
+  if (( count == 0 ))
+  then
+    out:emit '📋' '1' 'no open pull requests'
+  else
+    out:emit '📋' '1' "${count} open pull request$( (( count == 1 )) || printf s) · $(status:badges "${states[@]}")"
+  fi
+
+  # Worktrees: the pull requests written in one, then the worktrees without one, by issue number.
+  local -A drawn=()
+  local -a lone=()
+  for branch in "${!worktree_of[@]}"
+  do
+    [[ -n "${pr_on[${branch}]:-}" ]] || lone+=("${branch}")
+  done
+  if (( ${#worktree_of[@]} + ${#detached_paths[@]} > 0 ))
+  then
+    section "worktrees"
+    for record in "${rows[@]}"
+    do
+      IFS=$'\x1f' read -r number branch _ <<<"${record}"
+      [[ -n "${worktree_of[${branch}]:-}" ]] || continue
+      drawn[${number}]=1
+      status:pr-block "${record}" "${title_w}" "${state_w}" "${age_w}" "${worktree_of[${branch}]}" "${main_root}" \
+        "${default_branch}"
+    done
+    while IFS=$'\t' read -r _ branch
+    do
+      [[ -n "${branch}" ]] || continue
+      status:worktree-alone "${worktree_of[${branch}]}" "${branch}" "${title_w}" "${main_root}" "${default_branch}"
+    done < <(status:by-number "${lone[@]}")
+    for path in "${detached_paths[@]}"
+    do
+      status:worktree-alone "${path}" '' "${title_w}" "${main_root}" "${default_branch}"
+    done
+  fi
+
+  # Pull requests with no worktree here.
+  if (( count > ${#drawn[@]} ))
+  then
+    section "pull requests"
+    for record in "${rows[@]}"
+    do
+      number=${record%%$'\x1f'*}
+      [[ -n "${drawn[${number}]:-}" ]] && continue
+      status:pr-block "${record}" "${title_w}" "${state_w}" "${age_w}" '' "${main_root}" "${default_branch}"
+    done
+  fi
+
+  local gone
+  gone=$(git:gone-branches)
+  if [[ -n "${gone}" ]]
+  then
+    section "branches whose upstream is gone (tidy removes these)"
+    while IFS= read -r branch
+    do
+      info "${branch}"
+    done <<<"${gone}"
+  fi
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/status.bats b/tests/status.bats
new file mode 100644
index 0000000..ec298f2
--- /dev/null
+++ b/tests/status.bats
@@ -0,0 +1,65 @@
+#!/usr/bin/env bats
+# status.bats - the parts of the picture that need no GitHub: a cell, the commit list, and a worktree's row
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  work=$(mktemp -d)
+  cd "${work}"
+  git init --quiet --bare --initial-branch=main origin.git
+  git clone --quiet origin.git desk 2>/dev/null
+  cd desk
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  printf 'one\n' > a && git add a && git commit --quiet --message one && git push --quiet origin main
+  git remote set-head origin main
+  mkdir worktrees
+}
+
+teardown() {
+  rm -rf "${work}"
+}
+
+# in_status <command>… runs a command with the status module loaded.
+in_status() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use status && "$@"' _ "$@"
+}
+
+@test "a cell is padded to its width, or clipped with an ellipsis" {
+  run in_status status:cell abc 5
+  [ "$output" = "abc  " ]
+  run in_status status:cell abcdefgh 5
+  [ "$output" = "abcd…" ]
+}
+
+@test "the commit list shows the newest, says how many are hidden, and ends with the oldest" {
+  git worktree add --quiet -b topic worktrees/topic main
+  for i in $(seq 1 15)
+  do
+    printf '%s\n' "${i}" > "worktrees/topic/f${i}" && git -C worktrees/topic add . && git -C worktrees/topic commit --quiet --message "c${i}"
+  done
+  run in_status status:commits "${PWD}/worktrees/topic" main..topic
+  [ "$status" -eq 0 ]
+  [ "${#lines[@]}" -eq 11 ]
+  [[ "${lines[0]}" == *" c15" ]]
+  [[ "${lines[8]}" == *" c7" ]]
+  [[ "${lines[9]}" == *"… and 5 more" ]]
+  [[ "${lines[10]}" == *" c1" ]]
+}
+
+@test "a worktree with no pull request says so, with its distance from main and the size of its diff" {
+  git worktree add --quiet -b topic worktrees/topic main
+  printf 'two\nthree\n' > worktrees/topic/b && git -C worktrees/topic add b && git -C worktrees/topic commit --quiet --message two
+  printf 'four\n' > c && git add c && git commit --quiet --message four && git push --quiet origin main
+  run in_status status:worktree-alone "${PWD}/worktrees/topic" topic 20 "${PWD}" main
+  [ "$status" -eq 0 ]
+  [ "$output" = "🌿 worktrees/topic        no open pull request   ↑1 ↓1 · +2 -0" ]
+}
+
+@test "a detached worktree is marked, and a dirty one counts its uncommitted paths" {
+  git worktree add --quiet --detach worktrees/loose main
+  printf 'x\n' > worktrees/loose/x
+  run in_status status:worktree-alone "${PWD}/worktrees/loose" '' 16 "${PWD}" main
+  [ "$status" -eq 0 ]
+  [ "$output" = "🌿 worktrees/loose    ❗ detached HEAD   ↑0 ↓0 · +0 -0 · 1 uncommitted" ]
+}

From 3b7cfd96d8a52766058c9094ad8fc1cb4d8cc27a Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 10:48:51 -0700
Subject: [PATCH 055/108] #1 bin/status.sh: every pull request in one section,
 dim timings, closes lines, unresolved threads

A pull request is a pull request whether or not a worktree holds its branch, so the first section
is every open pull request, each with its worktree line when there is one, and the second is the
worktrees with no pull request, which no longer repeat the heading on every row. The run duration
in the check cell is dim like every other timing. The issues a pull request closes read
"closes #N title". A row with unresolved review threads ends with their count, in yellow.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/status.sh     | 117 +++++++++++++++++++++++++---------------------
 tests/status.bats |   4 +-
 2 files changed, 66 insertions(+), 55 deletions(-)

diff --git a/bin/status.sh b/bin/status.sh
index 6a00ba6..7f31228 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -8,17 +8,17 @@
 #
 # The picture is a headline counting the pull requests by state, then three sections, each omitted when empty:
 #
-#   worktrees      — every pull request written in a worktree under worktrees/, then the worktrees with no pull
-#                    request. A pull request's block is its row, the issues it closes, up to ten of the commits it
-#                    carries past its fork from the default branch, and its worktree with how far that has moved
-#                    from the fork and the size of its diff.
-#   pull requests  — every open pull request with no worktree here, the same block without the worktree.
+#   pull requests  — every open pull request: its row, the issues it closes, and, when a worktree under worktrees/
+#                    holds its branch, up to ten of the commits it carries past its fork from the default branch
+#                    and the worktree with how far that has moved from the fork and the size of its diff.
+#   worktrees      — every worktree under worktrees/ with no open pull request, with the same measures.
 #   gone branches  — every local branch whose upstream is gone, which kit tidy removes.
 #
-# A row is the title, the state with its glyph, the age, and the checks. Every state has its own glyph, so a row is
-# recognizable without reading the token. Color is by family, never by state: green when nothing is left to decide,
-# yellow when a human owes a decision, blue when the next move is a machine's or a reviewer's, dim when someone
-# already owns the work. The state is the first of these that holds:
+# A row is the title, the state with its glyph, the age, the checks, and, when there are any, the unresolved review
+# threads. Every state has its own glyph, so a row is recognizable without reading the token. Color is by family,
+# never by state: green when nothing is left to decide, yellow when a human owes a decision, blue when the next move
+# is a machine's or a reviewer's, dim when someone already owns the work, and every timing is dim. The state is the
+# first of these that holds:
 #
 #   draft              🔨  dim     unfinished work that belongs to someone
 #   queued             🚦  blue    a check is still running
@@ -95,8 +95,9 @@ status:state-emoji() {
 }
 
 # status:collect prints one record per open pull request, oldest first, with the fields separated by the unit
-# separator: number, branch, title, state, age, check glyph, check text, and the issues it closes as "#n title"
-# separated by the record separator. The one request to GitHub.
+# separator: number, branch, title, state, age, check glyph, check text, how long the checks took, the count of
+# unresolved review threads, and the issues it closes as "#n title" separated by the record separator. The one
+# request to GitHub.
 status:collect() {
   local repo query filter
   repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || return 0
@@ -155,7 +156,7 @@ status:collect() {
        else "ready" end) as $state
     | [ (.number | tostring), .headRefName, .title, $state,
         (($now - (.createdAt | fromdateiso8601)) | age),
-        $cell[0], ($cell[1] + (if $took == "" or $cell[1] == "" then "" else " · \($took)" end)),
+        $cell[0], $cell[1], (if $cell[1] == "" then "" else $took end), ($unresolved | tostring),
         ([.closingIssuesReferences.nodes[] | "#\(.number) \(.title)"] | join("\u001e")) ]
     | join("\u001f")'
   gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
@@ -222,23 +223,29 @@ status:commits() {
   done
 }
 
-# status:pr-block <record> <title-width> <state-width> <age-width> <path> <main-root> <default-branch> prints one
-# pull request: its row, the issues it closes, and, when <path> names its worktree, the commits it carries past its
-# fork and the worktree's line.
+# status:pr-block <record> <title-width> <state-width> <age-width> <check-width> <path> <main-root> <default-branch>
+# prints one pull request: its row, the issues it closes, and, when <path> names its worktree, the commits it
+# carries past its fork and the worktree's line.
 status:pr-block() {
-  local title_w=$2 state_w=$3 age_w=$4 path=$5 main_root=$6 default_branch=$7
-  local number branch title state age glyph check issues issue row fork counts
-  IFS=$'\x1f' read -r number branch title state age glyph check issues <<<"$1"
+  local title_w=$2 state_w=$3 age_w=$4 check_w=$5 path=$6 main_root=$7 default_branch=$8
+  local number branch title state age glyph check took unresolved issues issue row fork counts
+  IFS=$'\x1f' read -r number branch title state age glyph check took unresolved issues <<<"$1"
   row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
   row+="   $(status:state-emoji "${state}") $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
   row+="   $(status:paint 90 "$(status:cell "${age}" "${age_w}")")"
-  [[ -n "${glyph}" ]] && row+="   ${glyph} ${check}"
+  if (( unresolved > 0 ))
+  then
+    row+="   $(status:check-cell "${glyph}" "${check}" "${took}" "${check_w}")   $(status:paint 33 "💬 ${unresolved} unresolved")"
+  elif [[ -n "${glyph}" ]]
+  then
+    row+="   $(status:check-cell "${glyph}" "${check}" "${took}" 0)"
+  fi
   printf '%s\n' "${row}" >&2
   if [[ -n "${issues}" ]]
   then
     while IFS= read -r issue
     do
-      printf '   %s\n' "$(status:paint 90 "${issue}")" >&2
+      printf '   %s\n' "$(status:paint 90 "closes ${issue}")" >&2
     done < <(tr '\036' '\n' <<<"${issues}")
   fi
   [[ -n "${path}" ]] || return 0
@@ -250,20 +257,32 @@ status:pr-block() {
     "$(status:uncommitted "${path}")" >&2
 }
 
+# status:check-cell <glyph> <text> <took> <width> prints the checks as "<glyph> <text> · <took>", the duration dim,
+# padded to <width> characters when something follows it; nothing when no check has reported.
+status:check-cell() {
+  local glyph=$1 text=$2 took=$3 width=$4 plain=''
+  if [[ -n "${glyph}" ]]
+  then
+    plain="${glyph} ${text}${took:+ · ${took}}"
+    printf '%s %s%s' "${glyph}" "${text}" "${took:+ · $(status:paint 90 "${took}")}"
+  fi
+  (( ${#plain} < width )) && printf '%*s' $(( width - ${#plain} )) ''
+  return 0
+}
+
 # status:worktree-alone <path> <branch> <title-width> <main-root> <default-branch> prints a worktree with no open
-# pull request as a row: its path, why it stands alone, and its divergence.
+# pull request as a row: its path, a mark when it is detached, and its divergence.
 status:worktree-alone() {
-  local path=$1 branch=$2 title_w=$3 main_root=$4 default_branch=$5 mark fork='' counts
+  local path=$1 branch=$2 title_w=$3 main_root=$4 default_branch=$5 mark='' fork='' counts
   if [[ -n "${branch}" ]]
   then
-    mark=$(status:paint 90 'no open pull request')
     fork=$(status:fork "${branch}" "${default_branch}")
   else
-    mark=$(status:paint 33 '❗ detached HEAD')
+    mark="$(status:paint 33 '❗ detached HEAD')   "
   fi
   counts=$(status:divergence "${path}" "${branch}" "${fork}" "${default_branch}")
   # shellcheck disable=SC2086  # the four counts are tab-separated words
-  printf '🌿 %s   %s   %s%s\n' "$(status:cell "${path#"${main_root}"/}" "${title_w}")" "${mark}" \
+  printf '🌿 %s   %s%s%s\n' "$(status:cell "${path#"${main_root}"/}" "${title_w}")" "${mark}" \
     "$(status:paint-counts ${counts})" "$(status:uncommitted "${path}")" >&2
 }
 
@@ -344,17 +363,18 @@ status:render() {
   # The rows, and the width of each column across them.
   local -a rows=() states=()
   local -A pr_on=()
-  local number title state age glyph check issues count=0 state_w=0 age_w=0 check_w=0 title_w=0 issue
+  local number title state age glyph check took unresolved issues count=0 state_w=0 age_w=0 check_w=0 title_w=0 issue
   while IFS= read -r record
   do
     [[ -n "${record}" ]] || continue
-    IFS=$'\x1f' read -r number branch title state age glyph check issues <<<"${record}"
+    IFS=$'\x1f' read -r number branch title state age glyph check took unresolved issues <<<"${record}"
     rows+=("${record}")
     states+=("${state}")
     pr_on[${branch}]=1
     (( ${#state} > state_w )) && state_w=${#state}
     (( ${#age} > age_w )) && age_w=${#age}
-    [[ -n "${glyph}" ]] && (( ${#check} + 3 > check_w )) && check_w=$(( ${#check} + 3 ))
+    check="${glyph:+${glyph} ${check}${took:+ · ${took}}}"
+    (( ${#check} + 1 > check_w )) && check_w=$(( ${#check} + 1 ))
     title="#${number} ${title}"
     (( ${#title} > title_w )) && title_w=${#title}
     while IFS= read -r issue
@@ -369,7 +389,7 @@ status:render() {
     (( ${#path} > title_w )) && title_w=${#path}
   done
   local avail
-  avail=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - check_w ))
+  avail=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - check_w - 3 - 16 ))
   (( avail < 20 )) && avail=20
   (( title_w > avail )) && title_w=${avail}
 
@@ -380,24 +400,27 @@ status:render() {
     out:emit '📋' '1' "${count} open pull request$( (( count == 1 )) || printf s) · $(status:badges "${states[@]}")"
   fi
 
-  # Worktrees: the pull requests written in one, then the worktrees without one, by issue number.
-  local -A drawn=()
+  # Every pull request, with its worktree when one here holds its branch.
+  if (( count > 0 ))
+  then
+    section "pull requests"
+    for record in "${rows[@]}"
+    do
+      IFS=$'\x1f' read -r _ branch _ <<<"${record}"
+      status:pr-block "${record}" "${title_w}" "${state_w}" "${age_w}" "${check_w}" "${worktree_of[${branch}]:-}" \
+        "${main_root}" "${default_branch}"
+    done
+  fi
+
+  # The worktrees with no pull request, by issue number, then the detached ones.
   local -a lone=()
   for branch in "${!worktree_of[@]}"
   do
     [[ -n "${pr_on[${branch}]:-}" ]] || lone+=("${branch}")
   done
-  if (( ${#worktree_of[@]} + ${#detached_paths[@]} > 0 ))
+  if (( ${#lone[@]} + ${#detached_paths[@]} > 0 ))
   then
-    section "worktrees"
-    for record in "${rows[@]}"
-    do
-      IFS=$'\x1f' read -r number branch _ <<<"${record}"
-      [[ -n "${worktree_of[${branch}]:-}" ]] || continue
-      drawn[${number}]=1
-      status:pr-block "${record}" "${title_w}" "${state_w}" "${age_w}" "${worktree_of[${branch}]}" "${main_root}" \
-        "${default_branch}"
-    done
+    section "worktrees with no open pull request"
     while IFS=$'\t' read -r _ branch
     do
       [[ -n "${branch}" ]] || continue
@@ -409,18 +432,6 @@ status:render() {
     done
   fi
 
-  # Pull requests with no worktree here.
-  if (( count > ${#drawn[@]} ))
-  then
-    section "pull requests"
-    for record in "${rows[@]}"
-    do
-      number=${record%%$'\x1f'*}
-      [[ -n "${drawn[${number}]:-}" ]] && continue
-      status:pr-block "${record}" "${title_w}" "${state_w}" "${age_w}" '' "${main_root}" "${default_branch}"
-    done
-  fi
-
   local gone
   gone=$(git:gone-branches)
   if [[ -n "${gone}" ]]
diff --git a/tests/status.bats b/tests/status.bats
index ec298f2..c48139a 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -47,13 +47,13 @@ in_status() {
   [[ "${lines[10]}" == *" c1" ]]
 }
 
-@test "a worktree with no pull request says so, with its distance from main and the size of its diff" {
+@test "a worktree with no pull request shows its distance from main and the size of its diff" {
   git worktree add --quiet -b topic worktrees/topic main
   printf 'two\nthree\n' > worktrees/topic/b && git -C worktrees/topic add b && git -C worktrees/topic commit --quiet --message two
   printf 'four\n' > c && git add c && git commit --quiet --message four && git push --quiet origin main
   run in_status status:worktree-alone "${PWD}/worktrees/topic" topic 20 "${PWD}" main
   [ "$status" -eq 0 ]
-  [ "$output" = "🌿 worktrees/topic        no open pull request   ↑1 ↓1 · +2 -0" ]
+  [ "$output" = "🌿 worktrees/topic        ↑1 ↓1 · +2 -0" ]
 }
 
 @test "a detached worktree is marked, and a dirty one counts its uncommitted paths" {

From a51fa702c8bcca8fa56e24aebc5595fe539f460f Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 10:52:49 -0700
Subject: [PATCH 056/108] #1 README.md: the by-hand install goes through gh,
 which the kit needs anyway

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4664520..ae981be 100644
--- a/README.md
+++ b/README.md
@@ -38,13 +38,13 @@ With Homebrew, from the empowerite tap:
 brew install empowerite/tap/kit
 ```
 
-Or by hand, with the version in `version`: unpack the release and put its `bin/` on `PATH`:
+Or by hand, with `gh`, which the kit needs anyway. Without a tag this takes the latest release, never a
+pre-release; `gh release download "v${version}" ...` takes a particular one. Unpack it and put its `bin/` on `PATH`:
 
 ```sh
-curl --location --output "kit-${version}.tar.gz" \
-  "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz"
-tar --extract --gzip --file "kit-${version}.tar.gz"
-export PATH="${PWD}/kit-${version}/bin:${PATH}"
+gh release download --repo empowerite/kit --pattern 'kit-*.tar.gz'
+tar --extract --gzip --file kit-*.tar.gz
+export PATH="${PWD}/$(ls -d kit-*/ | head -n 1)bin:${PATH}"
 ```
 
 The kit needs bash 4.4 or later, git, `gh`, and `jq`. macOS ships bash 3.2, and `brew install bash` gives a

From 1377f068f379aa183afba18918898dfcc9dc428c Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 10:53:33 -0700
Subject: [PATCH 057/108] #1 README.md: the by-hand install unpacks into a
 named directory

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ae981be..a08b898 100644
--- a/README.md
+++ b/README.md
@@ -42,9 +42,9 @@ Or by hand, with `gh`, which the kit needs anyway. Without a tag this takes the
 pre-release; `gh release download "v${version}" ...` takes a particular one. Unpack it and put its `bin/` on `PATH`:
 
 ```sh
-gh release download --repo empowerite/kit --pattern 'kit-*.tar.gz'
-tar --extract --gzip --file kit-*.tar.gz
-export PATH="${PWD}/$(ls -d kit-*/ | head -n 1)bin:${PATH}"
+gh release download --repo empowerite/kit --pattern 'kit-*.tar.gz' --output kit.tar.gz
+mkdir kit && tar --extract --gzip --file kit.tar.gz --directory kit --strip-components 1
+export PATH="${PWD}/kit/bin:${PATH}"
 ```
 
 The kit needs bash 4.4 or later, git, `gh`, and `jq`. macOS ships bash 3.2, and `brew install bash` gives a

From 50b3fec39d0e64fb6372be647b22a12723e11139 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 10:59:30 -0700
Subject: [PATCH 058/108] #1 the desk is the root checkout, not main; the kit
 is the checks, not only the rules

The human's desk is the checkout at the repository root, whatever branch it has: usually main, and
otherwise any branch no worktree holds. The entry file says so. kit rebase refuses the root checkout
whatever its branch, and the default branch anywhere. kit issue sweeps uncommitted work out of the
root checkout whatever its branch, and fast-forwards it only when it is on the default branch. The
README says what the kit is for: verification that does not depend on anyone's word, with the rules
as the text the checks hold the work against.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md       | 15 ++++++++-------
 .kit/manifest     |  2 +-
 README.md         | 12 ++++++++----
 bin/gh.sh         | 17 ++++++++++-------
 bin/git.sh        | 11 ++++++++---
 bin/kit-rebase.sh |  2 +-
 tests/rebase.bats | 18 +++++++++++++++---
 tree/.kit/1st.md  | 15 ++++++++-------
 8 files changed, 59 insertions(+), 33 deletions(-)

diff --git a/.kit/1st.md b/.kit/1st.md
index cf4b2a1..1792650 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -14,11 +14,12 @@ the repository's own rules in `AGENTS.md` bind beside it. Where the two differ,
 5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
    written into a rule file or `AGENTS.md` through the loop, where every agent and every person reads it.
 
-## `main` is the human's desk
+## The root checkout is the human's desk
 
-The checkout at the repository root stays on the default branch. It is where the human types, reviews, and
-leaves work in progress. Never check out, reset, rebase, or otherwise change it in place. Work happens in a
-worktree under `worktrees/`, one per issue, and reaches `main` only through a merged pull request.
+The checkout at the repository root is the human's. It is where they type, review, and leave work in progress.
+It usually has `main` checked out, and may have any branch no worktree holds. An agent never checks out, resets,
+rebases, or otherwise changes it in place. Work happens in a worktree under `worktrees/`, one per issue, and
+reaches `main` only through a merged pull request.
 
 ## The loop
 
@@ -37,12 +38,12 @@ worktree under `worktrees/`, one per issue, and reaches `main` only through a me
 Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. The rule runs inside
 it, and a harness that can refuse the raw spelling does.
 
-- `kit rebase`, never `git rebase`. It refuses the default branch and otherwise rebases the worktree's branch onto
-  `origin/main` and pushes it.
+- `kit rebase`, never `git rebase`. It refuses the root checkout and the default branch, and otherwise rebases the
+  worktree's branch onto `origin/main` and pushes it.
 - `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
 - `kit tidy`, never `git worktree remove` or `git branch -D`.
 
-The human at the desk is not bound by this; `main` is theirs to rebase.
+The human at the desk is not bound by this; the root checkout is theirs.
 
 ## Plans are prose
 
diff --git a/.kit/manifest b/.kit/manifest
index 4ba3e5c..0723404 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -9,7 +9,7 @@ edcd5198f76362ef2890f2dfa5ca2df1a81bce27864dc7c19fd64a683e040e23  .claude/rules/
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
 100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
 f03e0fa3ae07c74235558bffc38d5cb24c388c7c440e469cf8a8e58604edfc4b  .github/workflows/kit-ci.yml
-22275196b95f53fe4b0bef7d309748161fcd2ede466a0ab3b67265fc2fa6814c  .kit/1st.md
+d83f24086d807bf6e9c6ed55d0fd7d77aa130a5b41a3db41d806e4ce84918aa1  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 b7f7f37d89165d6364fbb4e91c0c637eeb26fa72391a76f3419926efb7923522  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
diff --git a/README.md b/README.md
index a08b898..ebbaafc 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,14 @@ shortcut anyone ever took: the "done" that was not, the test that was skipped an
 that quietly rewrote a colleague's branch. An agent is a tireless new colleague who has read everything and holds
 none of your house rules, unless you put them where it looks.
 
-kit is the house rules, put where agents look, as a versioned release any repository can take and keep taking.
-It is small on purpose: the text an agent reads first, a rule file per kind of file, a guard that keeps `main` as
-the human's desk, and the one command no harness provides, which turns an issue into a worktree with a draft pull
-request. A tag on `main` publishes a release. A repository pins it, installs it, and keeps rules of its own
+kit is the house rules, put where agents look, and the checks that hold agents to them, as a versioned release any
+repository can take and keep taking. The rules are the smaller part. The point is verification that does not depend on
+anyone's word: a delivered CI job that refuses a pull request without a linked open issue, `kit check` holding every
+delivered file to its release, a pre-commit hook that runs the linters over what is staged, a deny list that refuses
+the spellings the rules forbid, and `kit status` showing what every pull request's checks said. The text is what those
+checks hold the work against: the entry file an agent reads first, a rule file per kind of file, the root checkout
+kept as the human's desk, and the one command no harness provides, which turns an issue into a worktree with a draft
+pull request. A tag on `main` publishes a release. A repository pins it, installs it, and keeps rules of its own
 beside it. The design is [#1](https://github.com/empowerite/kit/issues/1), and the entry file every agent reads is
 [.kit/1st.md](.kit/1st.md).
 
diff --git a/bin/gh.sh b/bin/gh.sh
index e097d06..3ced0f9 100644
--- a/bin/gh.sh
+++ b/bin/gh.sh
@@ -9,9 +9,10 @@
 # under the main checkout, and an existing branch, worktree, or pull request is reused, so a re-run reconciles.
 #
 # With no argument and a terminal on stdin it asks for a title and creates the issue; without a terminal the
-# usage error stands, so an agent never hangs on a prompt. Uncommitted work on the default branch is swept into
-# the new worktree, uncommitted, and the desk is left clean and fast-forwarded; inside any other checkout, dirty
-# files are that issue's own and stay. A sweep that cannot apply leaves the stash in place and stops.
+# usage error stands, so an agent never hangs on a prompt. Uncommitted work in the root checkout, the human's
+# desk, is swept into the new worktree, uncommitted, and the desk is left clean, and fast-forwarded when it is on
+# the default branch; inside any other checkout, dirty files are that issue's own and stay. A sweep that cannot
+# apply leaves the stash in place and stops.
 #
 # Each step below prints its one result on stdout and talks on stderr, so gh:issue reads them in order.
 
@@ -134,7 +135,8 @@ gh:sweep-push() {
 }
 
 # gh:sweep-apply <root> <worktree> <stash> <default-branch> lands the stash in the worktree, uncommitted, drops it,
-# and fast-forwards the now-clean desk. On a conflict the stash is kept and the caller stops.
+# and fast-forwards the now-clean desk when it is on the default branch. On a conflict the stash is kept and the
+# caller stops.
 gh:sweep-apply() {
   local root=$1 wt=$2 stash=$3 default_branch=$4 slot
   if ! git -C "${wt}" stash apply "${stash}" >/dev/null 2>&1
@@ -145,6 +147,7 @@ gh:sweep-apply() {
   slot=$(git -C "${root}" stash list --format='%gd %H' | awk -v h="${stash}" '$2 == h { print $1; exit }')
   [[ -n "${slot}" ]] && git -C "${root}" stash drop "${slot}" >/dev/null
   ok "Swept the work into ${wt}, uncommitted; commit it there with a real message."
+  [[ "$(git -C "${root}" rev-parse --abbrev-ref HEAD)" == "${default_branch}" ]] || return 0
   git -C "${root}" merge --ff-only "origin/${default_branch}" >/dev/null 2>&1 \
     || warn "${default_branch} could not fast-forward to origin; it is left as it was."
 }
@@ -221,9 +224,9 @@ gh:issue() {
   section "Starting #${primary}: ${title}"
 
   branch=$(gh:issue-branch "${primary}" "${default_branch}") || return
-  if [[ "${desk_branch}" == "${default_branch}" ]] && ! git:clean "${desk}"
+  if [[ "${desk}" == "${main_root}" ]] && ! git:clean "${desk}"
   then
-    step "Sweeping the uncommitted work on ${default_branch} into the worktree"
+    step "Sweeping the uncommitted work on ${desk_branch} into the worktree"
     stash=$(gh:sweep-push "${desk}" "kit issue #${primary} → ${branch}") || return
   fi
   wt=$(gh:worktree "${main_root}" "${branch}") || return
@@ -240,7 +243,7 @@ gh:issue() {
 
   ok "Draft pull request #${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
   ok "Worktree ready: ${wt}"
-  step "cd '${wt}'    # do all work there; this checkout stays on ${default_branch}"
+  step "cd '${wt}'    # do all work there; this checkout stays on ${desk_branch}"
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/git.sh b/bin/git.sh
index 4dd85e6..3597230 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -9,8 +9,8 @@
 # runs in. --dry-run says what a sweep would do and changes nothing.
 #
 # git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto
-# origin/<default> and pushes it with --force-with-lease. It refuses the default branch, the human's desk, and
-# on a conflict aborts and leaves the worktree as it was.
+# origin/<default> and pushes it with --force-with-lease. It refuses the root checkout, the human's desk, whatever
+# branch it has, and the default branch anywhere. On a conflict it aborts and leaves the worktree as it was.
 
 # git:default-branch [<path>] prints the default branch of the repository at <path>: origin/HEAD, else main.
 git:default-branch() {
@@ -218,10 +218,15 @@ git:rebase() {
     error "${worktree} has no branch checked out, so there is nothing to rebase"
     return 1
   fi
+  if [[ "$(git -C "${worktree}" rev-parse --show-toplevel)" == "$(git:main-root "${worktree}")" ]]
+  then
+    error "refusing to rebase ${branch}: it is checked out at the root, the human's desk; work is rebased in its worktree"
+    return 1
+  fi
   default_branch=$(git:default-branch "${worktree}")
   if [[ "${branch}" == "${default_branch}" ]]
   then
-    error "refusing to rebase ${branch}: it is the default branch, the human's desk; it advances by: git pull --ff-only"
+    error "refusing to rebase ${branch}: it is the default branch; it advances by: git pull --ff-only"
     return 1
   fi
   section "kit rebase ${branch} onto origin/${default_branch}"
diff --git a/bin/kit-rebase.sh b/bin/kit-rebase.sh
index 649451c..e9e7e6e 100755
--- a/bin/kit-rebase.sh
+++ b/bin/kit-rebase.sh
@@ -2,7 +2,7 @@
 # kit-rebase - rebase a worktree's branch onto the default branch and push it (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Never the default branch itself.
+# Never the root checkout, the human's desk, and never the default branch.
 #
 # see: bin/git.sh
 
diff --git a/tests/rebase.bats b/tests/rebase.bats
index fbb922b..f02f194 100644
--- a/tests/rebase.bats
+++ b/tests/rebase.bats
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# rebase.bats - kit rebase refuses the default branch and brings a worktree's branch up to date
+# rebase.bats - kit rebase refuses the desk and the default branch, and brings a worktree's branch up to date
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -33,10 +33,22 @@ commit-in() {
   git -C "$1" commit --quiet --message "$2"
 }
 
-@test "rebase refuses the default branch" {
+@test "rebase refuses the root checkout, whatever branch it has" {
   run "${kit_checkout}/bin/kit" rebase
   [ "$status" -eq 1 ]
-  [[ "$output" == *"refusing to rebase main"* ]]
+  [[ "$output" == *"refusing to rebase main: it is checked out at the root"* ]]
+  git switch --quiet --create desk-topic
+  run "${kit_checkout}/bin/kit" rebase
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"refusing to rebase desk-topic: it is checked out at the root"* ]]
+}
+
+@test "rebase refuses the default branch in a worktree" {
+  git switch --quiet --create desk-topic
+  git worktree add --quiet ../wt main
+  run "${kit_checkout}/bin/kit" rebase ../wt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"refusing to rebase main: it is the default branch"* ]]
 }
 
 @test "rebase moves a worktree's branch onto origin/main and pushes it" {
diff --git a/tree/.kit/1st.md b/tree/.kit/1st.md
index cf4b2a1..1792650 100644
--- a/tree/.kit/1st.md
+++ b/tree/.kit/1st.md
@@ -14,11 +14,12 @@ the repository's own rules in `AGENTS.md` bind beside it. Where the two differ,
 5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
    written into a rule file or `AGENTS.md` through the loop, where every agent and every person reads it.
 
-## `main` is the human's desk
+## The root checkout is the human's desk
 
-The checkout at the repository root stays on the default branch. It is where the human types, reviews, and
-leaves work in progress. Never check out, reset, rebase, or otherwise change it in place. Work happens in a
-worktree under `worktrees/`, one per issue, and reaches `main` only through a merged pull request.
+The checkout at the repository root is the human's. It is where they type, review, and leave work in progress.
+It usually has `main` checked out, and may have any branch no worktree holds. An agent never checks out, resets,
+rebases, or otherwise changes it in place. Work happens in a worktree under `worktrees/`, one per issue, and
+reaches `main` only through a merged pull request.
 
 ## The loop
 
@@ -37,12 +38,12 @@ worktree under `worktrees/`, one per issue, and reaches `main` only through a me
 Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. The rule runs inside
 it, and a harness that can refuse the raw spelling does.
 
-- `kit rebase`, never `git rebase`. It refuses the default branch and otherwise rebases the worktree's branch onto
-  `origin/main` and pushes it.
+- `kit rebase`, never `git rebase`. It refuses the root checkout and the default branch, and otherwise rebases the
+  worktree's branch onto `origin/main` and pushes it.
 - `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
 - `kit tidy`, never `git worktree remove` or `git branch -D`.
 
-The human at the desk is not bound by this; `main` is theirs to rebase.
+The human at the desk is not bound by this; the root checkout is theirs.
 
 ## Plans are prose
 

From 3781843baff56c9f74d962fc999ee4f119a9ab0a Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 13:08:37 -0700
Subject: [PATCH 059/108] #1 bin/status.sh: the desk is a row of its own

Under the headline, before the sections, kit status draws the root checkout: its branch, how far it
has moved from where that branch left origin's default branch, the size of that diff, and its
uncommitted paths. The worktree row and the desk row are one function, told apart by glyph and
label.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/status.sh     | 24 ++++++++++++++++--------
 tests/status.bats | 14 +++++++++++---
 2 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/bin/status.sh b/bin/status.sh
index 7f31228..c7b4a58 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -6,7 +6,9 @@
 # GitHub once, for every open pull request with the issues it closes, its review threads, and the checks on its
 # head; everything else is a local git read.
 #
-# The picture is a headline counting the pull requests by state, then three sections, each omitted when empty:
+# The picture is a headline counting the pull requests by state; the desk, the root checkout, with its branch, how
+# far it has moved from where that branch left origin's default branch, the size of that diff, and its uncommitted
+# paths; then three sections, each omitted when empty:
 #
 #   pull requests  — every open pull request: its row, the issues it closes, and, when a worktree under worktrees/
 #                    holds its branch, up to ten of the commits it carries past its fork from the default branch
@@ -270,10 +272,11 @@ status:check-cell() {
   return 0
 }
 
-# status:worktree-alone <path> <branch> <title-width> <main-root> <default-branch> prints a worktree with no open
-# pull request as a row: its path, a mark when it is detached, and its divergence.
-status:worktree-alone() {
-  local path=$1 branch=$2 title_w=$3 main_root=$4 default_branch=$5 mark='' fork='' counts
+# status:checkout-row <glyph> <label> <path> <branch> <title-width> <default-branch> prints a checkout with no pull
+# request row of its own as one row: the glyph, the label in the title column, a mark when it is detached, its
+# divergence, and its uncommitted paths. The desk is drawn with 🏠 and its branch; a worktree with 🌿 and its path.
+status:checkout-row() {
+  local glyph=$1 label=$2 path=$3 branch=$4 title_w=$5 default_branch=$6 mark='' fork='' counts
   if [[ -n "${branch}" ]]
   then
     fork=$(status:fork "${branch}" "${default_branch}")
@@ -282,7 +285,7 @@ status:worktree-alone() {
   fi
   counts=$(status:divergence "${path}" "${branch}" "${fork}" "${default_branch}")
   # shellcheck disable=SC2086  # the four counts are tab-separated words
-  printf '🌿 %s   %s%s%s\n' "$(status:cell "${path#"${main_root}"/}" "${title_w}")" "${mark}" \
+  printf '%s %s   %s%s%s\n' "${glyph}" "$(status:cell "${label}" "${title_w}")" "${mark}" \
     "$(status:paint-counts ${counts})" "$(status:uncommitted "${path}")" >&2
 }
 
@@ -345,6 +348,8 @@ status:render() {
   main_root=$(git:main-root)
   default_branch=$(git:default-branch)
   records=$(status:collect)
+  local desk_branch
+  desk_branch=$(git -C "${main_root}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
 
   # The linked worktrees: by branch, and the detached ones.
   local -A worktree_of=()
@@ -388,6 +393,7 @@ status:render() {
     path=${path#"${main_root}"/}
     (( ${#path} > title_w )) && title_w=${#path}
   done
+  (( ${#desk_branch} > title_w )) && title_w=${#desk_branch}
   local avail
   avail=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - check_w - 3 - 16 ))
   (( avail < 20 )) && avail=20
@@ -399,6 +405,7 @@ status:render() {
   else
     out:emit '📋' '1' "${count} open pull request$( (( count == 1 )) || printf s) · $(status:badges "${states[@]}")"
   fi
+  status:checkout-row '🏠' "${desk_branch:-HEAD}" "${main_root}" "${desk_branch}" "${title_w}" "${default_branch}"
 
   # Every pull request, with its worktree when one here holds its branch.
   if (( count > 0 ))
@@ -424,11 +431,12 @@ status:render() {
     while IFS=$'\t' read -r _ branch
     do
       [[ -n "${branch}" ]] || continue
-      status:worktree-alone "${worktree_of[${branch}]}" "${branch}" "${title_w}" "${main_root}" "${default_branch}"
+      path=${worktree_of[${branch}]}
+      status:checkout-row '🌿' "${path#"${main_root}"/}" "${path}" "${branch}" "${title_w}" "${default_branch}"
     done < <(status:by-number "${lone[@]}")
     for path in "${detached_paths[@]}"
     do
-      status:worktree-alone "${path}" '' "${title_w}" "${main_root}" "${default_branch}"
+      status:checkout-row '🌿' "${path#"${main_root}"/}" "${path}" '' "${title_w}" "${default_branch}"
     done
   fi
 
diff --git a/tests/status.bats b/tests/status.bats
index c48139a..a118a69 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# status.bats - the parts of the picture that need no GitHub: a cell, the commit list, and a worktree's row
+# status.bats - the parts of the picture that need no GitHub: a cell, the commit list, and a checkout's row
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -51,7 +51,7 @@ in_status() {
   git worktree add --quiet -b topic worktrees/topic main
   printf 'two\nthree\n' > worktrees/topic/b && git -C worktrees/topic add b && git -C worktrees/topic commit --quiet --message two
   printf 'four\n' > c && git add c && git commit --quiet --message four && git push --quiet origin main
-  run in_status status:worktree-alone "${PWD}/worktrees/topic" topic 20 "${PWD}" main
+  run in_status status:checkout-row 🌿 worktrees/topic "${PWD}/worktrees/topic" topic 20 main
   [ "$status" -eq 0 ]
   [ "$output" = "🌿 worktrees/topic        ↑1 ↓1 · +2 -0" ]
 }
@@ -59,7 +59,15 @@ in_status() {
 @test "a detached worktree is marked, and a dirty one counts its uncommitted paths" {
   git worktree add --quiet --detach worktrees/loose main
   printf 'x\n' > worktrees/loose/x
-  run in_status status:worktree-alone "${PWD}/worktrees/loose" '' 16 "${PWD}" main
+  run in_status status:checkout-row 🌿 worktrees/loose "${PWD}/worktrees/loose" '' 16 main
   [ "$status" -eq 0 ]
   [ "$output" = "🌿 worktrees/loose    ❗ detached HEAD   ↑0 ↓0 · +0 -0 · 1 uncommitted" ]
 }
+
+@test "the desk row shows its branch, its unpushed commits, and its uncommitted paths" {
+  printf 'two\n' > b && git add b && git commit --quiet --message two
+  printf 'x\n' > c
+  run in_status status:checkout-row 🏠 main "${PWD}" main 4 main
+  [ "$status" -eq 0 ]
+  [ "$output" = "🏠 main   ↑1 ↓0 · +1 -0 · 1 uncommitted" ]
+}

From 73903e9fa68263f057fc5528d4e8ab2a353a99e2 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 23:34:44 -0700
Subject: [PATCH 060/108] #1 bin/status.sh: the desk first, every worktree with
 its commits, then the pull requests; --json

Three groups of blocks with a blank line between and no headings. The desk and each worktree are
one shape: the label, which is the path from the current directory with the branch underlined or
"branch on path", then ahead, behind, lines, and uncommitted paths, then the commits past the fork
with the oldest kept. A pull request is its row, the issues it closes, and the worktree holding its
branch, with no commit list. Everything that is detail is dim. --json prints the same facts as one
document: desk, worktrees, pullRequests, goneBranches. Each measured checkout is a JSON object
first, and the table is drawn from those, so the two outputs cannot disagree.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/kit-status.sh |   2 +-
 bin/status.sh     | 488 ++++++++++++++++++++++------------------------
 tests/status.bats |  85 +++++---
 3 files changed, 297 insertions(+), 278 deletions(-)

diff --git a/bin/kit-status.sh b/bin/kit-status.sh
index a0c04a3..dc47e5c 100755
--- a/bin/kit-status.sh
+++ b/bin/kit-status.sh
@@ -11,7 +11,7 @@ use status
 
 if [[ "${1:-}" == --help ]]
 then
-  echo "usage: kit status [--no-fetch]" >&2
+  echo "usage: kit status [--no-fetch] [--json]" >&2
   exit 0
 fi
 
diff --git a/bin/status.sh b/bin/status.sh
index c7b4a58..b9f9e72 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -2,25 +2,29 @@
 # status.sh - the picture of the work in flight (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# status:render [--no-fetch] prints the open pull requests and the linked worktrees, and changes nothing. It asks
+# status:render [--no-fetch] [--json] prints the checkouts and the open pull requests, and changes nothing. It asks
 # GitHub once, for every open pull request with the issues it closes, its review threads, and the checks on its
 # head; everything else is a local git read.
 #
-# The picture is a headline counting the pull requests by state; the desk, the root checkout, with its branch, how
-# far it has moved from where that branch left origin's default branch, the size of that diff, and its uncommitted
-# paths; then three sections, each omitted when empty:
+# The picture is three groups of blocks, a blank line between blocks and no headings:
 #
-#   pull requests  — every open pull request: its row, the issues it closes, and, when a worktree under worktrees/
-#                    holds its branch, up to ten of the commits it carries past its fork from the default branch
-#                    and the worktree with how far that has moved from the fork and the size of its diff.
-#   worktrees      — every worktree under worktrees/ with no open pull request, with the same measures.
-#   gone branches  — every local branch whose upstream is gone, which kit tidy removes.
+#   🏠 the desk        the root checkout, the human's. Its branch, then how far it has moved from where that branch
+#                      left origin's default branch, the lines its working tree adds and removes against that point,
+#                      and its uncommitted paths; under it the commits it carries past that point, dim hash and
+#                      subject, up to ten with the rest counted.
+#   🌿 each worktree   under worktrees/, by issue number, drawn exactly as the desk is. The label is the path from
+#                      the current directory with the branch underlined when the path ends in it, or "branch on
+#                      path" when it does not.
+#   🔀 each pull request  its title, its state with the state's glyph, its age, its checks (how many passed and how
+#                      long they took, or which failed), and its unresolved review threads when there are any; under
+#                      it the issues it closes and the worktree that holds its branch, when one here does.
 #
-# A row is the title, the state with its glyph, the age, the checks, and, when there are any, the unresolved review
-# threads. Every state has its own glyph, so a row is recognizable without reading the token. Color is by family,
-# never by state: green when nothing is left to decide, yellow when a human owes a decision, blue when the next move
-# is a machine's or a reviewer's, dim when someone already owns the work, and every timing is dim. The state is the
-# first of these that holds:
+# Then every local branch whose upstream is gone, which kit tidy removes, each on a 🔖 line.
+#
+# Color is by family, never by state: green when nothing is left to decide, yellow when a human owes a decision,
+# blue when the next move is a machine's or a reviewer's, dim when someone already owns the work. Everything that
+# is detail rather than signal is dim: hashes, ages, durations, zero counts, directory prefixes, and the lines under
+# a row. The state is the first of these that holds:
 #
 #   draft              🔨  dim     unfinished work that belongs to someone
 #   queued             🚦  blue    a check is still running
@@ -30,10 +34,13 @@
 #   comments:open      💬  yellow  unresolved review threads
 #   blocked:approval   👀  blue    a review is required or requested and has not arrived
 #   ready              🛬  green   green, thread-free, approved, and mergeable
+#
+# --json prints the same facts as one document instead: {desk, worktrees, pullRequests, goneBranches}, every
+# measure a number and every list complete, for a consumer that draws its own picture.
 
 use git
 
-# status_commit_cap is how many commits a block lists before eliding the rest.
+# status_commit_cap is how many commits a block lists before counting the rest.
 status_commit_cap=10
 
 # status:width prints the terminal's width in columns: COLUMNS, else the terminal on stderr, else 100.
@@ -96,10 +103,23 @@ status:state-emoji() {
   esac
 }
 
-# status:collect prints one record per open pull request, oldest first, with the fields separated by the unit
-# separator: number, branch, title, state, age, check glyph, check text, how long the checks took, the count of
-# unresolved review threads, and the issues it closes as "#n title" separated by the record separator. The one
-# request to GitHub.
+# status:age <seconds> prints a duration in its coarsest informative unit: 45s, 12m, 3h, 47d.
+status:age() {
+  local secs=$1
+  (( secs < 0 )) && secs=0
+  if (( secs < 120 ))
+  then printf '%ds' "${secs}"
+  elif (( secs < 7200 ))
+  then printf '%dm' $(( secs / 60 ))
+  elif (( secs < 172800 ))
+  then printf '%dh' $(( secs / 3600 ))
+  else printf '%dd' $(( secs / 86400 ))
+  fi
+}
+
+# status:collect prints one JSON object per open pull request, oldest first: number, branch, title, createdAt, age
+# in seconds, state, checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes
+# [{number, title}]. The one request to GitHub.
 status:collect() {
   local repo query filter
   repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || return 0
@@ -122,8 +142,6 @@ status:collect() {
   }'
   # shellcheck disable=SC2016  # a jq filter, with jq variables
   filter='
-    def age: if . < 120 then "\(.)s" elif . < 7200 then "\(. / 60 | floor)m"
-             elif . < 172800 then "\(. / 3600 | floor)h" else "\(. / 86400 | floor)d" end;
     def verdict: if .__typename == "CheckRun" then (if .status == "COMPLETED" then .conclusion else "PENDING" end)
                  else .state end;
     def pending: IN("PENDING", "EXPECTED");
@@ -139,14 +157,10 @@ status:collect() {
       as $check
     | ([$checks[] | .startedAt // .createdAt // empty | fromdateiso8601] | min) as $started
     | ([$checks[] | .completedAt // empty | fromdateiso8601] | max) as $completed
-    | (if $started == null then ""
-       elif $check == "PENDING" then (($now - $started) | age)
-       elif $completed == null then ""
-       else (($completed - $started) | age) end) as $took
-    | (if $check == "SUCCESS" then ["✅", "\($n) / \($n)"]
-       elif $check == "FAILURE" then ["❌", "\($failing) · \($ok) / \($n)"]
-       elif $check == "PENDING" then ["🏃", "\($n - $running) / \($n)"]
-       else ["", ""] end) as $cell
+    | (if $started == null then null
+       elif $check == "PENDING" then $now - $started
+       elif $completed == null then null
+       else $completed - $started end) as $took
     | ([.reviewThreads.nodes[]? | select(.isResolved | not)] | length) as $unresolved
     | (if .isDraft then "draft"
        elif $check == "PENDING" then "queued"
@@ -156,11 +170,11 @@ status:collect() {
        elif $unresolved > 0 then "comments:open"
        elif (.reviewDecision // "") | IN("REVIEW_REQUIRED", "CHANGES_REQUESTED") then "blocked:approval"
        else "ready" end) as $state
-    | [ (.number | tostring), .headRefName, .title, $state,
-        (($now - (.createdAt | fromdateiso8601)) | age),
-        $cell[0], $cell[1], (if $cell[1] == "" then "" else $took end), ($unresolved | tostring),
-        ([.closingIssuesReferences.nodes[] | "#\(.number) \(.title)"] | join("\u001e")) ]
-    | join("\u001f")'
+    | { number, branch: .headRefName, title, createdAt, age: ($now - (.createdAt | fromdateiso8601)), state: $state,
+        checks: { state: $check, passed: $ok, total: $n, failing: $failing, took: $took },
+        unresolved: $unresolved,
+        closes: [.closingIssuesReferences.nodes[] | { number, title }] }
+    | tojson'
   gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
     2>/dev/null || true
 }
@@ -170,11 +184,35 @@ status:fork() {
   git merge-base "origin/$2" "$1" 2>/dev/null || git merge-base "$2" "$1" 2>/dev/null || true
 }
 
-# status:divergence <path> <branch> <fork> prints "<ahead>\t<behind>\t<added>\t<removed>": the commits on <branch>
-# past <fork>, the commits on the default branch past it, and the lines the working tree at <path> adds and removes
-# against it. A detached checkout has no branch and no fork, and measures its lines against its own head.
-status:divergence() {
-  local path=$1 branch=$2 fork=$3 default_branch=$4 ahead=0 behind=0 added=0 removed=0 a r _
+# status:relative <path> prints <path> relative to the current directory: ".", a descent, or a climb.
+status:relative() {
+  local target=$1 here=${PWD} up=''
+  if [[ "${target}" == "${here}" ]]
+  then
+    printf '.\n'
+    return 0
+  fi
+  while [[ -n "${here}" && "${target}" != "${here}" && "${target}" != "${here}"/* ]]
+  do
+    here=${here%/*}
+    up+='../'
+  done
+  if [[ "${target}" == "${here}" ]]
+  then
+    printf '%s\n' "${up%/}"
+  else
+    printf '%s%s\n' "${up}" "${target#"${here}"/}"
+  fi
+}
+
+# status:checkout <path> <branch> <default-branch> prints one JSON object measuring the checkout at <path>: path,
+# relative, branch (empty when detached), detached, ahead of and behind the point where the branch left origin's
+# default branch, the lines the working tree adds and removes against that point, the count of uncommitted paths,
+# and the commits past that point as [{sha, subject}]. A detached checkout measures its lines against its own head
+# and lists no commits.
+status:checkout() {
+  local path=$1 branch=$2 default_branch=$3 fork='' ahead=0 behind=0 added=0 removed=0 uncommitted a r _
+  [[ -n "${branch}" ]] && fork=$(status:fork "${branch}" "${default_branch}")
   if [[ -n "${fork}" ]]
   then
     ahead=$(git rev-list --count "${fork}..${branch}" 2>/dev/null || printf 0)
@@ -185,159 +223,131 @@ status:divergence() {
     [[ -n "${a}" && "${a}" != '-' ]] && added=$(( added + a ))
     [[ -n "${r}" && "${r}" != '-' ]] && removed=$(( removed + r ))
   done < <(git -C "${path}" diff --numstat "${fork:-HEAD}" 2>/dev/null || true)
-  printf '%s\t%s\t%s\t%s\n' "${ahead}" "${behind}" "${added}" "${removed}"
+  uncommitted=$(git -C "${path}" status --porcelain | grep --count . || true)
+  {
+    [[ -n "${fork}" ]] && git -C "${path}" log --format='%h%x09%s' "${fork}..${branch}" 2>/dev/null
+    true
+  } | jq --raw-input --slurp --compact-output \
+    --arg path "${path}" --arg relative "$(status:relative "${path}")" --arg branch "${branch}" \
+    --argjson ahead "${ahead}" --argjson behind "${behind}" --argjson added "${added}" --argjson removed "${removed}" \
+    --argjson uncommitted "${uncommitted}" '
+    { path: $path, relative: $relative, branch: $branch, detached: ($branch == ""),
+      ahead: $ahead, behind: $behind, added: $added, removed: $removed, uncommitted: $uncommitted,
+      commits: [split("\n")[] | select(. != "") | split("\t") | { sha: .[0], subject: (.[1:] | join("\t")) }] }'
 }
 
-# status:paint-counts <ahead> <behind> <added> <removed> prints "↑a ↓b · +x -y": a non-zero count in bold green or
-# bold red, a zero dim.
-status:paint-counts() {
-  local ahead=$1 behind=$2 added=$3 removed=$4
-  printf '%s %s · %s %s' \
-    "$(status:paint-count "${ahead}" '↑' '1;32')" "$(status:paint-count "${behind}" '↓' '1;31')" \
-    "$(status:paint-count "${added}" '+' '1;32')" "$(status:paint-count "${removed}" '-' '1;31')"
+# status:label <relative> <branch> prints the label of a checkout and its plain width, tab-separated: the path with
+# the directory dim and the branch underlined when the path's last component is the branch or ends in "-<branch>",
+# the branch alone at ".", or "branch on path" otherwise. A detached checkout is its path.
+status:label() {
+  local relative=$1 branch=$2 dir
+  if [[ -z "${branch}" ]]
+  then
+    printf '%s\t%s\n' "${relative}" "${#relative}"
+  elif [[ "${relative}" == "." ]]
+  then
+    printf '%s\t%s\n' "${branch}" "${#branch}"
+  elif [[ "${relative##*/}" == "${branch}" || "${relative##*/}" == *"-${branch}" ]]
+  then
+    dir=${relative%"${branch}"}
+    printf '%s%s\t%s\n' "$(status:paint 90 "${dir}")" "$(status:paint 4 "${branch}")" "${#relative}"
+  else
+    printf '%s %s %s\t%s\n' "${branch}" "$(status:paint 90 on)" "${relative}" $(( ${#branch} + 4 + ${#relative} ))
+  fi
 }
 
-# status:paint-count <count> <sign> <sgr> prints <sign><count>, in <sgr> when the count is above zero and dim otherwise.
+# status:paint-count <count> <sign> <sgr> prints <sign><count>, in <sgr> above zero and dim at zero.
 status:paint-count() {
   local count=$1 sign=$2 sgr=$3
   (( count > 0 )) || sgr=90
   status:paint "${sgr}" "${sign}${count}"
 }
 
-# status:commits <path> <range> prints the commits in <range>, dim hash then subject, indented under a row. Past
-# status_commit_cap, the first commits, a dim "… and N more", and the oldest.
-status:commits() {
-  local path=$1 range=$2 line total hidden=0 i
-  local -a commits=()
-  mapfile -t commits < <(git -C "${path}" log --format='%h %s' "${range}" 2>/dev/null || true)
-  total=${#commits[@]}
-  (( total > status_commit_cap + 1 )) && hidden=$(( total - status_commit_cap ))
-  for (( i = 0; i < total; i++ ))
+# status:measures <checkout-json> prints "↑a ↓b · +x -y", and " · n uncommitted" in yellow when n is above zero.
+status:measures() {
+  local ahead behind added removed uncommitted
+  IFS=$'\t' read -r ahead behind added removed uncommitted \
+    < <(jq --raw-output '[.ahead, .behind, .added, .removed, .uncommitted] | @tsv' <<<"$1")
+  printf '%s %s · %s %s' "$(status:paint-count "${ahead}" '↑' '1;32')" "$(status:paint-count "${behind}" '↓' '1;31')" \
+    "$(status:paint-count "${added}" '+' '1;32')" "$(status:paint-count "${removed}" '-' '1;31')"
+  (( uncommitted > 0 )) && printf ' · %s' "$(status:paint 33 "${uncommitted} uncommitted")"
+  return 0
+}
+
+# status:checkout-block <glyph> <checkout-json> <label-width> prints a checkout: its row, then its commits, dim
+# hash and subject. Past status_commit_cap it prints the newest, a dim count of the hidden, and the oldest.
+status:checkout-block() {
+  local glyph=$1 doc=$2 label_w=$3 relative branch label width mark='' sha subject
+  IFS=$'\x1f' read -r relative branch < <(jq --raw-output '[.relative, .branch] | join("\u001f")' <<<"${doc}")
+  IFS=$'\t' read -r label width < <(status:label "${relative}" "${branch}")
+  [[ -n "${branch}" ]] || mark="   $(status:paint 33 '❗ detached HEAD')"
+  printf '%s %s%*s%s   %s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" "$(status:measures "${doc}")" >&2
+  while IFS=$'\t' read -r sha subject
   do
-    if (( hidden > 0 && i == status_commit_cap - 1 ))
+    [[ -n "${sha}" ]] || continue
+    if [[ "${sha}" == '…' ]]
     then
-      printf '   %s\n' "$(status:paint 90 "… and ${hidden} more")" >&2
-      i=$(( total - 2 ))
-      continue
+      printf '   %s\n' "$(status:paint 90 "… ${subject}")" >&2
+    else
+      printf '   %s %s\n' "$(status:paint 90 "${sha}")" "${subject}" >&2
     fi
-    line=${commits[i]}
-    printf '   %s %s\n' "$(status:paint 90 "${line%% *}")" "${line#* }" >&2
-  done
+  done < <(jq --raw-output --argjson cap "${status_commit_cap}" '
+    (.commits | length) as $n
+    | (if $n > $cap + 1
+       then (.commits[:$cap - 1][] | [.sha, .subject]), ["…", "and \($n - $cap) more"], (.commits[-1] | [.sha, .subject])
+       else .commits[] | [.sha, .subject] end)
+    | @tsv' <<<"${doc}")
 }
 
-# status:pr-block <record> <title-width> <state-width> <age-width> <check-width> <path> <main-root> <default-branch>
-# prints one pull request: its row, the issues it closes, and, when <path> names its worktree, the commits it
-# carries past its fork and the worktree's line.
-status:pr-block() {
-  local title_w=$2 state_w=$3 age_w=$4 check_w=$5 path=$6 main_root=$7 default_branch=$8
-  local number branch title state age glyph check took unresolved issues issue row fork counts
-  IFS=$'\x1f' read -r number branch title state age glyph check took unresolved issues <<<"$1"
-  row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
-  row+="   $(status:state-emoji "${state}") $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
-  row+="   $(status:paint 90 "$(status:cell "${age}" "${age_w}")")"
-  if (( unresolved > 0 ))
-  then
-    row+="   $(status:check-cell "${glyph}" "${check}" "${took}" "${check_w}")   $(status:paint 33 "💬 ${unresolved} unresolved")"
-  elif [[ -n "${glyph}" ]]
-  then
-    row+="   $(status:check-cell "${glyph}" "${check}" "${took}" 0)"
-  fi
-  printf '%s\n' "${row}" >&2
-  if [[ -n "${issues}" ]]
-  then
-    while IFS= read -r issue
-    do
-      printf '   %s\n' "$(status:paint 90 "closes ${issue}")" >&2
-    done < <(tr '\036' '\n' <<<"${issues}")
-  fi
-  [[ -n "${path}" ]] || return 0
-  fork=$(status:fork "${branch}" "${default_branch}")
-  [[ -n "${fork}" ]] && status:commits "${path}" "${fork}..${branch}"
-  counts=$(status:divergence "${path}" "${branch}" "${fork}" "${default_branch}")
-  # shellcheck disable=SC2086  # the four counts are tab-separated words
-  printf '   🌿 %s   %s%s\n' "$(status:paint 90 "${path#"${main_root}"/}")" "$(status:paint-counts ${counts})" \
-    "$(status:uncommitted "${path}")" >&2
-}
-
-# status:check-cell <glyph> <text> <took> <width> prints the checks as "<glyph> <text> · <took>", the duration dim,
-# padded to <width> characters when something follows it; nothing when no check has reported.
+# status:check-cell <checks-json> prints the checks as "✅ <passed> / <total> · <took>", the duration dim, or
+# "❌ <failing> · <passed> / <total> · <took>", or "🏃 <passed> / <total> · <elapsed>"; nothing when none has
+# reported.
 status:check-cell() {
-  local glyph=$1 text=$2 took=$3 width=$4 plain=''
-  if [[ -n "${glyph}" ]]
-  then
-    plain="${glyph} ${text}${took:+ · ${took}}"
-    printf '%s %s%s' "${glyph}" "${text}" "${took:+ · $(status:paint 90 "${took}")}"
-  fi
-  (( ${#plain} < width )) && printf '%*s' $(( width - ${#plain} )) ''
+  local state passed total failing took text
+  # A field here can be empty, and a tab read collapses an empty field, so the separator is one that cannot.
+  IFS=$'\x1f' read -r state passed total failing took \
+    < <(jq --raw-output '[.state, .passed, .total, .failing, (.took // "")] | map(tostring) | join("\u001f")' <<<"$1")
+  case "${state}" in
+    (SUCCESS) text="✅ ${total} / ${total}" ;;
+    (FAILURE) text="❌ ${failing} · ${passed} / ${total}" ;;
+    (PENDING) text="🏃 ${passed} / ${total}" ;;
+    (*) return 0 ;;
+  esac
+  printf '%s' "${text}"
+  [[ -n "${took}" ]] && printf ' · %s' "$(status:paint 90 "$(status:age "${took}")")"
   return 0
 }
 
-# status:checkout-row <glyph> <label> <path> <branch> <title-width> <default-branch> prints a checkout with no pull
-# request row of its own as one row: the glyph, the label in the title column, a mark when it is detached, its
-# divergence, and its uncommitted paths. The desk is drawn with 🏠 and its branch; a worktree with 🌿 and its path.
-status:checkout-row() {
-  local glyph=$1 label=$2 path=$3 branch=$4 title_w=$5 default_branch=$6 mark='' fork='' counts
-  if [[ -n "${branch}" ]]
-  then
-    fork=$(status:fork "${branch}" "${default_branch}")
-  else
-    mark="$(status:paint 33 '❗ detached HEAD')   "
-  fi
-  counts=$(status:divergence "${path}" "${branch}" "${fork}" "${default_branch}")
-  # shellcheck disable=SC2086  # the four counts are tab-separated words
-  printf '%s %s   %s%s%s\n' "${glyph}" "$(status:cell "${label}" "${title_w}")" "${mark}" \
-    "$(status:paint-counts ${counts})" "$(status:uncommitted "${path}")" >&2
-}
-
-# status:uncommitted <path> prints " · n uncommitted" for a dirty checkout, nothing for a clean one.
-status:uncommitted() {
-  git:clean "$1" && return 0
-  printf ' · %s' "$(status:paint 33 "$(git -C "$1" status --porcelain | grep --count .) uncommitted")"
-}
-
-# status:by-number <branch>… prints "<number>\t<branch>" for each branch whose worktree directory opens with an issue
-# number, 0 for one that does not, sorted by that number.
-status:by-number() {
-  local branch dir number
-  for branch in "$@"
-  do
-    dir=${worktree_of[${branch}]##*/}
-    number=${dir%%-*}
-    [[ "${number}" =~ ^[0-9]+$ ]] || number=0
-    printf '%s\t%s\n' "${number}" "${branch}"
-  done | sort -n -k1,1
-}
-
-# status:badges <state>… prints "<glyph> <count>" per state, most populous first.
-status:badges() {
-  local -A tally=()
-  local state count out=''
-  for state in "$@"
-  do
-    tally[${state}]=$(( ${tally[${state}]:-0} + 1 ))
-  done
-  while IFS=$'\t' read -r count state
+# status:pr-block <pr-json> <title-width> <state-width> <age-width> <worktree-relative> prints a pull request: its
+# row, the issues it closes, and the worktree here that holds its branch, when one does.
+status:pr-block() {
+  local doc=$1 title_w=$2 state_w=$3 age_w=$4 worktree=$5 number title state age unresolved row issue checks
+  IFS=$'\t' read -r number title state age unresolved \
+    < <(jq --raw-output '[.number, .title, .state, .age, .unresolved] | @tsv' <<<"${doc}")
+  row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
+  row+="   $(status:state-emoji "${state}") $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
+  row+="   $(status:paint 90 "$(status:cell "$(status:age "${age}")" "${age_w}")")"
+  checks=$(status:check-cell "$(jq --compact-output .checks <<<"${doc}")")
+  [[ -n "${checks}" ]] && row+="   ${checks}"
+  (( unresolved > 0 )) && row+="   $(status:paint 33 "💬 ${unresolved} unresolved")"
+  printf '%s\n' "${row}" >&2
+  while IFS= read -r issue
   do
-    out+="${out:+  }$(status:state-emoji "${state}") ${count}"
-  done < <(
-    for state in "${!tally[@]}"
-    do
-      printf '%s\t%s\n' "${tally[${state}]}" "${state}"
-    done | sort -t$'\t' -k1,1nr -k2,2
-  )
-  printf '%s' "${out}"
+    [[ -n "${issue}" ]] && printf '   %s\n' "$(status:paint 90 "closes ${issue}")" >&2
+  done < <(jq --raw-output '.closes[] | "#\(.number) \(.title)"' <<<"${doc}")
+  [[ -n "${worktree}" ]] && printf '   %s\n' "$(status:paint 90 "🌿 ${worktree}")" >&2
+  return 0
 }
 
 status:render() {
-  local no_fetch=false arg main_root default_branch records path branch record
+  local no_fetch=false json=false arg main_root default_branch desk_branch path branch doc gone
   for arg in "$@"
   do
     case "${arg}" in
-      (--no-fetch)
-        no_fetch=true
-        ;;
+      (--no-fetch) no_fetch=true ;;
+      (--json) json=true ;;
       (*)
-        error "unknown flag '${arg}' (only --no-fetch is recognized)"
+        error "unknown flag '${arg}' (usage: kit status [--no-fetch] [--json])"
         return 2
     esac
   done
@@ -347,109 +357,87 @@ status:render() {
   fi
   main_root=$(git:main-root)
   default_branch=$(git:default-branch)
-  records=$(status:collect)
-  local desk_branch
   desk_branch=$(git -C "${main_root}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+  gone=$(git:gone-branches)
 
-  # The linked worktrees: by branch, and the detached ones.
-  local -A worktree_of=()
-  local -a detached_paths=()
+  # The desk, the worktrees by issue number, and the pull requests, each as JSON.
+  local desk prs
+  local -a worktrees=()
+  desk=$(status:checkout "${main_root}" "${desk_branch}" "${default_branch}")
   while IFS=$'\t' read -r path branch _
   do
     [[ -n "${path}" ]] || continue
-    if [[ -n "${branch}" ]]
-    then
-      worktree_of[${branch}]=${path}
-    else
-      detached_paths+=("${path}")
-    fi
-  done < <(git:worktrees)
-
-  # The rows, and the width of each column across them.
-  local -a rows=() states=()
-  local -A pr_on=()
-  local number title state age glyph check took unresolved issues count=0 state_w=0 age_w=0 check_w=0 title_w=0 issue
-  while IFS= read -r record
-  do
-    [[ -n "${record}" ]] || continue
-    IFS=$'\x1f' read -r number branch title state age glyph check took unresolved issues <<<"${record}"
-    rows+=("${record}")
-    states+=("${state}")
-    pr_on[${branch}]=1
-    (( ${#state} > state_w )) && state_w=${#state}
-    (( ${#age} > age_w )) && age_w=${#age}
-    check="${glyph:+${glyph} ${check}${took:+ · ${took}}}"
-    (( ${#check} + 1 > check_w )) && check_w=$(( ${#check} + 1 ))
-    title="#${number} ${title}"
-    (( ${#title} > title_w )) && title_w=${#title}
-    while IFS= read -r issue
-    do
-      (( ${#issue} > title_w )) && title_w=${#issue}
-    done < <(tr '\036' '\n' <<<"${issues}")
-  done <<<"${records}"
-  count=${#rows[@]}
-  for path in "${worktree_of[@]}" "${detached_paths[@]}"
-  do
-    path=${path#"${main_root}"/}
-    (( ${#path} > title_w )) && title_w=${#path}
-  done
-  (( ${#desk_branch} > title_w )) && title_w=${#desk_branch}
-  local avail
-  avail=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - check_w - 3 - 16 ))
-  (( avail < 20 )) && avail=20
-  (( title_w > avail )) && title_w=${avail}
-
-  if (( count == 0 ))
-  then
-    out:emit '📋' '1' 'no open pull requests'
-  else
-    out:emit '📋' '1' "${count} open pull request$( (( count == 1 )) || printf s) · $(status:badges "${states[@]}")"
-  fi
-  status:checkout-row '🏠' "${desk_branch:-HEAD}" "${main_root}" "${desk_branch}" "${title_w}" "${default_branch}"
+    worktrees+=("$(status:checkout "${path}" "${branch}" "${default_branch}")")
+  done < <(git:worktrees | status:by-number)
+  prs=$(status:collect)
 
-  # Every pull request, with its worktree when one here holds its branch.
-  if (( count > 0 ))
+  if [[ "${json}" == true ]]
   then
-    section "pull requests"
-    for record in "${rows[@]}"
-    do
-      IFS=$'\x1f' read -r _ branch _ <<<"${record}"
-      status:pr-block "${record}" "${title_w}" "${state_w}" "${age_w}" "${check_w}" "${worktree_of[${branch}]:-}" \
-        "${main_root}" "${default_branch}"
-    done
+    jq --null-input --argjson desk "${desk}" \
+      --argjson worktrees "$(printf '%s\n' "${worktrees[@]}" | jq --slurp .)" \
+      --argjson pullRequests "$(jq --slurp . <<<"${prs}")" \
+      --argjson goneBranches "$(jq --raw-input . <<<"${gone}" | jq --slurp 'map(select(. != ""))')" \
+      '{ desk: $desk, worktrees: $worktrees, pullRequests: $pullRequests, goneBranches: $goneBranches }'
+    return 0
   fi
 
-  # The worktrees with no pull request, by issue number, then the detached ones.
-  local -a lone=()
-  for branch in "${!worktree_of[@]}"
+  # Column widths across the rows that share a column.
+  local label_w=0 width title_w=0 state_w=0 age_w=0 text state_text age_secs relative
+  local -A worktree_on=()
+  for doc in "${desk}" "${worktrees[@]}"
   do
-    [[ -n "${pr_on[${branch}]:-}" ]] || lone+=("${branch}")
+    IFS=$'\x1f' read -r relative branch < <(jq --raw-output '[.relative, .branch] | join("\u001f")' <<<"${doc}")
+    IFS=$'\t' read -r _ width < <(status:label "${relative}" "${branch}")
+    (( width > label_w )) && label_w=${width}
+    [[ -n "${branch}" && "${doc}" != "${desk}" ]] && worktree_on[${branch}]=${relative}
   done
-  if (( ${#lone[@]} + ${#detached_paths[@]} > 0 ))
-  then
-    section "worktrees with no open pull request"
-    while IFS=$'\t' read -r _ branch
-    do
-      [[ -n "${branch}" ]] || continue
-      path=${worktree_of[${branch}]}
-      status:checkout-row '🌿' "${path#"${main_root}"/}" "${path}" "${branch}" "${title_w}" "${default_branch}"
-    done < <(status:by-number "${lone[@]}")
-    for path in "${detached_paths[@]}"
-    do
-      status:checkout-row '🌿' "${path#"${main_root}"/}" "${path}" '' "${title_w}" "${default_branch}"
-    done
-  fi
+  while IFS=$'\t' read -r text state_text age_secs
+  do
+    [[ -n "${text}" ]] || continue
+    (( ${#text} > title_w )) && title_w=${#text}
+    (( ${#state_text} > state_w )) && state_w=${#state_text}
+    text=$(status:age "${age_secs}")
+    (( ${#text} > age_w )) && age_w=${#text}
+  done < <(jq --raw-output '["#\(.number) \(.title)", .state, .age] | @tsv' <<<"${prs}")
+  width=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - 24 ))
+  (( width < 20 )) && width=20
+  (( title_w > width )) && title_w=${width}
 
-  local gone
-  gone=$(git:gone-branches)
+  status:checkout-block '🏠' "${desk}" "${label_w}"
+  for doc in "${worktrees[@]}"
+  do
+    printf '\n' >&2
+    status:checkout-block '🌿' "${doc}" "${label_w}"
+  done
+  while IFS= read -r doc
+  do
+    [[ -n "${doc}" ]] || continue
+    printf '\n' >&2
+    branch=$(jq --raw-output .branch <<<"${doc}")
+    status:pr-block "${doc}" "${title_w}" "${state_w}" "${age_w}" "${worktree_on[${branch}]:-}"
+  done <<<"${prs}"
   if [[ -n "${gone}" ]]
   then
-    section "branches whose upstream is gone (tidy removes these)"
+    printf '\n' >&2
     while IFS= read -r branch
     do
-      info "${branch}"
+      printf '🔖 %s   %s\n' "${branch}" "$(status:paint 90 'upstream gone · kit tidy removes it')" >&2
     done <<<"${gone}"
   fi
 }
 
+# status:by-number sorts git:worktrees lines by the issue number their directory opens with; a directory that
+# opens with no number sorts first.
+status:by-number() {
+  local path rest dir number
+  while IFS=$'\t' read -r path rest
+  do
+    [[ -n "${path}" ]] || continue
+    dir=${path##*/}
+    number=${dir%%-*}
+    [[ "${number}" =~ ^[0-9]+$ ]] || number=0
+    printf '%s\t%s\t%s\n' "${number}" "${path}" "${rest}"
+  done | sort -n -k1,1 | cut -f2-
+}
+
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/status.bats b/tests/status.bats
index a118a69..1f6569f 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -1,5 +1,6 @@
 #!/usr/bin/env bats
-# status.bats - the parts of the picture that need no GitHub: a cell, the commit list, and a checkout's row
+# status.bats - the parts of the picture that need no GitHub: a cell, a checkout's measures and block, its label,
+# and its path from the current directory
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -25,6 +26,15 @@ in_status() {
   bash -c 'source "${kit_root}/bin/1st.sh" && use status && "$@"' _ "$@"
 }
 
+# commits-in <path> <n> makes <n> commits in the checkout at <path>.
+commits-in() {
+  local i
+  for (( i = 1; i <= $2; i++ ))
+  do
+    printf '%s\n' "${i}" > "$1/f${i}" && git -C "$1" add . && git -C "$1" commit --quiet --message "c${i}"
+  done
+}
+
 @test "a cell is padded to its width, or clipped with an ellipsis" {
   run in_status status:cell abc 5
   [ "$output" = "abc  " ]
@@ -32,42 +42,63 @@ in_status() {
   [ "$output" = "abcd…" ]
 }
 
-@test "the commit list shows the newest, says how many are hidden, and ends with the oldest" {
-  git worktree add --quiet -b topic worktrees/topic main
-  for i in $(seq 1 15)
-  do
-    printf '%s\n' "${i}" > "worktrees/topic/f${i}" && git -C worktrees/topic add . && git -C worktrees/topic commit --quiet --message "c${i}"
-  done
-  run in_status status:commits "${PWD}/worktrees/topic" main..topic
-  [ "$status" -eq 0 ]
-  [ "${#lines[@]}" -eq 11 ]
-  [[ "${lines[0]}" == *" c15" ]]
-  [[ "${lines[8]}" == *" c7" ]]
-  [[ "${lines[9]}" == *"… and 5 more" ]]
-  [[ "${lines[10]}" == *" c1" ]]
-}
-
-@test "a worktree with no pull request shows its distance from main and the size of its diff" {
+@test "a checkout is measured from where its branch left origin's default branch" {
   git worktree add --quiet -b topic worktrees/topic main
   printf 'two\nthree\n' > worktrees/topic/b && git -C worktrees/topic add b && git -C worktrees/topic commit --quiet --message two
   printf 'four\n' > c && git add c && git commit --quiet --message four && git push --quiet origin main
-  run in_status status:checkout-row 🌿 worktrees/topic "${PWD}/worktrees/topic" topic 20 main
+  printf 'x\n' > worktrees/topic/x
+  run in_status status:checkout "${PWD}/worktrees/topic" topic main
   [ "$status" -eq 0 ]
-  [ "$output" = "🌿 worktrees/topic        ↑1 ↓1 · +2 -0" ]
+  [ "$(jq -r '[.relative, .branch, .ahead, .behind, .added, .removed, .uncommitted, (.commits | length)] | @tsv' <<<"$output")" \
+    = "$(printf 'worktrees/topic\ttopic\t1\t1\t2\t0\t1\t1')" ]
 }
 
-@test "a detached worktree is marked, and a dirty one counts its uncommitted paths" {
-  git worktree add --quiet --detach worktrees/loose main
-  printf 'x\n' > worktrees/loose/x
-  run in_status status:checkout-row 🌿 worktrees/loose "${PWD}/worktrees/loose" '' 16 main
+@test "a block shows the newest commits, counts the hidden ones, and ends with the oldest" {
+  git worktree add --quiet -b topic worktrees/topic main
+  commits-in worktrees/topic 15
+  doc=$(in_status status:checkout "${PWD}/worktrees/topic" topic main)
+  run in_status status:checkout-block 🌿 "${doc}" 15
   [ "$status" -eq 0 ]
-  [ "$output" = "🌿 worktrees/loose    ❗ detached HEAD   ↑0 ↓0 · +0 -0 · 1 uncommitted" ]
+  [ "${lines[0]}" = "🌿 worktrees/topic   ↑15 ↓0 · +15 -0" ]
+  [ "${#lines[@]}" -eq 12 ]
+  [[ "${lines[1]}" == *" c15" ]]
+  [[ "${lines[9]}" == *" c7" ]]
+  [[ "${lines[10]}" == *"… and 5 more" ]]
+  [[ "${lines[11]}" == *" c1" ]]
 }
 
-@test "the desk row shows its branch, its unpushed commits, and its uncommitted paths" {
+@test "the desk block is its branch, its unpushed commits, and its uncommitted paths" {
   printf 'two\n' > b && git add b && git commit --quiet --message two
   printf 'x\n' > c
-  run in_status status:checkout-row 🏠 main "${PWD}" main 4 main
+  doc=$(in_status status:checkout "${PWD}" main main)
+  run in_status status:checkout-block 🏠 "${doc}" 4
   [ "$status" -eq 0 ]
-  [ "$output" = "🏠 main   ↑1 ↓0 · +1 -0 · 1 uncommitted" ]
+  [ "${lines[0]}" = "🏠 main   ↑1 ↓0 · +1 -0 · 1 uncommitted" ]
+  [[ "${lines[1]}" == *" two" ]]
+}
+
+@test "a detached checkout is marked and lists no commits" {
+  git worktree add --quiet --detach worktrees/loose main
+  doc=$(in_status status:checkout "${PWD}/worktrees/loose" '' main)
+  run in_status status:checkout-block 🌿 "${doc}" 15
+  [ "$output" = "🌿 worktrees/loose   ❗ detached HEAD   ↑0 ↓0 · +0 -0" ]
+}
+
+@test "a label is the path when the branch ends it, the branch at the current directory, or branch on path" {
+  run in_status status:label worktrees/topic topic
+  [ "$output" = "$(printf 'worktrees/topic\t15')" ]
+  run in_status status:label . main
+  [ "$output" = "$(printf 'main\t4')" ]
+  run in_status status:label ../other topic
+  [ "$output" = "$(printf 'topic on ../other\t17')" ]
+}
+
+@test "a path is printed relative to the current directory" {
+  run in_status status:relative "${PWD}"
+  [ "$output" = "." ]
+  run in_status status:relative "${PWD}/worktrees/topic"
+  [ "$output" = "worktrees/topic" ]
+  cd worktrees
+  run in_status status:relative "${PWD%/worktrees}"
+  [ "$output" = ".." ]
 }

From 216cb360f4faebb2753288fc14feccb13d7e2521 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sat, 24 Oct 2026 23:44:13 -0700
Subject: [PATCH 061/108] #1 bin/status.sh: the counts of every checkout in
 columns, so the dots align

Ahead and added are right-aligned, behind and removed left-aligned, each in a column as wide as the
widest value across the desk and the worktrees. Padding is by character, since the arrows are
multibyte and printf's field width counts bytes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/status.sh     | 55 ++++++++++++++++++++++++++++++++++++-----------
 tests/status.bats | 11 ++++++++++
 2 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/bin/status.sh b/bin/status.sh
index b9f9e72..0e4077f 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -256,32 +256,59 @@ status:label() {
   fi
 }
 
-# status:paint-count <count> <sign> <sgr> prints <sign><count>, in <sgr> above zero and dim at zero.
+# status:paint-count <count> <sign> <sgr> <width> <side> prints <sign><count> padded to <width> characters on the
+# left or the right, in <sgr> above zero and dim at zero. The padding is by character, since the arrows are
+# multibyte and printf's field width counts bytes.
 status:paint-count() {
-  local count=$1 sign=$2 sgr=$3
+  local count=$1 sign=$2 sgr=$3 width=$4 side=$5 text pad=''
   (( count > 0 )) || sgr=90
-  status:paint "${sgr}" "${sign}${count}"
+  text="${sign}${count}"
+  (( ${#text} < width )) && printf -v pad '%*s' $(( width - ${#text} )) ''
+  if [[ "${side}" == right ]]
+  then
+    printf '%s%s' "${pad}" "$(status:paint "${sgr}" "${text}")"
+  else
+    printf '%s%s' "$(status:paint "${sgr}" "${text}")" "${pad}"
+  fi
 }
 
-# status:measures <checkout-json> prints "↑a ↓b · +x -y", and " · n uncommitted" in yellow when n is above zero.
+# status:measures <checkout-json> [<widths>] prints "↑a ↓b · +x -y", and " · n uncommitted" in yellow when n is
+# above zero. <widths> is status:count-widths' line; with it, ahead and added are right-aligned and behind and
+# removed left-aligned in columns of those widths, so the dots of every row fall under each other.
 status:measures() {
-  local ahead behind added removed uncommitted
+  local ahead behind added removed uncommitted ahead_w=0 behind_w=0 added_w=0 removed_w=0
   IFS=$'\t' read -r ahead behind added removed uncommitted \
     < <(jq --raw-output '[.ahead, .behind, .added, .removed, .uncommitted] | @tsv' <<<"$1")
-  printf '%s %s · %s %s' "$(status:paint-count "${ahead}" '↑' '1;32')" "$(status:paint-count "${behind}" '↓' '1;31')" \
-    "$(status:paint-count "${added}" '+' '1;32')" "$(status:paint-count "${removed}" '-' '1;31')"
+  [[ -n "${2:-}" ]] && IFS=' ' read -r ahead_w behind_w added_w removed_w <<<"$2"
+  # The last column is padded only when something follows it, so no row ends in blanks.
+  (( uncommitted > 0 )) || removed_w=0
+  printf '%s %s · %s %s' \
+    "$(status:paint-count "${ahead}" '↑' '1;32' "${ahead_w}" right)" \
+    "$(status:paint-count "${behind}" '↓' '1;31' "${behind_w}" left)" \
+    "$(status:paint-count "${added}" '+' '1;32' "${added_w}" right)" \
+    "$(status:paint-count "${removed}" '-' '1;31' "${removed_w}" left)"
   (( uncommitted > 0 )) && printf ' · %s' "$(status:paint 33 "${uncommitted} uncommitted")"
   return 0
 }
 
-# status:checkout-block <glyph> <checkout-json> <label-width> prints a checkout: its row, then its commits, dim
-# hash and subject. Past status_commit_cap it prints the newest, a dim count of the hidden, and the oldest.
+# status:count-widths <checkout-json>… prints the widest "↑a", "↓b", "+x", and "-y" across the checkouts, as four
+# numbers on one line.
+status:count-widths() {
+  printf '%s\n' "$@" | jq --raw-output --slurp '
+    [ (map(.ahead) | max), (map(.behind) | max), (map(.added) | max), (map(.removed) | max) ]
+    | map(tostring | length + 1) | join(" ")'
+}
+
+# status:checkout-block <glyph> <checkout-json> <label-width> [<widths>] prints a checkout: its row, with the
+# counts in status:count-widths' columns, then its commits, dim hash and subject. Past status_commit_cap it prints
+# the newest, a dim count of the hidden, and the oldest.
 status:checkout-block() {
-  local glyph=$1 doc=$2 label_w=$3 relative branch label width mark='' sha subject
+  local glyph=$1 doc=$2 label_w=$3 widths=${4:-} relative branch label width mark='' sha subject
   IFS=$'\x1f' read -r relative branch < <(jq --raw-output '[.relative, .branch] | join("\u001f")' <<<"${doc}")
   IFS=$'\t' read -r label width < <(status:label "${relative}" "${branch}")
   [[ -n "${branch}" ]] || mark="   $(status:paint 33 '❗ detached HEAD')"
-  printf '%s %s%*s%s   %s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" "$(status:measures "${doc}")" >&2
+  printf '%s %s%*s%s   %s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" \
+    "$(status:measures "${doc}" "${widths}")" >&2
   while IFS=$'\t' read -r sha subject
   do
     [[ -n "${sha}" ]] || continue
@@ -403,11 +430,13 @@ status:render() {
   (( width < 20 )) && width=20
   (( title_w > width )) && title_w=${width}
 
-  status:checkout-block '🏠' "${desk}" "${label_w}"
+  local widths
+  widths=$(status:count-widths "${desk}" "${worktrees[@]}")
+  status:checkout-block '🏠' "${desk}" "${label_w}" "${widths}"
   for doc in "${worktrees[@]}"
   do
     printf '\n' >&2
-    status:checkout-block '🌿' "${doc}" "${label_w}"
+    status:checkout-block '🌿' "${doc}" "${label_w}" "${widths}"
   done
   while IFS= read -r doc
   do
diff --git a/tests/status.bats b/tests/status.bats
index 1f6569f..92ec1f8 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -84,6 +84,17 @@ commits-in() {
   [ "$output" = "🌿 worktrees/loose   ❗ detached HEAD   ↑0 ↓0 · +0 -0" ]
 }
 
+@test "the counts of every checkout sit in columns, ahead and added right-aligned, behind and removed left-aligned" {
+  one=$(jq -nc '{ahead: 1, behind: 22, added: 3, removed: 4444, uncommitted: 0}')
+  two=$(jq -nc '{ahead: 100, behind: 2, added: 30000, removed: 4, uncommitted: 2}')
+  widths=$(in_status status:count-widths "${one}" "${two}")
+  [ "${widths}" = "4 3 6 5" ]
+  run in_status status:measures "${one}" "${widths}"
+  [ "$output" = "  ↑1 ↓22 ·     +3 -4444" ]
+  run in_status status:measures "${two}" "${widths}"
+  [ "$output" = "↑100 ↓2  · +30000 -4    · 2 uncommitted" ]
+}
+
 @test "a label is the path when the branch ends it, the branch at the current directory, or branch on path" {
   run in_status status:label worktrees/topic topic
   [ "$output" = "$(printf 'worktrees/topic\t15')" ]

From 3209e512082967fdf29fb2640ac34284c7dbcdd7 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 00:56:05 -0700
Subject: [PATCH 062/108] #4 modules: the release as modules, and a file's
 rules found through kit context

Everything the release delivers is a module under modules/<name>/: a module file of metadata
(description, default, depends, answer), a tree/ mirrored at the consumer's root, templates/
rendered from the consumer's .kit/answers with @key@ keys, and docs/. kit install activates the
default modules and the named ones with their dependencies; kit module list, add, and remove change
the set, and remove refuses a module another active module depends on. The manifest records the set
on a modules line. The resolver is the closure over depends, ordered by tsort.

A rule lives once and is copied nowhere. kit context <path> names the rules governing a file by the
paths: globs and content: first-line patterns in its frontmatter, and logs every ask under the git
directory. kit context --claude answers in Claude Code's hook protocol, a rule's text once per
session and its path after that. The claude module merges the deny list and that hook into
.claude/settings.json and delivers no rule mirror; this repository's .claude/rules/kit-*.md copies
are removed by the refresh.

The ci module renders its workflow from a template with one answer, ci_runner. docs/modules.md and
docs/context.md describe the two mechanisms, and each module has a docs/README.md. The release
workflow packs bin/ and modules/. 35 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/rules/kit-bash.md                     |  50 ----
 .claude/rules/kit-gitignore.md                |  30 ---
 .claude/rules/kit-json.md                     |  27 ---
 .claude/rules/kit-just.md                     |  58 -----
 .claude/rules/kit-markdown.md                 |  53 ----
 .claude/rules/kit-yaml.md                     |  35 ---
 .claude/settings.json                         |  13 +
 .github/workflows/kit-ci.yml                  |   3 +-
 .github/workflows/release.yml                 |   6 +-
 .kit/1st.md                                   |  37 ++-
 .kit/manifest                                 |  18 +-
 .kit/rules/bash.md                            |   2 +
 .kit/rules/just.md                            |   2 +
 AGENTS.md                                     |   8 +-
 README.md                                     |  36 +--
 bin/context.sh                                | 170 +++++++++++++
 bin/kit                                       |  12 +-
 bin/kit-check.sh                              |   7 +-
 bin/kit-context.sh                            |  24 ++
 bin/kit-install.sh                            |  18 +-
 bin/kit-module.sh                             |  82 +++++++
 bin/kit-target.sh                             |  82 -------
 bin/kit-update.sh                             |  16 +-
 bin/release.sh                                | 227 +++++++++++++++---
 docs/context.md                               |  50 ++++
 docs/modules.md                               |  61 +++++
 justfile                                      |   8 +-
 modules/ci/docs/README.md                     |   7 +
 modules/ci/module                             |   8 +
 .../templates}/.github/workflows/kit-ci.yml   |   5 +-
 modules/claude/docs/README.md                 |  10 +
 modules/claude/module                         |   6 +
 .../claude/tree}/.claude/settings.json        |  13 +
 modules/kit/docs/README.md                    |  11 +
 modules/kit/module                            |   6 +
 {tree => modules/kit/tree}/.kit/1st.md        |  37 ++-
 {tree => modules/kit/tree}/.kit/rules/bash.md |   2 +
 .../kit/tree}/.kit/rules/gitignore.md         |   0
 {tree => modules/kit/tree}/.kit/rules/json.md |   0
 {tree => modules/kit/tree}/.kit/rules/just.md |   2 +
 .../kit/tree}/.kit/rules/markdown.md          |   0
 {tree => modules/kit/tree}/.kit/rules/yaml.md |   0
 modules/lefthook/docs/README.md               |   5 +
 modules/lefthook/module                       |   7 +
 .../lefthook/tree}/.kit/lefthook.yml          |   0
 targets/claude/.claude/rules/kit-bash.md      |   1 -
 targets/claude/.claude/rules/kit-gitignore.md |   1 -
 targets/claude/.claude/rules/kit-json.md      |   1 -
 targets/claude/.claude/rules/kit-just.md      |   1 -
 targets/claude/.claude/rules/kit-markdown.md  |   1 -
 targets/claude/.claude/rules/kit-yaml.md      |   1 -
 tests/context.bats                            |  62 +++++
 tests/kit.bats                                | 113 +++++----
 tests/release.bats                            |   6 +-
 54 files changed, 906 insertions(+), 535 deletions(-)
 delete mode 100644 .claude/rules/kit-bash.md
 delete mode 100644 .claude/rules/kit-gitignore.md
 delete mode 100644 .claude/rules/kit-json.md
 delete mode 100644 .claude/rules/kit-just.md
 delete mode 100644 .claude/rules/kit-markdown.md
 delete mode 100644 .claude/rules/kit-yaml.md
 create mode 100644 bin/context.sh
 create mode 100755 bin/kit-context.sh
 create mode 100755 bin/kit-module.sh
 delete mode 100755 bin/kit-target.sh
 create mode 100644 docs/context.md
 create mode 100644 docs/modules.md
 create mode 100644 modules/ci/docs/README.md
 create mode 100644 modules/ci/module
 rename {tree => modules/ci/templates}/.github/workflows/kit-ci.yml (97%)
 create mode 100644 modules/claude/docs/README.md
 create mode 100644 modules/claude/module
 rename {targets/claude => modules/claude/tree}/.claude/settings.json (54%)
 create mode 100644 modules/kit/docs/README.md
 create mode 100644 modules/kit/module
 rename {tree => modules/kit/tree}/.kit/1st.md (76%)
 rename {tree => modules/kit/tree}/.kit/rules/bash.md (98%)
 rename {tree => modules/kit/tree}/.kit/rules/gitignore.md (100%)
 rename {tree => modules/kit/tree}/.kit/rules/json.md (100%)
 rename {tree => modules/kit/tree}/.kit/rules/just.md (98%)
 rename {tree => modules/kit/tree}/.kit/rules/markdown.md (100%)
 rename {tree => modules/kit/tree}/.kit/rules/yaml.md (100%)
 create mode 100644 modules/lefthook/docs/README.md
 create mode 100644 modules/lefthook/module
 rename {tree => modules/lefthook/tree}/.kit/lefthook.yml (100%)
 delete mode 120000 targets/claude/.claude/rules/kit-bash.md
 delete mode 120000 targets/claude/.claude/rules/kit-gitignore.md
 delete mode 120000 targets/claude/.claude/rules/kit-json.md
 delete mode 120000 targets/claude/.claude/rules/kit-just.md
 delete mode 120000 targets/claude/.claude/rules/kit-markdown.md
 delete mode 120000 targets/claude/.claude/rules/kit-yaml.md
 create mode 100644 tests/context.bats

diff --git a/.claude/rules/kit-bash.md b/.claude/rules/kit-bash.md
deleted file mode 100644
index 33b1128..0000000
--- a/.claude/rules/kit-bash.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
-paths:
-  - "**/*.sh"
-  - "**/*.bash"
----
-# Bash
-
-Applies to `*.sh` and `*.bash`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
-workflows.
-
-## Shape
-
-1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
-   rule of dashes to column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
-2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
-   would change the caller's.
-3. The file closes with the same rule of dashes.
-
-## Style
-
-1. `then`, `do`, and `else` go on their own line, never after a semicolon.
-2. Spell `set` options out: `set -o errexit`, never `set -e`.
-3. Spell a tool's options out where every platform accepts the long form: `--raw-output`, `--field`,
-   `--quiet`. Where BSD and GNU differ, use the form both accept, which is the short one: `sed -n`, `head -n 1`,
-   `mkdir -p`, `rm -f`, `cut -d`, `cp -R`, `find -type`, `read -r`, and `git -C`.
-4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
-5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
-6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
-7. Quote every expansion outside `[[ ]]` and `(( ))`.
-8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
-   loader's own verbs are the exception and stay bare: `use`, `info`, `step`, `ok`, `section`, `warn`, `error`.
-9. A function private to one executed script is bare kebab-case.
-
-## Behavior
-
-1. An error message is one line, names the remedy first, and is the same wherever the same condition arises.
-2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
-3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
-4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
-5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
-   to do, and a `--dry-run` where the mutation is a sweep.
-6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
-7. shellcheck passes with no directive, or the directive carries the reason on the same line.
-
-## Comments
-
-1. A comment states what the code does and the non-obvious why. It carries no history and defends no obvious
-   choice.
-2. A pointer is `# see: <ref>`, on its own line after the comment it supports.
diff --git a/.claude/rules/kit-gitignore.md b/.claude/rules/kit-gitignore.md
deleted file mode 100644
index 7465b65..0000000
--- a/.claude/rules/kit-gitignore.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
-paths:
-  - ".gitignore"
-  - "**/.gitignore"
----
-# Ignore lists
-
-Applies to `.gitignore` at any depth.
-
-## Shape
-
-1. The file opens with `# .gitignore - untracked files and folders`, a rule of dashes to column 120, and a
-   blank line.
-2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
-   line.
-3. The file closes with a rule of dashes.
-
-## Entries
-
-1. Every entry names a file the repository itself produces. Editor and operating-system files belong in the
-   user's global ignore list, not here.
-2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
-   repository.
-3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
-4. `worktrees/` is ignored at the root: it is where the loop checks out a branch per issue.
-
-## Adding one
-
-Ask what produces the file. If nothing in the repository does, do not add it.
diff --git a/.claude/rules/kit-json.md b/.claude/rules/kit-json.md
deleted file mode 100644
index 692c8aa..0000000
--- a/.claude/rules/kit-json.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
-paths:
-  - "**/*.json"
-  - "**/*.jsonc"
----
-# JSON
-
-Applies to `*.json` and `*.jsonc`.
-
-## Shape
-
-1. Two-space indentation. Keys in a stable order: the order the consuming tool documents, else alphabetical.
-2. One trailing newline. No trailing commas in `.json`.
-3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where
-   it reads plain JSON, the reason for a setting lives in the document that describes the file.
-
-## Settings
-
-1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
-2. A tool's settings file that the kit writes into is merged by key. The kit owns only the keys and entries
-   it writes, and anything else in the file is the repository's.
-
-## Comments
-
-1. A comment states what the entry does and the non-obvious why. It carries no history.
-2. A pointer is `// see: <ref>`.
diff --git a/.claude/rules/kit-just.md b/.claude/rules/kit-just.md
deleted file mode 100644
index d91dd1f..0000000
--- a/.claude/rules/kit-just.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
-paths:
-  - "justfile"
-  - "**/justfile"
-  - "**/*.just"
----
-# Just
-
-Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
-applies to it as well.
-
-## Shape
-
-1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120,
-   and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
-   --justfile` shebang above that; a module does not.
-2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), and `set positional-arguments := true`. `set export := true` comes after the
-   default-and-help pair, so that pair reads the same in every justfile.
-3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
-
-   ```just
-   # This file's own path, assigned at parse time so the body below needs no interpolation.
-   export <name>_justfile := source_file()
-
-   # Default recipe: list this justfile's recipes.
-   _: help
-
-   # List recipes in this justfile.
-   [no-exit-message]
-   @help *options:
-     just --justfile "${<name>_justfile}" --list
-   ```
-
-4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
-   the invoking root rather than the module's directory.
-5. The file closes with a rule of dashes.
-
-## Recipes
-
-1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
-2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
-   recipe does, when to run it, and what it produces.
-3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
-4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
-5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
-   variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
-   `${name}` and nothing else.
-6. Two-space indentation inside a body. Never a tab.
-7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
-8. Comments wrap at 118 columns. Bodies do not wrap.
-
-## Invocation
-
-1. The idiom is the space form, `just tools check`, never `just tools/check` and never `tools::check` outside a
-   dependency list.
-2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/.claude/rules/kit-markdown.md b/.claude/rules/kit-markdown.md
deleted file mode 100644
index d830ce3..0000000
--- a/.claude/rules/kit-markdown.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
-paths:
-  - "**/*.md"
----
-# Markdown
-
-Applies to `*.md`.
-
-## Prose
-
-1. Write plain declarative sentences with the thing under discussion as the subject.
-2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
-3. Use a list where the content is a list, and for a procedure or a loop, so it scans. Use a table where the
-   content has columns.
-4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
-5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
-6. Use the serial comma in every list of three or more.
-7. Expand an uncommon acronym the first time it appears.
-8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
-   when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
-
-## Snippets
-
-1. A value the reader supplies is a shell variable the prose names, `"${signing_key}"`, never an angle-bracket
-   placeholder, so the block pastes after one export.
-2. Where a reader may lack a prerequisite, link the page that creates it beside the command that uses it.
-
-## Layout
-
-1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
-   per nesting level, to a limit of 12.
-2. Balance the wrap: no line, in particular the last, reads as a stub.
-3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
-4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
-5. Headings are ATX (`#`). One `#` heading per file, at the top.
-6. Fenced code blocks declare a language and have a blank line on each side.
-7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
-
-## Links
-
-1. Use inline links with descriptive text, never a bare URL in angle brackets.
-2. Use the same anchor text every time the same URL appears in a file.
-3. When a label and the link text would say the same thing, make the label the link.
-4. A relative link resolves from the file that carries it, and it resolves: a check reads them.
-
-## Files
-
-1. Name an index file `1st.md`. It lists its siblings and says what each is for.
-2. A file says what its subject is in its first paragraph, before how to use it.
-3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
-   what the repository is.
-4. No file names another repository as the source of a rule.
diff --git a/.claude/rules/kit-yaml.md b/.claude/rules/kit-yaml.md
deleted file mode 100644
index 3e5795c..0000000
--- a/.claude/rules/kit-yaml.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
-paths:
-  - "**/*.yml"
-  - "**/*.yaml"
----
-# YAML
-
-Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
-
-## Shape
-
-1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
-   reader would not guess from the keys.
-2. Two-space indentation. No tabs. No trailing whitespace.
-3. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
-4. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
-   breaks the requirement.
-5. `permissions` is declared at the top and names the least the jobs need.
-
-## Steps
-
-1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
-2. A step has a `name` that is the policy it enforces, in kebab-case.
-3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>`, writes `### ❌ <Message>` and a remedy to `${GITHUB_STEP_SUMMARY}`,
-   and returns non-zero. The remedy is the action to take, with a link that is that action.
-5. A pass writes one `✅` line to the summary.
-6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
-
-## Comments
-
-1. A comment states the non-obvious why. It carries no history.
-2. A pointer is `# see: <ref>`.
diff --git a/.claude/settings.json b/.claude/settings.json
index fde98cf..5beeca9 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -1,4 +1,17 @@
 {
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kit context --claude"
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "deny": [
       "Bash(git checkout main *)",
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 3cf9a98..72b648a 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -6,7 +6,8 @@
 # open issue of this repository under Development. The last two run even when an earlier step refused, so one
 # run reports every finding.
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. Rendered from a template: the
+# job runs on the ci_runner answer, ubuntu-latest unless .kit/answers says otherwise.
 #
 # see: .kit/1st.md
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b78d5a6..e208617 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,8 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, tree/, targets/, and a
-# stamped version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A
+# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, modules/, and a stamped
+# version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A
 # release, v<major>.<minor>.<patch>, is tagged on main, any commit on main and not only its head. A pre-release,
 # the same with a -<suffix>, is tagged on a commit that is not on main and is published as a GitHub pre-release.
 # The tag is the version: the repository carries no version file, and the one in the packed kit is stamped here
@@ -67,7 +67,7 @@ jobs:
           version=${GITHUB_REF_NAME#v}
           staging=$(mktemp --directory)
           mkdir "${staging}/kit-${version}"
-          cp --recursive --no-dereference bin tree targets "${staging}/kit-${version}/"
+          cp --recursive --no-dereference bin modules "${staging}/kit-${version}/"
           # the packed kit's version is the tag's, suffix included
           printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
diff --git a/.kit/1st.md b/.kit/1st.md
index 1792650..0d4fc49 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -67,10 +67,10 @@ A worker is whoever implements one issue in the worktree that issue names.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`, and each rule file's `paths:` header names the paths it
-binds. A harness that loads rules by path gets a copy in its own rules directory when the repository takes that
-target: `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of that
-kind.
+Each file kind has a rule file under `.kit/rules/`, and each rule file's header names what it governs: `paths:`,
+globs on the repository path, and `content:`, patterns on the first line. Before you create or change a file, run
+`kit context <path>`. It names the rules that govern the file and records that you asked. Read what it names. No
+harness holds a copy of a rule; this call is how every harness, and every person, finds it.
 
 | Kind | Rule |
 | --- | --- |
@@ -84,22 +84,21 @@ kind.
 ## What the kit carries
 
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
-release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
-carries the machinery, reached through the `kit` command on `PATH`. A release mirrors its `tree/` at the
-repository root, and `targets/<name>/` for each target taken. A `.json` destination is merged by key; everything
-else is copied as it is.
-
-- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, and `kit lint`, spelled that way and
-  no other.
-- `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
+release version, the active modules, and a checksum per delivered file. The release, where it is installed,
+carries the machinery, reached through the `kit` command on `PATH`. Everything the release delivers is a module,
+and a repository activates the modules it takes: `kit install claude`, or `kit module add claude` later, and
+`kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning only the entries
+it writes; everything else is copied as it is.
+
+- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled
+  that way and no other.
+- `kit`: this file and the rules, discovered through `kit context`.
+- `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
-- Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
-  it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
-  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
-  The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
-  back out.
-- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`, runs `kit check`, and refuses
-  a pull request not linked to an open issue.
+- `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
+  refuses a pull request not linked to an open issue.
+- `claude`: for Claude Code, seven deny rules merged into `.claude/settings.json`, and a hook that runs
+  `kit context` before every write so the rules reach the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/manifest b/.kit/manifest
index 0723404..5697a2c 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,19 +1,13 @@
 # .kit/manifest - written by kit, not by hand
 version unreleased
-targets claude
-b7f7f37d89165d6364fbb4e91c0c637eeb26fa72391a76f3419926efb7923522  .claude/rules/kit-bash.md
-0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .claude/rules/kit-gitignore.md
-1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .claude/rules/kit-json.md
-edcd5198f76362ef2890f2dfa5ca2df1a81bce27864dc7c19fd64a683e040e23  .claude/rules/kit-just.md
-15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .claude/rules/kit-markdown.md
-03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .claude/rules/kit-yaml.md
-100646bca2e00429393e788cf2b7f09121216feb551144ece67890dc40932e86  .claude/settings.json
-f03e0fa3ae07c74235558bffc38d5cb24c388c7c440e469cf8a8e58604edfc4b  .github/workflows/kit-ci.yml
-d83f24086d807bf6e9c6ed55d0fd7d77aa130a5b41a3db41d806e4ce84918aa1  .kit/1st.md
+modules kit claude ci lefthook
+86563533cd11f87831320d57b24d68d83c8d3a47382b09afeb71f5ee46e93584  .claude/settings.json
+cd66dc3b7fe79643f0a706e0ea571962906ffd117743c68e23aadbab7c91e143  .github/workflows/kit-ci.yml
+f7db408e409f39c36c9906efbedfd800054a654b44615b021bd02fd93fa4d57e  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
-b7f7f37d89165d6364fbb4e91c0c637eeb26fa72391a76f3419926efb7923522  .kit/rules/bash.md
+6f1101c9b19bfbe2d42d6e602e92d0df4dc650a4a04ccbd06c5a03a5e6e5edc2  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
 1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
-edcd5198f76362ef2890f2dfa5ca2df1a81bce27864dc7c19fd64a683e040e23  .kit/rules/just.md
+f2610c647eb99c3951cfb2e079c8d2a19ea0ddd03bdb4cbf3dbfea89b414d3da  .kit/rules/just.md
 15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .kit/rules/markdown.md
 03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .kit/rules/yaml.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index 33b1128..e04e9b0 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -3,6 +3,8 @@
 paths:
   - "**/*.sh"
   - "**/*.bash"
+content:
+  - "^#!.*/(env +)?(ba)?sh( |$)"
 ---
 # Bash
 
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index d91dd1f..69f6620 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -4,6 +4,8 @@ paths:
   - "justfile"
   - "**/justfile"
   - "**/*.just"
+content:
+  - "^#!.*/(env +)?just( |$)"
 ---
 # Just
 
diff --git a/AGENTS.md b/AGENTS.md
index 536a177..c1f467d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,8 +10,8 @@ Read .kit/1st.md first. It is the kit's entry file, and this repository uses its
   not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
   published release is immutable, so a tag is never reused. A release is permanent; a pre-release is retired when
   the branch it was tagged on is deleted.
-- `.claude/rules/kit-*.md`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and `.kit/manifest` are
-  this repository's installed copies of its own kit, written by `just refresh` from `tree/` and `targets/`; see
-  [README.md](README.md) § Maintaining. Edit the source; the pre-commit hook refreshes the copies into the same
-  commit, and a desk without the hook runs `just refresh` and commits both.
+- `.kit/`, `.github/workflows/kit-ci.yml`, and `.claude/settings.json` are this repository's installed copies of its
+  own kit, written by `just refresh` from `modules/`; see [README.md](README.md) § Maintaining. Edit the source; the
+  pre-commit hook refreshes the copies into the same commit, and a desk without the hook runs `just refresh` and
+  commits both.
 - `just ci` is the gate; the justfile says what it runs.
diff --git a/README.md b/README.md
index ebbaafc..63080ea 100644
--- a/README.md
+++ b/README.md
@@ -69,12 +69,14 @@ kit install claude
 Read .kit/1st.md first.
 ```
 
-The rest of `AGENTS.md` is yours. `install` writes `.kit/`, the CI workflow, and the files of each target named;
-`claude` is the one target this release knows, and a repository with no target still binds every agent that
-reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the root justfile for the delivered `CI` job to
-run, and take the pre-commit linters by pinning `lefthook`, putting `extends: [.kit/lefthook.yml]` in
-`lefthook.yml`, and running `lefthook install` once per clone. `kit target add`, `kit target remove`, and
-`kit target list` change and show the targets later.
+The rest of `AGENTS.md` is yours. Everything the kit delivers is a module, and `install` activates the default
+ones, `kit`, `lefthook`, and `ci`, plus those named: `claude` is the adapter for Claude Code, and a repository
+with no adapter still binds every agent that reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the
+root justfile for the delivered `CI` job to run, and take the pre-commit linters by pinning `lefthook`, putting
+`extends: [.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit module list`,
+`kit module add`, and `kit module remove` show and change the set later, and [docs/modules.md](docs/modules.md)
+describes a module. An agent asks `kit context <path>` which rules govern a file before it creates or changes
+it; [docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
 
 To move to a new release, bump the pin or reinstall, then run `kit update`: a delivered file you left alone is
 replaced, one you edited is three-way merged with the previous release as the base, which `update` fetches from
@@ -117,23 +119,23 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 ## Maintaining
 
-This repository is both the source of the kit and a consumer of it. The release is the checkout: `tree/` is what
-every consumer gets, mirrored at its root; `targets/<name>/` is what a consumer taking that target gets, mirrored
-the same way; and `bin/` is the machinery, `bin/kit` dispatching to one executable `bin/kit-<verb>.sh` per verb,
-each sourcing the modules beside it. A symlink under `targets/` is delivered as the file it points at, so a rule
-lives once, in `tree/.kit/rules/`.
+This repository is both the source of the kit and a consumer of it. The release is the checkout: `modules/<name>/`
+is what a consumer activating that module gets, its `tree/` mirrored at the consumer's root and its `templates/`
+rendered from the consumer's answers first; `bin/` is the machinery, `bin/kit` dispatching to one executable
+`bin/kit-<verb>.sh` per verb, each sourcing the bash modules beside it; and `docs/` with each module's `docs/` is
+the documentation. [docs/modules.md](docs/modules.md) is the module format.
 
 The installed copies are written by `bin/kit install` and not edited by hand:
 
 | Installed copy | Written from |
 | --- | --- |
-| `.kit/1st.md`, `.kit/rules/`, `.kit/lefthook.yml` | `tree/.kit/` |
-| `.github/workflows/kit-ci.yml` | `tree/.github/workflows/kit-ci.yml` |
-| `.claude/rules/kit-<kind>.md` | `targets/claude/.claude/rules/`, links into `tree/.kit/rules/` |
-| `.claude/settings.json` | `targets/claude/.claude/settings.json`, merged by key; here only the kit's entries |
-| `.kit/manifest` | the release version (`unreleased` here), the targets taken, and a digest per delivered path |
+| `.kit/1st.md`, `.kit/rules/` | `modules/kit/tree/.kit/` |
+| `.kit/lefthook.yml` | `modules/lefthook/tree/.kit/lefthook.yml` |
+| `.github/workflows/kit-ci.yml` | `modules/ci/templates/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
+| `.claude/settings.json` | `modules/claude/tree/.claude/settings.json`, merged by key; here only the kit's entries |
+| `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
-A commit that changes a file under `tree/` or `targets/` rewrites the installed copies in the same commit: the
+A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the
 pre-commit hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk
 without the hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names
 any installed copy that no longer matches its source. Each delivered text file says in its header that it is
diff --git a/bin/context.sh b/bin/context.sh
new file mode 100644
index 0000000..975ff96
--- /dev/null
+++ b/bin/context.sh
@@ -0,0 +1,170 @@
+# shellcheck shell=bash
+# context.sh - which rules govern a file (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# context:render <path>… [--json] names the rule files under .kit/rules/ that govern each path, and records each
+# ask in the repository's context log. A rule's frontmatter declares what it governs: `paths:`, globs matched
+# against the repository-relative path, where ** stands for any depth; and `content:`, patterns matched against
+# the first line of a file that exists, so a bash script with no extension is bash by its shebang. The rules are
+# discovered here and copied nowhere, which is what lets every harness, and every person, find them the same way.
+#
+# context:claude is the same answer in Claude Code's hook protocol: the hook input on stdin, the rules as
+# additional context on stdout. The first time a rule is named in a session its text is given; after that, its
+# path. docs/context.md is the description.
+
+shopt -s extglob
+
+# context_log is where every ask is recorded, under the repository's git directory, shared by its worktrees.
+context:log-path() {
+  printf '%s/kit/context.log\n' "$(git rev-parse --path-format=absolute --git-common-dir)"
+}
+
+# context:frontmatter <file> <key> prints the items of the list under <key> in the file's frontmatter, unquoted.
+context:frontmatter() {
+  awk -v key="$2" '
+    NR == 1 && $0 != "---" { exit }
+    NR > 1 && $0 == "---" { exit }
+    $0 == key ":" { in_key = 1; next }
+    /^[a-z]+:/ { in_key = 0 }
+    in_key && /^  - / { item = $0; sub(/^  - /, "", item); gsub(/^"|"$/, "", item); print item }
+  ' "$1"
+}
+
+# context:relative <path> prints <path> relative to the repository root. A relative path is taken from the current
+# directory. The nearest directory of the path that exists is resolved physically, as git reports the root, so a
+# path through a symlinked directory, or to a file not yet created, still cuts at the root.
+context:relative() {
+  local path=$1 root dir rest
+  root=$(git rev-parse --show-toplevel)
+  [[ "${path}" == /* ]] || path="${PWD}/${path}"
+  dir=${path%/*}
+  rest=${path##*/}
+  while [[ -n "${dir}" && ! -d "${dir}" ]]
+  do
+    rest="${dir##*/}/${rest}"
+    dir=${dir%/*}
+  done
+  dir=$(cd "${dir:-/}" && pwd -P)
+  path="${dir}/${rest}"
+  printf '%s\n' "${path#"${root}"/}"
+}
+
+# context:glob-matches <path> <glob> is true when the repository-relative path matches the glob; ** is any depth.
+context:glob-matches() {
+  local path=$1 glob=$2
+  glob=${glob//\*\*\//*(*\/)}
+  glob=${glob//\*\*/*}
+  # shellcheck disable=SC2053  # the glob is the point
+  [[ "${path}" == ${glob} ]]
+}
+
+# context:rules <path> prints the rule files governing <path>, by its path or by its first line.
+context:rules() {
+  local path=$1 rule glob pattern first=''
+  [[ -f "${path}" ]] && first=$(head -n 1 "${path}" 2>/dev/null || true)
+  for rule in .kit/rules/*.md
+  do
+    [[ -f "${rule}" ]] || continue
+    # Read, never word-split: an unquoted glob would be expanded against the working tree before it is matched.
+    while IFS= read -r glob
+    do
+      [[ -n "${glob}" ]] || continue
+      if context:glob-matches "${path}" "${glob}"
+      then
+        printf '%s\n' "${rule}"
+        continue 2
+      fi
+    done < <(context:frontmatter "${rule}" paths)
+    [[ -n "${first}" ]] || continue
+    while IFS= read -r pattern
+    do
+      [[ -n "${pattern}" ]] || continue
+      if [[ "${first}" =~ ${pattern} ]]
+      then
+        printf '%s\n' "${rule}"
+        continue 2
+      fi
+    done < <(context:frontmatter "${rule}" content)
+  done
+}
+
+# context:log <path> records that the context of <path> was asked for.
+context:log() {
+  local log
+  log=$(context:log-path)
+  mkdir -p "$(dirname "${log}")"
+  printf '%s\t%s\n' "$(date +%s)" "$1" >> "${log}"
+}
+
+# context:render <path>… [--json] prints the rules governing the paths: once each, as paths to read; with --json,
+# one object per path with its rules.
+context:render() {
+  local json=false arg path rule
+  local -a paths=()
+  local -A seen=()
+  for arg in "$@"
+  do
+    case "${arg}" in
+      (--json) json=true ;;
+      (-*)
+        error "unknown flag '${arg}' (usage: kit context <path>… [--json] | kit context --claude)"
+        return 2
+        ;;
+      (*) paths+=("${arg}")
+    esac
+  done
+  if (( ${#paths[@]} == 0 ))
+  then
+    error "usage: kit context <path>… [--json] | kit context --claude"
+    return 2
+  fi
+  cd "$(git rev-parse --show-toplevel)" || return 1
+  for path in "${paths[@]}"
+  do
+    path=$(context:relative "${path}")
+    context:log "${path}"
+    if [[ "${json}" == true ]]
+    then
+      context:rules "${path}" | jq --raw-input --slurp --compact-output --arg path "${path}" \
+        '{ path: $path, rules: [split("\n")[] | select(. != "")] }'
+      continue
+    fi
+    while IFS= read -r rule
+    do
+      [[ -n "${rule}" && -z "${seen[${rule}]:-}" ]] || continue
+      seen[${rule}]=1
+      printf '%s\n' "${rule}"
+    done < <(context:rules "${path}")
+  done
+}
+
+# context:claude reads Claude Code's PreToolUse hook input on stdin and answers with the rules governing the file
+# the tool is about to write, as additional context: the rule's text the first time it is named in the session,
+# its path after that. A tool input with no file path, or a file no rule governs, gets no answer.
+context:claude() {
+  local input path session rule text='' given
+  input=$(cat)
+  path=$(jq --raw-output '.tool_input.file_path // empty' <<<"${input}")
+  session=$(jq --raw-output '.session_id // "none"' <<<"${input}")
+  [[ -n "${path}" ]] || return 0
+  cd "$(git rev-parse --show-toplevel)" || return 0
+  path=$(context:relative "${path}")
+  context:log "${path}"
+  given="${TMPDIR:-/tmp}/kit-context-${session//[^A-Za-z0-9_-]/_}"
+  while IFS= read -r rule
+  do
+    [[ -n "${rule}" ]] || continue
+    if grep --quiet --line-regexp --fixed-strings "${rule}" "${given}" 2>/dev/null
+    then
+      text+="${path} is governed by ${rule}, which you have read this session."$'\n'
+    else
+      printf '%s\n' "${rule}" >> "${given}"
+      text+="${path} is governed by ${rule}. Its text:"$'\n\n'"$(cat "${rule}")"$'\n\n'
+    fi
+  done < <(context:rules "${path}")
+  [[ -n "${text}" ]] || return 0
+  jq --null-input --compact-output --arg text "${text}" \
+    '{ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: $text } }'
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit b/bin/kit
index 87bc9cf..4a22f8c 100755
--- a/bin/kit
+++ b/bin/kit
@@ -25,15 +25,17 @@ case "${verb}" in
     cat <<'USAGE'
 usage: kit <verb> [<argument>…]
 
-  install [<target>…]   mirror the release into the repository, take the named targets, write .kit/manifest
+  install [<module>…]   activate the default modules and the named ones, place their files, write .kit/manifest
   update                after the pin is bumped: replace unchanged files, three-way merge changed ones
   check                 fail when a delivered file differs from the pinned release
-  target <list|add|remove> [<target>…]
-                        the targets this repository takes
+  module <list|add|remove> [<module>…]
+                        the modules this repository takes
+  context <path>…       name the rules that govern a file, and record the ask
   issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
-  rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the default branch
+  rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
-  status [--no-fetch]   show every worktree with its branch, pull request, and state
+  status [--no-fetch] [--json]
+                        the desk, the worktrees, and the open pull requests
   lint [--all-files]    run the pre-commit hook's linters by hand, over the staged paths or every path
   version               print this release's version
 
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index 732c1c3..8f50bdc 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -16,8 +16,9 @@ then
 fi
 
 release:require-manifest
-read -r -a targets <<<"$(release:manifest-targets)"
+read -r -a modules <<<"$(release:manifest-modules)"
 version=$(release:manifest-version)
+release:render-all "${kit_root}" "${modules[@]}"
 findings=0
 if [[ "${version}" != "$(release:version)" ]]
 then
@@ -46,12 +47,12 @@ do
     error "${path} differs from the pinned release"
     findings=$(( findings + 1 ))
   fi
-done < <(release:delivered "${kit_root}" "${targets[@]}")
+done < <(release:delivered "${kit_root}" "${modules[@]}")
 if (( findings > 0 ))
 then
   error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
   exit 1
 fi
-ok "kit ${version}, targets ${targets[*]:-none}: every delivered file matches the pinned release."
+ok "kit ${version}, modules ${modules[*]:-none}: every delivered file matches the pinned release."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-context.sh b/bin/kit-context.sh
new file mode 100755
index 0000000..0faa33c
--- /dev/null
+++ b/bin/kit-context.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# kit-context - name the rules that govern a file, and record the ask (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bin/context.sh, docs/context.md
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use context
+
+case "${1:-}" in
+  (--help)
+    echo "usage: kit context <path>… [--json] | kit context --claude" >&2
+    exit 0
+    ;;
+  (--claude)
+    context:claude
+    ;;
+  (*)
+    context:render "$@"
+esac
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index 4ee448c..a290581 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -2,7 +2,8 @@
 # kit-install - mirror the release into the repository (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Takes the named targets and writes .kit/manifest.
+# Activates the default modules and the named ones, with the modules they depend on, places what they deliver,
+# and writes .kit/manifest.
 #
 # see: bin/release.sh
 
@@ -13,24 +14,27 @@ use release
 
 if [[ "${1:-}" == --help ]]
 then
-  echo "usage: kit install [<target>…]" >&2
+  echo "usage: kit install [<module>…]" >&2
   exit 0
 fi
 
 guard:require tool:jq
-release:require-targets "$@"
+release:require-modules "${kit_root}" "$@"
 if [[ -f .kit/manifest ]]
 then
   error "run: kit update (this repository already carries kit $(release:manifest-version))"
   exit 1
 fi
-section "kit install $(release:version)${*:+, targets: $*}"
+read -r -a defaults <<<"$(release:default-modules "${kit_root}" | paste -s -d ' ' -)"
+read -r -a modules <<<"$(release:resolve "${kit_root}" "${defaults[@]}" "$@" | paste -s -d ' ' -)"
+release:render-all "${kit_root}" "${modules[@]}"
+section "kit install $(release:version), modules: ${modules[*]}"
 while IFS=$'\t' read -r path src
 do
   step "${path}"
   release:place "${src}" "${path}"
-done < <(release:delivered "${kit_root}" "$@")
-release:write-manifest "$@"
-release:finish "$@"
+done < <(release:delivered "${kit_root}" "${modules[@]}")
+release:write-manifest "${modules[@]}"
+release:finish "${modules[@]}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-module.sh b/bin/kit-module.sh
new file mode 100755
index 0000000..0d37281
--- /dev/null
+++ b/bin/kit-module.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# kit-module - list, activate, or deactivate the modules this repository takes (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# see: bin/release.sh, docs/modules.md
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
+
+usage() { echo "usage: kit module list | kit module add <module>… | kit module remove <module>…" >&2; }
+
+verb=${1:-list}
+shift || true
+case "${verb}" in
+  (--help) usage; exit 0 ;;
+  (list | add | remove) ;;
+  (*) usage; exit 2
+esac
+release:require-manifest
+read -r -a active <<<"$(release:manifest-modules)"
+
+case "${verb}" in
+  (list)
+    for module in $(release:modules)
+    do
+      if release:among "${module}" "${active[@]}"
+      then mark='✅'
+      else mark='  '
+      fi
+      printf '%s %-10s %s\n' "${mark}" "${module}" "$(release:field "${kit_root}" "${module}" description)"
+    done
+    ;;
+  (add)
+    (( $# > 0 )) || { usage; exit 2; }
+    guard:require tool:jq
+    release:require-modules "${kit_root}" "$@"
+    read -r -a wanted <<<"$(release:resolve "${kit_root}" "${active[@]}" "$@" | paste -s -d ' ' -)"
+    release:render-all "${kit_root}" "${wanted[@]}"
+    section "kit module add $*"
+    while IFS= read -r path
+    do
+      [[ -n "${path}" ]] || continue
+      step "${path}"
+      release:place "$(release:source-of "${kit_root}" "${path}" "${wanted[@]}")" "${path}"
+    done < <(release:paths-beyond "${kit_root}" "${active[*]}" "${wanted[*]}")
+    release:write-manifest "${wanted[@]}"
+    ok "modules: ${wanted[*]}"
+    ;;
+  (remove)
+    (( $# > 0 )) || { usage; exit 2; }
+    guard:require tool:jq
+    release:require-modules "${kit_root}" "$@"
+    remaining=("${active[@]}")
+    for module in "$@"
+    do
+      if ! release:among "${module}" "${remaining[@]}"
+      then
+        step "${module}: not active"
+        continue
+      fi
+      read -r -a dependents <<<"$(release:dependents "${kit_root}" "${module}" "${remaining[@]}" | paste -s -d ' ' -)"
+      if (( ${#dependents[@]} > 0 ))
+      then
+        error "${module} cannot be removed while ${dependents[*]} depend(s) on it"
+        exit 1
+      fi
+      read -r -a remaining <<<"$(release:without "${module}" "${remaining[@]}" | paste -s -d ' ' -)"
+    done
+    release:render-all "${kit_root}" "${active[@]}"
+    section "kit module remove $*"
+    while IFS= read -r path
+    do
+      [[ -n "${path}" ]] || continue
+      release:unplace "$(release:source-of "${kit_root}" "${path}" "${active[@]}")" "${path}"
+    done < <(release:paths-beyond "${kit_root}" "${remaining[*]}" "${active[*]}")
+    release:write-manifest "${remaining[@]}"
+    ok "modules: ${remaining[*]:-none}"
+esac
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-target.sh b/bin/kit-target.sh
deleted file mode 100755
index 1d770ef..0000000
--- a/bin/kit-target.sh
+++ /dev/null
@@ -1,82 +0,0 @@
-#!/usr/bin/env bash
-# kit-target - list, take, or drop the targets this repository takes (kit verb)
-# ----------------------------------------------------------------------------------------------------------------------
-#
-# see: bin/release.sh
-
-set -o errexit -o nounset -o pipefail
-# shellcheck source=bin/1st.sh
-source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use release
-
-usage() { echo "usage: kit target list | kit target add <target>… | kit target remove <target>…" >&2; }
-
-verb=${1:-list}
-shift || true
-case "${verb}" in
-  (--help) usage; exit 0 ;;
-  (list | add | remove) ;;
-  (*) usage; exit 2
-esac
-release:require-manifest
-read -r -a targets <<<"$(release:manifest-targets)"
-
-case "${verb}" in
-  (list)
-    printf '%s\n' "${targets[@]}"
-    ;;
-  (add)
-    (( $# > 0 )) || { usage; exit 2; }
-    guard:require tool:jq
-    release:require-targets "$@"
-    for t in "$@"
-    do
-      if release:among "${t}" "${targets[@]}"
-      then
-        step "${t}: already taken"
-        continue
-      fi
-      section "kit target add ${t}"
-      while IFS= read -r path
-      do
-        step "${path}"
-        release:place "${kit_root}/targets/${t}/${path}" "${path}"
-      done < <(release:target-only "${t}")
-      targets+=("${t}")
-    done
-    release:write-manifest "${targets[@]}"
-    ok "targets: ${targets[*]}"
-    ;;
-  (remove)
-    (( $# > 0 )) || { usage; exit 2; }
-    guard:require tool:jq
-    release:require-targets "$@"
-    for t in "$@"
-    do
-      if ! release:among "${t}" "${targets[@]}"
-      then
-        step "${t}: not taken"
-        continue
-      fi
-      section "kit target remove ${t}"
-      while IFS= read -r path
-      do
-        src="${kit_root}/targets/${t}/${path}"
-        if release:merged "${path}"
-        then
-          [[ -f "${path}" ]] || continue
-          step "${path}: the kit's entries taken out"
-          # shellcheck disable=SC2016  # a jq filter, with jq variables
-          release:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
-        else
-          step "removing ${path}"
-          rm -f "${path}"
-        fi
-      done < <(release:target-only "${t}")
-      read -r -a targets <<<"$(release:without "${t}" "${targets[@]}" | paste -s -d ' ' -)"
-    done
-    release:write-manifest "${targets[@]}"
-    ok "targets: ${targets[*]:-none}"
-esac
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 4a3e181..d29aed6 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -5,7 +5,7 @@
 # A file whose digest still matches the manifest, which records the previous release's own content, is replaced.
 # An edited one is three-way merged with the previous release as the base, which release:fetch finds or fetches.
 # A path the previous release did not deliver is written only where the repository has nothing, or the same
-# thing, there.
+# thing, there. A template is rendered from the repository's answers in both releases before either is compared.
 #
 # see: bin/release.sh
 
@@ -22,10 +22,11 @@ fi
 
 guard:require tool:jq
 release:require-manifest
-read -r -a targets <<<"$(release:manifest-targets)"
+read -r -a modules <<<"$(release:manifest-modules)"
 previous=$(release:manifest-version)
 current=$(release:version)
-section "kit update ${previous} → ${current}${targets[*]:+, targets: ${targets[*]}}"
+release:render-all "${kit_root}" "${modules[@]}"
+section "kit update ${previous} → ${current}, modules: ${modules[*]}"
 
 # The previous release is the base of every merge, needed only when the release changed. KIT_BASE names its
 # root; otherwise release:fetch finds or fetches it.
@@ -38,6 +39,7 @@ elif [[ "${previous}" != "${current}" && "${previous}" != "${release_unreleased}
 then
   base_root=$(release:fetch "${previous}" || true)
 fi
+[[ -n "${base_root}" ]] && release:render-all "${base_root}" "${modules[@]}"
 needs_base=false
 [[ "${previous}" != "${current}" ]] && needs_base=true
 
@@ -62,7 +64,7 @@ do
     continue
   fi
   base=""
-  [[ -n "${base_root}" ]] && base=$(release:source-of "${base_root}" "${path}" "${targets[@]}")
+  [[ -n "${base_root}" ]] && base=$(release:source-of "${base_root}" "${path}" "${modules[@]}")
   if [[ "${needs_base}" == true && -z "${base}" ]]
   then
     # Without the base, neither a merge nor the removal of the previous release's entries is possible.
@@ -90,14 +92,14 @@ do
       conflicts=$(( conflicts + 1 ))
     fi
   fi
-done < <(release:delivered "${kit_root}" "${targets[@]}")
+done < <(release:delivered "${kit_root}" "${modules[@]}")
 
-release:write-manifest "${targets[@]}"
+release:write-manifest "${modules[@]}"
 if (( conflicts > 0 ))
 then
   error "${conflicts} file(s) need a hand; see above."
   exit 1
 fi
-release:finish "${targets[@]}"
+release:finish "${modules[@]}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/release.sh b/bin/release.sh
index 755453a..e8d03a3 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -1,15 +1,16 @@
 # shellcheck shell=bash
 # shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
-# release.sh - the release's layout, the one merge rule, and the manifest (sourced module)
+# release.sh - the release's modules, the one merge rule, the templates, and the manifest (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A release mirrors its tree/ at the repository root, and targets/<name>/ for each target taken; a symlink in
-# either is delivered as the file it points at. A destination ending in .json is merged by key, with the kit's
-# keys set, the kit's array entries added, and on update or removal only the previous release's entries taken
-# out. .kit/manifest records the version, the targets, and the release's digest for every delivered path.
+# A release is bin/ and modules/. Each modules/<name>/ is a module: a `module` file of metadata, a tree/ mirrored
+# at the repository root, and templates/ with @key@ rendered from the repository's answers, then placed the same way. A
+# destination ending in .json is merged by key, with the kit's keys set, the kit's array entries added, and on
+# update or removal only the previous release's entries taken out. .kit/manifest records the version, the active
+# modules, and the release's digest for every delivered path. docs/modules.md is the format's description.
 #
-# Every function reads the release from kit_root, exported by bin/kit.
+# Every function reads a release from a root, kit_root by default, which bin/kit exports.
 
 # A release carries a version file the release workflow stamps from the tag; a checkout carries none and is
 # "unreleased", the one version kit update never asks mise for.
@@ -20,19 +21,162 @@ release:version() {
   cat "${kit_root}/version" 2>/dev/null || printf '%s\n' "${release_unreleased}"
 }
 
-# release:layers <root> <target>… prints the directories mirrored at the repository root, tree first.
+# release:modules [<root>] prints the modules the release carries.
+release:modules() {
+  (cd "${1:-${kit_root}}/modules" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
+}
+
+# release:field <root> <module> <keyword> prints the value of every <keyword> line in the module's metadata.
+release:field() {
+  sed -n "s/^$3 //p; s/^$3\$//p" "$1/modules/$2/module" 2>/dev/null || true
+}
+
+# release:default-modules <root> prints the modules active unless removed.
+release:default-modules() {
+  local module
+  for module in $(release:modules "$1")
+  do
+    grep --quiet --line-regexp default "$1/modules/${module}/module" && printf '%s\n' "${module}"
+  done
+  return 0
+}
+
+# release:require-modules <root> <name>… refuses a module the release does not carry, naming the ones it does.
+release:require-modules() {
+  local root=$1 module
+  shift
+  for module in "$@"
+  do
+    if [[ ! -f "${root}/modules/${module}/module" ]]
+    then
+      error "'${module}' is not a module this release knows; the modules are: $(release:modules "${root}" | paste -s -d ' ' -)"
+      return 2
+    fi
+  done
+}
+
+# release:resolve <root> <name>… prints the named modules and everything they depend on, each once, a module
+# after the modules it depends on: the closure over depends, ordered by tsort over its edges.
+release:resolve() {
+  local root=$1 module dep
+  shift
+  local -A wanted=()
+  local -a queue=("$@")
+  while (( ${#queue[@]} > 0 ))
+  do
+    module=${queue[0]}
+    queue=("${queue[@]:1}")
+    [[ -n "${wanted[${module}]:-}" ]] && continue
+    wanted[${module}]=1
+    for dep in $(release:field "${root}" "${module}" depends)
+    do
+      queue+=("${dep}")
+    done
+  done
+  for module in "${!wanted[@]}"
+  do
+    printf '%s %s\n' "${module}" "${module}"
+    for dep in $(release:field "${root}" "${module}" depends)
+    do
+      printf '%s %s\n' "${dep}" "${module}"
+    done
+  done | sort | tsort
+}
+
+# release:dependents <root> <module> <active>… prints the active modules that depend on <module>.
+release:dependents() {
+  local root=$1 module=$2 other dep
+  shift 2
+  for other in "$@"
+  do
+    for dep in $(release:field "${root}" "${other}" depends)
+    do
+      [[ "${dep}" == "${module}" ]] && printf '%s\n' "${other}"
+    done
+  done
+}
+
+# release:answers <root> <module> prints "<key>\t<value>" for every answer the module's templates may use: the
+# module's defaults, each overridden by a "<key> <value>" line in the repository's .kit/answers.
+release:answers() {
+  {
+    release:field "$1" "$2" answer
+    [[ -f .kit/answers ]] && grep --invert-match '^#' .kit/answers
+    true
+  } | awk 'NF >= 2 { v = $0; sub(/^[^ ]+ +/, "", v); a[$1] = v } END { for (k in a) print k "\t" a[k] }'
+}
+
+# release:tmp prints a directory for this process's rendered templates, made once and removed at exit.
+release:tmp() {
+  if [[ -z "${release_tmp:-}" ]]
+  then
+    release_tmp=$(mktemp -d)
+    # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
+    trap "rm -rf '${release_tmp}'" EXIT
+  fi
+  printf '%s\n' "${release_tmp}"
+}
+
+# release:render <root> <module> renders the module's templates once per process and prints the directory holding
+# them, or prints nothing for a module with no templates. A key is written @key@, autoconf's form, which neither
+# bash's ${var} nor GitHub's ${{ }} can be mistaken for; one with no answer refuses, naming the key.
+release:render() {
+  local root=$1 module=$2 templates="$1/modules/$2/templates" out key value text file rel
+  local -A answer=()
+  [[ -d "${templates}" ]] || return 0
+  out="$(release:tmp)/$(printf '%s' "${root}" | release:digest)/${module}"
+  if [[ ! -d "${out}" ]]
+  then
+    while IFS=$'\t' read -r key value
+    do
+      [[ -n "${key}" ]] && answer[${key}]=${value}
+    done < <(release:answers "${root}" "${module}")
+    while IFS= read -r file
+    do
+      rel=${file#"${templates}"/}
+      text=$(<"${file}")
+      for key in $(grep --only-matching '@[a-z_]*@' "${file}" | sort --unique | tr -d '@')
+      do
+        if [[ -z "${answer[${key}]+x}" ]]
+        then
+          error "${rel} needs an answer for '${key}'; add a line '${key} <value>' to .kit/answers (module ${module})"
+          return 1
+        fi
+        text=${text//"@${key}@"/"${answer[${key}]}"}
+      done
+      mkdir -p "${out}/$(dirname "${rel}")"
+      printf '%s\n' "${text}" > "${out}/${rel}"
+    done < <(find "${templates}" -type f)
+  fi
+  printf '%s\n' "${out}"
+}
+
+# release:render-all <root> <module>… renders every named module's templates, refusing on the first unanswered key.
+release:render-all() {
+  local root=$1 module
+  shift
+  for module in "$@"
+  do
+    release:render "${root}" "${module}" >/dev/null || return 1
+  done
+}
+
+# release:layers <root> <module>… prints the directories mirrored at the repository root, in module order: each
+# module's tree/, then its rendered templates.
 release:layers() {
-  local root=$1 t
+  local root=$1 module rendered
   shift
-  printf '%s\n' "${root}/tree"
-  for t in "$@"
+  for module in "$@"
   do
-    printf '%s\n' "${root}/targets/${t}"
+    [[ -d "${root}/modules/${module}/tree" ]] && printf '%s\n' "${root}/modules/${module}/tree"
+    rendered=$(release:render "${root}" "${module}")
+    [[ -n "${rendered}" ]] && printf '%s\n' "${rendered}"
   done
+  return 0
 }
 
-# release:delivered <root> <target>… prints "<path>\t<source>" for every repository path the release at <root>
-# delivers for those targets, sorted by path, the last layer winning. A symlink is a source only when it points
+# release:delivered <root> <module>… prints "<path>\t<source>" for every repository path the release at <root>
+# delivers for those modules, sorted by path, the last layer winning. A symlink is a source only when it points
 # at a file; a dangling one is refused here, where it is found.
 release:delivered() {
   local layer path src
@@ -51,34 +195,21 @@ release:delivered() {
   done
 }
 
-# release:source-of <root> <path> <target>… prints the release file behind one repository path, or nothing.
+# release:source-of <root> <path> <module>… prints the release file behind one repository path, or nothing.
 release:source-of() {
   local root=$1 path=$2
   shift 2
   release:delivered "${root}" "$@" | awk -F '\t' -v p="${path}" '$1 == p { print $2 }'
 }
 
-# release:target-only <target> prints the paths the target delivers that tree/ does not.
-release:target-only() {
-  comm -13 <(release:delivered "${kit_root}" | cut -f 1) <(release:delivered "${kit_root}" "$1" | cut -f 1)
-}
-
-# release:known-targets prints the targets this release carries.
-release:known-targets() {
-  (cd "${kit_root}/targets" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
-}
-
-# release:require-targets <name>… refuses a target this release does not carry, naming the ones it does.
-release:require-targets() {
-  local t
-  for t in "$@"
-  do
-    if [[ ! -d "${kit_root}/targets/${t}" ]]
-    then
-      error "'${t}' is not a target this release knows; the targets are: $(release:known-targets | paste -s -d ' ' -)"
-      return 2
-    fi
-  done
+# release:paths-beyond <root> <before> <after> prints the paths the module set <after> delivers that <before>
+# does not; each set is one space-separated word.
+release:paths-beyond() {
+  local root=$1
+  local -a before after
+  read -r -a before <<<"$2"
+  read -r -a after <<<"$3"
+  comm -13 <(release:delivered "${root}" "${before[@]}" | cut -f 1) <(release:delivered "${root}" "${after[@]}" | cut -f 1)
 }
 
 release:merged() { [[ "$1" == *.json ]]; }
@@ -204,13 +335,29 @@ release:place() {
   fi
 }
 
-# release:write-manifest <target>… records the version, the targets, and the release's digest for every delivered path.
+# release:unplace <source> <path> takes the release's content back out of <path>: the kit's entries for .json,
+# the file itself otherwise.
+release:unplace() {
+  local src=$1 path=$2
+  if release:merged "${path}"
+  then
+    [[ -f "${path}" ]] || return 0
+    step "${path}: the kit's entries taken out"
+    release:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
+  else
+    step "removing ${path}"
+    rm -f "${path}"
+  fi
+}
+
+# release:write-manifest <module>… records the version, the active modules, and the release's digest for every
+# delivered path.
 release:write-manifest() {
   local path src
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
     printf 'version %s\n' "$(release:version)"
-    printf 'targets%s\n' "${*:+ $*}"
+    printf 'modules%s\n' "${*:+ $*}"
     while IFS=$'\t' read -r path src
     do
       printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
@@ -219,7 +366,7 @@ release:write-manifest() {
 }
 
 release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
-release:manifest-targets() { sed -n 's/^targets *//p' .kit/manifest; }
+release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest; }
 
 # release:require-manifest refuses to go on in a repository that never took the kit.
 release:require-manifest() {
@@ -230,9 +377,9 @@ release:require-manifest() {
   fi
 }
 
-# release:finish <target>… reports a completed install or update.
+# release:finish <module>… reports a completed install or update.
 release:finish() {
-  ok "kit $(release:version) is installed, targets: ${*:-none}; .kit/manifest is written."
+  ok "kit $(release:version) is installed, modules: ${*:-none}; .kit/manifest is written."
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
 
diff --git a/docs/context.md b/docs/context.md
new file mode 100644
index 0000000..f28b4df
--- /dev/null
+++ b/docs/context.md
@@ -0,0 +1,50 @@
+# Context
+
+A rule is written once, in `.kit/rules/<kind>.md`, and copied nowhere. Before an agent creates or changes a file,
+it asks which rules govern that file:
+
+```sh
+kit context <path>…
+```
+
+The answer is the rule files to read, one per line. `--json` gives one object per path with its rules. Every ask
+is appended to `.git/kit/context.log` as `<epoch>\t<path>`, which is the evidence a check can read to ask whether
+every path a commit touched had its context asked for.
+
+## How a rule declares what it governs
+
+A rule file opens with a frontmatter of two optional lists:
+
+```yaml
+---
+paths:
+  - "**/*.sh"
+content:
+  - "^#!.*/(env +)?(ba)?sh( |$)"
+---
+```
+
+- `paths:` are globs matched against the repository-relative path. `**` stands for any depth, so `**/*.sh` is
+  every `.sh` file and `justfile` is the one at the root.
+- `content:` are extended regular expressions matched against the first line of a file that already exists, so a
+  bash script with no extension is bash by its shebang, and a file about to be created is governed by its path
+  alone.
+
+A rule governs a file when any glob or any pattern matches.
+
+## Harness adapters
+
+A harness that can run a command before a write runs `kit context` itself, so the rules reach the agent without
+the agent remembering to ask. The `claude` module wires Claude Code's `PreToolUse` hook on `Write`, `Edit`, and
+`MultiEdit` to:
+
+```sh
+kit context --claude
+```
+
+It reads the hook's input on stdin, takes the file path from the tool's input, and answers in the hook's output
+with the rules as additional context: a rule's text the first time it is named in the session, its path after
+that. The session is told apart by the hook input's `session_id`, and what was given is kept under `TMPDIR`.
+
+A harness with no hook, and a person, use the plain call. `.kit/1st.md` names it as the step before any file is
+created or changed.
diff --git a/docs/modules.md b/docs/modules.md
new file mode 100644
index 0000000..5da9de1
--- /dev/null
+++ b/docs/modules.md
@@ -0,0 +1,61 @@
+# Modules
+
+Everything the kit delivers is a module: a directory under `modules/` in the release. A repository activates the
+modules it wants, and `kit install`, `kit update`, and `kit check` work over the active set.
+
+## Layout
+
+```text
+modules/<name>/
+  module        metadata, one keyword per line
+  tree/         files mirrored at the repository root
+  templates/    files rendered from the repository's answers, then mirrored the same way
+  docs/         the module's documentation, for a reader of this repository; not delivered
+```
+
+A module may have any of `tree/`, `templates/`, and `docs/`, and must have `module`.
+
+## Metadata
+
+The `module` file is lines of one keyword each. A line starting with `#` is a comment.
+
+| Keyword | Meaning |
+| --- | --- |
+| `description <text>` | One line, shown by `kit module list`. |
+| `default` | Active unless removed. `kit install` with no names activates every default module. |
+| `depends <name>…` | Activated with this module. `kit module remove` refuses a module another active module depends on. |
+| `answer <key> <value>` | The default value of a template key. A repository overrides it in `.kit/answers`. |
+
+## Delivery
+
+A file under `tree/` is placed at the same path under the repository root. A destination ending in `.json` is
+merged by key: the kit's keys are set, its array entries added, and on update or removal only the previous
+release's entries are taken out, so a repository's own keys and entries survive. Every other destination is a copy.
+Where two active modules deliver the same path, the later module in dependency order wins.
+
+A file under `templates/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
+answer, then the result is placed, digested, and merged exactly as a `tree/` file is. The form is one neither
+bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
+answers live in `.kit/answers`, a file of `key value` lines the repository owns and the kit never writes; a key
+with no line there takes the module's `answer` default, and a key with neither refuses the install, naming the key
+and the module.
+
+## Activation
+
+- `kit install [<module>…]` activates the default modules and the named ones, with their dependencies, and records
+  the set on the `modules` line of `.kit/manifest`.
+- `kit module list` shows every module the release carries and which are active.
+- `kit module add <module>…` activates more, placing only the paths the new set delivers beyond the old.
+- `kit module remove <module>…` deactivates, removing the paths only the removed modules delivered and taking the
+  kit's entries back out of a merged `.json`.
+
+## This release's modules
+
+| Module | Default | Depends on | Delivers |
+| --- | --- | --- | --- |
+| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md` |
+| `lefthook` | yes | `kit` | `.kit/lefthook.yml` |
+| `ci` | yes | `kit` | `.github/workflows/kit-ci.yml`, from a template; answer `ci_runner` |
+| `claude` | no | `kit` | `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
+
+Each module's `docs/README.md` says what it places and why.
diff --git a/justfile b/justfile
index eee51c1..b271160 100644
--- a/justfile
+++ b/justfile
@@ -38,7 +38,7 @@ ci:
   echo "✅ ci passed"
 
 # Reinstall this repository's own kit from the index and stage the result. Here the checkout is the release, so an
-# edit under tree/ or targets/ is an edit to the release, not a consumer's drift. The copies are made from the
+# edit under modules/ is an edit to the release, not a consumer's drift. The copies are made from the
 # index, what the commit will carry, never from the working tree, so a half-staged edit cannot put a copy into a
 # commit that lacks its source. Every path the old manifest lists is removed first and written again from the
 # new release: a source that was deleted leaves no copy behind, and an entry that was retired does not survive
@@ -53,14 +53,14 @@ refresh:
   set -o errexit -o nounset -o pipefail
   paths() { awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest; }
   readarray -t before < <(paths)
-  read -r -a targets <<<"$(sed -n 's/^targets *//p' .kit/manifest)"
+  read -r -a modules <<<"$(sed -n 's/^modules *//p' .kit/manifest)"
   index=$(mktemp -d)
   trap 'rm -rf "${index}"' EXIT
   git checkout-index --all --prefix="${index}/"
   rm -f "${before[@]}" .kit/manifest
-  "${index}/bin/kit" install "${targets[@]}" >/dev/null
+  "${index}/bin/kit" install "${modules[@]}" >/dev/null
   readarray -t after < <(paths)
   git add --all -- "${before[@]}" "${after[@]}" .kit/manifest
-  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, targets ${targets[*]:-none}"
+  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, modules ${modules[*]:-none}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/ci/docs/README.md b/modules/ci/docs/README.md
new file mode 100644
index 0000000..41912f8
--- /dev/null
+++ b/modules/ci/docs/README.md
@@ -0,0 +1,7 @@
+# The ci module
+
+Places `.github/workflows/kit-ci.yml`: one job, `CI`, which runs the repository's `just ci` when its root justfile
+has that recipe, runs `kit check`, and refuses a pull request not linked to an open issue of the repository.
+
+The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
+a repository with runners of its own puts `ci_runner <label>` in `.kit/answers`.
diff --git a/modules/ci/module b/modules/ci/module
new file mode 100644
index 0000000..9c3302f
--- /dev/null
+++ b/modules/ci/module
@@ -0,0 +1,8 @@
+# modules/ci/module - the ci module: one CI job, the gate, kit check, and the linked-open-issue refusal
+# ----------------------------------------------------------------------------------------------------------------------
+# One keyword per line. docs/modules.md says what each keyword means.
+
+description One CI job: the repository's gate, kit check, and the refusal of a pull request without an open issue
+default
+depends kit
+answer ci_runner ubuntu-latest
diff --git a/tree/.github/workflows/kit-ci.yml b/modules/ci/templates/.github/workflows/kit-ci.yml
similarity index 97%
rename from tree/.github/workflows/kit-ci.yml
rename to modules/ci/templates/.github/workflows/kit-ci.yml
index 3cf9a98..b4c1ba6 100644
--- a/tree/.github/workflows/kit-ci.yml
+++ b/modules/ci/templates/.github/workflows/kit-ci.yml
@@ -6,7 +6,8 @@
 # open issue of this repository under Development. The last two run even when an earlier step refused, so one
 # run reports every finding.
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. Rendered from a template: the
+# job runs on the ci_runner answer, ubuntu-latest unless .kit/answers says otherwise.
 #
 # see: .kit/1st.md
 
@@ -24,7 +25,7 @@ permissions:
 jobs:
   CI:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
-    runs-on: ubuntu-latest
+    runs-on: @ci_runner@
     env:
       # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
       MISE_ENV: ci
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
new file mode 100644
index 0000000..f6052df
--- /dev/null
+++ b/modules/claude/docs/README.md
@@ -0,0 +1,10 @@
+# The claude module
+
+The adapter for Claude Code. It merges into `.claude/settings.json`, by key, leaving the repository's own entries:
+
+- `permissions.deny`: the seven spellings the rules forbid an agent, such as `git rebase` and `git push --force`,
+  which `kit rebase` and the loop replace.
+- `hooks.PreToolUse`: on `Write`, `Edit`, and `MultiEdit`, `kit context --claude`, which puts the rules governing
+  the file before the agent, described in [docs/context.md](../../../docs/context.md).
+
+It copies no rule. `.claude/rules/` is the repository's own.
diff --git a/modules/claude/module b/modules/claude/module
new file mode 100644
index 0000000..13eda3e
--- /dev/null
+++ b/modules/claude/module
@@ -0,0 +1,6 @@
+# modules/claude/module - the claude module: Claude Code's deny list and its hook into kit context
+# ----------------------------------------------------------------------------------------------------------------------
+# One keyword per line. docs/modules.md says what each keyword means.
+
+description Claude Code: the deny list for the spellings the rules forbid, and the hook that puts a file's rules before the agent
+depends kit
diff --git a/targets/claude/.claude/settings.json b/modules/claude/tree/.claude/settings.json
similarity index 54%
rename from targets/claude/.claude/settings.json
rename to modules/claude/tree/.claude/settings.json
index fde98cf..d762f8d 100644
--- a/targets/claude/.claude/settings.json
+++ b/modules/claude/tree/.claude/settings.json
@@ -9,5 +9,18 @@
       "Bash(git push -f *)",
       "Bash(git worktree remove --force *)"
     ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kit context --claude"
+          }
+        ]
+      }
+    ]
   }
 }
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
new file mode 100644
index 0000000..472dc3c
--- /dev/null
+++ b/modules/kit/docs/README.md
@@ -0,0 +1,11 @@
+# The kit module
+
+The core, active in every repository that takes the kit. It places:
+
+- `.kit/1st.md`, the entry every agent reads, imported by the repository's `AGENTS.md`.
+- `.kit/rules/<kind>.md`, one rule file per kind of file, each declaring in its frontmatter which paths and which
+  first lines it governs.
+
+The rules are discovered through `kit context <path>`, described in [docs/context.md](../../../docs/context.md),
+and copied into no harness's directory. Adding a kind is adding one rule file here and one row to the table in
+`1st.md`; every harness and every person finds it the same way.
diff --git a/modules/kit/module b/modules/kit/module
new file mode 100644
index 0000000..ed1b74c
--- /dev/null
+++ b/modules/kit/module
@@ -0,0 +1,6 @@
+# modules/kit/module - the kit module: the entry every agent reads, the rules by file kind, and kit context
+# ----------------------------------------------------------------------------------------------------------------------
+# One keyword per line. docs/modules.md says what each keyword means.
+
+description The entry every agent reads, the rules by file kind, and the context call that names them
+default
diff --git a/tree/.kit/1st.md b/modules/kit/tree/.kit/1st.md
similarity index 76%
rename from tree/.kit/1st.md
rename to modules/kit/tree/.kit/1st.md
index 1792650..0d4fc49 100644
--- a/tree/.kit/1st.md
+++ b/modules/kit/tree/.kit/1st.md
@@ -67,10 +67,10 @@ A worker is whoever implements one issue in the worktree that issue names.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`, and each rule file's `paths:` header names the paths it
-binds. A harness that loads rules by path gets a copy in its own rules directory when the repository takes that
-target: `.claude/rules/kit-<kind>.md` for Claude Code. Read the rule for a kind before writing a file of that
-kind.
+Each file kind has a rule file under `.kit/rules/`, and each rule file's header names what it governs: `paths:`,
+globs on the repository path, and `content:`, patterns on the first line. Before you create or change a file, run
+`kit context <path>`. It names the rules that govern the file and records that you asked. Read what it names. No
+harness holds a copy of a rule; this call is how every harness, and every person, finds it.
 
 | Kind | Rule |
 | --- | --- |
@@ -84,22 +84,21 @@ kind.
 ## What the kit carries
 
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
-release version, the targets taken, and a checksum per delivered file. The release, where mise installed it,
-carries the machinery, reached through the `kit` command on `PATH`. A release mirrors its `tree/` at the
-repository root, and `targets/<name>/` for each target taken. A `.json` destination is merged by key; everything
-else is copied as it is.
-
-- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, and `kit lint`, spelled that way and
-  no other.
-- `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
+release version, the active modules, and a checksum per delivered file. The release, where it is installed,
+carries the machinery, reached through the `kit` command on `PATH`. Everything the release delivers is a module,
+and a repository activates the modules it takes: `kit install claude`, or `kit module add claude` later, and
+`kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning only the entries
+it writes; everything else is copied as it is.
+
+- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled
+  that way and no other.
+- `kit`: this file and the rules, discovered through `kit context`.
+- `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
-- Targets. A harness that insists on files outside `.kit/` is a target, and a repository takes only the targets
-  it names: `kit install claude`, or `kit target add claude` later. The `claude` target places
-  `.claude/rules/kit-<kind>.md`, copies of the rules, and merges seven deny rules into `.claude/settings.json`.
-  The kit owns only the entries it writes; the repository may add its own. `kit target remove` takes a target
-  back out.
-- `.github/workflows/kit-ci.yml`: one `CI` job that runs the consumer's `just ci`, runs `kit check`, and refuses
-  a pull request not linked to an open issue.
+- `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
+  refuses a pull request not linked to an open issue.
+- `claude`: for Claude Code, seven deny rules merged into `.claude/settings.json`, and a hook that runs
+  `kit context` before every write so the rules reach the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/tree/.kit/rules/bash.md b/modules/kit/tree/.kit/rules/bash.md
similarity index 98%
rename from tree/.kit/rules/bash.md
rename to modules/kit/tree/.kit/rules/bash.md
index 33b1128..e04e9b0 100644
--- a/tree/.kit/rules/bash.md
+++ b/modules/kit/tree/.kit/rules/bash.md
@@ -3,6 +3,8 @@
 paths:
   - "**/*.sh"
   - "**/*.bash"
+content:
+  - "^#!.*/(env +)?(ba)?sh( |$)"
 ---
 # Bash
 
diff --git a/tree/.kit/rules/gitignore.md b/modules/kit/tree/.kit/rules/gitignore.md
similarity index 100%
rename from tree/.kit/rules/gitignore.md
rename to modules/kit/tree/.kit/rules/gitignore.md
diff --git a/tree/.kit/rules/json.md b/modules/kit/tree/.kit/rules/json.md
similarity index 100%
rename from tree/.kit/rules/json.md
rename to modules/kit/tree/.kit/rules/json.md
diff --git a/tree/.kit/rules/just.md b/modules/kit/tree/.kit/rules/just.md
similarity index 98%
rename from tree/.kit/rules/just.md
rename to modules/kit/tree/.kit/rules/just.md
index d91dd1f..69f6620 100644
--- a/tree/.kit/rules/just.md
+++ b/modules/kit/tree/.kit/rules/just.md
@@ -4,6 +4,8 @@ paths:
   - "justfile"
   - "**/justfile"
   - "**/*.just"
+content:
+  - "^#!.*/(env +)?just( |$)"
 ---
 # Just
 
diff --git a/tree/.kit/rules/markdown.md b/modules/kit/tree/.kit/rules/markdown.md
similarity index 100%
rename from tree/.kit/rules/markdown.md
rename to modules/kit/tree/.kit/rules/markdown.md
diff --git a/tree/.kit/rules/yaml.md b/modules/kit/tree/.kit/rules/yaml.md
similarity index 100%
rename from tree/.kit/rules/yaml.md
rename to modules/kit/tree/.kit/rules/yaml.md
diff --git a/modules/lefthook/docs/README.md b/modules/lefthook/docs/README.md
new file mode 100644
index 0000000..139f18b
--- /dev/null
+++ b/modules/lefthook/docs/README.md
@@ -0,0 +1,5 @@
+# The lefthook module
+
+Places `.kit/lefthook.yml`, which says which linter runs over which paths before a commit. The repository's own
+`lefthook.yml` takes it with `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name.
+`kit lint` runs the same hook by hand. The repository pins `lefthook` itself, since only a desk runs a hook.
diff --git a/modules/lefthook/module b/modules/lefthook/module
new file mode 100644
index 0000000..f7d56b1
--- /dev/null
+++ b/modules/lefthook/module
@@ -0,0 +1,7 @@
+# modules/lefthook/module - the lefthook module: which linter runs over which paths before a commit
+# ----------------------------------------------------------------------------------------------------------------------
+# One keyword per line. docs/modules.md says what each keyword means.
+
+description Which linter runs over which paths before a commit, for the repository's lefthook.yml to extend
+default
+depends kit
diff --git a/tree/.kit/lefthook.yml b/modules/lefthook/tree/.kit/lefthook.yml
similarity index 100%
rename from tree/.kit/lefthook.yml
rename to modules/lefthook/tree/.kit/lefthook.yml
diff --git a/targets/claude/.claude/rules/kit-bash.md b/targets/claude/.claude/rules/kit-bash.md
deleted file mode 120000
index bb642e0..0000000
--- a/targets/claude/.claude/rules/kit-bash.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../tree/.kit/rules/bash.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-gitignore.md b/targets/claude/.claude/rules/kit-gitignore.md
deleted file mode 120000
index 1a1c591..0000000
--- a/targets/claude/.claude/rules/kit-gitignore.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../tree/.kit/rules/gitignore.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-json.md b/targets/claude/.claude/rules/kit-json.md
deleted file mode 120000
index d4e607d..0000000
--- a/targets/claude/.claude/rules/kit-json.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../tree/.kit/rules/json.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-just.md b/targets/claude/.claude/rules/kit-just.md
deleted file mode 120000
index 2b2f173..0000000
--- a/targets/claude/.claude/rules/kit-just.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../tree/.kit/rules/just.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-markdown.md b/targets/claude/.claude/rules/kit-markdown.md
deleted file mode 120000
index 8d735ea..0000000
--- a/targets/claude/.claude/rules/kit-markdown.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../tree/.kit/rules/markdown.md
\ No newline at end of file
diff --git a/targets/claude/.claude/rules/kit-yaml.md b/targets/claude/.claude/rules/kit-yaml.md
deleted file mode 120000
index d91b5eb..0000000
--- a/targets/claude/.claude/rules/kit-yaml.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../tree/.kit/rules/yaml.md
\ No newline at end of file
diff --git a/tests/context.bats b/tests/context.bats
new file mode 100644
index 0000000..080304a
--- /dev/null
+++ b/tests/context.bats
@@ -0,0 +1,62 @@
+#!/usr/bin/env bats
+# context.bats - kit context names a file's rules by path or by first line, logs the ask, and speaks Claude's hook
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  repo=$(mktemp -d)
+  git -C "${repo}" init --quiet --initial-branch=main
+  cd "${repo}"
+  "${kit_checkout}/bin/kit" install >/dev/null
+  export TMPDIR="${repo}/tmp"
+  mkdir "${TMPDIR}"
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+@test "a file is governed by its path, by its first line, or by nothing" {
+  # a real file the rule's glob would expand to, were the glob ever word-split
+  mkdir docs && printf '# x\n' > docs/x.md
+  run "${kit_checkout}/bin/kit" context README.md
+  [ "$output" = ".kit/rules/markdown.md" ]
+  run "${kit_checkout}/bin/kit" context justfile
+  [ "$status" -eq 0 ]
+  [ "$output" = ".kit/rules/just.md" ]
+  mkdir bin && printf '#!/usr/bin/env bash\necho\n' > bin/tool
+  run "${kit_checkout}/bin/kit" context bin/tool
+  [ "$output" = ".kit/rules/bash.md" ]
+  run "${kit_checkout}/bin/kit" context bin/other
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+  run "${kit_checkout}/bin/kit" context docs/a.md "${PWD}/.github/workflows/x.yml" lib/x.md
+  [ "${lines[0]}" = ".kit/rules/markdown.md" ]
+  [ "${lines[1]}" = ".kit/rules/yaml.md" ]
+  [ "${#lines[@]}" -eq 2 ]
+}
+
+@test "the json answer is one object per path, and every ask is logged" {
+  run "${kit_checkout}/bin/kit" context --json justfile README.md
+  [ "$status" -eq 0 ]
+  [ "$(jq -c .rules <<<"${lines[0]}")" = '[".kit/rules/just.md"]' ]
+  [ "$(jq -r .path <<<"${lines[1]}")" = "README.md" ]
+  [ "$(cut -f 2 .git/kit/context.log | paste -s -d ' ' -)" = "justfile README.md" ]
+}
+
+@test "the claude hook gives a rule's text once per session, then its path" {
+  input='{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"'"${PWD}"'/lib/run.sh","content":""}}'
+  run "${kit_checkout}/bin/kit" context --claude <<<"${input}"
+  [ "$status" -eq 0 ]
+  text=$(jq -r .hookSpecificOutput.additionalContext <<<"$output")
+  [[ "${text}" == "lib/run.sh is governed by .kit/rules/bash.md. Its text:"* ]]
+  [[ "${text}" == *"# Bash"* ]]
+  run "${kit_checkout}/bin/kit" context --claude <<<"${input}"
+  text=$(jq -r .hookSpecificOutput.additionalContext <<<"$output")
+  [ "${text}" = "lib/run.sh is governed by .kit/rules/bash.md, which you have read this session." ]
+  run "${kit_checkout}/bin/kit" context --claude <<<'{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"x.bin"}}'
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 75b5e02..ed11d71 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -1,9 +1,9 @@
 #!/usr/bin/env bats
-# kit.bats - bin/kit install, check, and update against a fresh repository
+# kit.bats - bin/kit install, module, check, and update against a fresh repository
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # Each test gets an empty git repository under a temporary directory and runs the kit from this checkout against
-# it. The update tests build a second, later payload from the first so the three-way merge has a base.
+# it. The update tests build a second, later release from the first so the three-way merge has a base.
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
@@ -13,80 +13,103 @@ setup() {
 }
 
 teardown() {
-  rm -rf "${repo}"
+  rm -rf "${repo}" "${repo}.later"
 }
 
 # later-release <dir> copies this checkout's release to <dir> as version 9.9.9 with one changed rule line.
 later-release() {
   mkdir -p "$1"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "$1/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/modules" "$1/"
   printf '9.9.9\n' > "$1/version"
-  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/tree/.kit/rules/json.md"
+  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/modules/kit/tree/.kit/rules/json.md"
 }
 
-@test "install with the claude target writes the tree, the mirrors, the workflow, the settings, and the manifest" {
-  run "${kit_checkout}/bin/kit" install claude
+@test "install with no module writes the default modules and nothing under .claude" {
+  run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
   [ -f .kit/1st.md ]
   [ -f .kit/rules/bash.md ]
-  [ ! -e .kit/bash ]
   [ -f .kit/lefthook.yml ]
-  [ -f .claude/rules/kit-markdown.md ]
-  [ ! -L .claude/rules/kit-markdown.md ]
-  cmp --silent .claude/rules/kit-markdown.md .kit/rules/markdown.md
-  head -n 1 .claude/rules/kit-bash.md | grep --quiet --line-regexp -- '---'
-  grep --quiet '"\*\*/\*\.sh"' .claude/rules/kit-bash.md
-  [ -f .github/workflows/kit-ci.yml ]
-  jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
-  grep --quiet '^version unreleased$' .kit/manifest
-  grep --quiet '^targets claude$' .kit/manifest
-}
-
-@test "install with no target writes the neutral tree and nothing under .claude" {
-  run "${kit_checkout}/bin/kit" install
-  [ "$status" -eq 0 ]
-  [ -f .kit/1st.md ]
   [ -f .github/workflows/kit-ci.yml ]
+  grep --quiet '^    runs-on: ubuntu-latest$' .github/workflows/kit-ci.yml
   [ ! -e .claude ]
-  grep --quiet '^targets$' .kit/manifest
+  grep --quiet '^version unreleased$' .kit/manifest
+  grep --quiet '^modules kit ci lefthook$' .kit/manifest
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
-  # a stray file under a target not taken is nobody's business
-  mkdir -p .claude/rules && printf 'theirs\n' > .claude/rules/kit-json.md
+  # a stray file under a module not active is nobody's business
+  mkdir -p .claude && printf '{"model":"x"}\n' > .claude/settings.json
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
 }
 
-@test "install refuses a target this release does not know and names the known ones" {
+@test "install with claude adds the deny list and the context hook, and copies no rule" {
+  run "${kit_checkout}/bin/kit" install claude
+  [ "$status" -eq 0 ]
+  grep --quiet '^modules kit claude ci lefthook$' .kit/manifest
+  jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
+  jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
+  [ ! -e .claude/rules ]
+}
+
+@test "install refuses a module this release does not know and names the known ones" {
   run "${kit_checkout}/bin/kit" install gemini
   [ "$status" -eq 2 ]
-  [[ "$output" == *"the targets are: claude"* ]]
+  [[ "$output" == *"the modules are: ci claude kit lefthook"* ]]
   [ ! -e .kit/manifest ]
 }
 
-@test "target add places a target's files, and target remove takes them and the kit's entries back out" {
+@test "module add places a module's files, and module remove takes them and the kit's entries back out" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
   "${kit_checkout}/bin/kit" install
-  [ "$("${kit_checkout}/bin/kit" target list)" = "" ]
-  run "${kit_checkout}/bin/kit" target add claude
+  run "${kit_checkout}/bin/kit" module list
+  [[ "$output" == *"✅ kit "* ]]
+  [[ "$output" == *"   claude "* ]]
+  run "${kit_checkout}/bin/kit" module add claude
   [ "$status" -eq 0 ]
-  [ "$("${kit_checkout}/bin/kit" target list)" = "claude" ]
-  [ -f .claude/rules/kit-bash.md ]
   jq --exit-status '.permissions.deny | index("Bash(git switch main *)")' .claude/settings.json >/dev/null
-  grep --quiet '^targets claude$' .kit/manifest
+  grep --quiet '^modules kit claude ci lefthook$' .kit/manifest
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
-  run "${kit_checkout}/bin/kit" target remove claude
+  run "${kit_checkout}/bin/kit" module remove claude
   [ "$status" -eq 0 ]
-  [ ! -e .claude/rules/kit-bash.md ]
   [ "$(jq --raw-output .model .claude/settings.json)" = "x" ]
   jq --exit-status '.permissions.deny == ["Bash(rm -rf /)"]' .claude/settings.json >/dev/null
-  grep --quiet '^targets$' .kit/manifest
+  jq --exit-status '.hooks == {"PreToolUse": []}' .claude/settings.json >/dev/null
+  grep --quiet '^modules kit ci lefthook$' .kit/manifest
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
 }
 
+@test "module remove refuses a module another active module depends on, and removes a leaf" {
+  "${kit_checkout}/bin/kit" install claude
+  run "${kit_checkout}/bin/kit" module remove kit
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"kit cannot be removed while"* ]]
+  [ -f .kit/1st.md ]
+  run "${kit_checkout}/bin/kit" module remove ci
+  [ "$status" -eq 0 ]
+  [ ! -e .github/workflows/kit-ci.yml ]
+  grep --quiet '^modules kit claude lefthook$' .kit/manifest
+}
+
+@test "a template takes the repository's answer over the module's default, and refuses a key with neither" {
+  mkdir .kit && printf 'ci_runner blacksmith-2vcpu\n' > .kit/answers
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  grep --quiet '^    runs-on: blacksmith-2vcpu$' .github/workflows/kit-ci.yml
+  grep --quiet 'uses: actions/checkout@' .github/workflows/kit-ci.yml
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  later-release "${repo}.later"
+  printf 'runner @ci_runner@ owner @owner@\n' > "${repo}.later/modules/ci/templates/OWNER"
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"OWNER needs an answer for 'owner'"* ]]
+  [ ! -e OWNER ]
+}
+
 @test "install keeps the repository's own settings keys and deny entries" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
@@ -108,12 +131,12 @@ later-release() {
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   printf 'edited\n' >> .kit/rules/yaml.md
-  rm .claude/rules/kit-json.md
+  rm .kit/lefthook.yml
   jq '.permissions.deny -= ["Bash(git reset --hard *)"]' .claude/settings.json > s && mv s .claude/settings.json
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 1 ]
   [[ "$output" == *".kit/rules/yaml.md differs"* ]]
-  [[ "$output" == *".claude/rules/kit-json.md is missing"* ]]
+  [[ "$output" == *".kit/lefthook.yml is missing"* ]]
   [[ "$output" == *"missing an entry the kit writes"* ]]
   [[ "$output" == *"3 finding(s)"* ]]
 }
@@ -134,28 +157,25 @@ later-release() {
   grep --quiet '^version 9.9.9$' .kit/manifest
   grep --quiet '^# JSON (ours)$' .kit/rules/json.md
   grep --quiet '^## Added in 9.9.9$' .kit/rules/json.md
-  grep --quiet '^## Added in 9.9.9$' .claude/rules/kit-json.md
   # the manifest carries the release's digest, so the edit still reads as an edit
-  release_digest=$(shasum -a 256 "${repo}.later/tree/.kit/rules/json.md" | cut -d ' ' -f 1)
+  release_digest=$(shasum -a 256 "${repo}.later/modules/kit/tree/.kit/rules/json.md" | cut -d ' ' -f 1)
   grep --quiet "^${release_digest}  .kit/rules/json.md$" .kit/manifest
   # and check names the one file that still differs from the release
   run "${repo}.later/bin/kit" check
   [ "$status" -eq 1 ]
   [[ "$output" == *".kit/rules/json.md differs"* ]]
   [[ "$output" == *"1 finding(s)"* ]]
-  rm -rf "${repo}.later"
 }
 
 @test "update refuses a path new in the release where the repository already has a different file" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
-  printf 'new rule\n' > "${repo}.later/tree/.kit/rules/toml.md"
+  printf 'new rule\n' > "${repo}.later/modules/kit/tree/.kit/rules/toml.md"
   printf 'mine\n' > .kit/rules/toml.md
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
   [[ "$output" == *".kit/rules/toml.md is new in 9.9.9"* ]]
   [ "$(cat .kit/rules/toml.md)" = "mine" ]
-  rm -rf "${repo}.later"
 }
 
 @test "update of an untouched install leaves check green" {
@@ -165,19 +185,17 @@ later-release() {
   [ "$status" -eq 0 ]
   run "${repo}.later/bin/kit" check
   [ "$status" -eq 0 ]
-  rm -rf "${repo}.later"
 }
 
 @test "update leaves conflict markers and fails when the same lines changed" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
-  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${repo}.later/tree/.kit/rules/json.md" && rm "${repo}.later/tree/.kit/rules/json.md.bak"
+  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${repo}.later/modules/kit/tree/.kit/rules/json.md" && rm "${repo}.later/modules/kit/tree/.kit/rules/json.md.bak"
   sed -i.bak 's/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
   grep --quiet '^<<<<<<<' .kit/rules/json.md
   [[ "$output" == *"conflict markers"* ]]
-  rm -rf "${repo}.later"
 }
 
 @test "update without the base release refuses an edited file and names the base" {
@@ -189,7 +207,6 @@ later-release() {
   run env PATH="${PWD}/shims:${PATH}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
   [[ "$output" == *"cannot be updated without the base release unreleased"* ]]
-  rm -rf "${repo}.later"
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/release.bats b/tests/release.bats
index ba5c9e3..2469254 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -16,7 +16,7 @@ teardown() {
   # packed the way the workflow packs it, with the tag's version stamped in
   version=9.9.9
   mkdir "kit-${version}"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/tree" "${kit_checkout}/targets" "kit-${version}/"
+  cp -R "${kit_checkout}/bin" "${kit_checkout}/modules" "kit-${version}/"
   printf '%s\n' "${version}" > "kit-${version}/version"
   tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
   rm -rf "kit-${version}"
@@ -24,7 +24,7 @@ teardown() {
   [ "$(ls unpacked)" = "kit-${version}" ]
   [ -x "unpacked/kit-${version}/bin/kit" ]
   [ -x "unpacked/kit-${version}/bin/kit-install.sh" ]
-  [ -L "unpacked/kit-${version}/targets/claude/.claude/rules/kit-bash.md" ]
+  [ -f "unpacked/kit-${version}/modules/claude/module" ]
   mkdir fresh && git -C fresh init --quiet --initial-branch=main
   cd fresh
   run "${work}/unpacked/kit-${version}/bin/kit" install claude
@@ -32,7 +32,7 @@ teardown() {
   run "${work}/unpacked/kit-${version}/bin/kit" check
   [ "$status" -eq 0 ]
   [ "$("${work}/unpacked/kit-${version}/bin/kit" version)" = "${version}" ]
-  [ ! -L .claude/rules/kit-bash.md ]
+  grep --quiet "^version ${version}$" .kit/manifest
 }
 
 # ----------------------------------------------------------------------------------------------------------------------

From efeee135f8e90cd4bed82428a6a811df0d1379b4 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 00:58:32 -0700
Subject: [PATCH 063/108] #4 bin/release.sh: the module order is the kit's own,
 not tsort's

A module after its dependencies, alphabetical otherwise, so the manifest's modules line is the same
on every machine; GNU and BSD tsort broke ties differently.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/release.sh | 36 ++++++++++++++++++++++++++----------
 tests/kit.bats |  4 ++--
 2 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/bin/release.sh b/bin/release.sh
index e8d03a3..9f2647d 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -55,13 +55,14 @@ release:require-modules() {
   done
 }
 
-# release:resolve <root> <name>… prints the named modules and everything they depend on, each once, a module
-# after the modules it depends on: the closure over depends, ordered by tsort over its edges.
+# release:resolve <root> <name>… prints the named modules and everything they depend on, each once: a module
+# after the modules it depends on, and alphabetical where that leaves a choice, so the order is the same on
+# every machine. A cycle is refused.
 release:resolve() {
-  local root=$1 module dep
+  local root=$1 module dep ready placed_count=0
   shift
-  local -A wanted=()
-  local -a queue=("$@")
+  local -A wanted=() placed=()
+  local -a queue=("$@") names=()
   while (( ${#queue[@]} > 0 ))
   do
     module=${queue[0]}
@@ -73,14 +74,29 @@ release:resolve() {
       queue+=("${dep}")
     done
   done
-  for module in "${!wanted[@]}"
+  readarray -t names < <(printf '%s\n' "${!wanted[@]}" | sort)
+  while (( placed_count < ${#names[@]} ))
   do
-    printf '%s %s\n' "${module}" "${module}"
-    for dep in $(release:field "${root}" "${module}" depends)
+    ready=''
+    for module in "${names[@]}"
     do
-      printf '%s %s\n' "${dep}" "${module}"
+      [[ -n "${placed[${module}]:-}" ]] && continue
+      for dep in $(release:field "${root}" "${module}" depends)
+      do
+        [[ -n "${placed[${dep}]:-}" ]] || continue 2
+      done
+      ready=${module}
+      break
     done
-  done | sort | tsort
+    if [[ -z "${ready}" ]]
+    then
+      error "the modules' depends lines form a cycle among: ${names[*]}"
+      return 1
+    fi
+    placed[${ready}]=1
+    placed_count=$(( placed_count + 1 ))
+    printf '%s\n' "${ready}"
+  done
 }
 
 # release:dependents <root> <module> <active>… prints the active modules that depend on <module>.
diff --git a/tests/kit.bats b/tests/kit.bats
index ed11d71..eebf5fc 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -46,7 +46,7 @@ later-release() {
 @test "install with claude adds the deny list and the context hook, and copies no rule" {
   run "${kit_checkout}/bin/kit" install claude
   [ "$status" -eq 0 ]
-  grep --quiet '^modules kit claude ci lefthook$' .kit/manifest
+  grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
   [ ! -e .claude/rules ]
@@ -69,7 +69,7 @@ later-release() {
   run "${kit_checkout}/bin/kit" module add claude
   [ "$status" -eq 0 ]
   jq --exit-status '.permissions.deny | index("Bash(git switch main *)")' .claude/settings.json >/dev/null
-  grep --quiet '^modules kit claude ci lefthook$' .kit/manifest
+  grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   run "${kit_checkout}/bin/kit" module remove claude

From 450e27fd573d6d17ee3cbc41898d84dbd7eda6b6 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:00:03 -0700
Subject: [PATCH 064/108] #4 .kit/manifest: the modules line in the resolver's
 order

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/manifest | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.kit/manifest b/.kit/manifest
index 5697a2c..cb7a597 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,6 +1,6 @@
 # .kit/manifest - written by kit, not by hand
 version unreleased
-modules kit claude ci lefthook
+modules kit ci claude lefthook
 86563533cd11f87831320d57b24d68d83c8d3a47382b09afeb71f5ee46e93584  .claude/settings.json
 cd66dc3b7fe79643f0a706e0ea571962906ffd117743c68e23aadbab7c91e143  .github/workflows/kit-ci.yml
 f7db408e409f39c36c9906efbedfd800054a654b44615b021bd02fd93fa4d57e  .kit/1st.md

From 8ce7398eb46693f9f79108eb0b0a22619e81780e Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:10:53 -0700
Subject: [PATCH 065/108] #4 bin/context.sh: the Claude hook names the rules
 and never quotes them

The same answer the plain call prints, so there is no session state, no compaction case, and
reading a rule stays an act the agent takes, one a hook on Read can record.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/context.sh     | 29 +++++++++--------------------
 docs/context.md    |  5 +++--
 tests/context.bats | 15 +++++----------
 3 files changed, 17 insertions(+), 32 deletions(-)

diff --git a/bin/context.sh b/bin/context.sh
index 975ff96..f1eec91 100644
--- a/bin/context.sh
+++ b/bin/context.sh
@@ -8,9 +8,9 @@
 # the first line of a file that exists, so a bash script with no extension is bash by its shebang. The rules are
 # discovered here and copied nowhere, which is what lets every harness, and every person, find them the same way.
 #
-# context:claude is the same answer in Claude Code's hook protocol: the hook input on stdin, the rules as
-# additional context on stdout. The first time a rule is named in a session its text is given; after that, its
-# path. docs/context.md is the description.
+# context:claude is the same answer in Claude Code's hook protocol: the hook input on stdin, the rules' paths as
+# additional context on stdout. It names, never quotes: reading the rule stays the agent's own act, one a hook on
+# Read can record. docs/context.md is the description.
 
 shopt -s extglob
 
@@ -139,30 +139,19 @@ context:render() {
 }
 
 # context:claude reads Claude Code's PreToolUse hook input on stdin and answers with the rules governing the file
-# the tool is about to write, as additional context: the rule's text the first time it is named in the session,
-# its path after that. A tool input with no file path, or a file no rule governs, gets no answer.
+# the tool is about to write, as additional context naming each rule's path. A tool input with no file path, or
+# a file no rule governs, gets no answer.
 context:claude() {
-  local input path session rule text='' given
+  local input path rules text=''
   input=$(cat)
   path=$(jq --raw-output '.tool_input.file_path // empty' <<<"${input}")
-  session=$(jq --raw-output '.session_id // "none"' <<<"${input}")
   [[ -n "${path}" ]] || return 0
   cd "$(git rev-parse --show-toplevel)" || return 0
   path=$(context:relative "${path}")
   context:log "${path}"
-  given="${TMPDIR:-/tmp}/kit-context-${session//[^A-Za-z0-9_-]/_}"
-  while IFS= read -r rule
-  do
-    [[ -n "${rule}" ]] || continue
-    if grep --quiet --line-regexp --fixed-strings "${rule}" "${given}" 2>/dev/null
-    then
-      text+="${path} is governed by ${rule}, which you have read this session."$'\n'
-    else
-      printf '%s\n' "${rule}" >> "${given}"
-      text+="${path} is governed by ${rule}. Its text:"$'\n\n'"$(cat "${rule}")"$'\n\n'
-    fi
-  done < <(context:rules "${path}")
-  [[ -n "${text}" ]] || return 0
+  rules=$(context:rules "${path}" | paste -s -d ' ' -)
+  [[ -n "${rules}" ]] || return 0
+  text="kit: ${path} is governed by ${rules}; read it before this change."
   jq --null-input --compact-output --arg text "${text}" \
     '{ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: $text } }'
 }
diff --git a/docs/context.md b/docs/context.md
index f28b4df..a9108df 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -43,8 +43,9 @@ kit context --claude
 ```
 
 It reads the hook's input on stdin, takes the file path from the tool's input, and answers in the hook's output
-with the rules as additional context: a rule's text the first time it is named in the session, its path after
-that. The session is told apart by the hook input's `session_id`, and what was given is kept under `TMPDIR`.
+with the rules' paths as additional context, the same answer the plain call prints. It names and never quotes, so
+reading the rule stays an act the agent takes, one a hook on `Read` can record and a check can compare against
+the context log. No state is kept between calls.
 
 A harness with no hook, and a person, use the plain call. `.kit/1st.md` names it as the step before any file is
 created or changed.
diff --git a/tests/context.bats b/tests/context.bats
index 080304a..268c40d 100644
--- a/tests/context.bats
+++ b/tests/context.bats
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# context.bats - kit context names a file's rules by path or by first line, logs the ask, and speaks Claude's hook
+# context.bats - kit context names a file's rules by path or by first line, logs the ask, and answers Claude's hook
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -8,8 +8,6 @@ setup() {
   git -C "${repo}" init --quiet --initial-branch=main
   cd "${repo}"
   "${kit_checkout}/bin/kit" install >/dev/null
-  export TMPDIR="${repo}/tmp"
-  mkdir "${TMPDIR}"
 }
 
 teardown() {
@@ -44,16 +42,13 @@ teardown() {
   [ "$(cut -f 2 .git/kit/context.log | paste -s -d ' ' -)" = "justfile README.md" ]
 }
 
-@test "the claude hook gives a rule's text once per session, then its path" {
+@test "the claude hook names the rules of the file about to be written, and nothing for a file none governs" {
   input='{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"'"${PWD}"'/lib/run.sh","content":""}}'
   run "${kit_checkout}/bin/kit" context --claude <<<"${input}"
   [ "$status" -eq 0 ]
-  text=$(jq -r .hookSpecificOutput.additionalContext <<<"$output")
-  [[ "${text}" == "lib/run.sh is governed by .kit/rules/bash.md. Its text:"* ]]
-  [[ "${text}" == *"# Bash"* ]]
-  run "${kit_checkout}/bin/kit" context --claude <<<"${input}"
-  text=$(jq -r .hookSpecificOutput.additionalContext <<<"$output")
-  [ "${text}" = "lib/run.sh is governed by .kit/rules/bash.md, which you have read this session." ]
+  [ "$(jq -r .hookSpecificOutput.hookEventName <<<"$output")" = "PreToolUse" ]
+  [ "$(jq -r .hookSpecificOutput.additionalContext <<<"$output")" = "kit: lib/run.sh is governed by .kit/rules/bash.md; read it before this change." ]
+  [ "$(cut -f 2 .git/kit/context.log)" = "lib/run.sh" ]
   run "${kit_checkout}/bin/kit" context --claude <<<'{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"x.bin"}}'
   [ "$status" -eq 0 ]
   [ -z "$output" ]

From a6965e9c37fedbae2d65e680d49b5579f04e34ee Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:24:32 -0700
Subject: [PATCH 066/108] #4 modules: module.yml, files/<base>/ with repo and
 home, and Claude reads AGENTS.md like everyone else

A module's metadata is module.yml, in the small subset of YAML bin/yaml.sh reads, the same reader
the rules' frontmatter goes through. A module delivers from files/<base>/ and templates/<base>/,
with two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's ~,
recorded in ~/.kit/manifest, the desk's own record, which kit check reads where it exists and
reports absent where it does not. A module naming another base is refused with the bases listed.
KIT_HOME stands in for the home directory, and every test sets it, so no test touches the real one.

Claude Code reads CLAUDE.md and not AGENTS.md, so the claude module places .claude/CLAUDE.md, two
lines importing AGENTS.md, and AGENTS.md opens with the sentence every agent reads, in prose, and no
import of Claude's own. 38 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/CLAUDE.md                             |   2 +
 .kit/1st.md                                   |   5 +-
 .kit/manifest                                 |   3 +-
 AGENTS.md                                     |   5 +-
 README.md                                     |  36 ++--
 bin/context.sh                                |  18 +-
 bin/kit-check.sh                              |  47 +++--
 bin/kit-install.sh                            |  22 ++-
 bin/kit-module.sh                             |  32 ++--
 bin/kit-update.sh                             | 101 +++++-----
 bin/release.sh                                | 175 +++++++++++++-----
 bin/yaml.sh                                   |  50 +++++
 docs/modules.md                               |  55 ++++--
 modules/ci/module                             |   8 -
 modules/ci/module.yml                         |  10 +
 .../{ => repo}/.github/workflows/kit-ci.yml   |   0
 modules/claude/docs/README.md                 |   8 +-
 modules/claude/files/repo/.claude/CLAUDE.md   |   2 +
 .../repo}/.claude/settings.json               |   0
 modules/claude/module                         |   6 -
 modules/claude/module.yml                     |   7 +
 modules/kit/{tree => files/repo}/.kit/1st.md  |   5 +-
 .../{tree => files/repo}/.kit/rules/bash.md   |   0
 .../repo}/.kit/rules/gitignore.md             |   0
 .../{tree => files/repo}/.kit/rules/json.md   |   0
 .../{tree => files/repo}/.kit/rules/just.md   |   0
 .../repo}/.kit/rules/markdown.md              |   0
 .../{tree => files/repo}/.kit/rules/yaml.md   |   0
 modules/kit/module                            |   6 -
 modules/kit/module.yml                        |   6 +
 .../{tree => files/repo}/.kit/lefthook.yml    |   0
 modules/lefthook/module                       |   7 -
 modules/lefthook/module.yml                   |   8 +
 tests/context.bats                            |   2 +
 tests/kit.bats                                |  57 +++++-
 tests/release.bats                            |   4 +-
 36 files changed, 466 insertions(+), 221 deletions(-)
 create mode 100644 .claude/CLAUDE.md
 create mode 100644 bin/yaml.sh
 delete mode 100644 modules/ci/module
 create mode 100644 modules/ci/module.yml
 rename modules/ci/templates/{ => repo}/.github/workflows/kit-ci.yml (100%)
 create mode 100644 modules/claude/files/repo/.claude/CLAUDE.md
 rename modules/claude/{tree => files/repo}/.claude/settings.json (100%)
 delete mode 100644 modules/claude/module
 create mode 100644 modules/claude/module.yml
 rename modules/kit/{tree => files/repo}/.kit/1st.md (95%)
 rename modules/kit/{tree => files/repo}/.kit/rules/bash.md (100%)
 rename modules/kit/{tree => files/repo}/.kit/rules/gitignore.md (100%)
 rename modules/kit/{tree => files/repo}/.kit/rules/json.md (100%)
 rename modules/kit/{tree => files/repo}/.kit/rules/just.md (100%)
 rename modules/kit/{tree => files/repo}/.kit/rules/markdown.md (100%)
 rename modules/kit/{tree => files/repo}/.kit/rules/yaml.md (100%)
 delete mode 100644 modules/kit/module
 create mode 100644 modules/kit/module.yml
 rename modules/lefthook/{tree => files/repo}/.kit/lefthook.yml (100%)
 delete mode 100644 modules/lefthook/module
 create mode 100644 modules/lefthook/module.yml

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 0000000..819bb57
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,2 @@
+<!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
+@../AGENTS.md
diff --git a/.kit/1st.md b/.kit/1st.md
index 0d4fc49..ccb0fc6 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -97,8 +97,9 @@ it writes; everything else is copied as it is.
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
   refuses a pull request not linked to an open issue.
-- `claude`: for Claude Code, seven deny rules merged into `.claude/settings.json`, and a hook that runs
-  `kit context` before every write so the rules reach the agent without being asked for.
+- `claude`: for Claude Code, which reads `CLAUDE.md` and not `AGENTS.md`: `.claude/CLAUDE.md` importing
+  `AGENTS.md`, seven deny rules merged into `.claude/settings.json`, and a hook that runs `kit context` before
+  every write so the rules are named to the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/manifest b/.kit/manifest
index cb7a597..4ad7cd4 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,9 +1,10 @@
 # .kit/manifest - written by kit, not by hand
 version unreleased
 modules kit ci claude lefthook
+930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 86563533cd11f87831320d57b24d68d83c8d3a47382b09afeb71f5ee46e93584  .claude/settings.json
 cd66dc3b7fe79643f0a706e0ea571962906ffd117743c68e23aadbab7c91e143  .github/workflows/kit-ci.yml
-f7db408e409f39c36c9906efbedfd800054a654b44615b021bd02fd93fa4d57e  .kit/1st.md
+37df46c8bbe5a02b972412f0fea25246e14ab66cb0421c8cb23857c3fdb94189  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 6f1101c9b19bfbe2d42d6e602e92d0df4dc650a4a04ccbd06c5a03a5e6e5edc2  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
diff --git a/AGENTS.md b/AGENTS.md
index c1f467d..43408df 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,5 @@
-@.kit/1st.md
-
-Read .kit/1st.md first. It is the kit's entry file, and this repository uses its own kit.
+Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
+repository trustworthy. This repository is the kit's own source, and uses it.
 
 ## This repository's own rules
 
diff --git a/README.md b/README.md
index 63080ea..9c6aa6d 100644
--- a/README.md
+++ b/README.md
@@ -57,26 +57,26 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
 
 ## Take the kit
 
-In the repository, install it and point `AGENTS.md` at it:
+In the repository, install it and point `AGENTS.md` at it, in prose, the same sentence for every agent:
 
 ```sh
 kit install claude
 ```
 
 ```markdown
-@.kit/1st.md
-
-Read .kit/1st.md first.
+Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
+repository trustworthy.
 ```
 
-The rest of `AGENTS.md` is yours. Everything the kit delivers is a module, and `install` activates the default
-ones, `kit`, `lefthook`, and `ci`, plus those named: `claude` is the adapter for Claude Code, and a repository
-with no adapter still binds every agent that reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the
-root justfile for the delivered `CI` job to run, and take the pre-commit linters by pinning `lefthook`, putting
-`extends: [.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit module list`,
-`kit module add`, and `kit module remove` show and change the set later, and [docs/modules.md](docs/modules.md)
-describes a module. An agent asks `kit context <path>` which rules govern a file before it creates or changes
-it; [docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
+The rest of `AGENTS.md` is yours. Everything the kit delivers is a module, and `install` activates the default ones,
+`kit`, `lefthook`, and `ci`, plus those named: `claude` is the adapter for Claude Code, which reads `CLAUDE.md` and
+not `AGENTS.md`, so the module places `.claude/CLAUDE.md` importing `AGENTS.md` and Claude reads what everyone else
+reads. A repository with no adapter still binds every agent that reads `AGENTS.md`. Commit what it wrote, keep a `ci`
+recipe in the root justfile for the delivered `CI` job to run, and take the pre-commit linters by pinning `lefthook`,
+putting `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit module
+list`, `kit module add`, and `kit module remove` show and change the set later, and [docs/modules.md](docs/modules.md)
+describes a module. An agent asks `kit context <path>` which rules govern a file before it creates or changes it;
+[docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
 
 To move to a new release, bump the pin or reinstall, then run `kit update`: a delivered file you left alone is
 replaced, one you edited is three-way merged with the previous release as the base, which `update` fetches from
@@ -120,8 +120,8 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 ## Maintaining
 
 This repository is both the source of the kit and a consumer of it. The release is the checkout: `modules/<name>/`
-is what a consumer activating that module gets, its `tree/` mirrored at the consumer's root and its `templates/`
-rendered from the consumer's answers first; `bin/` is the machinery, `bin/kit` dispatching to one executable
+is what a consumer activating that module gets, its `files/repo/` mirrored at the consumer's root and its
+`templates/repo/` rendered from the consumer's answers first; `bin/` is the machinery, `bin/kit` dispatching to one executable
 `bin/kit-<verb>.sh` per verb, each sourcing the bash modules beside it; and `docs/` with each module's `docs/` is
 the documentation. [docs/modules.md](docs/modules.md) is the module format.
 
@@ -129,10 +129,10 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 
 | Installed copy | Written from |
 | --- | --- |
-| `.kit/1st.md`, `.kit/rules/` | `modules/kit/tree/.kit/` |
-| `.kit/lefthook.yml` | `modules/lefthook/tree/.kit/lefthook.yml` |
-| `.github/workflows/kit-ci.yml` | `modules/ci/templates/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
-| `.claude/settings.json` | `modules/claude/tree/.claude/settings.json`, merged by key; here only the kit's entries |
+| `.kit/1st.md`, `.kit/rules/` | `modules/kit/files/repo/.kit/` |
+| `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
+| `.github/workflows/kit-ci.yml` | `modules/ci/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
+| `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
 A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the
diff --git a/bin/context.sh b/bin/context.sh
index f1eec91..9529455 100644
--- a/bin/context.sh
+++ b/bin/context.sh
@@ -12,24 +12,14 @@
 # additional context on stdout. It names, never quotes: reading the rule stays the agent's own act, one a hook on
 # Read can record. docs/context.md is the description.
 
+use yaml
 shopt -s extglob
 
-# context_log is where every ask is recorded, under the repository's git directory, shared by its worktrees.
+# context:log-path prints where every ask is recorded: under the repository's git directory, shared by its worktrees.
 context:log-path() {
   printf '%s/kit/context.log\n' "$(git rev-parse --path-format=absolute --git-common-dir)"
 }
 
-# context:frontmatter <file> <key> prints the items of the list under <key> in the file's frontmatter, unquoted.
-context:frontmatter() {
-  awk -v key="$2" '
-    NR == 1 && $0 != "---" { exit }
-    NR > 1 && $0 == "---" { exit }
-    $0 == key ":" { in_key = 1; next }
-    /^[a-z]+:/ { in_key = 0 }
-    in_key && /^  - / { item = $0; sub(/^  - /, "", item); gsub(/^"|"$/, "", item); print item }
-  ' "$1"
-}
-
 # context:relative <path> prints <path> relative to the repository root. A relative path is taken from the current
 # directory. The nearest directory of the path that exists is resolved physically, as git reports the root, so a
 # path through a symlinked directory, or to a file not yet created, still cuts at the root.
@@ -74,7 +64,7 @@ context:rules() {
         printf '%s\n' "${rule}"
         continue 2
       fi
-    done < <(context:frontmatter "${rule}" paths)
+    done < <(yaml:list "${rule}" paths)
     [[ -n "${first}" ]] || continue
     while IFS= read -r pattern
     do
@@ -84,7 +74,7 @@ context:rules() {
         printf '%s\n' "${rule}"
         continue 2
       fi
-    done < <(context:frontmatter "${rule}" content)
+    done < <(yaml:list "${rule}" content)
   done
 }
 
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index 8f50bdc..aaed143 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -2,6 +2,9 @@
 # kit-check - fail when a delivered file differs from the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# Every path under the repository is checked. A path under home is checked where ~/.kit/manifest exists, that is,
+# on a desk that installed; a machine with none, such as a runner, is told so and the home base is skipped.
+#
 # see: bin/release.sh
 
 set -o errexit -o nounset -o pipefail
@@ -25,29 +28,41 @@ then
   error ".kit/manifest records kit ${version}, and the pinned release is $(release:version); run: kit update"
   findings=$(( findings + 1 ))
 fi
-while IFS=$'\t' read -r path src
+# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
+for base in "${release_bases[@]}"
 do
-  if [[ ! -f "${path}" ]]
-  then
-    error "${path} is missing"
-    findings=$(( findings + 1 ))
-  elif release:merged "${path}"
+  delivered=$(release:delivered "${kit_root}" "${base}" "${modules[@]}")
+  [[ -n "${delivered}" ]] || continue
+  if [[ "${base}" != repo && ! -f "$(release:manifest "${base}")" ]]
   then
-    if ! command -v jq >/dev/null 2>&1
+    info "${base}: nothing is installed under $(release:base-root "${base}") on this machine, so its paths were not checked"
+    continue
+  fi
+  while IFS=$'\t' read -r path src
+  do
+    dest=$(release:dest "${base}" "${path}")
+    if [[ ! -f "${dest}" ]]
     then
-      error "run: mise install (jq is not on PATH, so ${path} could not be read)"
+      error "${dest} is missing"
       findings=$(( findings + 1 ))
-    elif ! release:json-holds "${path}" "${src}"
+    elif release:merged "${dest}"
     then
-      error "${path} is missing an entry the kit writes; run: kit update"
+      if ! command -v jq >/dev/null 2>&1
+      then
+        error "run: mise install (jq is not on PATH, so ${dest} could not be read)"
+        findings=$(( findings + 1 ))
+      elif ! release:json-holds "${dest}" "${src}"
+      then
+        error "${dest} is missing an entry the kit writes; run: kit update"
+        findings=$(( findings + 1 ))
+      fi
+    elif ! cmp --silent "${src}" "${dest}"
+    then
+      error "${dest} differs from the pinned release"
       findings=$(( findings + 1 ))
     fi
-  elif ! cmp --silent "${src}" "${path}"
-  then
-    error "${path} differs from the pinned release"
-    findings=$(( findings + 1 ))
-  fi
-done < <(release:delivered "${kit_root}" "${modules[@]}")
+  done <<<"${delivered}"
+done
 if (( findings > 0 ))
 then
   error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index a290581..137e596 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
-# kit-install - mirror the release into the repository (kit verb)
+# kit-install - mirror the release into the repository, and into the home directory (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Activates the default modules and the named ones, with the modules they depend on, places what they deliver,
-# and writes .kit/manifest.
+# Activates the default modules and the named ones, with the modules they depend on, places what they deliver
+# under each base, and writes the manifests: .kit/manifest, and ~/.kit/manifest when a module delivers to home.
 #
 # see: bin/release.sh
 
@@ -29,12 +29,18 @@ read -r -a defaults <<<"$(release:default-modules "${kit_root}" | paste -s -d '
 read -r -a modules <<<"$(release:resolve "${kit_root}" "${defaults[@]}" "$@" | paste -s -d ' ' -)"
 release:render-all "${kit_root}" "${modules[@]}"
 section "kit install $(release:version), modules: ${modules[*]}"
-while IFS=$'\t' read -r path src
+# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
+for base in "${release_bases[@]}"
 do
-  step "${path}"
-  release:place "${src}" "${path}"
-done < <(release:delivered "${kit_root}" "${modules[@]}")
-release:write-manifest "${modules[@]}"
+  while IFS=$'\t' read -r path src
+  do
+    [[ -n "${path}" ]] || continue
+    dest=$(release:dest "${base}" "${path}")
+    step "${dest}"
+    release:place "${src}" "${dest}"
+  done < <(release:delivered "${kit_root}" "${base}" "${modules[@]}")
+done
+release:write-manifests "${modules[@]}"
 release:finish "${modules[@]}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-module.sh b/bin/kit-module.sh
index 0d37281..1fd3556 100755
--- a/bin/kit-module.sh
+++ b/bin/kit-module.sh
@@ -21,6 +21,7 @@ esac
 release:require-manifest
 read -r -a active <<<"$(release:manifest-modules)"
 
+# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
 case "${verb}" in
   (list)
     for module in $(release:modules)
@@ -29,7 +30,7 @@ case "${verb}" in
       then mark='✅'
       else mark='  '
       fi
-      printf '%s %-10s %s\n' "${mark}" "${module}" "$(release:field "${kit_root}" "${module}" description)"
+      printf '%s %-10s %s\n' "${mark}" "${module}" "$(release:description "${kit_root}" "${module}")"
     done
     ;;
   (add)
@@ -39,13 +40,17 @@ case "${verb}" in
     read -r -a wanted <<<"$(release:resolve "${kit_root}" "${active[@]}" "$@" | paste -s -d ' ' -)"
     release:render-all "${kit_root}" "${wanted[@]}"
     section "kit module add $*"
-    while IFS= read -r path
+    for base in "${release_bases[@]}"
     do
-      [[ -n "${path}" ]] || continue
-      step "${path}"
-      release:place "$(release:source-of "${kit_root}" "${path}" "${wanted[@]}")" "${path}"
-    done < <(release:paths-beyond "${kit_root}" "${active[*]}" "${wanted[*]}")
-    release:write-manifest "${wanted[@]}"
+      while IFS= read -r path
+      do
+        [[ -n "${path}" ]] || continue
+        dest=$(release:dest "${base}" "${path}")
+        step "${dest}"
+        release:place "$(release:source-of "${kit_root}" "${base}" "${path}" "${wanted[@]}")" "${dest}"
+      done < <(release:paths-beyond "${kit_root}" "${base}" "${active[*]}" "${wanted[*]}")
+    done
+    release:write-manifests "${wanted[@]}"
     ok "modules: ${wanted[*]}"
     ;;
   (remove)
@@ -70,12 +75,15 @@ case "${verb}" in
     done
     release:render-all "${kit_root}" "${active[@]}"
     section "kit module remove $*"
-    while IFS= read -r path
+    for base in "${release_bases[@]}"
     do
-      [[ -n "${path}" ]] || continue
-      release:unplace "$(release:source-of "${kit_root}" "${path}" "${active[@]}")" "${path}"
-    done < <(release:paths-beyond "${kit_root}" "${remaining[*]}" "${active[*]}")
-    release:write-manifest "${remaining[@]}"
+      while IFS= read -r path
+      do
+        [[ -n "${path}" ]] || continue
+        release:unplace "$(release:source-of "${kit_root}" "${base}" "${path}" "${active[@]}")" "$(release:dest "${base}" "${path}")"
+      done < <(release:paths-beyond "${kit_root}" "${base}" "${remaining[*]}" "${active[*]}")
+    done
+    release:write-manifests "${remaining[@]}"
     ok "modules: ${remaining[*]:-none}"
 esac
 
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index d29aed6..87c81c0 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
-# kit-update - move the repository to the pinned release (kit verb)
+# kit-update - move the repository, and the home directory, to the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A file whose digest still matches the manifest, which records the previous release's own content, is replaced.
+# A file whose digest still matches its manifest, which records the previous release's own content, is replaced.
 # An edited one is three-way merged with the previous release as the base, which release:fetch finds or fetches.
-# A path the previous release did not deliver is written only where the repository has nothing, or the same
-# thing, there. A template is rendered from the repository's answers in both releases before either is compared.
+# A path the previous release did not deliver is written only where there is nothing, or the same thing, there.
+# A template is rendered from the repository's answers in both releases before either is compared. The home base
+# is updated against ~/.kit/manifest the same way.
 #
 # see: bin/release.sh
 
@@ -44,57 +45,63 @@ needs_base=false
 [[ "${previous}" != "${current}" ]] && needs_base=true
 
 conflicts=0
-while IFS=$'\t' read -r path src
+# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
+for base in "${release_bases[@]}"
 do
-  recorded=$(awk -v p="${path}" '$2 == p { print $1 }' .kit/manifest)
-  if [[ -z "${recorded}" ]]
-  then
-    # A path the previous release did not deliver: written where the repository has nothing, or the same thing.
-    if release:merged "${path}" || [[ ! -f "${path}" ]]
+  while IFS=$'\t' read -r path src
+  do
+    [[ -n "${path}" ]] || continue
+    dest=$(release:dest "${base}" "${path}")
+    recorded=$(release:recorded "${base}" "${path}")
+    if [[ -z "${recorded}" ]]
     then
-      step "${path}: new in ${current}, written"
-      release:place "${src}" "${path}"
-    elif cmp --silent "${src}" "${path}"
+      # A path the previous release did not deliver: written where there is nothing, or the same thing.
+      if release:merged "${dest}" || [[ ! -f "${dest}" ]]
+      then
+        step "${dest}: new in ${current}, written"
+        release:place "${src}" "${dest}"
+      elif cmp --silent "${src}" "${dest}"
+      then
+        step "${dest}: new in ${current}, and already as the release has it"
+      else
+        error "${dest} is new in ${current} and a file is there already; move yours aside, then run: kit update"
+        conflicts=$(( conflicts + 1 ))
+      fi
+      continue
+    fi
+    previous_src=""
+    [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "${modules[@]}")
+    if [[ "${needs_base}" == true && -z "${previous_src}" ]]
     then
-      step "${path}: new in ${current}, and already as the release has it"
-    else
-      error "${path} is new in ${current} and the repository has a file there; move yours aside, then run: kit update"
+      # Without the base, neither a merge nor the removal of the previous release's entries is possible.
+      error "${dest} cannot be updated without the base release ${previous}; set KIT_BASE to a copy of it"
       conflicts=$(( conflicts + 1 ))
+      continue
     fi
-    continue
-  fi
-  base=""
-  [[ -n "${base_root}" ]] && base=$(release:source-of "${base_root}" "${path}" "${modules[@]}")
-  if [[ "${needs_base}" == true && -z "${base}" ]]
-  then
-    # Without the base, neither a merge nor the removal of the previous release's entries is possible.
-    error "${path} cannot be updated without the base release ${previous}; set KIT_BASE to a copy of it"
-    conflicts=$(( conflicts + 1 ))
-    continue
-  fi
-  if release:merged "${path}"
-  then
-    step "${path}: merged by key"
-    release:place "${src}" "${path}" "${base}"
-  elif [[ ! -f "${path}" ]]
-  then
-    step "${path}: missing, written"
-    release:place "${src}" "${path}"
-  elif [[ "${recorded}" == "$(release:digest < "${path}")" ]]
-  then
-    step "${path}: unchanged since ${previous}, replaced"
-    release:place "${src}" "${path}"
-  else
-    step "${path}: edited since ${previous}, three-way merged"
-    if ! git merge-file --marker-size 7 "${path}" "${base}" "${src}"
+    if release:merged "${dest}"
     then
-      warn "${path}: conflict markers are left in the file; resolve them, then run: kit check"
-      conflicts=$(( conflicts + 1 ))
+      step "${dest}: merged by key"
+      release:place "${src}" "${dest}" "${previous_src}"
+    elif [[ ! -f "${dest}" ]]
+    then
+      step "${dest}: missing, written"
+      release:place "${src}" "${dest}"
+    elif [[ "${recorded}" == "$(release:digest < "${dest}")" ]]
+    then
+      step "${dest}: unchanged since ${previous}, replaced"
+      release:place "${src}" "${dest}"
+    else
+      step "${dest}: edited since ${previous}, three-way merged"
+      if ! git merge-file --marker-size 7 "${dest}" "${previous_src}" "${src}"
+      then
+        warn "${dest}: conflict markers are left in the file; resolve them, then run: kit check"
+        conflicts=$(( conflicts + 1 ))
+      fi
     fi
-  fi
-done < <(release:delivered "${kit_root}" "${modules[@]}")
+  done < <(release:delivered "${kit_root}" "${base}" "${modules[@]}")
+done
 
-release:write-manifest "${modules[@]}"
+release:write-manifests "${modules[@]}"
 if (( conflicts > 0 ))
 then
   error "${conflicts} file(s) need a hand; see above."
diff --git a/bin/release.sh b/bin/release.sh
index 9f2647d..9a9045e 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -4,14 +4,44 @@
 # release.sh - the release's modules, the one merge rule, the templates, and the manifest (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A release is bin/ and modules/. Each modules/<name>/ is a module: a `module` file of metadata, a tree/ mirrored
-# at the repository root, and templates/ with @key@ rendered from the repository's answers, then placed the same way. A
+# A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
+# mirrored at the base's root; and templates/<base>/, with @key@ rendered from the repository's answers, then
+# mirrored the same way. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's
+# home directory, recorded in ~/.kit/manifest, which is the desk's record rather than the repository's. A
 # destination ending in .json is merged by key, with the kit's keys set, the kit's array entries added, and on
 # update or removal only the previous release's entries taken out. .kit/manifest records the version, the active
 # modules, and the release's digest for every delivered path. docs/modules.md is the format's description.
 #
 # Every function reads a release from a root, kit_root by default, which bin/kit exports.
 
+use yaml
+
+# release_bases are the destinations a module may deliver to, as the subdirectories of files/ and templates/.
+declare -gra release_bases=(repo home)
+
+# release:base-root <base> prints the directory the base's files are mirrored at: the repository root, which the
+# verbs run from, or the home directory, KIT_HOME when set so a test can stand in for it.
+release:base-root() {
+  case "$1" in
+    (repo) printf '.\n' ;;
+    (home) printf '%s\n' "${KIT_HOME:-${HOME}}" ;;
+    (*)
+      error "'$1' is not a base; the bases are: ${release_bases[*]}"
+      return 2
+  esac
+}
+
+# release:dest <base> <path> prints where a delivered path lands.
+release:dest() {
+  if [[ "$1" == repo ]]
+  then printf '%s\n' "$2"
+  else printf '%s/%s\n' "$(release:base-root "$1")" "$2"
+  fi
+}
+
+# release:manifest <base> prints the base's manifest: .kit/manifest in the repository, ~/.kit/manifest for home.
+release:manifest() { release:dest "$1" .kit/manifest; }
+
 # A release carries a version file the release workflow stamps from the tag; a checkout carries none and is
 # "unreleased", the one version kit update never asks mise for.
 declare -gr release_unreleased=unreleased
@@ -21,22 +51,26 @@ release:version() {
   cat "${kit_root}/version" 2>/dev/null || printf '%s\n' "${release_unreleased}"
 }
 
-# release:modules [<root>] prints the modules the release carries.
+# release:modules [<root>] prints the modules the release carries: every modules/<name>/ with a module.yml.
 release:modules() {
-  (cd "${1:-${kit_root}}/modules" && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@' | sort)
+  (cd "${1:-${kit_root}}/modules" && find . -mindepth 2 -maxdepth 2 -name module.yml | sed 's@^\./@@; s@/module.yml$@@' | sort)
 }
 
-# release:field <root> <module> <keyword> prints the value of every <keyword> line in the module's metadata.
-release:field() {
-  sed -n "s/^$3 //p; s/^$3\$//p" "$1/modules/$2/module" 2>/dev/null || true
-}
+# release:meta <root> <module> prints the path of the module's metadata.
+release:meta() { printf '%s/modules/%s/module.yml\n' "$1" "$2"; }
+
+# release:description <root> <module> prints the module's one-line description.
+release:description() { yaml:value "$(release:meta "$1" "$2")" description; }
+
+# release:depends <root> <module> prints the modules this one depends on, one per line.
+release:depends() { yaml:list "$(release:meta "$1" "$2")" depends; }
 
-# release:default-modules <root> prints the modules active unless removed.
+# release:default-modules <root> prints the modules active unless removed: those whose default is true.
 release:default-modules() {
   local module
   for module in $(release:modules "$1")
   do
-    grep --quiet --line-regexp default "$1/modules/${module}/module" && printf '%s\n' "${module}"
+    [[ "$(yaml:value "$(release:meta "$1" "${module}")" default)" == true ]] && printf '%s\n' "${module}"
   done
   return 0
 }
@@ -47,7 +81,7 @@ release:require-modules() {
   shift
   for module in "$@"
   do
-    if [[ ! -f "${root}/modules/${module}/module" ]]
+    if [[ ! -f "$(release:meta "${root}" "${module}")" ]]
     then
       error "'${module}' is not a module this release knows; the modules are: $(release:modules "${root}" | paste -s -d ' ' -)"
       return 2
@@ -69,7 +103,7 @@ release:resolve() {
     queue=("${queue[@]:1}")
     [[ -n "${wanted[${module}]:-}" ]] && continue
     wanted[${module}]=1
-    for dep in $(release:field "${root}" "${module}" depends)
+    for dep in $(release:depends "${root}" "${module}")
     do
       queue+=("${dep}")
     done
@@ -81,7 +115,7 @@ release:resolve() {
     for module in "${names[@]}"
     do
       [[ -n "${placed[${module}]:-}" ]] && continue
-      for dep in $(release:field "${root}" "${module}" depends)
+      for dep in $(release:depends "${root}" "${module}")
       do
         [[ -n "${placed[${dep}]:-}" ]] || continue 2
       done
@@ -105,7 +139,7 @@ release:dependents() {
   shift 2
   for other in "$@"
   do
-    for dep in $(release:field "${root}" "${other}" depends)
+    for dep in $(release:depends "${root}" "${other}")
     do
       [[ "${dep}" == "${module}" ]] && printf '%s\n' "${other}"
     done
@@ -113,10 +147,10 @@ release:dependents() {
 }
 
 # release:answers <root> <module> prints "<key>\t<value>" for every answer the module's templates may use: the
-# module's defaults, each overridden by a "<key> <value>" line in the repository's .kit/answers.
+# module's defaults under answers:, each overridden by a "<key> <value>" line in the repository's .kit/answers.
 release:answers() {
   {
-    release:field "$1" "$2" answer
+    yaml:map "$(release:meta "$1" "$2")" answers | tr '\t' ' '
     [[ -f .kit/answers ]] && grep --invert-match '^#' .kit/answers
     true
   } | awk 'NF >= 2 { v = $0; sub(/^[^ ]+ +/, "", v); a[$1] = v } END { for (k in a) print k "\t" a[k] }'
@@ -133,14 +167,14 @@ release:tmp() {
   printf '%s\n' "${release_tmp}"
 }
 
-# release:render <root> <module> renders the module's templates once per process and prints the directory holding
-# them, or prints nothing for a module with no templates. A key is written @key@, autoconf's form, which neither
-# bash's ${var} nor GitHub's ${{ }} can be mistaken for; one with no answer refuses, naming the key.
+# release:render <root> <module> <base> renders the module's templates for <base> once per process and prints the
+# directory holding them, or prints nothing where the module has none. A key is written @key@, autoconf's form,
+# which neither bash's ${var} nor GitHub's ${{ }} can be mistaken for; one with no answer refuses, naming the key.
 release:render() {
-  local root=$1 module=$2 templates="$1/modules/$2/templates" out key value text file rel
+  local root=$1 module=$2 base=$3 templates="$1/modules/$2/templates/$3" out key value text file rel
   local -A answer=()
   [[ -d "${templates}" ]] || return 0
-  out="$(release:tmp)/$(printf '%s' "${root}" | release:digest)/${module}"
+  out="$(release:tmp)/$(printf '%s' "${root}" | release:digest)/${module}/${base}"
   if [[ ! -d "${out}" ]]
   then
     while IFS=$'\t' read -r key value
@@ -167,33 +201,48 @@ release:render() {
   printf '%s\n' "${out}"
 }
 
-# release:render-all <root> <module>… renders every named module's templates, refusing on the first unanswered key.
+# release:render-all <root> <module>… renders every named module's templates for every base, and refuses a base
+# the kit does not know, or an unanswered key, naming it.
 release:render-all() {
-  local root=$1 module
+  local root=$1 module kind base
   shift
   for module in "$@"
   do
-    release:render "${root}" "${module}" >/dev/null || return 1
+    for kind in files templates
+    do
+      for base in $(cd "${root}/modules/${module}/${kind}" 2>/dev/null && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@')
+      do
+        if ! release:among "${base}" "${release_bases[@]}"
+        then
+          error "modules/${module}/${kind}/${base} names a base the kit does not deliver to; the bases are: ${release_bases[*]}"
+          return 1
+        fi
+      done
+    done
+    for base in "${release_bases[@]}"
+    do
+      release:render "${root}" "${module}" "${base}" >/dev/null || return 1
+    done
   done
 }
 
-# release:layers <root> <module>… prints the directories mirrored at the repository root, in module order: each
-# module's tree/, then its rendered templates.
+# release:layers <root> <base> <module>… prints the directories mirrored at the base's root, in module order: each
+# module's files/<base>, then its rendered templates/<base>.
 release:layers() {
-  local root=$1 module rendered
-  shift
+  local root=$1 base=$2 module rendered
+  shift 2
   for module in "$@"
   do
-    [[ -d "${root}/modules/${module}/tree" ]] && printf '%s\n' "${root}/modules/${module}/tree"
-    rendered=$(release:render "${root}" "${module}")
+    [[ -d "${root}/modules/${module}/files/${base}" ]] && printf '%s\n' "${root}/modules/${module}/files/${base}"
+    rendered=$(release:render "${root}" "${module}" "${base}")
     [[ -n "${rendered}" ]] && printf '%s\n' "${rendered}"
   done
   return 0
 }
 
-# release:delivered <root> <module>… prints "<path>\t<source>" for every repository path the release at <root>
-# delivers for those modules, sorted by path, the last layer winning. A symlink is a source only when it points
-# at a file; a dangling one is refused here, where it is found.
+# release:delivered <root> <base> <module>… prints "<path>\t<source>" for every path under the base's root that
+# the release at <root> delivers for those modules, sorted by path, the last layer winning. A symlink is a source
+# only when it points at a file; a dangling one is refused here, where it is found.
 release:delivered() {
   local layer path src
   while IFS= read -r layer
@@ -211,21 +260,22 @@ release:delivered() {
   done
 }
 
-# release:source-of <root> <path> <module>… prints the release file behind one repository path, or nothing.
+# release:source-of <root> <base> <path> <module>… prints the release file behind one delivered path, or nothing.
 release:source-of() {
-  local root=$1 path=$2
-  shift 2
-  release:delivered "${root}" "$@" | awk -F '\t' -v p="${path}" '$1 == p { print $2 }'
+  local root=$1 base=$2 path=$3
+  shift 3
+  release:delivered "${root}" "${base}" "$@" | awk -F '\t' -v p="${path}" '$1 == p { print $2 }'
 }
 
-# release:paths-beyond <root> <before> <after> prints the paths the module set <after> delivers that <before>
-# does not; each set is one space-separated word.
+# release:paths-beyond <root> <base> <before> <after> prints the paths the module set <after> delivers under the
+# base that <before> does not; each set is one space-separated word.
 release:paths-beyond() {
-  local root=$1
+  local root=$1 base=$2
   local -a before after
-  read -r -a before <<<"$2"
-  read -r -a after <<<"$3"
-  comm -13 <(release:delivered "${root}" "${before[@]}" | cut -f 1) <(release:delivered "${root}" "${after[@]}" | cut -f 1)
+  read -r -a before <<<"$3"
+  read -r -a after <<<"$4"
+  comm -13 <(release:delivered "${root}" "${base}" "${before[@]}" | cut -f 1) \
+    <(release:delivered "${root}" "${base}" "${after[@]}" | cut -f 1)
 }
 
 release:merged() { [[ "$1" == *.json ]]; }
@@ -366,24 +416,51 @@ release:unplace() {
   fi
 }
 
-# release:write-manifest <module>… records the version, the active modules, and the release's digest for every
-# delivered path.
+# release:write-manifest <base> <module>… records, in the base's manifest, the version, the active modules, and
+# the release's digest for every path delivered under the base. The repository's is always written; home's only
+# when something is delivered there, and it is removed when nothing is any more.
 release:write-manifest() {
-  local path src
+  local base=$1 manifest path src delivered
+  shift
+  manifest=$(release:manifest "${base}")
+  delivered=$(release:delivered "${kit_root}" "${base}" "$@")
+  if [[ "${base}" != repo && -z "${delivered}" ]]
+  then
+    rm -f "${manifest}"
+    return 0
+  fi
+  mkdir -p "$(dirname "${manifest}")"
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
     printf 'version %s\n' "$(release:version)"
     printf 'modules%s\n' "${*:+ $*}"
     while IFS=$'\t' read -r path src
     do
-      printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
-    done < <(release:delivered "${kit_root}" "$@")
-  } > .kit/manifest
+      [[ -n "${path}" ]] && printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
+    done <<<"${delivered}"
+  } > "${manifest}"
+}
+
+# release:write-manifests <module>… writes every base's manifest.
+release:write-manifests() {
+  local base
+  for base in "${release_bases[@]}"
+  do
+    release:write-manifest "${base}" "$@"
+  done
 }
 
 release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
 release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest; }
 
+# release:recorded <base> <path> prints the digest the base's manifest records for <path>, or nothing.
+release:recorded() {
+  local manifest
+  manifest=$(release:manifest "$1")
+  [[ -f "${manifest}" ]] || return 0
+  awk -v p="$2" '$2 == p { print $1 }' "${manifest}"
+}
+
 # release:require-manifest refuses to go on in a repository that never took the kit.
 release:require-manifest() {
   if [[ ! -f .kit/manifest ]]
diff --git a/bin/yaml.sh b/bin/yaml.sh
new file mode 100644
index 0000000..d93f6fa
--- /dev/null
+++ b/bin/yaml.sh
@@ -0,0 +1,50 @@
+# shellcheck shell=bash
+# yaml.sh - the subset of YAML the kit's own files are written in (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Two kinds of file are read here: a module's module.yml, and the frontmatter between the opening and closing `---`
+# of a rule file. Both are written in the same small subset, and one reader serves both so they cannot drift:
+#
+#   key: value          a scalar, quoted or not
+#   key:                a list, one `  - item` per line
+#     - item
+#   key:                a map, one `  name: value` per line
+#     name: value
+#
+# A line starting with # is a comment. Nothing deeper is read, and a file that needs more is a file the kit does
+# not write. When the file opens with `---`, only the frontmatter up to the next `---` is read.
+
+# yaml:value <file> <key> prints the scalar under <key>, unquoted, or nothing.
+yaml:value() {
+  yaml:read "$1" | awk -v key="$2" '
+    $0 ~ "^" key ": " { v = $0; sub("^" key ": *", "", v); gsub(/^"|"$/, "", v); print v; exit }'
+}
+
+# yaml:list <file> <key> prints the items of the list under <key>, unquoted, one per line.
+yaml:list() {
+  yaml:read "$1" | awk -v key="$2" '
+    $0 == key ":" { on = 1; next }
+    /^[A-Za-z]/ { on = 0 }
+    on && /^  - / { v = $0; sub(/^  - /, "", v); gsub(/^"|"$/, "", v); print v }'
+}
+
+# yaml:map <file> <key> prints "<name>\t<value>" for every entry of the map under <key>, values unquoted.
+yaml:map() {
+  yaml:read "$1" | awk -v key="$2" '
+    $0 == key ":" { on = 1; next }
+    /^[A-Za-z]/ { on = 0 }
+    on && /^  [A-Za-z_]+: / { n = $0; sub(/^  /, "", n); sub(/: .*$/, "", n); v = $0; sub(/^  [A-Za-z_]+: */, "", v);
+      gsub(/^"|"$/, "", v); print n "\t" v }'
+}
+
+# yaml:read <file> prints the file's YAML: the frontmatter when the file opens with ---, the whole file otherwise.
+yaml:read() {
+  [[ -f "$1" ]] || return 0
+  awk '
+    NR == 1 && $0 == "---" { front = 1; next }
+    front && $0 == "---" { exit }
+    /^#/ { next }
+    { print }' "$1"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/docs/modules.md b/docs/modules.md
index 5da9de1..0b7c553 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -7,39 +7,63 @@ modules it wants, and `kit install`, `kit update`, and `kit check` work over the
 
 ```text
 modules/<name>/
-  module        metadata, one keyword per line
-  tree/         files mirrored at the repository root
-  templates/    files rendered from the repository's answers, then mirrored the same way
-  docs/         the module's documentation, for a reader of this repository; not delivered
+  module.yml          metadata
+  files/<base>/       files mirrored at the base's root
+  templates/<base>/   files rendered from the repository's answers, then mirrored the same way
+  docs/               the module's documentation, for a reader of this repository; not delivered
 ```
 
-A module may have any of `tree/`, `templates/`, and `docs/`, and must have `module`.
+A module may have any of `files/`, `templates/`, and `docs/`, and must have `module.yml`. A base names where a
+file lands:
+
+| Base | Root | Record |
+| --- | --- | --- |
+| `repo` | the repository root | `.kit/manifest`, committed with the repository |
+| `home` | the user's home directory, `~` | `~/.kit/manifest`, the desk's own; a runner has none |
+
+So `files/home/.kit/<name>` is a user-level setting, delivered once per desk by whichever repository installs or
+updates last. `kit check` holds home paths to the release where `~/.kit/manifest` exists and says so where it does
+not, since a runner installs nothing there. A module naming any other base is refused at install with the known
+bases listed. `KIT_HOME` stands in for the home directory, which is how the tests keep out of the real one.
 
 ## Metadata
 
-The `module` file is lines of one keyword each. A line starting with `#` is a comment.
+`module.yml` is the small subset of YAML `bin/yaml.sh` reads: scalars, lists of `- item`, and one level of map.
+A line starting with `#` is a comment.
+
+```yaml
+description: One CI job: the repository's gate, kit check, and the linked-open-issue refusal
+default: true
+depends:
+  - kit
+answers:
+  ci_runner: ubuntu-latest
+```
 
-| Keyword | Meaning |
+| Key | Meaning |
 | --- | --- |
-| `description <text>` | One line, shown by `kit module list`. |
-| `default` | Active unless removed. `kit install` with no names activates every default module. |
-| `depends <name>…` | Activated with this module. `kit module remove` refuses a module another active module depends on. |
-| `answer <key> <value>` | The default value of a template key. A repository overrides it in `.kit/answers`. |
+| `description` | One line, shown by `kit module list`. |
+| `default` | `true` for a module active unless removed. `kit install` with no names activates every default module. |
+| `depends` | Modules activated with this one. `kit module remove` refuses a module another active module depends on. |
+| `answers` | The default value of each template key. A repository overrides one in `.kit/answers`. |
 
 ## Delivery
 
-A file under `tree/` is placed at the same path under the repository root. A destination ending in `.json` is
+A file under `files/<base>/` is placed at the same path under the base's root. A destination ending in `.json` is
 merged by key: the kit's keys are set, its array entries added, and on update or removal only the previous
 release's entries are taken out, so a repository's own keys and entries survive. Every other destination is a copy.
 Where two active modules deliver the same path, the later module in dependency order wins.
 
-A file under `templates/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
+A file under `templates/<base>/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
 answer, then the result is placed, digested, and merged exactly as a `tree/` file is. The form is one neither
 bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
 answers live in `.kit/answers`, a file of `key value` lines the repository owns and the kit never writes; a key
 with no line there takes the module's `answer` default, and a key with neither refuses the install, naming the key
 and the module.
 
+The same file is also what a rule's frontmatter is written in, read by the same functions, so a rule's `paths:` and
+`content:` lists and a module's `depends:` list have one reader between them.
+
 ## Activation
 
 - `kit install [<module>…]` activates the default modules and the named ones, with their dependencies, and records
@@ -56,6 +80,9 @@ and the module.
 | `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md` |
 | `lefthook` | yes | `kit` | `.kit/lefthook.yml` |
 | `ci` | yes | `kit` | `.github/workflows/kit-ci.yml`, from a template; answer `ci_runner` |
-| `claude` | no | `kit` | `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
+| `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
+
+No module delivers to `home` yet. A module's `files/repo/` and `templates/repo/` carry the paths above; its
+`docs/README.md` says why.
 
 Each module's `docs/README.md` says what it places and why.
diff --git a/modules/ci/module b/modules/ci/module
deleted file mode 100644
index 9c3302f..0000000
--- a/modules/ci/module
+++ /dev/null
@@ -1,8 +0,0 @@
-# modules/ci/module - the ci module: one CI job, the gate, kit check, and the linked-open-issue refusal
-# ----------------------------------------------------------------------------------------------------------------------
-# One keyword per line. docs/modules.md says what each keyword means.
-
-description One CI job: the repository's gate, kit check, and the refusal of a pull request without an open issue
-default
-depends kit
-answer ci_runner ubuntu-latest
diff --git a/modules/ci/module.yml b/modules/ci/module.yml
new file mode 100644
index 0000000..6e90e90
--- /dev/null
+++ b/modules/ci/module.yml
@@ -0,0 +1,10 @@
+# modules/ci/module.yml - the ci module: one CI job, the gate, kit check, and the linked-open-issue refusal
+# ----------------------------------------------------------------------------------------------------------------------
+# docs/modules.md says what each key means.
+
+description: "One CI job: the repository's gate, kit check, and the refusal of a pull request without an open issue"
+default: true
+depends:
+  - kit
+answers:
+  ci_runner: ubuntu-latest
diff --git a/modules/ci/templates/.github/workflows/kit-ci.yml b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
similarity index 100%
rename from modules/ci/templates/.github/workflows/kit-ci.yml
rename to modules/ci/templates/repo/.github/workflows/kit-ci.yml
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index f6052df..c8be779 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -1,6 +1,9 @@
 # The claude module
 
-The adapter for Claude Code. It merges into `.claude/settings.json`, by key, leaving the repository's own entries:
+The adapter for Claude Code. Claude Code reads `CLAUDE.md` and not `AGENTS.md`, so the module places
+`.claude/CLAUDE.md`, two lines, the second `@../AGENTS.md`: Claude then reads what every other agent reads, and a
+root `CLAUDE.md` of the repository's own stays its own. It also merges into `.claude/settings.json`, by key,
+leaving the repository's own entries:
 
 - `permissions.deny`: the seven spellings the rules forbid an agent, such as `git rebase` and `git push --force`,
   which `kit rebase` and the loop replace.
@@ -8,3 +11,6 @@ The adapter for Claude Code. It merges into `.claude/settings.json`, by key, lea
   the file before the agent, described in [docs/context.md](../../../docs/context.md).
 
 It copies no rule. `.claude/rules/` is the repository's own.
+
+Why not `@.kit/1st.md` in `AGENTS.md`: that is Claude's import syntax in a file every harness reads, and Claude,
+having inlined the file, would then be told to read it again by the sentence beside it.
diff --git a/modules/claude/files/repo/.claude/CLAUDE.md b/modules/claude/files/repo/.claude/CLAUDE.md
new file mode 100644
index 0000000..819bb57
--- /dev/null
+++ b/modules/claude/files/repo/.claude/CLAUDE.md
@@ -0,0 +1,2 @@
+<!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
+@../AGENTS.md
diff --git a/modules/claude/tree/.claude/settings.json b/modules/claude/files/repo/.claude/settings.json
similarity index 100%
rename from modules/claude/tree/.claude/settings.json
rename to modules/claude/files/repo/.claude/settings.json
diff --git a/modules/claude/module b/modules/claude/module
deleted file mode 100644
index 13eda3e..0000000
--- a/modules/claude/module
+++ /dev/null
@@ -1,6 +0,0 @@
-# modules/claude/module - the claude module: Claude Code's deny list and its hook into kit context
-# ----------------------------------------------------------------------------------------------------------------------
-# One keyword per line. docs/modules.md says what each keyword means.
-
-description Claude Code: the deny list for the spellings the rules forbid, and the hook that puts a file's rules before the agent
-depends kit
diff --git a/modules/claude/module.yml b/modules/claude/module.yml
new file mode 100644
index 0000000..ec279bb
--- /dev/null
+++ b/modules/claude/module.yml
@@ -0,0 +1,7 @@
+# modules/claude/module.yml - the claude module: Claude Code's deny list and its hook into kit context
+# ----------------------------------------------------------------------------------------------------------------------
+# docs/modules.md says what each key means.
+
+description: "Claude Code: the deny list for the spellings the rules forbid, and the hook that names a file's rules before a write"
+depends:
+  - kit
diff --git a/modules/kit/tree/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
similarity index 95%
rename from modules/kit/tree/.kit/1st.md
rename to modules/kit/files/repo/.kit/1st.md
index 0d4fc49..ccb0fc6 100644
--- a/modules/kit/tree/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -97,8 +97,9 @@ it writes; everything else is copied as it is.
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
   refuses a pull request not linked to an open issue.
-- `claude`: for Claude Code, seven deny rules merged into `.claude/settings.json`, and a hook that runs
-  `kit context` before every write so the rules reach the agent without being asked for.
+- `claude`: for Claude Code, which reads `CLAUDE.md` and not `AGENTS.md`: `.claude/CLAUDE.md` importing
+  `AGENTS.md`, seven deny rules merged into `.claude/settings.json`, and a hook that runs `kit context` before
+  every write so the rules are named to the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/modules/kit/tree/.kit/rules/bash.md b/modules/kit/files/repo/.kit/rules/bash.md
similarity index 100%
rename from modules/kit/tree/.kit/rules/bash.md
rename to modules/kit/files/repo/.kit/rules/bash.md
diff --git a/modules/kit/tree/.kit/rules/gitignore.md b/modules/kit/files/repo/.kit/rules/gitignore.md
similarity index 100%
rename from modules/kit/tree/.kit/rules/gitignore.md
rename to modules/kit/files/repo/.kit/rules/gitignore.md
diff --git a/modules/kit/tree/.kit/rules/json.md b/modules/kit/files/repo/.kit/rules/json.md
similarity index 100%
rename from modules/kit/tree/.kit/rules/json.md
rename to modules/kit/files/repo/.kit/rules/json.md
diff --git a/modules/kit/tree/.kit/rules/just.md b/modules/kit/files/repo/.kit/rules/just.md
similarity index 100%
rename from modules/kit/tree/.kit/rules/just.md
rename to modules/kit/files/repo/.kit/rules/just.md
diff --git a/modules/kit/tree/.kit/rules/markdown.md b/modules/kit/files/repo/.kit/rules/markdown.md
similarity index 100%
rename from modules/kit/tree/.kit/rules/markdown.md
rename to modules/kit/files/repo/.kit/rules/markdown.md
diff --git a/modules/kit/tree/.kit/rules/yaml.md b/modules/kit/files/repo/.kit/rules/yaml.md
similarity index 100%
rename from modules/kit/tree/.kit/rules/yaml.md
rename to modules/kit/files/repo/.kit/rules/yaml.md
diff --git a/modules/kit/module b/modules/kit/module
deleted file mode 100644
index ed1b74c..0000000
--- a/modules/kit/module
+++ /dev/null
@@ -1,6 +0,0 @@
-# modules/kit/module - the kit module: the entry every agent reads, the rules by file kind, and kit context
-# ----------------------------------------------------------------------------------------------------------------------
-# One keyword per line. docs/modules.md says what each keyword means.
-
-description The entry every agent reads, the rules by file kind, and the context call that names them
-default
diff --git a/modules/kit/module.yml b/modules/kit/module.yml
new file mode 100644
index 0000000..d183e78
--- /dev/null
+++ b/modules/kit/module.yml
@@ -0,0 +1,6 @@
+# modules/kit/module.yml - the kit module: the entry every agent reads, the rules by file kind, and kit context
+# ----------------------------------------------------------------------------------------------------------------------
+# docs/modules.md says what each key means.
+
+description: "The entry every agent reads, the rules by file kind, and the context call that names them"
+default: true
diff --git a/modules/lefthook/tree/.kit/lefthook.yml b/modules/lefthook/files/repo/.kit/lefthook.yml
similarity index 100%
rename from modules/lefthook/tree/.kit/lefthook.yml
rename to modules/lefthook/files/repo/.kit/lefthook.yml
diff --git a/modules/lefthook/module b/modules/lefthook/module
deleted file mode 100644
index f7d56b1..0000000
--- a/modules/lefthook/module
+++ /dev/null
@@ -1,7 +0,0 @@
-# modules/lefthook/module - the lefthook module: which linter runs over which paths before a commit
-# ----------------------------------------------------------------------------------------------------------------------
-# One keyword per line. docs/modules.md says what each keyword means.
-
-description Which linter runs over which paths before a commit, for the repository's lefthook.yml to extend
-default
-depends kit
diff --git a/modules/lefthook/module.yml b/modules/lefthook/module.yml
new file mode 100644
index 0000000..3cc9b6b
--- /dev/null
+++ b/modules/lefthook/module.yml
@@ -0,0 +1,8 @@
+# modules/lefthook/module.yml - the lefthook module: which linter runs over which paths before a commit
+# ----------------------------------------------------------------------------------------------------------------------
+# docs/modules.md says what each key means.
+
+description: "Which linter runs over which paths before a commit, for the repository's lefthook.yml to extend"
+default: true
+depends:
+  - kit
diff --git a/tests/context.bats b/tests/context.bats
index 268c40d..5cd955c 100644
--- a/tests/context.bats
+++ b/tests/context.bats
@@ -4,6 +4,8 @@
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home"
+  mkdir -p "${KIT_HOME}"
   repo=$(mktemp -d)
   git -C "${repo}" init --quiet --initial-branch=main
   cd "${repo}"
diff --git a/tests/kit.bats b/tests/kit.bats
index eebf5fc..2d92f65 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -9,11 +9,14 @@ setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
   repo=$(mktemp -d)
   git -C "${repo}" init --quiet --initial-branch=main
+  # a home directory of the test's own, so no test ever writes under the real one
+  export KIT_HOME="${repo}.home"
+  mkdir "${KIT_HOME}"
   cd "${repo}"
 }
 
 teardown() {
-  rm -rf "${repo}" "${repo}.later"
+  rm -rf "${repo}" "${repo}.later" "${repo}.home"
 }
 
 # later-release <dir> copies this checkout's release to <dir> as version 9.9.9 with one changed rule line.
@@ -21,7 +24,7 @@ later-release() {
   mkdir -p "$1"
   cp -R "${kit_checkout}/bin" "${kit_checkout}/modules" "$1/"
   printf '9.9.9\n' > "$1/version"
-  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/modules/kit/tree/.kit/rules/json.md"
+  printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/modules/kit/files/repo/.kit/rules/json.md"
 }
 
 @test "install with no module writes the default modules and nothing under .claude" {
@@ -49,6 +52,7 @@ later-release() {
   grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
+  [ "$(tail -n 1 .claude/CLAUDE.md)" = "@../AGENTS.md" ]
   [ ! -e .claude/rules ]
 }
 
@@ -74,6 +78,7 @@ later-release() {
   [ "$status" -eq 0 ]
   run "${kit_checkout}/bin/kit" module remove claude
   [ "$status" -eq 0 ]
+  [ ! -e .claude/CLAUDE.md ]
   [ "$(jq --raw-output .model .claude/settings.json)" = "x" ]
   jq --exit-status '.permissions.deny == ["Bash(rm -rf /)"]' .claude/settings.json >/dev/null
   jq --exit-status '.hooks == {"PreToolUse": []}' .claude/settings.json >/dev/null
@@ -103,13 +108,53 @@ later-release() {
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   later-release "${repo}.later"
-  printf 'runner @ci_runner@ owner @owner@\n' > "${repo}.later/modules/ci/templates/OWNER"
+  printf 'runner @ci_runner@ owner @owner@\n' > "${repo}.later/modules/ci/templates/repo/OWNER"
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
   [[ "$output" == *"OWNER needs an answer for 'owner'"* ]]
   [ ! -e OWNER ]
 }
 
+@test "a module delivering to a base the kit does not know is refused, naming the bases" {
+  later-release "${repo}.later"
+  mkdir -p "${repo}.later/modules/kit/files/etc" && printf 'x\n' > "${repo}.later/modules/kit/files/etc/.x"
+  run "${repo}.later/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"modules/kit/files/etc names a base the kit does not deliver to; the bases are: repo home"* ]]
+  [ ! -e .kit/manifest ]
+}
+
+@test "a module delivering to home lands under it with a manifest of its own, and leaves with it" {
+  later-release "${repo}.later"
+  mkdir -p "${repo}.later/modules/claude/files/home/.kit" && printf 'user level\n' > "${repo}.later/modules/claude/files/home/.kit/claude"
+  run "${repo}.later/bin/kit" install claude
+  [ "$status" -eq 0 ]
+  [ "$(cat "${KIT_HOME}/.kit/claude")" = "user level" ]
+  grep --quiet '^version 9.9.9$' "${KIT_HOME}/.kit/manifest"
+  grep --quiet '  .kit/claude$' "${KIT_HOME}/.kit/manifest"
+  grep --quiet --invert-match 'claude$' .kit/manifest
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 0 ]
+  printf 'edited\n' >> "${KIT_HOME}/.kit/claude"
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"/.kit/claude differs"* ]]
+  run "${repo}.later/bin/kit" module remove claude
+  [ "$status" -eq 0 ]
+  [ ! -e "${KIT_HOME}/.kit/claude" ]
+  [ ! -e "${KIT_HOME}/.kit/manifest" ]
+}
+
+@test "check skips the home base where nothing was installed there, and says so" {
+  later-release "${repo}.later"
+  mkdir -p "${repo}.later/modules/kit/files/home/.kit" && printf 'x\n' > "${repo}.later/modules/kit/files/home/.kit/x"
+  "${repo}.later/bin/kit" install
+  rm -rf "${KIT_HOME}/.kit"
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"home: nothing is installed under ${KIT_HOME} on this machine"* ]]
+}
+
 @test "install keeps the repository's own settings keys and deny entries" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
@@ -158,7 +203,7 @@ later-release() {
   grep --quiet '^# JSON (ours)$' .kit/rules/json.md
   grep --quiet '^## Added in 9.9.9$' .kit/rules/json.md
   # the manifest carries the release's digest, so the edit still reads as an edit
-  release_digest=$(shasum -a 256 "${repo}.later/modules/kit/tree/.kit/rules/json.md" | cut -d ' ' -f 1)
+  release_digest=$(shasum -a 256 "${repo}.later/modules/kit/files/repo/.kit/rules/json.md" | cut -d ' ' -f 1)
   grep --quiet "^${release_digest}  .kit/rules/json.md$" .kit/manifest
   # and check names the one file that still differs from the release
   run "${repo}.later/bin/kit" check
@@ -170,7 +215,7 @@ later-release() {
 @test "update refuses a path new in the release where the repository already has a different file" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
-  printf 'new rule\n' > "${repo}.later/modules/kit/tree/.kit/rules/toml.md"
+  printf 'new rule\n' > "${repo}.later/modules/kit/files/repo/.kit/rules/toml.md"
   printf 'mine\n' > .kit/rules/toml.md
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
@@ -190,7 +235,7 @@ later-release() {
 @test "update leaves conflict markers and fails when the same lines changed" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
-  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${repo}.later/modules/kit/tree/.kit/rules/json.md" && rm "${repo}.later/modules/kit/tree/.kit/rules/json.md.bak"
+  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${repo}.later/modules/kit/files/repo/.kit/rules/json.md" && rm "${repo}.later/modules/kit/files/repo/.kit/rules/json.md.bak"
   sed -i.bak 's/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
diff --git a/tests/release.bats b/tests/release.bats
index 2469254..6529eb4 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -4,6 +4,8 @@
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home"
+  mkdir -p "${KIT_HOME}"
   work=$(mktemp -d)
   cd "${work}"
 }
@@ -24,7 +26,7 @@ teardown() {
   [ "$(ls unpacked)" = "kit-${version}" ]
   [ -x "unpacked/kit-${version}/bin/kit" ]
   [ -x "unpacked/kit-${version}/bin/kit-install.sh" ]
-  [ -f "unpacked/kit-${version}/modules/claude/module" ]
+  [ -f "unpacked/kit-${version}/modules/claude/module.yml" ]
   mkdir fresh && git -C fresh init --quiet --initial-branch=main
   cd fresh
   run "${work}/unpacked/kit-${version}/bin/kit" install claude

From 598b6977d2121a423eb6ab078e807e267ce5def8 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:34:04 -0700
Subject: [PATCH 067/108] #4 documentation: Claude Code reads AGENTS.md as a
 conditional fallback, which is why the adapter imports it

Since 2.1.277 Claude Code reads AGENTS.md when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md is
present and its configuration allows. The claude module's .claude/CLAUDE.md makes AGENTS.md reach
Claude in every case; the text said Claude did not read it at all, which was wrong.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md                        |  6 +++---
 .kit/manifest                      |  2 +-
 README.md                          | 15 ++++++++-------
 modules/claude/docs/README.md      | 10 ++++++----
 modules/kit/files/repo/.kit/1st.md |  6 +++---
 5 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/.kit/1st.md b/.kit/1st.md
index ccb0fc6..0852482 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -97,9 +97,9 @@ it writes; everything else is copied as it is.
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
   refuses a pull request not linked to an open issue.
-- `claude`: for Claude Code, which reads `CLAUDE.md` and not `AGENTS.md`: `.claude/CLAUDE.md` importing
-  `AGENTS.md`, seven deny rules merged into `.claude/settings.json`, and a hook that runs `kit context` before
-  every write so the rules are named to the agent without being asked for.
+- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
+  importing `AGENTS.md`, so it is read in every case; seven deny rules merged into `.claude/settings.json`; and a
+  hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/manifest b/.kit/manifest
index 4ad7cd4..c58e693 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -4,7 +4,7 @@ modules kit ci claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 86563533cd11f87831320d57b24d68d83c8d3a47382b09afeb71f5ee46e93584  .claude/settings.json
 cd66dc3b7fe79643f0a706e0ea571962906ffd117743c68e23aadbab7c91e143  .github/workflows/kit-ci.yml
-37df46c8bbe5a02b972412f0fea25246e14ab66cb0421c8cb23857c3fdb94189  .kit/1st.md
+6a4818d08c59d04d47533ca22cd1da112050fb07a7c604e684d1431ceca73ae3  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 6f1101c9b19bfbe2d42d6e602e92d0df4dc650a4a04ccbd06c5a03a5e6e5edc2  .kit/rules/bash.md
 0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
diff --git a/README.md b/README.md
index 9c6aa6d..0cd7189 100644
--- a/README.md
+++ b/README.md
@@ -69,13 +69,14 @@ repository trustworthy.
 ```
 
 The rest of `AGENTS.md` is yours. Everything the kit delivers is a module, and `install` activates the default ones,
-`kit`, `lefthook`, and `ci`, plus those named: `claude` is the adapter for Claude Code, which reads `CLAUDE.md` and
-not `AGENTS.md`, so the module places `.claude/CLAUDE.md` importing `AGENTS.md` and Claude reads what everyone else
-reads. A repository with no adapter still binds every agent that reads `AGENTS.md`. Commit what it wrote, keep a `ci`
-recipe in the root justfile for the delivered `CI` job to run, and take the pre-commit linters by pinning `lefthook`,
-putting `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit module
-list`, `kit module add`, and `kit module remove` show and change the set later, and [docs/modules.md](docs/modules.md)
-describes a module. An agent asks `kit context <path>` which rules govern a file before it creates or changes it;
+`kit`, `lefthook`, and `ci`, plus those named: `claude` is the adapter for Claude Code, which reads `AGENTS.md` only
+as a fallback, when no `CLAUDE.md` is present and its configuration allows, so the module places `.claude/CLAUDE.md`
+importing `AGENTS.md` and Claude reads what everyone else reads in every case. A repository with no adapter still
+binds every agent that reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the root justfile for the
+delivered `CI` job to run, and take the pre-commit linters by pinning `lefthook`, putting `extends:
+[.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit module list`, `kit module
+add`, and `kit module remove` show and change the set later, and [docs/modules.md](docs/modules.md) describes a
+module. An agent asks `kit context <path>` which rules govern a file before it creates or changes it;
 [docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
 
 To move to a new release, bump the pin or reinstall, then run `kit update`: a delivered file you left alone is
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index c8be779..cb6ae19 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -1,9 +1,11 @@
 # The claude module
 
-The adapter for Claude Code. Claude Code reads `CLAUDE.md` and not `AGENTS.md`, so the module places
-`.claude/CLAUDE.md`, two lines, the second `@../AGENTS.md`: Claude then reads what every other agent reads, and a
-root `CLAUDE.md` of the repository's own stays its own. It also merges into `.claude/settings.json`, by key,
-leaving the repository's own entries:
+The adapter for Claude Code. Since 2.1.277, Claude Code reads `AGENTS.md` as a fallback: only when no `CLAUDE.md`,
+`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and only where its
+configuration allows. A repository with a `CLAUDE.md` of its own would have `AGENTS.md` skipped. So the module
+places `.claude/CLAUDE.md`, two lines, the second `@../AGENTS.md`: Claude then reads what every other agent reads
+in every case, and a root `CLAUDE.md` of the repository's own stays its own. It also merges into
+`.claude/settings.json`, by key, leaving the repository's own entries:
 
 - `permissions.deny`: the seven spellings the rules forbid an agent, such as `git rebase` and `git push --force`,
   which `kit rebase` and the loop replace.
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index ccb0fc6..0852482 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -97,9 +97,9 @@ it writes; everything else is copied as it is.
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
   refuses a pull request not linked to an open issue.
-- `claude`: for Claude Code, which reads `CLAUDE.md` and not `AGENTS.md`: `.claude/CLAUDE.md` importing
-  `AGENTS.md`, seven deny rules merged into `.claude/settings.json`, and a hook that runs `kit context` before
-  every write so the rules are named to the agent without being asked for.
+- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
+  importing `AGENTS.md`, so it is read in every case; seven deny rules merged into `.claude/settings.json`; and a
+  hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.

From 0aeeb60d9885ba302aa95cce3e5fd68b2624afb6 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:44:05 -0700
Subject: [PATCH 068/108] #4 docs/architecture.md, a schema for module.yml, and
 a CI workflow of one-liners over kit gate and kit linked

docs/architecture.md draws the whole in three SVG figures: delivery from a release into a repository
and a home, context discovery with the Claude hook, and the loop with its gate; and closes with a
table of what verifies what.

modules/module.schema.json is the schema for module.yml, JSON Schema 2020-12. The gate validates
every module.yml against it with ajv, pinned through mise, and the kit holds every module a release
carries to the same contract before it installs, updates, or checks: an unknown key, a default that
is not true or false, or a dependency the release lacks is refused, naming it.

The delivered workflow's steps are one kit command each. kit gate runs the root justfile's ci recipe
and reports a missing one as a skip, never a pass; kit linked refuses a pull request not linked to an
open issue of the repository, from the argument, the runner's event, or the current branch. Both are
verbs a desk can run. The template's key is quoted, since a YAML scalar cannot open with @.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml                  | 120 ++---------
 .kit/manifest                                 |   2 +-
 .mise/locks/npm-ajv-cli/5.0.0/aube-lock.yaml  | 202 ++++++++++++++++++
 .mise/locks/npm-ajv-cli/5.0.0/package.json    |   7 +
 README.md                                     |   2 +
 bin/1st.sh                                    |   6 +
 bin/gh.sh                                     |  53 +++++
 bin/kit                                       |   2 +
 bin/kit-gate.sh                               |  42 ++++
 bin/kit-linked.sh                             |  37 ++++
 bin/release.sh                                |  45 +++-
 bin/yaml.sh                                   |   5 +
 docs/architecture.md                          |  75 +++++++
 docs/context.svg                              |  85 ++++++++
 docs/delivery.svg                             | 100 +++++++++
 docs/loop.svg                                 |  95 ++++++++
 docs/modules.md                               |   5 +
 justfile                                      |   6 +-
 mise.lock                                     |   6 +
 mise.toml                                     |   1 +
 modules/ci/docs/README.md                     |   6 +-
 .../repo/.github/workflows/kit-ci.yml         | 120 ++---------
 modules/module.schema.json                    |  40 ++++
 tests/gate.bats                               |  55 +++++
 tests/kit.bats                                |  17 +-
 25 files changed, 909 insertions(+), 225 deletions(-)
 create mode 100644 .mise/locks/npm-ajv-cli/5.0.0/aube-lock.yaml
 create mode 100644 .mise/locks/npm-ajv-cli/5.0.0/package.json
 create mode 100755 bin/kit-gate.sh
 create mode 100755 bin/kit-linked.sh
 create mode 100644 docs/architecture.md
 create mode 100644 docs/context.svg
 create mode 100644 docs/delivery.svg
 create mode 100644 docs/loop.svg
 create mode 100644 modules/module.schema.json
 create mode 100644 tests/gate.bats

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 72b648a..a835c42 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -1,10 +1,11 @@
 # kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires. Three steps: the repository's `just ci` when its
-# root justfile has one, `kit check` with the kit mise pins, and a refusal of a pull request not linked to an
-# open issue of this repository under Development. The last two run even when an earlier step refused, so one
-# run reports every finding.
+# One job, CI, which is the check name a ruleset requires. Each step is one kit command, so what the runner does
+# is what a desk can do: `kit gate` runs the root justfile's ci recipe and reports a missing one as a skip,
+# `kit check` holds every delivered file to the pinned release, and `kit linked` refuses a pull request not linked
+# to an open issue of this repository under Development. The last two run even when an earlier step refused, so
+# one run reports every finding.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update. Rendered from a template: the
 # job runs on the ci_runner answer, ubuntu-latest unless .kit/answers says otherwise.
@@ -25,7 +26,7 @@ permissions:
 jobs:
   CI:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
-    runs-on: ubuntu-latest
+    runs-on: "ubuntu-latest"
     env:
       # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
       MISE_ENV: ci
@@ -35,117 +36,20 @@ jobs:
       # Every tool below comes from mise.toml, the kit included; this repository's mise.toml puts bin/ on PATH.
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
 
+      - name: kit-on-path
+        run: command -v kit >/dev/null || { echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'; exit 1; }
+
       - name: gate
-        run: |
-          set -o errexit -o nounset -o pipefail
-          # A missing recipe is a skip; a justfile that cannot be read is a failure, never a silent skip.
-          if [[ ! -f justfile ]]
-          then
-            echo "::warning::there is no root justfile, so the gate was skipped"
-            printf '⚠️ The gate was skipped: there is no root justfile.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
-          elif ! recipes=$(just --summary 2>&1)
-          then
-            echo "::error::the root justfile could not be read: ${recipes}"
-            printf '### ❌ The root justfile could not be read\n\n%s\n' "${recipes}" | tee --append "${GITHUB_STEP_SUMMARY}"
-            exit 1
-          elif ! tr ' ' '\n' <<< "${recipes}" | grep --quiet --line-regexp ci
-          then
-            echo "::warning::the root justfile has no ci recipe, so the gate was skipped"
-            printf '⚠️ The gate was skipped: the root justfile has no ci recipe.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
-          else
-            just ci
-            printf '✅ just ci passed.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
-          fi
+        run: kit gate
 
       - name: kit-check
         if: ${{ !cancelled() }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-          if ! command -v kit >/dev/null 2>&1
-          then
-            echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'
-            printf '### ❌ kit is not on PATH\n\nPin the release in mise.toml under [tools]: "github:empowerite/kit" = "<version>".\n' \
-              | tee --append "${GITHUB_STEP_SUMMARY}"
-            exit 1
-          fi
-          kit check
-          printf '✅ Every delivered file matches the pinned kit release.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+        run: kit check
 
       - name: linked-open-issue
         if: ${{ !cancelled() }}
         env:
           GH_TOKEN: ${{ github.token }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-
-          repo_slug="${GITHUB_REPOSITORY}"
-          pr=$(jq --raw-output '.pull_request.number' "${GITHUB_EVENT_PATH}")
-          pull="${GITHUB_SERVER_URL}/${repo_slug}/pull/${pr}"
-          run="${GITHUB_SERVER_URL}/${repo_slug}/actions/runs/${GITHUB_RUN_ID}"
-
-          remedy=$(cat <<REMEDY
-          Link an open issue of this repository under **Development** in [the sidebar](${pull}):
-
-          1. click the gear (⚙) beside **Development**
-          2. pick one or more open issues
-          3. [re-run this check](${run}): linking fires no event, so it does not re-run on its own
-
-          \`kit issue <N>\` makes this link when it starts the work.
-          REMEDY
-          )
-
-          refuse() {
-            echo "::error::$1"
-            printf '### ❌ %s\n\n%s\n' "${1^}" "${remedy}" | tee --append "${GITHUB_STEP_SUMMARY}"
-            return 1
-          }
-
-          query=$(cat <<'GRAPHQL'
-          query($owner: String!, $name: String!, $number: Int!) {
-            repository(owner: $owner, name: $name) {
-              pullRequest(number: $number) {
-                closingIssuesReferences(first: 100) {
-                  nodes { number state repository { nameWithOwner } }
-                }
-              }
-            }
-          }
-          GRAPHQL
-          )
-          refs=$(gh api graphql \
-            --field owner="${repo_slug%%/*}" \
-            --field name="${repo_slug#*/}" \
-            --field number="${pr}" \
-            --raw-field query="${query}" \
-            --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
-                  | "\(.number) \(.state) \(.repository.nameWithOwner)"')
-
-          if [[ -z "${refs}" ]]
-          then
-            refuse 'this pull request is not linked to any issue'
-          else
-            open_local=0
-            while read -r n state repo
-            do
-              if [[ "${repo}" != "${repo_slug}" ]]
-              then
-                echo "::warning::skipping ${repo}#${n}: it belongs to another repository"
-                continue
-              fi
-              if [[ "${state}" != OPEN ]]
-              then
-                echo "::warning::${repo}#${n} is ${state}; merging will not change it"
-                continue
-              fi
-              open_local=$(( open_local + 1 ))
-            done <<< "${refs}"
-            if (( open_local == 0 ))
-            then
-              refuse 'every issue this pull request is linked to is closed or belongs to another repository'
-            else
-              closes=$(cut --delimiter=' ' --fields=1 <<< "${refs}" | sed 's/^/#/' | paste --serial --delimiters=' ')
-              printf '✅ Linked to %s.\n' "${closes}" | tee --append "${GITHUB_STEP_SUMMARY}"
-            fi
-          fi
+        run: kit linked
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/manifest b/.kit/manifest
index c58e693..82a69d5 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,7 +3,7 @@ version unreleased
 modules kit ci claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 86563533cd11f87831320d57b24d68d83c8d3a47382b09afeb71f5ee46e93584  .claude/settings.json
-cd66dc3b7fe79643f0a706e0ea571962906ffd117743c68e23aadbab7c91e143  .github/workflows/kit-ci.yml
+972303cda70ea028bc266e64a56dc44bbb1689ba11e4023fd88173bbc11670fb  .github/workflows/kit-ci.yml
 6a4818d08c59d04d47533ca22cd1da112050fb07a7c604e684d1431ceca73ae3  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 6f1101c9b19bfbe2d42d6e602e92d0df4dc650a4a04ccbd06c5a03a5e6e5edc2  .kit/rules/bash.md
diff --git a/.mise/locks/npm-ajv-cli/5.0.0/aube-lock.yaml b/.mise/locks/npm-ajv-cli/5.0.0/aube-lock.yaml
new file mode 100644
index 0000000..0e702f7
--- /dev/null
+++ b/.mise/locks/npm-ajv-cli/5.0.0/aube-lock.yaml
@@ -0,0 +1,202 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      ajv-cli:
+        specifier: 5.0.0
+        version: 5.0.0
+
+packages:
+
+  ajv-cli@5.0.0:
+    resolution: {integrity: sha512-LY4m6dUv44HTyhV+u2z5uX4EhPYTM38Iv1jdgDJJJCyOOuqB8KtZEGjPZ2T+sh5ZIJrXUfgErYx/j3gLd3+PlQ==}
+    hasBin: true
+    peerDependencies:
+      ts-node: '>=9.0.0'
+    peerDependenciesMeta:
+      ts-node:
+        optional: true
+
+  ajv@8.20.0:
+    resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
+
+  argparse@1.0.10:
+    resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+
+  balanced-match@1.0.2:
+    resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
+
+  brace-expansion@1.1.21:
+    resolution: {integrity: sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==}
+
+  concat-map@0.0.1:
+    resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
+
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  fast-deep-equal@2.0.1:
+    resolution: {integrity: sha512-bCK/2Z4zLidyB4ReuIsvALH6w31YfAQDmXMqMx6FyfHqvBxtjC0eRumeSu4Bs3XtXwpyIywtSTrVT99BxY1f9w==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-json-patch@2.2.1:
+    resolution: {integrity: sha512-4j5uBaTnsYAV5ebkidvxiLUYOwjQ+JSFljeqfTxCrH9bDmlCQaOJFS84oDJ2rAXZq2yskmk3ORfoP9DCwqFNig==}
+    engines: {node: '>= 0.4.0'}
+
+  fast-uri@3.1.9:
+    resolution: {integrity: sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==}
+
+  fs.realpath@1.0.0:
+    resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==}
+
+  glob@7.2.3:
+    resolution: {integrity: sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+
+  inflight@1.0.6:
+    resolution: {integrity: sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==}
+    deprecated: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
+
+  inherits@2.0.4:
+    resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
+
+  js-yaml@3.15.2:
+    resolution: {integrity: sha512-6EuL879VkRA+1Cz578mKMiKvjPNEuk6+r1JaFzoSWejZmtf7xWbIyw1e3KkxlkzTIt9Taw6JBhEppG7utc1P+w==}
+    hasBin: true
+
+  json-schema-migrate@2.0.0:
+    resolution: {integrity: sha512-r38SVTtojDRp4eD6WsCqiE0eNDt4v1WalBXb9cyZYw9ai5cGtBwzRNWjHzJl38w6TxFkXAIA7h+fyX3tnrAFhQ==}
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  minimatch@3.1.5:
+    resolution: {integrity: sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==}
+
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
+  once@1.4.0:
+    resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
+
+  path-is-absolute@1.0.1:
+    resolution: {integrity: sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  sprintf-js@1.0.3:
+    resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+
+  wrappy@1.0.2:
+    resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
+
+snapshots:
+
+  ajv-cli@5.0.0:
+    dependencies:
+      ajv: 8.20.0
+      fast-json-patch: 2.2.1
+      glob: 7.2.3
+      js-yaml: 3.15.2
+      json-schema-migrate: 2.0.0
+      json5: 2.2.3
+      minimist: 1.2.8
+
+  ajv@8.20.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.9
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
+  argparse@1.0.10:
+    dependencies:
+      sprintf-js: 1.0.3
+
+  balanced-match@1.0.2: {}
+
+  brace-expansion@1.1.21:
+    dependencies:
+      balanced-match: 1.0.2
+      concat-map: 0.0.1
+
+  concat-map@0.0.1: {}
+
+  esprima@4.0.1: {}
+
+  fast-deep-equal@2.0.1: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-json-patch@2.2.1:
+    dependencies:
+      fast-deep-equal: 2.0.1
+
+  fast-uri@3.1.9: {}
+
+  fs.realpath@1.0.0: {}
+
+  glob@7.2.3:
+    dependencies:
+      fs.realpath: 1.0.0
+      inflight: 1.0.6
+      inherits: 2.0.4
+      minimatch: 3.1.5
+      once: 1.4.0
+      path-is-absolute: 1.0.1
+
+  inflight@1.0.6:
+    dependencies:
+      once: 1.4.0
+      wrappy: 1.0.2
+
+  inherits@2.0.4: {}
+
+  js-yaml@3.15.2:
+    dependencies:
+      argparse: 1.0.10
+      esprima: 4.0.1
+
+  json-schema-migrate@2.0.0:
+    dependencies:
+      ajv: 8.20.0
+
+  json-schema-traverse@1.0.0: {}
+
+  json5@2.2.3: {}
+
+  minimatch@3.1.5:
+    dependencies:
+      brace-expansion: 1.1.21
+
+  minimist@1.2.8: {}
+
+  once@1.4.0:
+    dependencies:
+      wrappy: 1.0.2
+
+  path-is-absolute@1.0.1: {}
+
+  require-from-string@2.0.2: {}
+
+  sprintf-js@1.0.3: {}
+
+  wrappy@1.0.2: {}
diff --git a/.mise/locks/npm-ajv-cli/5.0.0/package.json b/.mise/locks/npm-ajv-cli/5.0.0/package.json
new file mode 100644
index 0000000..3203299
--- /dev/null
+++ b/.mise/locks/npm-ajv-cli/5.0.0/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "mise-npm-install",
+  "private": true,
+  "dependencies": {
+    "ajv-cli": "5.0.0"
+  }
+}
diff --git a/README.md b/README.md
index 0cd7189..f9a6e77 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,8 @@ is what a consumer activating that module gets, its `files/repo/` mirrored at th
 `bin/kit-<verb>.sh` per verb, each sourcing the bash modules beside it; and `docs/` with each module's `docs/` is
 the documentation. [docs/modules.md](docs/modules.md) is the module format.
 
+[docs/architecture.md](docs/architecture.md) is the shape of the whole, with its figures.
+
 The installed copies are written by `bin/kit install` and not edited by hand:
 
 | Installed copy | Written from |
diff --git a/bin/1st.sh b/bin/1st.sh
index 3425cad..2976763 100644
--- a/bin/1st.sh
+++ b/bin/1st.sh
@@ -70,6 +70,12 @@ error() {
   return 0
 }
 
+# summary <line>… appends lines to the runner's step summary, where there is one, and is silent elsewhere.
+summary() {
+  [[ -n "${GITHUB_STEP_SUMMARY:-}" ]] || return 0
+  printf '%s\n' "$@" >> "${GITHUB_STEP_SUMMARY}"
+}
+
 # guard:require <predicate>… returns non-zero on the first predicate that does not hold, with the remedy.
 #   gh           gh is usably authenticated (a real API call, since a revoked token still passes gh auth status)
 #   signing-key  git user.signingkey is set
diff --git a/bin/gh.sh b/bin/gh.sh
index 3ced0f9..68177f0 100644
--- a/bin/gh.sh
+++ b/bin/gh.sh
@@ -186,6 +186,59 @@ gh:link-secondaries() {
   fi
 }
 
+# gh:linked-open-issue <number> refuses pull request <number> unless it is linked, under Development, to an issue
+# of this repository that is open. A linked issue of another repository, or a closed one, is noted and does not
+# count. On a runner the remedy also lands in the step summary.
+gh:linked-open-issue() {
+  local number=$1 repo query refs n state issue_repo open=0 closes url remedy
+  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+  url=$(gh repo view --json url --jq .url)
+  remedy=$(printf '%s\n' \
+    "Link an open issue of this repository under **Development** in [the sidebar](${url}/pull/${number}):" "" \
+    "1. click the gear (⚙) beside **Development**" \
+    "2. pick one or more open issues" \
+    "3. re-run the check: linking fires no event, so it does not re-run on its own" "" \
+    "\`kit issue <N>\` makes this link when it starts the work.")
+  # shellcheck disable=SC2016  # GraphQL variables
+  query='query($owner: String!, $name: String!, $number: Int!) {
+    repository(owner: $owner, name: $name) {
+      pullRequest(number: $number) {
+        closingIssuesReferences(first: 100) { nodes { number state repository { nameWithOwner } } }
+      }
+    }
+  }'
+  refs=$(gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --field number="${number}" \
+    --raw-field query="${query}" \
+    --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[] | "\(.number) \(.state) \(.repository.nameWithOwner)"')
+  if [[ -z "${refs}" ]]
+  then
+    error "pull request #${number} is not linked to any issue"
+    summary "### ❌ Pull request #${number} is not linked to any issue" "" "${remedy}"
+    return 1
+  fi
+  while read -r n state issue_repo
+  do
+    if [[ "${issue_repo}" != "${repo}" ]]
+    then
+      warn "skipping ${issue_repo}#${n}: it belongs to another repository"
+    elif [[ "${state}" != OPEN ]]
+    then
+      warn "#${n} is ${state}; merging will not change it"
+    else
+      open=$(( open + 1 ))
+    fi
+  done <<<"${refs}"
+  if (( open == 0 ))
+  then
+    error "every issue pull request #${number} is linked to is closed or belongs to another repository"
+    summary "### ❌ Every linked issue is closed or belongs to another repository" "" "${remedy}"
+    return 1
+  fi
+  closes=$(cut -d ' ' -f 1 <<<"${refs}" | sed 's/^/#/' | paste -s -d ' ' -)
+  ok "pull request #${number} is linked to ${closes}"
+  summary "✅ Linked to ${closes}."
+}
+
 gh:issue() {
   use git
   local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr
diff --git a/bin/kit b/bin/kit
index 4a22f8c..e4ab597 100755
--- a/bin/kit
+++ b/bin/kit
@@ -31,6 +31,8 @@ usage: kit <verb> [<argument>…]
   module <list|add|remove> [<module>…]
                         the modules this repository takes
   context <path>…       name the rules that govern a file, and record the ask
+  gate                  run the root justfile's ci recipe; a missing one is a skip, said so
+  linked [<number>]     refuse a pull request not linked to an open issue of this repository
   issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
diff --git a/bin/kit-gate.sh b/bin/kit-gate.sh
new file mode 100755
index 0000000..5858004
--- /dev/null
+++ b/bin/kit-gate.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# kit-gate - run the repository's gate, the root justfile's ci recipe, and say plainly when there is none (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The delivered CI job's first step. A missing justfile or a justfile with no ci recipe is a skip, reported as a
+# skip, never as a pass; a justfile that cannot be read is a failure. On a runner, each outcome also lands in the
+# step summary.
+#
+# see: modules/ci/templates/repo/.github/workflows/kit-ci.yml
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit gate" >&2
+  exit 0
+fi
+
+if [[ ! -f justfile ]]
+then
+  warn "there is no root justfile, so the gate was skipped"
+  summary "⚠️ The gate was skipped: there is no root justfile."
+  exit 0
+fi
+if ! recipes=$(just --summary 2>&1)
+then
+  error "the root justfile could not be read: ${recipes}"
+  summary "### ❌ The root justfile could not be read" "" "${recipes}"
+  exit 1
+fi
+if ! tr ' ' '\n' <<<"${recipes}" | grep --quiet --line-regexp ci
+then
+  warn "the root justfile has no ci recipe, so the gate was skipped"
+  summary "⚠️ The gate was skipped: the root justfile has no ci recipe."
+  exit 0
+fi
+just ci
+summary "✅ just ci passed."
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-linked.sh b/bin/kit-linked.sh
new file mode 100755
index 0000000..10c9330
--- /dev/null
+++ b/bin/kit-linked.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# kit-linked - refuse a pull request not linked to an open issue of this repository (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The delivered CI job's last step, and a check a desk can run on any pull request. The pull request is the
+# argument, else the one the GitHub event names on a runner, else the one for the current branch.
+#
+# see: bin/gh.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use gh
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit linked [<pull-request>]" >&2
+  exit 0
+fi
+
+number=${1:-}
+if [[ -z "${number}" && -n "${GITHUB_EVENT_PATH:-}" ]]
+then
+  number=$(jq --raw-output '.pull_request.number // empty' "${GITHUB_EVENT_PATH}")
+fi
+if [[ -z "${number}" ]]
+then
+  number=$(gh pr view --json number --jq .number 2>/dev/null || true)
+fi
+if [[ ! "${number}" =~ ^[0-9]+$ ]]
+then
+  error "name the pull request: kit linked <number> (none was given, and the current branch has none)"
+  exit 2
+fi
+gh:linked-open-issue "${number}"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/release.sh b/bin/release.sh
index 9a9045e..c2cd00b 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -201,11 +201,52 @@ release:render() {
   printf '%s\n' "${out}"
 }
 
-# release:render-all <root> <module>… renders every named module's templates for every base, and refuses a base
-# the kit does not know, or an unanswered key, naming it.
+# release:validate <root> <module> refuses metadata the schema would: a key the kit does not know, a default that
+# is not true or false, a dependency on a module the release lacks. The gate validates against
+# modules/module.schema.json with a real validator; this is the same contract where no validator is, at install.
+release:validate() {
+  local root=$1 module=$2 meta key value dep
+  meta=$(release:meta "${root}" "${module}")
+  for key in $(yaml:keys "${meta}")
+  do
+    case "${key}" in
+      (description | default | depends | answers) ;;
+      (*)
+        error "modules/${module}/module.yml has a key the kit does not know: ${key} (the schema is modules/module.schema.json)"
+        return 1
+    esac
+  done
+  if [[ -z "$(yaml:value "${meta}" description)" ]]
+  then
+    error "modules/${module}/module.yml has no description"
+    return 1
+  fi
+  value=$(yaml:value "${meta}" default)
+  if [[ -n "${value}" && "${value}" != true && "${value}" != false ]]
+  then
+    error "modules/${module}/module.yml: default must be true or false, not '${value}'"
+    return 1
+  fi
+  for dep in $(release:depends "${root}" "${module}")
+  do
+    if [[ ! -f "$(release:meta "${root}" "${dep}")" ]]
+    then
+      error "modules/${module}/module.yml depends on '${dep}', which this release does not carry"
+      return 1
+    fi
+  done
+}
+
+# release:render-all <root> <module>… validates the metadata of every module the release carries, active or not,
+# since a release with a broken module is a broken release; then renders the named modules' templates for every
+# base, refusing a base the kit does not know, or an unanswered key, naming it.
 release:render-all() {
   local root=$1 module kind base
   shift
+  for module in $(release:modules "${root}")
+  do
+    release:validate "${root}" "${module}" || return 1
+  done
   for module in "$@"
   do
     for kind in files templates
diff --git a/bin/yaml.sh b/bin/yaml.sh
index d93f6fa..f57052f 100644
--- a/bin/yaml.sh
+++ b/bin/yaml.sh
@@ -37,6 +37,11 @@ yaml:map() {
       gsub(/^"|"$/, "", v); print n "\t" v }'
 }
 
+# yaml:keys <file> prints the top-level keys, one per line.
+yaml:keys() {
+  yaml:read "$1" | awk '/^[A-Za-z_]+:/ { k = $0; sub(/:.*$/, "", k); print k }'
+}
+
 # yaml:read <file> prints the file's YAML: the frontmatter when the file opens with ---, the whole file otherwise.
 yaml:read() {
   [[ -f "$1" ]] || return 0
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..c33375a
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,75 @@
+# Architecture
+
+The kit is a release that a repository installs, a set of verbs an agent and a person both run, and the checks
+that hold the work to the rules. This page is the shape of it: what a release is, how it reaches a repository, how
+a file's rules are found, and how a change moves from an issue to `main`. [modules.md](modules.md) and
+[context.md](context.md) are the two mechanisms in detail.
+
+## The release and its delivery
+
+![Delivery: a release's modules, through the verbs, into a repository and a home](delivery.svg)
+
+A release is one tarball, `kit-<version>.tar.gz`, and its layout is the checkout's: `bin/` is the machinery, and
+`modules/` is everything delivered. `bin/kit` is the command; each verb is an executable `bin/kit-<verb>.sh`
+beside it, and the verbs share bash modules loaded with `use`. The release workflow stamps the tag's version into
+a `version` file; a checkout has none and is `unreleased`.
+
+A module is a directory under `modules/`: `module.yml` names it, says whether it is active by default, which
+modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the base's root;
+`templates/<base>/` is rendered first, every `@key@` replaced by an answer; `docs/` is for a reader of this
+repository and is never delivered. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
+
+The verbs are the only way content moves. `kit install` resolves the active set, default modules plus those named
+plus their dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
+an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
+fails when a delivered file differs from the release. `kit module` changes the active set. Two rules govern
+placement: a `.json` destination is merged by key, the kit owning only the entries it writes; everything else is a
+copy. Each base has a manifest, `.kit/manifest` committed with the repository and `~/.kit/manifest` on the desk,
+recording the version, the active modules, and the release's digest of every delivered path, which is how an edit
+reads as an edit at every later update.
+
+## Finding a file's rules
+
+![Context: how any agent, and Claude Code's hook, find the rules that govern a file](context.svg)
+
+A rule is written once, in `.kit/rules/<kind>.md`, and copied into no harness's directory. Its frontmatter says
+what it governs: `paths:`, globs on the repository-relative path, and `content:`, patterns on the first line of a
+file that exists. `kit context <path>` names the rules governing a path and appends the ask to
+`.git/kit/context.log`. Every caller gets the same answer: an agent of any harness following the sentence in
+`.kit/1st.md`, a person at the shell, a tool reading `--json`, and Claude Code's `PreToolUse` hook, which the
+`claude` module wires to `kit context --claude` so the rules are named before every write. The call names and
+never quotes: reading the rule stays an act the caller takes, which is what lets a later check compare the log of
+asks against the reads.
+
+## The loop and the gate
+
+![The loop: an issue becomes a worktree and a draft pull request, the gate holds it, a human merges](loop.svg)
+
+The desk is the root checkout and belongs to the human; it usually has `main` checked out and may have any branch
+no worktree holds, and no agent changes it in place. Work starts from an issue: `kit issue <N>` makes
+`worktrees/<N>-<slug>`, a branch linked to the issue under Development, a signed start commit, and a draft pull
+request, and sweeps uncommitted work off the desk into the worktree. Everything after that happens in the worktree:
+`kit context` before a change, `kit lint` for the pre-commit linters by hand, `kit rebase` to bring the branch onto
+`origin/main` and push it, and `gh pr ready` when the pull request body is the report.
+
+The gate is the delivered CI job, three steps that are each one kit command. `kit gate` runs the root justfile's
+`ci` recipe and reports a missing one as a skip, never a pass. `kit check` holds the delivered files to the
+release. `kit linked` refuses a pull request not linked to an open issue of the repository. A human merges, and
+`kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: the desk, every
+worktree with its commits past the fork, and every open pull request with its state, age, and checks.
+
+## What verifies what
+
+| Claim | Held by |
+| --- | --- |
+| A delivered file is the release's | `kit check`, in the gate and on a desk, against the manifest's digests |
+| A change has an issue | `kit linked` in the gate; `kit issue` makes the link when it starts the work |
+| The repository's own gate ran | `kit gate`, which reports a skip as a skip |
+| A rule's text reached the agent | the Claude Code hook; the plain call for every other harness |
+| A file's rules were asked for | `.git/kit/context.log`, one line per ask |
+| The forbidden spellings were not used | the harness's deny list, delivered by its adapter module |
+| The desk was not disturbed | `kit rebase` refusing the root checkout; `kit issue` never switching it |
+
+What no check holds yet is whether a rule, once read, was followed. The linters hold the mechanical part of that
+for the kinds they cover; the rest is the pull request body's report, which the integrity rules in `.kit/1st.md`
+bind.
diff --git a/docs/context.svg b/docs/context.svg
new file mode 100644
index 0000000..a5e83e1
--- /dev/null
+++ b/docs/context.svg
@@ -0,0 +1,85 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1040 440" width="1040" height="440" role="img"
+  aria-labelledby="title desc">
+  <title id="title">Context: how any agent, and Claude Code's hook, find the rules that govern a file</title>
+  <desc id="desc">An agent or a person runs kit context with a path. The kit matches the path and the file's first
+    line against each rule's frontmatter, names the governing rules, and appends the ask to the context log. Claude
+    Code's PreToolUse hook makes the same call before every write.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569"/>
+    </marker>
+    <style>
+      text { font-family: Inter, -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; font-size: 14px; fill: #0f172a; }
+      .h { font-size: 16px; font-weight: 600; }
+      .m { font-family: "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; font-size: 13px; }
+      .d { fill: #475569; font-size: 12.5px; }
+      .box { stroke: #334155; stroke-width: 1.25; rx: 8; }
+      .edge { stroke: #475569; stroke-width: 1.5; fill: none; marker-end: url(#arrow); }
+      .lbl { fill: #334155; font-size: 12px; }
+    </style>
+  </defs>
+
+  <!-- callers -->
+  <rect class="box" x="24" y="40" width="250" height="110" fill="#f1f5f9"/>
+  <text class="h" x="40" y="68">Any agent, any harness</text>
+  <text class="d" x="40" y="92">Before creating or changing a file,</text>
+  <text class="d" x="40" y="108">as .kit/1st.md says:</text>
+  <text class="m" x="40" y="134">kit context &lt;path&gt;…</text>
+
+  <rect class="box" x="24" y="176" width="250" height="110" fill="#f1f5f9"/>
+  <text class="h" x="40" y="204">A person</text>
+  <text class="d" x="40" y="228">The same call, by hand or in a</text>
+  <text class="d" x="40" y="244">script, or with --json for a tool.</text>
+  <text class="m" x="40" y="270">kit context --json &lt;path&gt;…</text>
+
+  <rect class="box" x="24" y="312" width="250" height="104" fill="#ede9fe"/>
+  <text class="h" x="40" y="340">Claude Code</text>
+  <text class="d" x="40" y="364">PreToolUse on Write, Edit, MultiEdit,</text>
+  <text class="d" x="40" y="380">wired by the claude module:</text>
+  <text class="m" x="40" y="404">kit context --claude</text>
+
+  <!-- the call -->
+  <rect class="box" x="340" y="120" width="300" height="200" fill="#dcfce7"/>
+  <text class="h" x="356" y="148">kit context</text>
+  <text class="d" x="356" y="172">For each path, every rule file whose</text>
+  <text class="d" x="356" y="188">frontmatter matches:</text>
+  <text class="m" x="372" y="214">paths:</text>
+  <text class="d" x="440" y="214">globs on the repository path</text>
+  <text class="m" x="372" y="236">content:</text>
+  <text class="d" x="440" y="236">patterns on the first line</text>
+  <text class="d" x="356" y="264">Then the ask is appended to the log.</text>
+  <text class="d" x="356" y="290">Nothing is copied; the rule is named,</text>
+  <text class="d" x="356" y="306">and reading it stays the caller's act.</text>
+
+  <!-- rules -->
+  <rect class="box" x="716" y="40" width="300" height="150" fill="#e0f2fe"/>
+  <text class="h" x="732" y="68">The rules, once</text>
+  <text class="m" x="732" y="94">.kit/rules/&lt;kind&gt;.md</text>
+  <text class="m" x="732" y="120">---</text>
+  <text class="m" x="732" y="138">paths: ["**/*.sh"]</text>
+  <text class="m" x="732" y="156">content: ["^#!.*/(env +)?(ba)?sh( |$)"]</text>
+  <text class="m" x="732" y="174">---</text>
+
+  <!-- log -->
+  <rect class="box" x="716" y="220" width="300" height="90" fill="#fef9c3"/>
+  <text class="h" x="732" y="248">The record</text>
+  <text class="m" x="732" y="272">.git/kit/context.log</text>
+  <text class="d" x="732" y="294">epoch and path per ask: the evidence a check reads</text>
+
+  <!-- answers -->
+  <rect class="box" x="716" y="340" width="300" height="76" fill="#ffffff"/>
+  <text class="h" x="732" y="368">The answer</text>
+  <text class="d" x="732" y="390">rule paths, one per line; as JSON; or as the</text>
+  <text class="d" x="732" y="406">hook's additionalContext naming them</text>
+
+  <!-- edges -->
+  <path class="edge" d="M 274 95 C 310 95, 310 200, 336 200"/>
+  <path class="edge" d="M 274 231 L 336 231"/>
+  <path class="edge" d="M 274 364 C 310 364, 310 262, 336 262"/>
+  <path class="edge" d="M 640 170 C 680 170, 680 115, 712 115"/>
+  <text class="lbl" x="652" y="134">reads</text>
+  <path class="edge" d="M 640 250 C 680 250, 680 265, 712 265"/>
+  <text class="lbl" x="652" y="247">appends</text>
+  <path class="edge" d="M 640 300 C 680 300, 680 378, 712 378"/>
+  <text class="lbl" x="652" y="350">prints</text>
+</svg>
diff --git a/docs/delivery.svg b/docs/delivery.svg
new file mode 100644
index 0000000..68d4d39
--- /dev/null
+++ b/docs/delivery.svg
@@ -0,0 +1,100 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1040 560" width="1040" height="560" role="img"
+  aria-labelledby="title desc">
+  <title id="title">Delivery: a release's modules, through the kit's verbs, into a repository and a home</title>
+  <desc id="desc">The release carries bin/ and modules/. The verbs render templates, merge JSON by key, and copy the
+    rest into the repository root and the user's home, each recorded in its own manifest.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569"/>
+    </marker>
+    <style>
+      text { font-family: Inter, -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; font-size: 14px; fill: #0f172a; }
+      .h { font-size: 16px; font-weight: 600; }
+      .m { font-family: "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; font-size: 13px; }
+      .d { fill: #475569; font-size: 12.5px; }
+      .box { stroke: #334155; stroke-width: 1.25; rx: 8; }
+      .edge { stroke: #475569; stroke-width: 1.5; fill: none; marker-end: url(#arrow); }
+    </style>
+  </defs>
+
+  <!-- release -->
+  <rect class="box" x="24" y="40" width="300" height="480" fill="#e0f2fe"/>
+  <text class="h" x="40" y="68">Release</text>
+  <text class="m" x="40" y="88">kit-&lt;version&gt;/</text>
+
+  <rect class="box" x="40" y="104" width="268" height="118" fill="#ffffff"/>
+  <text class="m" x="52" y="126">bin/</text>
+  <text class="m" x="68" y="148">kit</text>
+  <text class="d" x="200" y="148">the command</text>
+  <text class="m" x="68" y="170">kit-&lt;verb&gt;.sh</text>
+  <text class="d" x="200" y="170">one per verb</text>
+  <text class="m" x="68" y="192">release.sh context.sh …</text>
+  <text class="d" x="258" y="212">sourced modules</text>
+
+  <rect class="box" x="40" y="236" width="268" height="268" fill="#ffffff"/>
+  <text class="m" x="52" y="258">modules/&lt;name&gt;/</text>
+  <text class="m" x="68" y="282">module.yml</text>
+  <text class="d" x="180" y="282">description, default,</text>
+  <text class="d" x="180" y="298">depends, answers</text>
+  <text class="m" x="68" y="322">files/repo/</text>
+  <text class="d" x="180" y="322">mirrored at the root</text>
+  <text class="m" x="68" y="346">files/home/</text>
+  <text class="d" x="180" y="346">mirrored at ~</text>
+  <text class="m" x="68" y="370">templates/&lt;base&gt;/</text>
+  <text class="d" x="180" y="386">@key@ rendered first</text>
+  <text class="m" x="68" y="412">docs/</text>
+  <text class="d" x="180" y="412">not delivered</text>
+  <text class="d" x="52" y="446">kit, lefthook, ci are default;</text>
+  <text class="d" x="52" y="462">claude is named; each may depend</text>
+  <text class="d" x="52" y="478">on others, resolved at install.</text>
+  <text class="m" x="52" y="500">version</text>
+  <text class="d" x="140" y="500">stamped by the release workflow</text>
+
+  <!-- verbs -->
+  <rect class="box" x="380" y="150" width="280" height="260" fill="#ede9fe"/>
+  <text class="h" x="396" y="178">The verbs</text>
+  <text class="m" x="396" y="204">kit install [&lt;module&gt;…]</text>
+  <text class="m" x="396" y="226">kit update</text>
+  <text class="m" x="396" y="248">kit check</text>
+  <text class="m" x="396" y="270">kit module list|add|remove</text>
+  <line x1="396" y1="286" x2="644" y2="286" stroke="#a78bfa" stroke-width="1"/>
+  <text class="d" x="396" y="308">resolve the active set and its depends</text>
+  <text class="d" x="396" y="326">render @key@ from .kit/answers</text>
+  <text class="d" x="396" y="344">merge a .json destination by key</text>
+  <text class="d" x="396" y="362">copy everything else</text>
+  <text class="d" x="396" y="380">digest each path into the manifest</text>
+  <text class="d" x="396" y="398">three-way merge an edited file on update</text>
+
+  <!-- repository -->
+  <rect class="box" x="716" y="40" width="300" height="300" fill="#dcfce7"/>
+  <text class="h" x="732" y="68">Repository root</text>
+  <text class="d" x="732" y="88">base: repo</text>
+  <text class="m" x="732" y="116">.kit/1st.md</text>
+  <text class="m" x="732" y="138">.kit/rules/&lt;kind&gt;.md</text>
+  <text class="m" x="732" y="160">.kit/lefthook.yml</text>
+  <text class="m" x="732" y="182">.github/workflows/kit-ci.yml</text>
+  <text class="m" x="732" y="204">.claude/CLAUDE.md</text>
+  <text class="m" x="732" y="226">.claude/settings.json</text>
+  <text class="d" x="912" y="226">merged</text>
+  <line x1="732" y1="244" x2="1000" y2="244" stroke="#4ade80" stroke-width="1"/>
+  <text class="m" x="732" y="268">.kit/manifest</text>
+  <text class="d" x="856" y="268">version, modules, digests</text>
+  <text class="m" x="732" y="290">.kit/answers</text>
+  <text class="d" x="856" y="290">yours, never written</text>
+  <text class="m" x="732" y="312">AGENTS.md</text>
+  <text class="d" x="856" y="312">yours; names .kit/1st.md</text>
+
+  <!-- home -->
+  <rect class="box" x="716" y="380" width="300" height="140" fill="#fef9c3"/>
+  <text class="h" x="732" y="408">Home</text>
+  <text class="d" x="800" y="408">base: home, the user's ~</text>
+  <text class="m" x="732" y="436">~/.kit/manifest</text>
+  <text class="d" x="732" y="456">the desk's record, not the repository's;</text>
+  <text class="d" x="732" y="472">a runner has none, and kit check says so.</text>
+  <text class="d" x="732" y="500">No module delivers here yet.</text>
+
+  <!-- edges -->
+  <path class="edge" d="M 324 280 L 376 280"/>
+  <path class="edge" d="M 660 220 C 690 220, 690 190, 712 190"/>
+  <path class="edge" d="M 660 340 C 690 340, 690 450, 712 450"/>
+</svg>
diff --git a/docs/loop.svg b/docs/loop.svg
new file mode 100644
index 0000000..ce8d423
--- /dev/null
+++ b/docs/loop.svg
@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1040 500" width="1040" height="500" role="img"
+  aria-labelledby="title desc">
+  <title id="title">The loop: an issue becomes a worktree and a draft pull request, the gate holds it, a human merges</title>
+  <desc id="desc">The desk is the root checkout and stays the human's. kit issue makes a worktree per issue with a
+    linked branch and a draft pull request. Work happens there under kit context, kit lint, and kit rebase. The
+    delivered CI job runs the gate, kit check, and the linked-open-issue refusal. A human merges, and kit tidy sweeps.
+    kit status draws the whole picture.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569"/>
+    </marker>
+    <style>
+      text { font-family: Inter, -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; font-size: 14px; fill: #0f172a; }
+      .h { font-size: 16px; font-weight: 600; }
+      .m { font-family: "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; font-size: 13px; }
+      .d { fill: #475569; font-size: 12.5px; }
+      .box { stroke: #334155; stroke-width: 1.25; rx: 8; }
+      .edge { stroke: #475569; stroke-width: 1.5; fill: none; marker-end: url(#arrow); }
+      .lbl { fill: #334155; font-size: 12px; }
+    </style>
+  </defs>
+
+  <!-- desk -->
+  <rect class="box" x="24" y="40" width="300" height="130" fill="#fef9c3"/>
+  <text class="h" x="40" y="68">The desk</text>
+  <text class="d" x="40" y="92">The root checkout, the human's. Usually on main,</text>
+  <text class="d" x="40" y="108">sometimes on a branch no worktree holds. No agent</text>
+  <text class="d" x="40" y="124">checks out, resets, or rebases it.</text>
+  <text class="m" x="40" y="152">kit status</text>
+  <text class="d" x="140" y="152">draws desk, worktrees, pull requests</text>
+
+  <!-- issue -->
+  <rect class="box" x="24" y="210" width="300" height="80" fill="#f1f5f9"/>
+  <text class="h" x="40" y="238">An issue</text>
+  <text class="d" x="40" y="262">A change without one has not started.</text>
+  <text class="d" x="40" y="278">A design is prose in its body.</text>
+
+  <!-- worktree -->
+  <rect class="box" x="380" y="40" width="300" height="250" fill="#dcfce7"/>
+  <text class="h" x="396" y="68">The worktree</text>
+  <text class="m" x="396" y="92">kit issue &lt;N&gt;</text>
+  <text class="d" x="396" y="112">worktrees/&lt;N&gt;-&lt;slug&gt;, a branch linked under</text>
+  <text class="d" x="396" y="128">Development, a start commit, a draft pull request.</text>
+  <line x1="396" y1="144" x2="664" y2="144" stroke="#4ade80" stroke-width="1"/>
+  <text class="d" x="396" y="166">Work happens here, and only here:</text>
+  <text class="m" x="396" y="190">kit context &lt;path&gt;</text>
+  <text class="d" x="560" y="190">before a change</text>
+  <text class="m" x="396" y="212">kit lint</text>
+  <text class="d" x="560" y="212">the hook by hand</text>
+  <text class="m" x="396" y="234">kit rebase</text>
+  <text class="d" x="560" y="234">onto origin/main, pushed</text>
+  <text class="m" x="396" y="256">gh pr ready</text>
+  <text class="d" x="560" y="256">the body is the report</text>
+  <text class="d" x="396" y="280">Signed commits, subject #&lt;N&gt; &lt;area&gt;: &lt;subject&gt;.</text>
+
+  <!-- gate -->
+  <rect class="box" x="736" y="40" width="280" height="250" fill="#ede9fe"/>
+  <text class="h" x="752" y="68">The gate</text>
+  <text class="d" x="752" y="92">The delivered CI job, on every pull request:</text>
+  <text class="m" x="752" y="118">just ci</text>
+  <text class="d" x="752" y="136">the repository's own gate</text>
+  <text class="m" x="752" y="162">kit check</text>
+  <text class="d" x="752" y="180">every delivered file matches the release</text>
+  <text class="m" x="752" y="206">linked-open-issue</text>
+  <text class="d" x="752" y="224">refused without an open issue of this</text>
+  <text class="d" x="752" y="240">repository under Development</text>
+  <text class="d" x="752" y="268">On a desk, the pre-commit hook runs the</text>
+  <text class="d" x="752" y="284">linters over what is staged.</text>
+
+  <!-- merge -->
+  <rect class="box" x="380" y="340" width="300" height="120" fill="#f1f5f9"/>
+  <text class="h" x="396" y="368">A human merges</text>
+  <text class="d" x="396" y="392">Nothing reaches main any other way, and</text>
+  <text class="d" x="396" y="408">nothing is called merged until it is observed.</text>
+  <text class="m" x="396" y="436">kit tidy</text>
+  <text class="d" x="480" y="436">removes the worktree and its branch</text>
+
+  <!-- harness guards -->
+  <rect class="box" x="736" y="340" width="280" height="120" fill="#e0f2fe"/>
+  <text class="h" x="752" y="368">The harness adapter</text>
+  <text class="d" x="752" y="392">Deny list: git rebase, push --force, reset --hard,</text>
+  <text class="d" x="752" y="408">checkout main, worktree remove --force.</text>
+  <text class="d" x="752" y="432">Hook: kit context before every write.</text>
+  <text class="d" x="752" y="448">Nothing copied from the rules.</text>
+
+  <!-- edges -->
+  <path class="edge" d="M 324 250 C 350 250, 350 92, 376 92"/>
+  <text class="lbl" x="300" y="196">kit issue</text>
+  <path class="edge" d="M 680 165 L 732 165"/>
+  <text class="lbl" x="686" y="158">push</text>
+  <path class="edge" d="M 876 290 C 876 320, 700 320, 684 380"/>
+  <text class="lbl" x="886" y="318">green, reviewed</text>
+  <path class="edge" d="M 380 400 C 200 400, 174 300, 174 174"/>
+  <text class="lbl" x="196" y="330">main advances; the desk pulls</text>
+</svg>
diff --git a/docs/modules.md b/docs/modules.md
index 0b7c553..0fe0fcd 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -47,6 +47,11 @@ answers:
 | `depends` | Modules activated with this one. `kit module remove` refuses a module another active module depends on. |
 | `answers` | The default value of each template key. A repository overrides one in `.kit/answers`. |
 
+[module.schema.json](../modules/module.schema.json) is the schema, JSON Schema 2020-12. The gate validates every
+`module.yml` against it with `ajv`, and `kit install` holds a module to the same contract where no validator is:
+a key it does not know, a `default` that is not `true` or `false`, or a dependency the release lacks is refused,
+naming it.
+
 ## Delivery
 
 A file under `files/<base>/` is placed at the same path under the base's root. A destination ending in `.json` is
diff --git a/justfile b/justfile
index b271160..84f9c04 100644
--- a/justfile
+++ b/justfile
@@ -21,18 +21,20 @@ _: help
 set export := true
 
 # The gate: shellcheck over every bash file, actionlint over every workflow, markdownlint over every markdown
-# file, the bats suite, and bin/kit check over this repository's installed copy of its own kit. The runner runs
+# file, every module.yml against modules/module.schema.json, the bats suite, and bin/kit check over this
+# repository's installed copy of its own kit. The runner runs
 # it on every pull request, and a desk runs it the same way; the pre-commit hook is the narrower, faster check
 # over the staged paths.
 #
 #   just ci
-[doc("🚦 The gate: shellcheck, actionlint, markdownlint, bats, kit check")]
+[doc("🚦 The gate: shellcheck, actionlint, markdownlint, the module schema, bats, kit check")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
   mise exec -- shellcheck --shell=bash --external-sources bin/kit bin/*.sh
   mise exec -- actionlint
   mise exec -- markdownlint-cli2 '**/*.md'
+  mise exec -- ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
diff --git a/mise.lock b/mise.lock
index 937bbd2..87f18eb 100644
--- a/mise.lock
+++ b/mise.lock
@@ -169,6 +169,12 @@ checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
 
+[[tools."npm:ajv-cli"]]
+version = "5.0.0"
+aube = { path = ".mise/locks/npm-ajv-cli/5.0.0", digest = "sha256:36d7da953aa2dac85d8e85af560d39cd2802e0b55dbc19ab9416b6ca0a1c3f9e" }
+backend = "npm:ajv-cli"
+specifiers = ["5"]
+
 [[tools."npm:markdownlint-cli2"]]
 version = "0.24.0"
 aube = { path = ".mise/locks/npm-markdownlint-cli2/0.24.0", digest = "sha256:689e86a3f956c317400e5d3bcf0915902a43dbbb8aeec7210a3aa3efb6859684" }
diff --git a/mise.toml b/mise.toml
index a5ead37..6a3b9e5 100644
--- a/mise.toml
+++ b/mise.toml
@@ -20,5 +20,6 @@ bats = "1.14"
 gh = "2.103"
 jq = "1.8"
 just = "1.59"
+"npm:ajv-cli" = "5"
 "npm:markdownlint-cli2" = "0.24"
 shellcheck = "0.11"
diff --git a/modules/ci/docs/README.md b/modules/ci/docs/README.md
index 41912f8..8e59d3b 100644
--- a/modules/ci/docs/README.md
+++ b/modules/ci/docs/README.md
@@ -1,7 +1,9 @@
 # The ci module
 
-Places `.github/workflows/kit-ci.yml`: one job, `CI`, which runs the repository's `just ci` when its root justfile
-has that recipe, runs `kit check`, and refuses a pull request not linked to an open issue of the repository.
+Places `.github/workflows/kit-ci.yml`: one job, `CI`, whose steps are one kit command each. `kit gate` runs the
+repository's `just ci` when its root justfile has that recipe and reports a missing one as a skip, `kit check`
+holds every delivered file to the pinned release, and `kit linked` refuses a pull request not linked to an open
+issue of the repository. Each is a verb a desk can run, so the runner does nothing a person cannot repeat.
 
 The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
 a repository with runners of its own puts `ci_runner <label>` in `.kit/answers`.
diff --git a/modules/ci/templates/repo/.github/workflows/kit-ci.yml b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
index b4c1ba6..a52b5bc 100644
--- a/modules/ci/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
@@ -1,10 +1,11 @@
 # kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires. Three steps: the repository's `just ci` when its
-# root justfile has one, `kit check` with the kit mise pins, and a refusal of a pull request not linked to an
-# open issue of this repository under Development. The last two run even when an earlier step refused, so one
-# run reports every finding.
+# One job, CI, which is the check name a ruleset requires. Each step is one kit command, so what the runner does
+# is what a desk can do: `kit gate` runs the root justfile's ci recipe and reports a missing one as a skip,
+# `kit check` holds every delivered file to the pinned release, and `kit linked` refuses a pull request not linked
+# to an open issue of this repository under Development. The last two run even when an earlier step refused, so
+# one run reports every finding.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update. Rendered from a template: the
 # job runs on the ci_runner answer, ubuntu-latest unless .kit/answers says otherwise.
@@ -25,7 +26,7 @@ permissions:
 jobs:
   CI:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
-    runs-on: @ci_runner@
+    runs-on: "@ci_runner@"
     env:
       # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
       MISE_ENV: ci
@@ -35,117 +36,20 @@ jobs:
       # Every tool below comes from mise.toml, the kit included; this repository's mise.toml puts bin/ on PATH.
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
 
+      - name: kit-on-path
+        run: command -v kit >/dev/null || { echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'; exit 1; }
+
       - name: gate
-        run: |
-          set -o errexit -o nounset -o pipefail
-          # A missing recipe is a skip; a justfile that cannot be read is a failure, never a silent skip.
-          if [[ ! -f justfile ]]
-          then
-            echo "::warning::there is no root justfile, so the gate was skipped"
-            printf '⚠️ The gate was skipped: there is no root justfile.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
-          elif ! recipes=$(just --summary 2>&1)
-          then
-            echo "::error::the root justfile could not be read: ${recipes}"
-            printf '### ❌ The root justfile could not be read\n\n%s\n' "${recipes}" | tee --append "${GITHUB_STEP_SUMMARY}"
-            exit 1
-          elif ! tr ' ' '\n' <<< "${recipes}" | grep --quiet --line-regexp ci
-          then
-            echo "::warning::the root justfile has no ci recipe, so the gate was skipped"
-            printf '⚠️ The gate was skipped: the root justfile has no ci recipe.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
-          else
-            just ci
-            printf '✅ just ci passed.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
-          fi
+        run: kit gate
 
       - name: kit-check
         if: ${{ !cancelled() }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-          if ! command -v kit >/dev/null 2>&1
-          then
-            echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'
-            printf '### ❌ kit is not on PATH\n\nPin the release in mise.toml under [tools]: "github:empowerite/kit" = "<version>".\n' \
-              | tee --append "${GITHUB_STEP_SUMMARY}"
-            exit 1
-          fi
-          kit check
-          printf '✅ Every delivered file matches the pinned kit release.\n' | tee --append "${GITHUB_STEP_SUMMARY}"
+        run: kit check
 
       - name: linked-open-issue
         if: ${{ !cancelled() }}
         env:
           GH_TOKEN: ${{ github.token }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-
-          repo_slug="${GITHUB_REPOSITORY}"
-          pr=$(jq --raw-output '.pull_request.number' "${GITHUB_EVENT_PATH}")
-          pull="${GITHUB_SERVER_URL}/${repo_slug}/pull/${pr}"
-          run="${GITHUB_SERVER_URL}/${repo_slug}/actions/runs/${GITHUB_RUN_ID}"
-
-          remedy=$(cat <<REMEDY
-          Link an open issue of this repository under **Development** in [the sidebar](${pull}):
-
-          1. click the gear (⚙) beside **Development**
-          2. pick one or more open issues
-          3. [re-run this check](${run}): linking fires no event, so it does not re-run on its own
-
-          \`kit issue <N>\` makes this link when it starts the work.
-          REMEDY
-          )
-
-          refuse() {
-            echo "::error::$1"
-            printf '### ❌ %s\n\n%s\n' "${1^}" "${remedy}" | tee --append "${GITHUB_STEP_SUMMARY}"
-            return 1
-          }
-
-          query=$(cat <<'GRAPHQL'
-          query($owner: String!, $name: String!, $number: Int!) {
-            repository(owner: $owner, name: $name) {
-              pullRequest(number: $number) {
-                closingIssuesReferences(first: 100) {
-                  nodes { number state repository { nameWithOwner } }
-                }
-              }
-            }
-          }
-          GRAPHQL
-          )
-          refs=$(gh api graphql \
-            --field owner="${repo_slug%%/*}" \
-            --field name="${repo_slug#*/}" \
-            --field number="${pr}" \
-            --raw-field query="${query}" \
-            --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
-                  | "\(.number) \(.state) \(.repository.nameWithOwner)"')
-
-          if [[ -z "${refs}" ]]
-          then
-            refuse 'this pull request is not linked to any issue'
-          else
-            open_local=0
-            while read -r n state repo
-            do
-              if [[ "${repo}" != "${repo_slug}" ]]
-              then
-                echo "::warning::skipping ${repo}#${n}: it belongs to another repository"
-                continue
-              fi
-              if [[ "${state}" != OPEN ]]
-              then
-                echo "::warning::${repo}#${n} is ${state}; merging will not change it"
-                continue
-              fi
-              open_local=$(( open_local + 1 ))
-            done <<< "${refs}"
-            if (( open_local == 0 ))
-            then
-              refuse 'every issue this pull request is linked to is closed or belongs to another repository'
-            else
-              closes=$(cut --delimiter=' ' --fields=1 <<< "${refs}" | sed 's/^/#/' | paste --serial --delimiters=' ')
-              printf '✅ Linked to %s.\n' "${closes}" | tee --append "${GITHUB_STEP_SUMMARY}"
-            fi
-          fi
+        run: kit linked
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/module.schema.json b/modules/module.schema.json
new file mode 100644
index 0000000..add8873
--- /dev/null
+++ b/modules/module.schema.json
@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/empowerite/kit/modules/module.schema.json",
+  "title": "module.yml",
+  "description": "The metadata of one kit module: modules/<name>/module.yml. docs/modules.md says what each key means. The gate validates every module.yml against this file, and kit install refuses a module whose keys it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["description"],
+  "properties": {
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120,
+      "description": "One line, shown by kit module list."
+    },
+    "default": {
+      "type": "boolean",
+      "description": "true for a module active unless removed; kit install with no names activates every default module."
+    },
+    "depends": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "description": "The name of another module in the release, activated with this one."
+      }
+    },
+    "answers": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z_]+$": {
+          "type": "string",
+          "description": "The default value of a template key, written @key@ in the module's templates."
+        }
+      }
+    }
+  }
+}
diff --git a/tests/gate.bats b/tests/gate.bats
new file mode 100644
index 0000000..b3b0459
--- /dev/null
+++ b/tests/gate.bats
@@ -0,0 +1,55 @@
+#!/usr/bin/env bats
+# gate.bats - kit gate runs the root justfile's ci recipe, and reports a missing one as a skip and an unreadable one as a failure
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  repo=$(mktemp -d)
+  cd "${repo}"
+  export GITHUB_STEP_SUMMARY="${repo}/summary.md"
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+@test "no justfile is a skip, said so, and not a pass" {
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no root justfile, so the gate was skipped"* ]]
+  grep --quiet 'skipped' summary.md
+}
+
+@test "a justfile without a ci recipe is a skip" {
+  printf 'build:\n  echo built\n' > justfile
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no ci recipe, so the gate was skipped"* ]]
+}
+
+@test "a justfile that cannot be read is a failure" {
+  printf 'ci:\n  echo\nci:\n  echo twice\n' > justfile
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"the root justfile could not be read"* ]]
+  grep --quiet 'could not be read' summary.md
+}
+
+@test "a ci recipe runs, and its failure is the gate's" {
+  printf 'ci:\n  echo gate ran\n' > justfile
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"gate ran"* ]]
+  grep --quiet 'just ci passed' summary.md
+  printf 'ci:\n  exit 3\n' > justfile
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -ne 0 ]
+}
+
+@test "linked names the pull request it needs when none can be found" {
+  run env -u GITHUB_EVENT_PATH "${kit_checkout}/bin/kit" linked
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"kit linked <number>"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 2d92f65..c010375 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -34,7 +34,7 @@ later-release() {
   [ -f .kit/rules/bash.md ]
   [ -f .kit/lefthook.yml ]
   [ -f .github/workflows/kit-ci.yml ]
-  grep --quiet '^    runs-on: ubuntu-latest$' .github/workflows/kit-ci.yml
+  grep --quiet '^    runs-on: "ubuntu-latest"$' .github/workflows/kit-ci.yml
   [ ! -e .claude ]
   grep --quiet '^version unreleased$' .kit/manifest
   grep --quiet '^modules kit ci lefthook$' .kit/manifest
@@ -103,7 +103,7 @@ later-release() {
   mkdir .kit && printf 'ci_runner blacksmith-2vcpu\n' > .kit/answers
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
-  grep --quiet '^    runs-on: blacksmith-2vcpu$' .github/workflows/kit-ci.yml
+  grep --quiet '^    runs-on: "blacksmith-2vcpu"$' .github/workflows/kit-ci.yml
   grep --quiet 'uses: actions/checkout@' .github/workflows/kit-ci.yml
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
@@ -115,6 +115,19 @@ later-release() {
   [ ! -e OWNER ]
 }
 
+@test "a module whose metadata has a key the schema does not know is refused, naming the key" {
+  later-release "${repo}.later"
+  printf 'description: "x"\ndependz:\n  - kit\n' > "${repo}.later/modules/lefthook/module.yml"
+  run "${repo}.later/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"modules/lefthook/module.yml has a key the kit does not know: dependz"* ]]
+  [ ! -e .kit/manifest ]
+  printf 'description: "x"\ndefault: yes\n' > "${repo}.later/modules/lefthook/module.yml"
+  run "${repo}.later/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"default must be true or false"* ]]
+}
+
 @test "a module delivering to a base the kit does not know is refused, naming the bases" {
   later-release "${repo}.later"
   mkdir -p "${repo}.later/modules/kit/files/etc" && printf 'x\n' > "${repo}.later/modules/kit/files/etc/.x"

From 8821ecba77ebcaa4c2f400214ed8f9f9f195157e Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:45:09 -0700
Subject: [PATCH 069/108] #4 docs/loop.svg: the gate's steps by their verbs

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/loop.svg | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/loop.svg b/docs/loop.svg
index ce8d423..342c8a0 100644
--- a/docs/loop.svg
+++ b/docs/loop.svg
@@ -57,11 +57,11 @@
   <rect class="box" x="736" y="40" width="280" height="250" fill="#ede9fe"/>
   <text class="h" x="752" y="68">The gate</text>
   <text class="d" x="752" y="92">The delivered CI job, on every pull request:</text>
-  <text class="m" x="752" y="118">just ci</text>
-  <text class="d" x="752" y="136">the repository's own gate</text>
+  <text class="m" x="752" y="118">kit gate</text>
+  <text class="d" x="752" y="136">the root justfile's ci recipe, or a skip said so</text>
   <text class="m" x="752" y="162">kit check</text>
   <text class="d" x="752" y="180">every delivered file matches the release</text>
-  <text class="m" x="752" y="206">linked-open-issue</text>
+  <text class="m" x="752" y="206">kit linked</text>
   <text class="d" x="752" y="224">refused without an open issue of this</text>
   <text class="d" x="752" y="240">repository under Development</text>
   <text class="d" x="752" y="268">On a desk, the pre-commit hook runs the</text>

From 6c22d27920bb029d5ce109eba17c164684d8e821 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:51:36 -0700
Subject: [PATCH 070/108] #4 bin/kit-update.sh: retire paths a release no
 longer delivers, and read a targets manifest as modules

Found by updating an rc.4 install to rc.5: the old manifest has a targets line and no modules line,
so the update read an empty set, delivered nothing, and left the rule mirrors behind unmanaged with
check passing vacuously. A manifest written before modules existed now reads as the default modules
plus its targets. A path the previous release delivered and the new one does not is retired: removed
when it is still the previous release's own content, its entries taken out of a merged .json when
the base is at hand, and otherwise left with a warning. Two tests. 46 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/kit-update.sh | 33 +++++++++++++++++++++++++++++++--
 bin/release.sh    | 23 ++++++++++++++++++++++-
 tests/kit.bats    | 29 +++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 87c81c0..c9e974e 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -5,8 +5,10 @@
 # A file whose digest still matches its manifest, which records the previous release's own content, is replaced.
 # An edited one is three-way merged with the previous release as the base, which release:fetch finds or fetches.
 # A path the previous release did not deliver is written only where there is nothing, or the same thing, there.
-# A template is rendered from the repository's answers in both releases before either is compared. The home base
-# is updated against ~/.kit/manifest the same way.
+# A path the previous release delivered and this one does not is retired: removed when it is still the previous
+# release's own content, its entries taken out of a merged .json when the base is at hand, and otherwise left
+# with a warning. A template is rendered from the repository's answers in both releases before either is
+# compared. The home base is updated against ~/.kit/manifest the same way.
 #
 # see: bin/release.sh
 
@@ -99,6 +101,33 @@ do
       fi
     fi
   done < <(release:delivered "${kit_root}" "${base}" "${modules[@]}")
+
+  # The paths this release no longer delivers under the base.
+  while IFS= read -r path
+  do
+    [[ -n "${path}" ]] || continue
+    dest=$(release:dest "${base}" "${path}")
+    [[ -e "${dest}" ]] || continue
+    if release:merged "${dest}"
+    then
+      previous_src=""
+      [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "${modules[@]}")
+      if [[ -n "${previous_src}" ]]
+      then
+        step "${dest}: retired in ${current}, the previous release's entries taken out"
+        # shellcheck disable=SC2016  # a jq filter, with jq variables
+        release:json-write "${dest}" 'unmerge(.; $base[0])' --slurpfile base "${previous_src}"
+      else
+        warn "${dest}: retired in ${current}, but without the base release its entries cannot be taken out; it is left as it was"
+      fi
+    elif [[ "$(release:recorded "${base}" "${path}")" == "$(release:digest < "${dest}")" ]]
+    then
+      step "${dest}: retired in ${current}, removed"
+      rm -f "${dest}"
+    else
+      warn "${dest}: retired in ${current}, but edited since ${previous}; it is left as it was"
+    fi
+  done < <(comm -23 <(release:manifest-paths "${base}" | sort) <(release:delivered "${kit_root}" "${base}" "${modules[@]}" | cut -f 1 | sort))
 done
 
 release:write-manifests "${modules[@]}"
diff --git a/bin/release.sh b/bin/release.sh
index c2cd00b..ad25c1a 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -492,7 +492,28 @@ release:write-manifests() {
 }
 
 release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
-release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest; }
+
+# release:manifest-modules prints the active modules the repository's manifest records. A manifest written before
+# modules existed records targets instead, and reads as the default modules plus those targets, which is what that
+# release delivered.
+release:manifest-modules() {
+  if grep --quiet '^modules' .kit/manifest
+  then
+    sed -n 's/^modules *//p' .kit/manifest
+  else
+    # shellcheck disable=SC2046  # the names are meant to split
+    release:resolve "${kit_root}" $(release:default-modules "${kit_root}") $(sed -n 's/^targets *//p' .kit/manifest) \
+      | paste -s -d ' ' -
+  fi
+}
+
+# release:manifest-paths <base> prints every path the base's manifest records.
+release:manifest-paths() {
+  local manifest
+  manifest=$(release:manifest "$1")
+  [[ -f "${manifest}" ]] || return 0
+  awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' "${manifest}"
+}
 
 # release:recorded <base> <path> prints the digest the base's manifest records for <path>, or nothing.
 release:recorded() {
diff --git a/tests/kit.bats b/tests/kit.bats
index c010375..df9b71b 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -256,6 +256,35 @@ later-release() {
   [[ "$output" == *"conflict markers"* ]]
 }
 
+@test "update retires a path the new release no longer delivers, unless it was edited" {
+  "${kit_checkout}/bin/kit" install claude
+  later-release "${repo}.later"
+  rm "${repo}.later/modules/kit/files/repo/.kit/rules/yaml.md" "${repo}.later/modules/kit/files/repo/.kit/rules/json.md"
+  printf 'mine too\n' >> .kit/rules/json.md
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 0 ]
+  [ ! -e .kit/rules/yaml.md ]
+  [ -e .kit/rules/json.md ]
+  [[ "$output" == *".kit/rules/yaml.md: retired in 9.9.9, removed"* ]]
+  [[ "$output" == *".kit/rules/json.md: retired in 9.9.9, but edited"* ]]
+  grep --quiet --invert-match 'rules/yaml.md' .kit/manifest
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 0 ]
+}
+
+@test "update reads a manifest written before modules existed as the default modules plus its targets" {
+  "${kit_checkout}/bin/kit" install claude
+  sed -i.bak 's/^modules .*$/targets claude/' .kit/manifest && rm .kit/manifest.bak
+  grep --quiet '^targets claude$' .kit/manifest
+  later-release "${repo}.later"
+  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
+  [ "$status" -eq 0 ]
+  grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
+  jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
+  run "${repo}.later/bin/kit" check
+  [ "$status" -eq 0 ]
+}
+
 @test "update without the base release refuses an edited file and names the base" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"

From 12e4bd759954b68916f2a5758aa0b489aa105caf Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 01:55:05 -0700
Subject: [PATCH 071/108] #4 bin/release.sh: no upgrade path from an unreleased
 version

The reading of a targets manifest as modules served only the pre-release manifests, and goes. The
retirement of a path a release no longer delivers stays, since any release may drop one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/release.sh | 14 +-------------
 tests/kit.bats | 13 -------------
 2 files changed, 1 insertion(+), 26 deletions(-)

diff --git a/bin/release.sh b/bin/release.sh
index ad25c1a..a3b610e 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -493,19 +493,7 @@ release:write-manifests() {
 
 release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
 
-# release:manifest-modules prints the active modules the repository's manifest records. A manifest written before
-# modules existed records targets instead, and reads as the default modules plus those targets, which is what that
-# release delivered.
-release:manifest-modules() {
-  if grep --quiet '^modules' .kit/manifest
-  then
-    sed -n 's/^modules *//p' .kit/manifest
-  else
-    # shellcheck disable=SC2046  # the names are meant to split
-    release:resolve "${kit_root}" $(release:default-modules "${kit_root}") $(sed -n 's/^targets *//p' .kit/manifest) \
-      | paste -s -d ' ' -
-  fi
-}
+release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest; }
 
 # release:manifest-paths <base> prints every path the base's manifest records.
 release:manifest-paths() {
diff --git a/tests/kit.bats b/tests/kit.bats
index df9b71b..c5f6180 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -272,19 +272,6 @@ later-release() {
   [ "$status" -eq 0 ]
 }
 
-@test "update reads a manifest written before modules existed as the default modules plus its targets" {
-  "${kit_checkout}/bin/kit" install claude
-  sed -i.bak 's/^modules .*$/targets claude/' .kit/manifest && rm .kit/manifest.bak
-  grep --quiet '^targets claude$' .kit/manifest
-  later-release "${repo}.later"
-  run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
-  [ "$status" -eq 0 ]
-  grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
-  jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
-  run "${repo}.later/bin/kit" check
-  [ "$status" -eq 0 ]
-}
-
 @test "update without the base release refuses an edited file and names the base" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"

From 2eb92055ba30b337c2c1a26438d9dde5edc5b226 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 02:19:35 -0700
Subject: [PATCH 072/108] #4 lefthook.yml, AGENTS.md, README.md: the last
 references to tree/ and targets/

Copilot's three findings: the refresh hook matched the old source directories, so a change under
modules/ did not refresh the installed copies; the repository rule and the README described the
retired layout. All now name bin/, modules/, and the stamped version.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .markdownlint.jsonc | 2 +-
 AGENTS.md           | 2 +-
 README.md           | 4 ++--
 docs/modules.md     | 2 +-
 lefthook.yml        | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
index 53d88f5..38f7fc7 100644
--- a/.markdownlint.jsonc
+++ b/.markdownlint.jsonc
@@ -5,7 +5,7 @@
 // rule is tightened where the default is looser than the convention.
 //
 // see: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
-// see: tree/.kit/rules/markdown.md
+// see: modules/kit/files/repo/.kit/rules/markdown.md
 {
   // MD003 heading-style, tightened: the markdown rule says ATX, and "consistent" would accept a setext file.
   "MD003": { "style": "atx" },
diff --git a/AGENTS.md b/AGENTS.md
index 43408df..e4d6a35 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,7 +3,7 @@ repository trustworthy. This repository is the kit's own source, and uses it.
 
 ## This repository's own rules
 
-- The release is `bin/`, `tree/`, and `targets/`. Everything in it is written for a
+- The release is `bin/` and `modules/`. Everything in it is written for a
   consumer: no file names a consumer, a person, or another repository as the source of a rule.
 - A release is the tag `v<version>` on a commit on `main`; a pre-release is `v<version>-<suffix>` on a commit that is
   not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
diff --git a/README.md b/README.md
index f9a6e77..a1f8db6 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ ones, in its own files, and survive every update.
 
 ## Install
 
-The `kit` command is a release: a tarball holding `bin/`, `tree/`, and `targets/`. Take it whichever way the
+The `kit` command is a release: a tarball holding `bin/`, `modules/`, and a stamped `version`. Take it whichever way the
 repository takes its other tools.
 
 With mise, pin it in `mise.toml` and the version is part of the repository:
@@ -149,7 +149,7 @@ delivered by kit; `settings.json` cannot, so this table is its notice.
 A release is the tag `v<version>` on a commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`,
 say `v0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a GitHub pre-release. The tag is the
 version: the repository carries no version file, the workflow stamps the tag's version into the packed kit, and a
-published release is immutable, so a tag is never reused. The workflow packs `bin/`, `tree/`, and `targets/` into
+published release is immutable, so a tag is never reused. The workflow packs `bin/`, `modules/`, and `version` into
 `kit-<version>.tar.gz` and publishes the release; it refuses a tag that is not a version, a release tag off
 `main`, and a pre-release tag on `main`. A release is permanent. A pre-release is retired, tag and all, when the
 branch it was tagged on is deleted and no other branch reaches its commit.
diff --git a/docs/modules.md b/docs/modules.md
index 0fe0fcd..3ce6dec 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -60,7 +60,7 @@ release's entries are taken out, so a repository's own keys and entries survive.
 Where two active modules deliver the same path, the later module in dependency order wins.
 
 A file under `templates/<base>/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
-answer, then the result is placed, digested, and merged exactly as a `tree/` file is. The form is one neither
+answer, then the result is placed, digested, and merged exactly as a `files/` file is. The form is one neither
 bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
 answers live in `.kit/answers`, a file of `key value` lines the repository owns and the kit never writes; a key
 with no line there takes the module's `answer` default, and a key with neither refuses the install, naming the key
diff --git a/lefthook.yml b/lefthook.yml
index 840a2a8..b27e1b8 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -20,5 +20,5 @@ pre-commit:
     # the index, so nobody remembers just refresh. The recipe stages what it rewrote; stage_fixed would re-stage
     # only the source paths it was handed.
     refresh:
-      glob: "{tree,targets}/**"
+      glob: "modules/**"
       run: just refresh

From 09aa6edef85082981ee64bb40134c668e87684cb Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 03:06:22 -0700
Subject: [PATCH 073/108] #4 review: the bash and the documentation held to
 what they claim

Two independent reviews, every finding applied but two.

Code. git:worktrees puts the branch, the one field that can be empty, last, so a tab read no longer
misreads a detached worktree as a branch named true; kit tidy and kit status read it that way. The
verbs run from the repository root wherever they were typed, with the typed-in directory exported
for the paths kit context and kit status take. kit install and kit module add refuse a different
file at a delivered path instead of overwriting it, and update's new-path refusal is the same
function. kit update at the same version uses the release as its own base; a path left for lack of
a base keeps the manifest at the previous version; a failing render of the base is an error. The
home manifest, shared by every repository on the desk, is written when a module delivers there,
trimmed of gone paths otherwise, and never removed over another repository's lines; retirement
under home touches only paths the previous release delivered for these modules. kit rebase refuses
a dirty worktree and survives a failed abort. kit gate refuses a missing justfile or ci recipe,
since a gate that cannot run clears nothing. kit issue requires a signing key and writes the start
commit as #N start: title, the loop's own shape. kit module remove judges dependents against what
stays, in any order. Also: resolve with no names, the issue-create capture, gh repo view once,
warnings where status's GitHub read fails, headers on every function, every sort and comm in the C
locale, copies that keep the source's mode, manifest paths read by column so a space survives,
dangling links refused before anything is placed, and every code line under 120 columns.

Tests. Every suite has a home and a cache of its own; the lint suite had neither and removed
~/.kit/manifest. The base-fetch test installs a versioned release and shims mise and gh, so the fetch
path is the one tested. New: subdirectory invocation, overwrite refusal, same-version update,
multi-module remove, a foreign home manifest, a detached worktree through git:worktrees, a relative
context path from a subdirectory, and the gate's refusals. 52 cases.

Documentation. The deny list is the spellings .kit/1st.md forbids, and 1st.md names the desk
spellings too. kit check compares files, not digests; docs/ is packed and placed nowhere; the
installed-copies table has .claude/CLAUDE.md; the gate's steps are described as they are; kit
issue's sweep is the one change it makes to the desk; the hook names and never quotes. The rule
files are held to what this repository does: the bash shape allows a comment paragraph and names
1st.sh's helpers, the error rule asks for a remedy where there is one, dry-run is for sweeps that
remove work, the just rule exempts the help pair and sends long bodies to a script, the markdown
rule exempts AGENTS.md and scopes "names no repository" to delivered files, the YAML rule scopes
Shape and Steps to workflows and asks for a summary where a reader looks, and json and gitignore
read as imperatives. The README opens on what the kit is, lists the five checks, takes the kit in
bullets, documents KIT_BASE, and says where this repository's own sections begin. The release
workflows write their refusals and verdicts to the step summary.

Not applied: the Homebrew tap section, which infrastructure#459 provisions, and the module inventory
in 1st.md, which a consumer reads where the docs are not delivered. The README title keeps its
bold letters, which spell the acronym.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/settings.json                         |  10 +-
 .github/workflows/kit-ci.yml                  |  18 +-
 .github/workflows/release.yml                 |  24 +-
 .github/workflows/retire-pre-releases.yml     |   5 +-
 .kit/1st.md                                   |  28 +-
 .kit/manifest                                 |  18 +-
 .kit/rules/bash.md                            |  11 +-
 .kit/rules/gitignore.md                       |   2 +-
 .kit/rules/json.md                            |   4 +-
 .kit/rules/just.md                            |   5 +-
 .kit/rules/markdown.md                        |   7 +-
 .kit/rules/yaml.md                            |   9 +-
 .markdownlint.jsonc                           |   4 +-
 AGENTS.md                                     |  17 +-
 README.md                                     | 128 ++++----
 bin/1st.sh                                    |   5 +-
 bin/context.sh                                |  13 +-
 bin/gh.sh                                     |  42 ++-
 bin/git.sh                                    |  54 ++--
 bin/kit                                       |  15 +-
 bin/kit-check.sh                              |  13 +-
 bin/kit-gate.sh                               |  20 +-
 bin/kit-install.sh                            |  24 +-
 bin/kit-module.sh                             |  37 ++-
 bin/kit-update.sh                             |  84 ++---
 bin/release.sh                                | 292 ++++++++++++------
 bin/status.sh                                 |  72 +++--
 docs/architecture.md                          |  55 ++--
 docs/context.md                               |  23 +-
 docs/modules.md                               |  17 +-
 justfile                                      |   5 +-
 lefthook.yml                                  |  11 +-
 modules/ci/docs/README.md                     |   9 +-
 .../repo/.github/workflows/kit-ci.yml         |  18 +-
 modules/claude/docs/README.md                 |  15 +-
 .../claude/files/repo/.claude/settings.json   |  10 +-
 modules/claude/module.yml                     |   2 +-
 modules/kit/docs/README.md                    |   2 +-
 modules/kit/files/repo/.kit/1st.md            |  28 +-
 modules/kit/files/repo/.kit/rules/bash.md     |  11 +-
 .../kit/files/repo/.kit/rules/gitignore.md    |   2 +-
 modules/kit/files/repo/.kit/rules/json.md     |   4 +-
 modules/kit/files/repo/.kit/rules/just.md     |   5 +-
 modules/kit/files/repo/.kit/rules/markdown.md |   7 +-
 modules/kit/files/repo/.kit/rules/yaml.md     |   9 +-
 modules/module.schema.json                    |   4 +-
 tests/context.bats                            |  19 +-
 tests/gate.bats                               |  24 +-
 tests/kit.bats                                | 101 +++++-
 tests/linked.bats                             |  24 ++
 tests/lint.bats                               |   4 +-
 tests/rebase.bats                             |   6 +-
 tests/release.bats                            |   4 +-
 tests/status.bats                             |  16 +-
 tests/tidy.bats                               |  26 +-
 55 files changed, 854 insertions(+), 568 deletions(-)
 create mode 100644 tests/linked.bats

diff --git a/.claude/settings.json b/.claude/settings.json
index 5beeca9..cca6c4b 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -14,13 +14,17 @@
   },
   "permissions": {
     "deny": [
+      "Bash(git rebase *)",
+      "Bash(git worktree add *)",
+      "Bash(git checkout -b *)",
+      "Bash(git switch -c *)",
+      "Bash(git worktree remove *)",
+      "Bash(git branch -D *)",
       "Bash(git checkout main *)",
       "Bash(git switch main *)",
-      "Bash(git rebase *)",
       "Bash(git reset --hard *)",
       "Bash(git push --force *)",
-      "Bash(git push -f *)",
-      "Bash(git worktree remove --force *)"
+      "Bash(git push -f *)"
     ]
   }
 }
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index a835c42..dd17640 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -1,14 +1,14 @@
 # kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires. Each step is one kit command, so what the runner does
-# is what a desk can do: `kit gate` runs the root justfile's ci recipe and reports a missing one as a skip,
-# `kit check` holds every delivered file to the pinned release, and `kit linked` refuses a pull request not linked
-# to an open issue of this repository under Development. The last two run even when an earlier step refused, so
-# one run reports every finding.
+# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. After
+# a step that confirms kit is on PATH, three checks, each one kit command, so what the runner does a desk can do:
+# `kit gate` runs the root justfile's ci recipe and refuses when there is none, `kit check` holds every delivered
+# file to the pinned release, and `kit linked` refuses a pull request not linked to an open issue of this
+# repository under Development. The last two run even when an earlier step refused, so one run reports every
+# finding.
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. Rendered from a template: the
-# job runs on the ci_runner answer, ubuntu-latest unless .kit/answers says otherwise.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner answer.
 #
 # see: .kit/1st.md
 
@@ -37,7 +37,9 @@ jobs:
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
 
       - name: kit-on-path
-        run: command -v kit >/dev/null || { echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'; exit 1; }
+        run: |
+          command -v kit >/dev/null && exit 0
+          echo '::error::pin "github:empowerite/kit" in mise.toml; kit is not on PATH' && exit 1
 
       - name: gate
         run: kit gate
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e208617..f7f4101 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,10 +33,14 @@ jobs:
         run: |
           set -o errexit -o nounset -o pipefail
           tag_version=${GITHUB_REF_NAME#v}
+          refuse() {
+            echo "::error::$1"
+            printf '### ❌ %s\n' "$1" | tee --append "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          }
           if [[ ! "${tag_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
           then
-            echo "::error::${GITHUB_REF_NAME} is not a version tag; a release is v<major>.<minor>.<patch>, a pre-release the same with -<suffix>"
-            exit 1
+            refuse "${GITHUB_REF_NAME} is not a version tag: v<major>.<minor>.<patch>, -<suffix> for a pre-release"
           fi
           echo "✅ ${GITHUB_REF_NAME} is a version tag."
 
@@ -47,15 +51,18 @@ jobs:
           default_branch=$(jq --raw-output '.repository.default_branch' "${GITHUB_EVENT_PATH}")
           on_main=false
           git merge-base --is-ancestor "${GITHUB_SHA}" "origin/${default_branch}" && on_main=true
+          refuse() {
+            echo "::error::$1"
+            printf '### ❌ %s\n' "$1" | tee --append "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          }
           if [[ "${tag_version}" == *-* && "${on_main}" == true ]]
           then
-            echo "::error::${GITHUB_REF_NAME} is a pre-release tag on ${default_branch}; a pre-release is tagged on a branch commit, and a release on ${default_branch} carries no suffix"
-            exit 1
+            refuse "${GITHUB_REF_NAME} is a pre-release tag on ${default_branch}; tag a pre-release on a branch commit"
           fi
           if [[ "${tag_version}" != *-* && "${on_main}" == false ]]
           then
-            echo "::error::${GITHUB_REF_NAME} is not on ${default_branch}; a release is tagged on ${default_branch}, and a branch commit takes a pre-release tag with a -<suffix>"
-            exit 1
+            refuse "${GITHUB_REF_NAME} is not on ${default_branch}; a release is tagged there, a pre-release has a suffix"
           fi
           echo "✅ ${GITHUB_REF_NAME} is on the right side of ${default_branch} (on it: ${on_main})."
 
@@ -72,11 +79,12 @@ jobs:
           printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
           tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
           sha256sum "kit-${version}.tar.gz" > "kit-${version}.tar.gz.sha256"
-          notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\nThen, in the repository: kit install\n' "${version}")
+          notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\n' "${version}"
+            printf 'Then, in the repository: kit install\n')
           flags=()
           [[ "${version}" == *-* ]] && flags+=(--prerelease)
           gh release create "${GITHUB_REF_NAME}" "kit-${version}.tar.gz" "kit-${version}.tar.gz.sha256" \
             --title "kit ${version}" --notes "${notes}" "${flags[@]}"
-          echo "✅ Released kit ${version}."
+          printf '✅ Released kit %s.\n' "${version}" | tee --append "${GITHUB_STEP_SUMMARY}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
index a6d2ecd..e512c1b 100644
--- a/.github/workflows/retire-pre-releases.yml
+++ b/.github/workflows/retire-pre-releases.yml
@@ -51,7 +51,8 @@ jobs:
             gh release delete "${tag}" --cleanup-tag --yes
             echo "retired ${tag}: no branch reaches ${commit:0:7} since ${deleted} was deleted"
             retired=$(( retired + 1 ))
-          done < <(gh release list --limit 1000 --json tagName,isPrerelease --jq '.[] | select(.isPrerelease) | .tagName')
-          echo "✅ Retired ${retired} pre-release(s)."
+          done < <(gh release list --limit 1000 --json tagName,isPrerelease \
+            --jq '.[] | select(.isPrerelease) | .tagName')
+          printf '✅ Retired %s pre-release(s).\n' "${retired}" | tee --append "${GITHUB_STEP_SUMMARY}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/1st.md b/.kit/1st.md
index 0852482..ca4b942 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -27,7 +27,7 @@ reaches `main` only through a merged pull request.
 2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
    pull request. It never switches the checkout it is run from.
 3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`. `kit rebase`
-   brings the branch up to date with `main` and pushes it.
+   brings the branch up to date with the default branch and pushes it.
 4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
    and how, and what was left out and why.
 5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
@@ -35,13 +35,15 @@ reaches `main` only through a merged pull request.
 
 ## Spellings an agent uses
 
-Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. The rule runs inside
-it, and a harness that can refuse the raw spelling does.
+Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. Each kit spelling
+carries the check its rule requires, and a harness with a deny list refuses the raw git spelling.
 
 - `kit rebase`, never `git rebase`. It refuses the root checkout and the default branch, and otherwise rebases the
-  worktree's branch onto `origin/main` and pushes it.
+  worktree's branch onto the default branch at origin and pushes it.
 - `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
 - `kit tidy`, never `git worktree remove` or `git branch -D`.
+- The desk is never switched or reset by an agent: `git checkout main`, `git switch main`, `git reset --hard`,
+  and `git push --force` are refused as well.
 
 The human at the desk is not bound by this; the root checkout is theirs.
 
@@ -54,7 +56,8 @@ the design is written, the issue is the deliverable, and the loop above starts f
 
 A worker is whoever implements one issue in the worktree that issue names.
 
-1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints `<N>-`.
+1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints a branch name
+   beginning `<N>-`.
 2. Do every command from there. Never touch the repository root checkout.
 3. Never run `kit issue`, make a branch, or make a worktree. Those were done before the handoff.
 4. Implement what the issue asks and nothing beside it.
@@ -85,21 +88,20 @@ harness holds a copy of a rule; this call is how every harness, and every person
 
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
 release version, the active modules, and a checksum per delivered file. The release, where it is installed,
-carries the machinery, reached through the `kit` command on `PATH`. Everything the release delivers is a module,
-and a repository activates the modules it takes: `kit install claude`, or `kit module add claude` later, and
-`kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning only the entries
-it writes; everything else is copied as it is.
+carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
+`kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
+delivers is a module, and a repository activates the modules it takes: `kit install claude`, or `kit module add
+claude` later, and `kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning
+only the entries it writes; everything else is copied as it is.
 
-- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled
-  that way and no other.
 - `kit`: this file and the rules, discovered through `kit context`.
 - `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
   refuses a pull request not linked to an open issue.
 - `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
-  importing `AGENTS.md`, so it is read in every case; seven deny rules merged into `.claude/settings.json`; and a
-  hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
+  importing `AGENTS.md`, so it is read in every case; the deny list above merged into `.claude/settings.json`; and
+  a hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/manifest b/.kit/manifest
index 82a69d5..95b2052 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -2,13 +2,13 @@
 version unreleased
 modules kit ci claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
-86563533cd11f87831320d57b24d68d83c8d3a47382b09afeb71f5ee46e93584  .claude/settings.json
-972303cda70ea028bc266e64a56dc44bbb1689ba11e4023fd88173bbc11670fb  .github/workflows/kit-ci.yml
-6a4818d08c59d04d47533ca22cd1da112050fb07a7c604e684d1431ceca73ae3  .kit/1st.md
+deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
+cb71018c09692cca80de7212de73fd7460a60ec523bff9b3c150ce169d1c6eb8  .github/workflows/kit-ci.yml
+db619b465a7962c55205582fc5e7a8a54378a554114c45f752b6f8fb58344cf4  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
-6f1101c9b19bfbe2d42d6e602e92d0df4dc650a4a04ccbd06c5a03a5e6e5edc2  .kit/rules/bash.md
-0eedef778e1cdae63c731eec7a08055820726192006fba2148be7421535a22d5  .kit/rules/gitignore.md
-1e45ffbcca4dbcbd295e992bfa5874ffa9537b6f89911bf22608aa5785c54346  .kit/rules/json.md
-f2610c647eb99c3951cfb2e079c8d2a19ea0ddd03bdb4cbf3dbfea89b414d3da  .kit/rules/just.md
-15e2bc949cf1c034140989fbf00ebc39dc6b719eb1f87f88ac4c77ff3d37b549  .kit/rules/markdown.md
-03c1e6962c59627d3de12b57f7c6d682c5aea58fb9336613bb66ef6fd5145985  .kit/rules/yaml.md
+8c512e3f5951b5263c140500fb2494c45f92394b44ec643cc8d6475736f5ab11  .kit/rules/bash.md
+17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
+693815dcde0979638e20f021a6e879e5a3cc1420374f1d1329fc92d936e3461d  .kit/rules/json.md
+9a32591381c47fbb449a7b1f2ab900911a18901cbec3e768663db1171c6a9262  .kit/rules/just.md
+ea453a4dc6e1146527e51079cf1cefb0a70a4ca3e8e9151cc192daa956e592de  .kit/rules/markdown.md
+642e5d8618c0bc7810aa8b19bc63b68735811c3e33737e864fdf105c06298754  .kit/rules/yaml.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index e04e9b0..2d23371 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -14,7 +14,8 @@ workflows.
 ## Shape
 
 1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
-   rule of dashes to column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+   rule of dashes to column 120, a blank line, and an optional comment paragraph, then
+   `set -o errexit -o nounset -o pipefail`.
 2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
    would change the caller's.
 3. The file closes with the same rule of dashes.
@@ -31,17 +32,19 @@ workflows.
 6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
 8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
-   loader's own verbs are the exception and stay bare: `use`, `info`, `step`, `ok`, `section`, `warn`, `error`.
+   loader, `1st.sh`, is the exception: its verbs stay bare, `use`, `info`, `step`, `ok`, `section`, `warn`,
+   `error`, and `summary`, and its helpers are the `out:` and `guard:` families.
 9. A function private to one executed script is bare kebab-case.
 
 ## Behavior
 
-1. An error message is one line, names the remedy first, and is the same wherever the same condition arises.
+1. An error message is one line, names the remedy where there is one, and is the same wherever the same
+   condition arises.
 2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
 3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
 4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
 5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
-   to do, and a `--dry-run` where the mutation is a sweep.
+   to do, and a `--dry-run` where the mutation removes work, as a sweep of worktrees or branches does.
 6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
 7. shellcheck passes with no directive, or the directive carries the reason on the same line.
 
diff --git a/.kit/rules/gitignore.md b/.kit/rules/gitignore.md
index 7465b65..f1278c4 100644
--- a/.kit/rules/gitignore.md
+++ b/.kit/rules/gitignore.md
@@ -23,7 +23,7 @@ Applies to `.gitignore` at any depth.
 2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
    repository.
 3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
-4. `worktrees/` is ignored at the root: it is where the loop checks out a branch per issue.
+4. Ignore `/worktrees/` at the root: it is where the loop checks out a branch per issue.
 
 ## Adding one
 
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
index 692c8aa..f89871b 100644
--- a/.kit/rules/json.md
+++ b/.kit/rules/json.md
@@ -18,8 +18,8 @@ Applies to `*.json` and `*.jsonc`.
 ## Settings
 
 1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
-2. A tool's settings file that the kit writes into is merged by key. The kit owns only the keys and entries
-   it writes, and anything else in the file is the repository's.
+2. Do not edit an entry the kit wrote in a merged settings file; change it through a release and `kit update`.
+   Everything else in the file is the repository's to edit.
 
 ## Comments
 
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index 69f6620..af77933 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -41,11 +41,12 @@ applies to it as well.
 
 ## Recipes
 
-1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
+1. Every recipe but the default-and-help pair carries `[doc("<emoji> <short, action-first description>")]`.
+   Related recipes share an emoji.
 2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
    recipe does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
-4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
+4. A body says what runs. Logic longer than a dozen lines lives in a bash script the body calls.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
    variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
    `${name}` and nothing else.
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index d830ce3..7afc056 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -33,7 +33,8 @@ Applies to `*.md`.
 2. Balance the wrap: no line, in particular the last, reads as a stub.
 3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
 4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
-5. Headings are ATX (`#`). One `#` heading per file, at the top.
+5. Headings are ATX (`#`). One `#` heading per file, at the top; `AGENTS.md` is the exception, opening with the
+   sentence a harness reads first.
 6. Fenced code blocks declare a language and have a blank line on each side.
 7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
 
@@ -42,7 +43,7 @@ Applies to `*.md`.
 1. Use inline links with descriptive text, never a bare URL in angle brackets.
 2. Use the same anchor text every time the same URL appears in a file.
 3. When a label and the link text would say the same thing, make the label the link.
-4. A relative link resolves from the file that carries it, and it resolves: a check reads them.
+4. A relative link resolves from the file that carries it, and it resolves.
 
 ## Files
 
@@ -50,4 +51,4 @@ Applies to `*.md`.
 2. A file says what its subject is in its first paragraph, before how to use it.
 3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
    what the repository is.
-4. No file names another repository as the source of a rule.
+4. A delivered file names no repository as the source of a rule.
diff --git a/.kit/rules/yaml.md b/.kit/rules/yaml.md
index 3e5795c..69993c7 100644
--- a/.kit/rules/yaml.md
+++ b/.kit/rules/yaml.md
@@ -6,7 +6,8 @@ paths:
 ---
 # YAML
 
-Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
+Applies to `*.yml` and `*.yaml`. Shape and Steps apply to GitHub Actions workflows, under `.github/workflows/`;
+Comments apply to every YAML file.
 
 ## Shape
 
@@ -23,9 +24,9 @@ Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
 1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
 2. A step has a `name` that is the policy it enforces, in kebab-case.
 3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>`, writes `### ❌ <Message>` and a remedy to `${GITHUB_STEP_SUMMARY}`,
-   and returns non-zero. The remedy is the action to take, with a link that is that action.
-5. A pass writes one `✅` line to the summary.
+4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
+   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
+5. A step whose verdict a reader looks for writes one `✅` line to the summary.
 6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
 7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
 
diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
index 38f7fc7..abb6244 100644
--- a/.markdownlint.jsonc
+++ b/.markdownlint.jsonc
@@ -13,8 +13,8 @@
   // MD013 line-length: the 120-column ceiling the markdown rule sets; fenced code and tables do not wrap.
   "MD013": { "line_length": 120, "code_blocks": false, "tables": false },
 
-  // MD041 first-line-heading: AGENTS.md opens with the `@.kit/1st.md` import, and a delivered file opens with its
-  // notice; the title follows.
+  // MD041 first-line-heading: AGENTS.md opens with the sentence a harness reads first, and a delivered file opens
+  // with its notice; the title follows.
   "MD041": false,
 
   // MD060 table-column-style: the markdown rule asks for ` | ` around each pipe and nothing about column widths,
diff --git a/AGENTS.md b/AGENTS.md
index e4d6a35..9c4c5db 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,14 +3,11 @@ repository trustworthy. This repository is the kit's own source, and uses it.
 
 ## This repository's own rules
 
-- The release is `bin/` and `modules/`. Everything in it is written for a
-  consumer: no file names a consumer, a person, or another repository as the source of a rule.
-- A release is the tag `v<version>` on a commit on `main`; a pre-release is `v<version>-<suffix>` on a commit that is
-  not on `main`. The tag is the version: no file carries it, the workflow stamps it into the packed kit, and a
-  published release is immutable, so a tag is never reused. A release is permanent; a pre-release is retired when
-  the branch it was tagged on is deleted.
-- `.kit/`, `.github/workflows/kit-ci.yml`, and `.claude/settings.json` are this repository's installed copies of its
-  own kit, written by `just refresh` from `modules/`; see [README.md](README.md) § Maintaining. Edit the source; the
-  pre-commit hook refreshes the copies into the same commit, and a desk without the hook runs `just refresh` and
-  commits both.
+- The release is `bin/` and `modules/`. Everything in it is written for a consumer: no file names a consumer, a
+  person, or another repository as the source of a rule.
+- Releases and pre-releases: [README.md](README.md) § Release.
+- `.kit/`, `.github/workflows/kit-ci.yml`, `.claude/CLAUDE.md`, and `.claude/settings.json` are this repository's
+  installed copies of its own kit, written by `just refresh` from `modules/`; see [README.md](README.md)
+  § Maintaining. Edit the source; the pre-commit hook refreshes the copies into the same commit, and a desk
+  without the hook runs `just refresh` and commits both.
 - `just ci` is the gate; the justfile says what it runs.
diff --git a/README.md b/README.md
index a1f8db6..0f1796e 100644
--- a/README.md
+++ b/README.md
@@ -3,31 +3,36 @@
 Do you trust your agents? They were trained on the whole of what people have written, and that includes every
 shortcut anyone ever took: the "done" that was not, the test that was skipped and reported as passing, the rebase
 that quietly rewrote a colleague's branch. An agent is a tireless new colleague who has read everything and holds
-none of your house rules, unless you put them where it looks.
-
-kit is the house rules, put where agents look, and the checks that hold agents to them, as a versioned release any
-repository can take and keep taking. The rules are the smaller part. The point is verification that does not depend on
-anyone's word: a delivered CI job that refuses a pull request without a linked open issue, `kit check` holding every
-delivered file to its release, a pre-commit hook that runs the linters over what is staged, a deny list that refuses
-the spellings the rules forbid, and `kit status` showing what every pull request's checks said. The text is what those
-checks hold the work against: the entry file an agent reads first, a rule file per kind of file, the root checkout
-kept as the human's desk, and the one command no harness provides, which turns an issue into a worktree with a draft
-pull request. A tag on `main` publishes a release. A repository pins it, installs it, and keeps rules of its own
-beside it. The design is [#1](https://github.com/empowerite/kit/issues/1), and the entry file every agent reads is
-[.kit/1st.md](.kit/1st.md).
+none of your house rules, unless you put them where it looks. kit is the house rules, put where agents look, and
+the checks that hold agents to them, as a versioned release any repository can take and keep taking.
+
+The rules are the smaller part. The point is verification that does not depend on anyone's word:
+
+- a delivered CI job that refuses a pull request without a linked open issue, and refuses to pass a gate that did
+  not run;
+- `kit check`, which holds every delivered file to its release;
+- a pre-commit hook that runs the linters over what is staged;
+- a deny list that refuses the spellings the rules forbid;
+- `kit status`, which shows what every pull request's checks said.
+
+The text those checks hold the work against is the entry file an agent reads first and a rule file per kind of
+file. With it come the root checkout kept as the human's desk, and `kit issue`, the one command no harness
+provides, which turns an issue into a worktree with a draft pull request. A tag on `main` publishes a release. A
+repository pins it, installs it, and keeps rules of its own beside it. The design is
+[#1](https://github.com/empowerite/kit/issues/1) and [#4](https://github.com/empowerite/kit/issues/4), and the
+entry file every agent reads is [.kit/1st.md](.kit/1st.md).
 
 ## Why a release, and not a copy
 
-A copy drifts. Six repositories with six copies of the same rules have six sets of rules within a month, and no
-one can say which is current. A release is pinned, so a repository knows which rules bind it; updated, so a
-change to the rules reaches every repository as a pull request that bumps a version; and checked, so `kit check`
-fails the build when a delivered file was edited in place. The rules a repository adds live beside the delivered
-ones, in its own files, and survive every update.
+A copy drifts. A release is pinned, so a repository knows which rules bind it; updated, so a change reaches every
+repository as a pull request that bumps a version; and checked, so `kit check` fails the build when a delivered
+file was edited in place. The rules a repository adds live beside the delivered ones, in its own files, and
+survive every update.
 
 ## Install
 
-The `kit` command is a release: a tarball holding `bin/`, `modules/`, and a stamped `version`. Take it whichever way the
-repository takes its other tools.
+The kit ships as a release: a tarball holding `bin/`, `modules/`, and a stamped `version`. Take it whichever way
+the repository takes its other tools.
 
 With mise, pin it in `mise.toml` and the version is part of the repository:
 
@@ -57,37 +62,43 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
 
 ## Take the kit
 
-In the repository, install it and point `AGENTS.md` at it, in prose, the same sentence for every agent:
-
-```sh
-kit install claude
-```
-
-```markdown
-Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
-repository trustworthy.
-```
-
-The rest of `AGENTS.md` is yours. Everything the kit delivers is a module, and `install` activates the default ones,
-`kit`, `lefthook`, and `ci`, plus those named: `claude` is the adapter for Claude Code, which reads `AGENTS.md` only
-as a fallback, when no `CLAUDE.md` is present and its configuration allows, so the module places `.claude/CLAUDE.md`
-importing `AGENTS.md` and Claude reads what everyone else reads in every case. A repository with no adapter still
-binds every agent that reads `AGENTS.md`. Commit what it wrote, keep a `ci` recipe in the root justfile for the
-delivered `CI` job to run, and take the pre-commit linters by pinning `lefthook`, putting `extends:
-[.kit/lefthook.yml]` in `lefthook.yml`, and running `lefthook install` once per clone. `kit module list`, `kit module
-add`, and `kit module remove` show and change the set later, and [docs/modules.md](docs/modules.md) describes a
-module. An agent asks `kit context <path>` which rules govern a file before it creates or changes it;
+- In the repository, run `kit install`. It activates the default modules, `kit`, `lefthook`, and `ci`, and writes
+  their files and `.kit/manifest`. Add the Claude Code adapter with `kit install claude`, or later with
+  `kit module add claude`.
+- Point `AGENTS.md` at the entry file, in prose, the same sentence for every agent:
+
+  ```markdown
+  Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
+  repository trustworthy.
+  ```
+
+  The rest of `AGENTS.md` is yours.
+- Commit what `install` wrote.
+- Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it and refuses when there is none.
+- Take the pre-commit linters: pin `lefthook`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run
+  `lefthook install` once per clone.
+
+`claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is
+present. The module places `.claude/CLAUDE.md` importing `AGENTS.md`, so Claude reads what every agent reads in
+every case. A repository with no adapter still binds every agent that reads `AGENTS.md`. `kit module list`,
+`kit module add`, and `kit module remove` show and change the set, and [docs/modules.md](docs/modules.md)
+describes a module.
+
+Before an agent creates or changes a file, it asks `kit context "${path}"` which rules govern it;
 [docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
 
-To move to a new release, bump the pin or reinstall, then run `kit update`: a delivered file you left alone is
-replaced, one you edited is three-way merged with the previous release as the base, which `update` fetches from
-GitHub if it is not already on the machine, and your own deny entries and settings keys stay. `kit check` fails,
-locally and in `CI`, when a delivered file differs from the pinned release.
+To move to a new release, bump the pin or reinstall, then run `kit update`. A delivered file you left alone is
+replaced. One you edited is three-way merged with the previous release as the base, which `update` fetches from
+GitHub when it is not on the machine; `KIT_BASE` names a copy of it where that fetch is not possible. Your own
+deny entries and settings keys stay. `kit check` fails, locally and in `CI`, when a delivered file differs from
+the pinned release.
 
 ## Setup
 
-This repository uses its own kit, and its tools come from mise. Every commit is signed, and the branch ruleset
-refuses one that is not. If you have no signing key GitHub verifies, make one and register it, following
+The sections from here on are about working on this repository, the kit's own source, which uses its own kit.
+
+Its tools come from mise. Every commit is signed, and the branch ruleset refuses one that is not. If you have no
+signing key GitHub verifies, make one and register it, following
 [generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
 and [adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account).
 Then, once per clone, with the key's id in `signing_key`:
@@ -102,7 +113,8 @@ lefthook install
 ```
 
 `MISE_ENV=desk` belongs in your shell profile: it makes mise read `mise.desk.toml`, the tools only a desk runs,
-on top of `mise.toml`; the delivered `CI` job sets `MISE_ENV=ci` the same way for `mise.ci.toml`.
+on top of `mise.toml`. The delivered `CI` job sets `MISE_ENV=ci` the same way, for a `mise.ci.toml` where a
+repository has one.
 
 ## Getting started
 
@@ -120,13 +132,9 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 ## Maintaining
 
-This repository is both the source of the kit and a consumer of it. The release is the checkout: `modules/<name>/`
-is what a consumer activating that module gets, its `files/repo/` mirrored at the consumer's root and its
-`templates/repo/` rendered from the consumer's answers first; `bin/` is the machinery, `bin/kit` dispatching to one executable
-`bin/kit-<verb>.sh` per verb, each sourcing the bash modules beside it; and `docs/` with each module's `docs/` is
-the documentation. [docs/modules.md](docs/modules.md) is the module format.
-
-[docs/architecture.md](docs/architecture.md) is the shape of the whole, with its figures.
+The release is the checkout: `bin/` is the machinery, `modules/` is everything delivered, and `docs/` with each
+module's `docs/` is the documentation. [docs/architecture.md](docs/architecture.md) is the shape of the whole, with
+its figures, and [docs/modules.md](docs/modules.md) is the module format.
 
 The installed copies are written by `bin/kit install` and not edited by hand:
 
@@ -135,14 +143,15 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.kit/1st.md`, `.kit/rules/` | `modules/kit/files/repo/.kit/` |
 | `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
 | `.github/workflows/kit-ci.yml` | `modules/ci/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
+| `.claude/CLAUDE.md` | `modules/claude/files/repo/.claude/CLAUDE.md` |
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
-A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the
-pre-commit hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk
-without the hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names
-any installed copy that no longer matches its source. Each delivered text file says in its header that it is
-delivered by kit; `settings.json` cannot, so this table is its notice.
+A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the pre-commit
+hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk without the
+hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names any installed
+copy that does not match its source. Each delivered text file says in its header that it is delivered by kit;
+`settings.json` cannot, so this table is its notice.
 
 ## Release
 
@@ -154,4 +163,5 @@ published release is immutable, so a tag is never reused. The workflow packs `bi
 `main`, and a pre-release tag on `main`. A release is permanent. A pre-release is retired, tag and all, when the
 branch it was tagged on is deleted and no other branch reaches its commit.
 
-Repository policy is managed by Terraform; see: empowerite/infrastructure/terraform/projects/kit/main.tf
+The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure), under
+`terraform/projects/kit`.
diff --git a/bin/1st.sh b/bin/1st.sh
index 2976763..0e97a45 100644
--- a/bin/1st.sh
+++ b/bin/1st.sh
@@ -4,8 +4,8 @@
 #
 # Sourced by every verb, bin/kit-<verb>.sh, which bin/kit dispatches to with kit_root exported. It defines
 # functions only and sets no shell option, so the caller's options stand. A module is a sourced <module>.sh
-# beside this file, loaded once with `use <module>` by the verb or module that needs it; there is no other way
-# in. A verb is an executable kit-<verb>.sh beside it.
+# beside this file, loaded once with `use <module>` by the verb or module that needs it. A verb is an executable
+# kit-<verb>.sh beside it.
 #
 # Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
 # NO_COLOR is set. Under GitHub Actions, warn and error also emit the matching workflow command.
@@ -41,6 +41,7 @@ else
   declare -gr out_color=0
 fi
 
+# out:sgr <code> prints the escape for one SGR code when color is on, and nothing otherwise.
 out:sgr() {
   (( out_color )) && printf '\x1b[%sm' "$1"
   return 0
diff --git a/bin/context.sh b/bin/context.sh
index 9529455..a57fd24 100644
--- a/bin/context.sh
+++ b/bin/context.sh
@@ -20,13 +20,14 @@ context:log-path() {
   printf '%s/kit/context.log\n' "$(git rev-parse --path-format=absolute --git-common-dir)"
 }
 
-# context:relative <path> prints <path> relative to the repository root. A relative path is taken from the current
-# directory. The nearest directory of the path that exists is resolved physically, as git reports the root, so a
-# path through a symlinked directory, or to a file not yet created, still cuts at the root.
+# context:relative <path> prints <path> relative to the repository root. A relative path is taken from the
+# directory the command was typed in, which bin/kit exports as kit_invoked_in before it moves to the root. The
+# nearest directory of the path that exists is resolved physically, as git reports the root, so a path through a
+# symlinked directory, or to a file not yet created, still cuts at the root.
 context:relative() {
   local path=$1 root dir rest
   root=$(git rev-parse --show-toplevel)
-  [[ "${path}" == /* ]] || path="${PWD}/${path}"
+  [[ "${path}" == /* ]] || path="${kit_invoked_in:-$(pwd -P)}/${path}"
   dir=${path%/*}
   rest=${path##*/}
   while [[ -n "${dir}" && ! -d "${dir}" ]]
@@ -39,7 +40,9 @@ context:relative() {
   printf '%s\n' "${path#"${root}"/}"
 }
 
-# context:glob-matches <path> <glob> is true when the repository-relative path matches the glob; ** is any depth.
+# context:glob-matches <path> <glob> is true when the repository-relative path matches the glob. ** stands for any
+# depth, and a lone * also crosses directories, as bash's [[ == ]] has it: *.md governs every depth, while a glob
+# with no wildcard, such as justfile, names one path.
 context:glob-matches() {
   local path=$1 glob=$2
   glob=${glob//\*\*\//*(*\/)}
diff --git a/bin/gh.sh b/bin/gh.sh
index 68177f0..21d7fcc 100644
--- a/bin/gh.sh
+++ b/bin/gh.sh
@@ -16,6 +16,11 @@
 #
 # Each step below prints its one result on stdout and talks on stderr, so gh:issue reads them in order.
 
+# gh:repo prints the repository this checkout resolves to, as owner/name, or fails.
+gh:repo() {
+  gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null
+}
+
 # gh:me prints the authenticated login. A revoked token passes `gh auth status`, so this is the real probe.
 gh:me() {
   local me
@@ -55,8 +60,10 @@ gh:assign() {
   do
     assignees=$(gh issue view "${n}" --json assignees --jq '[.assignees[].login] | join(" ")')
     [[ " ${assignees} " == *" ${me} "* ]] && continue
-    [[ -z "${assignees}" ]] || warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
-    gh issue edit "${n}" --add-assignee "${me}" >/dev/null 2>&1 || warn "#${n} could not be assigned to ${me}; assign it by hand."
+    [[ -z "${assignees}" ]] \
+      || warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
+    gh issue edit "${n}" --add-assignee "${me}" >/dev/null 2>&1 \
+      || warn "#${n} could not be assigned to ${me}; assign it by hand."
   done
 }
 
@@ -67,7 +74,8 @@ gh:issue-branch() {
   local number=$1 default_branch=$2 branch
   branch=$(gh pr list --state open --json headRefName \
     --jq "[.[] | select(.headRefName | test(\"^${number}-\"))] | .[0].headRefName // empty" 2>/dev/null || true)
-  [[ -n "${branch}" ]] || branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+  [[ -n "${branch}" ]] \
+    || branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
   if [[ -z "${branch}" ]]
   then
     step "Linking a branch to #${number} (gh issue develop)"
@@ -112,18 +120,18 @@ gh:worktree() {
 
 # gh:start-commit <worktree> <default-branch> <number> <title> gives the branch its first commit when it has
 # none: GitHub cannot open a pull request with nothing to compare. --only keeps the commit empty, so work already
-# staged in a reused worktree stays in the index.
+# staged in a reused worktree stays in the index. The subject follows the loop's shape, #<N> <area>: <subject>.
 gh:start-commit() {
   local wt=$1 default_branch=$2 number=$3 title=$4
   if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
   then
     step "Adding the start commit"
-    git -C "${wt}" commit --quiet --allow-empty --only --message "start: #${number} ${title}"
+    git -C "${wt}" commit --quiet --allow-empty --only --message "#${number} start: ${title}"
   fi
 }
 
-# gh:sweep-push <root> <message> stashes everything uncommitted at <root>, untracked files included, and prints the
-# stash's commit, which stays valid however the stash list shifts.
+# gh:sweep-push <root> <message> stashes everything uncommitted at <root>, untracked files included, and prints
+# the stash's commit, which stays valid however the stash list shifts.
 gh:sweep-push() {
   local root=$1 message=$2
   if ! git -C "${root}" stash push --include-untracked --message "${message}" >/dev/null
@@ -173,7 +181,8 @@ gh:link-secondaries() {
   body=$(gh pr view "${pr}" --json body --jq '.body // ""')
   for n in "$@"
   do
-    if ! grep --quiet --ignore-case --extended-regexp "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
+    if ! grep --quiet --ignore-case --extended-regexp \
+      "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
     then
       body="${body}"$'\n'"Closes #${n}"
       changed=true
@@ -191,8 +200,7 @@ gh:link-secondaries() {
 # count. On a runner the remedy also lands in the step summary.
 gh:linked-open-issue() {
   local number=$1 repo query refs n state issue_repo open=0 closes url remedy
-  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
-  url=$(gh repo view --json url --jq .url)
+  IFS=$'\t' read -r repo url < <(gh repo view --json nameWithOwner,url --jq '[.nameWithOwner, .url] | @tsv')
   remedy=$(printf '%s\n' \
     "Link an open issue of this repository under **Development** in [the sidebar](${url}/pull/${number}):" "" \
     "1. click the gear (⚙) beside **Development**" \
@@ -209,7 +217,8 @@ gh:linked-open-issue() {
   }'
   refs=$(gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --field number="${number}" \
     --raw-field query="${query}" \
-    --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[] | "\(.number) \(.state) \(.repository.nameWithOwner)"')
+    --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
+          | "\(.number) \(.state) \(.repository.nameWithOwner)"')
   if [[ -z "${refs}" ]]
   then
     error "pull request #${number} is not linked to any issue"
@@ -239,10 +248,14 @@ gh:linked-open-issue() {
   summary "✅ Linked to ${closes}."
 }
 
+# gh:issue [<number>…] is the issue on-ramp the file header describes: assign, link a branch, make the worktree,
+# push a start commit, sweep the desk's uncommitted work into the worktree, and open a draft pull request. Every
+# commit the loop makes is signed, so a desk without a signing key is refused before anything is written.
 gh:issue() {
   use git
-  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr
+  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr created
   me=$(gh:me) || return 1
+  guard:require signing-key || return 1
   if (( $# == 0 ))
   then
     if [[ ! -t 0 ]]
@@ -250,7 +263,8 @@ gh:issue() {
       error "usage: kit issue <issue-number> [<issue-number>…]"
       return 2
     fi
-    set -- "$(gh:issue-create)" || return
+    created=$(gh:issue-create) || return
+    set -- "${created}"
   fi
   for n in "$@"
   do
@@ -284,7 +298,7 @@ gh:issue() {
   fi
   wt=$(gh:worktree "${main_root}" "${branch}") || return
   git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null \
-    || warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a status or a commit"
+    || warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a commit"
   gh:start-commit "${wt}" "${default_branch}" "${primary}" "${title}"
   git -C "${wt}" push --quiet --set-upstream origin "${branch}"
   if [[ -n "${stash}" ]]
diff --git a/bin/git.sh b/bin/git.sh
index 3597230..e8a905a 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -1,33 +1,24 @@
 # shellcheck shell=bash
 # git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
-#
-# git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
-# detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
-# every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a
-# live worktree, a dirty worktree, a detached worktree whose commit nothing else reaches, or the worktree it
-# runs in. --dry-run says what a sweep would do and changes nothing.
-#
-# git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto
-# origin/<default> and pushes it with --force-with-lease. It refuses the root checkout, the human's desk, whatever
-# branch it has, and the default branch anywhere. On a conflict it aborts and leaves the worktree as it was.
 
 # git:default-branch [<path>] prints the default branch of the repository at <path>: origin/HEAD, else main.
 git:default-branch() {
   local branch
-  branch=$(git -C "${1:-.}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' || true)
+  branch=$(git -C "${1:-.}" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' \
+    || true)
   [[ -n "${branch}" ]] || branch=main
   printf '%s\n' "${branch}"
 }
 
-# git:main-root [<path>] prints the root of the main checkout, the first entry of the worktree list. worktrees/
-# lives under it whether the caller stands in the main checkout or in a linked worktree.
+# git:main-root [<path>] prints the root of the main checkout, under which worktrees/ lives, from the main
+# checkout or any linked worktree.
 git:main-root() {
-  git -C "${1:-.}" worktree list --porcelain | sed -n 's@^worktree @@p' | head -n 1
+  dirname "$(git -C "${1:-.}" rev-parse --path-format=absolute --git-common-dir)"
 }
 
-# git:worktrees prints "<path>\t<branch>\t<detached>" for every linked worktree under worktrees/; <branch> is
-# empty and <detached> is true for a detached checkout.
+# git:worktrees prints "<path>\t<detached>\t<branch>" for every linked worktree under worktrees/. <detached> is
+# true or false, and <branch> is empty for a detached checkout; the empty field is last so a tab read keeps it.
 git:worktrees() {
   local worktree_root path="" branch="" detached=false line
   worktree_root="$(git:main-root)/worktrees"
@@ -47,18 +38,12 @@ git:worktrees() {
         ;;
       ("")
         # git ends every record with a blank line; the printf below adds one so the last record ends too.
-        [[ "${path}" == "${worktree_root}"/* ]] && printf '%s\t%s\t%s\n' "${path}" "${branch}" "${detached}"
+        [[ "${path}" == "${worktree_root}"/* ]] && printf '%s\t%s\t%s\n' "${path}" "${detached}" "${branch}"
         path=""
     esac
   done < <(git worktree list --porcelain; printf '\n')
 }
 
-# git:pr-summary <branch> prints "<number>\t<Draft|Ready>" for the open pull request on <branch>, or nothing.
-git:pr-summary() {
-  gh pr list --head "$1" --state open --json number,isDraft \
-    --jq '.[0] | select(.number) | "\(.number)\t\(if .isDraft then "Draft" else "Ready" end)"' 2>/dev/null || true
-}
-
 # git:gone-branches prints every local branch whose upstream no longer exists.
 git:gone-branches() {
   git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/ | awk '$2 == "[gone]" { print $1 }'
@@ -120,6 +105,11 @@ git:tidy-worktree() {
   esac
 }
 
+# git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
+# detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
+# every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a
+# live worktree, a dirty worktree, a detached worktree whose commit nothing else reaches, or the worktree it
+# runs in. --dry-run says what a sweep would do and changes nothing.
 git:tidy() {
   local dry_run=false flag repo default_branch self_root found=false path branch detached
   local removed_worktrees=0 removed_branches=0 checked_out
@@ -135,8 +125,9 @@ git:tidy() {
         return 2
     esac
   done
+  use gh
   guard:require gh || return 1
-  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || true)
+  repo=$(gh:repo || true)
   if [[ -z "${repo}" ]]
   then
     error "this checkout does not resolve to a GitHub repository (run: gh repo view), so nothing is swept."
@@ -160,7 +151,7 @@ git:tidy() {
   fi
 
   section "worktrees whose pull request is merged or closed"
-  while IFS=$'\t' read -r path branch detached
+  while IFS=$'\t' read -r path detached branch
   do
     found=true
     if git:tidy-worktree "${path}" "${branch}" "${detached}" "${default_branch}" "${self_root}" "${dry_run}"
@@ -210,6 +201,10 @@ git:tidy() {
   fi
 }
 
+# git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto the
+# default branch at origin and pushes it with --force-with-lease. It refuses the root checkout, the human's desk,
+# whatever branch it has; the default branch anywhere; and a dirty worktree. On a conflict it aborts and leaves
+# the worktree as it was.
 git:rebase() {
   local worktree=${1:-.} branch default_branch
   branch=$(git -C "${worktree}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
@@ -220,7 +215,7 @@ git:rebase() {
   fi
   if [[ "$(git -C "${worktree}" rev-parse --show-toplevel)" == "$(git:main-root "${worktree}")" ]]
   then
-    error "refusing to rebase ${branch}: it is checked out at the root, the human's desk; work is rebased in its worktree"
+    error "refusing to rebase ${branch}: it is the root checkout, the human's desk; rebase in the branch's worktree"
     return 1
   fi
   default_branch=$(git:default-branch "${worktree}")
@@ -229,11 +224,16 @@ git:rebase() {
     error "refusing to rebase ${branch}: it is the default branch; it advances by: git pull --ff-only"
     return 1
   fi
+  if ! git:clean "${worktree}"
+  then
+    error "refusing to rebase ${branch}: the worktree has uncommitted changes; commit or stash them first"
+    return 1
+  fi
   section "kit rebase ${branch} onto origin/${default_branch}"
   git -C "${worktree}" fetch --quiet --prune origin
   if ! git -C "${worktree}" rebase --quiet "origin/${default_branch}"
   then
-    git -C "${worktree}" rebase --abort
+    git -C "${worktree}" rebase --abort 2>/dev/null || true
     error "${branch} conflicts with origin/${default_branch}; the rebase was aborted and the worktree is as it was"
     return 1
   fi
diff --git a/bin/kit b/bin/kit
index e4ab597..d398fb9 100755
--- a/bin/kit
+++ b/bin/kit
@@ -3,8 +3,10 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # The release is the directory above bin/, found through any symlink this file is reached by, as when Homebrew
-# links it into its own bin. This file resolves it, exports it as kit_root, and hands the verb its arguments.
-# Everything else, the usage text included, lives with the verb.
+# links it into its own bin. This file resolves it, exports it as kit_root, moves to the repository root so every
+# verb reads and writes the same paths wherever it was typed, and hands the verb its arguments. The directory it
+# was typed in is exported as kit_invoked_in for the verbs that take relative paths. Everything else, the usage
+# text included, lives with the verb.
 #
 # see: .kit/1st.md
 
@@ -16,8 +18,15 @@ then
   exit 1
 fi
 
+# readlink -f needs macOS 12.3 or later, the first with a GNU-compatible readlink; older macOS lacks it.
 kit_root=$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)
 export kit_root
+kit_invoked_in=$(pwd -P)
+export kit_invoked_in
+if repository=$(git rev-parse --show-toplevel 2>/dev/null)
+then
+  cd "${repository}"
+fi
 
 verb=${1:-help}
 case "${verb}" in
@@ -31,7 +40,7 @@ usage: kit <verb> [<argument>…]
   module <list|add|remove> [<module>…]
                         the modules this repository takes
   context <path>…       name the rules that govern a file, and record the ask
-  gate                  run the root justfile's ci recipe; a missing one is a skip, said so
+  gate                  run the root justfile's ci recipe, and refuse when there is none
   linked [<number>]     refuse a pull request not linked to an open issue of this repository
   issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index aaed143..908be00 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -2,8 +2,8 @@
 # kit-check - fail when a delivered file differs from the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Every path under the repository is checked. A path under home is checked where ~/.kit/manifest exists, that is,
-# on a desk that installed; a machine with none, such as a runner, is told so and the home base is skipped.
+# Every path under the repository is compared with the release's file. A path under home is compared where
+# ~/.kit/manifest exists, that is, on a desk that installed; a machine with none, such as a runner, is told so.
 #
 # see: bin/release.sh
 
@@ -19,7 +19,7 @@ then
 fi
 
 release:require-manifest
-read -r -a modules <<<"$(release:manifest-modules)"
+readarray -t modules < <(release:manifest-modules)
 version=$(release:manifest-version)
 release:render-all "${kit_root}" "${modules[@]}"
 findings=0
@@ -28,14 +28,13 @@ then
   error ".kit/manifest records kit ${version}, and the pinned release is $(release:version); run: kit update"
   findings=$(( findings + 1 ))
 fi
-# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
-for base in "${release_bases[@]}"
+for base in $(release:bases)
 do
   delivered=$(release:delivered "${kit_root}" "${base}" "${modules[@]}")
   [[ -n "${delivered}" ]] || continue
   if [[ "${base}" != repo && ! -f "$(release:manifest "${base}")" ]]
   then
-    info "${base}: nothing is installed under $(release:base-root "${base}") on this machine, so its paths were not checked"
+    info "${base}: nothing is installed under $(release:base-root "${base}") on this machine; not checked"
     continue
   fi
   while IFS=$'\t' read -r path src
@@ -65,7 +64,7 @@ do
 done
 if (( findings > 0 ))
 then
-  error "${findings} finding(s). A delivered file is changed by pinning a new release and running kit update, not in place."
+  error "${findings} finding(s). A delivered file changes by a new release and kit update, never in place."
   exit 1
 fi
 ok "kit ${version}, modules ${modules[*]:-none}: every delivered file matches the pinned release."
diff --git a/bin/kit-gate.sh b/bin/kit-gate.sh
index 5858004..0934986 100755
--- a/bin/kit-gate.sh
+++ b/bin/kit-gate.sh
@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
-# kit-gate - run the repository's gate, the root justfile's ci recipe, and say plainly when there is none (kit verb)
+# kit-gate - run the repository's gate, the root justfile's ci recipe, and refuse when there is none (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The delivered CI job's first step. A missing justfile or a justfile with no ci recipe is a skip, reported as a
-# skip, never as a pass; a justfile that cannot be read is a failure. On a runner, each outcome also lands in the
-# step summary.
+# The delivered CI job's first step. A gate that cannot run clears nothing: a missing justfile, a justfile with no
+# ci recipe, and a justfile that cannot be read are each refused, naming the remedy. On a runner, each outcome
+# also lands in the step summary.
 #
 # see: modules/ci/templates/repo/.github/workflows/kit-ci.yml
 
@@ -20,9 +20,9 @@ fi
 
 if [[ ! -f justfile ]]
 then
-  warn "there is no root justfile, so the gate was skipped"
-  summary "⚠️ The gate was skipped: there is no root justfile."
-  exit 0
+  error "add a root justfile with a ci recipe; there is none, so the gate cannot run"
+  summary "### ❌ The gate cannot run: there is no root justfile" "" "Add a root justfile with a \`ci\` recipe."
+  exit 1
 fi
 if ! recipes=$(just --summary 2>&1)
 then
@@ -32,9 +32,9 @@ then
 fi
 if ! tr ' ' '\n' <<<"${recipes}" | grep --quiet --line-regexp ci
 then
-  warn "the root justfile has no ci recipe, so the gate was skipped"
-  summary "⚠️ The gate was skipped: the root justfile has no ci recipe."
-  exit 0
+  error "add a ci recipe to the root justfile; it has none, so the gate cannot run"
+  summary "### ❌ The gate cannot run: the root justfile has no ci recipe" "" "Add a \`ci\` recipe to it."
+  exit 1
 fi
 just ci
 summary "✅ just ci passed."
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index 137e596..3835c38 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -3,7 +3,8 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # Activates the default modules and the named ones, with the modules they depend on, places what they deliver
-# under each base, and writes the manifests: .kit/manifest, and ~/.kit/manifest when a module delivers to home.
+# under each base, and writes the manifests. A different file already at a delivered path is refused, named, and
+# left alone, and no manifest is written until every path is clear.
 #
 # see: bin/release.sh
 
@@ -25,21 +26,20 @@ then
   error "run: kit update (this repository already carries kit $(release:manifest-version))"
   exit 1
 fi
-read -r -a defaults <<<"$(release:default-modules "${kit_root}" | paste -s -d ' ' -)"
-read -r -a modules <<<"$(release:resolve "${kit_root}" "${defaults[@]}" "$@" | paste -s -d ' ' -)"
+readarray -t defaults < <(release:default-modules "${kit_root}")
+readarray -t modules < <(release:resolve "${kit_root}" "${defaults[@]}" "$@")
 release:render-all "${kit_root}" "${modules[@]}"
 section "kit install $(release:version), modules: ${modules[*]}"
-# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
-for base in "${release_bases[@]}"
+refused=0
+for base in $(release:bases)
 do
-  while IFS=$'\t' read -r path src
-  do
-    [[ -n "${path}" ]] || continue
-    dest=$(release:dest "${base}" "${path}")
-    step "${dest}"
-    release:place "${src}" "${dest}"
-  done < <(release:delivered "${kit_root}" "${base}" "${modules[@]}")
+  release:place-all "${kit_root}" "${base}" "${modules[@]}" || refused=$(( refused + $? ))
 done
+if (( refused > 0 ))
+then
+  error "${refused} path(s) already hold a different file; move each aside, then run: kit install"
+  exit 1
+fi
 release:write-manifests "${modules[@]}"
 release:finish "${modules[@]}"
 
diff --git a/bin/kit-module.sh b/bin/kit-module.sh
index 1fd3556..78da8c7 100755
--- a/bin/kit-module.sh
+++ b/bin/kit-module.sh
@@ -19,9 +19,8 @@ case "${verb}" in
   (*) usage; exit 2
 esac
 release:require-manifest
-read -r -a active <<<"$(release:manifest-modules)"
+readarray -t active < <(release:manifest-modules)
 
-# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
 case "${verb}" in
   (list)
     for module in $(release:modules)
@@ -37,19 +36,24 @@ case "${verb}" in
     (( $# > 0 )) || { usage; exit 2; }
     guard:require tool:jq
     release:require-modules "${kit_root}" "$@"
-    read -r -a wanted <<<"$(release:resolve "${kit_root}" "${active[@]}" "$@" | paste -s -d ' ' -)"
+    readarray -t wanted < <(release:resolve "${kit_root}" "${active[@]}" "$@")
     release:render-all "${kit_root}" "${wanted[@]}"
     section "kit module add $*"
-    for base in "${release_bases[@]}"
+    refused=0
+    for base in $(release:bases)
     do
       while IFS= read -r path
       do
         [[ -n "${path}" ]] || continue
-        dest=$(release:dest "${base}" "${path}")
-        step "${dest}"
-        release:place "$(release:source-of "${kit_root}" "${base}" "${path}" "${wanted[@]}")" "${dest}"
+        release:place-new "$(release:source-of "${kit_root}" "${base}" "${path}" "${wanted[@]}")" \
+          "$(release:dest "${base}" "${path}")" "placed" || refused=$(( refused + 1 ))
       done < <(release:paths-beyond "${kit_root}" "${base}" "${active[*]}" "${wanted[*]}")
     done
+    if (( refused > 0 ))
+    then
+      error "${refused} path(s) already hold a different file; move each aside, then run: kit module add $*"
+      exit 1
+    fi
     release:write-manifests "${wanted[@]}"
     ok "modules: ${wanted[*]}"
     ;;
@@ -60,27 +64,28 @@ case "${verb}" in
     remaining=("${active[@]}")
     for module in "$@"
     do
-      if ! release:among "${module}" "${remaining[@]}"
-      then
-        step "${module}: not active"
-        continue
-      fi
-      read -r -a dependents <<<"$(release:dependents "${kit_root}" "${module}" "${remaining[@]}" | paste -s -d ' ' -)"
+      release:among "${module}" "${active[@]}" || step "${module}: not active"
+      readarray -t remaining < <(release:without "${module}" "${remaining[@]}")
+    done
+    # Dependents are judged against what stays, so the order the modules are named in does not matter.
+    for module in "$@"
+    do
+      readarray -t dependents < <(release:dependents "${kit_root}" "${module}" "${remaining[@]}")
       if (( ${#dependents[@]} > 0 ))
       then
         error "${module} cannot be removed while ${dependents[*]} depend(s) on it"
         exit 1
       fi
-      read -r -a remaining <<<"$(release:without "${module}" "${remaining[@]}" | paste -s -d ' ' -)"
     done
     release:render-all "${kit_root}" "${active[@]}"
     section "kit module remove $*"
-    for base in "${release_bases[@]}"
+    for base in $(release:bases)
     do
       while IFS= read -r path
       do
         [[ -n "${path}" ]] || continue
-        release:unplace "$(release:source-of "${kit_root}" "${base}" "${path}" "${active[@]}")" "$(release:dest "${base}" "${path}")"
+        release:unplace "$(release:source-of "${kit_root}" "${base}" "${path}" "${active[@]}")" \
+          "$(release:dest "${base}" "${path}")"
       done < <(release:paths-beyond "${kit_root}" "${base}" "${remaining[*]}" "${active[*]}")
     done
     release:write-manifests "${remaining[@]}"
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index c9e974e..67fa26a 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -2,13 +2,9 @@
 # kit-update - move the repository, and the home directory, to the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A file whose digest still matches its manifest, which records the previous release's own content, is replaced.
-# An edited one is three-way merged with the previous release as the base, which release:fetch finds or fetches.
-# A path the previous release did not deliver is written only where there is nothing, or the same thing, there.
-# A path the previous release delivered and this one does not is retired: removed when it is still the previous
-# release's own content, its entries taken out of a merged .json when the base is at hand, and otherwise left
-# with a warning. A template is rendered from the repository's answers in both releases before either is
-# compared. The home base is updated against ~/.kit/manifest the same way.
+# The previous release is the base of every merge. KIT_BASE names its root; the same release as the current
+# one is its own base; otherwise release:fetch finds or fetches it. A path left for lack of a base keeps the
+# manifest at the previous version, so the next run starts where this one stopped.
 #
 # see: bin/release.sh
 
@@ -25,30 +21,32 @@ fi
 
 guard:require tool:jq
 release:require-manifest
-read -r -a modules <<<"$(release:manifest-modules)"
+readarray -t modules < <(release:manifest-modules)
 previous=$(release:manifest-version)
 current=$(release:version)
 release:render-all "${kit_root}" "${modules[@]}"
 section "kit update ${previous} → ${current}, modules: ${modules[*]}"
 
-# The previous release is the base of every merge, needed only when the release changed. KIT_BASE names its
-# root; otherwise release:fetch finds or fetches it.
 base_root=""
-# shellcheck disable=SC2154  # release_unreleased is declared by bin/release.sh, which use loaded above
 if [[ -n "${KIT_BASE:-}" ]]
 then
   base_root=${KIT_BASE}
-elif [[ "${previous}" != "${current}" && "${previous}" != "${release_unreleased}" ]]
+elif [[ "${previous}" == "${current}" ]]
+then
+  base_root=${kit_root}
+elif [[ "${previous}" != "$(release:unreleased)" ]]
 then
   base_root=$(release:fetch "${previous}" || true)
 fi
-[[ -n "${base_root}" ]] && release:render-all "${base_root}" "${modules[@]}"
-needs_base=false
-[[ "${previous}" != "${current}" ]] && needs_base=true
+if [[ -n "${base_root}" ]] && ! release:render-all "${base_root}" "${modules[@]}"
+then
+  error "the base release at ${base_root} could not be read; see above"
+  exit 1
+fi
 
 conflicts=0
-# shellcheck disable=SC2154  # release_bases is declared by bin/release.sh, which use loaded above
-for base in "${release_bases[@]}"
+skipped=0
+for base in $(release:bases)
 do
   while IFS=$'\t' read -r path src
   do
@@ -57,27 +55,16 @@ do
     recorded=$(release:recorded "${base}" "${path}")
     if [[ -z "${recorded}" ]]
     then
-      # A path the previous release did not deliver: written where there is nothing, or the same thing.
-      if release:merged "${dest}" || [[ ! -f "${dest}" ]]
-      then
-        step "${dest}: new in ${current}, written"
-        release:place "${src}" "${dest}"
-      elif cmp --silent "${src}" "${dest}"
-      then
-        step "${dest}: new in ${current}, and already as the release has it"
-      else
-        error "${dest} is new in ${current} and a file is there already; move yours aside, then run: kit update"
-        conflicts=$(( conflicts + 1 ))
-      fi
+      # New in this release: written where there is nothing, or the same thing, and refused over anything else.
+      release:place-new "${src}" "${dest}" "new in ${current}" || conflicts=$(( conflicts + 1 ))
       continue
     fi
     previous_src=""
     [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "${modules[@]}")
-    if [[ "${needs_base}" == true && -z "${previous_src}" ]]
+    if [[ -z "${previous_src}" ]]
     then
-      # Without the base, neither a merge nor the removal of the previous release's entries is possible.
       error "${dest} cannot be updated without the base release ${previous}; set KIT_BASE to a copy of it"
-      conflicts=$(( conflicts + 1 ))
+      skipped=$(( skipped + 1 ))
       continue
     fi
     if release:merged "${dest}"
@@ -101,35 +88,14 @@ do
       fi
     fi
   done < <(release:delivered "${kit_root}" "${base}" "${modules[@]}")
-
-  # The paths this release no longer delivers under the base.
-  while IFS= read -r path
-  do
-    [[ -n "${path}" ]] || continue
-    dest=$(release:dest "${base}" "${path}")
-    [[ -e "${dest}" ]] || continue
-    if release:merged "${dest}"
-    then
-      previous_src=""
-      [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "${modules[@]}")
-      if [[ -n "${previous_src}" ]]
-      then
-        step "${dest}: retired in ${current}, the previous release's entries taken out"
-        # shellcheck disable=SC2016  # a jq filter, with jq variables
-        release:json-write "${dest}" 'unmerge(.; $base[0])' --slurpfile base "${previous_src}"
-      else
-        warn "${dest}: retired in ${current}, but without the base release its entries cannot be taken out; it is left as it was"
-      fi
-    elif [[ "$(release:recorded "${base}" "${path}")" == "$(release:digest < "${dest}")" ]]
-    then
-      step "${dest}: retired in ${current}, removed"
-      rm -f "${dest}"
-    else
-      warn "${dest}: retired in ${current}, but edited since ${previous}; it is left as it was"
-    fi
-  done < <(comm -23 <(release:manifest-paths "${base}" | sort) <(release:delivered "${kit_root}" "${base}" "${modules[@]}" | cut -f 1 | sort))
+  release:retire "${base_root}" "${base}" "${previous}" "${current}" "${modules[@]}"
 done
 
+if (( skipped > 0 ))
+then
+  error "${skipped} path(s) stay at ${previous}, and so does the manifest; set KIT_BASE, then run: kit update"
+  exit 1
+fi
 release:write-manifests "${modules[@]}"
 if (( conflicts > 0 ))
 then
diff --git a/bin/release.sh b/bin/release.sh
index a3b610e..4e06745 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -1,23 +1,32 @@
 # shellcheck shell=bash
 # shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
-# release.sh - the release's modules, the one merge rule, the templates, and the manifest (sourced module)
+# release.sh - the release's modules, the one merge rule, the templates, and the manifests (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
 # mirrored at the base's root; and templates/<base>/, with @key@ rendered from the repository's answers, then
 # mirrored the same way. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's
-# home directory, recorded in ~/.kit/manifest, which is the desk's record rather than the repository's. A
-# destination ending in .json is merged by key, with the kit's keys set, the kit's array entries added, and on
-# update or removal only the previous release's entries taken out. .kit/manifest records the version, the active
-# modules, and the release's digest for every delivered path. docs/modules.md is the format's description.
+# home directory, recorded in ~/.kit/manifest, which every repository on the desk shares. A destination ending
+# in .json is merged by key, the kit owning only the entries it writes. docs/modules.md is the format's description.
 #
-# Every function reads a release from a root, kit_root by default, which bin/kit exports.
+# Every function reads a release from a root, kit_root by default, which bin/kit exports. bin/kit also moves to
+# the repository root, so .kit/manifest and every repo path here are relative to it. Every sort and comm here
+# collates in the C locale, so an order written on one machine is the order read on another.
 
 use yaml
 
-# release_bases are the destinations a module may deliver to, as the subdirectories of files/ and templates/.
-declare -gra release_bases=(repo home)
+# release:unreleased prints the version of a checkout: the release workflow stamps a version file, a checkout
+# has none, and this is the one version kit update never fetches.
+release:unreleased() { printf 'unreleased\n'; }
+
+# release:version prints this release's version.
+release:version() {
+  cat "${kit_root}/version" 2>/dev/null || release:unreleased
+}
+
+# release:bases prints the destinations a module may deliver to, the subdirectories of files/ and templates/.
+release:bases() { printf 'repo\nhome\n'; }
 
 # release:base-root <base> prints the directory the base's files are mirrored at: the repository root, which the
 # verbs run from, or the home directory, KIT_HOME when set so a test can stand in for it.
@@ -26,7 +35,7 @@ release:base-root() {
     (repo) printf '.\n' ;;
     (home) printf '%s\n' "${KIT_HOME:-${HOME}}" ;;
     (*)
-      error "'$1' is not a base; the bases are: ${release_bases[*]}"
+      error "'$1' is not a base; the bases are: $(release:bases | paste -s -d ' ' -)"
       return 2
   esac
 }
@@ -42,18 +51,10 @@ release:dest() {
 # release:manifest <base> prints the base's manifest: .kit/manifest in the repository, ~/.kit/manifest for home.
 release:manifest() { release:dest "$1" .kit/manifest; }
 
-# A release carries a version file the release workflow stamps from the tag; a checkout carries none and is
-# "unreleased", the one version kit update never asks mise for.
-declare -gr release_unreleased=unreleased
-
-# release:version prints this release's version.
-release:version() {
-  cat "${kit_root}/version" 2>/dev/null || printf '%s\n' "${release_unreleased}"
-}
-
 # release:modules [<root>] prints the modules the release carries: every modules/<name>/ with a module.yml.
 release:modules() {
-  (cd "${1:-${kit_root}}/modules" && find . -mindepth 2 -maxdepth 2 -name module.yml | sed 's@^\./@@; s@/module.yml$@@' | sort)
+  (cd "${1:-${kit_root}}/modules" \
+    && find . -mindepth 2 -maxdepth 2 -name module.yml | sed 's@^\./@@; s@/module.yml$@@' | LC_ALL=C sort)
 }
 
 # release:meta <root> <module> prints the path of the module's metadata.
@@ -83,7 +84,8 @@ release:require-modules() {
   do
     if [[ ! -f "$(release:meta "${root}" "${module}")" ]]
     then
-      error "'${module}' is not a module this release knows; the modules are: $(release:modules "${root}" | paste -s -d ' ' -)"
+      error "'${module}' is not a module this release knows; the modules are:" \
+        "$(release:modules "${root}" | paste -s -d ' ' -)"
       return 2
     fi
   done
@@ -95,6 +97,7 @@ release:require-modules() {
 release:resolve() {
   local root=$1 module dep ready placed_count=0
   shift
+  (( $# > 0 )) || return 0
   local -A wanted=() placed=()
   local -a queue=("$@") names=()
   while (( ${#queue[@]} > 0 ))
@@ -108,7 +111,7 @@ release:resolve() {
       queue+=("${dep}")
     done
   done
-  readarray -t names < <(printf '%s\n' "${!wanted[@]}" | sort)
+  readarray -t names < <(printf '%s\n' "${!wanted[@]}" | LC_ALL=C sort)
   while (( placed_count < ${#names[@]} ))
   do
     ready=''
@@ -146,6 +149,42 @@ release:dependents() {
   done
 }
 
+# release:validate <root> <module> refuses metadata the schema would refuse, as far as bash can tell without a
+# validator: a key the kit does not know, a default that is not true or false, a dependency on a module the
+# release lacks. The gate validates against modules/module.schema.json in full.
+release:validate() {
+  local root=$1 module=$2 meta key value dep
+  meta=$(release:meta "${root}" "${module}")
+  for key in $(yaml:keys "${meta}")
+  do
+    case "${key}" in
+      (description | default | depends | answers) ;;
+      (*)
+        error "modules/${module}/module.yml has a key the kit does not know: ${key} (see modules/module.schema.json)"
+        return 1
+    esac
+  done
+  if [[ -z "$(yaml:value "${meta}" description)" ]]
+  then
+    error "modules/${module}/module.yml has no description"
+    return 1
+  fi
+  value=$(yaml:value "${meta}" default)
+  if [[ -n "${value}" && "${value}" != true && "${value}" != false ]]
+  then
+    error "modules/${module}/module.yml: default must be true or false, not '${value}'"
+    return 1
+  fi
+  for dep in $(release:depends "${root}" "${module}")
+  do
+    if [[ ! -f "$(release:meta "${root}" "${dep}")" ]]
+    then
+      error "modules/${module}/module.yml depends on '${dep}', which this release does not carry"
+      return 1
+    fi
+  done
+}
+
 # release:answers <root> <module> prints "<key>\t<value>" for every answer the module's templates may use: the
 # module's defaults under answers:, each overridden by a "<key> <value>" line in the repository's .kit/answers.
 release:answers() {
@@ -156,7 +195,8 @@ release:answers() {
   } | awk 'NF >= 2 { v = $0; sub(/^[^ ]+ +/, "", v); a[$1] = v } END { for (k in a) print k "\t" a[k] }'
 }
 
-# release:tmp prints a directory for this process's rendered templates, made once and removed at exit.
+# release:tmp prints a directory for this process's rendered templates, made once and removed at exit. The
+# rendering happens in release:render-all, which every verb runs before it reads a release.
 release:tmp() {
   if [[ -z "${release_tmp:-}" ]]
   then
@@ -185,7 +225,7 @@ release:render() {
     do
       rel=${file#"${templates}"/}
       text=$(<"${file}")
-      for key in $(grep --only-matching '@[a-z_]*@' "${file}" | sort --unique | tr -d '@')
+      for key in $(grep --only-matching '@[a-z_]*@' "${file}" | LC_ALL=C sort --unique | tr -d '@')
       do
         if [[ -z "${answer[${key}]+x}" ]]
         then
@@ -201,48 +241,13 @@ release:render() {
   printf '%s\n' "${out}"
 }
 
-# release:validate <root> <module> refuses metadata the schema would: a key the kit does not know, a default that
-# is not true or false, a dependency on a module the release lacks. The gate validates against
-# modules/module.schema.json with a real validator; this is the same contract where no validator is, at install.
-release:validate() {
-  local root=$1 module=$2 meta key value dep
-  meta=$(release:meta "${root}" "${module}")
-  for key in $(yaml:keys "${meta}")
-  do
-    case "${key}" in
-      (description | default | depends | answers) ;;
-      (*)
-        error "modules/${module}/module.yml has a key the kit does not know: ${key} (the schema is modules/module.schema.json)"
-        return 1
-    esac
-  done
-  if [[ -z "$(yaml:value "${meta}" description)" ]]
-  then
-    error "modules/${module}/module.yml has no description"
-    return 1
-  fi
-  value=$(yaml:value "${meta}" default)
-  if [[ -n "${value}" && "${value}" != true && "${value}" != false ]]
-  then
-    error "modules/${module}/module.yml: default must be true or false, not '${value}'"
-    return 1
-  fi
-  for dep in $(release:depends "${root}" "${module}")
-  do
-    if [[ ! -f "$(release:meta "${root}" "${dep}")" ]]
-    then
-      error "modules/${module}/module.yml depends on '${dep}', which this release does not carry"
-      return 1
-    fi
-  done
-}
-
-# release:render-all <root> <module>… validates the metadata of every module the release carries, active or not,
-# since a release with a broken module is a broken release; then renders the named modules' templates for every
-# base, refusing a base the kit does not know, or an unanswered key, naming it.
+# release:render-all <root> <module>… makes the release at <root> ready to read for the named modules: it refuses
+# a module the release lacks, validates every module the release carries, refuses a base the kit does not deliver
+# to, renders the named modules' templates, and refuses a link to nothing among the delivered files.
 release:render-all() {
   local root=$1 module kind base
   shift
+  release:require-modules "${root}" "$@" || return 2
   for module in $(release:modules "${root}")
   do
     release:validate "${root}" "${module}" || return 1
@@ -251,20 +256,27 @@ release:render-all() {
   do
     for kind in files templates
     do
-      for base in $(cd "${root}/modules/${module}/${kind}" 2>/dev/null && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@')
+      for base in $(cd "${root}/modules/${module}/${kind}" 2>/dev/null \
+        && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@')
       do
-        if ! release:among "${base}" "${release_bases[@]}"
+        # shellcheck disable=SC2046  # the bases are single words
+        if ! release:among "${base}" $(release:bases)
         then
-          error "modules/${module}/${kind}/${base} names a base the kit does not deliver to; the bases are: ${release_bases[*]}"
+          error "modules/${module}/${kind}/${base} names a base the kit does not deliver to; the bases are:" \
+            "$(release:bases | paste -s -d ' ' -)"
           return 1
         fi
       done
     done
-    for base in "${release_bases[@]}"
+    for base in $(release:bases)
     do
       release:render "${root}" "${module}" "${base}" >/dev/null || return 1
     done
   done
+  for base in $(release:bases)
+  do
+    release:delivered "${root}" "${base}" "$@" >/dev/null || return 1
+  done
 }
 
 # release:layers <root> <base> <module>… prints the directories mirrored at the base's root, in module order: each
@@ -288,8 +300,9 @@ release:delivered() {
   local layer path src
   while IFS= read -r layer
   do
-    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@' | awk -v l="${layer}" '{ print $0 "\t" l "/" $0 }')
-  done < <(release:layers "$@") | awk -F '\t' '{ src[$1] = $2 } END { for (p in src) print p "\t" src[p] }' | sort \
+    (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@' \
+      | awk -v l="${layer}" '{ print $0 "\t" l "/" $0 }')
+  done < <(release:layers "$@") | awk -F '\t' '{ src[$1] = $2 } END { for (p in src) print p "\t" src[p] }' | LC_ALL=C sort \
     | while IFS=$'\t' read -r path src
   do
     if [[ -L "${src}" && ! -e "${src}" ]]
@@ -315,19 +328,18 @@ release:paths-beyond() {
   local -a before after
   read -r -a before <<<"$3"
   read -r -a after <<<"$4"
-  comm -13 <(release:delivered "${root}" "${base}" "${before[@]}" | cut -f 1) \
+  LC_ALL=C comm -13 <(release:delivered "${root}" "${base}" "${before[@]}" | cut -f 1) \
     <(release:delivered "${root}" "${base}" "${after[@]}" | cut -f 1)
 }
 
+# release:merged <path> is true for a destination that is merged by key rather than copied: a .json file.
 release:merged() { [[ "$1" == *.json ]]; }
 
 # release:fetch <version> prints the root of that release, fetching it if need be: the kit's cache first, then a
-# mise install if mise is here, then the GitHub release itself, unpacked into the cache. Nothing here assumes how
-# this release was installed.
+# mise install if mise is here, then the GitHub release itself, unpacked into the cache. The version comes from a
+# manifest, so it is held to a version's shape before it is used in a path.
 release:fetch() {
   local version=$1 root cache fresh
-  # The version comes from a manifest, which is repository content, so it is held to a version's shape before it
-  # becomes part of a path; the unpack goes into a directory made here and is moved into place only when whole.
   if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
   then
     error "'${version}' is not a kit version"
@@ -350,8 +362,8 @@ release:fetch() {
   fi
   step "Fetching kit ${version} from its GitHub release"
   fresh=$(mktemp -d)
-  if ! gh release download "v${version}" --repo empowerite/kit --pattern "kit-${version}.tar.gz" --output - 2>/dev/null \
-    | tar --extract --gzip --directory "${fresh}" --strip-components 1
+  if ! gh release download "v${version}" --repo empowerite/kit --pattern "kit-${version}.tar.gz" --output - \
+    2>/dev/null | tar --extract --gzip --directory "${fresh}" --strip-components 1
   then
     rm -rf "${fresh}"
     error "kit ${version} could not be fetched (run: gh auth status, or set KIT_BASE to a copy of it)"
@@ -383,8 +395,7 @@ release:without() {
   done
 }
 
-# The parameters are values ($), not filters: a filter parameter is re-read against the input at each use, which
-# inside the recursion is the wrong level of the object.
+# The merge, as jq. The parameters are values ($), not filters, so each is read once at the right level.
 release_jq='
   def merge($cur; $base; $new):
     if ($new | type) == "object" then
@@ -404,7 +415,8 @@ release_jq='
     else $cur == $new end;
 '
 
-# release:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if missing.
+# release:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if
+# missing.
 release:json-write() {
   local path=$1 filter=$2
   shift 2
@@ -414,7 +426,8 @@ release:json-write() {
   mv "${path}.kit-new" "${path}"
 }
 
-# release:json-holds <path> <source> is true when the JSON at <path> carries every entry the release's <source> writes.
+# release:json-holds <path> <source> is true when the JSON at <path> carries every entry the release's <source>
+# writes.
 release:json-holds() {
   jq --exit-status "${release_jq} holds(.; \$new[0])" --slurpfile new "$2" "$1" >/dev/null
 }
@@ -429,7 +442,8 @@ release:digest() {
   fi
 }
 
-# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, else a copy.
+# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, else a
+# copy that keeps the source's mode.
 release:place() {
   local src=$1 path=$2 base=${3:-/dev/null}
   if release:merged "${path}"
@@ -437,11 +451,41 @@ release:place() {
     release:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
   else
     mkdir -p "$(dirname "${path}")"
-    cat "${src}" > "${path}.kit-new"
+    cp "${src}" "${path}.kit-new"
     mv "${path}.kit-new" "${path}"
   fi
 }
 
+# release:place-new <source> <path> [<label>] places content the repository did not record: where there is
+# nothing, or the same thing, or a .json to merge into. A different file is refused, named, and left as it is.
+release:place-new() {
+  local src=$1 path=$2 label=${3:-}
+  if release:merged "${path}" || [[ ! -f "${path}" ]]
+  then
+    step "${path}${label:+: ${label}}"
+    release:place "${src}" "${path}"
+  elif cmp --silent "${src}" "${path}"
+  then
+    step "${path}${label:+: ${label}}, already as the release has it"
+  else
+    error "${path}: a different file is there already; move it aside, or remove it if it is not yours"
+    return 1
+  fi
+}
+
+# release:place-all <root> <base> <module>… places every path the modules deliver under the base, refusing where
+# a different file is. It returns the number of refusals.
+release:place-all() {
+  local root=$1 base=$2 path src refused=0
+  shift 2
+  while IFS=$'\t' read -r path src
+  do
+    [[ -n "${path}" ]] || continue
+    release:place-new "${src}" "$(release:dest "${base}" "${path}")" || refused=$(( refused + 1 ))
+  done < <(release:delivered "${root}" "${base}" "$@")
+  return "${refused}"
+}
+
 # release:unplace <source> <path> takes the release's content back out of <path>: the kit's entries for .json,
 # the file itself otherwise.
 release:unplace() {
@@ -457,27 +501,88 @@ release:unplace() {
   fi
 }
 
+# release:retire <base-root> <base> <previous> <current> <module>… handles the paths the base's manifest records
+# that the current release no longer delivers: removed when still the previous release's own content, their
+# entries taken out of a merged .json when the base release is at hand, left with a warning otherwise. Under
+# home, whose manifest every repository shares, only paths the previous release delivered for these modules are
+# touched, and none without the base release.
+release:retire() {
+  local base_root=$1 base=$2 previous=$3 current=$4 path dest previous_src candidates
+  shift 4
+  candidates=$(LC_ALL=C comm -23 <(release:manifest-paths "${base}" | LC_ALL=C sort) \
+    <(release:delivered "${kit_root}" "${base}" "$@" | cut -f 1 | LC_ALL=C sort))
+  if [[ "${base}" != repo ]]
+  then
+    [[ -n "${base_root}" ]] || return 0
+    candidates=$(LC_ALL=C comm -12 <(printf '%s\n' "${candidates}" | LC_ALL=C sort) \
+      <(release:delivered "${base_root}" "${base}" "$@" | cut -f 1 | LC_ALL=C sort))
+  fi
+  while IFS= read -r path
+  do
+    [[ -n "${path}" ]] || continue
+    dest=$(release:dest "${base}" "${path}")
+    [[ -e "${dest}" ]] || continue
+    if release:merged "${dest}"
+    then
+      previous_src=""
+      [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "$@")
+      if [[ -n "${previous_src}" ]]
+      then
+        step "${dest}: retired in ${current}, the previous release's entries taken out"
+        release:json-write "${dest}" 'unmerge(.; $base[0])' --slurpfile base "${previous_src}"
+      else
+        warn "${dest}: retired in ${current}; without the base release its entries stay, and it is left as it was"
+      fi
+    elif [[ "$(release:recorded "${base}" "${path}")" == "$(release:digest < "${dest}")" ]]
+    then
+      step "${dest}: retired in ${current}, removed"
+      rm -f "${dest}"
+    else
+      warn "${dest}: retired in ${current}, but edited since ${previous}; it is left as it was"
+    fi
+  done <<<"${candidates}"
+}
+
 # release:write-manifest <base> <module>… records, in the base's manifest, the version, the active modules, and
-# the release's digest for every path delivered under the base. The repository's is always written; home's only
-# when something is delivered there, and it is removed when nothing is any more.
+# the release's digest of every path delivered under the base. The repository's manifest is always written.
+# Home's is shared by every repository on the desk: it is written when these modules deliver there, and when they
+# do not, the lines whose paths are gone are dropped and the file is removed once nothing is left.
 release:write-manifest() {
-  local base=$1 manifest path src delivered
+  local base=$1 manifest path src delivered kept
   shift
   manifest=$(release:manifest "${base}")
   delivered=$(release:delivered "${kit_root}" "${base}" "$@")
   if [[ "${base}" != repo && -z "${delivered}" ]]
   then
-    rm -f "${manifest}"
+    [[ -f "${manifest}" ]] || return 0
+    kept=$(while IFS= read -r path
+      do
+        [[ -n "${path}" && -e "$(release:dest "${base}" "${path}")" ]] && grep -F "  ${path}" "${manifest}"
+      done < <(release:manifest-paths "${base}"); true)
+    if [[ -z "${kept}" ]]
+    then
+      rm -f "${manifest}"
+    else
+      { sed -n '1,3p' "${manifest}"; printf '%s\n' "${kept}"; } > "${manifest}.kit-new"
+      mv "${manifest}.kit-new" "${manifest}"
+    fi
     return 0
   fi
   mkdir -p "$(dirname "${manifest}")"
   {
     printf '# .kit/manifest - written by kit, not by hand\n'
     printf 'version %s\n' "$(release:version)"
-    printf 'modules%s\n' "${*:+ $*}"
+    if (( $# > 0 ))
+    then printf 'modules %s\n' "$*"
+    else printf 'modules\n'
+    fi
     while IFS=$'\t' read -r path src
     do
-      [[ -n "${path}" ]] && printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
+      # An if, not an && list: as the loop's last command, a false list would end the script under errexit.
+      if [[ -n "${path}" ]]
+      then
+        printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
+      fi
     done <<<"${delivered}"
   } > "${manifest}"
 }
@@ -485,22 +590,25 @@ release:write-manifest() {
 # release:write-manifests <module>… writes every base's manifest.
 release:write-manifests() {
   local base
-  for base in "${release_bases[@]}"
+  for base in $(release:bases)
   do
     release:write-manifest "${base}" "$@"
   done
 }
 
+# release:manifest-version prints the version the repository's manifest records.
 release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
 
-release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest; }
+# release:manifest-modules prints the active modules the repository's manifest records, one per line.
+release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest | tr ' ' '\n' | awk 'NF'; }
 
-# release:manifest-paths <base> prints every path the base's manifest records.
+# release:manifest-paths <base> prints every path the base's manifest records. A record line is a 64-digit
+# digest, two spaces, and the path, which may itself hold spaces.
 release:manifest-paths() {
   local manifest
   manifest=$(release:manifest "$1")
   [[ -f "${manifest}" ]] || return 0
-  awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' "${manifest}"
+  awk 'length($1) == 64 && $0 ~ /^[0-9a-f]+  / { print substr($0, 67) }' "${manifest}"
 }
 
 # release:recorded <base> <path> prints the digest the base's manifest records for <path>, or nothing.
@@ -508,7 +616,7 @@ release:recorded() {
   local manifest
   manifest=$(release:manifest "$1")
   [[ -f "${manifest}" ]] || return 0
-  awk -v p="$2" '$2 == p { print $1 }' "${manifest}"
+  awk -v p="$2" 'length($1) == 64 && substr($0, 67) == p { print $1 }' "${manifest}"
 }
 
 # release:require-manifest refuses to go on in a repository that never took the kit.
diff --git a/bin/status.sh b/bin/status.sh
index 0e4077f..cdd85f0 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -6,37 +6,16 @@
 # GitHub once, for every open pull request with the issues it closes, its review threads, and the checks on its
 # head; everything else is a local git read.
 #
-# The picture is three groups of blocks, a blank line between blocks and no headings:
+# The picture: the desk, the root checkout, first; then each worktree under worktrees/; then each open pull request
+# with its state, age, checks, the issues it closes, and the worktree holding its branch; then the branches whose
+# upstream is gone. Color is by family, never by state: green when nothing is left to decide, yellow when a human
+# owes a decision, blue when the next move is a machine's or a reviewer's, dim for detail. The states, in the
+# order the first that holds wins:
 #
-#   🏠 the desk        the root checkout, the human's. Its branch, then how far it has moved from where that branch
-#                      left origin's default branch, the lines its working tree adds and removes against that point,
-#                      and its uncommitted paths; under it the commits it carries past that point, dim hash and
-#                      subject, up to ten with the rest counted.
-#   🌿 each worktree   under worktrees/, by issue number, drawn exactly as the desk is. The label is the path from
-#                      the current directory with the branch underlined when the path ends in it, or "branch on
-#                      path" when it does not.
-#   🔀 each pull request  its title, its state with the state's glyph, its age, its checks (how many passed and how
-#                      long they took, or which failed), and its unresolved review threads when there are any; under
-#                      it the issues it closes and the worktree that holds its branch, when one here does.
+#   draft 🔨, queued 🚦, conflicted 💥, failing:gate 🔥, no-check 📭, comments:open 💬, blocked:approval 👀,
+#   ready 🛬
 #
-# Then every local branch whose upstream is gone, which kit tidy removes, each on a 🔖 line.
-#
-# Color is by family, never by state: green when nothing is left to decide, yellow when a human owes a decision,
-# blue when the next move is a machine's or a reviewer's, dim when someone already owns the work. Everything that
-# is detail rather than signal is dim: hashes, ages, durations, zero counts, directory prefixes, and the lines under
-# a row. The state is the first of these that holds:
-#
-#   draft              🔨  dim     unfinished work that belongs to someone
-#   queued             🚦  blue    a check is still running
-#   conflicted         💥  yellow  the branch does not apply cleanly to the default branch
-#   failing:gate       🔥  yellow  a check failed; the row names which
-#   no-check           📭  blue    nothing has reported on its head
-#   comments:open      💬  yellow  unresolved review threads
-#   blocked:approval   👀  blue    a review is required or requested and has not arrived
-#   ready              🛬  green   green, thread-free, approved, and mergeable
-#
-# --json prints the same facts as one document instead: {desk, worktrees, pullRequests, goneBranches}, every
-# measure a number and every list complete, for a consumer that draws its own picture.
+# --json prints the same facts as one document: {desk, worktrees, pullRequests, goneBranches}.
 
 use git
 
@@ -119,10 +98,15 @@ status:age() {
 
 # status:collect prints one JSON object per open pull request, oldest first: number, branch, title, createdAt, age
 # in seconds, state, checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes
-# [{number, title}]. The one request to GitHub.
+# [{number, title}]. The one request to GitHub; a request that fails is said so, and prints nothing.
 status:collect() {
   local repo query filter
-  repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || return 0
+  use gh
+  if ! repo=$(gh:repo)
+  then
+    warn "this checkout does not resolve to a GitHub repository, so no pull request is shown (run: gh repo view)"
+    return 0
+  fi
   # shellcheck disable=SC2016  # GraphQL variables
   query='query($owner: String!, $name: String!) {
     repository(owner: $owner, name: $name) {
@@ -176,7 +160,7 @@ status:collect() {
         closes: [.closingIssuesReferences.nodes[] | { number, title }] }
     | tojson'
   gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
-    2>/dev/null || true
+    2>/dev/null || warn "the pull requests could not be read from GitHub (run: gh auth status); none is shown"
 }
 
 # status:fork <branch> <default-branch> prints the commit where <branch> left the default branch, or nothing.
@@ -184,9 +168,19 @@ status:fork() {
   git merge-base "origin/$2" "$1" 2>/dev/null || git merge-base "$2" "$1" 2>/dev/null || true
 }
 
-# status:relative <path> prints <path> relative to the current directory: ".", a descent, or a climb.
+# status:relative <path> prints <path> relative to the directory the command was typed in: ".", a descent, or a
+# climb. Both sides are resolved physically, the target through its nearest directory that exists, so a symlinked
+# directory on either side still climbs correctly.
 status:relative() {
-  local target=$1 here=${PWD} up=''
+  local target=$1 here=${kit_invoked_in:-$(pwd -P)} up='' dir rest=''
+  dir=${target}
+  while [[ -n "${dir}" && ! -d "${dir}" ]]
+  do
+    rest="${dir##*/}${rest:+/${rest}}"
+    dir=${dir%/*}
+  done
+  dir=$(cd "${dir:-/}" && pwd -P)
+  target="${dir}${rest:+/${rest}}"
   if [[ "${target}" == "${here}" ]]
   then
     printf '.\n'
@@ -321,7 +315,8 @@ status:checkout-block() {
   done < <(jq --raw-output --argjson cap "${status_commit_cap}" '
     (.commits | length) as $n
     | (if $n > $cap + 1
-       then (.commits[:$cap - 1][] | [.sha, .subject]), ["…", "and \($n - $cap) more"], (.commits[-1] | [.sha, .subject])
+       then (.commits[:$cap - 1][] | [.sha, .subject]), ["…", "and \($n - $cap) more"],
+            (.commits[-1] | [.sha, .subject])
        else .commits[] | [.sha, .subject] end)
     | @tsv' <<<"${doc}")
 }
@@ -352,7 +347,8 @@ status:pr-block() {
   IFS=$'\t' read -r number title state age unresolved \
     < <(jq --raw-output '[.number, .title, .state, .age, .unresolved] | @tsv' <<<"${doc}")
   row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
-  row+="   $(status:state-emoji "${state}") $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
+  row+="   $(status:state-emoji "${state}")"
+  row+=" $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
   row+="   $(status:paint 90 "$(status:cell "$(status:age "${age}")" "${age_w}")")"
   checks=$(status:check-cell "$(jq --compact-output .checks <<<"${doc}")")
   [[ -n "${checks}" ]] && row+="   ${checks}"
@@ -366,6 +362,8 @@ status:pr-block() {
   return 0
 }
 
+# status:render [--no-fetch] [--json] draws the picture the file header describes, or prints it as one JSON
+# document.
 status:render() {
   local no_fetch=false json=false arg main_root default_branch desk_branch path branch doc gone
   for arg in "$@"
@@ -391,7 +389,7 @@ status:render() {
   local desk prs
   local -a worktrees=()
   desk=$(status:checkout "${main_root}" "${desk_branch}" "${default_branch}")
-  while IFS=$'\t' read -r path branch _
+  while IFS=$'\t' read -r path _ branch
   do
     [[ -n "${path}" ]] || continue
     worktrees+=("$(status:checkout "${path}" "${branch}" "${default_branch}")")
diff --git a/docs/architecture.md b/docs/architecture.md
index c33375a..35a0635 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -14,19 +14,21 @@ A release is one tarball, `kit-<version>.tar.gz`, and its layout is the checkout
 beside it, and the verbs share bash modules loaded with `use`. The release workflow stamps the tag's version into
 a `version` file; a checkout has none and is `unreleased`.
 
-A module is a directory under `modules/`: `module.yml` names it, says whether it is active by default, which
-modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the base's root;
-`templates/<base>/` is rendered first, every `@key@` replaced by an answer; `docs/` is for a reader of this
-repository and is never delivered. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
+A module is a directory under `modules/`, and the directory names it. `module.yml` describes it: whether it is active
+by default, which modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the
+base's root; `templates/<base>/` is rendered first, every `@key@` replaced by an answer; `docs/` is packed with the
+release and placed in no repository. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
 
 The verbs are the only way content moves. `kit install` resolves the active set, default modules plus those named
 plus their dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
 an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
-fails when a delivered file differs from the release. `kit module` changes the active set. Two rules govern
+fails when a delivered file differs from the release's. `kit module` changes the active set. Two rules govern
 placement: a `.json` destination is merged by key, the kit owning only the entries it writes; everything else is a
-copy. Each base has a manifest, `.kit/manifest` committed with the repository and `~/.kit/manifest` on the desk,
-recording the version, the active modules, and the release's digest of every delivered path, which is how an edit
-reads as an edit at every later update.
+copy.
+
+Each base has a manifest: `.kit/manifest`, committed with the repository, and `~/.kit/manifest` on the desk when a
+module delivers there. A manifest records the version, the active modules, and the release's digest of every
+delivered path, which is how `kit update` tells an edited file from an untouched one.
 
 ## Finding a file's rules
 
@@ -38,23 +40,25 @@ file that exists. `kit context <path>` names the rules governing a path and appe
 `.git/kit/context.log`. Every caller gets the same answer: an agent of any harness following the sentence in
 `.kit/1st.md`, a person at the shell, a tool reading `--json`, and Claude Code's `PreToolUse` hook, which the
 `claude` module wires to `kit context --claude` so the rules are named before every write. The call names and
-never quotes: reading the rule stays an act the caller takes, which is what lets a later check compare the log of
-asks against the reads.
+never quotes: reading the rule stays an act the caller takes, and the log of asks is the record of what was
+named.
 
 ## The loop and the gate
 
 ![The loop: an issue becomes a worktree and a draft pull request, the gate holds it, a human merges](loop.svg)
 
-The desk is the root checkout and belongs to the human; it usually has `main` checked out and may have any branch
-no worktree holds, and no agent changes it in place. Work starts from an issue: `kit issue <N>` makes
+The desk is the root checkout and belongs to the human; it usually has `main` checked out and may have any branch no
+worktree holds, and no agent changes it in place. Work starts from an issue: `kit issue <N>` makes
 `worktrees/<N>-<slug>`, a branch linked to the issue under Development, a signed start commit, and a draft pull
-request, and sweeps uncommitted work off the desk into the worktree. Everything after that happens in the worktree:
-`kit context` before a change, `kit lint` for the pre-commit linters by hand, `kit rebase` to bring the branch onto
-`origin/main` and push it, and `gh pr ready` when the pull request body is the report.
-
-The gate is the delivered CI job, three steps that are each one kit command. `kit gate` runs the root justfile's
-`ci` recipe and reports a missing one as a skip, never a pass. `kit check` holds the delivered files to the
-release. `kit linked` refuses a pull request not linked to an open issue of the repository. A human merges, and
+request, and sweeps uncommitted work off the desk into the worktree, the one change it makes there, announced.
+Everything after that happens in the worktree: `kit context` before a change, `kit lint` for the pre-commit linters by
+hand, `kit rebase` to bring the branch onto `origin/main` and push it, and `gh pr ready` when the pull request body is
+the report.
+
+The gate is the delivered CI job, run for a pull request into the default branch: after a step that confirms
+`kit` is on `PATH`, three checks that are each one kit command. `kit gate` runs the root justfile's `ci` recipe and
+refuses when there is none, since a gate that cannot run clears nothing. `kit check` holds the delivered files to
+the release. `kit linked` refuses a pull request not linked to an open issue of the repository. A human merges, and
 `kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: the desk, every
 worktree with its commits past the fork, and every open pull request with its state, age, and checks.
 
@@ -62,14 +66,13 @@ worktree with its commits past the fork, and every open pull request with its st
 
 | Claim | Held by |
 | --- | --- |
-| A delivered file is the release's | `kit check`, in the gate and on a desk, against the manifest's digests |
+| A delivered file is the release's | `kit check`, in the gate and on a desk, against the release's files and the manifest's version |
 | A change has an issue | `kit linked` in the gate; `kit issue` makes the link when it starts the work |
-| The repository's own gate ran | `kit gate`, which reports a skip as a skip |
-| A rule's text reached the agent | the Claude Code hook; the plain call for every other harness |
+| The repository's own gate ran | `kit gate`, which refuses when there is no gate to run |
+| A file's rules were named to the agent | the Claude Code hook; `kit context` in every other harness |
 | A file's rules were asked for | `.git/kit/context.log`, one line per ask |
 | The forbidden spellings were not used | the harness's deny list, delivered by its adapter module |
-| The desk was not disturbed | `kit rebase` refusing the root checkout; `kit issue` never switching it |
+| The desk was not disturbed | `kit rebase` refusing the root checkout; `kit issue` never switching its branch |
 
-What no check holds yet is whether a rule, once read, was followed. The linters hold the mechanical part of that
-for the kinds they cover; the rest is the pull request body's report, which the integrity rules in `.kit/1st.md`
-bind.
+No check holds whether a rule, once read, was followed. The linters hold the mechanical part of that for the kinds
+they cover; the rest is the pull request body's report, which the integrity rules in `.kit/1st.md` bind.
diff --git a/docs/context.md b/docs/context.md
index a9108df..2a323d9 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -4,12 +4,11 @@ A rule is written once, in `.kit/rules/<kind>.md`, and copied nowhere. Before an
 it asks which rules govern that file:
 
 ```sh
-kit context <path>…
+kit context "${path}"
 ```
 
 The answer is the rule files to read, one per line. `--json` gives one object per path with its rules. Every ask
-is appended to `.git/kit/context.log` as `<epoch>\t<path>`, which is the evidence a check can read to ask whether
-every path a commit touched had its context asked for.
+is appended to `.git/kit/context.log`, one line of epoch and path per ask.
 
 ## How a rule declares what it governs
 
@@ -24,8 +23,9 @@ content:
 ---
 ```
 
-- `paths:` are globs matched against the repository-relative path. `**` stands for any depth, so `**/*.sh` is
-  every `.sh` file and `justfile` is the one at the root.
+- `paths:` are globs matched against the repository-relative path. `**` stands for any depth, and a lone `*`
+  crosses directories too, so `**/*.sh` and `*.sh` both name every `.sh` file; a glob with no wildcard, such as
+  `justfile`, names the one path.
 - `content:` are extended regular expressions matched against the first line of a file that already exists, so a
   bash script with no extension is bash by its shebang, and a file about to be created is governed by its path
   alone.
@@ -42,10 +42,15 @@ the agent remembering to ask. The `claude` module wires Claude Code's `PreToolUs
 kit context --claude
 ```
 
-It reads the hook's input on stdin, takes the file path from the tool's input, and answers in the hook's output
-with the rules' paths as additional context, the same answer the plain call prints. It names and never quotes, so
-reading the rule stays an act the agent takes, one a hook on `Read` can record and a check can compare against
-the context log. No state is kept between calls.
+It reads the hook's input on stdin, takes the file path from the tool's input, and answers in the hook's output,
+naming the rules and never quoting them, so reading a rule stays an act the agent takes:
+
+```json
+{"hookSpecificOutput": {"hookEventName": "PreToolUse",
+  "additionalContext": "kit: lib/run.sh is governed by .kit/rules/bash.md; read it before this change."}}
+```
+
+No state is kept between calls.
 
 A harness with no hook, and a person, use the plain call. `.kit/1st.md` names it as the step before any file is
 created or changed.
diff --git a/docs/modules.md b/docs/modules.md
index 3ce6dec..608ae73 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -10,7 +10,7 @@ modules/<name>/
   module.yml          metadata
   files/<base>/       files mirrored at the base's root
   templates/<base>/   files rendered from the repository's answers, then mirrored the same way
-  docs/               the module's documentation, for a reader of this repository; not delivered
+  docs/               the module's documentation; packed with the release, placed in no repository
 ```
 
 A module may have any of `files/`, `templates/`, and `docs/`, and must have `module.yml`. A base names where a
@@ -32,7 +32,7 @@ bases listed. `KIT_HOME` stands in for the home directory, which is how the test
 A line starting with `#` is a comment.
 
 ```yaml
-description: One CI job: the repository's gate, kit check, and the linked-open-issue refusal
+description: "One CI job: the repository's gate, kit check, and the linked-open-issue refusal"
 default: true
 depends:
   - kit
@@ -63,11 +63,11 @@ A file under `templates/<base>/` is rendered first. Every `@key@` in it, autocon
 answer, then the result is placed, digested, and merged exactly as a `files/` file is. The form is one neither
 bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
 answers live in `.kit/answers`, a file of `key value` lines the repository owns and the kit never writes; a key
-with no line there takes the module's `answer` default, and a key with neither refuses the install, naming the key
-and the module.
+with no line there takes the module's default under `answers`, and a key with neither refuses the install, naming
+the key and the module.
 
-The same file is also what a rule's frontmatter is written in, read by the same functions, so a rule's `paths:` and
-`content:` lists and a module's `depends:` list have one reader between them.
+The same YAML subset is what a rule's frontmatter is written in, read by `bin/yaml.sh` in both places, so a rule's
+`paths:` and `content:` lists and a module's `depends:` list have one reader between them.
 
 ## Activation
 
@@ -87,7 +87,4 @@ The same file is also what a rule's frontmatter is written in, read by the same
 | `ci` | yes | `kit` | `.github/workflows/kit-ci.yml`, from a template; answer `ci_runner` |
 | `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
 
-No module delivers to `home` yet. A module's `files/repo/` and `templates/repo/` carry the paths above; its
-`docs/README.md` says why.
-
-Each module's `docs/README.md` says what it places and why.
+No module in this release delivers to `home`. Each module's `docs/README.md` says what it places and why.
diff --git a/justfile b/justfile
index 84f9c04..675010e 100644
--- a/justfile
+++ b/justfile
@@ -22,9 +22,8 @@ set export := true
 
 # The gate: shellcheck over every bash file, actionlint over every workflow, markdownlint over every markdown
 # file, every module.yml against modules/module.schema.json, the bats suite, and bin/kit check over this
-# repository's installed copy of its own kit. The runner runs
-# it on every pull request, and a desk runs it the same way; the pre-commit hook is the narrower, faster check
-# over the staged paths.
+# repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
+# same way; the pre-commit hook is the narrower, faster check over the staged paths.
 #
 #   just ci
 [doc("🚦 The gate: shellcheck, actionlint, markdownlint, the module schema, bats, kit check")]
diff --git a/lefthook.yml b/lefthook.yml
index b27e1b8..7df58ed 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,9 +1,9 @@
 # lefthook.yml - this repository's git hooks; see: https://lefthook.dev
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The kit's own linters come from its installed fragment, the way a consumer takes them; the dispatcher, which
-# carries no extension, and the refresh of the installed copies are this repository's own. Once per clone:
-# lefthook install
+# The kit's own linters come from its installed fragment, the way a consumer takes them. This repository adds
+# shellcheck over the dispatcher, which carries no extension, markdownlint, and the refresh of the installed
+# copies. Once per clone: lefthook install
 
 extends:
   - .kit/lefthook.yml
@@ -16,9 +16,8 @@ pre-commit:
     markdownlint:
       glob: "*.md"
       run: markdownlint-cli2 {staged_files}
-    # A commit that changes the source of a delivered file rewrites the installed copies in the same commit, from
-    # the index, so nobody remembers just refresh. The recipe stages what it rewrote; stage_fixed would re-stage
-    # only the source paths it was handed.
+    # A change to a delivered file's source rewrites the installed copies in the same commit; the recipe stages
+    # what it rewrote.
     refresh:
       glob: "modules/**"
       run: just refresh
diff --git a/modules/ci/docs/README.md b/modules/ci/docs/README.md
index 8e59d3b..30421ae 100644
--- a/modules/ci/docs/README.md
+++ b/modules/ci/docs/README.md
@@ -1,9 +1,10 @@
 # The ci module
 
-Places `.github/workflows/kit-ci.yml`: one job, `CI`, whose steps are one kit command each. `kit gate` runs the
-repository's `just ci` when its root justfile has that recipe and reports a missing one as a skip, `kit check`
-holds every delivered file to the pinned release, and `kit linked` refuses a pull request not linked to an open
-issue of the repository. Each is a verb a desk can run, so the runner does nothing a person cannot repeat.
+Places `.github/workflows/kit-ci.yml`: one job, `CI`, run for a pull request into the default branch. After a
+step that confirms `kit` is on `PATH`, three checks, each one kit command: `kit gate` runs the repository's
+`just ci` and refuses when the root justfile has no `ci` recipe, `kit check` holds every delivered file to the
+pinned release, and `kit linked` refuses a pull request not linked to an open issue of the repository. Each is a
+verb a desk can run, so the runner does nothing a person cannot repeat.
 
 The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
 a repository with runners of its own puts `ci_runner <label>` in `.kit/answers`.
diff --git a/modules/ci/templates/repo/.github/workflows/kit-ci.yml b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
index a52b5bc..ef6435c 100644
--- a/modules/ci/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
@@ -1,14 +1,14 @@
 # kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires. Each step is one kit command, so what the runner does
-# is what a desk can do: `kit gate` runs the root justfile's ci recipe and reports a missing one as a skip,
-# `kit check` holds every delivered file to the pinned release, and `kit linked` refuses a pull request not linked
-# to an open issue of this repository under Development. The last two run even when an earlier step refused, so
-# one run reports every finding.
+# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. After
+# a step that confirms kit is on PATH, three checks, each one kit command, so what the runner does a desk can do:
+# `kit gate` runs the root justfile's ci recipe and refuses when there is none, `kit check` holds every delivered
+# file to the pinned release, and `kit linked` refuses a pull request not linked to an open issue of this
+# repository under Development. The last two run even when an earlier step refused, so one run reports every
+# finding.
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. Rendered from a template: the
-# job runs on the ci_runner answer, ubuntu-latest unless .kit/answers says otherwise.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner answer.
 #
 # see: .kit/1st.md
 
@@ -37,7 +37,9 @@ jobs:
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
 
       - name: kit-on-path
-        run: command -v kit >/dev/null || { echo '::error::kit is not on PATH; pin "github:empowerite/kit" in mise.toml'; exit 1; }
+        run: |
+          command -v kit >/dev/null && exit 0
+          echo '::error::pin "github:empowerite/kit" in mise.toml; kit is not on PATH' && exit 1
 
       - name: gate
         run: kit gate
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index cb6ae19..9adf47f 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -1,18 +1,17 @@
 # The claude module
 
-The adapter for Claude Code. Since 2.1.277, Claude Code reads `AGENTS.md` as a fallback: only when no `CLAUDE.md`,
-`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and only where its
+The adapter for Claude Code. Claude Code reads `AGENTS.md` only as a fallback: when no `CLAUDE.md`,
+`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and where its
 configuration allows. A repository with a `CLAUDE.md` of its own would have `AGENTS.md` skipped. So the module
 places `.claude/CLAUDE.md`, two lines, the second `@../AGENTS.md`: Claude then reads what every other agent reads
 in every case, and a root `CLAUDE.md` of the repository's own stays its own. It also merges into
 `.claude/settings.json`, by key, leaving the repository's own entries:
 
-- `permissions.deny`: the seven spellings the rules forbid an agent, such as `git rebase` and `git push --force`,
-  which `kit rebase` and the loop replace.
+- `permissions.deny`: the spellings `.kit/1st.md` forbids an agent, `git rebase`, `git worktree add`,
+  `git checkout -b`, `git switch -c`, `git worktree remove`, `git branch -D`, `git checkout main`,
+  `git switch main`, `git reset --hard`, and `git push --force`, which the kit's verbs and the loop replace.
 - `hooks.PreToolUse`: on `Write`, `Edit`, and `MultiEdit`, `kit context --claude`, which puts the rules governing
   the file before the agent, described in [docs/context.md](../../../docs/context.md).
 
-It copies no rule. `.claude/rules/` is the repository's own.
-
-Why not `@.kit/1st.md` in `AGENTS.md`: that is Claude's import syntax in a file every harness reads, and Claude,
-having inlined the file, would then be told to read it again by the sentence beside it.
+It copies no rule. `.claude/rules/` is the repository's own. `AGENTS.md` carries no `@` import of Claude's, since
+every harness reads it.
diff --git a/modules/claude/files/repo/.claude/settings.json b/modules/claude/files/repo/.claude/settings.json
index d762f8d..4845384 100644
--- a/modules/claude/files/repo/.claude/settings.json
+++ b/modules/claude/files/repo/.claude/settings.json
@@ -1,13 +1,17 @@
 {
   "permissions": {
     "deny": [
+      "Bash(git rebase *)",
+      "Bash(git worktree add *)",
+      "Bash(git checkout -b *)",
+      "Bash(git switch -c *)",
+      "Bash(git worktree remove *)",
+      "Bash(git branch -D *)",
       "Bash(git checkout main *)",
       "Bash(git switch main *)",
-      "Bash(git rebase *)",
       "Bash(git reset --hard *)",
       "Bash(git push --force *)",
-      "Bash(git push -f *)",
-      "Bash(git worktree remove --force *)"
+      "Bash(git push -f *)"
     ]
   },
   "hooks": {
diff --git a/modules/claude/module.yml b/modules/claude/module.yml
index ec279bb..7ae8a27 100644
--- a/modules/claude/module.yml
+++ b/modules/claude/module.yml
@@ -2,6 +2,6 @@
 # ----------------------------------------------------------------------------------------------------------------------
 # docs/modules.md says what each key means.
 
-description: "Claude Code: the deny list for the spellings the rules forbid, and the hook that names a file's rules before a write"
+description: "Claude Code: the deny list of the spellings the rules forbid, and the hook that names a file's rules"
 depends:
   - kit
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
index 472dc3c..aff3499 100644
--- a/modules/kit/docs/README.md
+++ b/modules/kit/docs/README.md
@@ -2,7 +2,7 @@
 
 The core, active in every repository that takes the kit. It places:
 
-- `.kit/1st.md`, the entry every agent reads, imported by the repository's `AGENTS.md`.
+- `.kit/1st.md`, the entry every agent reads, named by the repository's `AGENTS.md`.
 - `.kit/rules/<kind>.md`, one rule file per kind of file, each declaring in its frontmatter which paths and which
   first lines it governs.
 
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 0852482..ca4b942 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -27,7 +27,7 @@ reaches `main` only through a merged pull request.
 2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
    pull request. It never switches the checkout it is run from.
 3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`. `kit rebase`
-   brings the branch up to date with `main` and pushes it.
+   brings the branch up to date with the default branch and pushes it.
 4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
    and how, and what was left out and why.
 5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
@@ -35,13 +35,15 @@ reaches `main` only through a merged pull request.
 
 ## Spellings an agent uses
 
-Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. The rule runs inside
-it, and a harness that can refuse the raw spelling does.
+Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. Each kit spelling
+carries the check its rule requires, and a harness with a deny list refuses the raw git spelling.
 
 - `kit rebase`, never `git rebase`. It refuses the root checkout and the default branch, and otherwise rebases the
-  worktree's branch onto `origin/main` and pushes it.
+  worktree's branch onto the default branch at origin and pushes it.
 - `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
 - `kit tidy`, never `git worktree remove` or `git branch -D`.
+- The desk is never switched or reset by an agent: `git checkout main`, `git switch main`, `git reset --hard`,
+  and `git push --force` are refused as well.
 
 The human at the desk is not bound by this; the root checkout is theirs.
 
@@ -54,7 +56,8 @@ the design is written, the issue is the deliverable, and the loop above starts f
 
 A worker is whoever implements one issue in the worktree that issue names.
 
-1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints `<N>-`.
+1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints a branch name
+   beginning `<N>-`.
 2. Do every command from there. Never touch the repository root checkout.
 3. Never run `kit issue`, make a branch, or make a worktree. Those were done before the handoff.
 4. Implement what the issue asks and nothing beside it.
@@ -85,21 +88,20 @@ harness holds a copy of a rule; this call is how every harness, and every person
 
 The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
 release version, the active modules, and a checksum per delivered file. The release, where it is installed,
-carries the machinery, reached through the `kit` command on `PATH`. Everything the release delivers is a module,
-and a repository activates the modules it takes: `kit install claude`, or `kit module add claude` later, and
-`kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning only the entries
-it writes; everything else is copied as it is.
+carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
+`kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
+delivers is a module, and a repository activates the modules it takes: `kit install claude`, or `kit module add
+claude` later, and `kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning
+only the entries it writes; everything else is copied as it is.
 
-- The loop's commands, `kit issue`, `kit rebase`, `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled
-  that way and no other.
 - `kit`: this file and the rules, discovered through `kit context`.
 - `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
 - `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
   refuses a pull request not linked to an open issue.
 - `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
-  importing `AGENTS.md`, so it is read in every case; seven deny rules merged into `.claude/settings.json`; and a
-  hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
+  importing `AGENTS.md`, so it is read in every case; the deny list above merged into `.claude/settings.json`; and
+  a hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/modules/kit/files/repo/.kit/rules/bash.md b/modules/kit/files/repo/.kit/rules/bash.md
index e04e9b0..2d23371 100644
--- a/modules/kit/files/repo/.kit/rules/bash.md
+++ b/modules/kit/files/repo/.kit/rules/bash.md
@@ -14,7 +14,8 @@ workflows.
 ## Shape
 
 1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
-   rule of dashes to column 120, and a blank line, then `set -o errexit -o nounset -o pipefail`.
+   rule of dashes to column 120, a blank line, and an optional comment paragraph, then
+   `set -o errexit -o nounset -o pipefail`.
 2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
    would change the caller's.
 3. The file closes with the same rule of dashes.
@@ -31,17 +32,19 @@ workflows.
 6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
 8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
-   loader's own verbs are the exception and stay bare: `use`, `info`, `step`, `ok`, `section`, `warn`, `error`.
+   loader, `1st.sh`, is the exception: its verbs stay bare, `use`, `info`, `step`, `ok`, `section`, `warn`,
+   `error`, and `summary`, and its helpers are the `out:` and `guard:` families.
 9. A function private to one executed script is bare kebab-case.
 
 ## Behavior
 
-1. An error message is one line, names the remedy first, and is the same wherever the same condition arises.
+1. An error message is one line, names the remedy where there is one, and is the same wherever the same
+   condition arises.
 2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
 3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
 4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
 5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
-   to do, and a `--dry-run` where the mutation is a sweep.
+   to do, and a `--dry-run` where the mutation removes work, as a sweep of worktrees or branches does.
 6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
 7. shellcheck passes with no directive, or the directive carries the reason on the same line.
 
diff --git a/modules/kit/files/repo/.kit/rules/gitignore.md b/modules/kit/files/repo/.kit/rules/gitignore.md
index 7465b65..f1278c4 100644
--- a/modules/kit/files/repo/.kit/rules/gitignore.md
+++ b/modules/kit/files/repo/.kit/rules/gitignore.md
@@ -23,7 +23,7 @@ Applies to `.gitignore` at any depth.
 2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
    repository.
 3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
-4. `worktrees/` is ignored at the root: it is where the loop checks out a branch per issue.
+4. Ignore `/worktrees/` at the root: it is where the loop checks out a branch per issue.
 
 ## Adding one
 
diff --git a/modules/kit/files/repo/.kit/rules/json.md b/modules/kit/files/repo/.kit/rules/json.md
index 692c8aa..f89871b 100644
--- a/modules/kit/files/repo/.kit/rules/json.md
+++ b/modules/kit/files/repo/.kit/rules/json.md
@@ -18,8 +18,8 @@ Applies to `*.json` and `*.jsonc`.
 ## Settings
 
 1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
-2. A tool's settings file that the kit writes into is merged by key. The kit owns only the keys and entries
-   it writes, and anything else in the file is the repository's.
+2. Do not edit an entry the kit wrote in a merged settings file; change it through a release and `kit update`.
+   Everything else in the file is the repository's to edit.
 
 ## Comments
 
diff --git a/modules/kit/files/repo/.kit/rules/just.md b/modules/kit/files/repo/.kit/rules/just.md
index 69f6620..af77933 100644
--- a/modules/kit/files/repo/.kit/rules/just.md
+++ b/modules/kit/files/repo/.kit/rules/just.md
@@ -41,11 +41,12 @@ applies to it as well.
 
 ## Recipes
 
-1. Every recipe carries `[doc("<emoji> <short, action-first description>")]`. Related recipes share an emoji.
+1. Every recipe but the default-and-help pair carries `[doc("<emoji> <short, action-first description>")]`.
+   Related recipes share an emoji.
 2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
    recipe does, when to run it, and what it produces.
 3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
-4. Non-trivial logic lives in a bash module the recipe loads, not in the body. The body stays a few lines.
+4. A body says what runs. Logic longer than a dozen lines lives in a bash script the body calls.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
    variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
    `${name}` and nothing else.
diff --git a/modules/kit/files/repo/.kit/rules/markdown.md b/modules/kit/files/repo/.kit/rules/markdown.md
index d830ce3..7afc056 100644
--- a/modules/kit/files/repo/.kit/rules/markdown.md
+++ b/modules/kit/files/repo/.kit/rules/markdown.md
@@ -33,7 +33,8 @@ Applies to `*.md`.
 2. Balance the wrap: no line, in particular the last, reads as a stub.
 3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
 4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
-5. Headings are ATX (`#`). One `#` heading per file, at the top.
+5. Headings are ATX (`#`). One `#` heading per file, at the top; `AGENTS.md` is the exception, opening with the
+   sentence a harness reads first.
 6. Fenced code blocks declare a language and have a blank line on each side.
 7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
 
@@ -42,7 +43,7 @@ Applies to `*.md`.
 1. Use inline links with descriptive text, never a bare URL in angle brackets.
 2. Use the same anchor text every time the same URL appears in a file.
 3. When a label and the link text would say the same thing, make the label the link.
-4. A relative link resolves from the file that carries it, and it resolves: a check reads them.
+4. A relative link resolves from the file that carries it, and it resolves.
 
 ## Files
 
@@ -50,4 +51,4 @@ Applies to `*.md`.
 2. A file says what its subject is in its first paragraph, before how to use it.
 3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
    what the repository is.
-4. No file names another repository as the source of a rule.
+4. A delivered file names no repository as the source of a rule.
diff --git a/modules/kit/files/repo/.kit/rules/yaml.md b/modules/kit/files/repo/.kit/rules/yaml.md
index 3e5795c..69993c7 100644
--- a/modules/kit/files/repo/.kit/rules/yaml.md
+++ b/modules/kit/files/repo/.kit/rules/yaml.md
@@ -6,7 +6,8 @@ paths:
 ---
 # YAML
 
-Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
+Applies to `*.yml` and `*.yaml`. Shape and Steps apply to GitHub Actions workflows, under `.github/workflows/`;
+Comments apply to every YAML file.
 
 ## Shape
 
@@ -23,9 +24,9 @@ Applies to `*.yml` and `*.yaml`, which here means GitHub Actions workflows.
 1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
 2. A step has a `name` that is the policy it enforces, in kebab-case.
 3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>`, writes `### ❌ <Message>` and a remedy to `${GITHUB_STEP_SUMMARY}`,
-   and returns non-zero. The remedy is the action to take, with a link that is that action.
-5. A pass writes one `✅` line to the summary.
+4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
+   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
+5. A step whose verdict a reader looks for writes one `✅` line to the summary.
 6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
 7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
 
diff --git a/modules/module.schema.json b/modules/module.schema.json
index add8873..75c4299 100644
--- a/modules/module.schema.json
+++ b/modules/module.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/empowerite/kit/modules/module.schema.json",
   "title": "module.yml",
-  "description": "The metadata of one kit module: modules/<name>/module.yml. docs/modules.md says what each key means. The gate validates every module.yml against this file, and kit install refuses a module whose keys it does not know.",
+  "description": "The metadata of one kit module, modules/<name>/module.yml; docs/modules.md says what each key means.",
   "type": "object",
   "additionalProperties": false,
   "required": ["description"],
@@ -15,7 +15,7 @@
     },
     "default": {
       "type": "boolean",
-      "description": "true for a module active unless removed; kit install with no names activates every default module."
+      "description": "true for a module active unless removed; kit install activates every default module."
     },
     "depends": {
       "type": "array",
diff --git a/tests/context.bats b/tests/context.bats
index 5cd955c..1314280 100644
--- a/tests/context.bats
+++ b/tests/context.bats
@@ -4,8 +4,8 @@
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
-  export KIT_HOME="${BATS_TEST_TMPDIR}/home"
-  mkdir -p "${KIT_HOME}"
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   repo=$(mktemp -d)
   git -C "${repo}" init --quiet --initial-branch=main
   cd "${repo}"
@@ -36,6 +36,13 @@ teardown() {
   [ "${#lines[@]}" -eq 2 ]
 }
 
+@test "a relative path is taken from the directory the command was typed in" {
+  mkdir docs && cd docs
+  run "${kit_checkout}/bin/kit" context x.md
+  [ "$output" = ".kit/rules/markdown.md" ]
+  [ "$(cut -f 2 ../.git/kit/context.log)" = "docs/x.md" ]
+}
+
 @test "the json answer is one object per path, and every ask is logged" {
   run "${kit_checkout}/bin/kit" context --json justfile README.md
   [ "$status" -eq 0 ]
@@ -45,13 +52,15 @@ teardown() {
 }
 
 @test "the claude hook names the rules of the file about to be written, and nothing for a file none governs" {
-  input='{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"'"${PWD}"'/lib/run.sh","content":""}}'
+  input=$(printf '{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"%s/lib/run.sh"}}' "${PWD}")
   run "${kit_checkout}/bin/kit" context --claude <<<"${input}"
   [ "$status" -eq 0 ]
   [ "$(jq -r .hookSpecificOutput.hookEventName <<<"$output")" = "PreToolUse" ]
-  [ "$(jq -r .hookSpecificOutput.additionalContext <<<"$output")" = "kit: lib/run.sh is governed by .kit/rules/bash.md; read it before this change." ]
+  [ "$(jq -r .hookSpecificOutput.additionalContext <<<"$output")" \
+    = "kit: lib/run.sh is governed by .kit/rules/bash.md; read it before this change." ]
   [ "$(cut -f 2 .git/kit/context.log)" = "lib/run.sh" ]
-  run "${kit_checkout}/bin/kit" context --claude <<<'{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"x.bin"}}'
+  input='{"session_id":"s1","tool_name":"Write","tool_input":{"file_path":"x.bin"}}'
+  run "${kit_checkout}/bin/kit" context --claude <<<"${input}"
   [ "$status" -eq 0 ]
   [ -z "$output" ]
 }
diff --git a/tests/gate.bats b/tests/gate.bats
index b3b0459..857b7e1 100644
--- a/tests/gate.bats
+++ b/tests/gate.bats
@@ -1,9 +1,11 @@
 #!/usr/bin/env bats
-# gate.bats - kit gate runs the root justfile's ci recipe, and reports a missing one as a skip and an unreadable one as a failure
+# gate.bats - kit gate runs the root justfile's ci recipe, and refuses a missing one and an unreadable one alike
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   repo=$(mktemp -d)
   cd "${repo}"
   export GITHUB_STEP_SUMMARY="${repo}/summary.md"
@@ -13,18 +15,18 @@ teardown() {
   rm -rf "${repo}"
 }
 
-@test "no justfile is a skip, said so, and not a pass" {
+@test "no justfile is refused, naming the remedy" {
   run "${kit_checkout}/bin/kit" gate
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"no root justfile, so the gate was skipped"* ]]
-  grep --quiet 'skipped' summary.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"add a root justfile with a ci recipe"* ]]
+  grep --quiet 'cannot run' summary.md
 }
 
-@test "a justfile without a ci recipe is a skip" {
+@test "a justfile without a ci recipe is refused" {
   printf 'build:\n  echo built\n' > justfile
   run "${kit_checkout}/bin/kit" gate
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"no ci recipe, so the gate was skipped"* ]]
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"add a ci recipe to the root justfile"* ]]
 }
 
 @test "a justfile that cannot be read is a failure" {
@@ -46,10 +48,4 @@ teardown() {
   [ "$status" -ne 0 ]
 }
 
-@test "linked names the pull request it needs when none can be found" {
-  run env -u GITHUB_EVENT_PATH "${kit_checkout}/bin/kit" linked
-  [ "$status" -eq 2 ]
-  [[ "$output" == *"kit linked <number>"* ]]
-}
-
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index c5f6180..6e6c628 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -10,13 +10,24 @@ setup() {
   repo=$(mktemp -d)
   git -C "${repo}" init --quiet --initial-branch=main
   # a home directory of the test's own, so no test ever writes under the real one
-  export KIT_HOME="${repo}.home"
-  mkdir "${KIT_HOME}"
+  export KIT_HOME="${repo}.home" XDG_CACHE_HOME="${repo}.cache"
+  mkdir "${KIT_HOME}" "${XDG_CACHE_HOME}"
   cd "${repo}"
 }
 
 teardown() {
-  rm -rf "${repo}" "${repo}.later" "${repo}.home"
+  rm -rf "${repo}" "${repo}.later" "${repo}.home" "${repo}.cache" "${repo}.shims"
+}
+
+# shims <tool>… puts a failing stand-in for each tool first on PATH, so a test proves a path is not taken.
+shims() {
+  local tool
+  mkdir -p "${repo}.shims"
+  for tool in "$@"
+  do
+    printf '#!/usr/bin/env bash\nexit 1\n' > "${repo}.shims/${tool}" && chmod +x "${repo}.shims/${tool}"
+  done
+  printf '%s:%s\n' "${repo}.shims" "${PATH}"
 }
 
 # later-release <dir> copies this checkout's release to <dir> as version 9.9.9 with one changed rule line.
@@ -139,7 +150,8 @@ later-release() {
 
 @test "a module delivering to home lands under it with a manifest of its own, and leaves with it" {
   later-release "${repo}.later"
-  mkdir -p "${repo}.later/modules/claude/files/home/.kit" && printf 'user level\n' > "${repo}.later/modules/claude/files/home/.kit/claude"
+  mkdir -p "${repo}.later/modules/claude/files/home/.kit"
+  printf 'user level\n' > "${repo}.later/modules/claude/files/home/.kit/claude"
   run "${repo}.later/bin/kit" install claude
   [ "$status" -eq 0 ]
   [ "$(cat "${KIT_HOME}/.kit/claude")" = "user level" ]
@@ -232,7 +244,7 @@ later-release() {
   printf 'mine\n' > .kit/rules/toml.md
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
-  [[ "$output" == *".kit/rules/toml.md is new in 9.9.9"* ]]
+  [[ "$output" == *".kit/rules/toml.md: a different file is there already"* ]]
   [ "$(cat .kit/rules/toml.md)" = "mine" ]
 }
 
@@ -248,7 +260,8 @@ later-release() {
 @test "update leaves conflict markers and fails when the same lines changed" {
   "${kit_checkout}/bin/kit" install claude
   later-release "${repo}.later"
-  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${repo}.later/modules/kit/files/repo/.kit/rules/json.md" && rm "${repo}.later/modules/kit/files/repo/.kit/rules/json.md.bak"
+  theirs="${repo}.later/modules/kit/files/repo/.kit/rules/json.md"
+  sed -i.bak 's/^# JSON$/# JSON (theirs)/' "${theirs}" && rm "${theirs}.bak"
   sed -i.bak 's/^# JSON$/# JSON (ours)/' .kit/rules/json.md && rm .kit/rules/json.md.bak
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
@@ -272,15 +285,79 @@ later-release() {
   [ "$status" -eq 0 ]
 }
 
-@test "update without the base release refuses an edited file and names the base" {
-  "${kit_checkout}/bin/kit" install claude
+@test "update without the base release refuses an edited file, names the base, and leaves the manifest's version" {
   later-release "${repo}.later"
+  "${repo}.later/bin/kit" install claude
+  grep --quiet '^version 9.9.9$' .kit/manifest
+  mkdir -p "${repo}.newer" && cp -R "${repo}.later/bin" "${repo}.later/modules" "${repo}.newer/"
+  printf '9.9.10\n' > "${repo}.newer/version"
   printf 'edited\n' >> .kit/rules/bash.md
-  # a mise that answers nothing, ahead of the real one
-  mkdir shims && printf '#!/usr/bin/env bash\nexit 1\n' > shims/mise && chmod +x shims/mise
-  run env PATH="${PWD}/shims:${PATH}" "${repo}.later/bin/kit" update
+  # neither the cache, nor mise, nor gh can produce 9.9.9
+  run env PATH="$(shims mise gh)" "${repo}.newer/bin/kit" update
   [ "$status" -eq 1 ]
-  [[ "$output" == *"cannot be updated without the base release unreleased"* ]]
+  [[ "$output" == *"could not be fetched"* ]]
+  [[ "$output" == *".kit/rules/bash.md cannot be updated without the base release 9.9.9"* ]]
+  grep --quiet '^version 9.9.9$' .kit/manifest
+  rm -rf "${repo}.newer"
+}
+
+@test "update at the same version uses the release as its own base, and a second run changes nothing" {
+  "${kit_checkout}/bin/kit" install claude
+  printf 'edited\n' >> .kit/rules/bash.md
+  run env PATH="$(shims mise gh)" "${kit_checkout}/bin/kit" update
+  [ "$status" -eq 0 ]
+  grep --quiet '^edited$' .kit/rules/bash.md
+  run env PATH="$(shims mise gh)" "${kit_checkout}/bin/kit" update
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"conflict"* ]]
+}
+
+@test "the verbs run from a subdirectory as from the root" {
+  "${kit_checkout}/bin/kit" install
+  mkdir -p docs/deep && cd docs/deep
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  run "${kit_checkout}/bin/kit" module add claude
+  [ "$status" -eq 0 ]
+  [ -f "${repo}/.claude/settings.json" ]
+  [ ! -e .claude ]
+}
+
+@test "install and module add refuse a different file at a delivered path, and accept the same one" {
+  mkdir .kit && printf 'mine\n' > .kit/1st.md
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/1st.md: a different file is there already"* ]]
+  [ ! -e .kit/manifest ]
+  [ "$(cat .kit/1st.md)" = "mine" ]
+  rm .kit/1st.md
+  "${kit_checkout}/bin/kit" install
+  mkdir .claude && printf 'theirs\n' > .claude/CLAUDE.md
+  run "${kit_checkout}/bin/kit" module add claude
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".claude/CLAUDE.md: a different file is there already"* ]]
+  grep --quiet '^modules kit ci lefthook$' .kit/manifest
+  cp "${kit_checkout}/modules/claude/files/repo/.claude/CLAUDE.md" .claude/CLAUDE.md
+  run "${kit_checkout}/bin/kit" module add claude
+  [ "$status" -eq 0 ]
+}
+
+@test "module remove judges dependents against what stays, in any order" {
+  "${kit_checkout}/bin/kit" install claude
+  run "${kit_checkout}/bin/kit" module remove kit ci lefthook claude
+  [ "$status" -eq 0 ]
+  grep --quiet '^modules$' .kit/manifest
+  [ ! -e .kit/1st.md ]
+}
+
+@test "a home manifest another repository wrote is left alone, and its surviving lines are kept" {
+  mkdir -p "${KIT_HOME}/.kit" && printf 'theirs\n' > "${KIT_HOME}/.kit/theirs"
+  digest=$(shasum -a 256 "${KIT_HOME}/.kit/theirs" | cut -d ' ' -f 1)
+  printf '# manifest\nversion 0.0.1\nmodules other\n%s  .kit/theirs\n' "${digest}" > "${KIT_HOME}/.kit/manifest"
+  "${kit_checkout}/bin/kit" install
+  [ -f "${KIT_HOME}/.kit/theirs" ]
+  grep --quiet '  .kit/theirs$' "${KIT_HOME}/.kit/manifest"
+  grep --quiet '^version 0.0.1$' "${KIT_HOME}/.kit/manifest"
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/linked.bats b/tests/linked.bats
new file mode 100644
index 0000000..87324ad
--- /dev/null
+++ b/tests/linked.bats
@@ -0,0 +1,24 @@
+#!/usr/bin/env bats
+# linked.bats - kit linked names the pull request it needs when none can be found; the rest needs GitHub
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+@test "linked names the pull request it needs when none can be found" {
+  run env -u GITHUB_EVENT_PATH "${kit_checkout}/bin/kit" linked
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"kit linked <number>"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/lint.bats b/tests/lint.bats
index 461fb11..bd09c26 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -6,6 +6,8 @@ setup() {
   lefthook version >/dev/null 2>&1 || skip "lefthook is a desk tool (mise.desk.toml, MISE_ENV=desk)"
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
   repo=$(mktemp -d)
+  export KIT_HOME="${repo}.home" XDG_CACHE_HOME="${repo}.cache"
+  mkdir "${KIT_HOME}" "${XDG_CACHE_HOME}"
   cd "${repo}"
   git init --quiet --initial-branch=main
   "${kit_checkout}/bin/kit" install >/dev/null
@@ -15,7 +17,7 @@ setup() {
 }
 
 teardown() {
-  rm -rf "${repo}"
+  rm -rf "${repo}" "${repo}.home" "${repo}.cache"
 }
 
 @test "lint refuses a staged bash file shellcheck faults, and passes a clean one" {
diff --git a/tests/rebase.bats b/tests/rebase.bats
index f02f194..6ec8635 100644
--- a/tests/rebase.bats
+++ b/tests/rebase.bats
@@ -4,6 +4,8 @@
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   work=$(mktemp -d)
   cd "${work}"
   git init --quiet --bare --initial-branch=main origin.git
@@ -36,11 +38,11 @@ commit-in() {
 @test "rebase refuses the root checkout, whatever branch it has" {
   run "${kit_checkout}/bin/kit" rebase
   [ "$status" -eq 1 ]
-  [[ "$output" == *"refusing to rebase main: it is checked out at the root"* ]]
+  [[ "$output" == *"refusing to rebase main: it is the root checkout"* ]]
   git switch --quiet --create desk-topic
   run "${kit_checkout}/bin/kit" rebase
   [ "$status" -eq 1 ]
-  [[ "$output" == *"refusing to rebase desk-topic: it is checked out at the root"* ]]
+  [[ "$output" == *"refusing to rebase desk-topic: it is the root checkout"* ]]
 }
 
 @test "rebase refuses the default branch in a worktree" {
diff --git a/tests/release.bats b/tests/release.bats
index 6529eb4..2307876 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -4,8 +4,8 @@
 
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
-  export KIT_HOME="${BATS_TEST_TMPDIR}/home"
-  mkdir -p "${KIT_HOME}"
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   work=$(mktemp -d)
   cd "${work}"
 }
diff --git a/tests/status.bats b/tests/status.bats
index 92ec1f8..8a3cee6 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -6,6 +6,8 @@
 setup() {
   export kit_root NO_COLOR=1
   kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   work=$(mktemp -d)
   cd "${work}"
   git init --quiet --bare --initial-branch=main origin.git
@@ -21,9 +23,9 @@ teardown() {
   rm -rf "${work}"
 }
 
-# in_status <command>… runs a command with the status module loaded.
+# in_status <command>… runs a command with the status module loaded, from this directory, as a verb would.
 in_status() {
-  bash -c 'source "${kit_root}/bin/1st.sh" && use status && "$@"' _ "$@"
+  kit_invoked_in=$(pwd -P) bash -c 'source "${kit_root}/bin/1st.sh" && use status && "$@"' _ "$@"
 }
 
 # commits-in <path> <n> makes <n> commits in the checkout at <path>.
@@ -31,7 +33,8 @@ commits-in() {
   local i
   for (( i = 1; i <= $2; i++ ))
   do
-    printf '%s\n' "${i}" > "$1/f${i}" && git -C "$1" add . && git -C "$1" commit --quiet --message "c${i}"
+    printf '%s\n' "${i}" > "$1/f${i}"
+    git -C "$1" add . && git -C "$1" commit --quiet --message "c${i}"
   done
 }
 
@@ -44,13 +47,14 @@ commits-in() {
 
 @test "a checkout is measured from where its branch left origin's default branch" {
   git worktree add --quiet -b topic worktrees/topic main
-  printf 'two\nthree\n' > worktrees/topic/b && git -C worktrees/topic add b && git -C worktrees/topic commit --quiet --message two
+  printf 'two\nthree\n' > worktrees/topic/b
+  git -C worktrees/topic add b && git -C worktrees/topic commit --quiet --message two
   printf 'four\n' > c && git add c && git commit --quiet --message four && git push --quiet origin main
   printf 'x\n' > worktrees/topic/x
   run in_status status:checkout "${PWD}/worktrees/topic" topic main
   [ "$status" -eq 0 ]
-  [ "$(jq -r '[.relative, .branch, .ahead, .behind, .added, .removed, .uncommitted, (.commits | length)] | @tsv' <<<"$output")" \
-    = "$(printf 'worktrees/topic\ttopic\t1\t1\t2\t0\t1\t1')" ]
+  fields='[.relative, .branch, .ahead, .behind, .added, .removed, .uncommitted, (.commits | length)] | @tsv'
+  [ "$(jq -r "${fields}" <<<"$output")" = "$(printf 'worktrees/topic\ttopic\t1\t1\t2\t0\t1\t1')" ]
 }
 
 @test "a block shows the newest commits, counts the hidden ones, and ends with the oldest" {
diff --git a/tests/tidy.bats b/tests/tidy.bats
index 5815f8d..01286db 100644
--- a/tests/tidy.bats
+++ b/tests/tidy.bats
@@ -6,6 +6,8 @@
 setup() {
   export kit_root
   kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   work=$(mktemp -d)
   cd "${work}"
   git init --quiet --bare --initial-branch=main origin.git
@@ -21,9 +23,29 @@ teardown() {
   rm -rf "${work}"
 }
 
-# decide <path> runs tidy's decision on <path>, a detached checkout, with main as the default branch and no dry run.
+# decide <path> runs tidy's decision on <path>, a detached checkout, with main as the default branch and no dry
+# run.
 decide() {
-  bash -c 'source "${kit_root}/bin/1st.sh" && use git && git:tidy-worktree "$1" "" true main "$(git rev-parse --show-toplevel)" false' _ "$1"
+  bash -c 'source "${kit_root}/bin/1st.sh" && use git \
+    && git:tidy-worktree "$1" "" true main "$(git rev-parse --show-toplevel)" false' _ "$1"
+}
+
+# fields prints every linked worktree as "<dir> <detached> [<branch>]", read the way the verbs read git:worktrees.
+fields() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use git && git:worktrees' \
+    | while IFS=$'\t' read -r path detached branch
+  do
+    printf '%s %s [%s]\n' "${path##*/}" "${detached}" "${branch}"
+  done
+}
+
+@test "the worktree list keeps a detached checkout's empty branch field where a tab read can keep it" {
+  git worktree add --quiet --detach worktrees/loose HEAD
+  git worktree add --quiet -b topic worktrees/topic HEAD
+  run fields
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"loose true []"* ]]
+  [[ "$output" == *"topic false [topic]"* ]]
 }
 
 @test "a clean detached worktree at a commit on main is removed" {

From 05c5c60056cced449f516bee87eb48a4e1f5b880 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 22:52:29 -0700
Subject: [PATCH 074/108] #5 settings.yml, modules a repository defines, and
 kit as the one default module

.kit/settings.yml replaces .kit/answers: the repository's own file, read by the kit and never written,
in the YAML subset bin/yaml.sh reads, with a module's template values under answers:. A directory
.kit/modules/<name>/ in the repository is a module in every respect, validated like a delivered one,
looked up after the release's modules, shown by kit module list with its origin, and installed,
checked, updated, and removed the same way; a rule it places is found by kit context. kit is the one
default module; ci, lefthook, and claude are named. 54 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml                  |  3 +-
 .kit/1st.md                                   |  5 +-
 .kit/manifest                                 |  4 +-
 README.md                                     |  8 +-
 bin/kit-module.sh                             |  3 +-
 bin/release.sh                                | 77 ++++++++++++++-----
 docs/architecture.md                          |  4 +-
 docs/delivery.svg                             |  4 +-
 docs/modules.md                               | 36 +++++++--
 modules/ci/docs/README.md                     |  2 +-
 modules/ci/module.yml                         |  1 -
 .../repo/.github/workflows/kit-ci.yml         |  3 +-
 modules/kit/files/repo/.kit/1st.md            |  5 +-
 modules/lefthook/module.yml                   |  1 -
 tests/kit.bats                                | 72 +++++++++++++----
 15 files changed, 166 insertions(+), 62 deletions(-)

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index dd17640..3b80555 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -8,7 +8,8 @@
 # repository under Development. The last two run even when an earlier step refused, so one run reports every
 # finding.
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner answer.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
+# answer, from answers: in .kit/settings.yml.
 #
 # see: .kit/1st.md
 
diff --git a/.kit/1st.md b/.kit/1st.md
index ca4b942..6ae13cc 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -90,8 +90,9 @@ The repository carries the text: this file, the rules under `.kit/rules/`, and `
 release version, the active modules, and a checksum per delivered file. The release, where it is installed,
 carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
 `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
-delivers is a module, and a repository activates the modules it takes: `kit install claude`, or `kit module add
-claude` later, and `kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning
+delivers is a module, and a repository activates the modules it takes: `kit install ci lefthook claude`, or
+`kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
+lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
 only the entries it writes; everything else is copied as it is.
 
 - `kit`: this file and the rules, discovered through `kit context`.
diff --git a/.kit/manifest b/.kit/manifest
index 95b2052..d654338 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,8 +3,8 @@ version unreleased
 modules kit ci claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-cb71018c09692cca80de7212de73fd7460a60ec523bff9b3c150ce169d1c6eb8  .github/workflows/kit-ci.yml
-db619b465a7962c55205582fc5e7a8a54378a554114c45f752b6f8fb58344cf4  .kit/1st.md
+1514237751977c53841fa424cf75ffc5efa1bbc5f99d8af2fea13fa5009b169a  .github/workflows/kit-ci.yml
+c3d44271cc463c355fbb487a86531e45ad24b8284728800c7f54869868c18551  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 8c512e3f5951b5263c140500fb2494c45f92394b44ec643cc8d6475736f5ab11  .kit/rules/bash.md
 17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
diff --git a/README.md b/README.md
index 0f1796e..ed3a5c4 100644
--- a/README.md
+++ b/README.md
@@ -62,9 +62,9 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
 
 ## Take the kit
 
-- In the repository, run `kit install`. It activates the default modules, `kit`, `lefthook`, and `ci`, and writes
-  their files and `.kit/manifest`. Add the Claude Code adapter with `kit install claude`, or later with
-  `kit module add claude`.
+- In the repository, run `kit install` with the modules it should take. `kit`, the entry file and the rules, is
+  always in; `ci` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the Claude Code
+  adapter. `kit install ci lefthook claude` takes all three, and `kit module add` takes one later.
 - Point `AGENTS.md` at the entry file, in prose, the same sentence for every agent:
 
   ```markdown
@@ -147,6 +147,8 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
+`.kit/settings.yml` is this repository's own, and `.kit/modules/` would hold modules of its own; it has none.
+
 A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the pre-commit
 hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk without the
 hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names any installed
diff --git a/bin/kit-module.sh b/bin/kit-module.sh
index 78da8c7..e143546 100755
--- a/bin/kit-module.sh
+++ b/bin/kit-module.sh
@@ -29,7 +29,8 @@ case "${verb}" in
       then mark='✅'
       else mark='  '
       fi
-      printf '%s %-10s %s\n' "${mark}" "${module}" "$(release:description "${kit_root}" "${module}")"
+      printf '%s %-10s %-10s %s\n' "${mark}" "${module}" "$(release:origin "${kit_root}" "${module}")" \
+        "$(release:description "${kit_root}" "${module}")"
     done
     ;;
   (add)
diff --git a/bin/release.sh b/bin/release.sh
index 4e06745..9daef76 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -6,9 +6,12 @@
 #
 # A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
 # mirrored at the base's root; and templates/<base>/, with @key@ rendered from the repository's answers, then
-# mirrored the same way. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's
-# home directory, recorded in ~/.kit/manifest, which every repository on the desk shares. A destination ending
-# in .json is merged by key, the kit owning only the entries it writes. docs/modules.md is the format's description.
+# mirrored the same way. A repository defines modules of its own the same way under .kit/modules/<name>/, and
+# a name is looked up in the release first, then there. Two bases: repo, the repository root, recorded in
+# .kit/manifest; and home, the user's home directory, recorded in ~/.kit/manifest, which every repository on the
+# desk shares. A destination ending in .json is merged by key, the kit owning only the entries it writes. The
+# repository's choices live in .kit/settings.yml, which the kit reads and never writes. docs/modules.md is the
+# format's description.
 #
 # Every function reads a release from a root, kit_root by default, which bin/kit exports. bin/kit also moves to
 # the repository root, so .kit/manifest and every repo path here are relative to it. Every sort and comm here
@@ -51,14 +54,45 @@ release:dest() {
 # release:manifest <base> prints the base's manifest: .kit/manifest in the repository, ~/.kit/manifest for home.
 release:manifest() { release:dest "$1" .kit/manifest; }
 
-# release:modules [<root>] prints the modules the release carries: every modules/<name>/ with a module.yml.
+# release_local is where a repository keeps modules of its own: .kit/modules/<name>/, in the release's shape.
+declare -gr release_local=.kit
+
+# release:settings prints the repository's settings file, which the kit reads and never writes.
+release:settings() { printf '.kit/settings.yml\n'; }
+
+# release:setting <key> prints the value of one top-level setting, or nothing.
+release:setting() { yaml:value "$(release:settings)" "$1"; }
+
+# release:modules [<root>] prints the modules in reach: every modules/<name>/ with a module.yml under the release
+# at <root>, and under .kit/modules/ in the repository.
 release:modules() {
-  (cd "${1:-${kit_root}}/modules" \
-    && find . -mindepth 2 -maxdepth 2 -name module.yml | sed 's@^\./@@; s@/module.yml$@@' | LC_ALL=C sort)
+  local root=${1:-${kit_root}} dir
+  for dir in "${root}" "${release_local}"
+  do
+    [[ -d "${dir}/modules" ]] || continue
+    (cd "${dir}/modules" && find . -mindepth 2 -maxdepth 2 -name module.yml | sed 's@^\./@@; s@/module.yml$@@')
+  done | LC_ALL=C sort --unique
+}
+
+# release:home <root> <module> prints where the module lives: the release at <root> when it carries the module,
+# else the repository's own .kit, so a path under it is <home>/modules/<module>/.
+release:home() {
+  if [[ -f "$1/modules/$2/module.yml" || ! -f "${release_local}/modules/$2/module.yml" ]]
+  then printf '%s\n' "$1"
+  else printf '%s\n' "${release_local}"
+  fi
+}
+
+# release:origin <root> <module> prints "release" or "repository", where the module comes from.
+release:origin() {
+  if [[ "$(release:home "$1" "$2")" == "$1" ]]
+  then printf 'release\n'
+  else printf 'repository\n'
+  fi
 }
 
 # release:meta <root> <module> prints the path of the module's metadata.
-release:meta() { printf '%s/modules/%s/module.yml\n' "$1" "$2"; }
+release:meta() { printf '%s/modules/%s/module.yml\n' "$(release:home "$1" "$2")" "$2"; }
 
 # release:description <root> <module> prints the module's one-line description.
 release:description() { yaml:value "$(release:meta "$1" "$2")" description; }
@@ -84,7 +118,7 @@ release:require-modules() {
   do
     if [[ ! -f "$(release:meta "${root}" "${module}")" ]]
     then
-      error "'${module}' is not a module this release knows; the modules are:" \
+      error "'${module}' is not a module in reach; the modules are:" \
         "$(release:modules "${root}" | paste -s -d ' ' -)"
       return 2
     fi
@@ -160,39 +194,38 @@ release:validate() {
     case "${key}" in
       (description | default | depends | answers) ;;
       (*)
-        error "modules/${module}/module.yml has a key the kit does not know: ${key} (see modules/module.schema.json)"
+        error "$(release:meta "${root}" "${module}") has a key the kit does not know: ${key} (see modules/module.schema.json)"
         return 1
     esac
   done
   if [[ -z "$(yaml:value "${meta}" description)" ]]
   then
-    error "modules/${module}/module.yml has no description"
+    error "$(release:meta "${root}" "${module}") has no description"
     return 1
   fi
   value=$(yaml:value "${meta}" default)
   if [[ -n "${value}" && "${value}" != true && "${value}" != false ]]
   then
-    error "modules/${module}/module.yml: default must be true or false, not '${value}'"
+    error "$(release:meta "${root}" "${module}"): default must be true or false, not '${value}'"
     return 1
   fi
   for dep in $(release:depends "${root}" "${module}")
   do
     if [[ ! -f "$(release:meta "${root}" "${dep}")" ]]
     then
-      error "modules/${module}/module.yml depends on '${dep}', which this release does not carry"
+      error "$(release:meta "${root}" "${module}") depends on '${dep}', which is not in reach"
       return 1
     fi
   done
 }
 
 # release:answers <root> <module> prints "<key>\t<value>" for every answer the module's templates may use: the
-# module's defaults under answers:, each overridden by a "<key> <value>" line in the repository's .kit/answers.
+# module's defaults under its answers:, each overridden by the repository's, under answers: in .kit/settings.yml.
 release:answers() {
   {
-    yaml:map "$(release:meta "$1" "$2")" answers | tr '\t' ' '
-    [[ -f .kit/answers ]] && grep --invert-match '^#' .kit/answers
-    true
-  } | awk 'NF >= 2 { v = $0; sub(/^[^ ]+ +/, "", v); a[$1] = v } END { for (k in a) print k "\t" a[k] }'
+    yaml:map "$(release:meta "$1" "$2")" answers
+    yaml:map "$(release:settings)" answers
+  } | awk -F '\t' '{ a[$1] = $2 } END { for (k in a) print k "\t" a[k] }'
 }
 
 # release:tmp prints a directory for this process's rendered templates, made once and removed at exit. The
@@ -211,8 +244,9 @@ release:tmp() {
 # directory holding them, or prints nothing where the module has none. A key is written @key@, autoconf's form,
 # which neither bash's ${var} nor GitHub's ${{ }} can be mistaken for; one with no answer refuses, naming the key.
 release:render() {
-  local root=$1 module=$2 base=$3 templates="$1/modules/$2/templates/$3" out key value text file rel
+  local root=$1 module=$2 base=$3 templates out key value text file rel
   local -A answer=()
+  templates="$(release:home "${root}" "${module}")/modules/${module}/templates/${base}"
   [[ -d "${templates}" ]] || return 0
   out="$(release:tmp)/$(printf '%s' "${root}" | release:digest)/${module}/${base}"
   if [[ ! -d "${out}" ]]
@@ -229,7 +263,7 @@ release:render() {
       do
         if [[ -z "${answer[${key}]+x}" ]]
         then
-          error "${rel} needs an answer for '${key}'; add a line '${key} <value>' to .kit/answers (module ${module})"
+          error "${rel} needs an answer for '${key}'; add '${key}: <value>' under answers: in .kit/settings.yml (module ${module})"
           return 1
         fi
         text=${text//"@${key}@"/"${answer[${key}]}"}
@@ -256,7 +290,7 @@ release:render-all() {
   do
     for kind in files templates
     do
-      for base in $(cd "${root}/modules/${module}/${kind}" 2>/dev/null \
+      for base in $(cd "$(release:home "${root}" "${module}")/modules/${module}/${kind}" 2>/dev/null \
         && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@')
       do
         # shellcheck disable=SC2046  # the bases are single words
@@ -286,7 +320,8 @@ release:layers() {
   shift 2
   for module in "$@"
   do
-    [[ -d "${root}/modules/${module}/files/${base}" ]] && printf '%s\n' "${root}/modules/${module}/files/${base}"
+    [[ -d "$(release:home "${root}" "${module}")/modules/${module}/files/${base}" ]] \
+      && printf '%s\n' "$(release:home "${root}" "${module}")/modules/${module}/files/${base}"
     rendered=$(release:render "${root}" "${module}" "${base}")
     [[ -n "${rendered}" ]] && printf '%s\n' "${rendered}"
   done
diff --git a/docs/architecture.md b/docs/architecture.md
index 35a0635..96b8428 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -19,8 +19,8 @@ by default, which modules it depends on, and the default answers for its templat
 base's root; `templates/<base>/` is rendered first, every `@key@` replaced by an answer; `docs/` is packed with the
 release and placed in no repository. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
 
-The verbs are the only way content moves. `kit install` resolves the active set, default modules plus those named
-plus their dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
+The verbs are the only way content moves. `kit install` resolves the active set, `kit` plus those named plus their
+dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
 an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
 fails when a delivered file differs from the release's. `kit module` changes the active set. Two rules govern
 placement: a `.json` destination is merged by key, the kit owning only the entries it writes; everything else is a
diff --git a/docs/delivery.svg b/docs/delivery.svg
index 68d4d39..65f2511 100644
--- a/docs/delivery.svg
+++ b/docs/delivery.svg
@@ -59,7 +59,7 @@
   <text class="m" x="396" y="270">kit module list|add|remove</text>
   <line x1="396" y1="286" x2="644" y2="286" stroke="#a78bfa" stroke-width="1"/>
   <text class="d" x="396" y="308">resolve the active set and its depends</text>
-  <text class="d" x="396" y="326">render @key@ from .kit/answers</text>
+  <text class="d" x="396" y="326">render @key@ from .kit/settings.yml</text>
   <text class="d" x="396" y="344">merge a .json destination by key</text>
   <text class="d" x="396" y="362">copy everything else</text>
   <text class="d" x="396" y="380">digest each path into the manifest</text>
@@ -79,7 +79,7 @@
   <line x1="732" y1="244" x2="1000" y2="244" stroke="#4ade80" stroke-width="1"/>
   <text class="m" x="732" y="268">.kit/manifest</text>
   <text class="d" x="856" y="268">version, modules, digests</text>
-  <text class="m" x="732" y="290">.kit/answers</text>
+  <text class="m" x="732" y="290">.kit/settings.yml</text>
   <text class="d" x="856" y="290">yours, never written</text>
   <text class="m" x="732" y="312">AGENTS.md</text>
   <text class="d" x="856" y="312">yours; names .kit/1st.md</text>
diff --git a/docs/modules.md b/docs/modules.md
index 608ae73..d28ee6d 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -43,7 +43,7 @@ answers:
 | Key | Meaning |
 | --- | --- |
 | `description` | One line, shown by `kit module list`. |
-| `default` | `true` for a module active unless removed. `kit install` with no names activates every default module. |
+| `default` | `true` for a module active unless removed. In this release, `kit` alone. |
 | `depends` | Modules activated with this one. `kit module remove` refuses a module another active module depends on. |
 | `answers` | The default value of each template key. A repository overrides one in `.kit/answers`. |
 
@@ -62,17 +62,37 @@ Where two active modules deliver the same path, the later module in dependency o
 A file under `templates/<base>/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
 answer, then the result is placed, digested, and merged exactly as a `files/` file is. The form is one neither
 bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
-answers live in `.kit/answers`, a file of `key value` lines the repository owns and the kit never writes; a key
-with no line there takes the module's default under `answers`, and a key with neither refuses the install, naming
-the key and the module.
+answers live under `answers:` in `.kit/settings.yml`; a key with none there takes the module's default under its
+own `answers`, and a key with neither refuses the install, naming the key and the module.
 
 The same YAML subset is what a rule's frontmatter is written in, read by `bin/yaml.sh` in both places, so a rule's
 `paths:` and `content:` lists and a module's `depends:` list have one reader between them.
 
+## Settings
+
+`.kit/settings.yml` is the repository's, read by the kit and never written by it, in the same YAML subset:
+
+```yaml
+answers:
+  ci_runner: ubuntu-latest
+```
+
+`answers` holds the values a module's templates take, overriding the module's own defaults. The other keys are
+the loop's choices, each described where the verb that reads it is.
+
+## Modules a repository defines
+
+A directory `.kit/modules/<name>/` in the repository is a module in every respect: `module.yml`, `files/<base>/`,
+`templates/<base>/`, and `docs/`. A name is looked up in the release first, then there. It is validated like a
+delivered module, may depend on delivered ones, is activated with `kit install <name>` or `kit module add <name>`,
+and `kit module list` shows it with its origin. Its paths are recorded in the manifest with their digests, so
+`kit check` tells an edited installed copy from its source, and `kit update` treats the module itself as its own
+base. A rule file it places under `.kit/rules/` is found by `kit context` like any other.
+
 ## Activation
 
-- `kit install [<module>…]` activates the default modules and the named ones, with their dependencies, and records
-  the set on the `modules` line of `.kit/manifest`.
+- `kit install [<module>…]` activates `kit`, the one default module, and the named ones, with their dependencies,
+  and records the set on the `modules` line of `.kit/manifest`.
 - `kit module list` shows every module the release carries and which are active.
 - `kit module add <module>…` activates more, placing only the paths the new set delivers beyond the old.
 - `kit module remove <module>…` deactivates, removing the paths only the removed modules delivered and taking the
@@ -83,8 +103,8 @@ The same YAML subset is what a rule's frontmatter is written in, read by `bin/ya
 | Module | Default | Depends on | Delivers |
 | --- | --- | --- | --- |
 | `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md` |
-| `lefthook` | yes | `kit` | `.kit/lefthook.yml` |
-| `ci` | yes | `kit` | `.github/workflows/kit-ci.yml`, from a template; answer `ci_runner` |
+| `lefthook` | no | `kit` | `.kit/lefthook.yml` |
+| `ci` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template; answer `ci_runner` |
 | `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
 
 No module in this release delivers to `home`. Each module's `docs/README.md` says what it places and why.
diff --git a/modules/ci/docs/README.md b/modules/ci/docs/README.md
index 30421ae..c4f2211 100644
--- a/modules/ci/docs/README.md
+++ b/modules/ci/docs/README.md
@@ -7,4 +7,4 @@ pinned release, and `kit linked` refuses a pull request not linked to an open is
 verb a desk can run, so the runner does nothing a person cannot repeat.
 
 The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
-a repository with runners of its own puts `ci_runner <label>` in `.kit/answers`.
+a repository with runners of its own sets `ci_runner` under `answers:` in `.kit/settings.yml`.
diff --git a/modules/ci/module.yml b/modules/ci/module.yml
index 6e90e90..eb9b047 100644
--- a/modules/ci/module.yml
+++ b/modules/ci/module.yml
@@ -3,7 +3,6 @@
 # docs/modules.md says what each key means.
 
 description: "One CI job: the repository's gate, kit check, and the refusal of a pull request without an open issue"
-default: true
 depends:
   - kit
 answers:
diff --git a/modules/ci/templates/repo/.github/workflows/kit-ci.yml b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
index ef6435c..4b058b6 100644
--- a/modules/ci/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
@@ -8,7 +8,8 @@
 # repository under Development. The last two run even when an earlier step refused, so one run reports every
 # finding.
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner answer.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
+# answer, from answers: in .kit/settings.yml.
 #
 # see: .kit/1st.md
 
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index ca4b942..6ae13cc 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -90,8 +90,9 @@ The repository carries the text: this file, the rules under `.kit/rules/`, and `
 release version, the active modules, and a checksum per delivered file. The release, where it is installed,
 carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
 `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
-delivers is a module, and a repository activates the modules it takes: `kit install claude`, or `kit module add
-claude` later, and `kit module remove` to take one back out. A `.json` destination is merged by key, the kit owning
+delivers is a module, and a repository activates the modules it takes: `kit install ci lefthook claude`, or
+`kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
+lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
 only the entries it writes; everything else is copied as it is.
 
 - `kit`: this file and the rules, discovered through `kit context`.
diff --git a/modules/lefthook/module.yml b/modules/lefthook/module.yml
index 3cc9b6b..f68ea0b 100644
--- a/modules/lefthook/module.yml
+++ b/modules/lefthook/module.yml
@@ -3,6 +3,5 @@
 # docs/modules.md says what each key means.
 
 description: "Which linter runs over which paths before a commit, for the repository's lefthook.yml to extend"
-default: true
 depends:
   - kit
diff --git a/tests/kit.bats b/tests/kit.bats
index 6e6c628..1eda34a 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -38,17 +38,21 @@ later-release() {
   printf '\n## Added in 9.9.9\n\nA new rule.\n' >> "$1/modules/kit/files/repo/.kit/rules/json.md"
 }
 
-@test "install with no module writes the default modules and nothing under .claude" {
+@test "install with no module writes the kit module and nothing else" {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
   [ -f .kit/1st.md ]
   [ -f .kit/rules/bash.md ]
-  [ -f .kit/lefthook.yml ]
-  [ -f .github/workflows/kit-ci.yml ]
-  grep --quiet '^    runs-on: "ubuntu-latest"$' .github/workflows/kit-ci.yml
+  [ ! -e .kit/lefthook.yml ]
+  [ ! -e .github ]
   [ ! -e .claude ]
   grep --quiet '^version unreleased$' .kit/manifest
-  grep --quiet '^modules kit ci lefthook$' .kit/manifest
+  grep --quiet '^modules kit$' .kit/manifest
+  run "${kit_checkout}/bin/kit" install ci
+  [ "$status" -eq 1 ]
+  run "${kit_checkout}/bin/kit" module add ci
+  [ "$status" -eq 0 ]
+  grep --quiet '^    runs-on: "ubuntu-latest"$' .github/workflows/kit-ci.yml
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   # a stray file under a module not active is nobody's business
@@ -60,7 +64,7 @@ later-release() {
 @test "install with claude adds the deny list and the context hook, and copies no rule" {
   run "${kit_checkout}/bin/kit" install claude
   [ "$status" -eq 0 ]
-  grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
+  grep --quiet '^modules kit claude$' .kit/manifest
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
   [ "$(tail -n 1 .claude/CLAUDE.md)" = "@../AGENTS.md" ]
@@ -84,7 +88,7 @@ later-release() {
   run "${kit_checkout}/bin/kit" module add claude
   [ "$status" -eq 0 ]
   jq --exit-status '.permissions.deny | index("Bash(git switch main *)")' .claude/settings.json >/dev/null
-  grep --quiet '^modules kit ci claude lefthook$' .kit/manifest
+  grep --quiet '^modules kit claude$' .kit/manifest
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   run "${kit_checkout}/bin/kit" module remove claude
@@ -93,13 +97,13 @@ later-release() {
   [ "$(jq --raw-output .model .claude/settings.json)" = "x" ]
   jq --exit-status '.permissions.deny == ["Bash(rm -rf /)"]' .claude/settings.json >/dev/null
   jq --exit-status '.hooks == {"PreToolUse": []}' .claude/settings.json >/dev/null
-  grep --quiet '^modules kit ci lefthook$' .kit/manifest
+  grep --quiet '^modules kit$' .kit/manifest
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
 }
 
 @test "module remove refuses a module another active module depends on, and removes a leaf" {
-  "${kit_checkout}/bin/kit" install claude
+  "${kit_checkout}/bin/kit" install claude ci
   run "${kit_checkout}/bin/kit" module remove kit
   [ "$status" -eq 1 ]
   [[ "$output" == *"kit cannot be removed while"* ]]
@@ -107,12 +111,12 @@ later-release() {
   run "${kit_checkout}/bin/kit" module remove ci
   [ "$status" -eq 0 ]
   [ ! -e .github/workflows/kit-ci.yml ]
-  grep --quiet '^modules kit claude lefthook$' .kit/manifest
+  grep --quiet '^modules kit claude$' .kit/manifest
 }
 
 @test "a template takes the repository's answer over the module's default, and refuses a key with neither" {
-  mkdir .kit && printf 'ci_runner blacksmith-2vcpu\n' > .kit/answers
-  run "${kit_checkout}/bin/kit" install
+  mkdir .kit && printf 'answers:\n  ci_runner: blacksmith-2vcpu\n' > .kit/settings.yml
+  run "${kit_checkout}/bin/kit" install ci
   [ "$status" -eq 0 ]
   grep --quiet '^    runs-on: "blacksmith-2vcpu"$' .github/workflows/kit-ci.yml
   grep --quiet 'uses: actions/checkout@' .github/workflows/kit-ci.yml
@@ -180,6 +184,46 @@ later-release() {
   [[ "$output" == *"home: nothing is installed under ${KIT_HOME} on this machine"* ]]
 }
 
+@test "a module the repository defines under .kit/modules installs, checks, updates, and removes like a delivered one" {
+  mkdir -p .kit/modules/python/files/repo/.kit/rules .kit/modules/python/templates/repo
+  printf 'description: "The Python rule and the tool pins"\ndepends:\n  - kit\nanswers:\n  python: "3.13"\n' \
+    > .kit/modules/python/module.yml
+  printf -- '---\npaths:\n  - "**/*.py"\n---\n# Python\n\nType everything.\n' > .kit/modules/python/files/repo/.kit/rules/python.md
+  printf 'python @python@\n' > .kit/modules/python/templates/repo/.python-version
+  run "${kit_checkout}/bin/kit" install python
+  [ "$status" -eq 0 ]
+  grep --quiet '^modules kit python$' .kit/manifest
+  [ "$(cat .python-version)" = "python 3.13" ]
+  run "${kit_checkout}/bin/kit" module list
+  [[ "$output" == *"python     repository"* ]]
+  [[ "$output" == *"kit        release"* ]]
+  run "${kit_checkout}/bin/kit" context app.py
+  [ "$output" = ".kit/rules/python.md" ]
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  printf 'edited\n' >> .kit/rules/python.md
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/rules/python.md differs"* ]]
+  printf 'answers:\n  python: "3.14"\n' > .kit/settings.yml
+  run env PATH="$(shims mise gh)" "${kit_checkout}/bin/kit" update
+  [ "$status" -eq 0 ]
+  [ "$(cat .python-version)" = "python 3.14" ]
+  grep --quiet '^edited$' .kit/rules/python.md
+  run "${kit_checkout}/bin/kit" module remove python
+  [ "$status" -eq 0 ]
+  [ ! -e .python-version ]
+  [ ! -e .kit/rules/python.md ]
+  [ -f .kit/modules/python/module.yml ]
+}
+
+@test "a module the repository defines is validated like a delivered one" {
+  mkdir -p .kit/modules/odd && printf 'description: "x"\ndependz:\n  - kit\n' > .kit/modules/odd/module.yml
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/modules/odd/module.yml has a key the kit does not know: dependz"* ]]
+}
+
 @test "install keeps the repository's own settings keys and deny entries" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
@@ -197,7 +241,7 @@ later-release() {
 }
 
 @test "check passes after install and fails on a drifted, a missing, and a lost deny entry" {
-  "${kit_checkout}/bin/kit" install claude
+  "${kit_checkout}/bin/kit" install claude lefthook
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   printf 'edited\n' >> .kit/rules/yaml.md
@@ -336,7 +380,7 @@ later-release() {
   run "${kit_checkout}/bin/kit" module add claude
   [ "$status" -eq 1 ]
   [[ "$output" == *".claude/CLAUDE.md: a different file is there already"* ]]
-  grep --quiet '^modules kit ci lefthook$' .kit/manifest
+  grep --quiet '^modules kit$' .kit/manifest
   cp "${kit_checkout}/modules/claude/files/repo/.claude/CLAUDE.md" .claude/CLAUDE.md
   run "${kit_checkout}/bin/kit" module add claude
   [ "$status" -eq 0 ]

From b6d304754ca89354b078714befe659ce9117c8b4 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 22:57:31 -0700
Subject: [PATCH 075/108] #5 kit ci as a verb, the ci-github module with a
 workflow that needs no mise, and the gate as a setting

kit ci runs the gate, kit check, and kit linked, every one even after a refusal, and exits with the
count refused, so any pipeline runs the delivered job's checks. The ci module is ci-github: its
workflow puts kit on PATH from this checkout where the manifest says unreleased and from the release
the manifest names otherwise, fetched from its public URL, and runs kit ci; mise-action runs only
where the repository has a mise.toml. kit gate runs the gate setting in .kit/settings.yml, else the
first of a justfile ci recipe, a Makefile ci target, or a package.json ci script, and refuses when
there is none. 56 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml                  | 43 ++++++------
 .kit/1st.md                                   |  7 +-
 .kit/manifest                                 |  6 +-
 README.md                                     | 15 +++--
 bin/kit                                       |  3 +-
 bin/kit-ci.sh                                 | 33 ++++++++++
 bin/kit-gate.sh                               | 65 ++++++++++++-------
 docs/architecture.md                          |  8 ++-
 docs/loop.svg                                 |  4 +-
 docs/modules.md                               |  4 +-
 modules/ci-github/docs/README.md              | 11 ++++
 modules/ci-github/module.yml                  |  9 +++
 .../repo/.github/workflows/kit-ci.yml         | 59 +++++++++++++++++
 modules/ci/docs/README.md                     | 10 ---
 modules/ci/module.yml                         |  9 ---
 .../repo/.github/workflows/kit-ci.yml         | 58 -----------------
 modules/kit/files/repo/.kit/1st.md            |  7 +-
 tests/ci.bats                                 | 36 ++++++++++
 tests/gate.bats                               | 28 ++++++--
 tests/kit.bats                                | 16 ++---
 20 files changed, 275 insertions(+), 156 deletions(-)
 create mode 100755 bin/kit-ci.sh
 create mode 100644 modules/ci-github/docs/README.md
 create mode 100644 modules/ci-github/module.yml
 create mode 100644 modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
 delete mode 100644 modules/ci/docs/README.md
 delete mode 100644 modules/ci/module.yml
 delete mode 100644 modules/ci/templates/repo/.github/workflows/kit-ci.yml
 create mode 100644 tests/ci.bats

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 3b80555..e59da51 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -1,12 +1,10 @@
-# kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
+# kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. After
-# a step that confirms kit is on PATH, three checks, each one kit command, so what the runner does a desk can do:
-# `kit gate` runs the root justfile's ci recipe and refuses when there is none, `kit check` holds every delivered
-# file to the pinned release, and `kit linked` refuses a pull request not linked to an open issue of this
-# repository under Development. The last two run even when an earlier step refused, so one run reports every
-# finding.
+# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
+# takes the kit release .kit/manifest names from its public URL, or this checkout's own bin/ where the manifest
+# says unreleased, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported. mise is used
+# only where the repository has a mise.toml, so the gate's own tools come from wherever the repository pins them.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
 # answer, from answers: in .kit/settings.yml.
@@ -34,25 +32,28 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      # Every tool below comes from mise.toml, the kit included; this repository's mise.toml puts bin/ on PATH.
       - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
+        if: ${{ hashFiles('mise.toml') != '' }}
 
       - name: kit-on-path
         run: |
-          command -v kit >/dev/null && exit 0
-          echo '::error::pin "github:empowerite/kit" in mise.toml; kit is not on PATH' && exit 1
-
-      - name: gate
-        run: kit gate
-
-      - name: kit-check
-        if: ${{ !cancelled() }}
-        run: kit check
-
-      - name: linked-open-issue
-        if: ${{ !cancelled() }}
+          set -o errexit -o nounset -o pipefail
+          version=$(sed -n 's/^version //p' .kit/manifest)
+          if [[ "${version}" == unreleased && -x bin/kit ]]
+          then
+            printf '%s/bin\n' "${PWD}" >> "${GITHUB_PATH}"
+          elif ! command -v kit >/dev/null
+          then
+            mkdir -p "${RUNNER_TEMP}/kit"
+            curl --fail --silent --location \
+              "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz" \
+              | tar --extract --gzip --directory "${RUNNER_TEMP}/kit" --strip-components 1
+            printf '%s/kit/bin\n' "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
+          fi
+
+      - name: kit-ci
         env:
           GH_TOKEN: ${{ github.token }}
-        run: kit linked
+        run: kit ci
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/1st.md b/.kit/1st.md
index 6ae13cc..578a58f 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -90,7 +90,7 @@ The repository carries the text: this file, the rules under `.kit/rules/`, and `
 release version, the active modules, and a checksum per delivered file. The release, where it is installed,
 carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
 `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
-delivers is a module, and a repository activates the modules it takes: `kit install ci lefthook claude`, or
+delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
 lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
 only the entries it writes; everything else is copied as it is.
@@ -98,8 +98,9 @@ only the entries it writes; everything else is copied as it is.
 - `kit`: this file and the rules, discovered through `kit context`.
 - `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
-- `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
-  refuses a pull request not linked to an open issue.
+- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
+  `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
+  anywhere.
 - `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
   importing `AGENTS.md`, so it is read in every case; the deny list above merged into `.claude/settings.json`; and
   a hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
diff --git a/.kit/manifest b/.kit/manifest
index d654338..f19151a 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,10 +1,10 @@
 # .kit/manifest - written by kit, not by hand
 version unreleased
-modules kit ci claude lefthook
+modules kit ci-github claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-1514237751977c53841fa424cf75ffc5efa1bbc5f99d8af2fea13fa5009b169a  .github/workflows/kit-ci.yml
-c3d44271cc463c355fbb487a86531e45ad24b8284728800c7f54869868c18551  .kit/1st.md
+24b66b6015ccf244245373009b35fc9610c52dc16d88ab6c842f21d116c74f02  .github/workflows/kit-ci.yml
+93c975792f902ea5439c062543711681468538ce837d924e4c49e730d37e8382  .kit/1st.md
 953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
 8c512e3f5951b5263c140500fb2494c45f92394b44ec643cc8d6475736f5ab11  .kit/rules/bash.md
 17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
diff --git a/README.md b/README.md
index ed3a5c4..6a623f5 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,8 @@ the checks that hold agents to them, as a versioned release any repository can t
 
 The rules are the smaller part. The point is verification that does not depend on anyone's word:
 
-- a delivered CI job that refuses a pull request without a linked open issue, and refuses to pass a gate that did
-  not run;
+- `kit ci`, which refuses a pull request without a linked open issue and refuses to pass a gate that did not
+  run, from the delivered GitHub Actions job or from any pipeline;
 - `kit check`, which holds every delivered file to its release;
 - a pre-commit hook that runs the linters over what is staged;
 - a deny list that refuses the spellings the rules forbid;
@@ -63,8 +63,9 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
 ## Take the kit
 
 - In the repository, run `kit install` with the modules it should take. `kit`, the entry file and the rules, is
-  always in; `ci` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the Claude Code
-  adapter. `kit install ci lefthook claude` takes all three, and `kit module add` takes one later.
+  always in; `ci-github` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the
+  Claude Code adapter. `kit install ci-github lefthook claude` takes all three, and `kit module add` takes one
+  later.
 - Point `AGENTS.md` at the entry file, in prose, the same sentence for every agent:
 
   ```markdown
@@ -74,7 +75,9 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
 
   The rest of `AGENTS.md` is yours.
 - Commit what `install` wrote.
-- Keep a `ci` recipe in the root justfile. The delivered `CI` job runs it and refuses when there is none.
+- Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
+  or any command as `gate` in `.kit/settings.yml`. `kit ci` runs it, with `kit check` and `kit linked`, from the
+  delivered workflow or from any pipeline of your own, and refuses when there is none.
 - Take the pre-commit linters: pin `lefthook`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run
   `lefthook install` once per clone.
 
@@ -142,7 +145,7 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | --- | --- |
 | `.kit/1st.md`, `.kit/rules/` | `modules/kit/files/repo/.kit/` |
 | `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
-| `.github/workflows/kit-ci.yml` | `modules/ci/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
+| `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
 | `.claude/CLAUDE.md` | `modules/claude/files/repo/.claude/CLAUDE.md` |
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
diff --git a/bin/kit b/bin/kit
index d398fb9..d809f8a 100755
--- a/bin/kit
+++ b/bin/kit
@@ -40,7 +40,8 @@ usage: kit <verb> [<argument>…]
   module <list|add|remove> [<module>…]
                         the modules this repository takes
   context <path>…       name the rules that govern a file, and record the ask
-  gate                  run the root justfile's ci recipe, and refuse when there is none
+  ci                    the delivered CI job's checks, anywhere: gate, check, and linked, every one reported
+  gate                  run the repository's gate, the gate setting or the detected one; refuse when there is none
   linked [<number>]     refuse a pull request not linked to an open issue of this repository
   issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
diff --git a/bin/kit-ci.sh b/bin/kit-ci.sh
new file mode 100755
index 0000000..f8fc647
--- /dev/null
+++ b/bin/kit-ci.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# kit-ci - the three checks of the delivered CI job, run anywhere: the gate, the kit's own check, and the issue link
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Every check runs even when an earlier one refused, so one run reports every finding. The exit status is the
+# number of checks that refused.
+#
+# see: bin/kit-gate.sh, bin/kit-check.sh, bin/kit-linked.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+
+if [[ "${1:-}" == --help ]]
+then
+  echo "usage: kit ci" >&2
+  exit 0
+fi
+
+refused=0
+for verb in gate check linked
+do
+  section "kit ${verb}"
+  "${kit_root}/bin/kit-${verb}.sh" || refused=$(( refused + 1 ))
+done
+if (( refused > 0 ))
+then
+  error "${refused} of 3 checks refused; see above"
+  exit "${refused}"
+fi
+ok "kit ci: the gate, the kit's check, and the issue link all passed."
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-gate.sh b/bin/kit-gate.sh
index 0934986..f294c13 100755
--- a/bin/kit-gate.sh
+++ b/bin/kit-gate.sh
@@ -1,16 +1,18 @@
 #!/usr/bin/env bash
-# kit-gate - run the repository's gate, the root justfile's ci recipe, and refuse when there is none (kit verb)
+# kit-gate - run the repository's gate, and refuse when there is none (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The delivered CI job's first step. A gate that cannot run clears nothing: a missing justfile, a justfile with no
-# ci recipe, and a justfile that cannot be read are each refused, naming the remedy. On a runner, each outcome
-# also lands in the step summary.
+# The gate is the `gate` setting in .kit/settings.yml, else the first of: a root justfile with a ci recipe, a
+# Makefile with a ci target, a package.json with a ci script. A gate that cannot run clears nothing: a repository
+# with none, or one whose justfile cannot be read, is refused, naming the remedy. On a runner, each outcome also
+# lands in the step summary.
 #
-# see: modules/ci/templates/repo/.github/workflows/kit-ci.yml
+# see: modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
 
 if [[ "${1:-}" == --help ]]
 then
@@ -18,25 +20,44 @@ then
   exit 0
 fi
 
-if [[ ! -f justfile ]]
-then
-  error "add a root justfile with a ci recipe; there is none, so the gate cannot run"
-  summary "### ❌ The gate cannot run: there is no root justfile" "" "Add a root justfile with a \`ci\` recipe."
-  exit 1
-fi
-if ! recipes=$(just --summary 2>&1)
-then
-  error "the root justfile could not be read: ${recipes}"
-  summary "### ❌ The root justfile could not be read" "" "${recipes}"
-  exit 1
-fi
-if ! tr ' ' '\n' <<<"${recipes}" | grep --quiet --line-regexp ci
+# gate:detect prints the command of the first gate found, or nothing.
+gate:detect() {
+  local recipes
+  if [[ -f justfile ]]
+  then
+    if ! recipes=$(just --summary 2>&1)
+    then
+      error "the root justfile could not be read: ${recipes}"
+      summary "### ❌ The root justfile could not be read" "" "${recipes}"
+      return 1
+    fi
+    tr ' ' '\n' <<<"${recipes}" | grep --quiet --line-regexp ci && printf 'just ci\n' && return 0
+  fi
+  if [[ -f Makefile ]] && grep --quiet '^ci:' Makefile
+  then
+    printf 'make ci\n'
+    return 0
+  fi
+  if [[ -f package.json ]] && jq --exit-status '.scripts.ci' package.json >/dev/null 2>&1
+  then
+    printf 'npm run ci\n'
+    return 0
+  fi
+  return 0
+}
+
+gate=$(release:setting gate)
+[[ -n "${gate}" ]] || gate=$(gate:detect) || exit 1
+if [[ -z "${gate}" ]]
 then
-  error "add a ci recipe to the root justfile; it has none, so the gate cannot run"
-  summary "### ❌ The gate cannot run: the root justfile has no ci recipe" "" "Add a \`ci\` recipe to it."
+  error "set gate in .kit/settings.yml, or give the root justfile a ci recipe; there is no gate to run"
+  # shellcheck disable=SC2016  # markdown code spans, not expansions
+  summary "### ❌ The gate cannot run: the repository has none" "" \
+    'Set `gate` in `.kit/settings.yml`, or give the root justfile a `ci` recipe.'
   exit 1
 fi
-just ci
-summary "✅ just ci passed."
+step "the gate: ${gate}"
+bash -c "${gate}"
+summary "✅ The gate passed: \`${gate}\`."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/docs/architecture.md b/docs/architecture.md
index 96b8428..2a7b098 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -55,9 +55,10 @@ Everything after that happens in the worktree: `kit context` before a change, `k
 hand, `kit rebase` to bring the branch onto `origin/main` and push it, and `gh pr ready` when the pull request body is
 the report.
 
-The gate is the delivered CI job, run for a pull request into the default branch: after a step that confirms
-`kit` is on `PATH`, three checks that are each one kit command. `kit gate` runs the root justfile's `ci` recipe and
-refuses when there is none, since a gate that cannot run clears nothing. `kit check` holds the delivered files to
+The gate is `kit ci`, three checks that are each one kit command, run by the delivered GitHub Actions job for a
+pull request into the default branch, or by any pipeline. `kit gate` runs the repository's gate, the `gate`
+setting or the detected justfile recipe, Makefile target, or package.json script, and refuses when there is none,
+since a gate that cannot run clears nothing. `kit check` holds the delivered files to
 the release. `kit linked` refuses a pull request not linked to an open issue of the repository. A human merges, and
 `kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: the desk, every
 worktree with its commits past the fork, and every open pull request with its state, age, and checks.
@@ -69,6 +70,7 @@ worktree with its commits past the fork, and every open pull request with its st
 | A delivered file is the release's | `kit check`, in the gate and on a desk, against the release's files and the manifest's version |
 | A change has an issue | `kit linked` in the gate; `kit issue` makes the link when it starts the work |
 | The repository's own gate ran | `kit gate`, which refuses when there is no gate to run |
+| All three held, wherever CI runs | `kit ci`, the three checks as one verb, every one reported |
 | A file's rules were named to the agent | the Claude Code hook; `kit context` in every other harness |
 | A file's rules were asked for | `.git/kit/context.log`, one line per ask |
 | The forbidden spellings were not used | the harness's deny list, delivered by its adapter module |
diff --git a/docs/loop.svg b/docs/loop.svg
index 342c8a0..bcdd950 100644
--- a/docs/loop.svg
+++ b/docs/loop.svg
@@ -55,10 +55,10 @@
 
   <!-- gate -->
   <rect class="box" x="736" y="40" width="280" height="250" fill="#ede9fe"/>
-  <text class="h" x="752" y="68">The gate</text>
+  <text class="h" x="752" y="68">The gate: kit ci</text>
   <text class="d" x="752" y="92">The delivered CI job, on every pull request:</text>
   <text class="m" x="752" y="118">kit gate</text>
-  <text class="d" x="752" y="136">the root justfile's ci recipe, or a skip said so</text>
+  <text class="d" x="752" y="136">the gate setting, or the one detected</text>
   <text class="m" x="752" y="162">kit check</text>
   <text class="d" x="752" y="180">every delivered file matches the release</text>
   <text class="m" x="752" y="206">kit linked</text>
diff --git a/docs/modules.md b/docs/modules.md
index d28ee6d..81a15af 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -32,7 +32,7 @@ bases listed. `KIT_HOME` stands in for the home directory, which is how the test
 A line starting with `#` is a comment.
 
 ```yaml
-description: "One CI job: the repository's gate, kit check, and the linked-open-issue refusal"
+description: "One GitHub Actions job that runs kit ci"
 default: true
 depends:
   - kit
@@ -104,7 +104,7 @@ base. A rule file it places under `.kit/rules/` is found by `kit context` like a
 | --- | --- | --- | --- |
 | `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md` |
 | `lefthook` | no | `kit` | `.kit/lefthook.yml` |
-| `ci` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template; answer `ci_runner` |
+| `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
 | `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
 
 No module in this release delivers to `home`. Each module's `docs/README.md` says what it places and why.
diff --git a/modules/ci-github/docs/README.md b/modules/ci-github/docs/README.md
new file mode 100644
index 0000000..c1c7a4c
--- /dev/null
+++ b/modules/ci-github/docs/README.md
@@ -0,0 +1,11 @@
+# The ci-github module
+
+Places `.github/workflows/kit-ci.yml`: one GitHub Actions job, `CI`, run for a pull request into the default
+branch. It puts `kit` on `PATH`, from this checkout where `.kit/manifest` says `unreleased` and from the release
+the manifest names otherwise, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported.
+
+mise is used only where the repository has a `mise.toml`. A repository that pins its tools another way gives the
+gate its tools its own way, and a repository on another CI calls `kit ci` from its own pipeline.
+
+The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
+a repository with runners of its own sets `ci_runner` under `answers:` in `.kit/settings.yml`.
diff --git a/modules/ci-github/module.yml b/modules/ci-github/module.yml
new file mode 100644
index 0000000..76ad45e
--- /dev/null
+++ b/modules/ci-github/module.yml
@@ -0,0 +1,9 @@
+# modules/ci-github/module.yml - the ci-github module: one GitHub Actions job that runs kit ci
+# ----------------------------------------------------------------------------------------------------------------------
+# docs/modules.md says what each key means.
+
+description: "One GitHub Actions job that runs kit ci: the gate, kit check, and the linked-open-issue refusal"
+depends:
+  - kit
+answers:
+  ci_runner: ubuntu-latest
diff --git a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
new file mode 100644
index 0000000..9f0d39b
--- /dev/null
+++ b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
@@ -0,0 +1,59 @@
+# kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
+# takes the kit release .kit/manifest names from its public URL, or this checkout's own bin/ where the manifest
+# says unreleased, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported. mise is used
+# only where the repository has a mise.toml, so the gate's own tools come from wherever the repository pins them.
+#
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
+# answer, from answers: in .kit/settings.yml.
+#
+# see: .kit/1st.md
+
+name: kit
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+jobs:
+  CI:
+    if: github.event.pull_request.base.ref == github.event.repository.default_branch
+    runs-on: "@ci_runner@"
+    env:
+      # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
+      MISE_ENV: ci
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
+        if: ${{ hashFiles('mise.toml') != '' }}
+
+      - name: kit-on-path
+        run: |
+          set -o errexit -o nounset -o pipefail
+          version=$(sed -n 's/^version //p' .kit/manifest)
+          if [[ "${version}" == unreleased && -x bin/kit ]]
+          then
+            printf '%s/bin\n' "${PWD}" >> "${GITHUB_PATH}"
+          elif ! command -v kit >/dev/null
+          then
+            mkdir -p "${RUNNER_TEMP}/kit"
+            curl --fail --silent --location \
+              "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz" \
+              | tar --extract --gzip --directory "${RUNNER_TEMP}/kit" --strip-components 1
+            printf '%s/kit/bin\n' "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
+          fi
+
+      - name: kit-ci
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: kit ci
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/ci/docs/README.md b/modules/ci/docs/README.md
deleted file mode 100644
index c4f2211..0000000
--- a/modules/ci/docs/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# The ci module
-
-Places `.github/workflows/kit-ci.yml`: one job, `CI`, run for a pull request into the default branch. After a
-step that confirms `kit` is on `PATH`, three checks, each one kit command: `kit gate` runs the repository's
-`just ci` and refuses when the root justfile has no `ci` recipe, `kit check` holds every delivered file to the
-pinned release, and `kit linked` refuses a pull request not linked to an open issue of the repository. Each is a
-verb a desk can run, so the runner does nothing a person cannot repeat.
-
-The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
-a repository with runners of its own sets `ci_runner` under `answers:` in `.kit/settings.yml`.
diff --git a/modules/ci/module.yml b/modules/ci/module.yml
deleted file mode 100644
index eb9b047..0000000
--- a/modules/ci/module.yml
+++ /dev/null
@@ -1,9 +0,0 @@
-# modules/ci/module.yml - the ci module: one CI job, the gate, kit check, and the linked-open-issue refusal
-# ----------------------------------------------------------------------------------------------------------------------
-# docs/modules.md says what each key means.
-
-description: "One CI job: the repository's gate, kit check, and the refusal of a pull request without an open issue"
-depends:
-  - kit
-answers:
-  ci_runner: ubuntu-latest
diff --git a/modules/ci/templates/repo/.github/workflows/kit-ci.yml b/modules/ci/templates/repo/.github/workflows/kit-ci.yml
deleted file mode 100644
index 4b058b6..0000000
--- a/modules/ci/templates/repo/.github/workflows/kit-ci.yml
+++ /dev/null
@@ -1,58 +0,0 @@
-# kit-ci.yml - the check the kit delivers: the repository's gate, the kit's own check, and the issue link
-# ----------------------------------------------------------------------------------------------------------------------
-#
-# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. After
-# a step that confirms kit is on PATH, three checks, each one kit command, so what the runner does a desk can do:
-# `kit gate` runs the root justfile's ci recipe and refuses when there is none, `kit check` holds every delivered
-# file to the pinned release, and `kit linked` refuses a pull request not linked to an open issue of this
-# repository under Development. The last two run even when an earlier step refused, so one run reports every
-# finding.
-#
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
-# answer, from answers: in .kit/settings.yml.
-#
-# see: .kit/1st.md
-
-name: kit
-
-on:
-  pull_request:
-    types: [opened, edited, reopened, synchronize]
-
-permissions:
-  contents: read
-  issues: read
-  pull-requests: read
-
-jobs:
-  CI:
-    if: github.event.pull_request.base.ref == github.event.repository.default_branch
-    runs-on: "@ci_runner@"
-    env:
-      # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
-      MISE_ENV: ci
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
-
-      # Every tool below comes from mise.toml, the kit included; this repository's mise.toml puts bin/ on PATH.
-      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
-
-      - name: kit-on-path
-        run: |
-          command -v kit >/dev/null && exit 0
-          echo '::error::pin "github:empowerite/kit" in mise.toml; kit is not on PATH' && exit 1
-
-      - name: gate
-        run: kit gate
-
-      - name: kit-check
-        if: ${{ !cancelled() }}
-        run: kit check
-
-      - name: linked-open-issue
-        if: ${{ !cancelled() }}
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: kit linked
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 6ae13cc..578a58f 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -90,7 +90,7 @@ The repository carries the text: this file, the rules under `.kit/rules/`, and `
 release version, the active modules, and a checksum per delivered file. The release, where it is installed,
 carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
 `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
-delivers is a module, and a repository activates the modules it takes: `kit install ci lefthook claude`, or
+delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
 lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
 only the entries it writes; everything else is copied as it is.
@@ -98,8 +98,9 @@ only the entries it writes; everything else is copied as it is.
 - `kit`: this file and the rules, discovered through `kit context`.
 - `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
-- `ci`: `.github/workflows/kit-ci.yml`, one `CI` job that runs the repository's `just ci`, runs `kit check`, and
-  refuses a pull request not linked to an open issue.
+- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
+  `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
+  anywhere.
 - `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
   importing `AGENTS.md`, so it is read in every case; the deny list above merged into `.claude/settings.json`; and
   a hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
diff --git a/tests/ci.bats b/tests/ci.bats
new file mode 100644
index 0000000..d08bee6
--- /dev/null
+++ b/tests/ci.bats
@@ -0,0 +1,36 @@
+#!/usr/bin/env bats
+# ci.bats - kit ci runs the gate, the kit's check, and the issue link, and reports every one
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}" "${BATS_TEST_TMPDIR}/shims"
+  printf '#!/usr/bin/env bash\nexit 1\n' > "${BATS_TEST_TMPDIR}/shims/gh" && chmod +x "${BATS_TEST_TMPDIR}/shims/gh"
+  export PATH="${BATS_TEST_TMPDIR}/shims:${PATH}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+  "${kit_checkout}/bin/kit" install >/dev/null
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+@test "every check runs and the refusals are counted" {
+  printf 'ci:\n  echo gate ran\n' > justfile
+  run "${kit_checkout}/bin/kit" ci
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"gate ran"* ]]
+  [[ "$output" == *"every delivered file matches"* ]]
+  [[ "$output" == *"kit linked <number>"* ]]
+  [[ "$output" == *"1 of 3 checks refused"* ]]
+  printf 'edited\n' >> .kit/1st.md
+  rm justfile
+  run "${kit_checkout}/bin/kit" ci
+  [ "$status" -eq 3 ]
+  [[ "$output" == *"3 of 3 checks refused"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/gate.bats b/tests/gate.bats
index 857b7e1..02da5a1 100644
--- a/tests/gate.bats
+++ b/tests/gate.bats
@@ -15,18 +15,36 @@ teardown() {
   rm -rf "${repo}"
 }
 
-@test "no justfile is refused, naming the remedy" {
+@test "no gate is refused, naming the remedy" {
   run "${kit_checkout}/bin/kit" gate
   [ "$status" -eq 1 ]
-  [[ "$output" == *"add a root justfile with a ci recipe"* ]]
+  [[ "$output" == *"set gate in .kit/settings.yml, or give the root justfile a ci recipe"* ]]
   grep --quiet 'cannot run' summary.md
 }
 
-@test "a justfile without a ci recipe is refused" {
+@test "a justfile without a ci recipe is no gate" {
   printf 'build:\n  echo built\n' > justfile
   run "${kit_checkout}/bin/kit" gate
   [ "$status" -eq 1 ]
-  [[ "$output" == *"add a ci recipe to the root justfile"* ]]
+  [[ "$output" == *"there is no gate to run"* ]]
+}
+
+@test "the gate setting wins, else a Makefile or a package.json is detected" {
+  mkdir .kit && printf 'gate: echo from the setting\n' > .kit/settings.yml
+  printf 'ci:\n  echo from just\n' > justfile
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"from the setting"* ]]
+  rm -r .kit justfile
+  printf 'ci:\n\t@echo from make\n' > Makefile
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"from make"* ]]
+  rm Makefile
+  printf '{"scripts": {"ci": "echo from npm"}}\n' > package.json
+  run "${kit_checkout}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"the gate: npm run ci"* ]]
 }
 
 @test "a justfile that cannot be read is a failure" {
@@ -42,7 +60,7 @@ teardown() {
   run "${kit_checkout}/bin/kit" gate
   [ "$status" -eq 0 ]
   [[ "$output" == *"gate ran"* ]]
-  grep --quiet 'just ci passed' summary.md
+  grep --quiet 'gate passed' summary.md
   printf 'ci:\n  exit 3\n' > justfile
   run "${kit_checkout}/bin/kit" gate
   [ "$status" -ne 0 ]
diff --git a/tests/kit.bats b/tests/kit.bats
index 1eda34a..8d66853 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -48,9 +48,9 @@ later-release() {
   [ ! -e .claude ]
   grep --quiet '^version unreleased$' .kit/manifest
   grep --quiet '^modules kit$' .kit/manifest
-  run "${kit_checkout}/bin/kit" install ci
+  run "${kit_checkout}/bin/kit" install ci-github
   [ "$status" -eq 1 ]
-  run "${kit_checkout}/bin/kit" module add ci
+  run "${kit_checkout}/bin/kit" module add ci-github
   [ "$status" -eq 0 ]
   grep --quiet '^    runs-on: "ubuntu-latest"$' .github/workflows/kit-ci.yml
   run "${kit_checkout}/bin/kit" check
@@ -74,7 +74,7 @@ later-release() {
 @test "install refuses a module this release does not know and names the known ones" {
   run "${kit_checkout}/bin/kit" install gemini
   [ "$status" -eq 2 ]
-  [[ "$output" == *"the modules are: ci claude kit lefthook"* ]]
+  [[ "$output" == *"the modules are: ci-github claude kit lefthook"* ]]
   [ ! -e .kit/manifest ]
 }
 
@@ -103,12 +103,12 @@ later-release() {
 }
 
 @test "module remove refuses a module another active module depends on, and removes a leaf" {
-  "${kit_checkout}/bin/kit" install claude ci
+  "${kit_checkout}/bin/kit" install claude ci-github
   run "${kit_checkout}/bin/kit" module remove kit
   [ "$status" -eq 1 ]
   [[ "$output" == *"kit cannot be removed while"* ]]
   [ -f .kit/1st.md ]
-  run "${kit_checkout}/bin/kit" module remove ci
+  run "${kit_checkout}/bin/kit" module remove ci-github
   [ "$status" -eq 0 ]
   [ ! -e .github/workflows/kit-ci.yml ]
   grep --quiet '^modules kit claude$' .kit/manifest
@@ -116,14 +116,14 @@ later-release() {
 
 @test "a template takes the repository's answer over the module's default, and refuses a key with neither" {
   mkdir .kit && printf 'answers:\n  ci_runner: blacksmith-2vcpu\n' > .kit/settings.yml
-  run "${kit_checkout}/bin/kit" install ci
+  run "${kit_checkout}/bin/kit" install ci-github
   [ "$status" -eq 0 ]
   grep --quiet '^    runs-on: "blacksmith-2vcpu"$' .github/workflows/kit-ci.yml
   grep --quiet 'uses: actions/checkout@' .github/workflows/kit-ci.yml
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   later-release "${repo}.later"
-  printf 'runner @ci_runner@ owner @owner@\n' > "${repo}.later/modules/ci/templates/repo/OWNER"
+  printf 'runner @ci_runner@ owner @owner@\n' > "${repo}.later/modules/ci-github/templates/repo/OWNER"
   run env KIT_BASE="${kit_checkout}" "${repo}.later/bin/kit" update
   [ "$status" -eq 1 ]
   [[ "$output" == *"OWNER needs an answer for 'owner'"* ]]
@@ -388,7 +388,7 @@ later-release() {
 
 @test "module remove judges dependents against what stays, in any order" {
   "${kit_checkout}/bin/kit" install claude
-  run "${kit_checkout}/bin/kit" module remove kit ci lefthook claude
+  run "${kit_checkout}/bin/kit" module remove kit lefthook claude
   [ "$status" -eq 0 ]
   grep --quiet '^modules$' .kit/manifest
   [ ! -e .kit/1st.md ]

From 4f1279bae7ccd31f6432e20307f0aa5498864d82 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 22:59:58 -0700
Subject: [PATCH 076/108] #5 bin/gh.sh: kit linked says why when gh fails, and
 the ci test leaves the runner's event aside

On the runner the event names the pull request, so the test's shimmed gh was reached and the verb
died under errexit with no message. The provider now names the remedy on either failed read.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/gh.sh     | 12 ++++++++++--
 tests/ci.bats |  4 ++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/bin/gh.sh b/bin/gh.sh
index 21d7fcc..abf9577 100644
--- a/bin/gh.sh
+++ b/bin/gh.sh
@@ -200,7 +200,11 @@ gh:link-secondaries() {
 # count. On a runner the remedy also lands in the step summary.
 gh:linked-open-issue() {
   local number=$1 repo query refs n state issue_repo open=0 closes url remedy
-  IFS=$'\t' read -r repo url < <(gh repo view --json nameWithOwner,url --jq '[.nameWithOwner, .url] | @tsv')
+  if ! IFS=$'\t' read -r repo url < <(gh repo view --json nameWithOwner,url --jq '[.nameWithOwner, .url] | @tsv')
+  then
+    error "run: gh auth status (the repository could not be read, so pull request #${number} was not checked)"
+    return 1
+  fi
   remedy=$(printf '%s\n' \
     "Link an open issue of this repository under **Development** in [the sidebar](${url}/pull/${number}):" "" \
     "1. click the gear (⚙) beside **Development**" \
@@ -215,10 +219,14 @@ gh:linked-open-issue() {
       }
     }
   }'
-  refs=$(gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --field number="${number}" \
+  if ! refs=$(gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --field number="${number}" \
     --raw-field query="${query}" \
     --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
           | "\(.number) \(.state) \(.repository.nameWithOwner)"')
+  then
+    error "run: gh auth status (pull request #${number} could not be read)"
+    return 1
+  fi
   if [[ -z "${refs}" ]]
   then
     error "pull request #${number} is not linked to any issue"
diff --git a/tests/ci.bats b/tests/ci.bats
index d08bee6..0872dd5 100644
--- a/tests/ci.bats
+++ b/tests/ci.bats
@@ -20,7 +20,7 @@ teardown() {
 
 @test "every check runs and the refusals are counted" {
   printf 'ci:\n  echo gate ran\n' > justfile
-  run "${kit_checkout}/bin/kit" ci
+  run env -u GITHUB_EVENT_PATH "${kit_checkout}/bin/kit" ci
   [ "$status" -eq 1 ]
   [[ "$output" == *"gate ran"* ]]
   [[ "$output" == *"every delivered file matches"* ]]
@@ -28,7 +28,7 @@ teardown() {
   [[ "$output" == *"1 of 3 checks refused"* ]]
   printf 'edited\n' >> .kit/1st.md
   rm justfile
-  run "${kit_checkout}/bin/kit" ci
+  run env -u GITHUB_EVENT_PATH "${kit_checkout}/bin/kit" ci
   [ "$status" -eq 3 ]
   [[ "$output" == *"3 of 3 checks refused"* ]]
 }

From 756b40653ded9d02310b4eb58a1f05c66f383b59 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 23:07:17 -0700
Subject: [PATCH 077/108] #5 the forge seam: the loop over bin/forge.sh, GitHub
 as its one provider, and gh as that provider's requirement

Every call the loop makes to the forge goes through forge:<call>, nineteen names the seam's header
lists, and bin/forge-github.sh answers them over gh with no change in behavior. The provider is the
forge setting in .kit/settings.yml, else github for an origin at github.com; an origin elsewhere,
or an unknown setting, is refused naming the forges the kit carries. The on-ramp is bin/issue.sh,
and kit tidy, kit status, and kit linked ask the seam. The core verbs never reach it, and the fetch
of a base release takes the public tarball with curl, so a repository with no gh installs, updates,
checks, and runs kit context. kit issue requires a signing key only where require_signing is true;
this repository says so in .kit/settings.yml. 60 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/settings.yml    |   1 +
 README.md            |   5 +-
 bin/forge-github.sh  | 179 ++++++++++++++++++++++++
 bin/forge.sh         |  96 +++++++++++++
 bin/gh.sh            | 324 -------------------------------------------
 bin/git.sh           |  19 ++-
 bin/issue.sh         | 239 +++++++++++++++++++++++++++++++
 bin/kit-issue.sh     |   6 +-
 bin/kit-linked.sh    |  53 +++++--
 bin/release.sh       |  13 +-
 bin/status.sh        |  68 +--------
 docs/architecture.md |   6 +
 tests/ci.bats        |   1 +
 tests/forge.bats     |  70 ++++++++++
 tests/kit.bats       |   4 +-
 tests/linked.bats    |   1 +
 16 files changed, 662 insertions(+), 423 deletions(-)
 create mode 100644 .kit/settings.yml
 create mode 100644 bin/forge-github.sh
 create mode 100644 bin/forge.sh
 delete mode 100644 bin/gh.sh
 create mode 100644 bin/issue.sh
 create mode 100644 tests/forge.bats

diff --git a/.kit/settings.yml b/.kit/settings.yml
new file mode 100644
index 0000000..5495dd2
--- /dev/null
+++ b/.kit/settings.yml
@@ -0,0 +1 @@
+require_signing: true
diff --git a/README.md b/README.md
index 6a623f5..22c15c0 100644
--- a/README.md
+++ b/README.md
@@ -56,8 +56,9 @@ mkdir kit && tar --extract --gzip --file kit.tar.gz --directory kit --strip-comp
 export PATH="${PWD}/kit/bin:${PATH}"
 ```
 
-The kit needs bash 4.4 or later, git, `gh`, and `jq`. macOS ships bash 3.2, and `brew install bash` gives a
-current one. With mise, an exact pin installs the minute a release exists; a range pin sees a new kit a day after
+The kit needs bash 4.4 or later, git, and `jq`; the loop's verbs, `kit issue`, `kit status`, `kit tidy`, and
+`kit linked`, also need the forge's own tool, `gh` for GitHub. macOS ships bash 3.2, and `brew install bash` gives
+a current one. With mise, an exact pin installs the minute a release exists; a range pin sees a new kit a day after
 it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:empowerite/kit"]`.
 
 ## Take the kit
diff --git a/bin/forge-github.sh b/bin/forge-github.sh
new file mode 100644
index 0000000..8522dec
--- /dev/null
+++ b/bin/forge-github.sh
@@ -0,0 +1,179 @@
+# shellcheck shell=bash
+# shellcheck disable=SC2016  # jq filters and GraphQL queries name their variables with $, in single quotes on purpose
+# forge-github.sh - GitHub, through gh, as the forge the loop runs on (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/forge.sh loads for a repository whose forge is github. Every call is one of the names the
+# seam's header lists; gh is this file's requirement and nobody else's.
+
+# forge-github:require refuses where gh is absent or not authenticated. A revoked token passes `gh auth status`,
+# so the probe is a real call.
+forge-github:require() {
+  guard:require tool:gh || return 1
+  if ! gh api user --jq '.login' >/dev/null 2>&1
+  then
+    error "run: gh auth login (the GitHub CLI is not authenticated)"
+    return 1
+  fi
+}
+
+forge-github:repo() {
+  gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null \
+    || { error "run: gh repo view (this checkout does not resolve to a GitHub repository)"; return 1; }
+}
+
+forge-github:repo-url() {
+  gh repo view --json url --jq .url 2>/dev/null \
+    || { error "run: gh repo view (this checkout does not resolve to a GitHub repository)"; return 1; }
+}
+
+forge-github:me() {
+  gh api user --jq '.login' 2>/dev/null || { error "run: gh auth login (the GitHub CLI is not authenticated)"; return 1; }
+}
+
+forge-github:issue-create() {
+  local number
+  number=$(gh issue create --title "$1" --body "" 2>/dev/null | sed -n 's@.*/issues/@@p')
+  if [[ ! "${number}" =~ ^[0-9]+$ ]]
+  then
+    error "run: gh auth status (the issue could not be created)"
+    return 1
+  fi
+  printf '%s\n' "${number}"
+}
+
+forge-github:issue-title() {
+  gh issue view "$1" --json title --jq '.title' 2>/dev/null \
+    || { error "run: gh auth status (the title of #$1 could not be read)"; return 1; }
+}
+
+forge-github:issue-state() {
+  gh issue view "$1" --json state --jq .state 2>/dev/null
+}
+
+forge-github:issue-assignees() {
+  gh issue view "$1" --json assignees --jq '[.assignees[].login] | join(" ")' 2>/dev/null
+}
+
+forge-github:issue-assign() {
+  gh issue edit "$1" --add-assignee "$2" >/dev/null 2>&1
+}
+
+# The branch is found by an open pull request's head, so a second run never forks a <N>-<slug>-1 duplicate.
+forge-github:branch-for-issue() {
+  gh pr list --state open --json headRefName \
+    --jq "[.[] | select(.headRefName | test(\"^$1-\"))] | .[0].headRefName // empty" 2>/dev/null || true
+}
+
+# gh issue develop names the branch <N>-<slug> itself, links it under Development, and pushes it.
+forge-github:link-branch() {
+  gh issue develop "$1" --base "$2" >/dev/null
+}
+
+forge-github:pr-for-branch() {
+  gh pr list --head "$1" --state open --json number --jq '.[0].number // empty' 2>/dev/null || true
+}
+
+forge-github:pr-create() {
+  gh pr create --draft --base "$2" --head "$1" --title "$3" --body "" >/dev/null
+  gh pr list --head "$1" --state open --json number --jq '.[0].number'
+}
+
+forge-github:pr-body() {
+  gh pr view "$1" --json body --jq '.body // ""'
+}
+
+forge-github:pr-set-body() {
+  gh pr edit "$1" --body "$2" >/dev/null
+}
+
+forge-github:pr-state-for-branch() {
+  gh pr list --head "$1" --state all --json state --jq '.[0].state // empty' 2>/dev/null || true
+}
+
+# On a runner the event names the pull request; on a desk the current branch does.
+forge-github:pr-here() {
+  local number=''
+  [[ -n "${GITHUB_EVENT_PATH:-}" ]] && number=$(jq --raw-output '.pull_request.number // empty' "${GITHUB_EVENT_PATH}")
+  [[ -n "${number}" ]] || number=$(gh pr view --json number --jq .number 2>/dev/null || true)
+  printf '%s\n' "${number}"
+}
+
+forge-github:pr-closing-issues() {
+  local repo query
+  repo=$(forge-github:repo) || return 1
+  query='query($owner: String!, $name: String!, $number: Int!) {
+    repository(owner: $owner, name: $name) {
+      pullRequest(number: $number) {
+        closingIssuesReferences(first: 100) { nodes { number state repository { nameWithOwner } } }
+      }
+    }
+  }'
+  gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --field number="$1" \
+    --raw-field query="${query}" \
+    --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
+          | "\(.number) \(.state) \(.repository.nameWithOwner)"' 2>/dev/null \
+    || { error "run: gh auth status (pull request #$1 could not be read)"; return 1; }
+}
+
+# One request: every open pull request with the issues it closes, its review threads, and the checks on its
+# head, folded into the document kit status draws: number, branch, title, createdAt, age in seconds, state,
+# checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes [{number, title}].
+forge-github:open-prs() {
+  local repo query filter
+  repo=$(forge-github:repo) || return 1
+  query='query($owner: String!, $name: String!) {
+    repository(owner: $owner, name: $name) {
+      pullRequests(states: OPEN, first: 100, orderBy: {field: CREATED_AT, direction: ASC}) {
+        nodes {
+          number title isDraft headRefName createdAt mergeStateStatus reviewDecision
+          closingIssuesReferences(first: 10) { nodes { number title } }
+          reviewThreads(first: 100) { nodes { isResolved } }
+          commits(last: 1) { nodes { commit { statusCheckRollup { contexts(first: 100) { nodes {
+            __typename
+            ... on CheckRun { name status conclusion startedAt completedAt }
+            ... on StatusContext { context state createdAt }
+          } } } } } }
+        }
+      }
+    }
+  }'
+  filter='
+    def verdict: if .__typename == "CheckRun" then (if .status == "COMPLETED" then .conclusion else "PENDING" end)
+                 else .state end;
+    def pending: IN("PENDING", "EXPECTED");
+    def passed: IN("SUCCESS", "NEUTRAL", "SKIPPED");
+    (now | floor) as $now
+    | .data.repository.pullRequests.nodes[]
+    | [.commits.nodes[0].commit.statusCheckRollup.contexts.nodes[]?] as $checks
+    | ($checks | length) as $n
+    | ([$checks[] | verdict | select(pending)] | length) as $running
+    | ([$checks[] | verdict | select(passed)] | length) as $ok
+    | ([$checks[] | select((verdict | pending or passed) | not) | (.name // .context)] | first // "") as $failing
+    | (if $n == 0 then "NONE" elif $failing != "" then "FAILURE" elif $running > 0 then "PENDING" else "SUCCESS" end)
+      as $check
+    | ([$checks[] | .startedAt // .createdAt // empty | fromdateiso8601] | min) as $started
+    | ([$checks[] | .completedAt // empty | fromdateiso8601] | max) as $completed
+    | (if $started == null then null
+       elif $check == "PENDING" then $now - $started
+       elif $completed == null then null
+       else $completed - $started end) as $took
+    | ([.reviewThreads.nodes[]? | select(.isResolved | not)] | length) as $unresolved
+    | (if .isDraft then "draft"
+       elif $check == "PENDING" then "queued"
+       elif .mergeStateStatus == "DIRTY" then "conflicted"
+       elif $check == "FAILURE" then "failing:gate"
+       elif $check == "NONE" then "no-check"
+       elif $unresolved > 0 then "comments:open"
+       elif (.reviewDecision // "") | IN("REVIEW_REQUIRED", "CHANGES_REQUESTED") then "blocked:approval"
+       else "ready" end) as $state
+    | { number, branch: .headRefName, title, createdAt, age: ($now - (.createdAt | fromdateiso8601)), state: $state,
+        checks: { state: $check, passed: $ok, total: $n, failing: $failing, took: $took },
+        unresolved: $unresolved,
+        closes: [.closingIssuesReferences.nodes[] | { number, title }] }
+    | tojson'
+  gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
+    2>/dev/null || { error "run: gh auth status (the pull requests could not be read)"; return 1; }
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/forge.sh b/bin/forge.sh
new file mode 100644
index 0000000..21b4465
--- /dev/null
+++ b/bin/forge.sh
@@ -0,0 +1,96 @@
+# shellcheck shell=bash
+# forge.sh - the loop's seam over the forge that hosts the repository (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The loop speaks of an issue, a branch linked to it, a pull request, its checks and review threads and linked
+# issues. Every verb that needs one asks here, by these names, and a provider answers: forge-<name>.sh beside this
+# file, its functions named forge-<name>:<call>. The provider is the `forge` setting in .kit/settings.yml, else
+# the one origin's host names. The core verbs never come here, so a repository on no forge still installs,
+# updates, checks, and runs kit context and kit lint.
+#
+# A provider answers these calls, each printing its result on stdout and failing with a remedy on stderr:
+#
+#   require                       the provider's own tool is present and authenticated
+#   repo                          the repository as owner/name
+#   repo-url                      the repository's browser URL
+#   me                            the caller's login
+#   issue-create <title>          the number of the issue it creates
+#   issue-title <n>               the issue's title
+#   issue-state <n>               OPEN or CLOSED
+#   issue-assignees <n>           the assignees' logins, space-separated
+#   issue-assign <n> <login>      adds the assignee
+#   branch-for-issue <n>          the branch an open pull request for issue <n> is on, or nothing
+#   link-branch <n> <default>     makes a branch linked to the issue, from <default>, pushed to origin
+#   pr-for-branch <branch>        the number of the open pull request on the branch, or nothing
+#   pr-create <branch> <default> <title>   opens a draft pull request and prints its number
+#   pr-body <n>                   the pull request's body
+#   pr-set-body <n> <body>        replaces it
+#   pr-state-for-branch <branch>  MERGED, CLOSED, or OPEN for the latest pull request on the branch, or nothing
+#   pr-here                       the number of the pull request this checkout is working on, or nothing
+#   pr-closing-issues <n>         one line per issue the pull request closes: "<number> <state> <owner/name>"
+#   open-prs                      one JSON object per open pull request, the documents kit status draws
+
+use release
+
+# forge:provider prints the provider's name: the forge setting, else github for an origin at github.com. It
+# fails, naming the remedy, where neither names a provider the kit carries.
+forge:provider() {
+  local provider host=''
+  provider=$(release:setting forge)
+  if [[ -z "${provider}" ]]
+  then
+    host=$(git remote get-url origin 2>/dev/null | sed -E 's#^([a-z]+://)?([^@/]+@)?([^/:]+).*#\3#')
+    case "${host}" in
+      (github.com | *.github.com) provider=github ;;
+    esac
+  fi
+  if [[ -z "${provider}" ]]
+  then
+    error "set forge in .kit/settings.yml; origin's host '${host:-none}' names no forge the kit knows ($(forge:providers))"
+    return 1
+  fi
+  # shellcheck disable=SC2154  # kit_bin_dir is declared by bin/1st.sh, which loaded this module
+  if [[ ! -f "${kit_bin_dir}/forge-${provider}.sh" ]]
+  then
+    error "'${provider}' is not a forge the kit knows; the forges are: $(forge:providers) (forge in .kit/settings.yml)"
+    return 1
+  fi
+  printf '%s\n' "${provider}"
+}
+
+# forge:providers prints the providers this release carries, space-separated.
+forge:providers() {
+  (cd "${kit_bin_dir}" && find . -maxdepth 1 -name 'forge-*.sh' | sed 's@^\./forge-@@; s@\.sh$@@' | LC_ALL=C sort \
+    | paste -s -d ' ' -)
+}
+
+# forge:call <call> <argument>… runs the provider's function for <call>, loading the provider once.
+forge:call() {
+  local call=$1 provider
+  shift
+  provider=$(forge:provider) || return 1
+  use "forge-${provider}"
+  "forge-${provider}:${call}" "$@"
+}
+
+forge:require()             { forge:call require "$@"; }
+forge:repo()                { forge:call repo "$@"; }
+forge:repo-url()            { forge:call repo-url "$@"; }
+forge:me()                  { forge:call me "$@"; }
+forge:issue-create()        { forge:call issue-create "$@"; }
+forge:issue-title()         { forge:call issue-title "$@"; }
+forge:issue-state()         { forge:call issue-state "$@"; }
+forge:issue-assignees()     { forge:call issue-assignees "$@"; }
+forge:issue-assign()        { forge:call issue-assign "$@"; }
+forge:branch-for-issue()    { forge:call branch-for-issue "$@"; }
+forge:link-branch()         { forge:call link-branch "$@"; }
+forge:pr-for-branch()       { forge:call pr-for-branch "$@"; }
+forge:pr-create()           { forge:call pr-create "$@"; }
+forge:pr-body()             { forge:call pr-body "$@"; }
+forge:pr-set-body()         { forge:call pr-set-body "$@"; }
+forge:pr-state-for-branch() { forge:call pr-state-for-branch "$@"; }
+forge:pr-here()             { forge:call pr-here "$@"; }
+forge:pr-closing-issues()   { forge:call pr-closing-issues "$@"; }
+forge:open-prs()            { forge:call open-prs "$@"; }
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/gh.sh b/bin/gh.sh
deleted file mode 100644
index abf9577..0000000
--- a/bin/gh.sh
+++ /dev/null
@@ -1,324 +0,0 @@
-# shellcheck shell=bash
-# gh.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft pull request (sourced module)
-# ----------------------------------------------------------------------------------------------------------------------
-#
-# gh:issue [<number>…] is the one command the loop needs and no vendor provides. The first number is the primary
-# issue, linked to the branch under Development by `gh issue develop`, which closes it on merge; any further
-# number is a secondary, closed by a `Closes #N` line in the pull request body. Every listed issue is assigned to
-# the caller. It never switches the checkout it runs from: the branch is checked out in worktrees/<N>-<slug>
-# under the main checkout, and an existing branch, worktree, or pull request is reused, so a re-run reconciles.
-#
-# With no argument and a terminal on stdin it asks for a title and creates the issue; without a terminal the
-# usage error stands, so an agent never hangs on a prompt. Uncommitted work in the root checkout, the human's
-# desk, is swept into the new worktree, uncommitted, and the desk is left clean, and fast-forwarded when it is on
-# the default branch; inside any other checkout, dirty files are that issue's own and stay. A sweep that cannot
-# apply leaves the stash in place and stops.
-#
-# Each step below prints its one result on stdout and talks on stderr, so gh:issue reads them in order.
-
-# gh:repo prints the repository this checkout resolves to, as owner/name, or fails.
-gh:repo() {
-  gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null
-}
-
-# gh:me prints the authenticated login. A revoked token passes `gh auth status`, so this is the real probe.
-gh:me() {
-  local me
-  me=$(gh api user --jq '.login' 2>/dev/null || true)
-  if [[ -z "${me}" ]]
-  then
-    error "run: gh auth login (the GitHub CLI is not authenticated)"
-    return 1
-  fi
-  printf '%s\n' "${me}"
-}
-
-# gh:issue-create asks for a title at the terminal and prints the number of the issue it creates.
-gh:issue-create() {
-  local title number
-  read -r -p "Issue title: " title
-  if [[ -z "${title}" ]]
-  then
-    error "an issue title is required"
-    return 2
-  fi
-  number=$(gh issue create --title "${title}" --body "" 2>/dev/null | sed -n 's@.*/issues/@@p')
-  if [[ ! "${number}" =~ ^[0-9]+$ ]]
-  then
-    error "run: gh auth status (the issue could not be created)"
-    return 1
-  fi
-  ok "Created #${number}: ${title}"
-  printf '%s\n' "${number}"
-}
-
-# gh:assign <me> <number>… adds <me> to each issue's assignees, warning where someone else is there already.
-gh:assign() {
-  local me=$1 n assignees
-  shift
-  for n in "$@"
-  do
-    assignees=$(gh issue view "${n}" --json assignees --jq '[.assignees[].login] | join(" ")')
-    [[ " ${assignees} " == *" ${me} "* ]] && continue
-    [[ -z "${assignees}" ]] \
-      || warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
-    gh issue edit "${n}" --add-assignee "${me}" >/dev/null 2>&1 \
-      || warn "#${n} could not be assigned to ${me}; assign it by hand."
-  done
-}
-
-# gh:issue-branch <number> <default-branch> prints the branch linked to the issue, making and linking one if none
-# exists. An existing one is found by an open pull request's head, then by the remote ref, so a second run never
-# forks a <N>-<slug>-1 duplicate.
-gh:issue-branch() {
-  local number=$1 default_branch=$2 branch
-  branch=$(gh pr list --state open --json headRefName \
-    --jq "[.[] | select(.headRefName | test(\"^${number}-\"))] | .[0].headRefName // empty" 2>/dev/null || true)
-  [[ -n "${branch}" ]] \
-    || branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
-  if [[ -z "${branch}" ]]
-  then
-    step "Linking a branch to #${number} (gh issue develop)"
-    gh issue develop "${number}" --base "${default_branch}" >/dev/null
-    git fetch --quiet origin
-    branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
-    if [[ -z "${branch}" ]]
-    then
-      error "the branch gh made for #${number} could not be found; run: gh issue develop ${number} --list"
-      return 1
-    fi
-  fi
-  printf '%s\n' "${branch}"
-}
-
-# gh:worktree <main-root> <branch> prints the worktree the branch is checked out in, making it if there is none.
-gh:worktree() {
-  local main_root=$1 branch=$2 wt
-  wt=$(git worktree list --porcelain 2>/dev/null \
-    | awk -v b="branch refs/heads/${branch}" '/^worktree / { w = substr($0, 10) } $0 == b { print w; exit }')
-  if [[ -n "${wt}" ]]
-  then
-    step "Reusing worktree ${wt}"
-  else
-    wt="${main_root}/worktrees/${branch}"
-    if [[ -e "${wt}" ]]
-    then
-      error "${wt} exists but is not a worktree of ${branch}; remove it (or run: kit tidy) and re-run."
-      return 2
-    fi
-    step "Creating worktree ${wt}"
-    mkdir -p "${main_root}/worktrees"
-    if git show-ref --verify --quiet "refs/heads/${branch}"
-    then
-      git worktree add --quiet "${wt}" "${branch}"
-    else
-      git worktree add --quiet "${wt}" -b "${branch}" "origin/${branch}"
-    fi
-  fi
-  printf '%s\n' "${wt}"
-}
-
-# gh:start-commit <worktree> <default-branch> <number> <title> gives the branch its first commit when it has
-# none: GitHub cannot open a pull request with nothing to compare. --only keeps the commit empty, so work already
-# staged in a reused worktree stays in the index. The subject follows the loop's shape, #<N> <area>: <subject>.
-gh:start-commit() {
-  local wt=$1 default_branch=$2 number=$3 title=$4
-  if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
-  then
-    step "Adding the start commit"
-    git -C "${wt}" commit --quiet --allow-empty --only --message "#${number} start: ${title}"
-  fi
-}
-
-# gh:sweep-push <root> <message> stashes everything uncommitted at <root>, untracked files included, and prints
-# the stash's commit, which stays valid however the stash list shifts.
-gh:sweep-push() {
-  local root=$1 message=$2
-  if ! git -C "${root}" stash push --include-untracked --message "${message}" >/dev/null
-  then
-    error "the uncommitted work at ${root} could not be stashed; resolve it by hand and re-run."
-    return 1
-  fi
-  git -C "${root}" rev-parse 'stash@{0}'
-}
-
-# gh:sweep-apply <root> <worktree> <stash> <default-branch> lands the stash in the worktree, uncommitted, drops it,
-# and fast-forwards the now-clean desk when it is on the default branch. On a conflict the stash is kept and the
-# caller stops.
-gh:sweep-apply() {
-  local root=$1 wt=$2 stash=$3 default_branch=$4 slot
-  if ! git -C "${wt}" stash apply "${stash}" >/dev/null 2>&1
-  then
-    error "the swept work conflicts in ${wt}. It is kept in the stash: git stash apply ${stash}"
-    return 1
-  fi
-  slot=$(git -C "${root}" stash list --format='%gd %H' | awk -v h="${stash}" '$2 == h { print $1; exit }')
-  [[ -n "${slot}" ]] && git -C "${root}" stash drop "${slot}" >/dev/null
-  ok "Swept the work into ${wt}, uncommitted; commit it there with a real message."
-  [[ "$(git -C "${root}" rev-parse --abbrev-ref HEAD)" == "${default_branch}" ]] || return 0
-  git -C "${root}" merge --ff-only "origin/${default_branch}" >/dev/null 2>&1 \
-    || warn "${default_branch} could not fast-forward to origin; it is left as it was."
-}
-
-# gh:pull-request <branch> <default-branch> <title> prints the number of the open pull request for the branch,
-# opening a draft if there is none.
-gh:pull-request() {
-  local branch=$1 default_branch=$2 title=$3 pr
-  pr=$(gh pr list --head "${branch}" --state open --json number --jq '.[0].number // empty')
-  if [[ -z "${pr}" ]]
-  then
-    step "Opening a draft pull request"
-    gh pr create --draft --base "${default_branch}" --head "${branch}" --title "${title}" --body "" >/dev/null
-    pr=$(gh pr list --head "${branch}" --state open --json number --jq '.[0].number')
-  fi
-  printf '%s\n' "${pr}"
-}
-
-# gh:link-secondaries <pr> <number>… adds a `Closes #N` line to the pull request body for each number not there.
-gh:link-secondaries() {
-  local pr=$1 n body changed=false
-  shift
-  body=$(gh pr view "${pr}" --json body --jq '.body // ""')
-  for n in "$@"
-  do
-    if ! grep --quiet --ignore-case --extended-regexp \
-      "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
-    then
-      body="${body}"$'\n'"Closes #${n}"
-      changed=true
-    fi
-  done
-  if [[ "${changed}" == true ]]
-  then
-    step "Linking the secondary issues in the pull request body"
-    gh pr edit "${pr}" --body "${body}" >/dev/null
-  fi
-}
-
-# gh:linked-open-issue <number> refuses pull request <number> unless it is linked, under Development, to an issue
-# of this repository that is open. A linked issue of another repository, or a closed one, is noted and does not
-# count. On a runner the remedy also lands in the step summary.
-gh:linked-open-issue() {
-  local number=$1 repo query refs n state issue_repo open=0 closes url remedy
-  if ! IFS=$'\t' read -r repo url < <(gh repo view --json nameWithOwner,url --jq '[.nameWithOwner, .url] | @tsv')
-  then
-    error "run: gh auth status (the repository could not be read, so pull request #${number} was not checked)"
-    return 1
-  fi
-  remedy=$(printf '%s\n' \
-    "Link an open issue of this repository under **Development** in [the sidebar](${url}/pull/${number}):" "" \
-    "1. click the gear (⚙) beside **Development**" \
-    "2. pick one or more open issues" \
-    "3. re-run the check: linking fires no event, so it does not re-run on its own" "" \
-    "\`kit issue <N>\` makes this link when it starts the work.")
-  # shellcheck disable=SC2016  # GraphQL variables
-  query='query($owner: String!, $name: String!, $number: Int!) {
-    repository(owner: $owner, name: $name) {
-      pullRequest(number: $number) {
-        closingIssuesReferences(first: 100) { nodes { number state repository { nameWithOwner } } }
-      }
-    }
-  }'
-  if ! refs=$(gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --field number="${number}" \
-    --raw-field query="${query}" \
-    --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[]
-          | "\(.number) \(.state) \(.repository.nameWithOwner)"')
-  then
-    error "run: gh auth status (pull request #${number} could not be read)"
-    return 1
-  fi
-  if [[ -z "${refs}" ]]
-  then
-    error "pull request #${number} is not linked to any issue"
-    summary "### ❌ Pull request #${number} is not linked to any issue" "" "${remedy}"
-    return 1
-  fi
-  while read -r n state issue_repo
-  do
-    if [[ "${issue_repo}" != "${repo}" ]]
-    then
-      warn "skipping ${issue_repo}#${n}: it belongs to another repository"
-    elif [[ "${state}" != OPEN ]]
-    then
-      warn "#${n} is ${state}; merging will not change it"
-    else
-      open=$(( open + 1 ))
-    fi
-  done <<<"${refs}"
-  if (( open == 0 ))
-  then
-    error "every issue pull request #${number} is linked to is closed or belongs to another repository"
-    summary "### ❌ Every linked issue is closed or belongs to another repository" "" "${remedy}"
-    return 1
-  fi
-  closes=$(cut -d ' ' -f 1 <<<"${refs}" | sed 's/^/#/' | paste -s -d ' ' -)
-  ok "pull request #${number} is linked to ${closes}"
-  summary "✅ Linked to ${closes}."
-}
-
-# gh:issue [<number>…] is the issue on-ramp the file header describes: assign, link a branch, make the worktree,
-# push a start commit, sweep the desk's uncommitted work into the worktree, and open a draft pull request. Every
-# commit the loop makes is signed, so a desk without a signing key is refused before anything is written.
-gh:issue() {
-  use git
-  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr created
-  me=$(gh:me) || return 1
-  guard:require signing-key || return 1
-  if (( $# == 0 ))
-  then
-    if [[ ! -t 0 ]]
-    then
-      error "usage: kit issue <issue-number> [<issue-number>…]"
-      return 2
-    fi
-    created=$(gh:issue-create) || return
-    set -- "${created}"
-  fi
-  for n in "$@"
-  do
-    if [[ ! "${n}" =~ ^[0-9]+$ ]]
-    then
-      error "not an issue number: '${n}'"
-      return 2
-    fi
-  done
-  primary=$1
-
-  git fetch --quiet --prune origin
-  default_branch=$(git:default-branch)
-  main_root=$(git:main-root)
-  desk=$(git rev-parse --show-toplevel)
-  desk_branch=$(git -C "${desk}" rev-parse --abbrev-ref HEAD)
-  title=$(gh issue view "${primary}" --json title --jq '.title')
-  if [[ -z "${title}" ]]
-  then
-    error "run: gh auth status (the title of #${primary} could not be read)"
-    return 1
-  fi
-  gh:assign "${me}" "$@"
-  section "Starting #${primary}: ${title}"
-
-  branch=$(gh:issue-branch "${primary}" "${default_branch}") || return
-  if [[ "${desk}" == "${main_root}" ]] && ! git:clean "${desk}"
-  then
-    step "Sweeping the uncommitted work on ${desk_branch} into the worktree"
-    stash=$(gh:sweep-push "${desk}" "kit issue #${primary} → ${branch}") || return
-  fi
-  wt=$(gh:worktree "${main_root}" "${branch}") || return
-  git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null \
-    || warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a commit"
-  gh:start-commit "${wt}" "${default_branch}" "${primary}" "${title}"
-  git -C "${wt}" push --quiet --set-upstream origin "${branch}"
-  if [[ -n "${stash}" ]]
-  then
-    gh:sweep-apply "${desk}" "${wt}" "${stash}" "${default_branch}" || return
-  fi
-  pr=$(gh:pull-request "${branch}" "${default_branch}" "${title}")
-  (( $# > 1 )) && gh:link-secondaries "${pr}" "${@:2}"
-
-  ok "Draft pull request #${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
-  ok "Worktree ready: ${wt}"
-  step "cd '${wt}'    # do all work there; this checkout stays on ${desk_branch}"
-}
-
-# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/git.sh b/bin/git.sh
index e8a905a..40ce195 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -1,6 +1,10 @@
 # shellcheck shell=bash
 # git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
+#
+# The sweep asks the forge, through bin/forge.sh, whether a worktree's pull request is merged or closed.
+
+use forge
 
 # git:default-branch [<path>] prints the default branch of the repository at <path>: origin/HEAD, else main.
 git:default-branch() {
@@ -70,11 +74,11 @@ git:tidy-worktree() {
   fi
   if [[ -n "${branch}" ]]
   then
-    state=$(gh pr list --head "${branch}" --state all --json state --jq '.[0].state // empty' 2>/dev/null || true)
+    state=$(forge:pr-state-for-branch "${branch}")
     if [[ -z "${state}" && "${branch}" =~ ^([0-9]+)- ]]
     then
       number=${BASH_REMATCH[1]}
-      [[ "$(gh issue view "${number}" --json state --jq .state 2>/dev/null)" == CLOSED ]] && state=CLOSED
+      [[ "$(forge:issue-state "${number}")" == CLOSED ]] && state=CLOSED
     fi
   elif [[ "${detached}" == true ]]
   then
@@ -125,14 +129,9 @@ git:tidy() {
         return 2
     esac
   done
-  use gh
-  guard:require gh || return 1
-  repo=$(gh:repo || true)
-  if [[ -z "${repo}" ]]
-  then
-    error "this checkout does not resolve to a GitHub repository (run: gh repo view), so nothing is swept."
-    return 1
-  fi
+  use forge
+  forge:require || return 1
+  repo=$(forge:repo) || return 1
   if [[ "${dry_run}" == true ]]
   then
     section "kit tidy, dry run: nothing is changed"
diff --git a/bin/issue.sh b/bin/issue.sh
new file mode 100644
index 0000000..e5fe8dc
--- /dev/null
+++ b/bin/issue.sh
@@ -0,0 +1,239 @@
+# shellcheck shell=bash
+# issue.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft pull request (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# issue:start [<number>…] is the one command the loop needs and no vendor provides. The first number is the
+# primary issue, linked to the branch the forge makes, which closes it on merge; any further number is a
+# secondary, closed by a `Closes #N` line in the pull request body. Every listed issue is assigned to the caller.
+# It never switches the checkout it runs from: the branch is checked out in worktrees/<N>-<slug> under the main
+# checkout, and an existing branch, worktree, or pull request is reused, so a re-run reconciles.
+#
+# With no argument and a terminal on stdin it asks for a title and creates the issue; without a terminal the
+# usage error stands, so an agent never hangs on a prompt. Uncommitted work in the root checkout, the human's
+# desk, is swept into the new worktree, uncommitted, and the desk is left clean, and fast-forwarded when it is on
+# the default branch; inside any other checkout, dirty files are that issue's own and stay. A sweep that cannot
+# apply leaves the stash in place and stops.
+#
+# Every call to the forge goes through bin/forge.sh. Each step below prints its one result on stdout and talks
+# on stderr, so issue:start reads them in order.
+
+use git forge
+
+# issue:create asks for a title at the terminal and prints the number of the issue the forge creates.
+issue:create() {
+  local title number
+  read -r -p "Issue title: " title
+  if [[ -z "${title}" ]]
+  then
+    error "an issue title is required"
+    return 2
+  fi
+  number=$(forge:issue-create "${title}") || return 1
+  ok "Created #${number}: ${title}"
+  printf '%s\n' "${number}"
+}
+
+# issue:assign <me> <number>… adds <me> to each issue's assignees, warning where someone else is there already.
+issue:assign() {
+  local me=$1 n assignees
+  shift
+  for n in "$@"
+  do
+    assignees=$(forge:issue-assignees "${n}")
+    [[ " ${assignees} " == *" ${me} "* ]] && continue
+    [[ -z "${assignees}" ]] \
+      || warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
+    forge:issue-assign "${n}" "${me}" || warn "#${n} could not be assigned to ${me}; assign it by hand."
+  done
+}
+
+# issue:branch <number> <default-branch> prints the branch linked to the issue, making and linking one if none
+# exists. An existing one is found by an open pull request's head, then by the remote ref, so a second run never
+# forks a duplicate.
+issue:branch() {
+  local number=$1 default_branch=$2 branch
+  branch=$(forge:branch-for-issue "${number}")
+  [[ -n "${branch}" ]] \
+    || branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+  if [[ -z "${branch}" ]]
+  then
+    step "Linking a branch to #${number}"
+    forge:link-branch "${number}" "${default_branch}" || return 1
+    git fetch --quiet origin
+    branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+    if [[ -z "${branch}" ]]
+    then
+      error "the branch the forge made for #${number} could not be found on origin; link one by hand and re-run"
+      return 1
+    fi
+  fi
+  printf '%s\n' "${branch}"
+}
+
+# issue:worktree <main-root> <branch> prints the worktree the branch is checked out in, making it if there is none.
+issue:worktree() {
+  local main_root=$1 branch=$2 wt
+  wt=$(git worktree list --porcelain 2>/dev/null \
+    | awk -v b="branch refs/heads/${branch}" '/^worktree / { w = substr($0, 10) } $0 == b { print w; exit }')
+  if [[ -n "${wt}" ]]
+  then
+    step "Reusing worktree ${wt}"
+  else
+    wt="${main_root}/worktrees/${branch}"
+    if [[ -e "${wt}" ]]
+    then
+      error "${wt} exists but is not a worktree of ${branch}; remove it (or run: kit tidy) and re-run."
+      return 2
+    fi
+    step "Creating worktree ${wt}"
+    mkdir -p "${main_root}/worktrees"
+    if git show-ref --verify --quiet "refs/heads/${branch}"
+    then
+      git worktree add --quiet "${wt}" "${branch}"
+    else
+      git worktree add --quiet "${wt}" -b "${branch}" "origin/${branch}"
+    fi
+  fi
+  printf '%s\n' "${wt}"
+}
+
+# issue:start-commit <worktree> <default-branch> <number> <title> gives the branch its first commit when it has
+# none: a forge cannot open a pull request with nothing to compare. --only keeps the commit empty, so work
+# already staged in a reused worktree stays in the index. The subject follows the loop's shape.
+issue:start-commit() {
+  local wt=$1 default_branch=$2 number=$3 title=$4
+  if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
+  then
+    step "Adding the start commit"
+    git -C "${wt}" commit --quiet --allow-empty --only --message "#${number} start: ${title}"
+  fi
+}
+
+# issue:sweep-push <root> <message> stashes everything uncommitted at <root>, untracked files included, and
+# prints the stash's commit, which stays valid however the stash list shifts.
+issue:sweep-push() {
+  local root=$1 message=$2
+  if ! git -C "${root}" stash push --include-untracked --message "${message}" >/dev/null
+  then
+    error "the uncommitted work at ${root} could not be stashed; resolve it by hand and re-run."
+    return 1
+  fi
+  git -C "${root}" rev-parse 'stash@{0}'
+}
+
+# issue:sweep-apply <root> <worktree> <stash> <default-branch> lands the stash in the worktree, uncommitted,
+# drops it, and fast-forwards the now-clean desk when it is on the default branch. On a conflict the stash is
+# kept and the caller stops.
+issue:sweep-apply() {
+  local root=$1 wt=$2 stash=$3 default_branch=$4 slot
+  if ! git -C "${wt}" stash apply "${stash}" >/dev/null 2>&1
+  then
+    error "the swept work conflicts in ${wt}. It is kept in the stash: git stash apply ${stash}"
+    return 1
+  fi
+  slot=$(git -C "${root}" stash list --format='%gd %H' | awk -v h="${stash}" '$2 == h { print $1; exit }')
+  [[ -n "${slot}" ]] && git -C "${root}" stash drop "${slot}" >/dev/null
+  ok "Swept the work into ${wt}, uncommitted; commit it there with a real message."
+  [[ "$(git -C "${root}" rev-parse --abbrev-ref HEAD)" == "${default_branch}" ]] || return 0
+  git -C "${root}" merge --ff-only "origin/${default_branch}" >/dev/null 2>&1 \
+    || warn "${default_branch} could not fast-forward to origin; it is left as it was."
+}
+
+# issue:pull-request <branch> <default-branch> <title> prints the number of the open pull request for the
+# branch, opening a draft if there is none.
+issue:pull-request() {
+  local branch=$1 default_branch=$2 title=$3 pr
+  pr=$(forge:pr-for-branch "${branch}")
+  if [[ -z "${pr}" ]]
+  then
+    step "Opening a draft pull request"
+    pr=$(forge:pr-create "${branch}" "${default_branch}" "${title}") || return 1
+  fi
+  printf '%s\n' "${pr}"
+}
+
+# issue:link-secondaries <pr> <number>… adds a `Closes #N` line to the pull request body for each number not
+# there.
+issue:link-secondaries() {
+  local pr=$1 n body changed=false
+  shift
+  body=$(forge:pr-body "${pr}")
+  for n in "$@"
+  do
+    if ! grep --quiet --ignore-case --extended-regexp \
+      "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
+    then
+      body="${body}"$'\n'"Closes #${n}"
+      changed=true
+    fi
+  done
+  if [[ "${changed}" == true ]]
+  then
+    step "Linking the secondary issues in the pull request body"
+    forge:pr-set-body "${pr}" "${body}"
+  fi
+}
+
+# issue:start [<number>…] is the on-ramp the file header describes. A desk without a signing key is refused
+# where the require_signing setting is true, before anything is written.
+issue:start() {
+  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr created
+  forge:require || return 1
+  me=$(forge:me) || return 1
+  if [[ "$(release:setting require_signing)" == true ]]
+  then
+    guard:require signing-key || return 1
+  fi
+  if (( $# == 0 ))
+  then
+    if [[ ! -t 0 ]]
+    then
+      error "usage: kit issue <issue-number> [<issue-number>…]"
+      return 2
+    fi
+    created=$(issue:create) || return
+    set -- "${created}"
+  fi
+  for n in "$@"
+  do
+    if [[ ! "${n}" =~ ^[0-9]+$ ]]
+    then
+      error "not an issue number: '${n}'"
+      return 2
+    fi
+  done
+  primary=$1
+
+  git fetch --quiet --prune origin
+  default_branch=$(git:default-branch)
+  main_root=$(git:main-root)
+  desk=$(git rev-parse --show-toplevel)
+  desk_branch=$(git -C "${desk}" rev-parse --abbrev-ref HEAD)
+  title=$(forge:issue-title "${primary}") || return 1
+  issue:assign "${me}" "$@"
+  section "Starting #${primary}: ${title}"
+
+  branch=$(issue:branch "${primary}" "${default_branch}") || return
+  if [[ "${desk}" == "${main_root}" ]] && ! git:clean "${desk}"
+  then
+    step "Sweeping the uncommitted work on ${desk_branch} into the worktree"
+    stash=$(issue:sweep-push "${desk}" "kit issue #${primary} → ${branch}") || return
+  fi
+  wt=$(issue:worktree "${main_root}" "${branch}") || return
+  git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null \
+    || warn "worktrees/ is not ignored; add /worktrees/ to .gitignore so a worktree never appears in a commit"
+  issue:start-commit "${wt}" "${default_branch}" "${primary}" "${title}"
+  git -C "${wt}" push --quiet --set-upstream origin "${branch}"
+  if [[ -n "${stash}" ]]
+  then
+    issue:sweep-apply "${desk}" "${wt}" "${stash}" "${default_branch}" || return
+  fi
+  pr=$(issue:pull-request "${branch}" "${default_branch}" "${title}") || return
+  (( $# > 1 )) && issue:link-secondaries "${pr}" "${@:2}"
+
+  ok "Draft pull request #${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
+  ok "Worktree ready: ${wt}"
+  step "cd '${wt}'    # do all work there; this checkout stays on ${desk_branch}"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-issue.sh b/bin/kit-issue.sh
index b59451f..d3bac9b 100755
--- a/bin/kit-issue.sh
+++ b/bin/kit-issue.sh
@@ -4,12 +4,12 @@
 #
 # A linked branch, a worktree, a start commit, and a draft pull request.
 #
-# see: bin/gh.sh
+# see: bin/issue.sh, bin/forge.sh
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use gh
+use issue
 
 if [[ "${1:-}" == --help ]]
 then
@@ -17,6 +17,6 @@ then
   exit 0
 fi
 
-gh:issue "$@"
+issue:start "$@"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-linked.sh b/bin/kit-linked.sh
index 10c9330..ccc5fcb 100755
--- a/bin/kit-linked.sh
+++ b/bin/kit-linked.sh
@@ -2,15 +2,16 @@
 # kit-linked - refuse a pull request not linked to an open issue of this repository (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The delivered CI job's last step, and a check a desk can run on any pull request. The pull request is the
-# argument, else the one the GitHub event names on a runner, else the one for the current branch.
+# The delivered CI job's last check, and a check a desk can run on any pull request. The pull request is the
+# argument, else the one the forge says this checkout is working on. A linked issue of another repository, or a
+# closed one, is noted and does not count. On a runner the remedy also lands in the step summary.
 #
-# see: bin/gh.sh
+# see: bin/forge.sh
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use gh
+use forge
 
 if [[ "${1:-}" == --help ]]
 then
@@ -19,19 +20,47 @@ then
 fi
 
 number=${1:-}
-if [[ -z "${number}" && -n "${GITHUB_EVENT_PATH:-}" ]]
+[[ -n "${number}" ]] || number=$(forge:pr-here)
+if [[ ! "${number}" =~ ^[0-9]+$ ]]
 then
-  number=$(jq --raw-output '.pull_request.number // empty' "${GITHUB_EVENT_PATH}")
+  error "name the pull request: kit linked <number> (none was given, and this checkout is working on none)"
+  exit 2
 fi
-if [[ -z "${number}" ]]
+repo=$(forge:repo) || exit 1
+url=$(forge:repo-url) || exit 1
+remedy=$(printf '%s\n' \
+  "Link an open issue of this repository to [the pull request](${url}/pull/${number}):" "" \
+  "1. open it, and under **Development** pick one or more open issues" \
+  "2. re-run the check: linking fires no event, so it does not re-run on its own" "" \
+  "\`kit issue <N>\` makes this link when it starts the work.")
+refs=$(forge:pr-closing-issues "${number}") || exit 1
+if [[ -z "${refs}" ]]
 then
-  number=$(gh pr view --json number --jq .number 2>/dev/null || true)
+  error "pull request #${number} is not linked to any issue"
+  summary "### ❌ Pull request #${number} is not linked to any issue" "" "${remedy}"
+  exit 1
 fi
-if [[ ! "${number}" =~ ^[0-9]+$ ]]
+open=0
+while read -r n state issue_repo
+do
+  if [[ "${issue_repo}" != "${repo}" ]]
+  then
+    warn "skipping ${issue_repo}#${n}: it belongs to another repository"
+  elif [[ "${state}" != OPEN ]]
+  then
+    warn "#${n} is ${state}; merging will not change it"
+  else
+    open=$(( open + 1 ))
+  fi
+done <<<"${refs}"
+if (( open == 0 ))
 then
-  error "name the pull request: kit linked <number> (none was given, and the current branch has none)"
-  exit 2
+  error "every issue pull request #${number} is linked to is closed or belongs to another repository"
+  summary "### ❌ Every linked issue is closed or belongs to another repository" "" "${remedy}"
+  exit 1
 fi
-gh:linked-open-issue "${number}"
+closes=$(cut -d ' ' -f 1 <<<"${refs}" | sed 's/^/#/' | paste -s -d ' ' -)
+ok "pull request #${number} is linked to ${closes}"
+summary "✅ Linked to ${closes}."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/release.sh b/bin/release.sh
index 9daef76..c61bbaa 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -371,8 +371,8 @@ release:paths-beyond() {
 release:merged() { [[ "$1" == *.json ]]; }
 
 # release:fetch <version> prints the root of that release, fetching it if need be: the kit's cache first, then a
-# mise install if mise is here, then the GitHub release itself, unpacked into the cache. The version comes from a
-# manifest, so it is held to a version's shape before it is used in a path.
+# mise install if mise is here, then the release's public tarball with curl, unpacked into the cache. The version
+# comes from a manifest, so it is held to a version's shape before it is used in a path.
 release:fetch() {
   local version=$1 root cache fresh
   if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
@@ -395,13 +395,14 @@ release:fetch() {
       return 0
     fi
   fi
-  step "Fetching kit ${version} from its GitHub release"
+  step "Fetching kit ${version} from its release"
   fresh=$(mktemp -d)
-  if ! gh release download "v${version}" --repo empowerite/kit --pattern "kit-${version}.tar.gz" --output - \
-    2>/dev/null | tar --extract --gzip --directory "${fresh}" --strip-components 1
+  if ! curl --fail --silent --location \
+      "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz" 2>/dev/null \
+    | tar --extract --gzip --directory "${fresh}" --strip-components 1 2>/dev/null
   then
     rm -rf "${fresh}"
-    error "kit ${version} could not be fetched (run: gh auth status, or set KIT_BASE to a copy of it)"
+    error "kit ${version} could not be fetched from its release; set KIT_BASE to a copy of it"
     return 1
   fi
   mkdir -p "$(dirname "${cache}")"
diff --git a/bin/status.sh b/bin/status.sh
index cdd85f0..13c180a 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -96,71 +96,11 @@ status:age() {
   fi
 }
 
-# status:collect prints one JSON object per open pull request, oldest first: number, branch, title, createdAt, age
-# in seconds, state, checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes
-# [{number, title}]. The one request to GitHub; a request that fails is said so, and prints nothing.
+# status:collect prints one JSON object per open pull request, the documents the forge provider folds, or
+# nothing with a warning where the forge cannot be asked.
 status:collect() {
-  local repo query filter
-  use gh
-  if ! repo=$(gh:repo)
-  then
-    warn "this checkout does not resolve to a GitHub repository, so no pull request is shown (run: gh repo view)"
-    return 0
-  fi
-  # shellcheck disable=SC2016  # GraphQL variables
-  query='query($owner: String!, $name: String!) {
-    repository(owner: $owner, name: $name) {
-      pullRequests(states: OPEN, first: 100, orderBy: {field: CREATED_AT, direction: ASC}) {
-        nodes {
-          number title isDraft headRefName createdAt mergeStateStatus reviewDecision
-          closingIssuesReferences(first: 10) { nodes { number title } }
-          reviewThreads(first: 100) { nodes { isResolved } }
-          commits(last: 1) { nodes { commit { statusCheckRollup { contexts(first: 100) { nodes {
-            __typename
-            ... on CheckRun { name status conclusion startedAt completedAt }
-            ... on StatusContext { context state createdAt }
-          } } } } } }
-        }
-      }
-    }
-  }'
-  # shellcheck disable=SC2016  # a jq filter, with jq variables
-  filter='
-    def verdict: if .__typename == "CheckRun" then (if .status == "COMPLETED" then .conclusion else "PENDING" end)
-                 else .state end;
-    def pending: IN("PENDING", "EXPECTED");
-    def passed: IN("SUCCESS", "NEUTRAL", "SKIPPED");
-    (now | floor) as $now
-    | .data.repository.pullRequests.nodes[]
-    | [.commits.nodes[0].commit.statusCheckRollup.contexts.nodes[]?] as $checks
-    | ($checks | length) as $n
-    | ([$checks[] | verdict | select(pending)] | length) as $running
-    | ([$checks[] | verdict | select(passed)] | length) as $ok
-    | ([$checks[] | select((verdict | pending or passed) | not) | (.name // .context)] | first // "") as $failing
-    | (if $n == 0 then "NONE" elif $failing != "" then "FAILURE" elif $running > 0 then "PENDING" else "SUCCESS" end)
-      as $check
-    | ([$checks[] | .startedAt // .createdAt // empty | fromdateiso8601] | min) as $started
-    | ([$checks[] | .completedAt // empty | fromdateiso8601] | max) as $completed
-    | (if $started == null then null
-       elif $check == "PENDING" then $now - $started
-       elif $completed == null then null
-       else $completed - $started end) as $took
-    | ([.reviewThreads.nodes[]? | select(.isResolved | not)] | length) as $unresolved
-    | (if .isDraft then "draft"
-       elif $check == "PENDING" then "queued"
-       elif .mergeStateStatus == "DIRTY" then "conflicted"
-       elif $check == "FAILURE" then "failing:gate"
-       elif $check == "NONE" then "no-check"
-       elif $unresolved > 0 then "comments:open"
-       elif (.reviewDecision // "") | IN("REVIEW_REQUIRED", "CHANGES_REQUESTED") then "blocked:approval"
-       else "ready" end) as $state
-    | { number, branch: .headRefName, title, createdAt, age: ($now - (.createdAt | fromdateiso8601)), state: $state,
-        checks: { state: $check, passed: $ok, total: $n, failing: $failing, took: $took },
-        unresolved: $unresolved,
-        closes: [.closingIssuesReferences.nodes[] | { number, title }] }
-    | tojson'
-  gh api graphql --field owner="${repo%%/*}" --field name="${repo#*/}" --raw-field query="${query}" --jq "${filter}" \
-    2>/dev/null || warn "the pull requests could not be read from GitHub (run: gh auth status); none is shown"
+  use forge
+  forge:open-prs || warn "no pull request is shown; see above"
 }
 
 # status:fork <branch> <default-branch> prints the commit where <branch> left the default branch, or nothing.
diff --git a/docs/architecture.md b/docs/architecture.md
index 2a7b098..fddfd3d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -55,6 +55,12 @@ Everything after that happens in the worktree: `kit context` before a change, `k
 hand, `kit rebase` to bring the branch onto `origin/main` and push it, and `gh pr ready` when the pull request body is
 the report.
 
+Every call the loop makes to the forge, an issue's title, a branch linked to it, a pull request and its state,
+its checks and threads and linked issues, goes through one seam, `forge:` in `bin/forge.sh`, and a provider
+answers: `forge-github.sh` over `gh`, chosen by the `forge` setting or by origin's host. The core verbs never
+reach the seam, so a repository on no forge still installs, updates, checks, and runs `kit context`, and `gh` is
+the GitHub provider's requirement alone. A second forge is a second provider against the same names.
+
 The gate is `kit ci`, three checks that are each one kit command, run by the delivered GitHub Actions job for a
 pull request into the default branch, or by any pipeline. `kit gate` runs the repository's gate, the `gate`
 setting or the detected justfile recipe, Makefile target, or package.json script, and refuses when there is none,
diff --git a/tests/ci.bats b/tests/ci.bats
index 0872dd5..8d63fac 100644
--- a/tests/ci.bats
+++ b/tests/ci.bats
@@ -11,6 +11,7 @@ setup() {
   repo=$(mktemp -d)
   cd "${repo}"
   git init --quiet --initial-branch=main
+  git remote add origin https://github.com/empowerite/example.git
   "${kit_checkout}/bin/kit" install >/dev/null
 }
 
diff --git a/tests/forge.bats b/tests/forge.bats
new file mode 100644
index 0000000..61d6c8f
--- /dev/null
+++ b/tests/forge.bats
@@ -0,0 +1,70 @@
+#!/usr/bin/env bats
+# forge.bats - the forge is the setting, else the one origin's host names, and an unknown one is refused by name
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+# provider prints the provider the seam picks here.
+provider() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use forge && forge:provider'
+}
+
+@test "an origin at github.com names the github provider, by https or ssh" {
+  git remote add origin https://github.com/empowerite/kit.git
+  run provider
+  [ "$status" -eq 0 ]
+  [ "$output" = "github" ]
+  git remote set-url origin git@github.com:empowerite/kit.git
+  run provider
+  [ "$output" = "github" ]
+}
+
+@test "an origin elsewhere, or none, is refused naming the setting and the forges the kit knows" {
+  git remote add origin https://gitlab.com/empowerite/kit.git
+  run provider
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"set forge in .kit/settings.yml; origin's host 'gitlab.com' names no forge the kit knows (github)"* ]]
+  git remote remove origin
+  run provider
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"origin's host 'none'"* ]]
+}
+
+@test "the forge setting wins, and an unknown one is refused by name" {
+  git remote add origin https://gitlab.com/empowerite/kit.git
+  mkdir .kit && printf 'forge: github\n' > .kit/settings.yml
+  run provider
+  [ "$status" -eq 0 ]
+  [ "$output" = "github" ]
+  printf 'forge: sourcehut\n' > .kit/settings.yml
+  run provider
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"'sourcehut' is not a forge the kit knows; the forges are: github"* ]]
+}
+
+@test "the core verbs need no forge and no gh" {
+  mkdir -p "${BATS_TEST_TMPDIR}/shims" && printf '#!/usr/bin/env bash\nexit 127\n' > "${BATS_TEST_TMPDIR}/shims/gh"
+  chmod +x "${BATS_TEST_TMPDIR}/shims/gh"
+  run env PATH="${BATS_TEST_TMPDIR}/shims:${PATH}" "${kit_root}/bin/kit" install claude
+  [ "$status" -eq 0 ]
+  run env PATH="${BATS_TEST_TMPDIR}/shims:${PATH}" "${kit_root}/bin/kit" check
+  [ "$status" -eq 0 ]
+  run env PATH="${BATS_TEST_TMPDIR}/shims:${PATH}" "${kit_root}/bin/kit" context justfile
+  [ "$status" -eq 0 ]
+  run env PATH="${BATS_TEST_TMPDIR}/shims:${PATH}" "${kit_root}/bin/kit" status --no-fetch
+  [[ "$output" == *"set forge in .kit/settings.yml"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 8d66853..e4574be 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -336,8 +336,8 @@ later-release() {
   mkdir -p "${repo}.newer" && cp -R "${repo}.later/bin" "${repo}.later/modules" "${repo}.newer/"
   printf '9.9.10\n' > "${repo}.newer/version"
   printf 'edited\n' >> .kit/rules/bash.md
-  # neither the cache, nor mise, nor gh can produce 9.9.9
-  run env PATH="$(shims mise gh)" "${repo}.newer/bin/kit" update
+  # neither the cache, nor mise, nor the release can produce 9.9.9
+  run env PATH="$(shims mise curl)" "${repo}.newer/bin/kit" update
   [ "$status" -eq 1 ]
   [[ "$output" == *"could not be fetched"* ]]
   [[ "$output" == *".kit/rules/bash.md cannot be updated without the base release 9.9.9"* ]]
diff --git a/tests/linked.bats b/tests/linked.bats
index 87324ad..d56f4f6 100644
--- a/tests/linked.bats
+++ b/tests/linked.bats
@@ -9,6 +9,7 @@ setup() {
   repo=$(mktemp -d)
   cd "${repo}"
   git init --quiet --initial-branch=main
+  git remote add origin https://github.com/empowerite/example.git
 }
 
 teardown() {

From 01d021ff3d5ca1548cbff89bbc5c39eec9b66898 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 23:12:21 -0700
Subject: [PATCH 078/108] #5 kit lint driven by the rules, and lefthook reduced
 to wiring

Each rule names its linter in its frontmatter, lint: beside paths: and content:, and kit lint runs
every rule's linter once over the paths it governs, staged, named, or with --all-files every tracked
one; a linter not on PATH is a refusal. The lefthook fragment is one command, kit lint over the
staged paths, and this repository's hook file keeps only its refresh. The workflow rule, with
actionlint, is split out of the YAML rule, which now governs every YAML file with what holds for all
of them. The gate's own linting is kit lint --all-files. 61 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md                                   |  9 ++-
 .kit/lefthook.yml                             | 16 ++--
 .kit/manifest                                 | 11 +--
 .kit/rules/bash.md                            |  1 +
 .kit/rules/markdown.md                        |  1 +
 .kit/rules/workflows.md                       | 30 +++++++
 .kit/rules/yaml.md                            | 23 +-----
 README.md                                     |  7 +-
 bin/kit                                       |  3 +-
 bin/kit-lint.sh                               | 78 +++++++++++++++++--
 docs/architecture.md                          |  4 +-
 docs/context.md                               |  6 +-
 docs/modules.md                               | 10 ++-
 justfile                                      | 12 ++-
 lefthook.yml                                  | 14 ++--
 modules/kit/files/repo/.kit/1st.md            |  9 ++-
 modules/kit/files/repo/.kit/rules/bash.md     |  1 +
 modules/kit/files/repo/.kit/rules/markdown.md |  1 +
 .../kit/files/repo/.kit/rules/workflows.md    | 30 +++++++
 modules/kit/files/repo/.kit/rules/yaml.md     | 23 +-----
 modules/lefthook/docs/README.md               |  8 +-
 modules/lefthook/files/repo/.kit/lefthook.yml | 16 ++--
 modules/lefthook/module.yml                   |  2 +-
 tests/context.bats                            |  5 +-
 tests/lint.bats                               | 34 ++++++--
 25 files changed, 240 insertions(+), 114 deletions(-)
 create mode 100644 .kit/rules/workflows.md
 create mode 100644 modules/kit/files/repo/.kit/rules/workflows.md

diff --git a/.kit/1st.md b/.kit/1st.md
index 578a58f..5aa4900 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -71,7 +71,8 @@ A worker is whoever implements one issue in the worktree that issue names.
 ## Rules by file type
 
 Each file kind has a rule file under `.kit/rules/`, and each rule file's header names what it governs: `paths:`,
-globs on the repository path, and `content:`, patterns on the first line. Before you create or change a file, run
+globs on the repository path, and `content:`, patterns on the first line; `lint:` names the linter `kit lint`
+runs over the paths it governs. Before you create or change a file, run
 `kit context <path>`. It names the rules that govern the file and records that you asked. Read what it names. No
 harness holds a copy of a rule; this call is how every harness, and every person, finds it.
 
@@ -81,6 +82,7 @@ harness holds a copy of a rule; this call is how every harness, and every person
 | Bash | [rules/bash.md](rules/bash.md) |
 | Just | [rules/just.md](rules/just.md) |
 | YAML | [rules/yaml.md](rules/yaml.md) |
+| Workflows | [rules/workflows.md](rules/workflows.md) |
 | JSON | [rules/json.md](rules/json.md) |
 | Ignore lists | [rules/gitignore.md](rules/gitignore.md) |
 
@@ -96,8 +98,9 @@ lives under `.kit/modules/` and is taken the same way. A `.json` destination is
 only the entries it writes; everything else is copied as it is.
 
 - `kit`: this file and the rules, discovered through `kit context`.
-- `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
-  `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
+- `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
+  `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
+  it runs each rule's linter over the paths the rule governs.
 - `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
   `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
   anywhere.
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index c0b9cfc..8fa1f10 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -1,17 +1,13 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# Which linter runs over which paths before a commit. The repository's lefthook.yml takes this with
-# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name, so a command of the same
-# name there overrides one here. `kit lint` runs this hook by hand, over the staged paths or, with --all-files,
-# over every tracked path. Once per clone: lefthook install
+# The pre-commit hook runs kit lint over the staged paths: each rule's own linter, declared in the rule's
+# frontmatter, over the paths the rule governs. The repository's lefthook.yml takes this with
+# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name. Once per clone:
+# lefthook install
 #
 # see: https://lefthook.dev
 
 pre-commit:
   commands:
-    shellcheck:
-      glob: "*.{sh,bash}"
-      run: shellcheck --shell=bash --external-sources {staged_files}
-    actionlint:
-      glob: ".github/workflows/*.{yml,yaml}"
-      run: actionlint {staged_files}
+    kit-lint:
+      run: kit lint {staged_files}
diff --git a/.kit/manifest b/.kit/manifest
index f19151a..65ef01a 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -4,11 +4,12 @@ modules kit ci-github claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
 24b66b6015ccf244245373009b35fc9610c52dc16d88ab6c842f21d116c74f02  .github/workflows/kit-ci.yml
-93c975792f902ea5439c062543711681468538ce837d924e4c49e730d37e8382  .kit/1st.md
-953e2f7c9804ca39922ca1ccb3f9b136b0283d56a200dcebfbbce594e9102faa  .kit/lefthook.yml
-8c512e3f5951b5263c140500fb2494c45f92394b44ec643cc8d6475736f5ab11  .kit/rules/bash.md
+da512121945d6c481e055dda1bdb34e7ca0a37d2c97b2068825ea1113502649c  .kit/1st.md
+f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
+bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
 17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
 693815dcde0979638e20f021a6e879e5a3cc1420374f1d1329fc92d936e3461d  .kit/rules/json.md
 9a32591381c47fbb449a7b1f2ab900911a18901cbec3e768663db1171c6a9262  .kit/rules/just.md
-ea453a4dc6e1146527e51079cf1cefb0a70a4ca3e8e9151cc192daa956e592de  .kit/rules/markdown.md
-642e5d8618c0bc7810aa8b19bc63b68735811c3e33737e864fdf105c06298754  .kit/rules/yaml.md
+a809a1969212d3d21dfafb903d0d2fd04c97ce45a057e896fcc7dcf555c18689  .kit/rules/markdown.md
+2f0cfeca313280bf984aaad927cd459ecf61f93861a11ccc839b7d5b8406cbac  .kit/rules/workflows.md
+158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index 2d23371..7cdc937 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -5,6 +5,7 @@ paths:
   - "**/*.bash"
 content:
   - "^#!.*/(env +)?(ba)?sh( |$)"
+lint: shellcheck --shell=bash --external-sources
 ---
 # Bash
 
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index 7afc056..73b95ca 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -2,6 +2,7 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.md"
+lint: markdownlint-cli2
 ---
 # Markdown
 
diff --git a/.kit/rules/workflows.md b/.kit/rules/workflows.md
new file mode 100644
index 0000000..37fb51f
--- /dev/null
+++ b/.kit/rules/workflows.md
@@ -0,0 +1,30 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - ".github/workflows/*.yml"
+  - ".github/workflows/*.yaml"
+lint: actionlint
+---
+# Workflows
+
+Applies to GitHub Actions workflows, under `.github/workflows/`. The YAML rule applies to them as well.
+
+## Shape
+
+1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
+   reader would not guess from the keys.
+2. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
+3. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
+   breaks the requirement.
+4. `permissions` is declared at the top and names the least the jobs need.
+
+## Steps
+
+1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. A step has a `name` that is the policy it enforces, in kebab-case.
+3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
+4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
+   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
+5. A step whose verdict a reader looks for writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
+7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step.
diff --git a/.kit/rules/yaml.md b/.kit/rules/yaml.md
index 69993c7..222fa95 100644
--- a/.kit/rules/yaml.md
+++ b/.kit/rules/yaml.md
@@ -6,29 +6,14 @@ paths:
 ---
 # YAML
 
-Applies to `*.yml` and `*.yaml`. Shape and Steps apply to GitHub Actions workflows, under `.github/workflows/`;
-Comments apply to every YAML file.
+Applies to `*.yml` and `*.yaml`. A GitHub Actions workflow follows the workflows rule as well.
 
 ## Shape
 
-1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
-   reader would not guess from the keys.
+1. The file opens with a comment: what the file configures and the one thing a reader would not guess from the
+   keys.
 2. Two-space indentation. No tabs. No trailing whitespace.
-3. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
-4. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
-   breaks the requirement.
-5. `permissions` is declared at the top and names the least the jobs need.
-
-## Steps
-
-1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
-2. A step has a `name` that is the policy it enforces, in kebab-case.
-3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
-   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
-5. A step whose verdict a reader looks for writes one `✅` line to the summary.
-6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
+3. A scalar that holds a colon followed by a space, or opens with a reserved character, is quoted.
 
 ## Comments
 
diff --git a/README.md b/README.md
index 22c15c0..d51fe0c 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ The rules are the smaller part. The point is verification that does not depend o
 - `kit ci`, which refuses a pull request without a linked open issue and refuses to pass a gate that did not
   run, from the delivered GitHub Actions job or from any pipeline;
 - `kit check`, which holds every delivered file to its release;
-- a pre-commit hook that runs the linters over what is staged;
+- `kit lint`, each rule's own linter over the paths it governs, before a commit or anywhere;
 - a deny list that refuses the spellings the rules forbid;
 - `kit status`, which shows what every pull request's checks said.
 
@@ -79,8 +79,9 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
 - Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
   or any command as `gate` in `.kit/settings.yml`. `kit ci` runs it, with `kit check` and `kit linked`, from the
   delivered workflow or from any pipeline of your own, and refuses when there is none.
-- Take the pre-commit linters: pin `lefthook`, put `extends: [.kit/lefthook.yml]` in `lefthook.yml`, and run
-  `lefthook install` once per clone.
+- Run the linters before a commit: `kit lint` runs each rule's own linter over the staged paths with no hook
+  manager at all, and the `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
+  in `lefthook.yml`, and run `lefthook install` once per clone.
 
 `claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is
 present. The module places `.claude/CLAUDE.md` importing `AGENTS.md`, so Claude reads what every agent reads in
diff --git a/bin/kit b/bin/kit
index d809f8a..2d9dd17 100755
--- a/bin/kit
+++ b/bin/kit
@@ -48,7 +48,8 @@ usage: kit <verb> [<argument>…]
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
   status [--no-fetch] [--json]
                         the desk, the worktrees, and the open pull requests
-  lint [--all-files]    run the pre-commit hook's linters by hand, over the staged paths or every path
+  lint [--all-files] [<path>…]
+                        run each rule's linter over the paths it governs: staged, named, or every tracked one
   version               print this release's version
 
 Each verb answers --help.
diff --git a/bin/kit-lint.sh b/bin/kit-lint.sh
index 5b7fd7d..a6bfb38 100755
--- a/bin/kit-lint.sh
+++ b/bin/kit-lint.sh
@@ -1,21 +1,85 @@
 #!/usr/bin/env bash
-# kit-lint - run the pre-commit hook's linters by hand (kit verb)
+# kit-lint - run each rule's linter over the paths it governs (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# An alias for `lefthook run pre-commit`, so the linters a commit meets are the ones this runs, over the staged
-# paths, or over every path with --all-files. The arguments are Lefthook's.
+# The paths are the arguments, else the staged ones, else with --all-files every tracked one. Each is matched to
+# the rules that govern it, as kit context matches, and every rule whose frontmatter carries a `lint:` command
+# runs it once over its paths. A linter the rule names that is not on PATH is a refusal, not a skip. The exit
+# status is the number of rules whose linter refused. No hook manager is assumed; the lefthook module wires its
+# pre-commit hook to this verb.
+#
+# see: bin/context.sh, docs/context.md
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use context yaml
 
-if [[ "${1:-}" == --help ]]
+all=false
+paths=()
+for arg in "$@"
+do
+  case "${arg}" in
+    (--help)
+      echo "usage: kit lint [--all-files] [<path>…]" >&2
+      exit 0
+      ;;
+    (--all-files) all=true ;;
+    (-*)
+      error "unknown flag '${arg}' (usage: kit lint [--all-files] [<path>…])"
+      exit 2
+      ;;
+    (*) paths+=("${arg}")
+  esac
+done
+if (( ${#paths[@]} == 0 ))
+then
+  if [[ "${all}" == true ]]
+  then
+    readarray -t paths < <(git ls-files)
+  else
+    readarray -t paths < <(git diff --cached --name-only --diff-filter=ACMR)
+  fi
+fi
+if (( ${#paths[@]} == 0 ))
 then
-  echo "usage: kit lint [--all-files] [<lefthook run option>…]" >&2
+  ok "nothing to lint"
   exit 0
 fi
 
-guard:require tool:lefthook
-exec lefthook run pre-commit "$@"
+# The paths each rule governs, newline-separated, keyed by the rule file.
+declare -A governed=()
+for path in "${paths[@]}"
+do
+  path=$(context:relative "${path}")
+  [[ -f "${path}" ]] || continue
+  while IFS= read -r rule
+  do
+    [[ -n "${rule}" ]] || continue
+    governed[${rule}]+="${path}"$'\n'
+  done < <(context:rules "${path}")
+done
+
+refused=0
+for rule in $(printf '%s\n' "${!governed[@]}" | LC_ALL=C sort)
+do
+  lint=$(yaml:value "${rule}" lint)
+  [[ -n "${lint}" ]] || continue
+  read -r -a command <<<"${lint}"
+  readarray -t targets < <(printf '%s' "${governed[${rule}]}")
+  step "${rule}: ${lint} over ${#targets[@]} path(s)"
+  if ! guard:require "tool:${command[0]}"
+  then
+    refused=$(( refused + 1 ))
+    continue
+  fi
+  "${command[@]}" "${targets[@]}" || refused=$(( refused + 1 ))
+done
+if (( refused > 0 ))
+then
+  error "${refused} rule(s) refused; see above"
+  exit "${refused}"
+fi
+ok "every governed path passes its rule's linter"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/docs/architecture.md b/docs/architecture.md
index fddfd3d..bbda21e 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -41,7 +41,8 @@ file that exists. `kit context <path>` names the rules governing a path and appe
 `.kit/1st.md`, a person at the shell, a tool reading `--json`, and Claude Code's `PreToolUse` hook, which the
 `claude` module wires to `kit context --claude` so the rules are named before every write. The call names and
 never quotes: reading the rule stays an act the caller takes, and the log of asks is the record of what was
-named.
+named. A rule also names its linter, and `kit lint` runs each rule's linter over the paths the rule governs, so
+the hook manager a repository uses, if any, only has to call the verb.
 
 ## The loop and the gate
 
@@ -79,6 +80,7 @@ worktree with its commits past the fork, and every open pull request with its st
 | All three held, wherever CI runs | `kit ci`, the three checks as one verb, every one reported |
 | A file's rules were named to the agent | the Claude Code hook; `kit context` in every other harness |
 | A file's rules were asked for | `.git/kit/context.log`, one line per ask |
+| A file keeps its rule's mechanical part | `kit lint`, each rule's own linter over the paths it governs |
 | The forbidden spellings were not used | the harness's deny list, delivered by its adapter module |
 | The desk was not disturbed | `kit rebase` refusing the root checkout; `kit issue` never switching its branch |
 
diff --git a/docs/context.md b/docs/context.md
index 2a323d9..7c0c7e8 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -20,6 +20,7 @@ paths:
   - "**/*.sh"
 content:
   - "^#!.*/(env +)?(ba)?sh( |$)"
+lint: shellcheck --shell=bash --external-sources
 ---
 ```
 
@@ -30,7 +31,10 @@ content:
   bash script with no extension is bash by its shebang, and a file about to be created is governed by its path
   alone.
 
-A rule governs a file when any glob or any pattern matches.
+A rule governs a file when any glob or any pattern matches. `lint:` names the linter for the paths the rule
+governs: `kit lint` runs it once over the staged paths, the named ones, or with `--all-files` every tracked one,
+and a linter not on `PATH` is a refusal, not a skip. No hook manager is assumed; the `lefthook` module wires its
+pre-commit hook to the verb.
 
 ## Harness adapters
 
diff --git a/docs/modules.md b/docs/modules.md
index 81a15af..a024e95 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -77,8 +77,12 @@ answers:
   ci_runner: ubuntu-latest
 ```
 
-`answers` holds the values a module's templates take, overriding the module's own defaults. The other keys are
-the loop's choices, each described where the verb that reads it is.
+| Key | Meaning |
+| --- | --- |
+| `forge` | The provider the loop's verbs use, `github` in this release; detected from origin's host when absent. |
+| `gate` | What `kit gate` runs; a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script is detected when absent. |
+| `require_signing` | `true` makes `kit issue` refuse a desk without a signing key. |
+| `answers` | The values a module's templates take, overriding the module's own defaults. |
 
 ## Modules a repository defines
 
@@ -103,7 +107,7 @@ base. A rule file it places under `.kit/rules/` is found by `kit context` like a
 | Module | Default | Depends on | Delivers |
 | --- | --- | --- | --- |
 | `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md` |
-| `lefthook` | no | `kit` | `.kit/lefthook.yml` |
+| `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` |
 | `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
 | `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
 
diff --git a/justfile b/justfile
index 675010e..5023b3d 100644
--- a/justfile
+++ b/justfile
@@ -20,19 +20,17 @@ _: help
 
 set export := true
 
-# The gate: shellcheck over every bash file, actionlint over every workflow, markdownlint over every markdown
-# file, every module.yml against modules/module.schema.json, the bats suite, and bin/kit check over this
-# repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
+# The gate: kit lint over every tracked path, each rule's own linter, every module.yml against
+# modules/module.schema.json, the bats suite, and bin/kit check over this repository's installed copy of its own
+# kit. The runner runs it on every pull request, and a desk runs it the
 # same way; the pre-commit hook is the narrower, faster check over the staged paths.
 #
 #   just ci
-[doc("🚦 The gate: shellcheck, actionlint, markdownlint, the module schema, bats, kit check")]
+[doc("🚦 The gate: kit lint, the module schema, bats, kit check")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  mise exec -- shellcheck --shell=bash --external-sources bin/kit bin/*.sh
-  mise exec -- actionlint
-  mise exec -- markdownlint-cli2 '**/*.md'
+  mise exec -- bin/kit lint --all-files
   mise exec -- ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
diff --git a/lefthook.yml b/lefthook.yml
index 7df58ed..1d14761 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,23 +1,19 @@
 # lefthook.yml - this repository's git hooks; see: https://lefthook.dev
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The kit's own linters come from its installed fragment, the way a consumer takes them. This repository adds
-# shellcheck over the dispatcher, which carries no extension, markdownlint, and the refresh of the installed
-# copies. Once per clone: lefthook install
+# The linters come from the kit's installed fragment, the way a consumer takes them: kit lint over the staged
+# paths, each rule's own linter. This repository adds the refresh of its installed copies. Once per clone:
+# lefthook install
 
 extends:
   - .kit/lefthook.yml
 
 pre-commit:
   commands:
-    shellcheck-dispatcher:
-      glob: "bin/kit"
-      run: shellcheck --shell=bash --external-sources {staged_files}
-    markdownlint:
-      glob: "*.md"
-      run: markdownlint-cli2 {staged_files}
     # A change to a delivered file's source rewrites the installed copies in the same commit; the recipe stages
     # what it rewrote.
     refresh:
       glob: "modules/**"
       run: just refresh
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 578a58f..5aa4900 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -71,7 +71,8 @@ A worker is whoever implements one issue in the worktree that issue names.
 ## Rules by file type
 
 Each file kind has a rule file under `.kit/rules/`, and each rule file's header names what it governs: `paths:`,
-globs on the repository path, and `content:`, patterns on the first line. Before you create or change a file, run
+globs on the repository path, and `content:`, patterns on the first line; `lint:` names the linter `kit lint`
+runs over the paths it governs. Before you create or change a file, run
 `kit context <path>`. It names the rules that govern the file and records that you asked. Read what it names. No
 harness holds a copy of a rule; this call is how every harness, and every person, finds it.
 
@@ -81,6 +82,7 @@ harness holds a copy of a rule; this call is how every harness, and every person
 | Bash | [rules/bash.md](rules/bash.md) |
 | Just | [rules/just.md](rules/just.md) |
 | YAML | [rules/yaml.md](rules/yaml.md) |
+| Workflows | [rules/workflows.md](rules/workflows.md) |
 | JSON | [rules/json.md](rules/json.md) |
 | Ignore lists | [rules/gitignore.md](rules/gitignore.md) |
 
@@ -96,8 +98,9 @@ lives under `.kit/modules/` and is taken the same way. A `.json` destination is
 only the entries it writes; everything else is copied as it is.
 
 - `kit`: this file and the rules, discovered through `kit context`.
-- `lefthook`: `.kit/lefthook.yml`, which linter runs over which paths before a commit on a desk. A repository's
-  `lefthook.yml` takes it with `extends` and adds commands of its own, and `kit lint` runs the same hook by hand.
+- `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
+  `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
+  it runs each rule's linter over the paths the rule governs.
 - `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
   `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
   anywhere.
diff --git a/modules/kit/files/repo/.kit/rules/bash.md b/modules/kit/files/repo/.kit/rules/bash.md
index 2d23371..7cdc937 100644
--- a/modules/kit/files/repo/.kit/rules/bash.md
+++ b/modules/kit/files/repo/.kit/rules/bash.md
@@ -5,6 +5,7 @@ paths:
   - "**/*.bash"
 content:
   - "^#!.*/(env +)?(ba)?sh( |$)"
+lint: shellcheck --shell=bash --external-sources
 ---
 # Bash
 
diff --git a/modules/kit/files/repo/.kit/rules/markdown.md b/modules/kit/files/repo/.kit/rules/markdown.md
index 7afc056..73b95ca 100644
--- a/modules/kit/files/repo/.kit/rules/markdown.md
+++ b/modules/kit/files/repo/.kit/rules/markdown.md
@@ -2,6 +2,7 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.md"
+lint: markdownlint-cli2
 ---
 # Markdown
 
diff --git a/modules/kit/files/repo/.kit/rules/workflows.md b/modules/kit/files/repo/.kit/rules/workflows.md
new file mode 100644
index 0000000..37fb51f
--- /dev/null
+++ b/modules/kit/files/repo/.kit/rules/workflows.md
@@ -0,0 +1,30 @@
+---
+# Delivered by kit, not edited by hand. A change is a new release, then kit update.
+paths:
+  - ".github/workflows/*.yml"
+  - ".github/workflows/*.yaml"
+lint: actionlint
+---
+# Workflows
+
+Applies to GitHub Actions workflows, under `.github/workflows/`. The YAML rule applies to them as well.
+
+## Shape
+
+1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
+   reader would not guess from the keys.
+2. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
+3. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
+   breaks the requirement.
+4. `permissions` is declared at the top and names the least the jobs need.
+
+## Steps
+
+1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. A step has a `name` that is the policy it enforces, in kebab-case.
+3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
+4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
+   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
+5. A step whose verdict a reader looks for writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
+7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step.
diff --git a/modules/kit/files/repo/.kit/rules/yaml.md b/modules/kit/files/repo/.kit/rules/yaml.md
index 69993c7..222fa95 100644
--- a/modules/kit/files/repo/.kit/rules/yaml.md
+++ b/modules/kit/files/repo/.kit/rules/yaml.md
@@ -6,29 +6,14 @@ paths:
 ---
 # YAML
 
-Applies to `*.yml` and `*.yaml`. Shape and Steps apply to GitHub Actions workflows, under `.github/workflows/`;
-Comments apply to every YAML file.
+Applies to `*.yml` and `*.yaml`. A GitHub Actions workflow follows the workflows rule as well.
 
 ## Shape
 
-1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
-   reader would not guess from the keys.
+1. The file opens with a comment: what the file configures and the one thing a reader would not guess from the
+   keys.
 2. Two-space indentation. No tabs. No trailing whitespace.
-3. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
-4. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
-   breaks the requirement.
-5. `permissions` is declared at the top and names the least the jobs need.
-
-## Steps
-
-1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
-2. A step has a `name` that is the policy it enforces, in kebab-case.
-3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
-   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
-5. A step whose verdict a reader looks for writes one `✅` line to the summary.
-6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because `mise.toml` pins it and `jdx/mise-action` installs it, never by `curl` in a step.
+3. A scalar that holds a colon followed by a space, or opens with a reserved character, is quoted.
 
 ## Comments
 
diff --git a/modules/lefthook/docs/README.md b/modules/lefthook/docs/README.md
index 139f18b..beff980 100644
--- a/modules/lefthook/docs/README.md
+++ b/modules/lefthook/docs/README.md
@@ -1,5 +1,7 @@
 # The lefthook module
 
-Places `.kit/lefthook.yml`, which says which linter runs over which paths before a commit. The repository's own
-`lefthook.yml` takes it with `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name.
-`kit lint` runs the same hook by hand. The repository pins `lefthook` itself, since only a desk runs a hook.
+Places `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths, so each rule's own
+linter runs over the paths the rule governs before a commit. The repository's own `lefthook.yml` takes it with
+`extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name. The repository pins
+`lefthook` itself, since only a desk runs a hook, and `kit lint` runs the same linters with no hook manager at
+all.
diff --git a/modules/lefthook/files/repo/.kit/lefthook.yml b/modules/lefthook/files/repo/.kit/lefthook.yml
index c0b9cfc..8fa1f10 100644
--- a/modules/lefthook/files/repo/.kit/lefthook.yml
+++ b/modules/lefthook/files/repo/.kit/lefthook.yml
@@ -1,17 +1,13 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# Which linter runs over which paths before a commit. The repository's lefthook.yml takes this with
-# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name, so a command of the same
-# name there overrides one here. `kit lint` runs this hook by hand, over the staged paths or, with --all-files,
-# over every tracked path. Once per clone: lefthook install
+# The pre-commit hook runs kit lint over the staged paths: each rule's own linter, declared in the rule's
+# frontmatter, over the paths the rule governs. The repository's lefthook.yml takes this with
+# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name. Once per clone:
+# lefthook install
 #
 # see: https://lefthook.dev
 
 pre-commit:
   commands:
-    shellcheck:
-      glob: "*.{sh,bash}"
-      run: shellcheck --shell=bash --external-sources {staged_files}
-    actionlint:
-      glob: ".github/workflows/*.{yml,yaml}"
-      run: actionlint {staged_files}
+    kit-lint:
+      run: kit lint {staged_files}
diff --git a/modules/lefthook/module.yml b/modules/lefthook/module.yml
index f68ea0b..1316c6c 100644
--- a/modules/lefthook/module.yml
+++ b/modules/lefthook/module.yml
@@ -2,6 +2,6 @@
 # ----------------------------------------------------------------------------------------------------------------------
 # docs/modules.md says what each key means.
 
-description: "Which linter runs over which paths before a commit, for the repository's lefthook.yml to extend"
+description: "A pre-commit hook that runs kit lint over the staged paths, for the repository's lefthook.yml to extend"
 depends:
   - kit
diff --git a/tests/context.bats b/tests/context.bats
index 1314280..3643081 100644
--- a/tests/context.bats
+++ b/tests/context.bats
@@ -32,8 +32,9 @@ teardown() {
   [ -z "$output" ]
   run "${kit_checkout}/bin/kit" context docs/a.md "${PWD}/.github/workflows/x.yml" lib/x.md
   [ "${lines[0]}" = ".kit/rules/markdown.md" ]
-  [ "${lines[1]}" = ".kit/rules/yaml.md" ]
-  [ "${#lines[@]}" -eq 2 ]
+  [ "${lines[1]}" = ".kit/rules/workflows.md" ]
+  [ "${lines[2]}" = ".kit/rules/yaml.md" ]
+  [ "${#lines[@]}" -eq 3 ]
 }
 
 @test "a relative path is taken from the directory the command was typed in" {
diff --git a/tests/lint.bats b/tests/lint.bats
index bd09c26..285797d 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -1,23 +1,23 @@
 #!/usr/bin/env bats
-# lint.bats - kit lint runs the linters the delivered fragment declares, over the staged paths or every path
+# lint.bats - kit lint runs each rule's linter over the paths it governs, staged, named, or every tracked one
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
-  lefthook version >/dev/null 2>&1 || skip "lefthook is a desk tool (mise.desk.toml, MISE_ENV=desk)"
+  shellcheck --version >/dev/null 2>&1 || skip "shellcheck is the bash rule's linter, and it is not on PATH"
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
   repo=$(mktemp -d)
-  export KIT_HOME="${repo}.home" XDG_CACHE_HOME="${repo}.cache"
-  mkdir "${KIT_HOME}" "${XDG_CACHE_HOME}"
   cd "${repo}"
   git init --quiet --initial-branch=main
   "${kit_checkout}/bin/kit" install >/dev/null
-  printf 'extends:\n  - .kit/lefthook.yml\n' > lefthook.yml
   printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
   printf '#!/usr/bin/env bash\necho "${x:-}"\n' > good.sh
+  printf '#!/usr/bin/env bash\necho $y\n' > tool
 }
 
 teardown() {
-  rm -rf "${repo}" "${repo}.home" "${repo}.cache"
+  rm -rf "${repo}"
 }
 
 @test "lint refuses a staged bash file shellcheck faults, and passes a clean one" {
@@ -25,19 +25,39 @@ teardown() {
   run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 1 ]
   [[ "$output" == *"SC2086"* ]]
+  [[ "$output" == *".kit/rules/bash.md: shellcheck"* ]]
   git reset --quiet && git add good.sh
   run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 0 ]
+  [[ "$output" == *"every governed path passes"* ]]
 }
 
-@test "lint --all-files reads every tracked path, where lint alone reads only the staged ones" {
+@test "a named path is linted by the rule its first line names, and --all-files reads every tracked path" {
+  run "${kit_checkout}/bin/kit" lint tool
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"SC2086"* ]]
+  git add good.sh
+  git -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false commit --quiet --no-verify --message good
   git add bad.sh
   git -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false commit --quiet --no-verify --message bad
   run "${kit_checkout}/bin/kit" lint
   [ "$status" -eq 0 ]
+  [[ "$output" == *"nothing to lint"* ]]
   run "${kit_checkout}/bin/kit" lint --all-files
   [ "$status" -eq 1 ]
   [[ "$output" == *"bad.sh"* ]]
 }
 
+@test "a linter a rule names that is not on PATH is a refusal, named" {
+  mkdir -p "${BATS_TEST_TMPDIR}/path" && ln -s "$(command -v git)" "${BATS_TEST_TMPDIR}/path/git"
+  for tool in bash jq awk sed grep sort cut paste tr find head tail cat mkdir rm mv cp dirname basename date env uname readlink comm
+  do
+    p=$(command -v "${tool}") && ln -s "${p}" "${BATS_TEST_TMPDIR}/path/${tool}" || true
+  done
+  git add good.sh
+  run env PATH="${BATS_TEST_TMPDIR}/path" "${kit_checkout}/bin/kit" lint
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"shellcheck is not on PATH"* ]]
+}
+
 # ----------------------------------------------------------------------------------------------------------------------

From 3fe95baf4db42753eb5f5c543d32c3f0ca4f9596 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 23:23:11 -0700
Subject: [PATCH 079/108] #5 regions: a kit-owned region inside a file the
 repository owns, for AGENTS.md and .gitignore

A third placement rule beside copy and JSON merge. A file under a module's regions/<base>/ is
written between marker comments naming the module, an HTML comment in markdown and a hash comment
elsewhere, inside the file at the same path: appended after a blank line where the file has no
region, the whole file where there is none. kit check holds only the content between the markers,
kit update replaces or three-way merges only that, and removal takes the region out, removing a file
it leaves empty. The kit module places two: the sentence in AGENTS.md that sends every agent to
.kit/1st.md, and the /worktrees/ entry in .gitignore, so a repository's own instructions and ignore
list never fail kit check. This repository carries both regions, and its refresh is now kit update
from the index export, which keeps its own text around them. 63 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .gitignore                          |   2 +
 .kit/1st.md                         |   3 +-
 .kit/manifest                       |   4 +-
 AGENTS.md                           |   6 +-
 README.md                           |  12 +-
 bin/kit-check.sh                    |  26 ++--
 bin/kit-update.sh                   |  20 ++-
 bin/release.sh                      | 203 ++++++++++++++++++++++------
 docs/architecture.md                |   7 +-
 docs/delivery.svg                   |   4 +-
 docs/modules.md                     |  16 ++-
 justfile                            |  24 ++--
 modules/kit/docs/README.md          |   4 +-
 modules/kit/files/repo/.kit/1st.md  |   3 +-
 modules/kit/regions/repo/.gitignore |   2 +
 modules/kit/regions/repo/AGENTS.md  |   2 +
 tests/kit.bats                      |  44 ++++++
 17 files changed, 292 insertions(+), 90 deletions(-)
 create mode 100644 modules/kit/regions/repo/.gitignore
 create mode 100644 modules/kit/regions/repo/AGENTS.md

diff --git a/.gitignore b/.gitignore
index ba8b0d5..a105eaa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,9 @@
 # .gitignore - untracked files and folders
 # ----------------------------------------------------------------------------------------------------------------------
 
+# kit:begin kit
 # per-issue worktrees for agents; see: .kit/1st.md
 /worktrees/
+# kit:end kit
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/1st.md b/.kit/1st.md
index 5aa4900..7252681 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -97,7 +97,8 @@ delivers is a module, and a repository activates the modules it takes: `kit inst
 lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
 only the entries it writes; everything else is copied as it is.
 
-- `kit`: this file and the rules, discovered through `kit context`.
+- `kit`: this file and the rules, discovered through `kit context`; the sentence in `AGENTS.md` that points here
+  and the `/worktrees/` entry in `.gitignore`, each a region the kit owns inside a file the repository owns.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/.kit/manifest b/.kit/manifest
index 65ef01a..10ba8dd 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -4,7 +4,8 @@ modules kit ci-github claude lefthook
 930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
 24b66b6015ccf244245373009b35fc9610c52dc16d88ab6c842f21d116c74f02  .github/workflows/kit-ci.yml
-da512121945d6c481e055dda1bdb34e7ca0a37d2c97b2068825ea1113502649c  .kit/1st.md
+919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
+2771b22ceee05bf708961013276bd5c760fd4101b8892b546e0109ad1d2b7b3f  .kit/1st.md
 f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
 17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
@@ -13,3 +14,4 @@ bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bas
 a809a1969212d3d21dfafb903d0d2fd04c97ce45a057e896fcc7dcf555c18689  .kit/rules/markdown.md
 2f0cfeca313280bf984aaad927cd459ecf61f93861a11ccc839b7d5b8406cbac  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
+dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/AGENTS.md b/AGENTS.md
index 9c4c5db..a115149 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,9 @@
+<!-- kit:begin kit -->
 Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
-repository trustworthy. This repository is the kit's own source, and uses it.
+repository trustworthy.
+<!-- kit:end kit -->
+
+This repository is the kit's own source, and uses it.
 
 ## This repository's own rules
 
diff --git a/README.md b/README.md
index d51fe0c..51c95ac 100644
--- a/README.md
+++ b/README.md
@@ -67,14 +67,10 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
   always in; `ci-github` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the
   Claude Code adapter. `kit install ci-github lefthook claude` takes all three, and `kit module add` takes one
   later.
-- Point `AGENTS.md` at the entry file, in prose, the same sentence for every agent:
-
-  ```markdown
-  Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
-  repository trustworthy.
-  ```
-
-  The rest of `AGENTS.md` is yours.
+- `install` writes the sentence every agent reads into a region of `AGENTS.md`, between `<!-- kit:begin kit -->`
+  and `<!-- kit:end kit -->`, making the file where there is none and leaving the rest of it yours, and the
+  `/worktrees/` entry into a region of `.gitignore` the same way. Move the region where you like; `kit check`
+  holds only what is between the markers.
 - Commit what `install` wrote.
 - Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
   or any command as `gate` in `.kit/settings.yml`. `kit ci` runs it, with `kit check` and `kit linked`, from the
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index 908be00..c878714 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -40,24 +40,26 @@ do
   while IFS=$'\t' read -r path src
   do
     dest=$(release:dest "${base}" "${path}")
+    kind=$(release:kind "${src}" "${dest}")
     if [[ ! -f "${dest}" ]]
     then
       error "${dest} is missing"
       findings=$(( findings + 1 ))
-    elif release:merged "${dest}"
+    elif [[ "${kind}" == merge ]] && ! command -v jq >/dev/null 2>&1
     then
-      if ! command -v jq >/dev/null 2>&1
-      then
-        error "run: mise install (jq is not on PATH, so ${dest} could not be read)"
-        findings=$(( findings + 1 ))
-      elif ! release:json-holds "${dest}" "${src}"
-      then
-        error "${dest} is missing an entry the kit writes; run: kit update"
-        findings=$(( findings + 1 ))
-      fi
-    elif ! cmp --silent "${src}" "${dest}"
+      error "run: mise install (jq is not on PATH, so ${dest} could not be read)"
+      findings=$(( findings + 1 ))
+    elif [[ "${kind}" == region ]] && ! release:installed "${src}" "${dest}" >/dev/null
+    then
+      error "${dest} has no kit region; run: kit update"
+      findings=$(( findings + 1 ))
+    elif ! release:holds "${src}" "${dest}"
     then
-      error "${dest} differs from the pinned release"
+      case "${kind}" in
+        (merge) error "${dest} is missing an entry the kit writes; run: kit update" ;;
+        (region) error "${dest}: the kit's region differs from the pinned release" ;;
+        (*) error "${dest} differs from the pinned release" ;;
+      esac
       findings=$(( findings + 1 ))
     fi
   done <<<"${delivered}"
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 67fa26a..50e9d58 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -67,18 +67,32 @@ do
       skipped=$(( skipped + 1 ))
       continue
     fi
-    if release:merged "${dest}"
+    kind=$(release:kind "${src}" "${dest}")
+    if [[ "${kind}" == merge ]]
     then
       step "${dest}: merged by key"
       release:place "${src}" "${dest}" "${previous_src}"
-    elif [[ ! -f "${dest}" ]]
+    elif ! release:installed "${src}" "${dest}" >/dev/null 2>&1
     then
       step "${dest}: missing, written"
       release:place "${src}" "${dest}"
-    elif [[ "${recorded}" == "$(release:digest < "${dest}")" ]]
+    elif [[ "${recorded}" == "$(release:installed "${src}" "${dest}" | release:digest)" ]]
     then
       step "${dest}: unchanged since ${previous}, replaced"
       release:place "${src}" "${dest}"
+    elif [[ "${kind}" == region ]]
+    then
+      # The region's content is merged on its own and written back between the markers.
+      step "${dest}: the kit's region edited since ${previous}, three-way merged"
+      ours=$(mktemp)
+      release:installed "${src}" "${dest}" > "${ours}"
+      if ! git merge-file --marker-size 7 "${ours}" "${previous_src}" "${src}"
+      then
+        warn "${dest}: conflict markers are left in the kit's region; resolve them, then run: kit check"
+        conflicts=$(( conflicts + 1 ))
+      fi
+      release:region-write "${dest}" "$(release:region-module "${src}")" "${ours}"
+      rm -f "${ours}"
     else
       step "${dest}: edited since ${previous}, three-way merged"
       if ! git merge-file --marker-size 7 "${dest}" "${previous_src}" "${src}"
diff --git a/bin/release.sh b/bin/release.sh
index c61bbaa..28d815b 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -5,13 +5,15 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
-# mirrored at the base's root; and templates/<base>/, with @key@ rendered from the repository's answers, then
-# mirrored the same way. A repository defines modules of its own the same way under .kit/modules/<name>/, and
-# a name is looked up in the release first, then there. Two bases: repo, the repository root, recorded in
-# .kit/manifest; and home, the user's home directory, recorded in ~/.kit/manifest, which every repository on the
-# desk shares. A destination ending in .json is merged by key, the kit owning only the entries it writes. The
-# repository's choices live in .kit/settings.yml, which the kit reads and never writes. docs/modules.md is the
-# format's description.
+# mirrored at the base's root; templates/<base>/, with @key@ rendered from the repository's answers, then
+# mirrored the same way; and regions/<base>/, each file placed as a region the kit owns inside a file the
+# repository owns, between marker comments, so the rest of that file stays the repository's. A repository
+# defines modules of its own the same way under .kit/modules/<name>/, and a name is looked up in the release
+# first, then there. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's home
+# directory, recorded in ~/.kit/manifest, which every repository on the desk shares. A destination ending in
+# .json is merged by key, the kit owning only the entries it writes, and a region is held to the release between
+# its markers and nowhere else. The repository's choices live in .kit/settings.yml, which the kit reads and never
+# writes. docs/modules.md is the format's description.
 #
 # Every function reads a release from a root, kit_root by default, which bin/kit exports. bin/kit also moves to
 # the repository root, so .kit/manifest and every repo path here are relative to it. Every sort and comm here
@@ -288,7 +290,7 @@ release:render-all() {
   done
   for module in "$@"
   do
-    for kind in files templates
+    for kind in files templates regions
     do
       for base in $(cd "$(release:home "${root}" "${module}")/modules/${module}/${kind}" 2>/dev/null \
         && find . -mindepth 1 -maxdepth 1 -type d | sed 's@^\./@@')
@@ -314,20 +316,104 @@ release:render-all() {
 }
 
 # release:layers <root> <base> <module>… prints the directories mirrored at the base's root, in module order: each
-# module's files/<base>, then its rendered templates/<base>.
+# module's files/<base>, its rendered templates/<base>, and its regions/<base>.
 release:layers() {
-  local root=$1 base=$2 module rendered
+  local root=$1 base=$2 module home rendered
   shift 2
   for module in "$@"
   do
-    [[ -d "$(release:home "${root}" "${module}")/modules/${module}/files/${base}" ]] \
-      && printf '%s\n' "$(release:home "${root}" "${module}")/modules/${module}/files/${base}"
+    home=$(release:home "${root}" "${module}")
+    [[ -d "${home}/modules/${module}/files/${base}" ]] && printf '%s\n' "${home}/modules/${module}/files/${base}"
     rendered=$(release:render "${root}" "${module}" "${base}")
     [[ -n "${rendered}" ]] && printf '%s\n' "${rendered}"
+    [[ -d "${home}/modules/${module}/regions/${base}" ]] && printf '%s\n' "${home}/modules/${module}/regions/${base}"
   done
   return 0
 }
 
+# release:kind <source> <path> prints how the content is placed: merge for a .json destination, region for a
+# source under a module's regions/, copy otherwise.
+release:kind() {
+  if release:merged "$2"
+  then printf 'merge\n'
+  elif [[ "$1" == */modules/*/regions/* ]]
+  then printf 'region\n'
+  else printf 'copy\n'
+  fi
+}
+
+# release:region-module <source> prints the module a region source belongs to, which names its markers.
+release:region-module() {
+  local rest=${1#*/modules/}
+  printf '%s\n' "${rest%%/*}"
+}
+
+# release:region-markers <path> <module> prints the region's two marker lines, in the file's own comment
+# syntax: an HTML comment for markdown, a hash comment otherwise.
+release:region-markers() {
+  if [[ "$1" == *.md ]]
+  then printf '<!-- kit:begin %s -->\n<!-- kit:end %s -->\n' "$2" "$2"
+  else printf '# kit:begin %s\n# kit:end %s\n' "$2" "$2"
+  fi
+}
+
+# release:region-read <path> <module> prints the region's content, between its markers, and fails where the
+# file or the region is absent.
+release:region-read() {
+  local path=$1 begin end
+  [[ -f "${path}" ]] || return 1
+  { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
+  grep --quiet --line-regexp --fixed-strings "${begin}" "${path}" || return 1
+  awk -v b="${begin}" -v e="${end}" '$0 == e { on = 0 } on { print } $0 == b { on = 1 }' "${path}"
+}
+
+# release:region-write <path> <module> <content-file> replaces the region's content, appending the region after a
+# blank line where the file has none, and making the file where there is none.
+release:region-write() {
+  local path=$1 module=$2 content=$3 begin end
+  { read -r begin; read -r end; } < <(release:region-markers "${path}" "${module}")
+  mkdir -p "$(dirname "${path}")"
+  if [[ -f "${path}" ]] && grep --quiet --line-regexp --fixed-strings "${begin}" "${path}"
+  then
+    awk -v b="${begin}" -v e="${end}" -v c="${content}" '
+      $0 == b { print; while ((getline line < c) > 0) print line; skip = 1; next }
+      $0 == e { skip = 0 }
+      !skip { print }' "${path}" > "${path}.kit-new"
+  else
+    {
+      if [[ -s "${path}" ]]
+      then
+        cat "${path}"
+        [[ "$(tail -c 1 "${path}")" == "" ]] || printf '\n'
+        printf '\n'
+      fi
+      printf '%s\n' "${begin}"
+      cat "${content}"
+      printf '%s\n' "${end}"
+    } > "${path}.kit-new"
+  fi
+  mv "${path}.kit-new" "${path}"
+}
+
+# release:region-remove <path> <module> takes the region and its markers out, and the blank line before it;
+# a file left empty is removed.
+release:region-remove() {
+  local path=$1 begin end
+  [[ -f "${path}" ]] || return 0
+  { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
+  awk -v b="${begin}" -v e="${end}" '
+    $0 == b { skip = 1; held = 0; next }
+    $0 == e { skip = 0; next }
+    skip { next }
+    held { print ""; held = 0 }
+    $0 == "" { held = 1; next }
+    { print }' "${path}" > "${path}.kit-new"
+  if [[ -s "${path}.kit-new" ]]
+  then mv "${path}.kit-new" "${path}"
+  else rm -f "${path}.kit-new" "${path}"
+  fi
+}
+
 # release:delivered <root> <base> <module>… prints "<path>\t<source>" for every path under the base's root that
 # the release at <root> delivers for those modules, sorted by path, the last layer winning. A symlink is a source
 # only when it points at a file; a dangling one is refused here, where it is found.
@@ -478,31 +564,62 @@ release:digest() {
   fi
 }
 
-# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, else a
-# copy that keeps the source's mode.
+# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, the
+# region for a region source, else a copy that keeps the source's mode.
 release:place() {
   local src=$1 path=$2 base=${3:-/dev/null}
-  if release:merged "${path}"
-  then
-    release:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
-  else
-    mkdir -p "$(dirname "${path}")"
-    cp "${src}" "${path}.kit-new"
-    mv "${path}.kit-new" "${path}"
-  fi
+  case "$(release:kind "${src}" "${path}")" in
+    (merge)
+      release:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
+      ;;
+    (region)
+      release:region-write "${path}" "$(release:region-module "${src}")" "${src}"
+      ;;
+    (*)
+      mkdir -p "$(dirname "${path}")"
+      cp "${src}" "${path}.kit-new"
+      mv "${path}.kit-new" "${path}"
+  esac
+}
+
+# release:installed <source> <path> prints what the repository holds of the release's content at <path>: the
+# file, or the region's content; nothing, failing, where there is none.
+release:installed() {
+  local src=$1 path=$2
+  case "$(release:kind "${src}" "${path}")" in
+    (region) release:region-read "${path}" "$(release:region-module "${src}")" ;;
+    (*) [[ -f "${path}" ]] && cat "${path}" ;;
+  esac
+}
+
+# release:holds <source> <path> is true when the repository holds the release's content at <path>: the same
+# file, every merged entry, or the same region.
+release:holds() {
+  local src=$1 path=$2
+  case "$(release:kind "${src}" "${path}")" in
+    (merge) [[ -f "${path}" ]] && release:json-holds "${path}" "${src}" ;;
+    (*) cmp --silent "${src}" <(release:installed "${src}" "${path}") ;;
+  esac
 }
 
 # release:place-new <source> <path> [<label>] places content the repository did not record: where there is
-# nothing, or the same thing, or a .json to merge into. A different file is refused, named, and left as it is.
+# nothing, or the same thing, a .json to merge into, or a file to carry a region. A different file, or a region
+# with different content, is refused, named, and left as it is.
 release:place-new() {
-  local src=$1 path=$2 label=${3:-}
-  if release:merged "${path}" || [[ ! -f "${path}" ]]
+  local src=$1 path=$2 label=${3:-} kind
+  kind=$(release:kind "${src}" "${path}")
+  if [[ "${kind}" == merge || ! -f "${path}" ]] \
+    || { [[ "${kind}" == region ]] && ! release:installed "${src}" "${path}" >/dev/null; }
   then
     step "${path}${label:+: ${label}}"
     release:place "${src}" "${path}"
-  elif cmp --silent "${src}" "${path}"
+  elif release:holds "${src}" "${path}"
   then
     step "${path}${label:+: ${label}}, already as the release has it"
+  elif [[ "${kind}" == region ]]
+  then
+    error "${path}: the kit's region is there with different content; make it the release's, or remove it"
+    return 1
   else
     error "${path}: a different file is there already; move it aside, or remove it if it is not yours"
     return 1
@@ -523,18 +640,23 @@ release:place-all() {
 }
 
 # release:unplace <source> <path> takes the release's content back out of <path>: the kit's entries for .json,
-# the file itself otherwise.
+# the kit's region for a region, the file itself otherwise.
 release:unplace() {
   local src=$1 path=$2
-  if release:merged "${path}"
-  then
-    [[ -f "${path}" ]] || return 0
-    step "${path}: the kit's entries taken out"
-    release:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
-  else
-    step "removing ${path}"
-    rm -f "${path}"
-  fi
+  case "$(release:kind "${src}" "${path}")" in
+    (merge)
+      [[ -f "${path}" ]] || return 0
+      step "${path}: the kit's entries taken out"
+      release:json-write "${path}" 'unmerge(.; $base[0])' --slurpfile base "${src}"
+      ;;
+    (region)
+      step "${path}: the kit's region taken out"
+      release:region-remove "${path}" "$(release:region-module "${src}")"
+      ;;
+    (*)
+      step "removing ${path}"
+      rm -f "${path}"
+  esac
 }
 
 # release:retire <base-root> <base> <previous> <current> <module>… handles the paths the base's manifest records
@@ -558,10 +680,10 @@ release:retire() {
     [[ -n "${path}" ]] || continue
     dest=$(release:dest "${base}" "${path}")
     [[ -e "${dest}" ]] || continue
+    previous_src=""
+    [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "$@")
     if release:merged "${dest}"
     then
-      previous_src=""
-      [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "$@")
       if [[ -n "${previous_src}" ]]
       then
         step "${dest}: retired in ${current}, the previous release's entries taken out"
@@ -569,10 +691,11 @@ release:retire() {
       else
         warn "${dest}: retired in ${current}; without the base release its entries stay, and it is left as it was"
       fi
-    elif [[ "$(release:recorded "${base}" "${path}")" == "$(release:digest < "${dest}")" ]]
+    elif [[ "$(release:recorded "${base}" "${path}")" \
+      == "$(release:installed "${previous_src:-/dev/null}" "${dest}" | release:digest)" ]]
     then
       step "${dest}: retired in ${current}, removed"
-      rm -f "${dest}"
+      release:unplace "${previous_src:-/dev/null}" "${dest}"
     else
       warn "${dest}: retired in ${current}, but edited since ${previous}; it is left as it was"
     fi
diff --git a/docs/architecture.md b/docs/architecture.md
index bbda21e..f9e32a7 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -22,9 +22,10 @@ release and placed in no repository. Two bases exist: `repo`, the repository roo
 The verbs are the only way content moves. `kit install` resolves the active set, `kit` plus those named plus their
 dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
 an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
-fails when a delivered file differs from the release's. `kit module` changes the active set. Two rules govern
-placement: a `.json` destination is merged by key, the kit owning only the entries it writes; everything else is a
-copy.
+fails when a delivered file differs from the release's. `kit module` changes the active set. Three rules govern
+placement: a `.json` destination is merged by key, the kit owning only the entries it writes; a region is written
+between marker comments inside a file the repository owns, the kit holding only what is between them; everything
+else is a copy.
 
 Each base has a manifest: `.kit/manifest`, committed with the repository, and `~/.kit/manifest` on the desk when a
 module delivers there. A manifest records the version, the active modules, and the release's digest of every
diff --git a/docs/delivery.svg b/docs/delivery.svg
index 65f2511..3a122a0 100644
--- a/docs/delivery.svg
+++ b/docs/delivery.svg
@@ -41,7 +41,7 @@
   <text class="m" x="68" y="346">files/home/</text>
   <text class="d" x="180" y="346">mirrored at ~</text>
   <text class="m" x="68" y="370">templates/&lt;base&gt;/</text>
-  <text class="d" x="180" y="386">@key@ rendered first</text>
+  <text class="d" x="180" y="386">@key@ rendered; regions/ into a file</text>
   <text class="m" x="68" y="412">docs/</text>
   <text class="d" x="180" y="412">not delivered</text>
   <text class="d" x="52" y="446">kit, lefthook, ci are default;</text>
@@ -60,7 +60,7 @@
   <line x1="396" y1="286" x2="644" y2="286" stroke="#a78bfa" stroke-width="1"/>
   <text class="d" x="396" y="308">resolve the active set and its depends</text>
   <text class="d" x="396" y="326">render @key@ from .kit/settings.yml</text>
-  <text class="d" x="396" y="344">merge a .json destination by key</text>
+  <text class="d" x="396" y="344">merge a .json destination by key; write a region</text>
   <text class="d" x="396" y="362">copy everything else</text>
   <text class="d" x="396" y="380">digest each path into the manifest</text>
   <text class="d" x="396" y="398">three-way merge an edited file on update</text>
diff --git a/docs/modules.md b/docs/modules.md
index a024e95..287d05b 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -10,11 +10,12 @@ modules/<name>/
   module.yml          metadata
   files/<base>/       files mirrored at the base's root
   templates/<base>/   files rendered from the repository's answers, then mirrored the same way
+  regions/<base>/     each file a region the kit owns inside a file the repository owns
   docs/               the module's documentation; packed with the release, placed in no repository
 ```
 
-A module may have any of `files/`, `templates/`, and `docs/`, and must have `module.yml`. A base names where a
-file lands:
+A module may have any of `files/`, `templates/`, `regions/`, and `docs/`; `module.yml` it must have. A base names
+where a file lands:
 
 | Base | Root | Record |
 | --- | --- | --- |
@@ -59,6 +60,15 @@ merged by key: the kit's keys are set, its array entries added, and on update or
 release's entries are taken out, so a repository's own keys and entries survive. Every other destination is a copy.
 Where two active modules deliver the same path, the later module in dependency order wins.
 
+A file under `regions/<base>/` is placed as a region inside the file at the same path: its content between two
+marker comments naming the module, `<!-- kit:begin kit -->` and `<!-- kit:end kit -->` in markdown, `# kit:begin
+kit` and `# kit:end kit` elsewhere. Where the file has no region, one is appended after a blank line; where there
+is no file, it is made of the region alone. The repository may move the region anywhere in the file and write
+what it likes around it. `kit check` holds only the content between the markers to the release, `kit update`
+replaces or three-way merges only that, and removal takes the region out and leaves the rest, removing a file it
+leaves empty. The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to `.kit/1st.md`,
+and the `/worktrees/` entry in `.gitignore`.
+
 A file under `templates/<base>/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
 answer, then the result is placed, digested, and merged exactly as a `files/` file is. The form is one neither
 bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
@@ -106,7 +116,7 @@ base. A rule file it places under `.kit/rules/` is found by `kit context` like a
 
 | Module | Default | Depends on | Delivers |
 | --- | --- | --- | --- |
-| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md` |
+| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md`; regions in `AGENTS.md` and `.gitignore` |
 | `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` |
 | `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
 | `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
diff --git a/justfile b/justfile
index 5023b3d..9cfad7f 100644
--- a/justfile
+++ b/justfile
@@ -36,30 +36,26 @@ ci:
   bin/kit check
   echo "✅ ci passed"
 
-# Reinstall this repository's own kit from the index and stage the result. Here the checkout is the release, so an
-# edit under modules/ is an edit to the release, not a consumer's drift. The copies are made from the
-# index, what the commit will carry, never from the working tree, so a half-staged edit cannot put a copy into a
-# commit that lacks its source. Every path the old manifest lists is removed first and written again from the
-# new release: a source that was deleted leaves no copy behind, and an entry that was retired does not survive
-# in a merged .json. This repository keeps nothing of its own in a delivered path, which is what makes that
-# removal safe here. The pre-commit hook runs this on a commit that touches the source; by hand it is for a desk
-# without the hook.
+# Bring this repository's own installed copies up to the index and stage the result. Here the checkout is the
+# release, so an edit under modules/ is an edit to the release, not a consumer's drift. The copies are made from
+# the index, what the commit will carry, never from the working tree, so a half-staged edit cannot put a copy
+# into a commit that lacks its source. It is kit update at the same version: an untouched copy is replaced, a
+# retired one removed, a region rewritten between its markers with the rest of its file left alone. The
+# pre-commit hook runs this on a commit that touches the source; by hand it is for a desk without the hook.
 #
 #   just refresh
-[doc("🔁 Reinstall this repository's own kit from the index, and stage the result")]
+[doc("🔁 Bring this repository's own installed copies up to the index, and stage the result")]
 refresh:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  paths() { awk '$1 ~ /^[0-9a-f]{64}$/ { print $2 }' .kit/manifest; }
+  paths() { awk 'length($1) == 64 { print substr($0, 67) }' .kit/manifest; }
   readarray -t before < <(paths)
-  read -r -a modules <<<"$(sed -n 's/^modules *//p' .kit/manifest)"
   index=$(mktemp -d)
   trap 'rm -rf "${index}"' EXIT
   git checkout-index --all --prefix="${index}/"
-  rm -f "${before[@]}" .kit/manifest
-  "${index}/bin/kit" install "${modules[@]}" >/dev/null
+  "${index}/bin/kit" update >/dev/null
   readarray -t after < <(paths)
   git add --all -- "${before[@]}" "${after[@]}" .kit/manifest
-  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, modules ${modules[*]:-none}"
+  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, modules $(sed -n 's/^modules *//p' .kit/manifest)"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
index aff3499..3796cbc 100644
--- a/modules/kit/docs/README.md
+++ b/modules/kit/docs/README.md
@@ -4,7 +4,9 @@ The core, active in every repository that takes the kit. It places:
 
 - `.kit/1st.md`, the entry every agent reads, named by the repository's `AGENTS.md`.
 - `.kit/rules/<kind>.md`, one rule file per kind of file, each declaring in its frontmatter which paths and which
-  first lines it governs.
+  first lines it governs, and the linter `kit lint` runs over them.
+- A region in `AGENTS.md`, the sentence that sends every agent to `.kit/1st.md`, and a region in `.gitignore`,
+  the `/worktrees/` entry the loop needs; the rest of each file is the repository's.
 
 The rules are discovered through `kit context <path>`, described in [docs/context.md](../../../docs/context.md),
 and copied into no harness's directory. Adding a kind is adding one rule file here and one row to the table in
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 5aa4900..7252681 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -97,7 +97,8 @@ delivers is a module, and a repository activates the modules it takes: `kit inst
 lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
 only the entries it writes; everything else is copied as it is.
 
-- `kit`: this file and the rules, discovered through `kit context`.
+- `kit`: this file and the rules, discovered through `kit context`; the sentence in `AGENTS.md` that points here
+  and the `/worktrees/` entry in `.gitignore`, each a region the kit owns inside a file the repository owns.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/modules/kit/regions/repo/.gitignore b/modules/kit/regions/repo/.gitignore
new file mode 100644
index 0000000..195dd81
--- /dev/null
+++ b/modules/kit/regions/repo/.gitignore
@@ -0,0 +1,2 @@
+# per-issue worktrees for agents; see: .kit/1st.md
+/worktrees/
diff --git a/modules/kit/regions/repo/AGENTS.md b/modules/kit/regions/repo/AGENTS.md
new file mode 100644
index 0000000..a961ab1
--- /dev/null
+++ b/modules/kit/regions/repo/AGENTS.md
@@ -0,0 +1,2 @@
+Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
+repository trustworthy.
diff --git a/tests/kit.bats b/tests/kit.bats
index e4574be..379e8c7 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -224,6 +224,50 @@ later-release() {
   [[ "$output" == *".kit/modules/odd/module.yml has a key the kit does not know: dependz"* ]]
 }
 
+@test "a region is placed inside the repository's own file, held to the release, and taken out whole" {
+  printf '# Ours\n\nOur own instructions.\n' > AGENTS.md
+  printf 'build/\n' > .gitignore
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ "$(sed -n '1,3p' AGENTS.md | paste -s -d '|' -)" = "# Ours||Our own instructions." ]
+  grep --quiet --line-regexp '<!-- kit:begin kit -->' AGENTS.md
+  grep --quiet 'Read .kit/1st.md at the start of every session' AGENTS.md
+  [ "$(sed -n '1p' .gitignore)" = "build/" ]
+  grep --quiet --line-regexp '/worktrees/' .gitignore
+  grep --quiet '  AGENTS.md$' .kit/manifest
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  printf '## More of ours\n' >> AGENTS.md
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  sed -i.bak 's/^Read .kit\/1st.md/Skip .kit\/1st.md/' AGENTS.md && rm AGENTS.md.bak
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"AGENTS.md: the kit's region differs from the pinned release"* ]]
+  # at the same version the release is its own base, so the edit inside the region is kept
+  run env PATH="$(shims mise curl)" "${kit_checkout}/bin/kit" update
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"AGENTS.md: the kit's region edited"* ]]
+  grep --quiet 'Skip .kit/1st.md' AGENTS.md
+  run "${kit_checkout}/bin/kit" module remove kit
+  [ "$status" -eq 0 ]
+  [ "$(cat AGENTS.md | paste -s -d '|' -)" = "# Ours||Our own instructions.|## More of ours" ]
+  [ "$(cat .gitignore)" = "build/" ]
+}
+
+@test "a region makes the file where there is none, and refuses one holding a different region" {
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ "$(sed -n '1p' AGENTS.md)" = "<!-- kit:begin kit -->" ]
+  run "${kit_checkout}/bin/kit" module remove kit
+  [ ! -e AGENTS.md ]
+  [ ! -e .gitignore ]
+  printf '<!-- kit:begin kit -->\nsomething else\n<!-- kit:end kit -->\n' > AGENTS.md
+  run "${kit_checkout}/bin/kit" module add kit
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"AGENTS.md: the kit's region is there with different content"* ]]
+}
+
 @test "install keeps the repository's own settings keys and deny entries" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json

From 5fcc7564b9dc6e52b32c79a927b92515deb7aa79 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 23:47:49 -0700
Subject: [PATCH 080/108] #5 a schema for .kit/settings.yml, delivered beside
 it and held to before every verb

.kit/settings.schema.json, JSON Schema 2020-12, is delivered by the kit module so an editor validates
the file through a modeline. The gate validates this repository's settings with ajv, and every verb
holds the file to the schema's main points first: an unknown key, a require_signing that is not
true or false, or an answer key a template could not name is refused. 64 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/manifest                                 |  1 +
 .kit/settings.schema.json                     | 36 +++++++++++++++++++
 .kit/settings.yml                             |  1 +
 README.md                                     |  2 +-
 bin/release.sh                                | 32 +++++++++++++++++
 docs/modules.md                               |  8 +++--
 justfile                                      |  8 ++---
 .../kit/files/repo/.kit/settings.schema.json  | 34 ++++++++++++++++++
 tests/kit.bats                                | 15 ++++++++
 9 files changed, 130 insertions(+), 7 deletions(-)
 create mode 100644 .kit/settings.schema.json
 create mode 100644 modules/kit/files/repo/.kit/settings.schema.json

diff --git a/.kit/manifest b/.kit/manifest
index 10ba8dd..bffaa35 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -14,4 +14,5 @@ bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bas
 a809a1969212d3d21dfafb903d0d2fd04c97ce45a057e896fcc7dcf555c18689  .kit/rules/markdown.md
 2f0cfeca313280bf984aaad927cd459ecf61f93861a11ccc839b7d5b8406cbac  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
+61c7dd26e9cd18e975cc0844dc6a690f1832f87d45ff2ccb37a4173f966834df  .kit/settings.schema.json
 dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
new file mode 100644
index 0000000..cae7b42
--- /dev/null
+++ b/.kit/settings.schema.json
@@ -0,0 +1,36 @@
+{
+  "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "properties": {
+    "answers": {
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z_]+$": {
+          "description": "The value a module's template takes for this key, written @key@ in the template.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "forge": {
+      "description": "The provider the loop's verbs use. Detected from origin's host when absent.",
+      "enum": [
+        "github"
+      ],
+      "type": "string"
+    },
+    "gate": {
+      "description": "What kit gate runs. A justfile ci recipe, a Makefile ci target, or a package.json ci script is detected when absent.",
+      "minLength": 1,
+      "type": "string"
+    },
+    "require_signing": {
+      "description": "true makes kit issue refuse a desk without a signing key.",
+      "type": "boolean"
+    }
+  },
+  "title": ".kit/settings.yml",
+  "type": "object"
+}
diff --git a/.kit/settings.yml b/.kit/settings.yml
index 5495dd2..47a39fd 100644
--- a/.kit/settings.yml
+++ b/.kit/settings.yml
@@ -1 +1,2 @@
+# yaml-language-server: $schema=settings.schema.json
 require_signing: true
diff --git a/README.md b/README.md
index 51c95ac..e9ceb9a 100644
--- a/README.md
+++ b/README.md
@@ -141,7 +141,7 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 
 | Installed copy | Written from |
 | --- | --- |
-| `.kit/1st.md`, `.kit/rules/` | `modules/kit/files/repo/.kit/` |
+| `.kit/1st.md`, `.kit/rules/`, `.kit/settings.schema.json` | `modules/kit/files/repo/.kit/` |
 | `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
 | `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
 | `.claude/CLAUDE.md` | `modules/claude/files/repo/.claude/CLAUDE.md` |
diff --git a/bin/release.sh b/bin/release.sh
index 28d815b..20ed5db 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -221,6 +221,37 @@ release:validate() {
   done
 }
 
+# release:validate-settings refuses a settings file the schema would refuse, as far as bash can tell: a key the
+# kit does not know, a require_signing that is not true or false, an answer key outside [a-z_]. The gate
+# validates this repository's against .kit/settings.schema.json in full; the schema is delivered so an editor
+# can do the same anywhere.
+release:validate-settings() {
+  local settings key value
+  settings=$(release:settings)
+  [[ -f "${settings}" ]] || return 0
+  for key in $(yaml:keys "${settings}")
+  do
+    case "${key}" in
+      (forge | gate | require_signing | answers) ;;
+      (*)
+        error "${settings} has a key the kit does not know: ${key} (see .kit/settings.schema.json)"
+        return 1
+    esac
+  done
+  value=$(yaml:value "${settings}" require_signing)
+  if [[ -n "${value}" && "${value}" != true && "${value}" != false ]]
+  then
+    error "${settings}: require_signing must be true or false, not '${value}'"
+    return 1
+  fi
+  while IFS=$'\t' read -r key value
+  do
+    [[ -z "${key}" || "${key}" =~ ^[a-z_]+$ ]] && continue
+    error "${settings}: the answer key '${key}' is not letters and underscores, as a template's @key@ must be"
+    return 1
+  done < <(yaml:map "${settings}" answers)
+}
+
 # release:answers <root> <module> prints "<key>\t<value>" for every answer the module's templates may use: the
 # module's defaults under its answers:, each overridden by the repository's, under answers: in .kit/settings.yml.
 release:answers() {
@@ -283,6 +314,7 @@ release:render() {
 release:render-all() {
   local root=$1 module kind base
   shift
+  release:validate-settings || return 1
   release:require-modules "${root}" "$@" || return 2
   for module in $(release:modules "${root}")
   do
diff --git a/docs/modules.md b/docs/modules.md
index 287d05b..12f171e 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -80,7 +80,11 @@ The same YAML subset is what a rule's frontmatter is written in, read by `bin/ya
 
 ## Settings
 
-`.kit/settings.yml` is the repository's, read by the kit and never written by it, in the same YAML subset:
+`.kit/settings.yml` is the repository's, read by the kit and never written by it, in the same YAML subset.
+[settings.schema.json](../modules/kit/files/repo/.kit/settings.schema.json) is its schema, delivered beside it as
+`.kit/settings.schema.json`, so an editor validates the file through the modeline
+`# yaml-language-server: $schema=settings.schema.json`; the kit holds the file to the schema's main points before
+every install, update, and check, naming an unknown key.
 
 ```yaml
 answers:
@@ -116,7 +120,7 @@ base. A rule file it places under `.kit/rules/` is found by `kit context` like a
 
 | Module | Default | Depends on | Delivers |
 | --- | --- | --- | --- |
-| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md`; regions in `AGENTS.md` and `.gitignore` |
+| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md`, `.kit/settings.schema.json`; regions in `AGENTS.md` and `.gitignore` |
 | `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` |
 | `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
 | `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
diff --git a/justfile b/justfile
index 9cfad7f..3bb2956 100644
--- a/justfile
+++ b/justfile
@@ -20,18 +20,18 @@ _: help
 
 set export := true
 
-# The gate: kit lint over every tracked path, each rule's own linter, every module.yml against
-# modules/module.schema.json, the bats suite, and bin/kit check over this repository's installed copy of its own
-# kit. The runner runs it on every pull request, and a desk runs it the
+# The gate: kit lint over every tracked path, each rule's own linter, every module.yml and .kit/settings.yml
+# against their schemas, the bats suite, and bin/kit check over this repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
 # same way; the pre-commit hook is the narrower, faster check over the staged paths.
 #
 #   just ci
-[doc("🚦 The gate: kit lint, the module schema, bats, kit check")]
+[doc("🚦 The gate: kit lint, the schemas, bats, kit check")]
 ci:
   #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
   mise exec -- bin/kit lint --all-files
   mise exec -- ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
+  mise exec -- ajv validate --spec=draft2020 -s .kit/settings.schema.json -d .kit/settings.yml
   mise exec -- bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
diff --git a/modules/kit/files/repo/.kit/settings.schema.json b/modules/kit/files/repo/.kit/settings.schema.json
new file mode 100644
index 0000000..84689ee
--- /dev/null
+++ b/modules/kit/files/repo/.kit/settings.schema.json
@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
+  "title": ".kit/settings.yml",
+  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "forge": {
+      "type": "string",
+      "enum": ["github"],
+      "description": "The provider the loop's verbs use. Detected from origin's host when absent."
+    },
+    "gate": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What kit gate runs. A justfile ci recipe, a Makefile ci target, or a package.json ci script is detected when absent."
+    },
+    "require_signing": {
+      "type": "boolean",
+      "description": "true makes kit issue refuse a desk without a signing key."
+    },
+    "answers": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z_]+$": {
+          "type": "string",
+          "description": "The value a module's template takes for this key, written @key@ in the template."
+        }
+      }
+    }
+  }
+}
diff --git a/tests/kit.bats b/tests/kit.bats
index 379e8c7..2c689f0 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -217,6 +217,21 @@ later-release() {
   [ -f .kit/modules/python/module.yml ]
 }
 
+@test "the settings file is held to its schema: an unknown key and a non-boolean require_signing are refused" {
+  mkdir .kit && printf 'forgery: github\n' > .kit/settings.yml
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/settings.yml has a key the kit does not know: forgery (see .kit/settings.schema.json)"* ]]
+  printf 'require_signing: yes\n' > .kit/settings.yml
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"require_signing must be true or false"* ]]
+  printf 'require_signing: false\nanswers:\n  ci_runner: x\n' > .kit/settings.yml
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ -f .kit/settings.schema.json ]
+}
+
 @test "a module the repository defines is validated like a delivered one" {
   mkdir -p .kit/modules/odd && printf 'description: "x"\ndependz:\n  - kit\n' > .kit/modules/odd/module.yml
   run "${kit_checkout}/bin/kit" install

From 9fe24800af7b9a77f4e4d42e8b10b031afc16fd5 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Sun, 25 Oct 2026 23:54:45 -0700
Subject: [PATCH 081/108] #5 .claude/CLAUDE.md is a region, and a schema is a
 copy

The claude module owns only the @../AGENTS.md import, between markers; the rest of the file is the
repository's, so a repository's own Claude instructions never fail kit check. The merge-by-key rule
is for settings files: a *.schema.json is a copy. 64 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/CLAUDE.md                             |  3 +-
 .kit/1st.md                                   |  7 +--
 .kit/manifest                                 |  4 +-
 .kit/settings.schema.json                     | 46 +++++++++----------
 README.md                                     | 12 ++---
 bin/release.sh                                |  5 +-
 docs/modules.md                               | 10 ++--
 modules/claude/docs/README.md                 |  5 +-
 modules/claude/files/repo/.claude/CLAUDE.md   |  2 -
 modules/claude/regions/repo/.claude/CLAUDE.md |  1 +
 modules/kit/files/repo/.kit/1st.md            |  7 +--
 tests/kit.bats                                | 16 ++++---
 12 files changed, 62 insertions(+), 56 deletions(-)
 delete mode 100644 modules/claude/files/repo/.claude/CLAUDE.md
 create mode 100644 modules/claude/regions/repo/.claude/CLAUDE.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 819bb57..bec3c22 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,2 +1,3 @@
-<!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
+<!-- kit:begin claude -->
 @../AGENTS.md
+<!-- kit:end claude -->
diff --git a/.kit/1st.md b/.kit/1st.md
index 7252681..7ba6b5f 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -105,9 +105,10 @@ only the entries it writes; everything else is copied as it is.
 - `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
   `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
   anywhere.
-- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
-  importing `AGENTS.md`, so it is read in every case; the deny list above merged into `.claude/settings.json`; and
-  a hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
+- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: a region in
+  `.claude/CLAUDE.md` importing `AGENTS.md`, so it is read in every case; the deny list above merged into
+  `.claude/settings.json`; and a hook that runs `kit context` before every write so the rules are named to the agent
+  without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/.kit/manifest b/.kit/manifest
index bffaa35..51b461c 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -1,11 +1,11 @@
 # .kit/manifest - written by kit, not by hand
 version unreleased
 modules kit ci-github claude lefthook
-930488befed8ab56355d33f55032b5e7bc6d57a1c0ee867b51d9495cdec9f3cd  .claude/CLAUDE.md
+7b50d15feae7b63b94d845b2fa6e19e3220527c5b0cac69303b7fc19bd7484a8  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
 24b66b6015ccf244245373009b35fc9610c52dc16d88ab6c842f21d116c74f02  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
-2771b22ceee05bf708961013276bd5c760fd4101b8892b546e0109ad1d2b7b3f  .kit/1st.md
+9f837e32f290c2e7b020ba2b35c2d73b2a368eb04db86db1024a744da024acad  .kit/1st.md
 f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
 17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
index cae7b42..84689ee 100644
--- a/.kit/settings.schema.json
+++ b/.kit/settings.schema.json
@@ -1,36 +1,34 @@
 {
-  "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "additionalProperties": false,
+  "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
+  "title": ".kit/settings.yml",
   "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "type": "object",
+  "additionalProperties": false,
   "properties": {
-    "answers": {
-      "additionalProperties": false,
-      "patternProperties": {
-        "^[a-z_]+$": {
-          "description": "The value a module's template takes for this key, written @key@ in the template.",
-          "type": "string"
-        }
-      },
-      "type": "object"
-    },
     "forge": {
-      "description": "The provider the loop's verbs use. Detected from origin's host when absent.",
-      "enum": [
-        "github"
-      ],
-      "type": "string"
+      "type": "string",
+      "enum": ["github"],
+      "description": "The provider the loop's verbs use. Detected from origin's host when absent."
     },
     "gate": {
-      "description": "What kit gate runs. A justfile ci recipe, a Makefile ci target, or a package.json ci script is detected when absent.",
+      "type": "string",
       "minLength": 1,
-      "type": "string"
+      "description": "What kit gate runs. A justfile ci recipe, a Makefile ci target, or a package.json ci script is detected when absent."
     },
     "require_signing": {
-      "description": "true makes kit issue refuse a desk without a signing key.",
-      "type": "boolean"
+      "type": "boolean",
+      "description": "true makes kit issue refuse a desk without a signing key."
+    },
+    "answers": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z_]+$": {
+          "type": "string",
+          "description": "The value a module's template takes for this key, written @key@ in the template."
+        }
+      }
     }
-  },
-  "title": ".kit/settings.yml",
-  "type": "object"
+  }
 }
diff --git a/README.md b/README.md
index e9ceb9a..0327317 100644
--- a/README.md
+++ b/README.md
@@ -79,11 +79,11 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
   manager at all, and the `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
   in `lefthook.yml`, and run `lefthook install` once per clone.
 
-`claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is
-present. The module places `.claude/CLAUDE.md` importing `AGENTS.md`, so Claude reads what every agent reads in
-every case. A repository with no adapter still binds every agent that reads `AGENTS.md`. `kit module list`,
-`kit module add`, and `kit module remove` show and change the set, and [docs/modules.md](docs/modules.md)
-describes a module.
+`claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is present.
+The module places a region in `.claude/CLAUDE.md` importing `AGENTS.md`, so Claude reads what every agent reads in
+every case, and the rest of that file is yours. A repository with no adapter still binds every agent that reads
+`AGENTS.md`. `kit module list`, `kit module add`, and `kit module remove` show and change the set, and
+[docs/modules.md](docs/modules.md) describes a module.
 
 Before an agent creates or changes a file, it asks `kit context "${path}"` which rules govern it;
 [docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
@@ -144,7 +144,7 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.kit/1st.md`, `.kit/rules/`, `.kit/settings.schema.json` | `modules/kit/files/repo/.kit/` |
 | `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
 | `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
-| `.claude/CLAUDE.md` | `modules/claude/files/repo/.claude/CLAUDE.md` |
+| `.claude/CLAUDE.md` | `modules/claude/regions/repo/.claude/CLAUDE.md`, a region; the rest of the file is the repository's |
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
diff --git a/bin/release.sh b/bin/release.sh
index 20ed5db..2aa7c3b 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -485,8 +485,9 @@ release:paths-beyond() {
     <(release:delivered "${root}" "${base}" "${after[@]}" | cut -f 1)
 }
 
-# release:merged <path> is true for a destination that is merged by key rather than copied: a .json file.
-release:merged() { [[ "$1" == *.json ]]; }
+# release:merged <path> is true for a destination that is merged by key rather than copied: a .json file that is
+# a settings file, which every .json is here except a schema, *.schema.json.
+release:merged() { [[ "$1" == *.json && "$1" != *.schema.json ]]; }
 
 # release:fetch <version> prints the root of that release, fetching it if need be: the kit's cache first, then a
 # mise install if mise is here, then the release's public tarball with curl, unpacked into the cache. The version
diff --git a/docs/modules.md b/docs/modules.md
index 12f171e..047f3f2 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -55,10 +55,10 @@ naming it.
 
 ## Delivery
 
-A file under `files/<base>/` is placed at the same path under the base's root. A destination ending in `.json` is
-merged by key: the kit's keys are set, its array entries added, and on update or removal only the previous
-release's entries are taken out, so a repository's own keys and entries survive. Every other destination is a copy.
-Where two active modules deliver the same path, the later module in dependency order wins.
+A file under `files/<base>/` is placed at the same path under the base's root. A destination ending in `.json`, other
+than a schema, `*.schema.json`, is merged by key: the kit's keys are set, its array entries added, and on update or
+removal only the previous release's entries are taken out, so a repository's own keys and entries survive. Every other
+destination is a copy. Where two active modules deliver the same path, the later module in dependency order wins.
 
 A file under `regions/<base>/` is placed as a region inside the file at the same path: its content between two
 marker comments naming the module, `<!-- kit:begin kit -->` and `<!-- kit:end kit -->` in markdown, `# kit:begin
@@ -123,6 +123,6 @@ base. A rule file it places under `.kit/rules/` is found by `kit context` like a
 | `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md`, `.kit/settings.schema.json`; regions in `AGENTS.md` and `.gitignore` |
 | `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` |
 | `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
-| `claude` | no | `kit` | `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
+| `claude` | no | `kit` | a region in `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
 
 No module in this release delivers to `home`. Each module's `docs/README.md` says what it places and why.
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index 9adf47f..78fd4ee 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -3,8 +3,9 @@
 The adapter for Claude Code. Claude Code reads `AGENTS.md` only as a fallback: when no `CLAUDE.md`,
 `.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and where its
 configuration allows. A repository with a `CLAUDE.md` of its own would have `AGENTS.md` skipped. So the module
-places `.claude/CLAUDE.md`, two lines, the second `@../AGENTS.md`: Claude then reads what every other agent reads
-in every case, and a root `CLAUDE.md` of the repository's own stays its own. It also merges into
+places a region in `.claude/CLAUDE.md` holding `@../AGENTS.md`: Claude then reads what every other agent reads in
+every case, the rest of that file and a root `CLAUDE.md` are the repository's own, and `kit check` holds only
+the region. It also merges into
 `.claude/settings.json`, by key, leaving the repository's own entries:
 
 - `permissions.deny`: the spellings `.kit/1st.md` forbids an agent, `git rebase`, `git worktree add`,
diff --git a/modules/claude/files/repo/.claude/CLAUDE.md b/modules/claude/files/repo/.claude/CLAUDE.md
deleted file mode 100644
index 819bb57..0000000
--- a/modules/claude/files/repo/.claude/CLAUDE.md
+++ /dev/null
@@ -1,2 +0,0 @@
-<!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
-@../AGENTS.md
diff --git a/modules/claude/regions/repo/.claude/CLAUDE.md b/modules/claude/regions/repo/.claude/CLAUDE.md
new file mode 100644
index 0000000..dba71e9
--- /dev/null
+++ b/modules/claude/regions/repo/.claude/CLAUDE.md
@@ -0,0 +1 @@
+@../AGENTS.md
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 7252681..7ba6b5f 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -105,9 +105,10 @@ only the entries it writes; everything else is copied as it is.
 - `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
   `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
   anywhere.
-- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: `.claude/CLAUDE.md`
-  importing `AGENTS.md`, so it is read in every case; the deny list above merged into `.claude/settings.json`; and
-  a hook that runs `kit context` before every write so the rules are named to the agent without being asked for.
+- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: a region in
+  `.claude/CLAUDE.md` importing `AGENTS.md`, so it is read in every case; the deny list above merged into
+  `.claude/settings.json`; and a hook that runs `kit context` before every write so the rules are named to the agent
+  without being asked for.
 
 `kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
 new release and running `kit update`, never by editing them in place.
diff --git a/tests/kit.bats b/tests/kit.bats
index 2c689f0..11ba72f 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -67,7 +67,8 @@ later-release() {
   grep --quiet '^modules kit claude$' .kit/manifest
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
-  [ "$(tail -n 1 .claude/CLAUDE.md)" = "@../AGENTS.md" ]
+  grep --quiet --line-regexp '@../AGENTS.md' .claude/CLAUDE.md
+  grep --quiet --line-regexp '<!-- kit:begin claude -->' .claude/CLAUDE.md
   [ ! -e .claude/rules ]
 }
 
@@ -435,14 +436,17 @@ later-release() {
   [ "$(cat .kit/1st.md)" = "mine" ]
   rm .kit/1st.md
   "${kit_checkout}/bin/kit" install
-  mkdir .claude && printf 'theirs\n' > .claude/CLAUDE.md
-  run "${kit_checkout}/bin/kit" module add claude
+  printf 'theirs\n' > .kit/lefthook.yml
+  run "${kit_checkout}/bin/kit" module add lefthook
   [ "$status" -eq 1 ]
-  [[ "$output" == *".claude/CLAUDE.md: a different file is there already"* ]]
+  [[ "$output" == *".kit/lefthook.yml: a different file is there already"* ]]
   grep --quiet '^modules kit$' .kit/manifest
-  cp "${kit_checkout}/modules/claude/files/repo/.claude/CLAUDE.md" .claude/CLAUDE.md
-  run "${kit_checkout}/bin/kit" module add claude
+  rm .kit/lefthook.yml
+  mkdir .claude && printf '# Ours\n' > .claude/CLAUDE.md
+  run "${kit_checkout}/bin/kit" module add claude lefthook
   [ "$status" -eq 0 ]
+  [ "$(sed -n '1p' .claude/CLAUDE.md)" = "# Ours" ]
+  grep --quiet --line-regexp '@../AGENTS.md' .claude/CLAUDE.md
 }
 
 @test "module remove judges dependents against what stays, in any order" {

From 691aeb6d63213a5cc898d403b8959e9e116a3613 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Mon, 26 Oct 2026 00:00:39 -0700
Subject: [PATCH 082/108] #5 kit release: verify, pack, publish, and retire as
 verbs, and the two workflows as one-liners

The release workflow is two steps, kit release verify and kit release publish; the retirement
workflow is one, kit release retire, which reads the deleted branch from the runner's event. A desk
runs the same: pack makes the tarball and its checksum anywhere. 65 bats cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml             |  73 ++----------
 .github/workflows/retire-pre-releases.yml |  38 +------
 README.md                                 |   9 +-
 bin/kit                                   |   2 +
 bin/kit-release.sh                        | 133 ++++++++++++++++++++++
 tests/release.bats                        |  37 ++++--
 6 files changed, 185 insertions(+), 107 deletions(-)
 create mode 100755 bin/kit-release.sh

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f7f4101..58d7e9f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,16 +1,13 @@
 # release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The tarball is kit-<version>.tar.gz, holding one directory kit-<version>/ with bin/, modules/, and a stamped
-# version, the layout a consumer's mise unpacks and puts on PATH. Only a version tag starts a run. A
-# release, v<major>.<minor>.<patch>, is tagged on main, any commit on main and not only its head. A pre-release,
-# the same with a -<suffix>, is tagged on a commit that is not on main and is published as a GitHub pre-release.
-# The tag is the version: the repository carries no version file, and the one in the packed kit is stamped here
-# from the tag, so a consumer sees it in kit version and .kit/manifest, and kit update can name the previous
-# release to mise. A published release is immutable, so a tag is never reused. A pre-release lives as long as
-# the branch it was tagged on; see: .github/workflows/retire-pre-releases.yml
+# Two steps, each one kit command, so a desk can run the same: `kit release verify` holds the tag to its shape and
+# its side of main, and `kit release publish` packs this checkout as kit-<version>.tar.gz with the tag's version
+# stamped in and publishes it, as a pre-release where the version has a suffix. Only a version tag starts a run.
+# A published release is immutable, so a tag is never reused; a pre-release lives as long as the branch it was
+# tagged on. see: .github/workflows/retire-pre-releases.yml
 #
-# see: .kit/1st.md
+# see: bin/kit-release.sh
 
 name: release
 
@@ -29,62 +26,12 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: tag-is-a-version
-        run: |
-          set -o errexit -o nounset -o pipefail
-          tag_version=${GITHUB_REF_NAME#v}
-          refuse() {
-            echo "::error::$1"
-            printf '### ❌ %s\n' "$1" | tee --append "${GITHUB_STEP_SUMMARY}"
-            exit 1
-          }
-          if [[ ! "${tag_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
-          then
-            refuse "${GITHUB_REF_NAME} is not a version tag: v<major>.<minor>.<patch>, -<suffix> for a pre-release"
-          fi
-          echo "✅ ${GITHUB_REF_NAME} is a version tag."
+      - name: verify
+        run: bin/kit release verify "${GITHUB_REF_NAME}"
 
-      - name: tag-is-on-the-right-side-of-main
-        run: |
-          set -o errexit -o nounset -o pipefail
-          tag_version=${GITHUB_REF_NAME#v}
-          default_branch=$(jq --raw-output '.repository.default_branch' "${GITHUB_EVENT_PATH}")
-          on_main=false
-          git merge-base --is-ancestor "${GITHUB_SHA}" "origin/${default_branch}" && on_main=true
-          refuse() {
-            echo "::error::$1"
-            printf '### ❌ %s\n' "$1" | tee --append "${GITHUB_STEP_SUMMARY}"
-            exit 1
-          }
-          if [[ "${tag_version}" == *-* && "${on_main}" == true ]]
-          then
-            refuse "${GITHUB_REF_NAME} is a pre-release tag on ${default_branch}; tag a pre-release on a branch commit"
-          fi
-          if [[ "${tag_version}" != *-* && "${on_main}" == false ]]
-          then
-            refuse "${GITHUB_REF_NAME} is not on ${default_branch}; a release is tagged there, a pre-release has a suffix"
-          fi
-          echo "✅ ${GITHUB_REF_NAME} is on the right side of ${default_branch} (on it: ${on_main})."
-
-      - name: pack-and-release
+      - name: publish
         env:
           GH_TOKEN: ${{ github.token }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-          version=${GITHUB_REF_NAME#v}
-          staging=$(mktemp --directory)
-          mkdir "${staging}/kit-${version}"
-          cp --recursive --no-dereference bin modules "${staging}/kit-${version}/"
-          # the packed kit's version is the tag's, suffix included
-          printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
-          tar --create --gzip --file "kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
-          sha256sum "kit-${version}.tar.gz" > "kit-${version}.tar.gz.sha256"
-          notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\n' "${version}"
-            printf 'Then, in the repository: kit install\n')
-          flags=()
-          [[ "${version}" == *-* ]] && flags+=(--prerelease)
-          gh release create "${GITHUB_REF_NAME}" "kit-${version}.tar.gz" "kit-${version}.tar.gz.sha256" \
-            --title "kit ${version}" --notes "${notes}" "${flags[@]}"
-          printf '✅ Released kit %s.\n' "${version}" | tee --append "${GITHUB_STEP_SUMMARY}"
+        run: bin/kit release publish "${GITHUB_REF_NAME}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
index e512c1b..a8d8214 100644
--- a/.github/workflows/retire-pre-releases.yml
+++ b/.github/workflows/retire-pre-releases.yml
@@ -1,13 +1,11 @@
 # retire-pre-releases.yml - a pre-release lives as long as the branch it was tagged on
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A pre-release is tagged on a commit that is not on main, and main takes a branch by squash, so once the branch is
-# deleted its commits are reachable from nothing but the pre-release's own tag. This runs on every branch deletion
-# and retires, tag and all, each pre-release whose commit no remaining branch reaches. A release is never touched:
-# it is on main, which is never deleted. A deleted tag is a delete event too, and that one is ignored here. An
-# immutable release deletes with its tag, and its tag name can never be reused.
+# One step, one kit command: on every branch deletion, `kit release retire` deletes, tag and all, each pre-release
+# whose commit no remaining branch reaches. A release is never touched: it is on main, which is never deleted. A
+# deleted tag is a delete event too, and that one is ignored here.
 #
-# see: .github/workflows/release.yml
+# see: bin/kit-release.sh, .github/workflows/release.yml
 
 name: retire-pre-releases
 
@@ -26,33 +24,9 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: retire-unreachable-pre-releases
+      - name: retire
         env:
           GH_TOKEN: ${{ github.token }}
-        run: |
-          set -o errexit -o nounset -o pipefail
-          git fetch --quiet --tags origin
-          deleted=$(jq --raw-output '.ref' "${GITHUB_EVENT_PATH}")
-          retired=0
-          while IFS= read -r tag
-          do
-            [[ -n "${tag}" ]] || continue
-            commit=$(git rev-parse --verify --quiet "${tag}^{commit}" || true)
-            if [[ -z "${commit}" ]]
-            then
-              echo "::warning::${tag} has no commit here; leaving it"
-              continue
-            fi
-            if git branch --remotes --contains "${commit}" | grep --quiet --invert-match 'origin/HEAD'
-            then
-              echo "keeping ${tag}: a branch still reaches ${commit:0:7}"
-              continue
-            fi
-            gh release delete "${tag}" --cleanup-tag --yes
-            echo "retired ${tag}: no branch reaches ${commit:0:7} since ${deleted} was deleted"
-            retired=$(( retired + 1 ))
-          done < <(gh release list --limit 1000 --json tagName,isPrerelease \
-            --jq '.[] | select(.isPrerelease) | .tagName')
-          printf '✅ Retired %s pre-release(s).\n' "${retired}" | tee --append "${GITHUB_STEP_SUMMARY}"
+        run: bin/kit release retire
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/README.md b/README.md
index 0327317..7c1a395 100644
--- a/README.md
+++ b/README.md
@@ -161,10 +161,11 @@ copy that does not match its source. Each delivered text file says in its header
 A release is the tag `v<version>` on a commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`,
 say `v0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a GitHub pre-release. The tag is the
 version: the repository carries no version file, the workflow stamps the tag's version into the packed kit, and a
-published release is immutable, so a tag is never reused. The workflow packs `bin/`, `modules/`, and `version` into
-`kit-<version>.tar.gz` and publishes the release; it refuses a tag that is not a version, a release tag off
-`main`, and a pre-release tag on `main`. A release is permanent. A pre-release is retired, tag and all, when the
-branch it was tagged on is deleted and no other branch reaches its commit.
+published release is immutable, so a tag is never reused. The workflow is two kit commands: `kit release verify`,
+which refuses a tag that is not a version, a release tag off `main`, and a pre-release tag on `main`; and `kit release
+publish`, which packs `bin/`, `modules/`, and `version` into `kit-<version>.tar.gz` and publishes the release. `kit
+release pack` makes the same tarball on a desk. A release is permanent. A pre-release is retired, tag and all, when
+the branch it was tagged on is deleted and no other branch reaches its commit.
 
 The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure), under
 `terraform/projects/kit`.
diff --git a/bin/kit b/bin/kit
index 2d9dd17..98e4e16 100755
--- a/bin/kit
+++ b/bin/kit
@@ -50,6 +50,8 @@ usage: kit <verb> [<argument>…]
                         the desk, the worktrees, and the open pull requests
   lint [--all-files] [<path>…]
                         run each rule's linter over the paths it governs: staged, named, or every tracked one
+  release <verify|pack|publish|retire> …
+                        the kit's own release: verify a tag, pack a checkout, publish it, retire pre-releases
   version               print this release's version
 
 Each verb answers --help.
diff --git a/bin/kit-release.sh b/bin/kit-release.sh
new file mode 100755
index 0000000..87a4dfb
--- /dev/null
+++ b/bin/kit-release.sh
@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# kit-release - verify a release tag, pack a checkout as a release, publish it, and retire pre-releases (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The kit releasing itself, as verbs a workflow step or a desk calls alike:
+#
+#   verify <tag>              the tag is v<major>.<minor>.<patch>, on the default branch, or the same with a
+#                             -<suffix>, a pre-release, on a commit off it; refused otherwise, naming why
+#   pack <tag> [<directory>]  kit-<version>.tar.gz and its .sha256 in <directory>, the current one by default:
+#                             one directory kit-<version>/ with bin/, modules/, and the version stamped in
+#   publish <tag>             pack, then a GitHub release carrying both files, marked pre-release for a suffix
+#   retire [<branch>]         delete every pre-release whose commit no remaining branch reaches, after <branch>
+#                             was deleted; the branch is the runner's delete event when none is given
+#
+# A release is permanent and immutable; only a pre-release is ever retired.
+#
+# see: .github/workflows/release.yml, .github/workflows/retire-pre-releases.yml
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use git release
+
+usage() { echo "usage: kit release verify <tag> | pack <tag> [<directory>] | publish <tag> | retire [<branch>]" >&2; }
+
+# release-tag:refuse <message> is the one refusal: the message, the runner's error line, the summary, exit 1.
+release-tag:refuse() {
+  error "$1"
+  summary "### ❌ $1"
+  exit 1
+}
+
+# release-tag:version <tag> prints the version a tag names, refusing a tag that is not a version.
+release-tag:version() {
+  local version=${1#v}
+  if [[ "$1" != v* || ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
+  then
+    release-tag:refuse "$1 is not a version tag: v<major>.<minor>.<patch>, with -<suffix> for a pre-release"
+  fi
+  printf '%s\n' "${version}"
+}
+
+verb=${1:-}
+case "${verb}" in
+  (--help | '') usage; exit 0 ;;
+  (verify | pack | publish | retire) ;;
+  (*) usage; exit 2
+esac
+shift
+
+case "${verb}" in
+  (verify)
+    (( $# == 1 )) || { usage; exit 2; }
+    tag=$1
+    version=$(release-tag:version "${tag}")
+    default_branch=$(git:default-branch)
+    on_default=false
+    git merge-base --is-ancestor "${tag}" "origin/${default_branch}" 2>/dev/null && on_default=true
+    if [[ "${version}" == *-* && "${on_default}" == true ]]
+    then
+      release-tag:refuse "${tag} is a pre-release tag on ${default_branch}; tag a pre-release on a commit off it"
+    fi
+    if [[ "${version}" != *-* && "${on_default}" == false ]]
+    then
+      release-tag:refuse "${tag} is not on ${default_branch}; a release is tagged there, a pre-release has a suffix"
+    fi
+    ok "${tag} is a version tag on the right side of ${default_branch} (on it: ${on_default})"
+    summary "✅ ${tag} is a version tag on the right side of ${default_branch}."
+    ;;
+  (pack)
+    (( $# >= 1 && $# <= 2 )) || { usage; exit 2; }
+    version=$(release-tag:version "$1")
+    into=${2:-.}
+    staging=$(mktemp -d)
+    # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
+    trap "rm -rf '${staging}'" EXIT
+    mkdir -p "${into}" "${staging}/kit-${version}"
+    cp -R "${kit_root}/bin" "${kit_root}/modules" "${staging}/kit-${version}/"
+    printf '%s\n' "${version}" > "${staging}/kit-${version}/version"
+    tar --create --gzip --file "${into}/kit-${version}.tar.gz" --directory "${staging}" "kit-${version}"
+    printf '%s  kit-%s.tar.gz\n' "$(release:digest < "${into}/kit-${version}.tar.gz")" "${version}" \
+      > "${into}/kit-${version}.tar.gz.sha256"
+    ok "packed kit ${version}: ${into}/kit-${version}.tar.gz and its .sha256"
+    ;;
+  (publish)
+    (( $# == 1 )) || { usage; exit 2; }
+    tag=$1
+    version=$(release-tag:version "${tag}")
+    guard:require tool:gh
+    into=$(mktemp -d)
+    # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
+    trap "rm -rf '${into}'" EXIT
+    "${kit_root}/bin/kit" release pack "${tag}" "${into}"
+    notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\n' "${version}"
+      printf 'Then, in the repository: kit install\n')
+    flags=()
+    [[ "${version}" == *-* ]] && flags+=(--prerelease)
+    gh release create "${tag}" "${into}/kit-${version}.tar.gz" "${into}/kit-${version}.tar.gz.sha256" \
+      --title "kit ${version}" --notes "${notes}" "${flags[@]}"
+    ok "released kit ${version}"
+    summary "✅ Released kit ${version}."
+    ;;
+  (retire)
+    (( $# <= 1 )) || { usage; exit 2; }
+    deleted=${1:-}
+    [[ -n "${deleted}" || -z "${GITHUB_EVENT_PATH:-}" ]] \
+      || deleted=$(jq --raw-output '.ref // empty' "${GITHUB_EVENT_PATH}")
+    guard:require tool:gh
+    git fetch --quiet --tags origin
+    retired=0
+    while IFS= read -r tag
+    do
+      [[ -n "${tag}" ]] || continue
+      commit=$(git rev-parse --verify --quiet "${tag}^{commit}" || true)
+      if [[ -z "${commit}" ]]
+      then
+        warn "${tag} has no commit here; leaving it"
+        continue
+      fi
+      if git branch --remotes --contains "${commit}" | grep --quiet --invert-match 'origin/HEAD'
+      then
+        step "keeping ${tag}: a branch still reaches ${commit:0:7}"
+        continue
+      fi
+      gh release delete "${tag}" --cleanup-tag --yes
+      step "retired ${tag}: no branch reaches ${commit:0:7}${deleted:+ since ${deleted} was deleted}"
+      retired=$(( retired + 1 ))
+    done < <(gh release list --limit 1000 --json tagName,isPrerelease --jq '.[] | select(.isPrerelease) | .tagName')
+    ok "retired ${retired} pre-release(s)"
+    summary "✅ Retired ${retired} pre-release(s)."
+esac
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/release.bats b/tests/release.bats
index 2307876..139509f 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# release.bats - a release packed the way the workflow packs it installs from its unpacked directory
+# release.bats - kit release verifies a tag and packs a checkout as a release that installs from its unpacked directory
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -14,14 +14,35 @@ teardown() {
   rm -rf "${work}"
 }
 
-@test "the tarball holds one directory with the release's layout, and installs a fresh repository" {
-  # packed the way the workflow packs it, with the tag's version stamped in
+@test "verify holds a tag to its shape and its side of the default branch" {
+  git init --quiet --bare origin.git && git clone --quiet origin.git desk 2>/dev/null && cd desk
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  printf 'one\n' > a && git add a && git commit --quiet --message one && git push --quiet origin main
+  git remote set-head origin main
+  git tag v1.2.3 && git tag v1.2.3-rc.1 && git tag vnope
+  git switch --quiet --create topic && printf 'two\n' > b && git add b && git commit --quiet --message two
+  git tag v1.2.4 && git tag v1.2.4-rc.1
+  run "${kit_checkout}/bin/kit" release verify v1.2.3
+  [ "$status" -eq 0 ]
+  run "${kit_checkout}/bin/kit" release verify v1.2.4-rc.1
+  [ "$status" -eq 0 ]
+  run "${kit_checkout}/bin/kit" release verify v1.2.3-rc.1
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"is a pre-release tag on main"* ]]
+  run "${kit_checkout}/bin/kit" release verify v1.2.4
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"is not on main"* ]]
+  run "${kit_checkout}/bin/kit" release verify vnope
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"is not a version tag"* ]]
+}
+
+@test "pack makes one directory with the release's layout and the version stamped in, which installs a repository" {
   version=9.9.9
-  mkdir "kit-${version}"
-  cp -R "${kit_checkout}/bin" "${kit_checkout}/modules" "kit-${version}/"
-  printf '%s\n' "${version}" > "kit-${version}/version"
-  tar --create --gzip --file "kit-${version}.tar.gz" "kit-${version}"
-  rm -rf "kit-${version}"
+  run "${kit_checkout}/bin/kit" release pack "v${version}" "${work}"
+  [ "$status" -eq 0 ]
+  [ -f "kit-${version}.tar.gz.sha256" ]
+  grep --quiet "  kit-${version}.tar.gz$" "kit-${version}.tar.gz.sha256"
   mkdir unpacked && tar --extract --gzip --file "kit-${version}.tar.gz" --directory unpacked
   [ "$(ls unpacked)" = "kit-${version}" ]
   [ -x "unpacked/kit-${version}/bin/kit" ]

From ebfb8858a85eafc788341014d56a1a301d673056 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Mon, 26 Oct 2026 00:02:06 -0700
Subject: [PATCH 083/108] #5 tests/release.bats: name the bare origin's branch,
 as the runner's git defaults to master

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/release.bats | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/release.bats b/tests/release.bats
index 139509f..9fd4e67 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -15,7 +15,7 @@ teardown() {
 }
 
 @test "verify holds a tag to its shape and its side of the default branch" {
-  git init --quiet --bare origin.git && git clone --quiet origin.git desk 2>/dev/null && cd desk
+  git init --quiet --bare --initial-branch=main origin.git && git clone --quiet origin.git desk 2>/dev/null && cd desk
   git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
   printf 'one\n' > a && git add a && git commit --quiet --message one && git push --quiet origin main
   git remote set-head origin main

From 648bf0b6b20c786737b187e3d5417e7b2bed405d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Mon, 26 Oct 2026 00:06:56 -0700
Subject: [PATCH 084/108] #5 justfile: the toolchain on PATH once at parse
 time, [script] recipes, tools called bare

As enchiridion's justfile has it: mise bin-paths goes first on PATH when the file is parsed, so every
recipe calls its tools bare and the pinned tool wins on a desk and on the runner alike, and a bash
body is a [script] recipe under set script-interpreter := ['bash'] rather than a shebang recipe. The
just rule says so.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/manifest                             |  2 +-
 .kit/rules/just.md                        | 29 ++++++++++++++------
 justfile                                  | 33 +++++++++++++++++------
 modules/kit/files/repo/.kit/rules/just.md | 29 ++++++++++++++------
 4 files changed, 68 insertions(+), 25 deletions(-)

diff --git a/.kit/manifest b/.kit/manifest
index 51b461c..a4ea8d7 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -10,7 +10,7 @@ f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
 17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
 693815dcde0979638e20f021a6e879e5a3cc1420374f1d1329fc92d936e3461d  .kit/rules/json.md
-9a32591381c47fbb449a7b1f2ab900911a18901cbec3e768663db1171c6a9262  .kit/rules/just.md
+bfa75fb42fd85d8c43034d910cff554fcbf1e273ad22806b481ebe985f1191f9  .kit/rules/just.md
 a809a1969212d3d21dfafb903d0d2fd04c97ce45a057e896fcc7dcf555c18689  .kit/rules/markdown.md
 2f0cfeca313280bf984aaad927cd459ecf61f93861a11ccc839b7d5b8406cbac  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index af77933..d15175d 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -9,8 +9,7 @@ content:
 ---
 # Just
 
-Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
-applies to it as well.
+Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the bash rule applies to it as well.
 
 ## Shape
 
@@ -18,9 +17,22 @@ applies to it as well.
    and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
    --justfile` shebang above that; a module does not.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), and `set positional-arguments := true`. `set export := true` comes after the
-   default-and-help pair, so that pair reads the same in every justfile.
-3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
+   root, which has no parent), `set positional-arguments := true`, and `set script-interpreter := ['bash']`,
+   the interpreter named bare so the pinned bash wins. `set export := true` comes after the default-and-help
+   pair, so that pair reads the same in every justfile.
+3. The root puts the mise-pinned toolchain first on `PATH` once, at parse time, from `mise bin-paths`, so every
+   recipe calls its tools bare and the pinned tool wins over any other copy, on a desk and on a runner alike:
+
+   ````just
+   export PATH := ```
+     mise bin-paths 2>/dev/null | while IFS= read -r d
+     do
+       case ":${PATH}:" in (*":${d}:"*) ;; (*) printf '%s:' "${d}" ;; esac
+     done
+     ``` + env('PATH')
+   ````
+
+4. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
    # This file's own path, assigned at parse time so the body below needs no interpolation.
@@ -35,9 +47,9 @@ applies to it as well.
      just --justfile "${<name>_justfile}" --list
    ```
 
-4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
+5. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
    the invoking root rather than the module's directory.
-5. The file closes with a rule of dashes.
+6. The file closes with a rule of dashes.
 
 ## Recipes
 
@@ -45,7 +57,8 @@ applies to it as well.
    Related recipes share an emoji.
 2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
    recipe does, when to run it, and what it produces.
-3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
+3. A non-trivial body is a `[script]` recipe, never a shebang recipe, with `set -o errexit -o nounset -o pipefail`
+   as its first line. A tool in it is called bare, never through `mise exec`.
 4. A body says what runs. Logic longer than a dozen lines lives in a bash script the body calls.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
    variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
diff --git a/justfile b/justfile
index 3bb2956..f086e2d 100644
--- a/justfile
+++ b/justfile
@@ -7,6 +7,22 @@
 set dotenv-load := true
 set positional-arguments := true
 
+# A bash recipe body is hosted by the interpreter named here and marked [script], not by a shebang: a shebang
+# recipe is exec'd from a temp executable and costs more per invocation than `bash <file>`. The interpreter is
+# named bare so it resolves through the PATH built below, and the pinned bash wins over the system's.
+set script-interpreter := ['bash']
+
+# The mise-pinned toolchain's bin directories go first on PATH once, at parse time, so every recipe calls its
+# tools bare and the pinned tool wins over any Homebrew or system copy: the same directories mise-action puts on
+# the runner's PATH, so a desk and the runner cannot disagree about which tool ran. Idempotent by inspecting
+# PATH rather than a sentinel, so a nested just adds nothing.
+export PATH := ```
+  mise bin-paths 2>/dev/null | while IFS= read -r d
+  do
+    case ":${PATH}:" in (*":${d}:"*) ;; (*) printf '%s:' "${d}" ;; esac
+  done
+  ``` + env('PATH')
+
 # This file's own path, assigned at parse time so the body below needs no interpolation.
 export root_justfile := source_file()
 
@@ -21,18 +37,19 @@ _: help
 set export := true
 
 # The gate: kit lint over every tracked path, each rule's own linter, every module.yml and .kit/settings.yml
-# against their schemas, the bats suite, and bin/kit check over this repository's installed copy of its own kit. The runner runs it on every pull request, and a desk runs it the
-# same way; the pre-commit hook is the narrower, faster check over the staged paths.
+# against their schemas, the bats suite, and bin/kit check over this repository's installed copy of its own kit.
+# The runner runs it on every pull request, and a desk runs it the same way; the pre-commit hook is the narrower,
+# faster check over the staged paths.
 #
 #   just ci
 [doc("🚦 The gate: kit lint, the schemas, bats, kit check")]
+[script]
 ci:
-  #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
-  mise exec -- bin/kit lint --all-files
-  mise exec -- ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
-  mise exec -- ajv validate --spec=draft2020 -s .kit/settings.schema.json -d .kit/settings.yml
-  mise exec -- bats --print-output-on-failure tests/
+  bin/kit lint --all-files
+  ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
+  ajv validate --spec=draft2020 -s .kit/settings.schema.json -d .kit/settings.yml
+  bats --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
 
@@ -45,8 +62,8 @@ ci:
 #
 #   just refresh
 [doc("🔁 Bring this repository's own installed copies up to the index, and stage the result")]
+[script]
 refresh:
-  #!/usr/bin/env bash
   set -o errexit -o nounset -o pipefail
   paths() { awk 'length($1) == 64 { print substr($0, 67) }' .kit/manifest; }
   readarray -t before < <(paths)
diff --git a/modules/kit/files/repo/.kit/rules/just.md b/modules/kit/files/repo/.kit/rules/just.md
index af77933..d15175d 100644
--- a/modules/kit/files/repo/.kit/rules/just.md
+++ b/modules/kit/files/repo/.kit/rules/just.md
@@ -9,8 +9,7 @@ content:
 ---
 # Just
 
-Applies to `justfile` and `*.just`. A recipe body under `#!/usr/bin/env bash` is bash, and the bash rule
-applies to it as well.
+Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the bash rule applies to it as well.
 
 ## Shape
 
@@ -18,9 +17,22 @@ applies to it as well.
    and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
    --justfile` shebang above that; a module does not.
 2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), and `set positional-arguments := true`. `set export := true` comes after the
-   default-and-help pair, so that pair reads the same in every justfile.
-3. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
+   root, which has no parent), `set positional-arguments := true`, and `set script-interpreter := ['bash']`,
+   the interpreter named bare so the pinned bash wins. `set export := true` comes after the default-and-help
+   pair, so that pair reads the same in every justfile.
+3. The root puts the mise-pinned toolchain first on `PATH` once, at parse time, from `mise bin-paths`, so every
+   recipe calls its tools bare and the pinned tool wins over any other copy, on a desk and on a runner alike:
+
+   ````just
+   export PATH := ```
+     mise bin-paths 2>/dev/null | while IFS= read -r d
+     do
+       case ":${PATH}:" in (*":${d}:"*) ;; (*) printf '%s:' "${d}" ;; esac
+     done
+     ``` + env('PATH')
+   ````
+
+4. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
    # This file's own path, assigned at parse time so the body below needs no interpolation.
@@ -35,9 +47,9 @@ applies to it as well.
      just --justfile "${<name>_justfile}" --list
    ```
 
-4. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
+5. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
    the invoking root rather than the module's directory.
-5. The file closes with a rule of dashes.
+6. The file closes with a rule of dashes.
 
 ## Recipes
 
@@ -45,7 +57,8 @@ applies to it as well.
    Related recipes share an emoji.
 2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
    recipe does, when to run it, and what it produces.
-3. A non-trivial body is `#!/usr/bin/env bash` with `set -o errexit -o nounset -o pipefail` as its first line.
+3. A non-trivial body is a `[script]` recipe, never a shebang recipe, with `set -o errexit -o nounset -o pipefail`
+   as its first line. A tool in it is called bare, never through `mise exec`.
 4. A body says what runs. Logic longer than a dozen lines lives in a bash script the body calls.
 5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
    variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads

From 47294bc5aab256c3b9f43734bacbdabd5f593325 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Mon, 26 Oct 2026 00:35:09 -0700
Subject: [PATCH 085/108] #5 kit-ci.yml: a missing manifest is refused with the
 remedy, not a sed error

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml                                 | 5 +++++
 .kit/manifest                                                | 2 +-
 .../ci-github/templates/repo/.github/workflows/kit-ci.yml    | 5 +++++
 3 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index e59da51..e324cb2 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -38,6 +38,11 @@ jobs:
       - name: kit-on-path
         run: |
           set -o errexit -o nounset -o pipefail
+          if [[ ! -f .kit/manifest ]]
+          then
+            echo '::error::run kit install and commit what it writes; this repository has no .kit/manifest to name a release'
+            exit 1
+          fi
           version=$(sed -n 's/^version //p' .kit/manifest)
           if [[ "${version}" == unreleased && -x bin/kit ]]
           then
diff --git a/.kit/manifest b/.kit/manifest
index a4ea8d7..a941c42 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,7 +3,7 @@ version unreleased
 modules kit ci-github claude lefthook
 7b50d15feae7b63b94d845b2fa6e19e3220527c5b0cac69303b7fc19bd7484a8  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-24b66b6015ccf244245373009b35fc9610c52dc16d88ab6c842f21d116c74f02  .github/workflows/kit-ci.yml
+277615ebe5af6a9fe9e183316aac74a0cf644aeef749ae3405631713015524f4  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
 9f837e32f290c2e7b020ba2b35c2d73b2a368eb04db86db1024a744da024acad  .kit/1st.md
 f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
diff --git a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
index 9f0d39b..33c275e 100644
--- a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
@@ -38,6 +38,11 @@ jobs:
       - name: kit-on-path
         run: |
           set -o errexit -o nounset -o pipefail
+          if [[ ! -f .kit/manifest ]]
+          then
+            echo '::error::run kit install and commit what it writes; this repository has no .kit/manifest to name a release'
+            exit 1
+          fi
           version=$(sed -n 's/^version //p' .kit/manifest)
           if [[ "${version}" == unreleased && -x bin/kit ]]
           then

From 2755d81ca06e76ece481be97391d34097aee9ae5 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Mon, 26 Oct 2026 01:23:54 -0700
Subject: [PATCH 086/108] Apply review round two: regions, lint, gate, docs,
 and tests

Region placement grows up: a destination that is a symlink keeps its link and the write
lands in its target; a directory at a destination is refused by name; a region that opens
and never closes is refused rather than treated as absent; two modules delivering a region
to the same path are refused at render; markers follow the file's comment syntax by
extension, and a kind of file the kit cannot mark is refused. Removing a region leaves no
leading blank line.

kit lint takes a named path relative to the directory the command was typed in and reads
git's lists NUL-separated. kit gate writes the failed gate to the step summary and detects
Justfile and .justfile too. The markdown rule's linter reads a delivered
.kit/markdownlint.jsonc, so a fresh repository lints its delivered markdown clean, and this
repository's own .markdownlint.jsonc goes. The GitHub provider parses the pull request
number from the URL gh prints, and the kit-ci template refuses an unreleased manifest with
no bin/kit. The YAML reader accepts keys with digits, underscores, and dashes.

Tests shim gh and the step summary wherever the real ones could be reached, the vacuous
inverted greps become real ones, and new cases cover each refusal above. Headers, docs,
figures, the entry file, and the README say regions, settings, and the delivered check the
same way the code does, and every prose line fits 120 columns.

Closes nothing on its own; part of #5.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml                  |  14 +-
 .github/workflows/release.yml                 |   3 +-
 .github/workflows/retire-pre-releases.yml     |   3 +-
 .kit/1st.md                                   |  12 +-
 .kit/manifest                                 |  13 +-
 .kit/markdownlint.jsonc                       |  20 +++
 .kit/rules/gitignore.md                       |   5 +-
 .kit/rules/markdown.md                        |   2 +-
 .kit/rules/workflows.md                       |   4 +-
 .kit/settings.schema.json                     |   2 +-
 .markdownlint.jsonc                           |  23 ---
 AGENTS.md                                     |   8 +-
 README.md                                     |  60 ++++----
 bin/1st.sh                                    |   8 --
 bin/forge-github.sh                           |  14 +-
 bin/forge.sh                                  |   6 +-
 bin/kit-gate.sh                               |  13 +-
 bin/kit-lint.sh                               |  11 +-
 bin/kit-release.sh                            |  24 ++--
 bin/release.sh                                | 135 +++++++++++++++---
 bin/status.sh                                 |   3 +-
 bin/yaml.sh                                   |  14 +-
 docs/architecture.md                          |  54 ++++---
 docs/context.md                               |   4 +-
 docs/context.svg                              |   2 +-
 docs/delivery.svg                             |  15 +-
 docs/loop.svg                                 |  10 +-
 docs/modules.md                               |  29 ++--
 justfile                                      |  13 +-
 mise.toml                                     |   2 +-
 modules/ci-github/docs/README.md              |   6 +-
 .../repo/.github/workflows/kit-ci.yml         |  14 +-
 modules/claude/docs/README.md                 |  11 +-
 modules/kit/docs/README.md                    |   6 +-
 modules/kit/files/repo/.kit/1st.md            |  12 +-
 .../kit/files/repo/.kit/markdownlint.jsonc    |  20 +++
 .../kit/files/repo/.kit/rules/gitignore.md    |   5 +-
 modules/kit/files/repo/.kit/rules/markdown.md |   2 +-
 .../kit/files/repo/.kit/rules/workflows.md    |   4 +-
 .../kit/files/repo/.kit/settings.schema.json  |   2 +-
 tests/ci.bats                                 |   1 +
 tests/forge.bats                              |   3 +-
 tests/gate.bats                               |   4 +-
 tests/kit.bats                                |  46 +++++-
 tests/linked.bats                             |   5 +-
 tests/lint.bats                               |  21 ++-
 46 files changed, 452 insertions(+), 236 deletions(-)
 create mode 100644 .kit/markdownlint.jsonc
 delete mode 100644 .markdownlint.jsonc
 create mode 100644 modules/kit/files/repo/.kit/markdownlint.jsonc

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index e324cb2..94b5179 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -1,4 +1,4 @@
-# kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request
+# kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request into the default branch
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
@@ -30,9 +30,11 @@ jobs:
       # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
       MISE_ENV: ci
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
+      - name: tools-from-mise
+        uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
         if: ${{ hashFiles('mise.toml') != '' }}
 
       - name: kit-on-path
@@ -40,13 +42,17 @@ jobs:
           set -o errexit -o nounset -o pipefail
           if [[ ! -f .kit/manifest ]]
           then
-            echo '::error::run kit install and commit what it writes; this repository has no .kit/manifest to name a release'
+            echo '::error::run kit install and commit what it writes; this repository has no .kit/manifest'
             exit 1
           fi
           version=$(sed -n 's/^version //p' .kit/manifest)
           if [[ "${version}" == unreleased && -x bin/kit ]]
           then
             printf '%s/bin\n' "${PWD}" >> "${GITHUB_PATH}"
+          elif [[ "${version}" == unreleased ]]
+          then
+            echo '::error::.kit/manifest says unreleased and there is no bin/kit; pin a release and run kit update'
+            exit 1
           elif ! command -v kit >/dev/null
           then
             mkdir -p "${RUNNER_TEMP}/kit"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 58d7e9f..d97358e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -22,7 +22,8 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
 
diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
index a8d8214..40816ba 100644
--- a/.github/workflows/retire-pre-releases.yml
+++ b/.github/workflows/retire-pre-releases.yml
@@ -20,7 +20,8 @@ jobs:
     if: github.event.ref_type == 'branch'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
 
diff --git a/.kit/1st.md b/.kit/1st.md
index 7ba6b5f..c7e65ce 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -12,7 +12,8 @@ the repository's own rules in `AGENTS.md` bind beside it. Where the two differ,
 3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
 4. Being wrong is recoverable. Misreporting is not.
 5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
-   written into a rule file or `AGENTS.md` through the loop, where every agent and every person reads it.
+   written, through the loop, into `AGENTS.md`, a module of the repository's own under `.kit/modules/`, or a kit
+   release, where every agent and every person reads it.
 
 ## The root checkout is the human's desk
 
@@ -94,11 +95,12 @@ carries the machinery, reached through the `kit` command on `PATH`: the loop's c
 `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
 delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
-lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
-only the entries it writes; everything else is copied as it is.
+lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
+key, the kit owning only the entries it writes; a region is held between its markers inside a file the
+repository owns; everything else is copied as it is.
 
-- `kit`: this file and the rules, discovered through `kit context`; the sentence in `AGENTS.md` that points here
-  and the `/worktrees/` entry in `.gitignore`, each a region the kit owns inside a file the repository owns.
+- `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
+  `.gitignore`, each a region the kit owns inside a file the repository owns.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/.kit/manifest b/.kit/manifest
index a941c42..0e86761 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,16 +3,17 @@ version unreleased
 modules kit ci-github claude lefthook
 7b50d15feae7b63b94d845b2fa6e19e3220527c5b0cac69303b7fc19bd7484a8  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-277615ebe5af6a9fe9e183316aac74a0cf644aeef749ae3405631713015524f4  .github/workflows/kit-ci.yml
+489c6b1cca814e69a5bfb826e34a6eb9378d51cbd05b66357bcd663d0cefe536  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
-9f837e32f290c2e7b020ba2b35c2d73b2a368eb04db86db1024a744da024acad  .kit/1st.md
+3a799487c744e7e4d089ca92d6e77a68422388454a41fd412c265d66d13a8f83  .kit/1st.md
 f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
+acf52f60f178be28ca2f09bb22f8a982bba0e61eff611ca1a91f1f8dae2ccbce  .kit/markdownlint.jsonc
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
-17890b40f40e1e4181ce8293d2c88fefc513cd5613a8a3b7e0766132571532c2  .kit/rules/gitignore.md
+b0f6e0e6ac1c2d1271082459f53b0cfdc7ad5028a6cd9a5d3a899bf160b5cde9  .kit/rules/gitignore.md
 693815dcde0979638e20f021a6e879e5a3cc1420374f1d1329fc92d936e3461d  .kit/rules/json.md
 bfa75fb42fd85d8c43034d910cff554fcbf1e273ad22806b481ebe985f1191f9  .kit/rules/just.md
-a809a1969212d3d21dfafb903d0d2fd04c97ce45a057e896fcc7dcf555c18689  .kit/rules/markdown.md
-2f0cfeca313280bf984aaad927cd459ecf61f93861a11ccc839b7d5b8406cbac  .kit/rules/workflows.md
+87aa30f09c4d931d8c77731f0d6877d98e5ccfc32a775918f774bb5a5010b232  .kit/rules/markdown.md
+ceb28d32ae5522b1e0586551667bab18809c1f9be1ffcf0ed4eadbceffb2f99c  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
-61c7dd26e9cd18e975cc0844dc6a690f1832f87d45ff2ccb37a4173f966834df  .kit/settings.schema.json
+b1d0219000842bd05d6e2b865854cd23ce4b221bfff5992f744de446b158da38  .kit/settings.schema.json
 dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/.kit/markdownlint.jsonc b/.kit/markdownlint.jsonc
new file mode 100644
index 0000000..7d880aa
--- /dev/null
+++ b/.kit/markdownlint.jsonc
@@ -0,0 +1,20 @@
+// .kit/markdownlint.jsonc - the markdownlint configuration the markdown rule's linter reads
+// ----------------------------------------------------------------------------------------------------------------------
+// Delivered by kit, not edited by hand. A change is a new release, then kit update. The markdown rule, .kit/rules/markdown.md,
+// is the convention; each setting here is one of its lines the linter can hold.
+
+{
+  // MD003 heading-style: ATX headings, the rule's §Layout 5.
+  "MD003": { "style": "atx" },
+
+  // MD013 line-length: prose wraps at 118, 120 being the ceiling; code and tables do not wrap (§Layout 1 and 3).
+  "MD013": { "line_length": 120, "code_blocks": false, "tables": false },
+
+  // MD041 first-line-heading: a delivered file opens with its notice, AGENTS.md with the sentence a harness reads
+  // first (§Layout 5).
+  "MD041": false,
+
+  // MD060 table-column-style: tables use " | " with spaces around each pipe (§Layout 7); the check is stricter
+  // than the rule and is off.
+  "MD060": false
+}
diff --git a/.kit/rules/gitignore.md b/.kit/rules/gitignore.md
index f1278c4..2712da0 100644
--- a/.kit/rules/gitignore.md
+++ b/.kit/rules/gitignore.md
@@ -10,8 +10,9 @@ Applies to `.gitignore` at any depth.
 
 ## Shape
 
-1. The file opens with `# .gitignore - untracked files and folders`, a rule of dashes to column 120, and a
-   blank line.
+1. A file the repository writes opens with `# .gitignore - untracked files and folders`, a rule of dashes to
+   column 120, and a blank line. One the kit made of its region alone is the kit's until the repository adds
+   to it.
 2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
    line.
 3. The file closes with a rule of dashes.
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index 73b95ca..4feb54c 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -2,7 +2,7 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.md"
-lint: markdownlint-cli2
+lint: markdownlint-cli2 --config .kit/markdownlint.jsonc
 ---
 # Markdown
 
diff --git a/.kit/rules/workflows.md b/.kit/rules/workflows.md
index 37fb51f..4d02c2b 100644
--- a/.kit/rules/workflows.md
+++ b/.kit/rules/workflows.md
@@ -27,4 +27,6 @@ Applies to GitHub Actions workflows, under `.github/workflows/`. The YAML rule a
    also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
 5. A step whose verdict a reader looks for writes one `✅` line to the summary.
 6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step.
+7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step. The one
+   exception is the kit itself, which the delivered job fetches from the release `.kit/manifest` names, since
+   nothing else can put it there first.
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
index 84689ee..8a334ae 100644
--- a/.kit/settings.schema.json
+++ b/.kit/settings.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
   "title": ".kit/settings.yml",
-  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; https://github.com/empowerite/kit/blob/main/docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
   "type": "object",
   "additionalProperties": false,
   "properties": {
diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
deleted file mode 100644
index abb6244..0000000
--- a/.markdownlint.jsonc
+++ /dev/null
@@ -1,23 +0,0 @@
-// .markdownlint.jsonc - markdownlint rule configuration: which built-in rules this repository turns off or tightens
-//
-// Scope lives in .markdownlint-cli2.jsonc; this file carries only rule state. A rule is off because it collides
-// with a convention the markdown rule states its own way, so every entry names the rule and the convention; a
-// rule is tightened where the default is looser than the convention.
-//
-// see: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
-// see: modules/kit/files/repo/.kit/rules/markdown.md
-{
-  // MD003 heading-style, tightened: the markdown rule says ATX, and "consistent" would accept a setext file.
-  "MD003": { "style": "atx" },
-
-  // MD013 line-length: the 120-column ceiling the markdown rule sets; fenced code and tables do not wrap.
-  "MD013": { "line_length": 120, "code_blocks": false, "tables": false },
-
-  // MD041 first-line-heading: AGENTS.md opens with the sentence a harness reads first, and a delivered file opens
-  // with its notice; the title follows.
-  "MD041": false,
-
-  // MD060 table-column-style: the markdown rule asks for ` | ` around each pipe and nothing about column widths,
-  // which this rule's aligned default would fight column by column.
-  "MD060": false
-}
diff --git a/AGENTS.md b/AGENTS.md
index a115149..6085c08 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,8 +10,8 @@ This repository is the kit's own source, and uses it.
 - The release is `bin/` and `modules/`. Everything in it is written for a consumer: no file names a consumer, a
   person, or another repository as the source of a rule.
 - Releases and pre-releases: [README.md](README.md) § Release.
-- `.kit/`, `.github/workflows/kit-ci.yml`, `.claude/CLAUDE.md`, and `.claude/settings.json` are this repository's
-  installed copies of its own kit, written by `just refresh` from `modules/`; see [README.md](README.md)
-  § Maintaining. Edit the source; the pre-commit hook refreshes the copies into the same commit, and a desk
-  without the hook runs `just refresh` and commits both.
+- `.kit/`, `.github/workflows/kit-ci.yml`, `.claude/settings.json`, and the regions in `AGENTS.md`, `.gitignore`, and
+  `.claude/CLAUDE.md` are this repository's installed copies of its own kit, written by `just refresh` from `modules/`;
+  see [README.md](README.md) § Maintaining. Edit the source; the pre-commit hook refreshes the copies into the same
+  commit, and a desk without the hook runs `just refresh` and commits both.
 - `just ci` is the gate; the justfile says what it runs.
diff --git a/README.md b/README.md
index 7c1a395..dafe710 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # empowerite/kit: **k**eep **i**t **t**rustworthy
 
-Do you trust your agents? They were trained on the whole of what people have written, and that includes every
-shortcut anyone ever took: the "done" that was not, the test that was skipped and reported as passing, the rebase
-that quietly rewrote a colleague's branch. An agent is a tireless new colleague who has read everything and holds
-none of your house rules, unless you put them where it looks. kit is the house rules, put where agents look, and
-the checks that hold agents to them, as a versioned release any repository can take and keep taking.
+kit is the house rules, put where agents look, and the checks that hold agents to them, as a versioned release
+any repository can take and keep taking. Do you trust your agents? They were trained on the whole of what people
+have written, and that includes every shortcut anyone ever took: the "done" that was not, the test that was
+skipped and reported as passing, the rebase that quietly rewrote a colleague's branch. An agent is a tireless
+new colleague who has read everything and holds none of your house rules, unless you put them where it looks.
 
 The rules are the smaller part. The point is verification that does not depend on anyone's word:
 
@@ -15,12 +15,12 @@ The rules are the smaller part. The point is verification that does not depend o
 - a deny list that refuses the spellings the rules forbid;
 - `kit status`, which shows what every pull request's checks said.
 
-The text those checks hold the work against is the entry file an agent reads first and a rule file per kind of
-file. With it come the root checkout kept as the human's desk, and `kit issue`, the one command no harness
-provides, which turns an issue into a worktree with a draft pull request. A tag on `main` publishes a release. A
-repository pins it, installs it, and keeps rules of its own beside it. The design is
-[#1](https://github.com/empowerite/kit/issues/1) and [#4](https://github.com/empowerite/kit/issues/4), and the
-entry file every agent reads is [.kit/1st.md](.kit/1st.md).
+The text those checks hold the work against is the entry file an agent reads first and a rule file per kind of file. Two
+more things come with it. The root checkout is kept as the human's desk. And `kit issue`, the one command no harness
+provides, turns an issue into a worktree with a draft pull request. A tag on `main` publishes a release. A repository
+pins it, installs it, and keeps rules of its own beside it. The design is
+[#1](https://github.com/empowerite/kit/issues/1) and [#4](https://github.com/empowerite/kit/issues/4), and the entry
+file every agent reads is [.kit/1st.md](.kit/1st.md).
 
 ## Why a release, and not a copy
 
@@ -56,10 +56,11 @@ mkdir kit && tar --extract --gzip --file kit.tar.gz --directory kit --strip-comp
 export PATH="${PWD}/kit/bin:${PATH}"
 ```
 
-The kit needs bash 4.4 or later, git, and `jq`; the loop's verbs, `kit issue`, `kit status`, `kit tidy`, and
-`kit linked`, also need the forge's own tool, `gh` for GitHub. macOS ships bash 3.2, and `brew install bash` gives
-a current one. With mise, an exact pin installs the minute a release exists; a range pin sees a new kit a day after
-it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:empowerite/kit"]`.
+The kit needs bash 4.4 or later, git, and `jq`. The loop's verbs, `kit issue`, `kit status`, `kit tidy`, and `kit
+linked`, also need the tool of the forge, the service that hosts the repository: `gh` for GitHub. macOS ships bash 3.2,
+and `brew install bash` gives a current one. With mise, an exact pin installs the minute a release exists; a range pin
+sees a new kit a day after it ships unless `[settings]` carries `minimum_release_age_excludes =
+["github:empowerite/kit"]`.
 
 ## Take the kit
 
@@ -73,10 +74,10 @@ it ships unless `[settings]` carries `minimum_release_age_excludes = ["github:em
   holds only what is between the markers.
 - Commit what `install` wrote.
 - Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
-  or any command as `gate` in `.kit/settings.yml`. `kit ci` runs it, with `kit check` and `kit linked`, from the
-  delivered workflow or from any pipeline of your own, and refuses when there is none.
-- Run the linters before a commit: `kit lint` runs each rule's own linter over the staged paths with no hook
-  manager at all, and the `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
+  or any command as `gate` in `.kit/settings.yml`. The delivered check, `kit ci`, runs it with `kit check` and
+  `kit linked`, from the delivered workflow or from any pipeline of your own, and refuses when there is none.
+- Run the linters before a commit. `kit lint` runs each rule's own linter over the staged paths with no hook
+  manager at all. The `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
   in `lefthook.yml`, and run `lefthook install` once per clone.
 
 `claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is present.
@@ -91,7 +92,7 @@ Before an agent creates or changes a file, it asks `kit context "${path}"` which
 To move to a new release, bump the pin or reinstall, then run `kit update`. A delivered file you left alone is
 replaced. One you edited is three-way merged with the previous release as the base, which `update` fetches from
 GitHub when it is not on the machine; `KIT_BASE` names a copy of it where that fetch is not possible. Your own
-deny entries and settings keys stay. `kit check` fails, locally and in `CI`, when a delivered file differs from
+deny entries and settings keys stay. `kit check` fails, locally and in CI, when a delivered file differs from
 the pinned release.
 
 ## Setup
@@ -99,10 +100,11 @@ the pinned release.
 The sections from here on are about working on this repository, the kit's own source, which uses its own kit.
 
 Its tools come from mise. Every commit is signed, and the branch ruleset refuses one that is not. If you have no
-signing key GitHub verifies, make one and register it, following
-[generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
-and [adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account).
-Then, once per clone, with the key's id in `signing_key`:
+signing key GitHub verifies, make one and register it, following these two pages, then run the commands below
+once per clone, with the key's id in `signing_key`:
+
+- [generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
+- [adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account)
 
 ```sh
 git config gpg.format openpgp
@@ -146,15 +148,16 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
 | `.claude/CLAUDE.md` | `modules/claude/regions/repo/.claude/CLAUDE.md`, a region; the rest of the file is the repository's |
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
+| `AGENTS.md`, `.gitignore` | `modules/kit/regions/repo/`, regions; the rest of each file is the repository's |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
-`.kit/settings.yml` is this repository's own, and `.kit/modules/` would hold modules of its own; it has none.
+`.kit/settings.yml` is this repository's own.
 
 A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the pre-commit
 hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk without the
 hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names any installed
-copy that does not match its source. Each delivered text file says in its header that it is delivered by kit;
-`settings.json` cannot, so this table is its notice.
+copy that does not match its source. Each delivered whole file says in its header that it is delivered by kit; a
+region's markers are its notice, and this table is `settings.json`'s.
 
 ## Release
 
@@ -167,5 +170,4 @@ publish`, which packs `bin/`, `modules/`, and `version` into `kit-<version>.tar.
 release pack` makes the same tarball on a desk. A release is permanent. A pre-release is retired, tag and all, when
 the branch it was tagged on is deleted and no other branch reaches its commit.
 
-The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure), under
-`terraform/projects/kit`.
+The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure).
diff --git a/bin/1st.sh b/bin/1st.sh
index 0e97a45..a2db375 100644
--- a/bin/1st.sh
+++ b/bin/1st.sh
@@ -78,7 +78,6 @@ summary() {
 }
 
 # guard:require <predicate>… returns non-zero on the first predicate that does not hold, with the remedy.
-#   gh           gh is usably authenticated (a real API call, since a revoked token still passes gh auth status)
 #   signing-key  git user.signingkey is set
 #   tool:<name>  <name> is on PATH
 guard:require() {
@@ -86,13 +85,6 @@ guard:require() {
   for predicate in "$@"
   do
     case "${predicate}" in
-      (gh)
-        if ! gh api user --jq '.login' >/dev/null 2>&1
-        then
-          error "run: gh auth login (the GitHub CLI is not authenticated)"
-          return 1
-        fi
-        ;;
       (signing-key)
         if [[ -z "$(git config user.signingkey 2>/dev/null)" ]]
         then
diff --git a/bin/forge-github.sh b/bin/forge-github.sh
index 8522dec..33d9f27 100644
--- a/bin/forge-github.sh
+++ b/bin/forge-github.sh
@@ -28,7 +28,9 @@ forge-github:repo-url() {
 }
 
 forge-github:me() {
-  gh api user --jq '.login' 2>/dev/null || { error "run: gh auth login (the GitHub CLI is not authenticated)"; return 1; }
+  gh api user --jq '.login' 2>/dev/null && return 0
+  error "run: gh auth login (the GitHub CLI is not authenticated)"
+  return 1
 }
 
 forge-github:issue-create() {
@@ -75,8 +77,9 @@ forge-github:pr-for-branch() {
 }
 
 forge-github:pr-create() {
-  gh pr create --draft --base "$2" --head "$1" --title "$3" --body "" >/dev/null
-  gh pr list --head "$1" --state open --json number --jq '.[0].number'
+  local url
+  url=$(gh pr create --draft --base "$2" --head "$1" --title "$3" --body "") || return 1
+  printf '%s\n' "${url##*/}"
 }
 
 forge-github:pr-body() {
@@ -94,7 +97,10 @@ forge-github:pr-state-for-branch() {
 # On a runner the event names the pull request; on a desk the current branch does.
 forge-github:pr-here() {
   local number=''
-  [[ -n "${GITHUB_EVENT_PATH:-}" ]] && number=$(jq --raw-output '.pull_request.number // empty' "${GITHUB_EVENT_PATH}")
+  if [[ -n "${GITHUB_EVENT_PATH:-}" ]]
+  then
+    number=$(jq --raw-output '.pull_request.number // empty' "${GITHUB_EVENT_PATH}" 2>/dev/null || true)
+  fi
   [[ -n "${number}" ]] || number=$(gh pr view --json number --jq .number 2>/dev/null || true)
   printf '%s\n' "${number}"
 }
diff --git a/bin/forge.sh b/bin/forge.sh
index 21b4465..8efbe5f 100644
--- a/bin/forge.sh
+++ b/bin/forge.sh
@@ -8,7 +8,8 @@
 # the one origin's host names. The core verbs never come here, so a repository on no forge still installs,
 # updates, checks, and runs kit context and kit lint.
 #
-# A provider answers these calls, each printing its result on stdout and failing with a remedy on stderr:
+# A provider answers these calls, each printing its result on stdout and failing with a remedy on stderr, or
+# printing nothing where the call says so:
 #
 #   require                       the provider's own tool is present and authenticated
 #   repo                          the repository as owner/name
@@ -46,7 +47,8 @@ forge:provider() {
   fi
   if [[ -z "${provider}" ]]
   then
-    error "set forge in .kit/settings.yml; origin's host '${host:-none}' names no forge the kit knows ($(forge:providers))"
+    error "set forge in .kit/settings.yml; origin's host '${host:-none}' names no forge the kit knows" \
+      "($(forge:providers))"
     return 1
   fi
   # shellcheck disable=SC2154  # kit_bin_dir is declared by bin/1st.sh, which loaded this module
diff --git a/bin/kit-gate.sh b/bin/kit-gate.sh
index f294c13..aecd577 100755
--- a/bin/kit-gate.sh
+++ b/bin/kit-gate.sh
@@ -21,9 +21,9 @@ then
 fi
 
 # gate:detect prints the command of the first gate found, or nothing.
-gate:detect() {
+detect-gate() {
   local recipes
-  if [[ -f justfile ]]
+  if [[ -f justfile || -f Justfile || -f .justfile ]]
   then
     if ! recipes=$(just --summary 2>&1)
     then
@@ -47,7 +47,7 @@ gate:detect() {
 }
 
 gate=$(release:setting gate)
-[[ -n "${gate}" ]] || gate=$(gate:detect) || exit 1
+[[ -n "${gate}" ]] || gate=$(detect-gate) || exit 1
 if [[ -z "${gate}" ]]
 then
   error "set gate in .kit/settings.yml, or give the root justfile a ci recipe; there is no gate to run"
@@ -57,7 +57,12 @@ then
   exit 1
 fi
 step "the gate: ${gate}"
-bash -c "${gate}"
+if ! bash -c "${gate}"
+then
+  error "the gate failed: ${gate}"
+  summary "### ❌ The gate failed: \`${gate}\`"
+  exit 1
+fi
 summary "✅ The gate passed: \`${gate}\`."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-lint.sh b/bin/kit-lint.sh
index a6bfb38..d493b48 100755
--- a/bin/kit-lint.sh
+++ b/bin/kit-lint.sh
@@ -32,13 +32,19 @@ do
     (*) paths+=("${arg}")
   esac
 done
+# A named path is taken from the directory the command was typed in; git's lists are root-relative already,
+# read NUL-separated so a name with a space or a non-ASCII character survives.
+for i in "${!paths[@]}"
+do
+  paths[i]=$(context:relative "${paths[i]}")
+done
 if (( ${#paths[@]} == 0 ))
 then
   if [[ "${all}" == true ]]
   then
-    readarray -t paths < <(git ls-files)
+    readarray -d '' -t paths < <(git ls-files -z)
   else
-    readarray -t paths < <(git diff --cached --name-only --diff-filter=ACMR)
+    readarray -d '' -t paths < <(git diff --cached --name-only --diff-filter=ACMR -z)
   fi
 fi
 if (( ${#paths[@]} == 0 ))
@@ -51,7 +57,6 @@ fi
 declare -A governed=()
 for path in "${paths[@]}"
 do
-  path=$(context:relative "${path}")
   [[ -f "${path}" ]] || continue
   while IFS= read -r rule
   do
diff --git a/bin/kit-release.sh b/bin/kit-release.sh
index 87a4dfb..07b938a 100755
--- a/bin/kit-release.sh
+++ b/bin/kit-release.sh
@@ -10,7 +10,9 @@
 #                             one directory kit-<version>/ with bin/, modules/, and the version stamped in
 #   publish <tag>             pack, then a GitHub release carrying both files, marked pre-release for a suffix
 #   retire [<branch>]         delete every pre-release whose commit no remaining branch reaches, after <branch>
-#                             was deleted; the branch is the runner's delete event when none is given
+#                             was deleted; the branch is the runner's delete event when none is given. A
+#                             pre-release merged by a merge commit stays reachable from the default branch and
+#                             is kept; a squash merge frees it.
 #
 # A release is permanent and immutable; only a pre-release is ever retired.
 #
@@ -23,19 +25,19 @@ use git release
 
 usage() { echo "usage: kit release verify <tag> | pack <tag> [<directory>] | publish <tag> | retire [<branch>]" >&2; }
 
-# release-tag:refuse <message> is the one refusal: the message, the runner's error line, the summary, exit 1.
-release-tag:refuse() {
+# refuse-tag <message> is the one refusal: the message, the runner's error line, the summary, exit 1.
+refuse-tag() {
   error "$1"
   summary "### ❌ $1"
   exit 1
 }
 
-# release-tag:version <tag> prints the version a tag names, refusing a tag that is not a version.
-release-tag:version() {
+# tag-version <tag> prints the version a tag names, refusing a tag that is not a version.
+tag-version() {
   local version=${1#v}
   if [[ "$1" != v* || ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
   then
-    release-tag:refuse "$1 is not a version tag: v<major>.<minor>.<patch>, with -<suffix> for a pre-release"
+    refuse-tag "$1 is not a version tag: v<major>.<minor>.<patch>, with -<suffix> for a pre-release"
   fi
   printf '%s\n' "${version}"
 }
@@ -52,24 +54,24 @@ case "${verb}" in
   (verify)
     (( $# == 1 )) || { usage; exit 2; }
     tag=$1
-    version=$(release-tag:version "${tag}")
+    version=$(tag-version "${tag}")
     default_branch=$(git:default-branch)
     on_default=false
     git merge-base --is-ancestor "${tag}" "origin/${default_branch}" 2>/dev/null && on_default=true
     if [[ "${version}" == *-* && "${on_default}" == true ]]
     then
-      release-tag:refuse "${tag} is a pre-release tag on ${default_branch}; tag a pre-release on a commit off it"
+      refuse-tag "${tag} is a pre-release tag on ${default_branch}; tag a pre-release on a commit off it"
     fi
     if [[ "${version}" != *-* && "${on_default}" == false ]]
     then
-      release-tag:refuse "${tag} is not on ${default_branch}; a release is tagged there, a pre-release has a suffix"
+      refuse-tag "${tag} is not on ${default_branch}; a release is tagged there, a pre-release has a suffix"
     fi
     ok "${tag} is a version tag on the right side of ${default_branch} (on it: ${on_default})"
     summary "✅ ${tag} is a version tag on the right side of ${default_branch}."
     ;;
   (pack)
     (( $# >= 1 && $# <= 2 )) || { usage; exit 2; }
-    version=$(release-tag:version "$1")
+    version=$(tag-version "$1")
     into=${2:-.}
     staging=$(mktemp -d)
     # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
@@ -85,7 +87,7 @@ case "${verb}" in
   (publish)
     (( $# == 1 )) || { usage; exit 2; }
     tag=$1
-    version=$(release-tag:version "${tag}")
+    version=$(tag-version "${tag}")
     guard:require tool:gh
     into=$(mktemp -d)
     # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
diff --git a/bin/release.sh b/bin/release.sh
index 2aa7c3b..d2378a4 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -30,7 +30,8 @@ release:version() {
   cat "${kit_root}/version" 2>/dev/null || release:unreleased
 }
 
-# release:bases prints the destinations a module may deliver to, the subdirectories of files/ and templates/.
+# release:bases prints the destinations a module may deliver to: the subdirectories of files/, templates/, and
+# regions/.
 release:bases() { printf 'repo\nhome\n'; }
 
 # release:base-root <base> prints the directory the base's files are mirrored at: the repository root, which the
@@ -196,7 +197,8 @@ release:validate() {
     case "${key}" in
       (description | default | depends | answers) ;;
       (*)
-        error "$(release:meta "${root}" "${module}") has a key the kit does not know: ${key} (see modules/module.schema.json)"
+        error "$(release:meta "${root}" "${module}") has a key the kit does not know: ${key}" \
+          "(see modules/module.schema.json)"
         return 1
     esac
   done
@@ -296,7 +298,8 @@ release:render() {
       do
         if [[ -z "${answer[${key}]+x}" ]]
         then
-          error "${rel} needs an answer for '${key}'; add '${key}: <value>' under answers: in .kit/settings.yml (module ${module})"
+          error "${rel} needs an answer for '${key}'; add '${key}: <value>' under answers: in .kit/settings.yml" \
+            "(module ${module})"
           return 1
         fi
         text=${text//"@${key}@"/"${answer[${key}]}"}
@@ -344,6 +347,37 @@ release:render-all() {
   for base in $(release:bases)
   do
     release:delivered "${root}" "${base}" "$@" >/dev/null || return 1
+    release:regions-apart "${root}" "${base}" "$@" || return 1
+  done
+}
+
+# release:regions-apart <root> <base> <module>… refuses a region path two of the modules both deliver, since one
+# file holds one kit region, and a region in a file whose comment syntax the kit does not know.
+release:regions-apart() {
+  local root=$1 base=$2 module home file rel owner
+  shift 2
+  local -A owner_of=()
+  for module in "$@"
+  do
+    home=$(release:home "${root}" "${module}")
+    [[ -d "${home}/modules/${module}/regions/${base}" ]] || continue
+    while IFS= read -r file
+    do
+      rel=${file#"${home}/modules/${module}/regions/${base}/"}
+      if ! release:region-known "${rel}"
+      then
+        error "modules/${module}/regions/${base}/${rel}: the kit knows no comment syntax for that kind of file," \
+          "so it cannot mark a region there"
+        return 1
+      fi
+      owner=${owner_of[${rel}]:-}
+      if [[ -n "${owner}" ]]
+      then
+        error "modules ${owner} and ${module} both deliver a region to ${rel}; one file holds one kit region"
+        return 1
+      fi
+      owner_of[${rel}]=${module}
+    done < <(find "${home}/modules/${module}/regions/${base}" -type f)
   done
 }
 
@@ -363,29 +397,73 @@ release:layers() {
   return 0
 }
 
-# release:kind <source> <path> prints how the content is placed: merge for a .json destination, region for a
-# source under a module's regions/, copy otherwise.
+# release:kind <source> <path> prints how the content is placed: region for a source under a module's
+# regions/<base>/, merge for a .json destination, copy otherwise. A source is a region by its last modules/
+# segment, so a checkout under a directory named modules reads the same as one anywhere else.
 release:kind() {
-  if release:merged "$2"
-  then printf 'merge\n'
-  elif [[ "$1" == */modules/*/regions/* ]]
+  if [[ "${1##*/modules/}" =~ ^[^/]+/regions/(repo|home)/ ]]
   then printf 'region\n'
+  elif release:merged "$2"
+  then printf 'merge\n'
   else printf 'copy\n'
   fi
 }
 
 # release:region-module <source> prints the module a region source belongs to, which names its markers.
 release:region-module() {
-  local rest=${1#*/modules/}
+  local rest=${1##*/modules/}
   printf '%s\n' "${rest%%/*}"
 }
 
-# release:region-markers <path> <module> prints the region's two marker lines, in the file's own comment
-# syntax: an HTML comment for markdown, a hash comment otherwise.
+# release:region-markers <path> <module> prints the region's two marker lines in the file's own comment syntax,
+# by its extension: an HTML comment, a double slash, a double dash, or a hash. A kind of file with no comment
+# syntax the kit knows is refused where the module is read, in release:render-all.
 release:region-markers() {
-  if [[ "$1" == *.md ]]
-  then printf '<!-- kit:begin %s -->\n<!-- kit:end %s -->\n' "$2" "$2"
-  else printf '# kit:begin %s\n# kit:end %s\n' "$2" "$2"
+  local open close
+  case "${1##*.}" in
+    (md | markdown | html | htm | xml | svg) open='<!-- ' close=' -->' ;;
+    (js | mjs | cjs | ts | tsx | jsx | go | rs | c | h | cc | cpp | hpp | java | kt | swift | cs | scala)
+      open='// ' close='' ;;
+    (sql | lua | hs) open='-- ' close='' ;;
+    (*) open='# ' close='' ;;
+  esac
+  printf '%skit:begin %s%s\n%skit:end %s%s\n' "${open}" "$2" "${close}" "${open}" "$2" "${close}"
+}
+
+# release:region-known <path> is true where the kit knows the file's comment syntax, so a region can be marked.
+release:region-known() {
+  case "${1##*/}" in
+    (*.json | *.jsonc | *.json5) return 1 ;;
+    (*.*) case "${1##*.}" in
+      (md | markdown | html | htm | xml | svg | js | mjs | cjs | ts | tsx | jsx | go | rs | c | h | cc | cpp | hpp \
+        | java | kt | swift | cs | scala | sql | lua | hs | sh | bash | zsh | yml | yaml | toml | ini | cfg | conf \
+        | py | rb | pl | txt | gitignore | gitattributes | editorconfig | env | just | mk | Makefile) return 0 ;;
+      (*) return 1 ;;
+    esac ;;
+    (*) return 0 ;;
+  esac
+}
+
+# release:target <path> prints the file a write to <path> lands in: the path, or what a symlink there points at,
+# so a repository that keeps AGENTS.md or a settings file as a link into another directory keeps its link.
+release:target() {
+  if [[ -L "$1" ]]
+  then readlink -f "$1"
+  else printf '%s\n' "$1"
+  fi
+}
+
+# release:region-has <path> <module> is true when the file carries the region's begin marker; a begin marker
+# with no end marker is refused, naming the file, since a write would drop everything after it.
+release:region-has() {
+  local path=$1 begin end
+  [[ -f "${path}" ]] || return 1
+  { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
+  grep --quiet --line-regexp --fixed-strings "${begin}" "${path}" || return 1
+  if ! grep --quiet --line-regexp --fixed-strings "${end}" "${path}"
+  then
+    error "${path}: the kit's region opens with '${begin}' and never closes; add '${end}' where it ends"
+    return 2
   fi
 }
 
@@ -393,19 +471,21 @@ release:region-markers() {
 # file or the region is absent.
 release:region-read() {
   local path=$1 begin end
-  [[ -f "${path}" ]] || return 1
+  release:region-has "$1" "$2" || return $?
   { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
-  grep --quiet --line-regexp --fixed-strings "${begin}" "${path}" || return 1
   awk -v b="${begin}" -v e="${end}" '$0 == e { on = 0 } on { print } $0 == b { on = 1 }' "${path}"
 }
 
 # release:region-write <path> <module> <content-file> replaces the region's content, appending the region after a
 # blank line where the file has none, and making the file where there is none.
 release:region-write() {
-  local path=$1 module=$2 content=$3 begin end
+  local path module=$2 content=$3 begin end status=0
+  path=$(release:target "$1")
   { read -r begin; read -r end; } < <(release:region-markers "${path}" "${module}")
   mkdir -p "$(dirname "${path}")"
-  if [[ -f "${path}" ]] && grep --quiet --line-regexp --fixed-strings "${begin}" "${path}"
+  release:region-has "${path}" "${module}" || status=$?
+  (( status == 2 )) && return 1
+  if (( status == 0 ))
   then
     awk -v b="${begin}" -v e="${end}" -v c="${content}" '
       $0 == b { print; while ((getline line < c) > 0) print line; skip = 1; next }
@@ -430,16 +510,17 @@ release:region-write() {
 # release:region-remove <path> <module> takes the region and its markers out, and the blank line before it;
 # a file left empty is removed.
 release:region-remove() {
-  local path=$1 begin end
+  local path begin end
+  path=$(release:target "$1")
   [[ -f "${path}" ]] || return 0
   { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
   awk -v b="${begin}" -v e="${end}" '
     $0 == b { skip = 1; held = 0; next }
     $0 == e { skip = 0; next }
     skip { next }
-    held { print ""; held = 0 }
+    held && printed { print ""; held = 0 }
     $0 == "" { held = 1; next }
-    { print }' "${path}" > "${path}.kit-new"
+    { print; printed = 1 }' "${path}" > "${path}.kit-new"
   if [[ -s "${path}.kit-new" ]]
   then mv "${path}.kit-new" "${path}"
   else rm -f "${path}.kit-new" "${path}"
@@ -455,7 +536,8 @@ release:delivered() {
   do
     (cd "${layer}" && find . \( -type f -o -type l \) | sed 's@^\./@@' \
       | awk -v l="${layer}" '{ print $0 "\t" l "/" $0 }')
-  done < <(release:layers "$@") | awk -F '\t' '{ src[$1] = $2 } END { for (p in src) print p "\t" src[p] }' | LC_ALL=C sort \
+  done < <(release:layers "$@") | awk -F '\t' '{ src[$1] = $2 } END { for (p in src) print p "\t" src[p] }' \
+    | LC_ALL=C sort \
     | while IFS=$'\t' read -r path src
   do
     if [[ -L "${src}" && ! -e "${src}" ]]
@@ -573,7 +655,8 @@ release_jq='
 # release:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if
 # missing.
 release:json-write() {
-  local path=$1 filter=$2
+  local path filter=$2
+  path=$(release:target "$1")
   shift 2
   mkdir -p "$(dirname "${path}")"
   [[ -f "${path}" ]] || printf '{}\n' > "${path}"
@@ -609,6 +692,7 @@ release:place() {
       release:region-write "${path}" "$(release:region-module "${src}")" "${src}"
       ;;
     (*)
+      path=$(release:target "${path}")
       mkdir -p "$(dirname "${path}")"
       cp "${src}" "${path}.kit-new"
       mv "${path}.kit-new" "${path}"
@@ -641,6 +725,11 @@ release:holds() {
 release:place-new() {
   local src=$1 path=$2 label=${3:-} kind
   kind=$(release:kind "${src}" "${path}")
+  if [[ -e "${path}" && ! -f "${path}" ]]
+  then
+    error "${path}: a directory, or something that is not a file, is there; move it aside"
+    return 1
+  fi
   if [[ "${kind}" == merge || ! -f "${path}" ]] \
     || { [[ "${kind}" == region ]] && ! release:installed "${src}" "${path}" >/dev/null; }
   then
diff --git a/bin/status.sh b/bin/status.sh
index 13c180a..b755449 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -12,7 +12,8 @@
 # owes a decision, blue when the next move is a machine's or a reviewer's, dim for detail. The states, in the
 # order the first that holds wins:
 #
-#   draft 🔨, queued 🚦, conflicted 💥, failing:gate 🔥, no-check 📭, comments:open 💬, blocked:approval 👀,
+#   draft 🔨, queued 🚦, conflicted 💥, failing:gate 🔥, no-check 📭, comments:open 💬,
+#   blocked:approval 👀,
 #   ready 🛬
 #
 # --json prints the same facts as one document: {desk, worktrees, pullRequests, goneBranches}.
diff --git a/bin/yaml.sh b/bin/yaml.sh
index f57052f..8df9822 100644
--- a/bin/yaml.sh
+++ b/bin/yaml.sh
@@ -2,8 +2,9 @@
 # yaml.sh - the subset of YAML the kit's own files are written in (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Two kinds of file are read here: a module's module.yml, and the frontmatter between the opening and closing `---`
-# of a rule file. Both are written in the same small subset, and one reader serves both so they cannot drift:
+# Three kinds of file are read here: a module's module.yml, the repository's .kit/settings.yml, and the
+# frontmatter between the opening and closing `---` of a rule file. All are written in the same small subset,
+# and one reader serves them so they cannot drift:
 #
 #   key: value          a scalar, quoted or not
 #   key:                a list, one `  - item` per line
@@ -24,7 +25,7 @@ yaml:value() {
 yaml:list() {
   yaml:read "$1" | awk -v key="$2" '
     $0 == key ":" { on = 1; next }
-    /^[A-Za-z]/ { on = 0 }
+    /^[A-Za-z0-9_-]/ { on = 0 }
     on && /^  - / { v = $0; sub(/^  - /, "", v); gsub(/^"|"$/, "", v); print v }'
 }
 
@@ -32,14 +33,15 @@ yaml:list() {
 yaml:map() {
   yaml:read "$1" | awk -v key="$2" '
     $0 == key ":" { on = 1; next }
-    /^[A-Za-z]/ { on = 0 }
-    on && /^  [A-Za-z_]+: / { n = $0; sub(/^  /, "", n); sub(/: .*$/, "", n); v = $0; sub(/^  [A-Za-z_]+: */, "", v);
+    /^[A-Za-z0-9_-]/ { on = 0 }
+    on && /^  [A-Za-z0-9_-]+: / {
+      n = $0; sub(/^  /, "", n); sub(/: .*$/, "", n); v = $0; sub(/^  [A-Za-z0-9_-]+: */, "", v);
       gsub(/^"|"$/, "", v); print n "\t" v }'
 }
 
 # yaml:keys <file> prints the top-level keys, one per line.
 yaml:keys() {
-  yaml:read "$1" | awk '/^[A-Za-z_]+:/ { k = $0; sub(/:.*$/, "", k); print k }'
+  yaml:read "$1" | awk '/^[A-Za-z0-9_-]+:/ { k = $0; sub(/:.*$/, "", k); print k }'
 }
 
 # yaml:read <file> prints the file's YAML: the frontmatter when the file opens with ---, the whole file otherwise.
diff --git a/docs/architecture.md b/docs/architecture.md
index f9e32a7..b92b349 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -14,18 +14,19 @@ A release is one tarball, `kit-<version>.tar.gz`, and its layout is the checkout
 beside it, and the verbs share bash modules loaded with `use`. The release workflow stamps the tag's version into
 a `version` file; a checkout has none and is `unreleased`.
 
-A module is a directory under `modules/`, and the directory names it. `module.yml` describes it: whether it is active
-by default, which modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the
-base's root; `templates/<base>/` is rendered first, every `@key@` replaced by an answer; `docs/` is packed with the
-release and placed in no repository. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
+A module is a directory under `modules/`, and the directory names it. `module.yml` describes it: whether it is active by
+default, which modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the
+base's root; `templates/<base>/` is rendered first, every `@key@` replaced by an answer; `regions/<base>/` holds what
+the kit owns inside a file the repository owns; `docs/` is packed with the release and placed in no repository. Two
+bases exist: `repo`, the repository root, and `home`, the user's `~`.
 
 The verbs are the only way content moves. `kit install` resolves the active set, `kit` plus those named plus their
 dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
 an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
 fails when a delivered file differs from the release's. `kit module` changes the active set. Three rules govern
-placement: a `.json` destination is merged by key, the kit owning only the entries it writes; a region is written
-between marker comments inside a file the repository owns, the kit holding only what is between them; everything
-else is a copy.
+placement: a `.json` destination, other than a schema, is merged by key, the kit owning only the entries it writes; a
+region is written between marker comments inside a file the repository owns, the kit holding only what is
+between them; everything else is a copy.
 
 Each base has a manifest: `.kit/manifest`, committed with the repository, and `~/.kit/manifest` on the desk when a
 module delivers there. A manifest records the version, the active modules, and the release's digest of every
@@ -35,15 +36,14 @@ delivered path, which is how `kit update` tells an edited file from an untouched
 
 ![Context: how any agent, and Claude Code's hook, find the rules that govern a file](context.svg)
 
-A rule is written once, in `.kit/rules/<kind>.md`, and copied into no harness's directory. Its frontmatter says
-what it governs: `paths:`, globs on the repository-relative path, and `content:`, patterns on the first line of a
-file that exists. `kit context <path>` names the rules governing a path and appends the ask to
-`.git/kit/context.log`. Every caller gets the same answer: an agent of any harness following the sentence in
-`.kit/1st.md`, a person at the shell, a tool reading `--json`, and Claude Code's `PreToolUse` hook, which the
-`claude` module wires to `kit context --claude` so the rules are named before every write. The call names and
-never quotes: reading the rule stays an act the caller takes, and the log of asks is the record of what was
-named. A rule also names its linter, and `kit lint` runs each rule's linter over the paths the rule governs, so
-the hook manager a repository uses, if any, only has to call the verb.
+A rule is written once, in `.kit/rules/<kind>.md`, and copied into no harness's directory. Its frontmatter says what it
+governs: `paths:`, globs on the repository-relative path, and `content:`, patterns on the first line of a file that
+exists. `kit context <path>` names the rules governing a path and appends the ask to `.git/kit/context.log`. Every
+caller gets the same answer: an agent of any harness following the sentence in `.kit/1st.md`, a person at the shell, a
+tool reading `--json`, and Claude Code's `PreToolUse` hook, which the `claude` module wires to `kit context --claude` so
+the rules are named before every write. The log of asks is the record of what was named. A rule also names its linter,
+and `kit lint` runs each rule's linter over the paths the rule governs, so the hook manager a repository uses, if any,
+only has to call the verb.
 
 ## The loop and the gate
 
@@ -51,22 +51,20 @@ the hook manager a repository uses, if any, only has to call the verb.
 
 The desk is the root checkout and belongs to the human; it usually has `main` checked out and may have any branch no
 worktree holds, and no agent changes it in place. Work starts from an issue: `kit issue <N>` makes
-`worktrees/<N>-<slug>`, a branch linked to the issue under Development, a signed start commit, and a draft pull
-request, and sweeps uncommitted work off the desk into the worktree, the one change it makes there, announced.
-Everything after that happens in the worktree: `kit context` before a change, `kit lint` for the pre-commit linters by
-hand, `kit rebase` to bring the branch onto `origin/main` and push it, and `gh pr ready` when the pull request body is
-the report.
+`worktrees/<N>-<slug>`, a branch linked to the issue, a start commit, and a draft pull request. It sweeps uncommitted
+work off the desk into the worktree, the one change it makes to the desk, and says so. Everything after that happens in
+the worktree: `kit context` before a change, `kit lint` for the pre-commit linters by hand, `kit rebase` to bring the
+branch onto the default branch at origin and push it, and `gh pr ready` when the pull request body is the report.
 
 Every call the loop makes to the forge, an issue's title, a branch linked to it, a pull request and its state,
 its checks and threads and linked issues, goes through one seam, `forge:` in `bin/forge.sh`, and a provider
 answers: `forge-github.sh` over `gh`, chosen by the `forge` setting or by origin's host. The core verbs never
 reach the seam, so a repository on no forge still installs, updates, checks, and runs `kit context`, and `gh` is
-the GitHub provider's requirement alone. A second forge is a second provider against the same names.
-
-The gate is `kit ci`, three checks that are each one kit command, run by the delivered GitHub Actions job for a
-pull request into the default branch, or by any pipeline. `kit gate` runs the repository's gate, the `gate`
-setting or the detected justfile recipe, Makefile target, or package.json script, and refuses when there is none,
-since a gate that cannot run clears nothing. `kit check` holds the delivered files to
+the GitHub provider's requirement alone.
+The delivered check is `kit ci`, three checks that are each one kit command, run by the delivered GitHub Actions
+job for a pull request into the default branch, or by any pipeline. `kit gate` runs the repository's own gate,
+the `gate` setting or the detected justfile recipe, Makefile target, or `package.json` script, and refuses when
+there is none, since a gate that cannot run clears nothing. `kit check` holds the delivered files to
 the release. `kit linked` refuses a pull request not linked to an open issue of the repository. A human merges, and
 `kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: the desk, every
 worktree with its commits past the fork, and every open pull request with its state, age, and checks.
@@ -78,7 +76,7 @@ worktree with its commits past the fork, and every open pull request with its st
 | A delivered file is the release's | `kit check`, in the gate and on a desk, against the release's files and the manifest's version |
 | A change has an issue | `kit linked` in the gate; `kit issue` makes the link when it starts the work |
 | The repository's own gate ran | `kit gate`, which refuses when there is no gate to run |
-| All three held, wherever CI runs | `kit ci`, the three checks as one verb, every one reported |
+| All three held, wherever CI runs | `kit ci`, the delivered check, the three as one verb, every one reported |
 | A file's rules were named to the agent | the Claude Code hook; `kit context` in every other harness |
 | A file's rules were asked for | `.git/kit/context.log`, one line per ask |
 | A file keeps its rule's mechanical part | `kit lint`, each rule's own linter over the paths it governs |
diff --git a/docs/context.md b/docs/context.md
index 7c0c7e8..90fac8a 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -12,7 +12,7 @@ is appended to `.git/kit/context.log`, one line of epoch and path per ask.
 
 ## How a rule declares what it governs
 
-A rule file opens with a frontmatter of two optional lists:
+A rule file opens with a frontmatter of two optional lists and one optional command:
 
 ```yaml
 ---
@@ -54,7 +54,7 @@ naming the rules and never quoting them, so reading a rule stays an act the agen
   "additionalContext": "kit: lib/run.sh is governed by .kit/rules/bash.md; read it before this change."}}
 ```
 
-No state is kept between calls.
+Nothing is kept between calls but the log line.
 
 A harness with no hook, and a person, use the plain call. `.kit/1st.md` names it as the step before any file is
 created or changed.
diff --git a/docs/context.svg b/docs/context.svg
index a5e83e1..77aa820 100644
--- a/docs/context.svg
+++ b/docs/context.svg
@@ -64,7 +64,7 @@
   <rect class="box" x="716" y="220" width="300" height="90" fill="#fef9c3"/>
   <text class="h" x="732" y="248">The record</text>
   <text class="m" x="732" y="272">.git/kit/context.log</text>
-  <text class="d" x="732" y="294">epoch and path per ask: the evidence a check reads</text>
+  <text class="d" x="732" y="294">epoch and path per ask: the record of what was named</text>
 
   <!-- answers -->
   <rect class="box" x="716" y="340" width="300" height="76" fill="#ffffff"/>
diff --git a/docs/delivery.svg b/docs/delivery.svg
index 3a122a0..45b7094 100644
--- a/docs/delivery.svg
+++ b/docs/delivery.svg
@@ -41,11 +41,11 @@
   <text class="m" x="68" y="346">files/home/</text>
   <text class="d" x="180" y="346">mirrored at ~</text>
   <text class="m" x="68" y="370">templates/&lt;base&gt;/</text>
-  <text class="d" x="180" y="386">@key@ rendered; regions/ into a file</text>
+  <text class="d" x="180" y="386">@key@ rendered; regions/&lt;base&gt;/</text>
   <text class="m" x="68" y="412">docs/</text>
-  <text class="d" x="180" y="412">not delivered</text>
-  <text class="d" x="52" y="446">kit, lefthook, ci are default;</text>
-  <text class="d" x="52" y="462">claude is named; each may depend</text>
+  <text class="d" x="180" y="412">packed, placed nowhere</text>
+  <text class="d" x="52" y="446">kit is default; ci-github, lefthook,</text>
+  <text class="d" x="52" y="462">and claude are named; each may depend</text>
   <text class="d" x="52" y="478">on others, resolved at install.</text>
   <text class="m" x="52" y="500">version</text>
   <text class="d" x="140" y="500">stamped by the release workflow</text>
@@ -74,6 +74,7 @@
   <text class="m" x="732" y="160">.kit/lefthook.yml</text>
   <text class="m" x="732" y="182">.github/workflows/kit-ci.yml</text>
   <text class="m" x="732" y="204">.claude/CLAUDE.md</text>
+  <text class="d" x="912" y="204">region</text>
   <text class="m" x="732" y="226">.claude/settings.json</text>
   <text class="d" x="912" y="226">merged</text>
   <line x1="732" y1="244" x2="1000" y2="244" stroke="#4ade80" stroke-width="1"/>
@@ -81,8 +82,8 @@
   <text class="d" x="856" y="268">version, modules, digests</text>
   <text class="m" x="732" y="290">.kit/settings.yml</text>
   <text class="d" x="856" y="290">yours, never written</text>
-  <text class="m" x="732" y="312">AGENTS.md</text>
-  <text class="d" x="856" y="312">yours; names .kit/1st.md</text>
+  <text class="m" x="732" y="312">AGENTS.md .gitignore</text>
+  <text class="d" x="912" y="312">regions</text>
 
   <!-- home -->
   <rect class="box" x="716" y="380" width="300" height="140" fill="#fef9c3"/>
@@ -91,7 +92,7 @@
   <text class="m" x="732" y="436">~/.kit/manifest</text>
   <text class="d" x="732" y="456">the desk's record, not the repository's;</text>
   <text class="d" x="732" y="472">a runner has none, and kit check says so.</text>
-  <text class="d" x="732" y="500">No module delivers here yet.</text>
+  <text class="d" x="732" y="500">No module in this release delivers here.</text>
 
   <!-- edges -->
   <path class="edge" d="M 324 280 L 376 280"/>
diff --git a/docs/loop.svg b/docs/loop.svg
index bcdd950..4a62480 100644
--- a/docs/loop.svg
+++ b/docs/loop.svg
@@ -48,15 +48,15 @@
   <text class="m" x="396" y="212">kit lint</text>
   <text class="d" x="560" y="212">the hook by hand</text>
   <text class="m" x="396" y="234">kit rebase</text>
-  <text class="d" x="560" y="234">onto origin/main, pushed</text>
+  <text class="d" x="560" y="234">onto the default branch, pushed</text>
   <text class="m" x="396" y="256">gh pr ready</text>
   <text class="d" x="560" y="256">the body is the report</text>
   <text class="d" x="396" y="280">Signed commits, subject #&lt;N&gt; &lt;area&gt;: &lt;subject&gt;.</text>
 
   <!-- gate -->
   <rect class="box" x="736" y="40" width="280" height="250" fill="#ede9fe"/>
-  <text class="h" x="752" y="68">The gate: kit ci</text>
-  <text class="d" x="752" y="92">The delivered CI job, on every pull request:</text>
+  <text class="h" x="752" y="68">The check: kit ci</text>
+  <text class="d" x="752" y="92">The delivered job, on a pull request into main:</text>
   <text class="m" x="752" y="118">kit gate</text>
   <text class="d" x="752" y="136">the gate setting, or the one detected</text>
   <text class="m" x="752" y="162">kit check</text>
@@ -78,8 +78,8 @@
   <!-- harness guards -->
   <rect class="box" x="736" y="340" width="280" height="120" fill="#e0f2fe"/>
   <text class="h" x="752" y="368">The harness adapter</text>
-  <text class="d" x="752" y="392">Deny list: git rebase, push --force, reset --hard,</text>
-  <text class="d" x="752" y="408">checkout main, worktree remove --force.</text>
+  <text class="d" x="752" y="392">Deny list: the raw git spellings .kit/1st.md</text>
+  <text class="d" x="752" y="408">forbids, rebase, push --force, and the rest.</text>
   <text class="d" x="752" y="432">Hook: kit context before every write.</text>
   <text class="d" x="752" y="448">Nothing copied from the rules.</text>
 
diff --git a/docs/modules.md b/docs/modules.md
index 047f3f2..3862a61 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -44,14 +44,14 @@ answers:
 | Key | Meaning |
 | --- | --- |
 | `description` | One line, shown by `kit module list`. |
-| `default` | `true` for a module active unless removed. In this release, `kit` alone. |
+| `default` | `true` for a module active unless removed: `kit`. |
 | `depends` | Modules activated with this one. `kit module remove` refuses a module another active module depends on. |
-| `answers` | The default value of each template key. A repository overrides one in `.kit/answers`. |
+| `answers` | The default value of each template key. A repository overrides one under `answers:` in `.kit/settings.yml`. |
 
-[module.schema.json](../modules/module.schema.json) is the schema, JSON Schema 2020-12. The gate validates every
-`module.yml` against it with `ajv`, and `kit install` holds a module to the same contract where no validator is:
-a key it does not know, a `default` that is not `true` or `false`, or a dependency the release lacks is refused,
-naming it.
+[module.schema.json](../modules/module.schema.json) is the schema, JSON Schema 2020-12. This repository's gate validates
+every `module.yml` against it with `ajv`, and `kit install` holds a module to the same contract where no validator is: a
+key it does not know, a `default` that is not `true` or `false`, or a dependency the release lacks is refused, naming
+it.
 
 ## Delivery
 
@@ -75,8 +75,8 @@ bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may car
 answers live under `answers:` in `.kit/settings.yml`; a key with none there takes the module's default under its
 own `answers`, and a key with neither refuses the install, naming the key and the module.
 
-The same YAML subset is what a rule's frontmatter is written in, read by `bin/yaml.sh` in both places, so a rule's
-`paths:` and `content:` lists and a module's `depends:` list have one reader between them.
+The same YAML subset is what a rule's frontmatter and `.kit/settings.yml` are written in, read by `bin/yaml.sh` in
+all three places, so a rule's lists, a module's `depends:`, and the settings have one reader among them.
 
 ## Settings
 
@@ -93,7 +93,7 @@ answers:
 
 | Key | Meaning |
 | --- | --- |
-| `forge` | The provider the loop's verbs use, `github` in this release; detected from origin's host when absent. |
+| `forge` | The provider the loop's verbs use, `github`; detected from origin's host when absent. |
 | `gate` | What `kit gate` runs; a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script is detected when absent. |
 | `require_signing` | `true` makes `kit issue` refuse a desk without a signing key. |
 | `answers` | The values a module's templates take, overriding the module's own defaults. |
@@ -101,11 +101,12 @@ answers:
 ## Modules a repository defines
 
 A directory `.kit/modules/<name>/` in the repository is a module in every respect: `module.yml`, `files/<base>/`,
-`templates/<base>/`, and `docs/`. A name is looked up in the release first, then there. It is validated like a
-delivered module, may depend on delivered ones, is activated with `kit install <name>` or `kit module add <name>`,
-and `kit module list` shows it with its origin. Its paths are recorded in the manifest with their digests, so
-`kit check` tells an edited installed copy from its source, and `kit update` treats the module itself as its own
-base. A rule file it places under `.kit/rules/` is found by `kit context` like any other.
+`templates/<base>/`, `regions/<base>/`, and `docs/`. A name is looked up in the release first, then there. It is
+validated like a delivered module, may depend on delivered ones, is activated with `kit install <name>` or `kit module
+add <name>`, and `kit module list` shows it with its origin. Its paths are recorded in the manifest with their digests,
+so `kit check` tells an edited installed copy from its source, and on update its files are compared with its own current
+source, so an edit under `.kit/modules/` is never merged against a release. A rule file it places under `.kit/rules/` is
+found by `kit context` like any other.
 
 ## Activation
 
diff --git a/justfile b/justfile
index f086e2d..227fc59 100644
--- a/justfile
+++ b/justfile
@@ -7,14 +7,14 @@
 set dotenv-load := true
 set positional-arguments := true
 
-# A bash recipe body is hosted by the interpreter named here and marked [script], not by a shebang: a shebang
-# recipe is exec'd from a temp executable and costs more per invocation than `bash <file>`. The interpreter is
-# named bare so it resolves through the PATH built below, and the pinned bash wins over the system's.
+# A bash recipe body is hosted by the interpreter named here and marked [script], as the just rule asks. The
+# interpreter is named bare so it resolves through the PATH built below; bash comes from the machine, 4.4 or
+# later, as the kit itself requires.
 set script-interpreter := ['bash']
 
 # The mise-pinned toolchain's bin directories go first on PATH once, at parse time, so every recipe calls its
-# tools bare and the pinned tool wins over any Homebrew or system copy: the same directories mise-action puts on
-# the runner's PATH, so a desk and the runner cannot disagree about which tool ran. Idempotent by inspecting
+# tools bare and the pinned tool wins over any other copy: the same directories mise-action puts on the
+# runner's PATH, so a desk and the runner cannot disagree about which tool ran. Idempotent by inspecting
 # PATH rather than a sentinel, so a nested just adds nothing.
 export PATH := ```
   mise bin-paths 2>/dev/null | while IFS= read -r d
@@ -73,6 +73,7 @@ refresh:
   "${index}/bin/kit" update >/dev/null
   readarray -t after < <(paths)
   git add --all -- "${before[@]}" "${after[@]}" .kit/manifest
-  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, modules $(sed -n 's/^modules *//p' .kit/manifest)"
+  modules=$(sed -n 's/^modules *//p' .kit/manifest)
+  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, modules ${modules}"
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/mise.toml b/mise.toml
index 6a3b9e5..5757ed2 100644
--- a/mise.toml
+++ b/mise.toml
@@ -2,7 +2,7 @@
 #
 # mise reads this file always, mise.desk.toml on top of it when MISE_ENV=desk, which a desk exports in its shell
 # profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in the file of whoever runs
-# it; today Lefthook is a desk's alone, and nothing is the runner's alone. `lockfile = true` records each pin's
+# it; Lefthook is a desk's alone, and nothing is the runner's alone. `lockfile = true` records each pin's
 # exact resolution in a lock beside its file. git and bash come from the machine.
 
 [settings]
diff --git a/modules/ci-github/docs/README.md b/modules/ci-github/docs/README.md
index c1c7a4c..8ac1bf4 100644
--- a/modules/ci-github/docs/README.md
+++ b/modules/ci-github/docs/README.md
@@ -1,8 +1,8 @@
 # The ci-github module
 
-Places `.github/workflows/kit-ci.yml`: one GitHub Actions job, `CI`, run for a pull request into the default
-branch. It puts `kit` on `PATH`, from this checkout where `.kit/manifest` says `unreleased` and from the release
-the manifest names otherwise, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported.
+Places `.github/workflows/kit-ci.yml`: one GitHub Actions job, `CI`, run for a pull request into the default branch. It
+puts `kit` on `PATH`, from the kit's own checkout where `.kit/manifest` says `unreleased` and from the release the
+manifest names otherwise, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported.
 
 mise is used only where the repository has a `mise.toml`. A repository that pins its tools another way gives the
 gate its tools its own way, and a repository on another CI calls `kit ci` from its own pipeline.
diff --git a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
index 33c275e..21992c0 100644
--- a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
@@ -1,4 +1,4 @@
-# kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request
+# kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request into the default branch
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
@@ -30,9 +30,11 @@ jobs:
       # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
       MISE_ENV: ci
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - name: checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
+      - name: tools-from-mise
+        uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
         if: ${{ hashFiles('mise.toml') != '' }}
 
       - name: kit-on-path
@@ -40,13 +42,17 @@ jobs:
           set -o errexit -o nounset -o pipefail
           if [[ ! -f .kit/manifest ]]
           then
-            echo '::error::run kit install and commit what it writes; this repository has no .kit/manifest to name a release'
+            echo '::error::run kit install and commit what it writes; this repository has no .kit/manifest'
             exit 1
           fi
           version=$(sed -n 's/^version //p' .kit/manifest)
           if [[ "${version}" == unreleased && -x bin/kit ]]
           then
             printf '%s/bin\n' "${PWD}" >> "${GITHUB_PATH}"
+          elif [[ "${version}" == unreleased ]]
+          then
+            echo '::error::.kit/manifest says unreleased and there is no bin/kit; pin a release and run kit update'
+            exit 1
           elif ! command -v kit >/dev/null
           then
             mkdir -p "${RUNNER_TEMP}/kit"
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index 78fd4ee..8282424 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -10,9 +10,10 @@ the region. It also merges into
 
 - `permissions.deny`: the spellings `.kit/1st.md` forbids an agent, `git rebase`, `git worktree add`,
   `git checkout -b`, `git switch -c`, `git worktree remove`, `git branch -D`, `git checkout main`,
-  `git switch main`, `git reset --hard`, and `git push --force`, which the kit's verbs and the loop replace.
-- `hooks.PreToolUse`: on `Write`, `Edit`, and `MultiEdit`, `kit context --claude`, which puts the rules governing
-  the file before the agent, described in [docs/context.md](../../../docs/context.md).
+  `git switch main`, `git reset --hard`, `git push --force`, and `git push -f`, which the kit's verbs and the
+  loop replace.
+- `hooks.PreToolUse`: on `Write`, `Edit`, and `MultiEdit`, `kit context --claude`, which puts the rules governing the
+  file before the agent, described in [docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md).
 
-It copies no rule. `.claude/rules/` is the repository's own. `AGENTS.md` carries no `@` import of Claude's, since
-every harness reads it.
+`.claude/rules/` is the repository's own, and `AGENTS.md` carries no `@` import of Claude's, since every harness
+reads it.
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
index 3796cbc..5728379 100644
--- a/modules/kit/docs/README.md
+++ b/modules/kit/docs/README.md
@@ -8,6 +8,6 @@ The core, active in every repository that takes the kit. It places:
 - A region in `AGENTS.md`, the sentence that sends every agent to `.kit/1st.md`, and a region in `.gitignore`,
   the `/worktrees/` entry the loop needs; the rest of each file is the repository's.
 
-The rules are discovered through `kit context <path>`, described in [docs/context.md](../../../docs/context.md),
-and copied into no harness's directory. Adding a kind is adding one rule file here and one row to the table in
-`1st.md`; every harness and every person finds it the same way.
+The rules are discovered through `kit context`, described in
+[docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md). Adding a kind is adding one rule
+file here and one row to the table in `1st.md`.
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 7ba6b5f..c7e65ce 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -12,7 +12,8 @@ the repository's own rules in `AGENTS.md` bind beside it. Where the two differ,
 3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
 4. Being wrong is recoverable. Misreporting is not.
 5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
-   written into a rule file or `AGENTS.md` through the loop, where every agent and every person reads it.
+   written, through the loop, into `AGENTS.md`, a module of the repository's own under `.kit/modules/`, or a kit
+   release, where every agent and every person reads it.
 
 ## The root checkout is the human's desk
 
@@ -94,11 +95,12 @@ carries the machinery, reached through the `kit` command on `PATH`: the loop's c
 `kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
 delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
-lives under `.kit/modules/` and is taken the same way. A `.json` destination is merged by key, the kit owning
-only the entries it writes; everything else is copied as it is.
+lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
+key, the kit owning only the entries it writes; a region is held between its markers inside a file the
+repository owns; everything else is copied as it is.
 
-- `kit`: this file and the rules, discovered through `kit context`; the sentence in `AGENTS.md` that points here
-  and the `/worktrees/` entry in `.gitignore`, each a region the kit owns inside a file the repository owns.
+- `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
+  `.gitignore`, each a region the kit owns inside a file the repository owns.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/modules/kit/files/repo/.kit/markdownlint.jsonc b/modules/kit/files/repo/.kit/markdownlint.jsonc
new file mode 100644
index 0000000..7d880aa
--- /dev/null
+++ b/modules/kit/files/repo/.kit/markdownlint.jsonc
@@ -0,0 +1,20 @@
+// .kit/markdownlint.jsonc - the markdownlint configuration the markdown rule's linter reads
+// ----------------------------------------------------------------------------------------------------------------------
+// Delivered by kit, not edited by hand. A change is a new release, then kit update. The markdown rule, .kit/rules/markdown.md,
+// is the convention; each setting here is one of its lines the linter can hold.
+
+{
+  // MD003 heading-style: ATX headings, the rule's §Layout 5.
+  "MD003": { "style": "atx" },
+
+  // MD013 line-length: prose wraps at 118, 120 being the ceiling; code and tables do not wrap (§Layout 1 and 3).
+  "MD013": { "line_length": 120, "code_blocks": false, "tables": false },
+
+  // MD041 first-line-heading: a delivered file opens with its notice, AGENTS.md with the sentence a harness reads
+  // first (§Layout 5).
+  "MD041": false,
+
+  // MD060 table-column-style: tables use " | " with spaces around each pipe (§Layout 7); the check is stricter
+  // than the rule and is off.
+  "MD060": false
+}
diff --git a/modules/kit/files/repo/.kit/rules/gitignore.md b/modules/kit/files/repo/.kit/rules/gitignore.md
index f1278c4..2712da0 100644
--- a/modules/kit/files/repo/.kit/rules/gitignore.md
+++ b/modules/kit/files/repo/.kit/rules/gitignore.md
@@ -10,8 +10,9 @@ Applies to `.gitignore` at any depth.
 
 ## Shape
 
-1. The file opens with `# .gitignore - untracked files and folders`, a rule of dashes to column 120, and a
-   blank line.
+1. A file the repository writes opens with `# .gitignore - untracked files and folders`, a rule of dashes to
+   column 120, and a blank line. One the kit made of its region alone is the kit's until the repository adds
+   to it.
 2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
    line.
 3. The file closes with a rule of dashes.
diff --git a/modules/kit/files/repo/.kit/rules/markdown.md b/modules/kit/files/repo/.kit/rules/markdown.md
index 73b95ca..4feb54c 100644
--- a/modules/kit/files/repo/.kit/rules/markdown.md
+++ b/modules/kit/files/repo/.kit/rules/markdown.md
@@ -2,7 +2,7 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 paths:
   - "**/*.md"
-lint: markdownlint-cli2
+lint: markdownlint-cli2 --config .kit/markdownlint.jsonc
 ---
 # Markdown
 
diff --git a/modules/kit/files/repo/.kit/rules/workflows.md b/modules/kit/files/repo/.kit/rules/workflows.md
index 37fb51f..4d02c2b 100644
--- a/modules/kit/files/repo/.kit/rules/workflows.md
+++ b/modules/kit/files/repo/.kit/rules/workflows.md
@@ -27,4 +27,6 @@ Applies to GitHub Actions workflows, under `.github/workflows/`. The YAML rule a
    also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
 5. A step whose verdict a reader looks for writes one `✅` line to the summary.
 6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step.
+7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step. The one
+   exception is the kit itself, which the delivered job fetches from the release `.kit/manifest` names, since
+   nothing else can put it there first.
diff --git a/modules/kit/files/repo/.kit/settings.schema.json b/modules/kit/files/repo/.kit/settings.schema.json
index 84689ee..8a334ae 100644
--- a/modules/kit/files/repo/.kit/settings.schema.json
+++ b/modules/kit/files/repo/.kit/settings.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
   "title": ".kit/settings.yml",
-  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; https://github.com/empowerite/kit/blob/main/docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
   "type": "object",
   "additionalProperties": false,
   "properties": {
diff --git a/tests/ci.bats b/tests/ci.bats
index 8d63fac..4c7166c 100644
--- a/tests/ci.bats
+++ b/tests/ci.bats
@@ -12,6 +12,7 @@ setup() {
   cd "${repo}"
   git init --quiet --initial-branch=main
   git remote add origin https://github.com/empowerite/example.git
+  export GITHUB_STEP_SUMMARY="${BATS_TEST_TMPDIR}/summary.md"
   "${kit_checkout}/bin/kit" install >/dev/null
 }
 
diff --git a/tests/forge.bats b/tests/forge.bats
index 61d6c8f..e6d0ee3 100644
--- a/tests/forge.bats
+++ b/tests/forge.bats
@@ -35,7 +35,8 @@ provider() {
   git remote add origin https://gitlab.com/empowerite/kit.git
   run provider
   [ "$status" -eq 1 ]
-  [[ "$output" == *"set forge in .kit/settings.yml; origin's host 'gitlab.com' names no forge the kit knows (github)"* ]]
+  [[ "$output" == *"set forge in .kit/settings.yml; origin's host 'gitlab.com' names no forge the kit knows"* ]]
+  [[ "$output" == *"(github)"* ]]
   git remote remove origin
   run provider
   [ "$status" -eq 1 ]
diff --git a/tests/gate.bats b/tests/gate.bats
index 02da5a1..22b5484 100644
--- a/tests/gate.bats
+++ b/tests/gate.bats
@@ -63,7 +63,9 @@ teardown() {
   grep --quiet 'gate passed' summary.md
   printf 'ci:\n  exit 3\n' > justfile
   run "${kit_checkout}/bin/kit" gate
-  [ "$status" -ne 0 ]
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"the gate failed: just ci"* ]]
+  grep --quiet 'gate failed' summary.md
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 11ba72f..805e76e 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -162,7 +162,7 @@ later-release() {
   [ "$(cat "${KIT_HOME}/.kit/claude")" = "user level" ]
   grep --quiet '^version 9.9.9$' "${KIT_HOME}/.kit/manifest"
   grep --quiet '  .kit/claude$' "${KIT_HOME}/.kit/manifest"
-  grep --quiet --invert-match 'claude$' .kit/manifest
+  ! grep --quiet 'claude$' .kit/manifest
   run "${repo}.later/bin/kit" check
   [ "$status" -eq 0 ]
   printf 'edited\n' >> "${KIT_HOME}/.kit/claude"
@@ -189,7 +189,8 @@ later-release() {
   mkdir -p .kit/modules/python/files/repo/.kit/rules .kit/modules/python/templates/repo
   printf 'description: "The Python rule and the tool pins"\ndepends:\n  - kit\nanswers:\n  python: "3.13"\n' \
     > .kit/modules/python/module.yml
-  printf -- '---\npaths:\n  - "**/*.py"\n---\n# Python\n\nType everything.\n' > .kit/modules/python/files/repo/.kit/rules/python.md
+  printf -- '---\npaths:\n  - "**/*.py"\n---\n# Python\n\nType everything.\n' \
+    > .kit/modules/python/files/repo/.kit/rules/python.md
   printf 'python @python@\n' > .kit/modules/python/templates/repo/.python-version
   run "${kit_checkout}/bin/kit" install python
   [ "$status" -eq 0 ]
@@ -271,6 +272,45 @@ later-release() {
   [ "$(cat .gitignore)" = "build/" ]
 }
 
+@test "a symlinked destination keeps its link, and a directory at a destination is refused" {
+  mkdir docs && printf '# Ours\n' > docs/AGENTS.md && ln -s docs/AGENTS.md AGENTS.md
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ -L AGENTS.md ]
+  grep --quiet 'kit:begin kit' docs/AGENTS.md
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  run "${kit_checkout}/bin/kit" module remove kit
+  [ "$status" -eq 0 ]
+  mkdir -p .kit/1st.md
+  run "${kit_checkout}/bin/kit" module add kit
+  [ "$status" -eq 1 ]
+  [[ "$output" == *".kit/1st.md: a directory, or something that is not a file, is there"* ]]
+}
+
+@test "a region that opens and never closes is refused by name, and two modules cannot share a region's file" {
+  printf '<!-- kit:begin kit -->\nhalf\n' > AGENTS.md
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"AGENTS.md: the kit's region opens with '<!-- kit:begin kit -->' and never closes"* ]]
+  rm AGENTS.md
+  mkdir -p .kit/modules/extra/regions/repo
+  printf 'description: "x"\ndepends:\n  - kit\n' > .kit/modules/extra/module.yml
+  printf 'extra\n' > .kit/modules/extra/regions/repo/AGENTS.md
+  run "${kit_checkout}/bin/kit" install extra
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"modules kit and extra both deliver a region to AGENTS.md"* ]]
+  printf 'x = 1\n' > .kit/modules/extra/regions/repo/config.toml
+  rm .kit/modules/extra/regions/repo/AGENTS.md
+  run "${kit_checkout}/bin/kit" install extra
+  [ "$status" -eq 0 ]
+  [ "$(sed -n '1p' config.toml)" = "# kit:begin extra" ]
+  printf 'const x = 1;\n' > .kit/modules/extra/regions/repo/lib.js
+  run env PATH="$(shims mise curl)" "${kit_checkout}/bin/kit" update
+  [ "$status" -eq 0 ]
+  [ "$(sed -n '1p' lib.js)" = "// kit:begin extra" ]
+}
+
 @test "a region makes the file where there is none, and refuses one holding a different region" {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
@@ -384,7 +424,7 @@ later-release() {
   [ -e .kit/rules/json.md ]
   [[ "$output" == *".kit/rules/yaml.md: retired in 9.9.9, removed"* ]]
   [[ "$output" == *".kit/rules/json.md: retired in 9.9.9, but edited"* ]]
-  grep --quiet --invert-match 'rules/yaml.md' .kit/manifest
+  ! grep --quiet 'rules/yaml.md' .kit/manifest
   run "${repo}.later/bin/kit" check
   [ "$status" -eq 0 ]
 }
diff --git a/tests/linked.bats b/tests/linked.bats
index d56f4f6..0320de0 100644
--- a/tests/linked.bats
+++ b/tests/linked.bats
@@ -5,11 +5,14 @@
 setup() {
   kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
   export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
-  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}" "${BATS_TEST_TMPDIR}/shims"
+  printf '#!/usr/bin/env bash\nexit 1\n' > "${BATS_TEST_TMPDIR}/shims/gh" && chmod +x "${BATS_TEST_TMPDIR}/shims/gh"
+  export PATH="${BATS_TEST_TMPDIR}/shims:${PATH}"
   repo=$(mktemp -d)
   cd "${repo}"
   git init --quiet --initial-branch=main
   git remote add origin https://github.com/empowerite/example.git
+  export GITHUB_STEP_SUMMARY="${BATS_TEST_TMPDIR}/summary.md"
 }
 
 teardown() {
diff --git a/tests/lint.bats b/tests/lint.bats
index 285797d..c306fb0 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -48,9 +48,28 @@ teardown() {
   [[ "$output" == *"bad.sh"* ]]
 }
 
+@test "a named path is taken from the directory the command was typed in, and the staged list from the root" {
+  mkdir sub && cp bad.sh sub/bad.sh && git add sub/bad.sh
+  cd sub
+  run "${kit_checkout}/bin/kit" lint
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"sub/bad.sh"* ]]
+  run "${kit_checkout}/bin/kit" lint bad.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"SC2086"* ]]
+}
+
+@test "the delivered markdown passes the delivered markdown linter in a fresh repository" {
+  command -v markdownlint-cli2 >/dev/null || skip "markdownlint-cli2, the markdown rule's linter, is not on PATH"
+  run "${kit_checkout}/bin/kit" lint .kit/1st.md .kit/rules/bash.md AGENTS.md
+  [ "$status" -eq 0 ]
+  [[ "$output" == *".kit/markdownlint.jsonc"* ]]
+}
+
 @test "a linter a rule names that is not on PATH is a refusal, named" {
   mkdir -p "${BATS_TEST_TMPDIR}/path" && ln -s "$(command -v git)" "${BATS_TEST_TMPDIR}/path/git"
-  for tool in bash jq awk sed grep sort cut paste tr find head tail cat mkdir rm mv cp dirname basename date env uname readlink comm
+  for tool in bash jq awk sed grep sort cut paste tr find head tail cat mkdir rm mv cp dirname basename date env uname \
+    readlink comm
   do
     p=$(command -v "${tool}") && ln -s "${p}" "${BATS_TEST_TMPDIR}/path/${tool}" || true
   done

From bc78ec93727a9c909e12d03fddfb864947d3e981 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Mon, 26 Oct 2026 01:28:39 -0700
Subject: [PATCH 087/108] Refresh against the index, with HEAD's release as the
 base

just refresh ran kit update over the working tree and staged each delivered file whole, so
a desk's unstaged text outside a region, or outside the kit's entries in a merged JSON file,
was staged with the kit's change. It also took the index's release as its own base, so an
entry the source dropped survived the merge.

Now the sources and the copies are exported from the index, kit update runs over the export
with HEAD's release as the base of every merge, the release the copies were last made from,
and the export is staged back through a temporary index. The working tree then takes the
same step, so a desk's copies agree with the index inside the kit's parts and its own text
stays where it was. Proven by hand: an unstaged line after the AGENTS.md region stays
unstaged, and a deny entry removed from the claude module's source leaves both the index
and the working tree.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 justfile | 36 ++++++++++++++++++++++--------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/justfile b/justfile
index 227fc59..1fadc93 100644
--- a/justfile
+++ b/justfile
@@ -54,26 +54,34 @@ ci:
   echo "✅ ci passed"
 
 # Bring this repository's own installed copies up to the index and stage the result. Here the checkout is the
-# release, so an edit under modules/ is an edit to the release, not a consumer's drift. The copies are made from
-# the index, what the commit will carry, never from the working tree, so a half-staged edit cannot put a copy
-# into a commit that lacks its source. It is kit update at the same version: an untouched copy is replaced, a
-# retired one removed, a region rewritten between its markers with the rest of its file left alone. The
-# pre-commit hook runs this on a commit that touches the source; by hand it is for a desk without the hook.
+# release, so an edit under modules/ is an edit to the release, not a consumer's drift. Everything is done
+# against the index, what the commit will carry: the sources and the copies are exported from it, kit update
+# runs over the export with HEAD's release as the base of every merge, the release the copies were last made
+# from, and the export is staged back. A desk's unstaged text outside a region, or outside the kit's entries in
+# a merged JSON file, is not staged with it, and an entry the source dropped is retired, since the base still
+# carries it. The working tree then takes the same step, so a desk's copies agree with the index inside the
+# kit's parts. The pre-commit hook runs this on a commit that touches the source; by hand it is for a desk
+# without the hook.
 #
 #   just refresh
 [doc("🔁 Bring this repository's own installed copies up to the index, and stage the result")]
 [script]
 refresh:
   set -o errexit -o nounset -o pipefail
-  paths() { awk 'length($1) == 64 { print substr($0, 67) }' .kit/manifest; }
-  readarray -t before < <(paths)
-  index=$(mktemp -d)
-  trap 'rm -rf "${index}"' EXIT
-  git checkout-index --all --prefix="${index}/"
-  "${index}/bin/kit" update >/dev/null
-  readarray -t after < <(paths)
-  git add --all -- "${before[@]}" "${after[@]}" .kit/manifest
+  work=$(mktemp -d)
+  trap 'rm -rf "${work}"' EXIT
+  mkdir "${work}/index" "${work}/base"
+  git checkout-index --all --prefix="${work}/index/"
+  git archive HEAD bin modules | tar -x -C "${work}/base"
+  cp "$(git rev-parse --git-path index)" "${work}/index.file"
+  # The export is no repository of its own: the ceiling keeps git from finding this one above the temp directory.
+  (cd "${work}/index" && GIT_CEILING_DIRECTORIES="${work}" KIT_BASE="${work}/base" bin/kit update >/dev/null)
+  GIT_DIR=$(git rev-parse --absolute-git-dir) GIT_WORK_TREE="${work}/index" GIT_INDEX_FILE="${work}/index.file" \
+    git -C "${work}/index" add --all
+  git read-tree "$(GIT_INDEX_FILE="${work}/index.file" git write-tree)"
+  KIT_BASE="${work}/base" "${work}/index/bin/kit" update >/dev/null
   modules=$(sed -n 's/^modules *//p' .kit/manifest)
-  echo "✅ refreshed from the index and staged: ${#after[@]} delivered paths, modules ${modules}"
+  count=$(awk 'length($1) == 64' .kit/manifest | wc -l | tr -d ' ')
+  echo "✅ refreshed from the index and staged: ${count} delivered paths, modules ${modules}"
 
 # ----------------------------------------------------------------------------------------------------------------------

From c4a7401f2d8988aa3f37b7ff2aa71d2a67627fb4 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 00:17:15 -0700
Subject: [PATCH 088/108] Say what the release workflows do in plain words

The header comments on release.yml and retire-pre-releases.yml read as jargon. They now
say, in sentences a reader new to the repository can follow, what event runs each
workflow, what each step checks or produces, and why a release is never changed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml             | 17 +++++++++++------
 .github/workflows/retire-pre-releases.yml |  8 ++++----
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d97358e..99d28c8 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,11 +1,16 @@
-# release.yml - a tag v<version> on main becomes a GitHub release carrying the kit as one tarball
+# release.yml - pushing a version tag publishes the kit as a GitHub release
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Two steps, each one kit command, so a desk can run the same: `kit release verify` holds the tag to its shape and
-# its side of main, and `kit release publish` packs this checkout as kit-<version>.tar.gz with the tag's version
-# stamped in and publishes it, as a pre-release where the version has a suffix. Only a version tag starts a run.
-# A published release is immutable, so a tag is never reused; a pre-release lives as long as the branch it was
-# tagged on. see: .github/workflows/retire-pre-releases.yml
+# Pushing a tag such as v0.1.0 runs this workflow. It has two steps, and each step is one kit command, so the
+# same thing can be run on a laptop:
+#
+#   kit release verify    checks the tag. A release tag, v0.1.0, must point at a commit on main. A pre-release
+#                         tag, v0.1.0-rc.1, must point at a commit that is not on main. Any other tag is refused.
+#   kit release publish   packs this checkout into kit-<version>.tar.gz, writes the tag's version into it, and
+#                         publishes it as a GitHub release. A tag with a suffix is published as a pre-release.
+#
+# GitHub does not let a published release change, so a version is tagged once and never again. A pre-release
+# is deleted when the branch it was tagged on is deleted; see retire-pre-releases.yml.
 #
 # see: bin/kit-release.sh
 
diff --git a/.github/workflows/retire-pre-releases.yml b/.github/workflows/retire-pre-releases.yml
index 40816ba..e92e684 100644
--- a/.github/workflows/retire-pre-releases.yml
+++ b/.github/workflows/retire-pre-releases.yml
@@ -1,9 +1,9 @@
-# retire-pre-releases.yml - a pre-release lives as long as the branch it was tagged on
+# retire-pre-releases.yml - deleting a branch deletes the pre-releases that were made from it
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One step, one kit command: on every branch deletion, `kit release retire` deletes, tag and all, each pre-release
-# whose commit no remaining branch reaches. A release is never touched: it is on main, which is never deleted. A
-# deleted tag is a delete event too, and that one is ignored here.
+# Deleting a branch on GitHub runs this workflow. Its one step is one kit command: kit release retire deletes
+# every pre-release, tag included, whose commit is no longer on any branch. A release is never deleted, because
+# it is on main and main is never deleted. Deleting a tag also sends a delete event, and that one is ignored.
 #
 # see: bin/kit-release.sh, .github/workflows/release.yml
 

From 7ff43e9c7908a7bc24ca7150e21a1c157e7f1e98 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 00:29:45 -0700
Subject: [PATCH 089/108] Tag a release as release/<version>

A release tag is release/0.1.0 and a pre-release tag release/0.1.0-rc.1, so the version
tags have a namespace of their own, and the glob that starts the release workflow,
release/*, says what it is for. The part after release/ is the version: it is stamped
into the packed kit, names the tarball kit-<version>.tar.gz, and names the release. The
workflow, kit release verify, the fetch URL in release:fetch and in the delivered kit-ci
job, the tests, and the README follow. A mise pin adds version_prefix = "release/", which
is how mise maps a plain version onto the tag; curl, gh, and Homebrew need nothing.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/CLAUDE.md                             |  2 ++
 .github/workflows/kit-ci.yml                  |  2 +-
 .github/workflows/release.yml                 | 18 ++++++++-------
 .kit/manifest                                 |  2 +-
 README.md                                     | 22 ++++++++++---------
 bin/kit-release.sh                            | 15 +++++++------
 bin/release.sh                                |  2 +-
 .../repo/.github/workflows/kit-ci.yml         |  2 +-
 tests/release.bats                            | 21 ++++++++++--------
 9 files changed, 48 insertions(+), 38 deletions(-)

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index bec3c22..b87e902 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,3 +1,5 @@
+# CLAUDE.md
+
 <!-- kit:begin claude -->
 @../AGENTS.md
 <!-- kit:end claude -->
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 94b5179..08d1632 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -57,7 +57,7 @@ jobs:
           then
             mkdir -p "${RUNNER_TEMP}/kit"
             curl --fail --silent --location \
-              "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz" \
+              "https://github.com/empowerite/kit/releases/download/release/${version}/kit-${version}.tar.gz" \
               | tar --extract --gzip --directory "${RUNNER_TEMP}/kit" --strip-components 1
             printf '%s/kit/bin\n' "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
           fi
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 99d28c8..657ad84 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,13 +1,15 @@
-# release.yml - pushing a version tag publishes the kit as a GitHub release
+# release.yml - pushing a release tag publishes the kit as a GitHub release
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Pushing a tag such as v0.1.0 runs this workflow. It has two steps, and each step is one kit command, so the
-# same thing can be run on a laptop:
+# Pushing a tag such as release/0.1.0 runs this workflow. It has two steps, and each step is one kit command, so
+# the same thing can be run on a laptop:
 #
-#   kit release verify    checks the tag. A release tag, v0.1.0, must point at a commit on main. A pre-release
-#                         tag, v0.1.0-rc.1, must point at a commit that is not on main. Any other tag is refused.
-#   kit release publish   packs this checkout into kit-<version>.tar.gz, writes the tag's version into it, and
-#                         publishes it as a GitHub release. A tag with a suffix is published as a pre-release.
+#   kit release verify    checks the tag. A release tag, release/0.1.0, must point at a commit on main. A
+#                         pre-release tag, release/0.1.0-rc.1, must point at a commit that is not on main. Any
+#                         other tag is refused.
+#   kit release publish   packs this checkout into kit-<version>.tar.gz, writes the version after release/ into
+#                         it, and publishes it as a GitHub release named by that version. A version with a
+#                         suffix is published as a pre-release.
 #
 # GitHub does not let a published release change, so a version is tagged once and never again. A pre-release
 # is deleted when the branch it was tagged on is deleted; see retire-pre-releases.yml.
@@ -18,7 +20,7 @@ name: release
 
 on:
   push:
-    tags: ['v[0-9]*']
+    tags: ['release/*']
 
 permissions:
   contents: write
diff --git a/.kit/manifest b/.kit/manifest
index 0e86761..26dc7aa 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,7 +3,7 @@ version unreleased
 modules kit ci-github claude lefthook
 7b50d15feae7b63b94d845b2fa6e19e3220527c5b0cac69303b7fc19bd7484a8  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-489c6b1cca814e69a5bfb826e34a6eb9378d51cbd05b66357bcd663d0cefe536  .github/workflows/kit-ci.yml
+86f04faeb1b3c0dc237ac01cd405512970953d97f1e0e6820315e5bf93a4d667  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
 3a799487c744e7e4d089ca92d6e77a68422388454a41fd412c265d66d13a8f83  .kit/1st.md
 f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
diff --git a/README.md b/README.md
index dafe710..29d17c7 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ With mise, pin it in `mise.toml` and the version is part of the repository:
 
 ```toml
 [tools]
-"github:empowerite/kit" = "0.1.0"
+"github:empowerite/kit" = { version = "0.1.0", version_prefix = "release/" }
 ```
 
 With Homebrew, from the empowerite tap:
@@ -48,7 +48,8 @@ brew install empowerite/tap/kit
 ```
 
 Or by hand, with `gh`, which the kit needs anyway. Without a tag this takes the latest release, never a
-pre-release; `gh release download "v${version}" ...` takes a particular one. Unpack it and put its `bin/` on `PATH`:
+pre-release; `gh release download "release/${version}" ...` takes a particular one. Unpack it and put its `bin/` on
+`PATH`:
 
 ```sh
 gh release download --repo empowerite/kit --pattern 'kit-*.tar.gz' --output kit.tar.gz
@@ -161,13 +162,14 @@ region's markers are its notice, and this table is `settings.json`'s.
 
 ## Release
 
-A release is the tag `v<version>` on a commit on `main`, not only its head. A pre-release is `v<version>-<suffix>`,
-say `v0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a GitHub pre-release. The tag is the
-version: the repository carries no version file, the workflow stamps the tag's version into the packed kit, and a
-published release is immutable, so a tag is never reused. The workflow is two kit commands: `kit release verify`,
-which refuses a tag that is not a version, a release tag off `main`, and a pre-release tag on `main`; and `kit release
-publish`, which packs `bin/`, `modules/`, and `version` into `kit-<version>.tar.gz` and publishes the release. `kit
-release pack` makes the same tarball on a desk. A release is permanent. A pre-release is retired, tag and all, when
-the branch it was tagged on is deleted and no other branch reaches its commit.
+A release is the tag `release/<version>` on a commit on `main`, not only its head. A pre-release is
+`release/<version>-<suffix>`, say `release/0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a
+GitHub pre-release. The tag is the version: the repository carries no version file, the workflow stamps the part after
+`release/` into the packed kit and names the release by it, and a published release is immutable, so a tag is never
+reused. The workflow is two kit commands: `kit release verify`, which refuses a tag that is not `release/` and a
+version, a release tag off `main`, and a pre-release tag on `main`; and `kit release publish`, which packs `bin/`,
+`modules/`, and `version` into `kit-<version>.tar.gz` and publishes the release. `kit release pack` makes the same
+tarball on a desk. A release is permanent. A pre-release is retired, tag and all, when the branch it was tagged on is
+deleted and no other branch reaches its commit.
 
 The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure).
diff --git a/bin/kit-release.sh b/bin/kit-release.sh
index 07b938a..e1b643c 100755
--- a/bin/kit-release.sh
+++ b/bin/kit-release.sh
@@ -4,8 +4,8 @@
 #
 # The kit releasing itself, as verbs a workflow step or a desk calls alike:
 #
-#   verify <tag>              the tag is v<major>.<minor>.<patch>, on the default branch, or the same with a
-#                             -<suffix>, a pre-release, on a commit off it; refused otherwise, naming why
+#   verify <tag>              the tag is release/<major>.<minor>.<patch>, on the default branch, or the same with
+#                             a -<suffix>, a pre-release, on a commit off it; refused otherwise, naming why
 #   pack <tag> [<directory>]  kit-<version>.tar.gz and its .sha256 in <directory>, the current one by default:
 #                             one directory kit-<version>/ with bin/, modules/, and the version stamped in
 #   publish <tag>             pack, then a GitHub release carrying both files, marked pre-release for a suffix
@@ -32,12 +32,12 @@ refuse-tag() {
   exit 1
 }
 
-# tag-version <tag> prints the version a tag names, refusing a tag that is not a version.
+# tag-version <tag> prints the version a tag names, the part after release/, refusing a tag that is not one.
 tag-version() {
-  local version=${1#v}
-  if [[ "$1" != v* || ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
+  local version=${1#release/}
+  if [[ "$1" != release/* || ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
   then
-    refuse-tag "$1 is not a version tag: v<major>.<minor>.<patch>, with -<suffix> for a pre-release"
+    refuse-tag "$1 is not a release tag: release/<major>.<minor>.<patch>, with -<suffix> for a pre-release"
   fi
   printf '%s\n' "${version}"
 }
@@ -93,7 +93,8 @@ case "${verb}" in
     # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
     trap "rm -rf '${into}'" EXIT
     "${kit_root}/bin/kit" release pack "${tag}" "${into}"
-    notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    "github:empowerite/kit" = "%s"\n\n' "${version}"
+    pin=$(printf '"github:empowerite/kit" = { version = "%s", version_prefix = "release/" }' "${version}")
+    notes=$(printf 'Pin it in mise.toml:\n\n    [tools]\n    %s\n\n' "${pin}"
       printf 'Then, in the repository: kit install\n')
     flags=()
     [[ "${version}" == *-* ]] && flags+=(--prerelease)
diff --git a/bin/release.sh b/bin/release.sh
index d2378a4..edf1c11 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -599,7 +599,7 @@ release:fetch() {
   step "Fetching kit ${version} from its release"
   fresh=$(mktemp -d)
   if ! curl --fail --silent --location \
-      "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz" 2>/dev/null \
+      "https://github.com/empowerite/kit/releases/download/release/${version}/kit-${version}.tar.gz" 2>/dev/null \
     | tar --extract --gzip --directory "${fresh}" --strip-components 1 2>/dev/null
   then
     rm -rf "${fresh}"
diff --git a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
index 21992c0..66dbd19 100644
--- a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
@@ -57,7 +57,7 @@ jobs:
           then
             mkdir -p "${RUNNER_TEMP}/kit"
             curl --fail --silent --location \
-              "https://github.com/empowerite/kit/releases/download/v${version}/kit-${version}.tar.gz" \
+              "https://github.com/empowerite/kit/releases/download/release/${version}/kit-${version}.tar.gz" \
               | tar --extract --gzip --directory "${RUNNER_TEMP}/kit" --strip-components 1
             printf '%s/kit/bin\n' "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
           fi
diff --git a/tests/release.bats b/tests/release.bats
index 9fd4e67..753d725 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -19,27 +19,30 @@ teardown() {
   git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
   printf 'one\n' > a && git add a && git commit --quiet --message one && git push --quiet origin main
   git remote set-head origin main
-  git tag v1.2.3 && git tag v1.2.3-rc.1 && git tag vnope
+  git tag release/1.2.3 && git tag release/1.2.3-rc.1 && git tag release/nope && git tag v1.2.3
   git switch --quiet --create topic && printf 'two\n' > b && git add b && git commit --quiet --message two
-  git tag v1.2.4 && git tag v1.2.4-rc.1
-  run "${kit_checkout}/bin/kit" release verify v1.2.3
+  git tag release/1.2.4 && git tag release/1.2.4-rc.1
+  run "${kit_checkout}/bin/kit" release verify release/1.2.3
   [ "$status" -eq 0 ]
-  run "${kit_checkout}/bin/kit" release verify v1.2.4-rc.1
+  run "${kit_checkout}/bin/kit" release verify release/1.2.4-rc.1
   [ "$status" -eq 0 ]
-  run "${kit_checkout}/bin/kit" release verify v1.2.3-rc.1
+  run "${kit_checkout}/bin/kit" release verify release/1.2.3-rc.1
   [ "$status" -eq 1 ]
   [[ "$output" == *"is a pre-release tag on main"* ]]
-  run "${kit_checkout}/bin/kit" release verify v1.2.4
+  run "${kit_checkout}/bin/kit" release verify release/1.2.4
   [ "$status" -eq 1 ]
   [[ "$output" == *"is not on main"* ]]
-  run "${kit_checkout}/bin/kit" release verify vnope
+  run "${kit_checkout}/bin/kit" release verify release/nope
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"is not a release tag"* ]]
+  run "${kit_checkout}/bin/kit" release verify v1.2.3
   [ "$status" -eq 1 ]
-  [[ "$output" == *"is not a version tag"* ]]
+  [[ "$output" == *"is not a release tag"* ]]
 }
 
 @test "pack makes one directory with the release's layout and the version stamped in, which installs a repository" {
   version=9.9.9
-  run "${kit_checkout}/bin/kit" release pack "v${version}" "${work}"
+  run "${kit_checkout}/bin/kit" release pack "release/${version}" "${work}"
   [ "$status" -eq 0 ]
   [ -f "kit-${version}.tar.gz.sha256" ]
   grep --quiet "  kit-${version}.tar.gz$" "kit-${version}.tar.gz.sha256"

From e5d9cd85510eba888a5c4d77e21449d547b4b7c8 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 00:32:55 -0700
Subject: [PATCH 090/108] Publish a release from the runner alone

kit release publish refuses a release tag anywhere but on the runner, naming the push that
starts the release workflow, so a desk cannot publish a release by hand. A desk may still
publish a pre-release, and kit release pack still makes the tarball anywhere.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 6 ++++--
 README.md                     | 5 +++--
 bin/kit-release.sh            | 8 +++++++-
 tests/release.bats            | 7 +++++++
 4 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 657ad84..97da27c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -11,8 +11,10 @@
 #                         it, and publishes it as a GitHub release named by that version. A version with a
 #                         suffix is published as a pre-release.
 #
-# GitHub does not let a published release change, so a version is tagged once and never again. A pre-release
-# is deleted when the branch it was tagged on is deleted; see retire-pre-releases.yml.
+# GitHub does not let a published release change, so a version is tagged once and never again. A release is
+# published here and nowhere else: kit release publish refuses a release tag anywhere but on the runner, so a
+# desk cannot publish one by hand. A desk may publish a pre-release. A pre-release is deleted when the branch it
+# was tagged on is deleted; see retire-pre-releases.yml.
 #
 # see: bin/kit-release.sh
 
diff --git a/README.md b/README.md
index 29d17c7..a966976 100644
--- a/README.md
+++ b/README.md
@@ -169,7 +169,8 @@ GitHub pre-release. The tag is the version: the repository carries no version fi
 reused. The workflow is two kit commands: `kit release verify`, which refuses a tag that is not `release/` and a
 version, a release tag off `main`, and a pre-release tag on `main`; and `kit release publish`, which packs `bin/`,
 `modules/`, and `version` into `kit-<version>.tar.gz` and publishes the release. `kit release pack` makes the same
-tarball on a desk. A release is permanent. A pre-release is retired, tag and all, when the branch it was tagged on is
-deleted and no other branch reaches its commit.
+tarball on a desk, and `kit release publish` refuses a release tag anywhere but on the runner, so a release is published
+by the workflow and nowhere else; a desk may publish a pre-release. A release is permanent. A pre-release is retired,
+tag and all, when the branch it was tagged on is deleted and no other branch reaches its commit.
 
 The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure).
diff --git a/bin/kit-release.sh b/bin/kit-release.sh
index e1b643c..2962ed0 100755
--- a/bin/kit-release.sh
+++ b/bin/kit-release.sh
@@ -8,7 +8,9 @@
 #                             a -<suffix>, a pre-release, on a commit off it; refused otherwise, naming why
 #   pack <tag> [<directory>]  kit-<version>.tar.gz and its .sha256 in <directory>, the current one by default:
 #                             one directory kit-<version>/ with bin/, modules/, and the version stamped in
-#   publish <tag>             pack, then a GitHub release carrying both files, marked pre-release for a suffix
+#   publish <tag>             pack, then a GitHub release carrying both files, marked pre-release for a suffix.
+#                             A release is published by the runner alone, from the release workflow a pushed
+#                             tag starts; a desk may publish a pre-release
 #   retire [<branch>]         delete every pre-release whose commit no remaining branch reaches, after <branch>
 #                             was deleted; the branch is the runner's delete event when none is given. A
 #                             pre-release merged by a merge commit stays reachable from the default branch and
@@ -88,6 +90,10 @@ case "${verb}" in
     (( $# == 1 )) || { usage; exit 2; }
     tag=$1
     version=$(tag-version "${tag}")
+    if [[ "${version}" != *-* && -z "${GITHUB_ACTIONS:-}" ]]
+    then
+      refuse-tag "a release is published by the release workflow, not from a desk; push the tag: git push origin ${tag}"
+    fi
     guard:require tool:gh
     into=$(mktemp -d)
     # shellcheck disable=SC2064  # expanded now on purpose: the path is fixed from here on
diff --git a/tests/release.bats b/tests/release.bats
index 753d725..0190afd 100644
--- a/tests/release.bats
+++ b/tests/release.bats
@@ -40,6 +40,13 @@ teardown() {
   [[ "$output" == *"is not a release tag"* ]]
 }
 
+@test "publish refuses a release from a desk, and names the push that has the runner publish it" {
+  run env -u GITHUB_ACTIONS "${kit_checkout}/bin/kit" release publish release/1.2.3
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"a release is published by the release workflow, not from a desk"* ]]
+  [[ "$output" == *"git push origin release/1.2.3"* ]]
+}
+
 @test "pack makes one directory with the release's layout and the version stamped in, which installs a repository" {
   version=9.9.9
   run "${kit_checkout}/bin/kit" release pack "release/${version}" "${work}"

From 07999717f544d6bcf78872034c3a4f03e3fa9eb7 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 00:49:38 -0700
Subject: [PATCH 091/108] Open the README with the question, not the definition

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index a966976..f3f6853 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # empowerite/kit: **k**eep **i**t **t**rustworthy
 
-kit is the house rules, put where agents look, and the checks that hold agents to them, as a versioned release
-any repository can take and keep taking. Do you trust your agents? They were trained on the whole of what people
-have written, and that includes every shortcut anyone ever took: the "done" that was not, the test that was
-skipped and reported as passing, the rebase that quietly rewrote a colleague's branch. An agent is a tireless
-new colleague who has read everything and holds none of your house rules, unless you put them where it looks.
+Do you trust your agents? They were trained on the whole of what people have written, and that includes every shortcut
+anyone ever took: the "done" that was not, the test that was skipped and reported as passing, the rebase that quietly
+rewrote a colleague's branch. An agent is a tireless new colleague who has read everything and holds none of your house
+rules, unless you put them where it looks. kit is the house rules, put where agents look, and the checks that hold
+agents to them, as a versioned release any repository can take and keep taking.
 
 The rules are the smaller part. The point is verification that does not depend on anyone's word:
 

From 55ebbbb735c7c698721e1de02931bd1b4abc28ac Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 00:54:35 -0700
Subject: [PATCH 092/108] kit status: a pull request's worktree ends its row

The worktree that holds a pull request's branch was a line of its own after the issues it
closes. It now ends the pull request's row, after the checks, so the lines under a pull
request are the issues it closes and nothing else.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/status.sh     |  4 ++--
 tests/status.bats | 13 +++++++++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/bin/status.sh b/bin/status.sh
index b755449..48fb56f 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -282,7 +282,7 @@ status:check-cell() {
 }
 
 # status:pr-block <pr-json> <title-width> <state-width> <age-width> <worktree-relative> prints a pull request: its
-# row, the issues it closes, and the worktree here that holds its branch, when one does.
+# row, ending with the worktree here that holds its branch when one does, then the issues it closes.
 status:pr-block() {
   local doc=$1 title_w=$2 state_w=$3 age_w=$4 worktree=$5 number title state age unresolved row issue checks
   IFS=$'\t' read -r number title state age unresolved \
@@ -294,12 +294,12 @@ status:pr-block() {
   checks=$(status:check-cell "$(jq --compact-output .checks <<<"${doc}")")
   [[ -n "${checks}" ]] && row+="   ${checks}"
   (( unresolved > 0 )) && row+="   $(status:paint 33 "💬 ${unresolved} unresolved")"
+  [[ -n "${worktree}" ]] && row+="   $(status:paint 90 "🌿 ${worktree}")"
   printf '%s\n' "${row}" >&2
   while IFS= read -r issue
   do
     [[ -n "${issue}" ]] && printf '   %s\n' "$(status:paint 90 "closes ${issue}")" >&2
   done < <(jq --raw-output '.closes[] | "#\(.number) \(.title)"' <<<"${doc}")
-  [[ -n "${worktree}" ]] && printf '   %s\n' "$(status:paint 90 "🌿 ${worktree}")" >&2
   return 0
 }
 
diff --git a/tests/status.bats b/tests/status.bats
index 8a3cee6..5b8eff0 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -108,6 +108,19 @@ commits-in() {
   [ "$output" = "$(printf 'topic on ../other\t17')" ]
 }
 
+@test "a pull request's row ends with its worktree, and the issues it closes follow" {
+  doc='{"number":2,"title":"The first","state":"queued","age":259200,"unresolved":0,'
+  doc+='"checks":{"state":"PENDING","passed":0,"total":1,"failing":0,"took":36},'
+  doc+='"closes":[{"number":1,"title":"One"},{"number":4,"title":"Four"}]}'
+  run in_status status:pr-block "${doc}" 12 6 2 worktrees/topic
+  [ "${lines[0]}" = "🔀 #2 The first   🚦 queued   3d   🏃 0 / 1 · 36s   🌿 worktrees/topic" ]
+  [ "${lines[1]}" = "   closes #1 One" ]
+  [ "${lines[2]}" = "   closes #4 Four" ]
+  [ "${#lines[@]}" -eq 3 ]
+  run in_status status:pr-block "${doc}" 12 6 2 ''
+  [ "${lines[0]}" = "🔀 #2 The first   🚦 queued   3d   🏃 0 / 1 · 36s" ]
+}
+
 @test "a path is printed relative to the current directory" {
   run in_status status:relative "${PWD}"
   [ "$output" = "." ]

From d99018c95bdd2b018b2991e2ac8d945e89669fc9 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 01:15:43 -0700
Subject: [PATCH 093/108] #8 Generate: a directive opens a region a command
 fills, and the kit's regions are made that way

A comment line that is `:generate:<command>:until:"<pattern>"`, or `:while:"<pattern>"`, and
nothing else opens a region: the command runs from the repository root with the running kit's
bin/ first on PATH, and its output replaces the lines after the directive up to the first line
matching the pattern, which stays, or every line matching it. The command is one command and
its arguments, with no shell operator, so what makes a region is always a verb, a recipe, a
target, or a script in the tree. A directive inside a fenced code block is not live.

kit generate expands the named files once, or every tracked and untracked-but-not-ignored file
to a fixed point, at most twenty passes; --check writes nothing and names every stale file. A
file is rewritten only on a clean expansion: a failing command, a region that never closes, a
command outside its shape, a conflict marker, or an empty result leaves it as it was and fails
the run. kit check runs the check over the whole repository, and the lefthook fragment over the
staged paths.

The kit's regions are made that way. Install writes the directive naming kit region <path>,
the content, and the end marker; kit region prints what the active modules deliver at a path;
update regenerates a region rather than merging it; a region there with other content is
regenerated rather than refused; and remove takes the block out. This repository's own
AGENTS.md, .gitignore, and .claude/CLAUDE.md carry the new form, which the refresh wrote.

docs/generate.md is the page; the README, the architecture and modules pages, the entry file,
the module pages, and the figure say region the same way. Six cases in tests/generate.bats
cover the semantics and each refusal, and the region tests in tests/kit.bats follow.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/CLAUDE.md                             |   4 +-
 .gitignore                                    |   4 +-
 .kit/1st.md                                   |   8 +-
 .kit/lefthook.yml                             |   2 +
 .kit/manifest                                 |   4 +-
 AGENTS.md                                     |   4 +-
 README.md                                     |  18 +-
 bin/generate.sh                               | 245 ++++++++++++++++++
 bin/kit                                       |   4 +
 bin/kit-check.sh                              |  18 +-
 bin/kit-generate.sh                           |  35 +++
 bin/kit-region.sh                             |  50 ++++
 bin/kit-update.sh                             |  18 +-
 bin/release.sh                                |  74 +++---
 docs/architecture.md                          |   5 +-
 docs/delivery.svg                             |   2 +-
 docs/generate.md                              |  82 ++++++
 docs/modules.md                               |  18 +-
 modules/claude/docs/README.md                 |   6 +-
 modules/kit/docs/README.md                    |   3 +-
 modules/kit/files/repo/.kit/1st.md            |   8 +-
 modules/lefthook/docs/README.md               |  10 +-
 modules/lefthook/files/repo/.kit/lefthook.yml |   2 +
 tests/generate.bats                           | 101 ++++++++
 tests/kit.bats                                |  50 ++--
 25 files changed, 665 insertions(+), 110 deletions(-)
 create mode 100644 bin/generate.sh
 create mode 100755 bin/kit-generate.sh
 create mode 100755 bin/kit-region.sh
 create mode 100644 docs/generate.md
 create mode 100644 tests/generate.bats

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index b87e902..db5628d 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,5 +1,5 @@
 # CLAUDE.md
 
-<!-- kit:begin claude -->
+<!-- :generate:kit region .claude/CLAUDE.md:until:"kit:end" -->
 @../AGENTS.md
-<!-- kit:end claude -->
+<!-- kit:end -->
diff --git a/.gitignore b/.gitignore
index a105eaa..19a72d7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,9 @@
 # .gitignore - untracked files and folders
 # ----------------------------------------------------------------------------------------------------------------------
 
-# kit:begin kit
+# :generate:kit region .gitignore:until:"kit:end"
 # per-issue worktrees for agents; see: .kit/1st.md
 /worktrees/
-# kit:end kit
+# kit:end
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/1st.md b/.kit/1st.md
index c7e65ce..eca00f6 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -96,11 +96,13 @@ carries the machinery, reached through the `kit` command on `PATH`: the loop's c
 delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
 lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
-key, the kit owning only the entries it writes; a region is held between its markers inside a file the
-repository owns; everything else is copied as it is.
+key, the kit owning only the entries it writes; a region inside a file the repository owns is opened by a
+`:generate:` directive and made by the command it names, through `kit generate`; everything else is copied as it
+is.
 
 - `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
-  `.gitignore`, each a region the kit owns inside a file the repository owns.
+  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a
+  `:generate:` directive of the repository's own, and `kit check` holds every region to its command.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index 8fa1f10..46fc359 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -11,3 +11,5 @@ pre-commit:
   commands:
     kit-lint:
       run: kit lint {staged_files}
+    kit-generate:
+      run: kit generate --check {staged_files}
diff --git a/.kit/manifest b/.kit/manifest
index 26dc7aa..f360f19 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -5,8 +5,8 @@ modules kit ci-github claude lefthook
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
 86f04faeb1b3c0dc237ac01cd405512970953d97f1e0e6820315e5bf93a4d667  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
-3a799487c744e7e4d089ca92d6e77a68422388454a41fd412c265d66d13a8f83  .kit/1st.md
-f2c9d380ac7b39e2e52be7822ead90d6031d958285a3a54681b4b34b2746abb8  .kit/lefthook.yml
+39d7f0bf97cc6a89e51f8a195f95b265d56156e9a62deb0722537097482d5585  .kit/1st.md
+a36cca49330228339ece2a2fd7fe4958f13496329de43d56e1e0534344c99d20  .kit/lefthook.yml
 acf52f60f178be28ca2f09bb22f8a982bba0e61eff611ca1a91f1f8dae2ccbce  .kit/markdownlint.jsonc
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
 b0f6e0e6ac1c2d1271082459f53b0cfdc7ad5028a6cd9a5d3a899bf160b5cde9  .kit/rules/gitignore.md
diff --git a/AGENTS.md b/AGENTS.md
index 6085c08..58f1c58 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
-<!-- kit:begin kit -->
+<!-- :generate:kit region AGENTS.md:until:"kit:end" -->
 Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
 repository trustworthy.
-<!-- kit:end kit -->
+<!-- kit:end -->
 
 This repository is the kit's own source, and uses it.
 
diff --git a/README.md b/README.md
index f3f6853..fd3a3f5 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ The rules are the smaller part. The point is verification that does not depend o
 
 - `kit ci`, which refuses a pull request without a linked open issue and refuses to pass a gate that did not
   run, from the delivered GitHub Actions job or from any pipeline;
-- `kit check`, which holds every delivered file to its release;
+- `kit check`, which holds every delivered file to its release and every generated region to its command;
 - `kit lint`, each rule's own linter over the paths it governs, before a commit or anywhere;
 - a deny list that refuses the spellings the rules forbid;
 - `kit status`, which shows what every pull request's checks said.
@@ -69,10 +69,12 @@ sees a new kit a day after it ships unless `[settings]` carries `minimum_release
   always in; `ci-github` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the
   Claude Code adapter. `kit install ci-github lefthook claude` takes all three, and `kit module add` takes one
   later.
-- `install` writes the sentence every agent reads into a region of `AGENTS.md`, between `<!-- kit:begin kit -->`
-  and `<!-- kit:end kit -->`, making the file where there is none and leaving the rest of it yours, and the
-  `/worktrees/` entry into a region of `.gitignore` the same way. Move the region where you like; `kit check`
-  holds only what is between the markers.
+- `install` writes the sentence every agent reads into a region of `AGENTS.md`, opened by a `:generate:`
+  directive naming `kit region AGENTS.md` and closed by `kit:end`, making the file where there is none and
+  leaving the rest of it yours, and the `/worktrees/` entry into a region of `.gitignore` the same way. Move the
+  region where you like and write what you like around it; `kit generate` makes the region what the command
+  makes it, and `kit check` holds it there. Any file of yours may carry a directive of its own;
+  [docs/generate.md](docs/generate.md) says how.
 - Commit what `install` wrote.
 - Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
   or any command as `gate` in `.kit/settings.yml`. The delivered check, `kit ci`, runs it with `kit check` and
@@ -147,9 +149,9 @@ The installed copies are written by `bin/kit install` and not edited by hand:
 | `.kit/1st.md`, `.kit/rules/`, `.kit/settings.schema.json` | `modules/kit/files/repo/.kit/` |
 | `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
 | `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
-| `.claude/CLAUDE.md` | `modules/claude/regions/repo/.claude/CLAUDE.md`, a region; the rest of the file is the repository's |
+| `.claude/CLAUDE.md` | `modules/claude/regions/repo/.claude/CLAUDE.md`, a region `kit region` fills; the rest of the file is the repository's |
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
-| `AGENTS.md`, `.gitignore` | `modules/kit/regions/repo/`, regions; the rest of each file is the repository's |
+| `AGENTS.md`, `.gitignore` | `modules/kit/regions/repo/`, regions `kit region` fills; the rest of each file is the repository's |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
 `.kit/settings.yml` is this repository's own.
@@ -158,7 +160,7 @@ A commit that changes a file under `modules/` rewrites the installed copies in t
 hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk without the
 hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names any installed
 copy that does not match its source. Each delivered whole file says in its header that it is delivered by kit; a
-region's markers are its notice, and this table is `settings.json`'s.
+region's directive is its notice, and this table is `settings.json`'s.
 
 ## Release
 
diff --git a/bin/generate.sh b/bin/generate.sh
new file mode 100644
index 0000000..b1b1fdc
--- /dev/null
+++ b/bin/generate.sh
@@ -0,0 +1,245 @@
+# shellcheck shell=bash
+# shellcheck disable=SC2154  # kit_root is exported by bin/kit
+# generate.sh - a directive opens a region a command fills: discovery, expansion, and the fixed point (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# A comment line in a file's own syntax that is `:generate:<command>:until:"<pattern>"`, or `:while:"<pattern>"`,
+# and nothing else opens a region. The directive line stays. The command runs from the repository root, with the running kit's
+# bin/ first on PATH, and its stdout replaces the lines after the directive: up to the first line matching the
+# pattern for until, which stays, or every line matching it for while. So a region is a command's output living
+# inside a file a person owns, and the file itself says how it is made.
+#
+# The command is one command and its arguments, with no shell operator, so what makes a region is always a verb,
+# a recipe, a target, or a script in the tree, where it can be read, listed, and tested, never a one-liner in a
+# comment. A directive inside a fenced code block is not live, so a page may show one.
+#
+# A file is rewritten only on a clean expansion. A command that fails, an until pattern no later line matches, a
+# conflict marker in the file, an empty result from a file that was not, or a command outside its shape leaves
+# the file as it was and fails the run, naming the file and the line.
+#
+# see: bin/kit-generate.sh, bin/kit-region.sh, docs/generate.md
+
+# The directive's shape: a line that is a comment, opened by one of the comment openers the kit knows, carrying
+# the directive and nothing before it, so a mention of the syntax inside prose, a code span, or a string in a
+# script is not one. Captures: the opener, the command, until or while, and the pattern.
+declare -g generate_directive_re='^[[:space:]]*(#|//|--|<!--|/\*|%|;)[[:space:]]*:generate:(.+):(until|while):[[:space:]]*"([^"]+)"'
+
+# The command's shape: words of letters, digits, and the characters a name, a flag, a path, or a key=value
+# pair is made of, and no shell operator.
+declare -g generate_command_re='^[A-Za-z0-9_./=:@~%,+-]+([[:space:]]+[A-Za-z0-9_./=:@~%,+-]+)*$'
+
+# An unresolved conflict's shape: a line of seven < or > alone or followed by git's label. The middle marker,
+# seven =, is also a markdown heading underline and is never written without the opening one, so it is not read.
+declare -g generate_conflict_re='^(<{7}|>{7})([[:space:]].*)?$'
+
+# generate:carries <file> is true when the file carries a directive.
+generate:carries() {
+  [[ -f "$1" ]] && grep --quiet --extended-regexp "${generate_directive_re}" "$1"
+}
+
+# generate:discover [<path>…] prints every file under the paths, or the whole repository, that carries a
+# directive: tracked files and untracked ones git does not ignore, so a file install just wrote counts before
+# it is added. A named file is printed when it carries one, wherever it is.
+generate:discover() {
+  local path
+  if (( $# == 0 ))
+  then
+    while IFS= read -r -d '' path
+    do
+      generate:carries "${path}" && printf '%s\n' "${path}"
+    done < <(git ls-files -z --cached --others --exclude-standard)
+    return 0
+  fi
+  for path in "$@"
+  do
+    generate:carries "${path}" && printf '%s\n' "${path}"
+  done
+  return 0
+}
+
+# generate:target <file> prints the file a write lands in: the file, or what a symlink there points at.
+generate:target() {
+  if [[ -L "$1" ]]
+  then readlink -f "$1"
+  else printf '%s\n' "$1"
+  fi
+}
+
+# generate:expand <file> <mode> expands the file's directives into a sibling temp file and compares. It returns 0
+# when nothing changed, 1 when the file was rewritten (mode write) or is stale (mode check), and 2 when it could
+# not be cleanly expanded, in which case the file is left as it was. Only mode write ever writes.
+generate:expand() {
+  local file=$1 mode=${2:-write} target temp line number=0 fence=false seeking='' pattern='' opened=0 command rc
+  local -a words
+  if [[ ! -f "${file}" ]]
+  then
+    error "generate: no such file: ${file}"
+    return 2
+  fi
+  if grep --quiet --extended-regexp "${generate_conflict_re}" "${file}"
+  then
+    error "generate: ${file} carries an unresolved conflict; resolve it, then run: kit generate"
+    return 2
+  fi
+  target=$(generate:target "${file}")
+  temp="${target}.kit-new"
+  cp -p "${target}" "${temp}"
+  rc=0
+  {
+    while IFS= read -r line || [[ -n "${line}" ]]
+    do
+      number=$(( number + 1 ))
+      if [[ "${seeking}" == until ]]
+      then
+        [[ "${line}" =~ ${pattern} ]] || continue
+        seeking=''
+      elif [[ "${seeking}" == while ]]
+      then
+        [[ "${line}" =~ ${pattern} ]] && continue
+        seeking=''
+      fi
+      printf '%s\n' "${line}"
+      if [[ "${line}" =~ ^[[:space:]]*(\`\`\`|~~~) ]]
+      then
+        if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+        continue
+      fi
+      [[ "${fence}" == false && "${line}" =~ ${generate_directive_re} ]] || continue
+      command=${BASH_REMATCH[2]}
+      seeking=${BASH_REMATCH[3]}
+      pattern=${BASH_REMATCH[4]}
+      opened=${number}
+      command=${command#"${command%%[![:space:]]*}"}
+      command=${command%"${command##*[![:space:]]}"}
+      if [[ ! "${command}" =~ ${generate_command_re} ]]
+      then
+        error "${file}:${number}: a :generate: command is one command and its arguments, with no shell operator:" \
+          "${command}"
+        rc=2
+        break
+      fi
+      read -r -a words <<<"${command}"
+      if ! PATH="${kit_root}/bin:${PATH}" "${words[@]}"
+      then
+        error "${file}:${number}: the command failed: ${command}"
+        rc=2
+        break
+      fi
+    done < "${file}"
+    if (( rc == 0 )) && [[ "${seeking}" == until ]]
+    then
+      error "${file}:${opened}: the region never closes; no later line matches \"${pattern}\""
+      rc=2
+    fi
+  } > "${temp}"
+  if (( rc != 0 ))
+  then
+    rm -f "${temp}"
+    return 2
+  fi
+  if [[ -s "${file}" && ! -s "${temp}" ]]
+  then
+    error "generate: expanding ${file} produced nothing; left as it was"
+    rm -f "${temp}"
+    return 2
+  fi
+  if cmp --silent "${file}" "${temp}"
+  then
+    rm -f "${temp}"
+    return 0
+  fi
+  if [[ "${mode}" == check ]]
+  then
+    error "${file}: stale; run: kit generate"
+    rm -f "${temp}"
+    return 1
+  fi
+  mv "${temp}" "${target}"
+  step "${file}: regenerated"
+  return 1
+}
+
+# generate:run [--check] [--iterations=<n>] [<path>…] is the driver. Named files are expanded for one pass, or
+# <n>; with none named every file carrying a directive is expanded until a pass changes nothing, at most twenty
+# passes or <n>. --check runs one pass without writing and fails naming every stale file. A file that could not
+# be cleanly expanded fails the run whatever the mode.
+generate:run() {
+  local check=false limit=0 explicit=false arg file rc pass=0 changed failed stale
+  local -a files=() targets=()
+  for arg in "$@"
+  do
+    case "${arg}" in
+      (--check) check=true ;;
+      (--iterations=*) limit=${arg#*=} ;;
+      (*) files+=("${arg}"); explicit=true ;;
+    esac
+  done
+  if (( ${#files[@]} ))
+  then readarray -t targets < <(generate:discover "${files[@]}")
+  else readarray -t targets < <(generate:discover)
+  fi
+  if (( ${#targets[@]} == 0 ))
+  then
+    ok "generate: no :generate: directive to expand"
+    return 0
+  fi
+  if [[ "${check}" == true ]]
+  then
+    stale=0
+    failed=0
+    for file in "${targets[@]}"
+    do
+      generate:expand "${file}" check && rc=0 || rc=$?
+      (( rc == 2 )) && failed=$(( failed + 1 ))
+      (( rc == 1 )) && stale=$(( stale + 1 ))
+    done
+    if (( failed > 0 ))
+    then
+      error "generate: ${failed} file(s) could not be expanded; see above"
+      return 1
+    fi
+    if (( stale > 0 ))
+    then
+      error "generate: ${stale} of ${#targets[@]} generated file(s) are stale; run: kit generate"
+      return 1
+    fi
+    ok "generate: ${#targets[@]} generated file(s), every region as its command makes it"
+    return 0
+  fi
+  if (( limit == 0 ))
+  then
+    if [[ "${explicit}" == true ]]; then limit=1; else limit=20; fi
+  fi
+  while (( pass < limit ))
+  do
+    pass=$(( pass + 1 ))
+    changed=0
+    failed=0
+    for file in "${targets[@]}"
+    do
+      generate:expand "${file}" write && rc=0 || rc=$?
+      (( rc == 2 )) && failed=$(( failed + 1 ))
+      (( rc == 1 )) && changed=$(( changed + 1 ))
+    done
+    if (( failed > 0 ))
+    then
+      error "generate: ${failed} file(s) could not be expanded; see above"
+      return 1
+    fi
+    if (( changed == 0 ))
+    then
+      ok "generate: ${#targets[@]} generated file(s), settled in ${pass} pass(es)"
+      return 0
+    fi
+  done
+  if [[ "${explicit}" == true ]]
+  then
+    ok "generate: ${#targets[@]} file(s) expanded in ${pass} pass(es)"
+    return 0
+  fi
+  error "generate: still changing after ${limit} passes; a command's output depends on its own output." \
+    "Raise the bound with --iterations=<n>, or fix the command."
+  return 1
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit b/bin/kit
index 98e4e16..fd3cbf9 100755
--- a/bin/kit
+++ b/bin/kit
@@ -40,6 +40,10 @@ usage: kit <verb> [<argument>…]
   module <list|add|remove> [<module>…]
                         the modules this repository takes
   context <path>…       name the rules that govern a file, and record the ask
+  generate [--check] [<path>…]
+                        expand every :generate: region to what its command makes, or check that it is
+  region [--home] <path>
+                        print the content the active modules deliver as the region at a path
   ci                    the delivered CI job's checks, anywhere: gate, check, and linked, every one reported
   gate                  run the repository's gate, the gate setting or the detected one; refuse when there is none
   linked [<number>]     refuse a pull request not linked to an open issue of this repository
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index c878714..04ceb7e 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -10,7 +10,7 @@
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use release
+use release generate
 
 if [[ "${1:-}" == --help ]]
 then
@@ -49,24 +49,30 @@ do
     then
       error "run: mise install (jq is not on PATH, so ${dest} could not be read)"
       findings=$(( findings + 1 ))
-    elif [[ "${kind}" == region ]] && ! release:installed "${src}" "${dest}" >/dev/null
+    elif [[ "${kind}" == region ]]
     then
-      error "${dest} has no kit region; run: kit update"
-      findings=$(( findings + 1 ))
+      # The directive must be there; what it makes is held below, with every other generated region.
+      if ! release:installed "${src}" "${dest}" >/dev/null
+      then
+        error "${dest} has no kit region; run: kit update"
+        findings=$(( findings + 1 ))
+      fi
     elif ! release:holds "${src}" "${dest}"
     then
       case "${kind}" in
         (merge) error "${dest} is missing an entry the kit writes; run: kit update" ;;
-        (region) error "${dest}: the kit's region differs from the pinned release" ;;
         (*) error "${dest} differs from the pinned release" ;;
       esac
       findings=$(( findings + 1 ))
     fi
   done <<<"${delivered}"
 done
+# Every generated region, the kit's and the repository's own, is what its command makes it.
+generate:run --check || findings=$(( findings + 1 ))
 if (( findings > 0 ))
 then
-  error "${findings} finding(s). A delivered file changes by a new release and kit update, never in place."
+  error "${findings} finding(s). A delivered file changes by a new release and kit update, never in place;" \
+    "a generated region by kit generate."
   exit 1
 fi
 ok "kit ${version}, modules ${modules[*]:-none}: every delivered file matches the pinned release."
diff --git a/bin/kit-generate.sh b/bin/kit-generate.sh
new file mode 100755
index 0000000..2122c78
--- /dev/null
+++ b/bin/kit-generate.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# kit-generate - expand every :generate: region to what its command makes, or check that it is (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The paths are the arguments, taken from the directory the command was typed in, else every tracked file and
+# every untracked one git does not ignore. Named files are expanded once, or --iterations=<n> times; the whole
+# repository is expanded until a pass changes nothing. --check writes nothing and fails naming every stale file;
+# kit check runs it, and the lefthook fragment runs it over the staged paths.
+#
+# see: bin/generate.sh, docs/generate.md
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use context generate
+
+args=()
+for arg in "$@"
+do
+  case "${arg}" in
+    (--help)
+      echo "usage: kit generate [--check] [--iterations=<n>] [<path>…]" >&2
+      exit 0
+      ;;
+    (--check | --iterations=*) args+=("${arg}") ;;
+    (-*)
+      error "unknown flag '${arg}' (usage: kit generate [--check] [--iterations=<n>] [<path>…])"
+      exit 2
+      ;;
+    (*) args+=("$(context:relative "${arg}")")
+  esac
+done
+generate:run "${args[@]}"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-region.sh b/bin/kit-region.sh
new file mode 100755
index 0000000..c1232f8
--- /dev/null
+++ b/bin/kit-region.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# kit-region - print the content the active modules deliver as the region at a path (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The command behind every region the kit delivers: the directive install writes into AGENTS.md reads
+# `:generate:kit region AGENTS.md:until:"kit:end"`, and kit generate runs this to fill it. The path is relative
+# to the repository, or with --home to the home directory. One active module delivers a region at a path, so
+# the answer is that module's regions/<base>/<path>, and a path no active module delivers is refused.
+#
+# see: bin/generate.sh, bin/release.sh
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use release
+
+base=repo
+path=''
+for arg in "$@"
+do
+  case "${arg}" in
+    (--help)
+      echo "usage: kit region [--home] <path>" >&2
+      exit 0
+      ;;
+    (--home) base=home ;;
+    (-*)
+      error "unknown flag '${arg}' (usage: kit region [--home] <path>)"
+      exit 2
+      ;;
+    (*) path=${arg}
+  esac
+done
+if [[ -z "${path}" ]]
+then
+  echo "usage: kit region [--home] <path>" >&2
+  exit 2
+fi
+release:require-manifest
+readarray -t modules < <(release:manifest-modules)
+release:render-all "${kit_root}" "${modules[@]}"
+src=$(release:source-of "${kit_root}" "${base}" "${path}" "${modules[@]}")
+if [[ -z "${src}" ]] || [[ "$(release:kind "${src}" "${path}")" != region ]]
+then
+  error "no active module delivers a region at ${path} (modules: ${modules[*]}); see .kit/manifest"
+  exit 1
+fi
+cat "${src}"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index 50e9d58..e190ee9 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -72,6 +72,11 @@ do
     then
       step "${dest}: merged by key"
       release:place "${src}" "${dest}" "${previous_src}"
+    elif [[ "${kind}" == region ]]
+    then
+      # A region is what its command makes it, so it is regenerated, never merged.
+      step "${dest}: the region regenerated"
+      release:place "${src}" "${dest}"
     elif ! release:installed "${src}" "${dest}" >/dev/null 2>&1
     then
       step "${dest}: missing, written"
@@ -80,19 +85,6 @@ do
     then
       step "${dest}: unchanged since ${previous}, replaced"
       release:place "${src}" "${dest}"
-    elif [[ "${kind}" == region ]]
-    then
-      # The region's content is merged on its own and written back between the markers.
-      step "${dest}: the kit's region edited since ${previous}, three-way merged"
-      ours=$(mktemp)
-      release:installed "${src}" "${dest}" > "${ours}"
-      if ! git merge-file --marker-size 7 "${ours}" "${previous_src}" "${src}"
-      then
-        warn "${dest}: conflict markers are left in the kit's region; resolve them, then run: kit check"
-        conflicts=$(( conflicts + 1 ))
-      fi
-      release:region-write "${dest}" "$(release:region-module "${src}")" "${ours}"
-      rm -f "${ours}"
     else
       step "${dest}: edited since ${previous}, three-way merged"
       if ! git merge-file --marker-size 7 "${dest}" "${previous_src}" "${src}"
diff --git a/bin/release.sh b/bin/release.sh
index edf1c11..e68a874 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -7,12 +7,12 @@
 # A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
 # mirrored at the base's root; templates/<base>/, with @key@ rendered from the repository's answers, then
 # mirrored the same way; and regions/<base>/, each file placed as a region the kit owns inside a file the
-# repository owns, between marker comments, so the rest of that file stays the repository's. A repository
+# repository owns, opened by a :generate: directive naming kit region and closed by an end marker, so the rest
+# of that file stays the repository's and kit generate makes the region what the command makes it. A repository
 # defines modules of its own the same way under .kit/modules/<name>/, and a name is looked up in the release
 # first, then there. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's home
 # directory, recorded in ~/.kit/manifest, which every repository on the desk shares. A destination ending in
-# .json is merged by key, the kit owning only the entries it writes, and a region is held to the release between
-# its markers and nowhere else. The repository's choices live in .kit/settings.yml, which the kit reads and never
+# .json is merged by key, the kit owning only the entries it writes, and a region is regenerated, never merged. The repository's choices live in .kit/settings.yml, which the kit reads and never
 # writes. docs/modules.md is the format's description.
 #
 # Every function reads a release from a root, kit_root by default, which bin/kit exports. bin/kit also moves to
@@ -409,15 +409,21 @@ release:kind() {
   fi
 }
 
-# release:region-module <source> prints the module a region source belongs to, which names its markers.
-release:region-module() {
-  local rest=${1##*/modules/}
-  printf '%s\n' "${rest%%/*}"
+# release:region-command <dest> prints the command that makes the region at a destination: kit region with the
+# path relative to the base's root, and --home under the home directory.
+release:region-command() {
+  local home
+  home=$(release:base-root home)
+  if [[ "$1" == "${home}"/* ]]
+  then printf 'kit region --home %s\n' "${1#"${home}"/}"
+  else printf 'kit region %s\n' "$1"
+  fi
 }
 
-# release:region-markers <path> <module> prints the region's two marker lines in the file's own comment syntax,
-# by its extension: an HTML comment, a double slash, a double dash, or a hash. A kind of file with no comment
-# syntax the kit knows is refused where the module is read, in release:render-all.
+# release:region-markers <dest> prints the region's two lines in the file's own comment syntax, by its extension,
+# an HTML comment, a double slash, a double dash, or a hash: the directive that opens it, naming the command and
+# the end marker, and the end marker. A kind of file with no comment syntax the kit knows is refused where the
+# module is read, in release:render-all.
 release:region-markers() {
   local open close
   case "${1##*.}" in
@@ -427,7 +433,8 @@ release:region-markers() {
     (sql | lua | hs) open='-- ' close='' ;;
     (*) open='# ' close='' ;;
   esac
-  printf '%skit:begin %s%s\n%skit:end %s%s\n' "${open}" "$2" "${close}" "${open}" "$2" "${close}"
+  printf '%s:generate:%s:until:"kit:end"%s\n%skit:end%s\n' "${open}" "$(release:region-command "$1")" "${close}" \
+    "${open}" "${close}"
 }
 
 # release:region-known <path> is true where the kit knows the file's comment syntax, so a region can be marked.
@@ -453,12 +460,12 @@ release:target() {
   fi
 }
 
-# release:region-has <path> <module> is true when the file carries the region's begin marker; a begin marker
-# with no end marker is refused, naming the file, since a write would drop everything after it.
+# release:region-has <dest> is true when the file carries the region's directive; a directive with no end
+# marker is refused, naming the file, since a write would drop everything after it.
 release:region-has() {
   local path=$1 begin end
   [[ -f "${path}" ]] || return 1
-  { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
+  { read -r begin; read -r end; } < <(release:region-markers "$1")
   grep --quiet --line-regexp --fixed-strings "${begin}" "${path}" || return 1
   if ! grep --quiet --line-regexp --fixed-strings "${end}" "${path}"
   then
@@ -467,23 +474,24 @@ release:region-has() {
   fi
 }
 
-# release:region-read <path> <module> prints the region's content, between its markers, and fails where the
-# file or the region is absent.
+# release:region-read <dest> prints the region's content, between its directive and its end marker, and fails
+# where the file or the region is absent.
 release:region-read() {
   local path=$1 begin end
-  release:region-has "$1" "$2" || return $?
-  { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
+  release:region-has "$1" || return $?
+  { read -r begin; read -r end; } < <(release:region-markers "$1")
   awk -v b="${begin}" -v e="${end}" '$0 == e { on = 0 } on { print } $0 == b { on = 1 }' "${path}"
 }
 
-# release:region-write <path> <module> <content-file> replaces the region's content, appending the region after a
-# blank line where the file has none, and making the file where there is none.
+# release:region-write <dest> <content-file> makes the region what its command makes it, which is the content:
+# between the directive and the end marker where the file carries them, appended after a blank line where it
+# does not, and as the whole file where there is none.
 release:region-write() {
-  local path module=$2 content=$3 begin end status=0
+  local path content=$2 begin end status=0
   path=$(release:target "$1")
-  { read -r begin; read -r end; } < <(release:region-markers "${path}" "${module}")
+  { read -r begin; read -r end; } < <(release:region-markers "$1")
   mkdir -p "$(dirname "${path}")"
-  release:region-has "${path}" "${module}" || status=$?
+  release:region-has "${path}" || status=$?
   (( status == 2 )) && return 1
   if (( status == 0 ))
   then
@@ -507,13 +515,13 @@ release:region-write() {
   mv "${path}.kit-new" "${path}"
 }
 
-# release:region-remove <path> <module> takes the region and its markers out, and the blank line before it;
-# a file left empty is removed.
+# release:region-remove <dest> takes the region, its directive, and its end marker out, and the blank line
+# before it; a file left empty is removed.
 release:region-remove() {
   local path begin end
   path=$(release:target "$1")
   [[ -f "${path}" ]] || return 0
-  { read -r begin; read -r end; } < <(release:region-markers "$1" "$2")
+  { read -r begin; read -r end; } < <(release:region-markers "$1")
   awk -v b="${begin}" -v e="${end}" '
     $0 == b { skip = 1; held = 0; next }
     $0 == e { skip = 0; next }
@@ -689,7 +697,7 @@ release:place() {
       release:json-write "${path}" 'merge(.; $base[0]; $new[0])' --slurpfile new "${src}" --slurpfile base "${base}"
       ;;
     (region)
-      release:region-write "${path}" "$(release:region-module "${src}")" "${src}"
+      release:region-write "${path}" "${src}"
       ;;
     (*)
       path=$(release:target "${path}")
@@ -704,7 +712,7 @@ release:place() {
 release:installed() {
   local src=$1 path=$2
   case "$(release:kind "${src}" "${path}")" in
-    (region) release:region-read "${path}" "$(release:region-module "${src}")" ;;
+    (region) release:region-read "${path}" ;;
     (*) [[ -f "${path}" ]] && cat "${path}" ;;
   esac
 }
@@ -720,8 +728,8 @@ release:holds() {
 }
 
 # release:place-new <source> <path> [<label>] places content the repository did not record: where there is
-# nothing, or the same thing, a .json to merge into, or a file to carry a region. A different file, or a region
-# with different content, is refused, named, and left as it is.
+# nothing, or the same thing, a .json to merge into, or a file to carry a region. A region already there is made
+# what its command makes it. A different file is refused, named, and left as it is.
 release:place-new() {
   local src=$1 path=$2 label=${3:-} kind
   kind=$(release:kind "${src}" "${path}")
@@ -740,8 +748,8 @@ release:place-new() {
     step "${path}${label:+: ${label}}, already as the release has it"
   elif [[ "${kind}" == region ]]
   then
-    error "${path}: the kit's region is there with different content; make it the release's, or remove it"
-    return 1
+    step "${path}${label:+: ${label}}, the region regenerated"
+    release:place "${src}" "${path}"
   else
     error "${path}: a different file is there already; move it aside, or remove it if it is not yours"
     return 1
@@ -773,7 +781,7 @@ release:unplace() {
       ;;
     (region)
       step "${path}: the kit's region taken out"
-      release:region-remove "${path}" "$(release:region-module "${src}")"
+      release:region-remove "${path}"
       ;;
     (*)
       step "removing ${path}"
diff --git a/docs/architecture.md b/docs/architecture.md
index b92b349..d6fd0ea 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -25,8 +25,9 @@ dependencies, renders, places, and writes the manifests. `kit update` moves to a
 an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
 fails when a delivered file differs from the release's. `kit module` changes the active set. Three rules govern
 placement: a `.json` destination, other than a schema, is merged by key, the kit owning only the entries it writes; a
-region is written between marker comments inside a file the repository owns, the kit holding only what is
-between them; everything else is a copy.
+region is opened inside a file the repository owns by a `:generate:` directive naming `kit region`, and `kit
+generate` makes it what that command makes it, as it makes every region any file in the repository declares, see
+[generate.md](generate.md); everything else is a copy.
 
 Each base has a manifest: `.kit/manifest`, committed with the repository, and `~/.kit/manifest` on the desk when a
 module delivers there. A manifest records the version, the active modules, and the release's digest of every
diff --git a/docs/delivery.svg b/docs/delivery.svg
index 45b7094..a8e5621 100644
--- a/docs/delivery.svg
+++ b/docs/delivery.svg
@@ -60,7 +60,7 @@
   <line x1="396" y1="286" x2="644" y2="286" stroke="#a78bfa" stroke-width="1"/>
   <text class="d" x="396" y="308">resolve the active set and its depends</text>
   <text class="d" x="396" y="326">render @key@ from .kit/settings.yml</text>
-  <text class="d" x="396" y="344">merge a .json destination by key; write a region</text>
+  <text class="d" x="396" y="344">merge a .json destination by key; generate a region</text>
   <text class="d" x="396" y="362">copy everything else</text>
   <text class="d" x="396" y="380">digest each path into the manifest</text>
   <text class="d" x="396" y="398">three-way merge an edited file on update</text>
diff --git a/docs/generate.md b/docs/generate.md
new file mode 100644
index 0000000..da5f134
--- /dev/null
+++ b/docs/generate.md
@@ -0,0 +1,82 @@
+# Generate
+
+A region is a stretch of a file that a command makes and a person does not edit: a table drawn from the
+manifests, a list of verbs drawn from their help, the sentence the kit puts in `AGENTS.md`. The file itself says
+how each region is made, with a directive in its own comment syntax, and `kit generate` makes every region what
+its command makes it. A hand edit is then a stale region, and `kit check` fails on one wherever `kit ci` runs.
+The mechanism is enchiridion's `:generate:` channel, carried into the kit so any repository has it.
+
+## The directive
+
+A comment line that is the directive and nothing else opens a region:
+
+```text
+:generate:<command>:until:"<pattern>"
+:generate:<command>:while:"<pattern>"
+```
+
+The directive line stays. The command runs from the repository root, with the running kit's `bin/` first on
+`PATH`, and its standard output replaces the lines after the directive. With `until`, the region runs up to the
+first later line matching the pattern, an extended regular expression, and that line stays as the end marker.
+With `while`, the region is every line matching the pattern, and the first line that does not match ends it. So
+a markdown page carries:
+
+```markdown
+<!-- :generate:kit region AGENTS.md:until:"kit:end" -->
+Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
+repository trustworthy.
+<!-- kit:end -->
+```
+
+and a shell script or a `.gitignore` carries the same with `#`, a JavaScript file with `//`, a SQL file with
+`--`. The comment openers the kit reads are `#`, `//`, `--`, `<!--`, `/*`, `%`, and `;`. A line that is not a
+comment opened by one of them is not a directive, so a page may mention the syntax in prose or a code span, and a
+directive inside a fenced code block is not live, so a page may show one whole.
+
+The command is one command and its arguments, with no shell operator: no pipe, no `&&`, no redirection, no
+substitution. A word is a name, a flag, a path, or a `key=value` pair. What makes a region is therefore always a
+kit verb, a just recipe, a make target, or a script in the tree, where it is listed, read, and tested, and never
+a one-liner hidden in a comment. A command outside that shape is refused by file and line.
+
+## The verbs
+
+`kit generate [<path>…]` expands the named files, taken from the directory the command was typed in, or with
+none named every tracked file and every untracked one git does not ignore. Named files are expanded once, or
+`--iterations=<n>` times. The whole repository is expanded until a pass changes nothing, at most twenty passes or
+`--iterations=<n>`, since a region's output may depend on another region's. A run that is still changing at the
+bound fails, naming the cause: a command whose output depends on its own output.
+
+`kit generate --check [<path>…]` runs one pass without writing and fails naming every stale file. `kit check`
+runs it over the whole repository, so the gate holds every generated region, the kit's and the repository's own,
+and the lefthook module's pre-commit hook runs it over the staged paths.
+
+`kit region [--home] <path>` prints the content the active modules deliver as the region at a path, the command
+behind every region the kit delivers. One active module delivers a region at a path, so the answer is that
+module's `regions/<base>/<path>`, and a path no active module delivers is refused.
+
+## What is refused
+
+A file is rewritten only on a clean expansion. Each of these leaves the file as it was and fails the run, naming
+the file and the line:
+
+- a command that fails;
+- an `until` pattern no later line matches, so the region never closes;
+- a command outside its shape;
+- a conflict marker in the file, a line of seven `<` or `>`, since a conflicted file is not input a region
+  expander can read;
+- an expansion that produces nothing from a file that was not empty.
+
+## The kit's regions
+
+A file under a module's `regions/<base>/<path>` is the content of a region. What `kit install` writes into the
+file at `<path>` is the directive naming `kit region <path>`, the content, and the end marker, in the file's
+comment syntax: between the directive and the end marker where the file already carries them, appended after a
+blank line where it does not, and as the whole file where there is none. The repository moves the block where it
+likes and writes what it likes around it. `kit update` regenerates the region, and there is no three-way merge of
+one, since its content is never the repository's to edit; `kit module remove` takes the block out, and removes a
+file it leaves empty. A directive with no end marker is refused by name, and two modules delivering a region to
+one file are refused where the modules are read.
+
+The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to `.kit/1st.md`, and the
+`/worktrees/` entry in `.gitignore`. The `claude` module places one in `.claude/CLAUDE.md`, importing
+`AGENTS.md`. [modules.md](modules.md) describes a module, and [architecture.md](architecture.md) the whole.
diff --git a/docs/modules.md b/docs/modules.md
index 3862a61..2b5c937 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -60,14 +60,16 @@ than a schema, `*.schema.json`, is merged by key: the kit's keys are set, its ar
 removal only the previous release's entries are taken out, so a repository's own keys and entries survive. Every other
 destination is a copy. Where two active modules deliver the same path, the later module in dependency order wins.
 
-A file under `regions/<base>/` is placed as a region inside the file at the same path: its content between two
-marker comments naming the module, `<!-- kit:begin kit -->` and `<!-- kit:end kit -->` in markdown, `# kit:begin
-kit` and `# kit:end kit` elsewhere. Where the file has no region, one is appended after a blank line; where there
-is no file, it is made of the region alone. The repository may move the region anywhere in the file and write
-what it likes around it. `kit check` holds only the content between the markers to the release, `kit update`
-replaces or three-way merges only that, and removal takes the region out and leaves the rest, removing a file it
-leaves empty. The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to `.kit/1st.md`,
-and the `/worktrees/` entry in `.gitignore`.
+A file under `regions/<base>/` is the content of a region inside the file at the same path. What is placed there is a
+`:generate:` directive naming `kit region <path>`, the content, and a `kit:end` marker, in the file's own comment
+syntax: `<!-- … -->` in markdown, `#` elsewhere, as [generate.md](generate.md) describes. Where the file carries the
+directive already, the content between it and the end marker is made what the command makes it; where it does not, the
+block is appended after a blank line; where there is no file, it is made of the block alone. The repository may move the
+block anywhere in the file and write what it likes around it. `kit check` holds the region to its command, `kit update`
+regenerates it, never merges it, and removal takes the block out and leaves the rest, removing a file it leaves empty.
+One file holds one kit region, and two modules delivering a region to the same path are refused by name. A kind of file
+the kit cannot mark is refused. The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to
+`.kit/1st.md`, and the `/worktrees/` entry in `.gitignore`.
 
 A file under `templates/<base>/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
 answer, then the result is placed, digested, and merged exactly as a `files/` file is. The form is one neither
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index 8282424..8ce6588 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -3,9 +3,9 @@
 The adapter for Claude Code. Claude Code reads `AGENTS.md` only as a fallback: when no `CLAUDE.md`,
 `.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and where its
 configuration allows. A repository with a `CLAUDE.md` of its own would have `AGENTS.md` skipped. So the module
-places a region in `.claude/CLAUDE.md` holding `@../AGENTS.md`: Claude then reads what every other agent reads in
-every case, the rest of that file and a root `CLAUDE.md` are the repository's own, and `kit check` holds only
-the region. It also merges into
+places a region in `.claude/CLAUDE.md` holding `@../AGENTS.md`, opened by a `:generate:` directive `kit
+generate` fills: Claude then reads what every other agent reads in every case, the rest of that file and a root
+`CLAUDE.md` are the repository's own, and `kit check` holds only the region. It also merges into
 `.claude/settings.json`, by key, leaving the repository's own entries:
 
 - `permissions.deny`: the spellings `.kit/1st.md` forbids an agent, `git rebase`, `git worktree add`,
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
index 5728379..1e6a28a 100644
--- a/modules/kit/docs/README.md
+++ b/modules/kit/docs/README.md
@@ -6,7 +6,8 @@ The core, active in every repository that takes the kit. It places:
 - `.kit/rules/<kind>.md`, one rule file per kind of file, each declaring in its frontmatter which paths and which
   first lines it governs, and the linter `kit lint` runs over them.
 - A region in `AGENTS.md`, the sentence that sends every agent to `.kit/1st.md`, and a region in `.gitignore`,
-  the `/worktrees/` entry the loop needs; the rest of each file is the repository's.
+  the `/worktrees/` entry the loop needs; each opened by a `:generate:` directive that `kit generate` fills
+  through `kit region`, and the rest of each file is the repository's.
 
 The rules are discovered through `kit context`, described in
 [docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md). Adding a kind is adding one rule
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index c7e65ce..eca00f6 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -96,11 +96,13 @@ carries the machinery, reached through the `kit` command on `PATH`: the loop's c
 delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
 lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
-key, the kit owning only the entries it writes; a region is held between its markers inside a file the
-repository owns; everything else is copied as it is.
+key, the kit owning only the entries it writes; a region inside a file the repository owns is opened by a
+`:generate:` directive and made by the command it names, through `kit generate`; everything else is copied as it
+is.
 
 - `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
-  `.gitignore`, each a region the kit owns inside a file the repository owns.
+  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a
+  `:generate:` directive of the repository's own, and `kit check` holds every region to its command.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/modules/lefthook/docs/README.md b/modules/lefthook/docs/README.md
index beff980..15c17a4 100644
--- a/modules/lefthook/docs/README.md
+++ b/modules/lefthook/docs/README.md
@@ -1,7 +1,7 @@
 # The lefthook module
 
-Places `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths, so each rule's own
-linter runs over the paths the rule governs before a commit. The repository's own `lefthook.yml` takes it with
-`extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name. The repository pins
-`lefthook` itself, since only a desk runs a hook, and `kit lint` runs the same linters with no hook manager at
-all.
+Places `.kit/lefthook.yml`, a pre-commit hook with two commands over the staged paths: `kit lint`, so each rule's own
+linter runs over the paths the rule governs before a commit, and `kit generate --check`, so a stale generated region is
+refused before it is committed. The repository's own `lefthook.yml` takes it with `extends: [.kit/lefthook.yml]` and
+adds commands of its own; Lefthook merges by name. The repository pins `lefthook` itself, since only a desk runs a hook,
+and `kit lint` and `kit generate` run the same way with no hook manager at all.
diff --git a/modules/lefthook/files/repo/.kit/lefthook.yml b/modules/lefthook/files/repo/.kit/lefthook.yml
index 8fa1f10..46fc359 100644
--- a/modules/lefthook/files/repo/.kit/lefthook.yml
+++ b/modules/lefthook/files/repo/.kit/lefthook.yml
@@ -11,3 +11,5 @@ pre-commit:
   commands:
     kit-lint:
       run: kit lint {staged_files}
+    kit-generate:
+      run: kit generate --check {staged_files}
diff --git a/tests/generate.bats b/tests/generate.bats
new file mode 100644
index 0000000..cf0e231
--- /dev/null
+++ b/tests/generate.bats
@@ -0,0 +1,101 @@
+#!/usr/bin/env bats
+# generate.bats - a :generate: directive opens a region its command fills, to a fixed point, held by --check
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  kit_checkout=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
+  work=$(mktemp -d)
+  cd "${work}"
+  git init --quiet --initial-branch=main
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  # A generator in the tree: a script that prints its arguments, one per line, so a region's content is visible.
+  printf '#!/usr/bin/env bash\nprintf "%%s\\n" "$@"\n' > lines.sh && chmod +x lines.sh
+}
+
+teardown() {
+  rm -rf "${work}"
+}
+
+@test "until fills the region up to its end marker, which stays, and while replaces every matching line" {
+  printf 'before\n<!-- :generate:./lines.sh one two:until:"^<!-- end -->$" -->\nstale\n<!-- end -->\nafter\n' > a.md
+  printf '# :generate:./lines.sh x=1 y=2:while:"^[a-z]+=[0-9]+$"\nold=0\nolder=0\nkeep this\n' > b.toml
+  run "${kit_checkout}/bin/kit" generate a.md b.toml
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"a.md: regenerated"* ]]
+  [ "$(paste -s -d '|' - < a.md)" = 'before|<!-- :generate:./lines.sh one two:until:"^<!-- end -->$" -->|one|two|<!-- end -->|after' ]
+  [ "$(paste -s -d '|' - < b.toml)" = '# :generate:./lines.sh x=1 y=2:while:"^[a-z]+=[0-9]+$"|x=1|y=2|keep this' ]
+  run "${kit_checkout}/bin/kit" generate a.md b.toml
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"settled in 1 pass"* ]]
+}
+
+@test "the whole repository is discovered, tracked or not, and --check names a stale file without writing it" {
+  printf '<!-- :generate:./lines.sh fresh:until:"end" -->\nstale\n<!-- end -->\n' > a.md
+  mkdir sub && printf '# :generate:./lines.sh deep:until:"end"\n# end\n' > sub/b.yml
+  printf 'no directive here\n' > c.md
+  git add a.md && printf 'ignored/\n' > .gitignore && mkdir ignored && cp a.md ignored/d.md
+  run "${kit_checkout}/bin/kit" generate --check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"a.md: stale; run: kit generate"* ]]
+  [[ "$output" == *"sub/b.yml: stale"* ]]
+  [[ "$output" != *"ignored/d.md"* ]]
+  [[ "$output" == *"2 of 2 generated file(s) are stale"* ]]
+  grep --quiet '^stale$' a.md
+  cd sub
+  run "${kit_checkout}/bin/kit" generate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"settled in 2 pass(es)"* ]]
+  [ "$(paste -s -d '|' - < b.yml)" = '# :generate:./lines.sh deep:until:"end"|deep|# end' ]
+  run "${kit_checkout}/bin/kit" generate --check b.yml ../c.md
+  [ "$status" -eq 0 ]
+  run "${kit_checkout}/bin/kit" generate --check ../c.md
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no :generate: directive to expand"* ]]
+}
+
+@test "a command is one command and its arguments, and a failing one, an unclosed region, or an empty result leaves the file as it was" {
+  printf '<!-- :generate:./lines.sh a | cat:until:"end" -->\n<!-- end -->\n' > pipe.md
+  run "${kit_checkout}/bin/kit" generate pipe.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"pipe.md:1: a :generate: command is one command and its arguments, with no shell operator: ./lines.sh a | cat"* ]]
+  printf '<!-- :generate:./missing.sh:until:"end" -->\nheld\n<!-- end -->\n' > fail.md
+  run "${kit_checkout}/bin/kit" generate fail.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"fail.md:1: the command failed: ./missing.sh"* ]]
+  grep --quiet '^held$' fail.md
+  printf 'top\n<!-- :generate:./lines.sh a:until:"never" -->\nheld\n' > open.md
+  run "${kit_checkout}/bin/kit" generate open.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *'open.md:2: the region never closes; no later line matches "never"'* ]]
+  grep --quiet '^held$' open.md
+  printf '<<<<<<< ours\n<!-- :generate:./lines.sh a:until:"end" -->\n<!-- end -->\n>>>>>>> theirs\n' > conflict.md
+  run "${kit_checkout}/bin/kit" generate conflict.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"conflict.md carries an unresolved conflict"* ]]
+}
+
+@test "a directive inside a fenced code block is not live, and a region inside a symlinked file lands in its target" {
+  printf '```markdown\n<!-- :generate:./lines.sh shown:until:"end" -->\n<!-- end -->\n```\nprose\n' > doc.md
+  run "${kit_checkout}/bin/kit" generate doc.md
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no :generate: directive"* || "$output" == *"settled"* ]]
+  ! grep --quiet '^shown$' doc.md
+  mkdir real && printf '# :generate:./lines.sh linked:until:"end"\n# end\n' > real/x.sh && ln -s real/x.sh x.sh
+  run "${kit_checkout}/bin/kit" generate x.sh
+  [ "$status" -eq 0 ]
+  [ -L x.sh ]
+  grep --quiet '^linked$' real/x.sh
+}
+
+@test "a command runs with the running kit first on PATH, so kit region fills the kit's own regions" {
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  printf '## Ours\n' >> AGENTS.md
+  run env PATH="$(dirname "$(command -v bash)"):/usr/bin:/bin" "${kit_checkout}/bin/kit" generate --check
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"every region as its command makes it"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 805e76e..b3fea55 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -68,7 +68,7 @@ later-release() {
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
   grep --quiet --line-regexp '@../AGENTS.md' .claude/CLAUDE.md
-  grep --quiet --line-regexp '<!-- kit:begin claude -->' .claude/CLAUDE.md
+  grep --quiet --line-regexp '<!-- :generate:kit region .claude/CLAUDE.md:until:"kit:end" -->' .claude/CLAUDE.md
   [ ! -e .claude/rules ]
 }
 
@@ -247,7 +247,8 @@ later-release() {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
   [ "$(sed -n '1,3p' AGENTS.md | paste -s -d '|' -)" = "# Ours||Our own instructions." ]
-  grep --quiet --line-regexp '<!-- kit:begin kit -->' AGENTS.md
+  grep --quiet --line-regexp '<!-- :generate:kit region AGENTS.md:until:"kit:end" -->' AGENTS.md
+  grep --quiet --line-regexp '<!-- kit:end -->' AGENTS.md
   grep --quiet 'Read .kit/1st.md at the start of every session' AGENTS.md
   [ "$(sed -n '1p' .gitignore)" = "build/" ]
   grep --quiet --line-regexp '/worktrees/' .gitignore
@@ -260,12 +261,19 @@ later-release() {
   sed -i.bak 's/^Read .kit\/1st.md/Skip .kit\/1st.md/' AGENTS.md && rm AGENTS.md.bak
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 1 ]
-  [[ "$output" == *"AGENTS.md: the kit's region differs from the pinned release"* ]]
-  # at the same version the release is its own base, so the edit inside the region is kept
+  [[ "$output" == *"AGENTS.md: stale; run: kit generate"* ]]
+  run "${kit_checkout}/bin/kit" generate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"AGENTS.md: regenerated"* ]]
+  grep --quiet 'Read .kit/1st.md' AGENTS.md
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  # a region is what its command makes it: update regenerates an edited one rather than merging it
+  sed -i.bak 's/^Read .kit\/1st.md/Skip .kit\/1st.md/' AGENTS.md && rm AGENTS.md.bak
   run env PATH="$(shims mise curl)" "${kit_checkout}/bin/kit" update
   [ "$status" -eq 0 ]
-  [[ "$output" == *"AGENTS.md: the kit's region edited"* ]]
-  grep --quiet 'Skip .kit/1st.md' AGENTS.md
+  [[ "$output" == *"AGENTS.md: the region regenerated"* ]]
+  grep --quiet 'Read .kit/1st.md' AGENTS.md
   run "${kit_checkout}/bin/kit" module remove kit
   [ "$status" -eq 0 ]
   [ "$(cat AGENTS.md | paste -s -d '|' -)" = "# Ours||Our own instructions.|## More of ours" ]
@@ -277,7 +285,7 @@ later-release() {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
   [ -L AGENTS.md ]
-  grep --quiet 'kit:begin kit' docs/AGENTS.md
+  grep --quiet ':generate:kit region AGENTS.md' docs/AGENTS.md
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   run "${kit_checkout}/bin/kit" module remove kit
@@ -289,10 +297,10 @@ later-release() {
 }
 
 @test "a region that opens and never closes is refused by name, and two modules cannot share a region's file" {
-  printf '<!-- kit:begin kit -->\nhalf\n' > AGENTS.md
+  printf '<!-- :generate:kit region AGENTS.md:until:"kit:end" -->\nhalf\n' > AGENTS.md
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 1 ]
-  [[ "$output" == *"AGENTS.md: the kit's region opens with '<!-- kit:begin kit -->' and never closes"* ]]
+  [[ "$output" == *"AGENTS.md: the kit's region opens with '<!-- :generate:kit region AGENTS.md:until:\"kit:end\" -->' and never closes"* ]]
   rm AGENTS.md
   mkdir -p .kit/modules/extra/regions/repo
   printf 'description: "x"\ndepends:\n  - kit\n' > .kit/modules/extra/module.yml
@@ -304,24 +312,34 @@ later-release() {
   rm .kit/modules/extra/regions/repo/AGENTS.md
   run "${kit_checkout}/bin/kit" install extra
   [ "$status" -eq 0 ]
-  [ "$(sed -n '1p' config.toml)" = "# kit:begin extra" ]
+  [ "$(sed -n '1p' config.toml)" = '# :generate:kit region config.toml:until:"kit:end"' ]
+  [ "$("${kit_checkout}/bin/kit" region config.toml)" = "x = 1" ]
   printf 'const x = 1;\n' > .kit/modules/extra/regions/repo/lib.js
   run env PATH="$(shims mise curl)" "${kit_checkout}/bin/kit" update
   [ "$status" -eq 0 ]
-  [ "$(sed -n '1p' lib.js)" = "// kit:begin extra" ]
+  [ "$(sed -n '1p' lib.js)" = '// :generate:kit region lib.js:until:"kit:end"' ]
+  run "${kit_checkout}/bin/kit" region AGENTS.md
+  [ "$status" -eq 0 ]
+  [[ "$output" == "Read .kit/1st.md"* ]]
+  run "${kit_checkout}/bin/kit" region README.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"no active module delivers a region at README.md"* ]]
 }
 
-@test "a region makes the file where there is none, and refuses one holding a different region" {
+@test "a region makes the file where there is none, and one holding different content is regenerated" {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
-  [ "$(sed -n '1p' AGENTS.md)" = "<!-- kit:begin kit -->" ]
+  [ "$(sed -n '1p' AGENTS.md)" = '<!-- :generate:kit region AGENTS.md:until:"kit:end" -->' ]
   run "${kit_checkout}/bin/kit" module remove kit
   [ ! -e AGENTS.md ]
   [ ! -e .gitignore ]
-  printf '<!-- kit:begin kit -->\nsomething else\n<!-- kit:end kit -->\n' > AGENTS.md
+  printf '# Ours\n\n<!-- :generate:kit region AGENTS.md:until:"kit:end" -->\nsomething else\n<!-- kit:end -->\n' > AGENTS.md
   run "${kit_checkout}/bin/kit" module add kit
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"AGENTS.md: the kit's region is there with different content"* ]]
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"AGENTS.md: placed, the region regenerated"* ]]
+  [ "$(sed -n '1p' AGENTS.md)" = "# Ours" ]
+  grep --quiet 'Read .kit/1st.md' AGENTS.md
+  ! grep --quiet 'something else' AGENTS.md
 }
 
 @test "install keeps the repository's own settings keys and deny entries" {

From fbbd5e0c470c7d8d14d39299342792caf6597b16 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 01:47:11 -0700
Subject: [PATCH 094/108] #9 generate: a comment-agnostic kit:generate
 directive, named regions that nest, and bash command lines

A region opens on a line that is kit:generate <name>, optionally with a backticked command, framed by nothing
but punctuation, and closes on kit:end <name> framed the same way, so it is read without knowing the host's
comment syntax and a line of prose is never one. The command is a bash command line with pipes; with none
it is kit region, reading the name. Every unit is balanced on its own, the file and each command's output,
and an output's regions expand in turn, depth first. while: is gone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/generate.sh     | 262 +++++++++++++++++++++++++++++++-------------
 tests/generate.bats | 168 +++++++++++++++++++---------
 2 files changed, 297 insertions(+), 133 deletions(-)

diff --git a/bin/generate.sh b/bin/generate.sh
index b1b1fdc..e2ec416 100644
--- a/bin/generate.sh
+++ b/bin/generate.sh
@@ -1,40 +1,55 @@
 # shellcheck shell=bash
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
-# generate.sh - a directive opens a region a command fills: discovery, expansion, and the fixed point (sourced module)
+# shellcheck disable=SC2016  # the $ in a pattern anchors a line; nothing is meant to expand
+# generate.sh - a directive opens a named region a command fills: discovery, expansion, and the fixed point (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A comment line in a file's own syntax that is `:generate:<command>:until:"<pattern>"`, or `:while:"<pattern>"`,
-# and nothing else opens a region. The directive line stays. The command runs from the repository root, with the running kit's
-# bin/ first on PATH, and its stdout replaces the lines after the directive: up to the first line matching the
-# pattern for until, which stays, or every line matching it for while. So a region is a command's output living
-# inside a file a person owns, and the file itself says how it is made.
+# A line that is `kit:generate <name>`, or `kit:generate <name> `<command>``, with nothing but non-alphanumeric
+# characters before and after it, opens a region; a line that is `kit:end <name>` framed the same way closes it.
+# So the directive sits in any comment syntax, and is read without knowing one: `#`, `//`, `--`, `;`, `%`, `'`,
+# `<!-- -->`, `/* */`, and whatever else a language frames a comment with, since every such frame is punctuation,
+# and a line of prose has letters before the marker. The directive and the end marker stay; the command's
+# standard output replaces the lines between them. With no command, the command is `kit region`, which reads the
+# region's name as the path of a region an active module delivers.
 #
-# The command is one command and its arguments, with no shell operator, so what makes a region is always a verb,
-# a recipe, a target, or a script in the tree, where it can be read, listed, and tested, never a one-liner in a
-# comment. A directive inside a fenced code block is not live, so a page may show one.
+# The command is a bash command line, pipes and all, run from the repository root with the running kit's bin/
+# first on PATH, stdin closed, errexit and pipefail on, and the file and the region's name exported as
+# KIT_GENERATE_FILE and KIT_GENERATE_REGION. A literal backtick is the one thing a command cannot carry; $() does.
 #
-# A file is rewritten only on a clean expansion. A command that fails, an until pattern no later line matches, a
-# conflict marker in the file, an empty result from a file that was not, or a command outside its shape leaves
-# the file as it was and fails the run, naming the file and the line.
+# Every unit is balanced on its own: the file as written, and each command's output. An output may open regions
+# of its own, each closed in that same output, and they are expanded in turn, depth first, so a region nests and
+# one pass settles a file. An output that closes a region it did not open, or opens one it does not close, holds
+# the file. A line that opens with the marker and is not a directive holds the file too, so a misspelled one is
+# never silently skipped; a line of prose, with letters before the marker, is not read at all. In markdown, a
+# fenced code block is not live, so a page may show a directive whole.
+#
+# A file is rewritten only on a clean expansion. A command that fails, an unbalanced unit, a malformed marker, a
+# name opened twice, or a conflict marker in the file leaves the file as it was and fails the run, naming the
+# file and the line.
 #
 # see: bin/kit-generate.sh, bin/kit-region.sh, docs/generate.md
 
-# The directive's shape: a line that is a comment, opened by one of the comment openers the kit knows, carrying
-# the directive and nothing before it, so a mention of the syntax inside prose, a code span, or a string in a
-# script is not one. Captures: the opener, the command, until or while, and the pattern.
-declare -g generate_directive_re='^[[:space:]]*(#|//|--|<!--|/\*|%|;)[[:space:]]*:generate:(.+):(until|while):[[:space:]]*"([^"]+)"'
-
-# The command's shape: words of letters, digits, and the characters a name, a flag, a path, or a key=value
-# pair is made of, and no shell operator.
-declare -g generate_command_re='^[A-Za-z0-9_./=:@~%,+-]+([[:space:]]+[A-Za-z0-9_./=:@~%,+-]+)*$'
+# The marker's shapes. A line is read as a directive only when nothing but non-alphanumeric characters frames it:
+# the comment opener before, the comment closer after. The name is any run without whitespace or a backtick,
+# the command everything between the first backtick after the name and the last one before the closer.
+declare -g generate_open_re='^[^[:alnum:]]*kit:generate[[:space:]]+([^[:space:]`]+)([[:space:]]+`(.+)`)?[^[:alnum:]]*$'
+declare -g generate_end_re='^[^[:alnum:]]*kit:end[[:space:]]+([^[:space:]`]+)[^[:alnum:]]*$'
+# A line that opens with a marker is a directive or an error, never prose.
+declare -g generate_marker_re='^[^[:alnum:]]*kit:(generate|end)([^[:alnum:]]|$)'
+declare -g generate_fence_re='^[[:space:]]*(```|~~~)'
 
 # An unresolved conflict's shape: a line of seven < or > alone or followed by git's label. The middle marker,
 # seven =, is also a markdown heading underline and is never written without the opening one, so it is not read.
 declare -g generate_conflict_re='^(<{7}|>{7})([[:space:]].*)?$'
 
-# generate:carries <file> is true when the file carries a directive.
+# generate:carries <file> is true when the file has a line that opens with a marker.
 generate:carries() {
-  [[ -f "$1" ]] && grep --quiet --extended-regexp "${generate_directive_re}" "$1"
+  [[ -f "$1" ]] && grep --quiet --extended-regexp "${generate_marker_re}" "$1"
+}
+
+# generate:markdown <file> is true for a markdown file, the one kind where a fenced code block is not live.
+generate:markdown() {
+  [[ "$1" == *.md || "$1" == *.markdown ]]
 }
 
 # generate:discover [<path>…] prints every file under the paths, or the whole repository, that carries a
@@ -65,12 +80,147 @@ generate:target() {
   fi
 }
 
-# generate:expand <file> <mode> expands the file's directives into a sibling temp file and compares. It returns 0
+# generate:command <file> <line> <name> <command> <out> runs one region's command with its stdout in <out>.
+generate:command() {
+  local file=$1 number=$2 name=$3 command=$4 out=$5
+  if ! KIT_GENERATE_FILE="${file}" KIT_GENERATE_REGION="${name}" PATH="${kit_root}/bin:${PATH}" \
+    bash -o errexit -o pipefail -c "${command}" </dev/null >"${out}"
+  then
+    error "${file}:${number}: the command failed: ${command}"
+    return 2
+  fi
+}
+
+# generate:unit <in> <out> <file> <where> <markdown> expands one unit, the file or a command's output, from <in>
+# into <out>. <where> opens every message: the file's path for the file, and for an output the file, the line
+# of the directive, and the command. Two passes: the first holds the unit to its shape, every marker line a
+# directive and every region opened and closed here, in order; the second runs each top-level region's command,
+# expands the output as a unit of its own, and writes the result between the markers.
+generate:unit() {
+  local in=$1 out=$2 file=$3 where=$4 markdown=$5
+  local -a lines stack opened
+  local n i j line fence=false depth name command body result
+  mapfile -t lines < "${in}"
+  n=${#lines[@]}
+  stack=()
+  opened=()
+  for (( i = 0; i < n; i++ ))
+  do
+    line=${lines[i]}
+    if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
+    then
+      if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+      continue
+    fi
+    [[ "${fence}" == false && "${line}" =~ ${generate_marker_re} ]] || continue
+    if [[ "${line}" =~ ${generate_open_re} ]]
+    then
+      stack+=("${BASH_REMATCH[1]}")
+      opened+=("$(( i + 1 ))")
+    elif [[ "${line}" =~ ${generate_end_re} ]]
+    then
+      name=${BASH_REMATCH[1]}
+      if (( ${#stack[@]} == 0 ))
+      then
+        error "${where}:$(( i + 1 )): closes '${name}', which is not open"
+        return 2
+      fi
+      if [[ "${stack[-1]}" != "${name}" ]]
+      then
+        error "${where}:$(( i + 1 )): closes '${name}' while '${stack[-1]}' is open"
+        return 2
+      fi
+      unset 'stack[-1]' 'opened[-1]'
+    else
+      error "${where}:$(( i + 1 )): not a directive: ${line}"
+      return 2
+    fi
+  done
+  if (( ${#stack[@]} > 0 ))
+  then
+    error "${where}:${opened[-1]}: the region '${stack[-1]}' never closes"
+    return 2
+  fi
+  : > "${out}"
+  fence=false
+  i=0
+  while (( i < n ))
+  do
+    line=${lines[i]}
+    printf '%s\n' "${line}" >> "${out}"
+    if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
+    then
+      if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+      i=$(( i + 1 ))
+      continue
+    fi
+    if [[ "${fence}" == true ]] || ! [[ "${line}" =~ ${generate_open_re} ]]
+    then
+      i=$(( i + 1 ))
+      continue
+    fi
+    name=${BASH_REMATCH[1]}
+    command=${BASH_REMATCH[3]:-kit region}
+    body=$(mktemp)
+    result=$(mktemp)
+    if ! generate:command "${file}" "$(( i + 1 ))" "${name}" "${command}" "${body}" \
+      || ! generate:unit "${body}" "${result}" "${file}" "${where}:$(( i + 1 )) (the output of ${command})" "${markdown}"
+    then
+      rm -f "${body}" "${result}"
+      return 2
+    fi
+    cat "${result}" >> "${out}"
+    rm -f "${body}" "${result}"
+    # The old body is skipped to this region's end, by depth, since the first pass proved the nesting.
+    depth=1
+    for (( j = i + 1; depth > 0; j++ ))
+    do
+      line=${lines[j]}
+      if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
+      then
+        if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+        continue
+      fi
+      [[ "${fence}" == false ]] || continue
+      if [[ "${line}" =~ ${generate_open_re} ]]
+      then depth=$(( depth + 1 ))
+      elif [[ "${line}" =~ ${generate_end_re} ]]
+      then depth=$(( depth - 1 ))
+      fi
+    done
+    printf '%s\n' "${lines[j - 1]}" >> "${out}"
+    i=${j}
+  done
+}
+
+# generate:twice <file> prints the first region name the file opens twice, outside a markdown fence, or nothing.
+generate:twice() {
+  local file=$1 line fence=false markdown
+  local -A seen=()
+  markdown=false
+  generate:markdown "$2" && markdown=true
+  while IFS= read -r line || [[ -n "${line}" ]]
+  do
+    if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
+    then
+      if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+      continue
+    fi
+    [[ "${fence}" == false && "${line}" =~ ${generate_open_re} ]] || continue
+    if [[ -n "${seen[${BASH_REMATCH[1]}]+x}" ]]
+    then
+      printf '%s\n' "${BASH_REMATCH[1]}"
+      return 0
+    fi
+    seen[${BASH_REMATCH[1]}]=1
+  done < "${file}"
+}
+
+# generate:expand <file> <mode> expands the file's regions into a sibling temp file and compares. It returns 0
 # when nothing changed, 1 when the file was rewritten (mode write) or is stale (mode check), and 2 when it could
 # not be cleanly expanded, in which case the file is left as it was. Only mode write ever writes.
 generate:expand() {
-  local file=$1 mode=${2:-write} target temp line number=0 fence=false seeking='' pattern='' opened=0 command rc
-  local -a words
+  local file=$1 mode=${2:-write} target temp markdown=false twice
   if [[ ! -f "${file}" ]]
   then
     error "generate: no such file: ${file}"
@@ -84,62 +234,16 @@ generate:expand() {
   target=$(generate:target "${file}")
   temp="${target}.kit-new"
   cp -p "${target}" "${temp}"
-  rc=0
-  {
-    while IFS= read -r line || [[ -n "${line}" ]]
-    do
-      number=$(( number + 1 ))
-      if [[ "${seeking}" == until ]]
-      then
-        [[ "${line}" =~ ${pattern} ]] || continue
-        seeking=''
-      elif [[ "${seeking}" == while ]]
-      then
-        [[ "${line}" =~ ${pattern} ]] && continue
-        seeking=''
-      fi
-      printf '%s\n' "${line}"
-      if [[ "${line}" =~ ^[[:space:]]*(\`\`\`|~~~) ]]
-      then
-        if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
-        continue
-      fi
-      [[ "${fence}" == false && "${line}" =~ ${generate_directive_re} ]] || continue
-      command=${BASH_REMATCH[2]}
-      seeking=${BASH_REMATCH[3]}
-      pattern=${BASH_REMATCH[4]}
-      opened=${number}
-      command=${command#"${command%%[![:space:]]*}"}
-      command=${command%"${command##*[![:space:]]}"}
-      if [[ ! "${command}" =~ ${generate_command_re} ]]
-      then
-        error "${file}:${number}: a :generate: command is one command and its arguments, with no shell operator:" \
-          "${command}"
-        rc=2
-        break
-      fi
-      read -r -a words <<<"${command}"
-      if ! PATH="${kit_root}/bin:${PATH}" "${words[@]}"
-      then
-        error "${file}:${number}: the command failed: ${command}"
-        rc=2
-        break
-      fi
-    done < "${file}"
-    if (( rc == 0 )) && [[ "${seeking}" == until ]]
-    then
-      error "${file}:${opened}: the region never closes; no later line matches \"${pattern}\""
-      rc=2
-    fi
-  } > "${temp}"
-  if (( rc != 0 ))
+  generate:markdown "${file}" && markdown=true
+  if ! generate:unit "${file}" "${temp}" "${file}" "${file}" "${markdown}"
   then
     rm -f "${temp}"
     return 2
   fi
-  if [[ -s "${file}" && ! -s "${temp}" ]]
+  twice=$(generate:twice "${temp}" "${file}")
+  if [[ -n "${twice}" ]]
   then
-    error "generate: expanding ${file} produced nothing; left as it was"
+    error "${file}: the region '${twice}' is opened twice"
     rm -f "${temp}"
     return 2
   fi
@@ -161,8 +265,8 @@ generate:expand() {
 
 # generate:run [--check] [--iterations=<n>] [<path>…] is the driver. Named files are expanded for one pass, or
 # <n>; with none named every file carrying a directive is expanded until a pass changes nothing, at most twenty
-# passes or <n>. --check runs one pass without writing and fails naming every stale file. A file that could not
-# be cleanly expanded fails the run whatever the mode.
+# passes or <n>, since a command may read another file's region. --check runs one pass without writing and fails
+# naming every stale file. A file that could not be cleanly expanded fails the run whatever the mode.
 generate:run() {
   local check=false limit=0 explicit=false arg file rc pass=0 changed failed stale
   local -a files=() targets=()
@@ -180,7 +284,7 @@ generate:run() {
   fi
   if (( ${#targets[@]} == 0 ))
   then
-    ok "generate: no :generate: directive to expand"
+    ok "generate: no kit:generate directive to expand"
     return 0
   fi
   if [[ "${check}" == true ]]
diff --git a/tests/generate.bats b/tests/generate.bats
index cf0e231..4f307c6 100644
--- a/tests/generate.bats
+++ b/tests/generate.bats
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# generate.bats - a :generate: directive opens a region its command fills, to a fixed point, held by --check
+# generate.bats - a kit:generate directive opens a named region its command fills, nested and balanced, held by --check
 # ----------------------------------------------------------------------------------------------------------------------
 
 setup() {
@@ -18,22 +18,122 @@ teardown() {
   rm -rf "${work}"
 }
 
-@test "until fills the region up to its end marker, which stays, and while replaces every matching line" {
-  printf 'before\n<!-- :generate:./lines.sh one two:until:"^<!-- end -->$" -->\nstale\n<!-- end -->\nafter\n' > a.md
-  printf '# :generate:./lines.sh x=1 y=2:while:"^[a-z]+=[0-9]+$"\nold=0\nolder=0\nkeep this\n' > b.toml
-  run "${kit_checkout}/bin/kit" generate a.md b.toml
+# joined <file> prints the file's lines joined by |, so a whole file is one assertion.
+joined() { paste -s -d '|' - < "$1"; }
+
+@test "a region is named, fills up to its end marker, and is read whatever comment syntax frames it" {
+  printf 'before\n<!-- kit:generate a `./lines.sh one two` -->\nstale\n<!-- kit:end a -->\nafter\n' > a.md
+  printf '# kit:generate b `./lines.sh x=1`\nold=0\n# kit:end b\nkeep this\n' > b.toml
+  printf '; kit:generate c `./lines.sh z`\n; kit:end c\n' > c.ini
+  printf "' kit:generate d \`./lines.sh v\`\n' kit:end d\n" > d.vb
+  run "${kit_checkout}/bin/kit" generate a.md b.toml c.ini d.vb
   [ "$status" -eq 0 ]
   [[ "$output" == *"a.md: regenerated"* ]]
-  [ "$(paste -s -d '|' - < a.md)" = 'before|<!-- :generate:./lines.sh one two:until:"^<!-- end -->$" -->|one|two|<!-- end -->|after' ]
-  [ "$(paste -s -d '|' - < b.toml)" = '# :generate:./lines.sh x=1 y=2:while:"^[a-z]+=[0-9]+$"|x=1|y=2|keep this' ]
-  run "${kit_checkout}/bin/kit" generate a.md b.toml
+  [ "$(joined a.md)" = 'before|<!-- kit:generate a `./lines.sh one two` -->|one|two|<!-- kit:end a -->|after' ]
+  [ "$(joined b.toml)" = '# kit:generate b `./lines.sh x=1`|x=1|# kit:end b|keep this' ]
+  [ "$(joined c.ini)" = '; kit:generate c `./lines.sh z`|z|; kit:end c' ]
+  [ "$(joined d.vb)" = "' kit:generate d \`./lines.sh v\`|v|' kit:end d" ]
+  run "${kit_checkout}/bin/kit" generate a.md b.toml c.ini d.vb
   [ "$status" -eq 0 ]
   [[ "$output" == *"settled in 1 pass"* ]]
 }
 
-@test "the whole repository is discovered, tracked or not, and --check names a stale file without writing it" {
-  printf '<!-- :generate:./lines.sh fresh:until:"end" -->\nstale\n<!-- end -->\n' > a.md
-  mkdir sub && printf '# :generate:./lines.sh deep:until:"end"\n# end\n' > sub/b.yml
+@test "a command is a bash command line: a pipe works, a failure holds the file, and the file and region are in its environment" {
+  printf '# kit:generate sorted `./lines.sh c b a | sort`\n# kit:end sorted\n' > sorted.txt
+  printf '# kit:generate env `printf "%%s %%s\\n" "$KIT_GENERATE_FILE" "$KIT_GENERATE_REGION"`\n# kit:end env\n' > env.txt
+  run "${kit_checkout}/bin/kit" generate sorted.txt env.txt
+  [ "$status" -eq 0 ]
+  [ "$(joined sorted.txt)" = '# kit:generate sorted `./lines.sh c b a | sort`|a|b|c|# kit:end sorted' ]
+  [ "$(sed -n '2p' env.txt)" = 'env.txt env' ]
+  printf '# kit:generate f `./lines.sh a | grep --quiet zzz`\nheld\n# kit:end f\n' > fail.txt
+  run "${kit_checkout}/bin/kit" generate fail.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"fail.txt:1: the command failed: ./lines.sh a | grep --quiet zzz"* ]]
+  grep --quiet '^held$' fail.txt
+  printf '# kit:generate m `./missing.sh`\nheld\n# kit:end m\n' > missing.txt
+  run "${kit_checkout}/bin/kit" generate missing.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"missing.txt:1: the command failed: ./missing.sh"* ]]
+  grep --quiet '^held$' missing.txt
+}
+
+@test "a region nests when its command's output opens one, and an output must be balanced on its own" {
+  printf '#!/usr/bin/env bash\nprintf "%%s\\n" "head" "# kit:generate inner \\`./lines.sh deep\\`" "# kit:end inner" "tail"\n' > nest.sh
+  chmod +x nest.sh
+  printf '# kit:generate outer `./nest.sh`\n# kit:end outer\n' > n.txt
+  run "${kit_checkout}/bin/kit" generate n.txt
+  [ "$status" -eq 0 ]
+  [ "$(joined n.txt)" = '# kit:generate outer `./nest.sh`|head|# kit:generate inner `./lines.sh deep`|deep|# kit:end inner|tail|# kit:end outer' ]
+  run "${kit_checkout}/bin/kit" generate --check
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"every region as its command makes it"* ]]
+  printf '# kit:generate outer `./lines.sh "# kit:end outer"`\nheld\n# kit:end outer\n' > close.txt
+  run "${kit_checkout}/bin/kit" generate close.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"close.txt:1 (the output of ./lines.sh \"# kit:end outer\"):1: closes 'outer', which is not open"* ]]
+  grep --quiet '^held$' close.txt
+  printf '# kit:generate outer `./lines.sh "# kit:generate loose \\`./lines.sh x\\`"`\nheld\n# kit:end outer\n' > open.txt
+  run "${kit_checkout}/bin/kit" generate open.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"open.txt:1 (the output of"*"):1: the region 'loose' never closes"* ]]
+  grep --quiet '^held$' open.txt
+}
+
+@test "an unbalanced, malformed, or repeated marker holds the file and names the line, as a conflict marker does" {
+  printf 'top\n# kit:end z\n' > stray.txt
+  run "${kit_checkout}/bin/kit" generate stray.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"stray.txt:2: closes 'z', which is not open"* ]]
+  printf '# kit:generate b `./lines.sh x`\n# kit:end a\n# kit:end b\n' > cross.txt
+  run "${kit_checkout}/bin/kit" generate cross.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"cross.txt:2: closes 'a' while 'b' is open"* ]]
+  printf 'top\n# kit:generate a `./lines.sh x`\nheld\n' > never.txt
+  run "${kit_checkout}/bin/kit" generate never.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"never.txt:2: the region 'a' never closes"* ]]
+  grep --quiet '^held$' never.txt
+  printf '# kit:generate\n# kit:end\n' > noname.txt
+  run "${kit_checkout}/bin/kit" generate noname.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"noname.txt:1: not a directive: # kit:generate"* ]]
+  printf '# kit:generate a `./lines.sh x`\n# kit:end a\n# kit:generate a `./lines.sh y`\n# kit:end a\n' > twice.txt
+  run "${kit_checkout}/bin/kit" generate twice.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"twice.txt: the region 'a' is opened twice"* ]]
+  printf '<<<<<<< ours\n# kit:generate a `./lines.sh x`\n# kit:end a\n>>>>>>> theirs\n' > conflict.txt
+  run "${kit_checkout}/bin/kit" generate conflict.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"conflict.txt carries an unresolved conflict"* ]]
+  printf 'x\n' > plain.txt
+  run "${kit_checkout}/bin/kit" generate plain.txt
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no kit:generate directive to expand"* ]]
+}
+
+@test "a line is a directive by what frames it: prose is not, a bare marker line is an error, and a markdown fence is not live" {
+  printf 'A kit:generate x line opens a region, and kit:end x closes it.\n' > prose.md
+  run "${kit_checkout}/bin/kit" generate --check prose.md
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no kit:generate directive"* ]]
+  printf -- '- kit:generate x is how a region opens\n' > bullet.md
+  run "${kit_checkout}/bin/kit" generate bullet.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"bullet.md:1: not a directive: - kit:generate x is how a region opens"* ]]
+  printf '```markdown\n<!-- kit:generate shown `./lines.sh shown` -->\n<!-- kit:end shown -->\n```\nprose\n' > doc.md
+  run "${kit_checkout}/bin/kit" generate doc.md
+  [ "$status" -eq 0 ]
+  run grep --quiet '^shown$' doc.md
+  [ "$status" -eq 1 ]
+  printf 'cat <<EOF\n```\nEOF\n# kit:generate s `./lines.sh live`\n# kit:end s\n' > fenced.sh
+  run "${kit_checkout}/bin/kit" generate fenced.sh
+  [ "$status" -eq 0 ]
+  grep --quiet '^live$' fenced.sh
+}
+
+@test "the whole repository is discovered, tracked or not, --check names a stale file without writing it, and a symlink lands in its target" {
+  printf '<!-- kit:generate a `./lines.sh fresh` -->\nstale\n<!-- kit:end a -->\n' > a.md
+  mkdir sub && printf '# kit:generate b `./lines.sh deep`\n# kit:end b\n' > sub/b.yml
   printf 'no directive here\n' > c.md
   git add a.md && printf 'ignored/\n' > .gitignore && mkdir ignored && cp a.md ignored/d.md
   run "${kit_checkout}/bin/kit" generate --check
@@ -47,55 +147,15 @@ teardown() {
   run "${kit_checkout}/bin/kit" generate
   [ "$status" -eq 0 ]
   [[ "$output" == *"settled in 2 pass(es)"* ]]
-  [ "$(paste -s -d '|' - < b.yml)" = '# :generate:./lines.sh deep:until:"end"|deep|# end' ]
+  [ "$(joined b.yml)" = '# kit:generate b `./lines.sh deep`|deep|# kit:end b' ]
   run "${kit_checkout}/bin/kit" generate --check b.yml ../c.md
   [ "$status" -eq 0 ]
-  run "${kit_checkout}/bin/kit" generate --check ../c.md
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"no :generate: directive to expand"* ]]
-}
-
-@test "a command is one command and its arguments, and a failing one, an unclosed region, or an empty result leaves the file as it was" {
-  printf '<!-- :generate:./lines.sh a | cat:until:"end" -->\n<!-- end -->\n' > pipe.md
-  run "${kit_checkout}/bin/kit" generate pipe.md
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"pipe.md:1: a :generate: command is one command and its arguments, with no shell operator: ./lines.sh a | cat"* ]]
-  printf '<!-- :generate:./missing.sh:until:"end" -->\nheld\n<!-- end -->\n' > fail.md
-  run "${kit_checkout}/bin/kit" generate fail.md
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"fail.md:1: the command failed: ./missing.sh"* ]]
-  grep --quiet '^held$' fail.md
-  printf 'top\n<!-- :generate:./lines.sh a:until:"never" -->\nheld\n' > open.md
-  run "${kit_checkout}/bin/kit" generate open.md
-  [ "$status" -eq 1 ]
-  [[ "$output" == *'open.md:2: the region never closes; no later line matches "never"'* ]]
-  grep --quiet '^held$' open.md
-  printf '<<<<<<< ours\n<!-- :generate:./lines.sh a:until:"end" -->\n<!-- end -->\n>>>>>>> theirs\n' > conflict.md
-  run "${kit_checkout}/bin/kit" generate conflict.md
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"conflict.md carries an unresolved conflict"* ]]
-}
-
-@test "a directive inside a fenced code block is not live, and a region inside a symlinked file lands in its target" {
-  printf '```markdown\n<!-- :generate:./lines.sh shown:until:"end" -->\n<!-- end -->\n```\nprose\n' > doc.md
-  run "${kit_checkout}/bin/kit" generate doc.md
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"no :generate: directive"* || "$output" == *"settled"* ]]
-  ! grep --quiet '^shown$' doc.md
-  mkdir real && printf '# :generate:./lines.sh linked:until:"end"\n# end\n' > real/x.sh && ln -s real/x.sh x.sh
+  cd ..
+  mkdir real && printf '# kit:generate l `./lines.sh linked`\n# kit:end l\n' > real/x.sh && ln -s real/x.sh x.sh
   run "${kit_checkout}/bin/kit" generate x.sh
   [ "$status" -eq 0 ]
   [ -L x.sh ]
   grep --quiet '^linked$' real/x.sh
 }
 
-@test "a command runs with the running kit first on PATH, so kit region fills the kit's own regions" {
-  run "${kit_checkout}/bin/kit" install
-  [ "$status" -eq 0 ]
-  printf '## Ours\n' >> AGENTS.md
-  run env PATH="$(dirname "$(command -v bash)"):/usr/bin:/bin" "${kit_checkout}/bin/kit" generate --check
-  [ "$status" -eq 0 ]
-  [[ "$output" == *"every region as its command makes it"* ]]
-}
-
 # ----------------------------------------------------------------------------------------------------------------------

From aa846783e9f30a5e38f5ebccfb2fa044b196c076 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 01:56:29 -0700
Subject: [PATCH 095/108] #9 the kit's regions are bare directives:
 kit:generate <path>, filled by kit region reading the name

Install writes kit:generate <path> and kit:end <path> in the file's comment syntax, with no command, and kit
region with no argument reads the region's name from KIT_GENERATE_REGION. A home region still spells its
command, since the bare form cannot say --home. This repository's own three regions are rewritten by hand,
since the old markers are no longer read.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .claude/CLAUDE.md   |  4 ++--
 .gitignore          |  4 ++--
 AGENTS.md           |  4 ++--
 bin/kit-region.sh   | 16 +++++++++-------
 bin/release.sh      | 28 +++++++++++++++++++---------
 tests/generate.bats | 15 +++++++++++++++
 tests/kit.bats      | 27 +++++++++++++++++----------
 7 files changed, 66 insertions(+), 32 deletions(-)

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index db5628d..af9f8b5 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,5 +1,5 @@
 # CLAUDE.md
 
-<!-- :generate:kit region .claude/CLAUDE.md:until:"kit:end" -->
+<!-- kit:generate .claude/CLAUDE.md -->
 @../AGENTS.md
-<!-- kit:end -->
+<!-- kit:end .claude/CLAUDE.md -->
diff --git a/.gitignore b/.gitignore
index 19a72d7..91c9424 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,9 @@
 # .gitignore - untracked files and folders
 # ----------------------------------------------------------------------------------------------------------------------
 
-# :generate:kit region .gitignore:until:"kit:end"
+# kit:generate .gitignore
 # per-issue worktrees for agents; see: .kit/1st.md
 /worktrees/
-# kit:end
+# kit:end .gitignore
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/AGENTS.md b/AGENTS.md
index 58f1c58..078a923 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
-<!-- :generate:kit region AGENTS.md:until:"kit:end" -->
+<!-- kit:generate AGENTS.md -->
 Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
 repository trustworthy.
-<!-- kit:end -->
+<!-- kit:end AGENTS.md -->
 
 This repository is the kit's own source, and uses it.
 
diff --git a/bin/kit-region.sh b/bin/kit-region.sh
index c1232f8..2fd14ac 100755
--- a/bin/kit-region.sh
+++ b/bin/kit-region.sh
@@ -2,10 +2,11 @@
 # kit-region - print the content the active modules deliver as the region at a path (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The command behind every region the kit delivers: the directive install writes into AGENTS.md reads
-# `:generate:kit region AGENTS.md:until:"kit:end"`, and kit generate runs this to fill it. The path is relative
-# to the repository, or with --home to the home directory. One active module delivers a region at a path, so
-# the answer is that module's regions/<base>/<path>, and a path no active module delivers is refused.
+# The command behind every region the kit delivers. Install writes a bare directive, `kit:generate AGENTS.md`,
+# and kit generate fills it by running `kit region` with the region's name in KIT_GENERATE_REGION; the path is
+# that name, or the argument, relative to the repository, or with --home to the home directory. One active
+# module delivers a region at a path, so the answer is that module's regions/<base>/<path>, and a path no
+# active module delivers is refused.
 #
 # see: bin/generate.sh, bin/release.sh
 
@@ -20,20 +21,21 @@ for arg in "$@"
 do
   case "${arg}" in
     (--help)
-      echo "usage: kit region [--home] <path>" >&2
+      echo "usage: kit region [--home] [<path>]    (the path defaults to KIT_GENERATE_REGION)" >&2
       exit 0
       ;;
     (--home) base=home ;;
     (-*)
-      error "unknown flag '${arg}' (usage: kit region [--home] <path>)"
+      error "unknown flag '${arg}' (usage: kit region [--home] [<path>])"
       exit 2
       ;;
     (*) path=${arg}
   esac
 done
+path=${path:-${KIT_GENERATE_REGION:-}}
 if [[ -z "${path}" ]]
 then
-  echo "usage: kit region [--home] <path>" >&2
+  echo "usage: kit region [--home] [<path>]    (the path defaults to KIT_GENERATE_REGION)" >&2
   exit 2
 fi
 release:require-manifest
diff --git a/bin/release.sh b/bin/release.sh
index e68a874..316f97b 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -409,23 +409,31 @@ release:kind() {
   fi
 }
 
-# release:region-command <dest> prints the command that makes the region at a destination: kit region with the
-# path relative to the base's root, and --home under the home directory.
+# release:region-name <dest> prints the region's name, which is the path relative to the base's root, and
+# release:region-command the command behind it: nothing under the repository, where the bare directive means
+# `kit region <name>`, and `kit region --home <name>` under the home directory, which the bare form cannot say.
+release:region-name() {
+  local home
+  home=$(release:base-root home)
+  if [[ "$1" == "${home}"/* ]]
+  then printf '%s\n' "${1#"${home}"/}"
+  else printf '%s\n' "$1"
+  fi
+}
 release:region-command() {
   local home
   home=$(release:base-root home)
   if [[ "$1" == "${home}"/* ]]
   then printf 'kit region --home %s\n' "${1#"${home}"/}"
-  else printf 'kit region %s\n' "$1"
   fi
 }
 
 # release:region-markers <dest> prints the region's two lines in the file's own comment syntax, by its extension,
-# an HTML comment, a double slash, a double dash, or a hash: the directive that opens it, naming the command and
-# the end marker, and the end marker. A kind of file with no comment syntax the kit knows is refused where the
-# module is read, in release:render-all.
+# an HTML comment, a double slash, a double dash, or a hash: the directive that opens it, `kit:generate <name>`
+# with the command in backticks where there is one, and the end marker, `kit:end <name>`. A kind of file with no
+# comment syntax the kit knows is refused where the module is read, in release:render-all.
 release:region-markers() {
-  local open close
+  local open close name command
   case "${1##*.}" in
     (md | markdown | html | htm | xml | svg) open='<!-- ' close=' -->' ;;
     (js | mjs | cjs | ts | tsx | jsx | go | rs | c | h | cc | cpp | hpp | java | kt | swift | cs | scala)
@@ -433,8 +441,10 @@ release:region-markers() {
     (sql | lua | hs) open='-- ' close='' ;;
     (*) open='# ' close='' ;;
   esac
-  printf '%s:generate:%s:until:"kit:end"%s\n%skit:end%s\n' "${open}" "$(release:region-command "$1")" "${close}" \
-    "${open}" "${close}"
+  name=$(release:region-name "$1")
+  command=$(release:region-command "$1")
+  printf '%skit:generate %s%s%s\n%skit:end %s%s\n' "${open}" "${name}" "${command:+ \`${command}\`}" "${close}" \
+    "${open}" "${name}" "${close}"
 }
 
 # release:region-known <path> is true where the kit knows the file's comment syntax, so a region can be marked.
diff --git a/tests/generate.bats b/tests/generate.bats
index 4f307c6..96f8a71 100644
--- a/tests/generate.bats
+++ b/tests/generate.bats
@@ -158,4 +158,19 @@ joined() { paste -s -d '|' - < "$1"; }
   grep --quiet '^linked$' real/x.sh
 }
 
+@test "a bare directive means kit region, which reads the name, so the kit's regions carry no command and need only kit on PATH" {
+  run "${kit_checkout}/bin/kit" install
+  [ "$status" -eq 0 ]
+  [ "$(sed -n '1p' AGENTS.md)" = '<!-- kit:generate AGENTS.md -->' ]
+  printf '## Ours\n' >> AGENTS.md
+  run env PATH="$(dirname "$(command -v bash)"):/usr/bin:/bin" "${kit_checkout}/bin/kit" generate --check
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"every region as its command makes it"* ]]
+  printf '# kit:generate nothing\n# kit:end nothing\n' > bare.txt
+  run "${kit_checkout}/bin/kit" generate bare.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"no active module delivers a region at nothing"* ]]
+  [[ "$output" == *"bare.txt:1: the command failed: kit region"* ]]
+}
+
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index b3fea55..0f9bb5b 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -68,7 +68,7 @@ later-release() {
   jq --exit-status '.permissions.deny | index("Bash(git rebase *)")' .claude/settings.json >/dev/null
   jq --exit-status '.hooks.PreToolUse[0].hooks[0].command == "kit context --claude"' .claude/settings.json >/dev/null
   grep --quiet --line-regexp '@../AGENTS.md' .claude/CLAUDE.md
-  grep --quiet --line-regexp '<!-- :generate:kit region .claude/CLAUDE.md:until:"kit:end" -->' .claude/CLAUDE.md
+  grep --quiet --line-regexp '<!-- kit:generate .claude/CLAUDE.md -->' .claude/CLAUDE.md
   [ ! -e .claude/rules ]
 }
 
@@ -247,8 +247,8 @@ later-release() {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
   [ "$(sed -n '1,3p' AGENTS.md | paste -s -d '|' -)" = "# Ours||Our own instructions." ]
-  grep --quiet --line-regexp '<!-- :generate:kit region AGENTS.md:until:"kit:end" -->' AGENTS.md
-  grep --quiet --line-regexp '<!-- kit:end -->' AGENTS.md
+  grep --quiet --line-regexp '<!-- kit:generate AGENTS.md -->' AGENTS.md
+  grep --quiet --line-regexp '<!-- kit:end AGENTS.md -->' AGENTS.md
   grep --quiet 'Read .kit/1st.md at the start of every session' AGENTS.md
   [ "$(sed -n '1p' .gitignore)" = "build/" ]
   grep --quiet --line-regexp '/worktrees/' .gitignore
@@ -285,7 +285,7 @@ later-release() {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
   [ -L AGENTS.md ]
-  grep --quiet ':generate:kit region AGENTS.md' docs/AGENTS.md
+  grep --quiet --line-regexp '<!-- kit:generate AGENTS.md -->' docs/AGENTS.md
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   run "${kit_checkout}/bin/kit" module remove kit
@@ -297,10 +297,10 @@ later-release() {
 }
 
 @test "a region that opens and never closes is refused by name, and two modules cannot share a region's file" {
-  printf '<!-- :generate:kit region AGENTS.md:until:"kit:end" -->\nhalf\n' > AGENTS.md
+  printf '<!-- kit:generate AGENTS.md -->\nhalf\n' > AGENTS.md
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 1 ]
-  [[ "$output" == *"AGENTS.md: the kit's region opens with '<!-- :generate:kit region AGENTS.md:until:\"kit:end\" -->' and never closes"* ]]
+  [[ "$output" == *"AGENTS.md: the kit's region opens with '<!-- kit:generate AGENTS.md -->' and never closes"* ]]
   rm AGENTS.md
   mkdir -p .kit/modules/extra/regions/repo
   printf 'description: "x"\ndepends:\n  - kit\n' > .kit/modules/extra/module.yml
@@ -312,15 +312,22 @@ later-release() {
   rm .kit/modules/extra/regions/repo/AGENTS.md
   run "${kit_checkout}/bin/kit" install extra
   [ "$status" -eq 0 ]
-  [ "$(sed -n '1p' config.toml)" = '# :generate:kit region config.toml:until:"kit:end"' ]
+  [ "$(sed -n '1p' config.toml)" = '# kit:generate config.toml' ]
   [ "$("${kit_checkout}/bin/kit" region config.toml)" = "x = 1" ]
   printf 'const x = 1;\n' > .kit/modules/extra/regions/repo/lib.js
   run env PATH="$(shims mise curl)" "${kit_checkout}/bin/kit" update
   [ "$status" -eq 0 ]
-  [ "$(sed -n '1p' lib.js)" = '// :generate:kit region lib.js:until:"kit:end"' ]
+  [ "$(sed -n '1p' lib.js)" = '// kit:generate lib.js' ]
+  [ "$(sed -n '3p' lib.js)" = '// kit:end lib.js' ]
   run "${kit_checkout}/bin/kit" region AGENTS.md
   [ "$status" -eq 0 ]
   [[ "$output" == "Read .kit/1st.md"* ]]
+  run env KIT_GENERATE_REGION=AGENTS.md "${kit_checkout}/bin/kit" region
+  [ "$status" -eq 0 ]
+  [[ "$output" == "Read .kit/1st.md"* ]]
+  run "${kit_checkout}/bin/kit" region
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"usage: kit region"* ]]
   run "${kit_checkout}/bin/kit" region README.md
   [ "$status" -eq 1 ]
   [[ "$output" == *"no active module delivers a region at README.md"* ]]
@@ -329,11 +336,11 @@ later-release() {
 @test "a region makes the file where there is none, and one holding different content is regenerated" {
   run "${kit_checkout}/bin/kit" install
   [ "$status" -eq 0 ]
-  [ "$(sed -n '1p' AGENTS.md)" = '<!-- :generate:kit region AGENTS.md:until:"kit:end" -->' ]
+  [ "$(sed -n '1p' AGENTS.md)" = '<!-- kit:generate AGENTS.md -->' ]
   run "${kit_checkout}/bin/kit" module remove kit
   [ ! -e AGENTS.md ]
   [ ! -e .gitignore ]
-  printf '# Ours\n\n<!-- :generate:kit region AGENTS.md:until:"kit:end" -->\nsomething else\n<!-- kit:end -->\n' > AGENTS.md
+  printf '# Ours\n\n<!-- kit:generate AGENTS.md -->\nsomething else\n<!-- kit:end AGENTS.md -->\n' > AGENTS.md
   run "${kit_checkout}/bin/kit" module add kit
   [ "$status" -eq 0 ]
   [[ "$output" == *"AGENTS.md: placed, the region regenerated"* ]]

From 4847f8deede6b66f7a02c8dee049a77ce70ba162 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 02:08:25 -0700
Subject: [PATCH 096/108] #9 a region is a template, rendered with the whole of
 .kit/settings.yml as context

A module's regions/<base>/<path> is rendered as templates/<base>/ is, before delivery, so kit region prints the
rendered content: a top-level setting as @key@, a map's entry as @map.name@, and a bare @key@ meaning the entry
under answers:, the module's defaults beneath. The rendered directory keeps the modules/<module>/<kind>/<base>
shape so a rendered region still reads as one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/release.sh | 86 +++++++++++++++++++++++++++++++++-----------------
 tests/kit.bats | 25 +++++++++++++++
 2 files changed, 82 insertions(+), 29 deletions(-)

diff --git a/bin/release.sh b/bin/release.sh
index 316f97b..eccc4b9 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -5,10 +5,11 @@
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
-# mirrored at the base's root; templates/<base>/, with @key@ rendered from the repository's answers, then
-# mirrored the same way; and regions/<base>/, each file placed as a region the kit owns inside a file the
-# repository owns, opened by a :generate: directive naming kit region and closed by an end marker, so the rest
-# of that file stays the repository's and kit generate makes the region what the command makes it. A repository
+# mirrored at the base's root; templates/<base>/, with @key@ rendered from the repository's settings, then
+# mirrored the same way; and regions/<base>/, rendered the same way, each file placed as a region the kit owns
+# inside a file the repository owns, between a bare kit:generate line and a kit:end line that name the path,
+# so the rest of that file stays the repository's and kit generate makes the region what kit region prints. A
+# repository
 # defines modules of its own the same way under .kit/modules/<name>/, and a name is looked up in the release
 # first, then there. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's home
 # directory, recorded in ~/.kit/manifest, which every repository on the desk shares. A destination ending in
@@ -254,12 +255,30 @@ release:validate-settings() {
   done < <(yaml:map "${settings}" answers)
 }
 
-# release:answers <root> <module> prints "<key>\t<value>" for every answer the module's templates may use: the
-# module's defaults under its answers:, each overridden by the repository's, under answers: in .kit/settings.yml.
-release:answers() {
+# release:context <root> <module> prints "<key>\t<value>" for every key a template or region of the module may
+# use: the module's defaults under its answers:, as <key> and answers.<key>; then the whole of .kit/settings.yml,
+# a top-level scalar as <key>, a map's entries as <map>.<name>, and the answers map's as <name> too. A later
+# line overrides an earlier one, so the repository's answer wins over the module's default.
+release:context() {
+  local settings key name value
+  settings=$(release:settings)
   {
-    yaml:map "$(release:meta "$1" "$2")" answers
-    yaml:map "$(release:settings)" answers
+    while IFS=$'\t' read -r name value
+    do
+      [[ -n "${name}" ]] || continue
+      printf '%s\t%s\n%s\t%s\n' "${name}" "${value}" "answers.${name}" "${value}"
+    done < <(yaml:map "$(release:meta "$1" "$2")" answers)
+    for key in $(yaml:keys "${settings}")
+    do
+      value=$(yaml:value "${settings}" "${key}")
+      [[ -n "${value}" ]] && printf '%s\t%s\n' "${key}" "${value}"
+      while IFS=$'\t' read -r name value
+      do
+        [[ -n "${name}" ]] || continue
+        printf '%s\t%s\n' "${key}.${name}" "${value}"
+        [[ "${key}" == answers ]] && printf '%s\t%s\n' "${name}" "${value}"
+      done < <(yaml:map "${settings}" "${key}")
+    done
   } | awk -F '\t' '{ a[$1] = $2 } END { for (k in a) print k "\t" a[k] }'
 }
 
@@ -275,30 +294,34 @@ release:tmp() {
   printf '%s\n' "${release_tmp}"
 }
 
-# release:render <root> <module> <base> renders the module's templates for <base> once per process and prints the
-# directory holding them, or prints nothing where the module has none. A key is written @key@, autoconf's form,
-# which neither bash's ${var} nor GitHub's ${{ }} can be mistaken for; one with no answer refuses, naming the key.
+# release:render <root> <module> <kind> <base> renders the module's templates or regions, the <kind>, for <base>
+# once per process and prints the directory holding them, or prints nothing where the module has none. The
+# directory keeps the modules/<module>/<kind>/<base> shape, so a rendered region still reads as one. A key is
+# written @key@, autoconf's form, which neither bash's ${var} nor GitHub's ${{ }} can be mistaken for, and may
+# be dotted, @answers.key@; one with no value refuses, naming the key.
 release:render() {
-  local root=$1 module=$2 base=$3 templates out key value text file rel
+  local root=$1 module=$2 kind=$3 base=$4 source out key value text file rel map
   local -A answer=()
-  templates="$(release:home "${root}" "${module}")/modules/${module}/templates/${base}"
-  [[ -d "${templates}" ]] || return 0
-  out="$(release:tmp)/$(printf '%s' "${root}" | release:digest)/${module}/${base}"
+  source="$(release:home "${root}" "${module}")/modules/${module}/${kind}/${base}"
+  [[ -d "${source}" ]] || return 0
+  out="$(release:tmp)/$(printf '%s' "${root}" | release:digest)/modules/${module}/${kind}/${base}"
   if [[ ! -d "${out}" ]]
   then
     while IFS=$'\t' read -r key value
     do
       [[ -n "${key}" ]] && answer[${key}]=${value}
-    done < <(release:answers "${root}" "${module}")
+    done < <(release:context "${root}" "${module}")
     while IFS= read -r file
     do
-      rel=${file#"${templates}"/}
+      rel=${file#"${source}"/}
       text=$(<"${file}")
-      for key in $(grep --only-matching '@[a-z_]*@' "${file}" | LC_ALL=C sort --unique | tr -d '@')
+      for key in $(grep --only-matching '@[a-z_][a-z_.]*@' "${file}" | LC_ALL=C sort --unique | tr -d '@')
       do
         if [[ -z "${answer[${key}]+x}" ]]
         then
-          error "${rel} needs an answer for '${key}'; add '${key}: <value>' under answers: in .kit/settings.yml" \
+          map=answers
+          [[ "${key}" == *.* ]] && map=${key%.*}
+          error "${rel} needs an answer for '${key}'; add '${key##*.}: <value>' under ${map}: in .kit/settings.yml" \
             "(module ${module})"
           return 1
         fi
@@ -306,14 +329,14 @@ release:render() {
       done
       mkdir -p "${out}/$(dirname "${rel}")"
       printf '%s\n' "${text}" > "${out}/${rel}"
-    done < <(find "${templates}" -type f)
+    done < <(find "${source}" -type f)
   fi
   printf '%s\n' "${out}"
 }
 
 # release:render-all <root> <module>… makes the release at <root> ready to read for the named modules: it refuses
 # a module the release lacks, validates every module the release carries, refuses a base the kit does not deliver
-# to, renders the named modules' templates, and refuses a link to nothing among the delivered files.
+# to, renders the named modules' templates and regions, and refuses a link to nothing among the delivered files.
 release:render-all() {
   local root=$1 module kind base
   shift
@@ -339,9 +362,12 @@ release:render-all() {
         fi
       done
     done
-    for base in $(release:bases)
+    for kind in templates regions
     do
-      release:render "${root}" "${module}" "${base}" >/dev/null || return 1
+      for base in $(release:bases)
+      do
+        release:render "${root}" "${module}" "${kind}" "${base}" >/dev/null || return 1
+      done
     done
   done
   for base in $(release:bases)
@@ -382,17 +408,19 @@ release:regions-apart() {
 }
 
 # release:layers <root> <base> <module>… prints the directories mirrored at the base's root, in module order: each
-# module's files/<base>, its rendered templates/<base>, and its regions/<base>.
+# module's files/<base>, its rendered templates/<base>, and its rendered regions/<base>.
 release:layers() {
-  local root=$1 base=$2 module home rendered
+  local root=$1 base=$2 module home kind rendered
   shift 2
   for module in "$@"
   do
     home=$(release:home "${root}" "${module}")
     [[ -d "${home}/modules/${module}/files/${base}" ]] && printf '%s\n' "${home}/modules/${module}/files/${base}"
-    rendered=$(release:render "${root}" "${module}" "${base}")
-    [[ -n "${rendered}" ]] && printf '%s\n' "${rendered}"
-    [[ -d "${home}/modules/${module}/regions/${base}" ]] && printf '%s\n' "${home}/modules/${module}/regions/${base}"
+    for kind in templates regions
+    do
+      rendered=$(release:render "${root}" "${module}" "${kind}" "${base}")
+      [[ -n "${rendered}" ]] && printf '%s\n' "${rendered}"
+    done
   done
   return 0
 }
diff --git a/tests/kit.bats b/tests/kit.bats
index 0f9bb5b..7ccb1af 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -532,4 +532,29 @@ later-release() {
   grep --quiet '^version 0.0.1$' "${KIT_HOME}/.kit/manifest"
 }
 
+@test "a region is a template: @key@ takes the repository's answer, the module's default, or a settings key, and refuses a key with none" {
+  mkdir -p .kit/modules/extra/regions/repo
+  printf 'description: "x"\ndepends:\n  - kit\nanswers:\n  ci_runner: ours\n' > .kit/modules/extra/module.yml
+  printf 'runner = "@ci_runner@"\nsigning = @require_signing@\nagain = "@answers.ci_runner@"\n' > .kit/modules/extra/regions/repo/config.toml
+  printf 'require_signing: false\n' > .kit/settings.yml
+  run "${kit_checkout}/bin/kit" install extra
+  [ "$status" -eq 0 ]
+  [ "$(sed -n '2,4p' config.toml | paste -s -d '|' -)" = 'runner = "ours"|signing = false|again = "ours"' ]
+  [ "$("${kit_checkout}/bin/kit" region config.toml | paste -s -d '|' -)" = 'runner = "ours"|signing = false|again = "ours"' ]
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  printf 'require_signing: false\nanswers:\n  ci_runner: theirs\n' > .kit/settings.yml
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"config.toml: stale"* ]]
+  run "${kit_checkout}/bin/kit" generate
+  [ "$status" -eq 0 ]
+  grep --quiet '^runner = "theirs"$' config.toml
+  grep --quiet '^again = "theirs"$' config.toml
+  printf 'x = @missing@\n' > .kit/modules/extra/regions/repo/other.toml
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"other.toml needs an answer for 'missing'; add 'missing: <value>' under answers: in .kit/settings.yml (module extra)"* ]]
+}
+
 # ----------------------------------------------------------------------------------------------------------------------

From cc87c5cf1aeff686ff29dbc15d3cc6e6e86a92f7 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 02:08:26 -0700
Subject: [PATCH 097/108] #9 docs: the kit:generate directive, its framing,
 nesting, and the region as a template

Every mention of the old form becomes the new one, and no line of prose opens with the marker, since such a
line is a directive or an error.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .kit/1st.md                        |  8 +--
 .kit/manifest                      |  2 +-
 README.md                          | 10 +--
 bin/kit                            |  4 +-
 bin/kit-generate.sh                |  2 +-
 docs/architecture.md               | 10 +--
 docs/generate.md                   | 98 +++++++++++++++++++-----------
 docs/modules.md                    | 33 +++++-----
 modules/claude/docs/README.md      |  2 +-
 modules/kit/docs/README.md         |  2 +-
 modules/kit/files/repo/.kit/1st.md |  8 +--
 11 files changed, 103 insertions(+), 76 deletions(-)

diff --git a/.kit/1st.md b/.kit/1st.md
index eca00f6..dc9df03 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -97,12 +97,12 @@ delivers is a module, and a repository activates the modules it takes: `kit inst
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
 lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
 key, the kit owning only the entries it writes; a region inside a file the repository owns is opened by a
-`:generate:` directive and made by the command it names, through `kit generate`; everything else is copied as it
-is.
+directive, `kit:generate`, and made by the command it names, through `kit generate`; everything else is copied
+as it is.
 
 - `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
-  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a
-  `:generate:` directive of the repository's own, and `kit check` holds every region to its command.
+  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a directive
+  of the repository's own, `kit:generate` naming any command, and `kit check` holds every region to its command.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
diff --git a/.kit/manifest b/.kit/manifest
index f360f19..f2d803d 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -5,7 +5,7 @@ modules kit ci-github claude lefthook
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
 86f04faeb1b3c0dc237ac01cd405512970953d97f1e0e6820315e5bf93a4d667  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
-39d7f0bf97cc6a89e51f8a195f95b265d56156e9a62deb0722537097482d5585  .kit/1st.md
+bb816c7d215b13f5d4f1da525b3254857e12d87aa9aca05158d8176e10d871fa  .kit/1st.md
 a36cca49330228339ece2a2fd7fe4958f13496329de43d56e1e0534344c99d20  .kit/lefthook.yml
 acf52f60f178be28ca2f09bb22f8a982bba0e61eff611ca1a91f1f8dae2ccbce  .kit/markdownlint.jsonc
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
diff --git a/README.md b/README.md
index fd3a3f5..6abb188 100644
--- a/README.md
+++ b/README.md
@@ -69,11 +69,11 @@ sees a new kit a day after it ships unless `[settings]` carries `minimum_release
   always in; `ci-github` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the
   Claude Code adapter. `kit install ci-github lefthook claude` takes all three, and `kit module add` takes one
   later.
-- `install` writes the sentence every agent reads into a region of `AGENTS.md`, opened by a `:generate:`
-  directive naming `kit region AGENTS.md` and closed by `kit:end`, making the file where there is none and
-  leaving the rest of it yours, and the `/worktrees/` entry into a region of `.gitignore` the same way. Move the
-  region where you like and write what you like around it; `kit generate` makes the region what the command
-  makes it, and `kit check` holds it there. Any file of yours may carry a directive of its own;
+- `install` writes the sentence every agent reads into a region of `AGENTS.md`, between a `kit:generate` line
+  and a `kit:end` line that both name the file, making the file where there is none and leaving the rest of it
+  yours, and the `/worktrees/` entry into a region of `.gitignore` the same way. Move the region where you like
+  and write what you like around it; `kit generate` makes the region what `kit region` prints, and `kit check`
+  holds it there. Any file of yours may carry a directive of its own, naming any command;
   [docs/generate.md](docs/generate.md) says how.
 - Commit what `install` wrote.
 - Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
diff --git a/bin/kit b/bin/kit
index fd3cbf9..d06d452 100755
--- a/bin/kit
+++ b/bin/kit
@@ -41,8 +41,8 @@ usage: kit <verb> [<argument>…]
                         the modules this repository takes
   context <path>…       name the rules that govern a file, and record the ask
   generate [--check] [<path>…]
-                        expand every :generate: region to what its command makes, or check that it is
-  region [--home] <path>
+                        expand every kit:generate region to what its command makes, or check that it is
+  region [--home] [<path>]
                         print the content the active modules deliver as the region at a path
   ci                    the delivered CI job's checks, anywhere: gate, check, and linked, every one reported
   gate                  run the repository's gate, the gate setting or the detected one; refuse when there is none
diff --git a/bin/kit-generate.sh b/bin/kit-generate.sh
index 2122c78..6b48fe5 100755
--- a/bin/kit-generate.sh
+++ b/bin/kit-generate.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# kit-generate - expand every :generate: region to what its command makes, or check that it is (kit verb)
+# kit-generate - expand every kit:generate region to what its command makes, or check that it is (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # The paths are the arguments, taken from the directory the command was typed in, else every tracked file and
diff --git a/docs/architecture.md b/docs/architecture.md
index d6fd0ea..d316e6a 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -16,17 +16,17 @@ a `version` file; a checkout has none and is `unreleased`.
 
 A module is a directory under `modules/`, and the directory names it. `module.yml` describes it: whether it is active by
 default, which modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the
-base's root; `templates/<base>/` is rendered first, every `@key@` replaced by an answer; `regions/<base>/` holds what
-the kit owns inside a file the repository owns; `docs/` is packed with the release and placed in no repository. Two
-bases exist: `repo`, the repository root, and `home`, the user's `~`.
+base's root; `templates/<base>/` is rendered first, every `@key@` replaced by a setting; `regions/<base>/`, rendered
+the same way, holds what the kit owns inside a file the repository owns; `docs/` is packed with the release and placed
+in no repository. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
 
 The verbs are the only way content moves. `kit install` resolves the active set, `kit` plus those named plus their
 dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
 an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
 fails when a delivered file differs from the release's. `kit module` changes the active set. Three rules govern
 placement: a `.json` destination, other than a schema, is merged by key, the kit owning only the entries it writes; a
-region is opened inside a file the repository owns by a `:generate:` directive naming `kit region`, and `kit
-generate` makes it what that command makes it, as it makes every region any file in the repository declares, see
+region is opened inside a file the repository owns by a bare `kit:generate` directive naming its path, and `kit
+generate` makes it what `kit region` prints, as it makes every region any file in the repository declares, see
 [generate.md](generate.md); everything else is a copy.
 
 Each base has a manifest: `.kit/manifest`, committed with the repository, and `~/.kit/manifest` on the desk when a
diff --git a/docs/generate.md b/docs/generate.md
index da5f134..8014d64 100644
--- a/docs/generate.md
+++ b/docs/generate.md
@@ -4,55 +4,78 @@ A region is a stretch of a file that a command makes and a person does not edit:
 manifests, a list of verbs drawn from their help, the sentence the kit puts in `AGENTS.md`. The file itself says
 how each region is made, with a directive in its own comment syntax, and `kit generate` makes every region what
 its command makes it. A hand edit is then a stale region, and `kit check` fails on one wherever `kit ci` runs.
-The mechanism is enchiridion's `:generate:` channel, carried into the kit so any repository has it.
 
 ## The directive
 
-A comment line that is the directive and nothing else opens a region:
+A region opens on a line that is the marker `kit:generate`, a name, and optionally a command in backticks, and
+closes on a line that is `kit:end` and the same name. Nothing but punctuation may surround either: the comment
+opener before, the comment closer after.
 
 ```text
-:generate:<command>:until:"<pattern>"
-:generate:<command>:while:"<pattern>"
+<!-- kit:generate <name> -->
+<!-- kit:generate <name> `<command>` -->
+…
+<!-- kit:end <name> -->
 ```
 
-The directive line stays. The command runs from the repository root, with the running kit's `bin/` first on
-`PATH`, and its standard output replaces the lines after the directive. With `until`, the region runs up to the
-first later line matching the pattern, an extended regular expression, and that line stays as the end marker.
-With `while`, the region is every line matching the pattern, and the first line that does not match ends it. So
-a markdown page carries:
+Both lines stay. The command's standard output replaces the lines between them. So a markdown page carries:
 
 ```markdown
-<!-- :generate:kit region AGENTS.md:until:"kit:end" -->
+<!-- kit:generate AGENTS.md -->
 Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
 repository trustworthy.
-<!-- kit:end -->
+<!-- kit:end AGENTS.md -->
 ```
 
 and a shell script or a `.gitignore` carries the same with `#`, a JavaScript file with `//`, a SQL file with
-`--`. The comment openers the kit reads are `#`, `//`, `--`, `<!--`, `/*`, `%`, and `;`. A line that is not a
-comment opened by one of them is not a directive, so a page may mention the syntax in prose or a code span, and a
-directive inside a fenced code block is not live, so a page may show one whole.
-
-The command is one command and its arguments, with no shell operator: no pipe, no `&&`, no redirection, no
-substitution. A word is a name, a flag, a path, or a `key=value` pair. What makes a region is therefore always a
-kit verb, a just recipe, a make target, or a script in the tree, where it is listed, read, and tested, and never
-a one-liner hidden in a comment. A command outside that shape is refused by file and line.
+`--`, a Visual Basic file with `'`. The reader knows no list of comment syntaxes. It reads a line as a directive
+when only non-alphanumeric characters come before the marker and after the closing backtick, which every comment
+frame satisfies and no line of prose does, since prose has letters before the marker. A line that opens with
+the marker and is not a well-formed directive is an error, never a line silently skipped, so a misspelled
+directive is found rather than left stale. A page that wants to show the syntax puts it in a fenced code block,
+which is not live, or in prose, with a word before the marker.
+
+The **name** is any run of characters without whitespace or a backtick, set off by whitespace. It pairs the
+directive with its end marker, and it is unique in a file. A region the kit delivers is named by its path, so
+the name says what the region is.
+
+The **command** is a bash command line: pipes, redirections, and `$()` are all its own. It runs from the
+repository root with the running kit's `bin/` first on `PATH`, standard input closed, `errexit` and `pipefail`
+set, and two variables in its environment: `KIT_GENERATE_FILE`, the file, and `KIT_GENERATE_REGION`, the name.
+The command is everything between the first backtick after the name and the last backtick before the closer, so
+the one thing it cannot carry is a literal backtick; `$()` says the same thing. A region whose command needs
+more than a line is a script in the tree, where it is read and tested.
+
+With **no command**, the command is `kit region`, which reads the region's name from its environment as the path
+of a region an active module delivers. A name no module delivers fails, naming the directive's line, so a
+forgotten command is never a silent no-op. The directive may sit in any file; the name says only which region.
+
+## Nesting and balance
+
+Every unit is balanced on its own: the file as written, and each command's output. A directive opened in a unit
+closes in that unit; an end marker closes the region most recently opened there. A command's output may open
+regions of its own, each closed in that same output, and `kit generate` expands those in turn, depth first, so a
+region nests and one pass settles a file. An output that closes a region it did not open, or opens one it does
+not close, is refused, naming the file, the directive's line, and the command. A region that nests is therefore
+always one the enclosing command wrote; a hand-written directive inside a region is replaced with the rest of the
+region's content.
 
 ## The verbs
 
 `kit generate [<path>…]` expands the named files, taken from the directory the command was typed in, or with
 none named every tracked file and every untracked one git does not ignore. Named files are expanded once, or
 `--iterations=<n>` times. The whole repository is expanded until a pass changes nothing, at most twenty passes or
-`--iterations=<n>`, since a region's output may depend on another region's. A run that is still changing at the
-bound fails, naming the cause: a command whose output depends on its own output.
+`--iterations=<n>`, since a command may read another file's region. A run that is still changing at the bound
+fails, naming the cause: a command whose output depends on its own output.
 
 `kit generate --check [<path>…]` runs one pass without writing and fails naming every stale file. `kit check`
 runs it over the whole repository, so the gate holds every generated region, the kit's and the repository's own,
 and the lefthook module's pre-commit hook runs it over the staged paths.
 
-`kit region [--home] <path>` prints the content the active modules deliver as the region at a path, the command
-behind every region the kit delivers. One active module delivers a region at a path, so the answer is that
-module's `regions/<base>/<path>`, and a path no active module delivers is refused.
+`kit region [--home] [<path>]` prints the content the active modules deliver as the region at a path, rendered as
+a template is, the command behind every region the kit delivers. The path defaults to `KIT_GENERATE_REGION`, so
+a bare directive needs none. One active module delivers a region at a path, so the answer is that module's
+`regions/<base>/<path>`, and a path no active module delivers is refused.
 
 ## What is refused
 
@@ -60,22 +83,25 @@ A file is rewritten only on a clean expansion. Each of these leaves the file as
 the file and the line:
 
 - a command that fails;
-- an `until` pattern no later line matches, so the region never closes;
-- a command outside its shape;
+- a line that opens with the marker and is not a directive;
+- an end marker with no open region, or naming a region other than the one open;
+- a directive whose region never closes, in the file or in a command's output;
+- a name opened twice in the expanded file;
 - a conflict marker in the file, a line of seven `<` or `>`, since a conflicted file is not input a region
-  expander can read;
-- an expansion that produces nothing from a file that was not empty.
+  expander can read.
 
 ## The kit's regions
 
-A file under a module's `regions/<base>/<path>` is the content of a region. What `kit install` writes into the
-file at `<path>` is the directive naming `kit region <path>`, the content, and the end marker, in the file's
-comment syntax: between the directive and the end marker where the file already carries them, appended after a
-blank line where it does not, and as the whole file where there is none. The repository moves the block where it
-likes and writes what it likes around it. `kit update` regenerates the region, and there is no three-way merge of
-one, since its content is never the repository's to edit; `kit module remove` takes the block out, and removes a
-file it leaves empty. A directive with no end marker is refused by name, and two modules delivering a region to
-one file are refused where the modules are read.
+A file under a module's `regions/<base>/<path>` is a template for the content of a region: every `@key@` in it
+is rendered from `.kit/settings.yml` and the module's defaults, as [modules.md](modules.md) describes. What
+`kit install` writes into the file at `<path>` is the bare directive naming the path, the rendered content, and
+the end marker, in the file's comment syntax: between the directive and the end marker where the file already
+carries them, appended after a blank line where it does not, and as the whole file where there is none. The
+repository moves the block where it likes and writes what it likes around it. `kit update` regenerates the
+region, and there is no three-way merge of one, since its content is never the repository's to edit;
+`kit module remove` takes the block out, and removes a file it leaves empty. A directive with no end marker is
+refused by name, and two modules delivering a region to one file are refused where the modules are read. A region
+under `home` spells its command, `kit region --home <path>`, since the bare form cannot.
 
 The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to `.kit/1st.md`, and the
 `/worktrees/` entry in `.gitignore`. The `claude` module places one in `.claude/CLAUDE.md`, importing
diff --git a/docs/modules.md b/docs/modules.md
index 2b5c937..7928860 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -60,22 +60,23 @@ than a schema, `*.schema.json`, is merged by key: the kit's keys are set, its ar
 removal only the previous release's entries are taken out, so a repository's own keys and entries survive. Every other
 destination is a copy. Where two active modules deliver the same path, the later module in dependency order wins.
 
-A file under `regions/<base>/` is the content of a region inside the file at the same path. What is placed there is a
-`:generate:` directive naming `kit region <path>`, the content, and a `kit:end` marker, in the file's own comment
-syntax: `<!-- … -->` in markdown, `#` elsewhere, as [generate.md](generate.md) describes. Where the file carries the
-directive already, the content between it and the end marker is made what the command makes it; where it does not, the
-block is appended after a blank line; where there is no file, it is made of the block alone. The repository may move the
-block anywhere in the file and write what it likes around it. `kit check` holds the region to its command, `kit update`
-regenerates it, never merges it, and removal takes the block out and leaves the rest, removing a file it leaves empty.
-One file holds one kit region, and two modules delivering a region to the same path are refused by name. A kind of file
-the kit cannot mark is refused. The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to
-`.kit/1st.md`, and the `/worktrees/` entry in `.gitignore`.
-
-A file under `templates/<base>/` is rendered first. Every `@key@` in it, autoconf's form, is replaced by the key's
-answer, then the result is placed, digested, and merged exactly as a `files/` file is. The form is one neither
-bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both untouched. The repository's
-answers live under `answers:` in `.kit/settings.yml`; a key with none there takes the module's default under its
-own `answers`, and a key with neither refuses the install, naming the key and the module.
+A file under `regions/<base>/` is the content of a region inside the file at the same path, rendered as a template
+is. What is placed there is the bare directive `kit:generate <path>`, the content, and the marker `kit:end <path>`, in
+the file's own comment syntax: `<!-- … -->` in markdown, `#` elsewhere, as [generate.md](generate.md) describes. Where
+the file carries the directive already, the content between it and the end marker is made what `kit region` prints;
+where it does not, the block is appended after a blank line; where there is no file, it is made of the block alone. The
+repository may move the block anywhere in the file and write what it likes around it. `kit check` holds the region to
+its command, `kit update` regenerates it, never merges it, and removal takes the block out and leaves the rest, removing
+a file it leaves empty. One file holds one kit region, and two modules delivering a region to the same path are refused
+by name. A kind of file the kit cannot mark is refused. The `kit` module places two: the sentence in `AGENTS.md` that
+sends every agent to `.kit/1st.md`, and the `/worktrees/` entry in `.gitignore`.
+
+A file under `templates/<base>/`, and one under `regions/<base>/`, is rendered first. Every `@key@` in it, autoconf's
+form, is replaced by the key's value, then the result is placed, digested, and merged exactly as a `files/` file is.
+The form is one neither bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both
+untouched. The context is the whole of `.kit/settings.yml`: a top-level setting as `@require_signing@`, a map's entry
+as `@answers.ci_runner@`, and a bare `@ci_runner@` meaning the entry under `answers:`. A key with no value there takes
+the module's default under its own `answers`, and a key with neither refuses the install, naming the key and the module.
 
 The same YAML subset is what a rule's frontmatter and `.kit/settings.yml` are written in, read by `bin/yaml.sh` in
 all three places, so a rule's lists, a module's `depends:`, and the settings have one reader among them.
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index 8ce6588..6811111 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -3,7 +3,7 @@
 The adapter for Claude Code. Claude Code reads `AGENTS.md` only as a fallback: when no `CLAUDE.md`,
 `.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and where its
 configuration allows. A repository with a `CLAUDE.md` of its own would have `AGENTS.md` skipped. So the module
-places a region in `.claude/CLAUDE.md` holding `@../AGENTS.md`, opened by a `:generate:` directive `kit
+places a region in `.claude/CLAUDE.md` holding `@../AGENTS.md`, opened by a `kit:generate` directive `kit
 generate` fills: Claude then reads what every other agent reads in every case, the rest of that file and a root
 `CLAUDE.md` are the repository's own, and `kit check` holds only the region. It also merges into
 `.claude/settings.json`, by key, leaving the repository's own entries:
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
index 1e6a28a..2ed0d81 100644
--- a/modules/kit/docs/README.md
+++ b/modules/kit/docs/README.md
@@ -6,7 +6,7 @@ The core, active in every repository that takes the kit. It places:
 - `.kit/rules/<kind>.md`, one rule file per kind of file, each declaring in its frontmatter which paths and which
   first lines it governs, and the linter `kit lint` runs over them.
 - A region in `AGENTS.md`, the sentence that sends every agent to `.kit/1st.md`, and a region in `.gitignore`,
-  the `/worktrees/` entry the loop needs; each opened by a `:generate:` directive that `kit generate` fills
+  the `/worktrees/` entry the loop needs; each opened by a `kit:generate` directive that `kit generate` fills
   through `kit region`, and the rest of each file is the repository's.
 
 The rules are discovered through `kit context`, described in
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index eca00f6..dc9df03 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -97,12 +97,12 @@ delivers is a module, and a repository activates the modules it takes: `kit inst
 `kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
 lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
 key, the kit owning only the entries it writes; a region inside a file the repository owns is opened by a
-`:generate:` directive and made by the command it names, through `kit generate`; everything else is copied as it
-is.
+directive, `kit:generate`, and made by the command it names, through `kit generate`; everything else is copied
+as it is.
 
 - `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
-  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a
-  `:generate:` directive of the repository's own, and `kit check` holds every region to its command.
+  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a directive
+  of the repository's own, `kit:generate` naming any command, and `kit check` holds every region to its command.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.

From defb447bb798a1c56bc5ee6cc01585cd225e8e66 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 02:33:27 -0700
Subject: [PATCH 098/108] #9 generate: refuse a fence that never closes, name a
 nested failure by its output, and the bash rule's then

From review: a markdown output with an odd number of fence lines wrote a file the next pass refused, so a
fence open at the end of any unit is now refused naming its line; a nested command's failure named a line of
the output as the file's, so it is named by the unit it is in; the duplicate-name refusal names the line of
the expanded file; and every fence toggle takes the rule's then on its own line.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/generate.sh     | 60 +++++++++++++++++++++++++++++----------------
 docs/generate.md    |  2 ++
 tests/generate.bats | 21 +++++++++++++++-
 3 files changed, 61 insertions(+), 22 deletions(-)

diff --git a/bin/generate.sh b/bin/generate.sh
index e2ec416..ab77e56 100644
--- a/bin/generate.sh
+++ b/bin/generate.sh
@@ -21,7 +21,8 @@
 # one pass settles a file. An output that closes a region it did not open, or opens one it does not close, holds
 # the file. A line that opens with the marker and is not a directive holds the file too, so a misspelled one is
 # never silently skipped; a line of prose, with letters before the marker, is not read at all. In markdown, a
-# fenced code block is not live, so a page may show a directive whole.
+# fenced code block is not live, so a page may show a directive whole, and a fence that opens and never closes,
+# in the file or in an output, is refused, since the directives after it could not be read.
 #
 # A file is rewritten only on a clean expansion. A command that fails, an unbalanced unit, a malformed marker, a
 # name opened twice, or a conflict marker in the file leaves the file as it was and fails the run, naming the
@@ -80,17 +81,26 @@ generate:target() {
   fi
 }
 
-# generate:command <file> <line> <name> <command> <out> runs one region's command with its stdout in <out>.
+# generate:command <file> <where> <line> <name> <command> <out> runs one region's command with its stdout in
+# <out>; a failure is named by <where> and the line, the unit the directive is in.
 generate:command() {
-  local file=$1 number=$2 name=$3 command=$4 out=$5
+  local file=$1 where=$2 number=$3 name=$4 command=$5 out=$6
   if ! KIT_GENERATE_FILE="${file}" KIT_GENERATE_REGION="${name}" PATH="${kit_root}/bin:${PATH}" \
     bash -o errexit -o pipefail -c "${command}" </dev/null >"${out}"
   then
-    error "${file}:${number}: the command failed: ${command}"
+    error "${where}:${number}: the command failed: ${command}"
     return 2
   fi
 }
 
+# generate:flip toggles the caller's fence state, its variable fence, at a fence line.
+generate:flip() {
+  if [[ "${fence}" == true ]]
+  then fence=false
+  else fence=true
+  fi
+}
+
 # generate:unit <in> <out> <file> <where> <markdown> expands one unit, the file or a command's output, from <in>
 # into <out>. <where> opens every message: the file's path for the file, and for an output the file, the line
 # of the directive, and the command. Two passes: the first holds the unit to its shape, every marker line a
@@ -99,7 +109,7 @@ generate:command() {
 generate:unit() {
   local in=$1 out=$2 file=$3 where=$4 markdown=$5
   local -a lines stack opened
-  local n i j line fence=false depth name command body result
+  local n i j line fence=false fenced=0 depth name command body result
   mapfile -t lines < "${in}"
   n=${#lines[@]}
   stack=()
@@ -109,7 +119,8 @@ generate:unit() {
     line=${lines[i]}
     if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
     then
-      if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+      generate:flip
+      [[ "${fence}" == true ]] && fenced=$(( i + 1 ))
       continue
     fi
     [[ "${fence}" == false && "${line}" =~ ${generate_marker_re} ]] || continue
@@ -141,6 +152,11 @@ generate:unit() {
     error "${where}:${opened[-1]}: the region '${stack[-1]}' never closes"
     return 2
   fi
+  if [[ "${fence}" == true ]]
+  then
+    error "${where}: a fenced code block opens at line ${fenced} and never closes"
+    return 2
+  fi
   : > "${out}"
   fence=false
   i=0
@@ -150,7 +166,7 @@ generate:unit() {
     printf '%s\n' "${line}" >> "${out}"
     if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
     then
-      if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+      generate:flip
       i=$(( i + 1 ))
       continue
     fi
@@ -163,7 +179,7 @@ generate:unit() {
     command=${BASH_REMATCH[3]:-kit region}
     body=$(mktemp)
     result=$(mktemp)
-    if ! generate:command "${file}" "$(( i + 1 ))" "${name}" "${command}" "${body}" \
+    if ! generate:command "${file}" "${where}" "$(( i + 1 ))" "${name}" "${command}" "${body}" \
       || ! generate:unit "${body}" "${result}" "${file}" "${where}:$(( i + 1 )) (the output of ${command})" "${markdown}"
     then
       rm -f "${body}" "${result}"
@@ -178,7 +194,7 @@ generate:unit() {
       line=${lines[j]}
       if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
       then
-        if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+        generate:flip
         continue
       fi
       [[ "${fence}" == false ]] || continue
@@ -193,34 +209,35 @@ generate:unit() {
   done
 }
 
-# generate:twice <file> prints the first region name the file opens twice, outside a markdown fence, or nothing.
+# generate:twice <expanded> <file> prints "<name>\t<line>" for the first region the expanded text opens twice,
+# outside a markdown fence when <file> is markdown, or nothing.
 generate:twice() {
-  local file=$1 line fence=false markdown
+  local expanded=$1 line fence=false markdown=false number=0
   local -A seen=()
-  markdown=false
   generate:markdown "$2" && markdown=true
   while IFS= read -r line || [[ -n "${line}" ]]
   do
+    number=$(( number + 1 ))
     if [[ "${markdown}" == true && "${line}" =~ ${generate_fence_re} ]]
     then
-      if [[ "${fence}" == true ]]; then fence=false; else fence=true; fi
+      generate:flip
       continue
     fi
     [[ "${fence}" == false && "${line}" =~ ${generate_open_re} ]] || continue
     if [[ -n "${seen[${BASH_REMATCH[1]}]+x}" ]]
     then
-      printf '%s\n' "${BASH_REMATCH[1]}"
+      printf '%s\t%s\n' "${BASH_REMATCH[1]}" "${number}"
       return 0
     fi
     seen[${BASH_REMATCH[1]}]=1
-  done < "${file}"
+  done < "${expanded}"
 }
 
 # generate:expand <file> <mode> expands the file's regions into a sibling temp file and compares. It returns 0
 # when nothing changed, 1 when the file was rewritten (mode write) or is stale (mode check), and 2 when it could
 # not be cleanly expanded, in which case the file is left as it was. Only mode write ever writes.
 generate:expand() {
-  local file=$1 mode=${2:-write} target temp markdown=false twice
+  local file=$1 mode=${2:-write} target temp markdown=false twice number
   if [[ ! -f "${file}" ]]
   then
     error "generate: no such file: ${file}"
@@ -240,10 +257,10 @@ generate:expand() {
     rm -f "${temp}"
     return 2
   fi
-  twice=$(generate:twice "${temp}" "${file}")
+  IFS=$'\t' read -r twice number < <(generate:twice "${temp}" "${file}")
   if [[ -n "${twice}" ]]
   then
-    error "${file}: the region '${twice}' is opened twice"
+    error "${file}: the region '${twice}' is opened twice, the second time at line ${number} of the expanded file"
     rm -f "${temp}"
     return 2
   fi
@@ -310,9 +327,10 @@ generate:run() {
     ok "generate: ${#targets[@]} generated file(s), every region as its command makes it"
     return 0
   fi
-  if (( limit == 0 ))
-  then
-    if [[ "${explicit}" == true ]]; then limit=1; else limit=20; fi
+  if (( limit == 0 )) && [[ "${explicit}" == true ]]
+  then limit=1
+  elif (( limit == 0 ))
+  then limit=20
   fi
   while (( pass < limit ))
   do
diff --git a/docs/generate.md b/docs/generate.md
index 8014d64..1537363 100644
--- a/docs/generate.md
+++ b/docs/generate.md
@@ -87,6 +87,8 @@ the file and the line:
 - an end marker with no open region, or naming a region other than the one open;
 - a directive whose region never closes, in the file or in a command's output;
 - a name opened twice in the expanded file;
+- a fenced code block in a markdown file, or in a command's output, that opens and never closes, since the
+  directives after it could not be read;
 - a conflict marker in the file, a line of seven `<` or `>`, since a conflicted file is not input a region
   expander can read.
 
diff --git a/tests/generate.bats b/tests/generate.bats
index 96f8a71..6123edd 100644
--- a/tests/generate.bats
+++ b/tests/generate.bats
@@ -100,7 +100,7 @@ joined() { paste -s -d '|' - < "$1"; }
   printf '# kit:generate a `./lines.sh x`\n# kit:end a\n# kit:generate a `./lines.sh y`\n# kit:end a\n' > twice.txt
   run "${kit_checkout}/bin/kit" generate twice.txt
   [ "$status" -eq 1 ]
-  [[ "$output" == *"twice.txt: the region 'a' is opened twice"* ]]
+  [[ "$output" == *"twice.txt: the region 'a' is opened twice, the second time at line 4 of the expanded file"* ]]
   printf '<<<<<<< ours\n# kit:generate a `./lines.sh x`\n# kit:end a\n>>>>>>> theirs\n' > conflict.txt
   run "${kit_checkout}/bin/kit" generate conflict.txt
   [ "$status" -eq 1 ]
@@ -173,4 +173,23 @@ joined() { paste -s -d '|' - < "$1"; }
   [[ "$output" == *"bare.txt:1: the command failed: kit region"* ]]
 }
 
+@test "a nested command's failure names the output's line, and an output that leaves a markdown fence open is refused" {
+  printf '#!/usr/bin/env bash\nprintf "%%s\\n" "head" "# kit:generate inner \\`false\\`" "# kit:end inner"\n' > nf.sh && chmod +x nf.sh
+  printf '# kit:generate outer `./nf.sh`\nheld\n# kit:end outer\n' > nf.txt
+  run "${kit_checkout}/bin/kit" generate nf.txt
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"nf.txt:1 (the output of ./nf.sh):2: the command failed: false"* ]]
+  grep --quiet '^held$' nf.txt
+  printf '#!/usr/bin/env bash\nprintf "%%s\\n" text %s more\n' "'\`\`\`'" > fence.sh && chmod +x fence.sh
+  printf '<!-- kit:generate odd `./fence.sh` -->\nheld\n<!-- kit:end odd -->\n' > odd.md
+  run "${kit_checkout}/bin/kit" generate odd.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"odd.md:1 (the output of ./fence.sh): a fenced code block opens at line 2 and never closes"* ]]
+  grep --quiet '^held$' odd.md
+  printf '# Title\n\n```\n<!-- kit:generate a `./lines.sh x` -->\n<!-- kit:end a -->\n' > open.md
+  run "${kit_checkout}/bin/kit" generate open.md
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"open.md: a fenced code block opens at line 3 and never closes"* ]]
+}
+
 # ----------------------------------------------------------------------------------------------------------------------

From f65a6da3241bfee137aa0dc06d01fda19560b331 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 11:29:48 -0700
Subject: [PATCH 099/108] kit status: whose pull requests, the author column,
 the branch on the row, and timed tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

kit status takes --mine, --all, and --owner=<login>, given once or more; --all is the default.
Every choice but --mine shows the author before the state, 👤 and the login, in a column of its
own. The pull request document carries the author, which the GitHub provider reads in the one
request it makes, and --json carries it too, the pull requests chosen the same way.

The worktree on a pull request's row is named by its branch, the name the worktree's own block
showed, not by its path relative to the current directory.

just ci runs bats with --timing, so every test's time is in the log. #10 holds the numbers.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 bin/forge-github.sh |  8 +++--
 bin/kit             |  5 +--
 bin/kit-status.sh   |  2 +-
 bin/status.sh       | 79 ++++++++++++++++++++++++++++++---------------
 justfile            |  2 +-
 tests/status.bats   | 24 ++++++++++----
 6 files changed, 80 insertions(+), 40 deletions(-)

diff --git a/bin/forge-github.sh b/bin/forge-github.sh
index 33d9f27..7461f66 100644
--- a/bin/forge-github.sh
+++ b/bin/forge-github.sh
@@ -123,8 +123,8 @@ forge-github:pr-closing-issues() {
 }
 
 # One request: every open pull request with the issues it closes, its review threads, and the checks on its
-# head, folded into the document kit status draws: number, branch, title, createdAt, age in seconds, state,
-# checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes [{number, title}].
+# head, folded into the document kit status draws: number, branch, title, author, createdAt, age in seconds,
+# state, checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes [{number, title}].
 forge-github:open-prs() {
   local repo query filter
   repo=$(forge-github:repo) || return 1
@@ -133,6 +133,7 @@ forge-github:open-prs() {
       pullRequests(states: OPEN, first: 100, orderBy: {field: CREATED_AT, direction: ASC}) {
         nodes {
           number title isDraft headRefName createdAt mergeStateStatus reviewDecision
+          author { login }
           closingIssuesReferences(first: 10) { nodes { number title } }
           reviewThreads(first: 100) { nodes { isResolved } }
           commits(last: 1) { nodes { commit { statusCheckRollup { contexts(first: 100) { nodes {
@@ -173,7 +174,8 @@ forge-github:open-prs() {
        elif $unresolved > 0 then "comments:open"
        elif (.reviewDecision // "") | IN("REVIEW_REQUIRED", "CHANGES_REQUESTED") then "blocked:approval"
        else "ready" end) as $state
-    | { number, branch: .headRefName, title, createdAt, age: ($now - (.createdAt | fromdateiso8601)), state: $state,
+    | { number, branch: .headRefName, title, author: (.author.login // ""), createdAt,
+        age: ($now - (.createdAt | fromdateiso8601)), state: $state,
         checks: { state: $check, passed: $ok, total: $n, failing: $failing, took: $took },
         unresolved: $unresolved,
         closes: [.closingIssuesReferences.nodes[] | { number, title }] }
diff --git a/bin/kit b/bin/kit
index d06d452..31f9657 100755
--- a/bin/kit
+++ b/bin/kit
@@ -50,8 +50,9 @@ usage: kit <verb> [<argument>…]
   issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
-  status [--no-fetch] [--json]
-                        the desk, the worktrees, and the open pull requests
+  status [--no-fetch] [--json] [--mine | --all | --owner=<login>…]
+                        the desk, the worktrees, and the open pull requests: everyone's, yours, or the named
+                        authors'
   lint [--all-files] [<path>…]
                         run each rule's linter over the paths it governs: staged, named, or every tracked one
   release <verify|pack|publish|retire> …
diff --git a/bin/kit-status.sh b/bin/kit-status.sh
index dc47e5c..32da89a 100755
--- a/bin/kit-status.sh
+++ b/bin/kit-status.sh
@@ -11,7 +11,7 @@ use status
 
 if [[ "${1:-}" == --help ]]
 then
-  echo "usage: kit status [--no-fetch] [--json]" >&2
+  echo "usage: kit status [--no-fetch] [--json] [--mine | --all | --owner=<login>…]" >&2
   exit 0
 fi
 
diff --git a/bin/status.sh b/bin/status.sh
index 48fb56f..92a9fb2 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -2,21 +2,24 @@
 # status.sh - the picture of the work in flight (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# status:render [--no-fetch] [--json] prints the checkouts and the open pull requests, and changes nothing. It asks
-# GitHub once, for every open pull request with the issues it closes, its review threads, and the checks on its
-# head; everything else is a local git read.
+# status:render [--no-fetch] [--json] [--mine | --all | --owner=<login>…] prints the checkouts and the open pull
+# requests, and changes nothing. It asks the forge once, for every open pull request with the issues it closes,
+# its review threads, and the checks on its head; everything else is a local git read.
 #
-# The picture: the desk, the root checkout, first; then each worktree under worktrees/; then each open pull request
-# with its state, age, checks, the issues it closes, and the worktree holding its branch; then the branches whose
-# upstream is gone. Color is by family, never by state: green when nothing is left to decide, yellow when a human
-# owes a decision, blue when the next move is a machine's or a reviewer's, dim for detail. The states, in the
-# order the first that holds wins:
+# The picture: the desk, the root checkout, first; then each worktree under worktrees/; then each open pull request with
+# its author, state, age, checks, the worktree holding its branch, and the issues it closes; then the branches whose
+# upstream is gone. --mine shows the pull requests the caller opened and no author column; --all, the default, shows
+# every open one, and --owner=<login>, given once or more, those the named authors opened, each with the author before
+# the state. Color is by family, never by state: green when nothing is left to decide, yellow when a human owes a
+# decision, blue when the next move is a machine's or a reviewer's, dim for detail. The states, in the order the first
+# that holds wins:
 #
 #   draft 🔨, queued 🚦, conflicted 💥, failing:gate 🔥, no-check 📭, comments:open 💬,
 #   blocked:approval 👀,
 #   ready 🛬
 #
-# --json prints the same facts as one document: {desk, worktrees, pullRequests, goneBranches}.
+# --json prints the same facts as one document: {desk, worktrees, pullRequests, goneBranches}, the pull requests
+# chosen the same way.
 
 use git
 
@@ -104,6 +107,15 @@ status:collect() {
   forge:open-prs || warn "no pull request is shown; see above"
 }
 
+# status:select <login>… keeps, of the pull request documents on stdin, those an author named here opened; with
+# no login named, every one.
+status:select() {
+  if (( $# == 0 ))
+  then cat
+  else jq --compact-output --arg logins "$*" 'select(.author as $a | ($logins | split(" ")) | index($a))'
+  fi
+}
+
 # status:fork <branch> <default-branch> prints the commit where <branch> left the default branch, or nothing.
 status:fork() {
   git merge-base "origin/$2" "$1" 2>/dev/null || git merge-base "$2" "$1" 2>/dev/null || true
@@ -281,20 +293,24 @@ status:check-cell() {
   return 0
 }
 
-# status:pr-block <pr-json> <title-width> <state-width> <age-width> <worktree-relative> prints a pull request: its
-# row, ending with the worktree here that holds its branch when one does, then the issues it closes.
+# status:pr-block <pr-json> <title-width> <owner-width> <state-width> <age-width> <worktree> prints a pull request:
+# its row, with the author before the state where the owner width is above zero and ending with its branch where
+# a worktree here holds it, then the issues it closes.
 status:pr-block() {
-  local doc=$1 title_w=$2 state_w=$3 age_w=$4 worktree=$5 number title state age unresolved row issue checks
-  IFS=$'\t' read -r number title state age unresolved \
-    < <(jq --raw-output '[.number, .title, .state, .age, .unresolved] | @tsv' <<<"${doc}")
+  local doc=$1 title_w=$2 owner_w=$3 state_w=$4 age_w=$5 worktree=$6
+  local number title author branch state age unresolved row issue checks
+  IFS=$'\x1f' read -r number title author branch state age unresolved \
+    < <(jq --raw-output '[.number, .title, .author, .branch, .state, .age, .unresolved] | map(tostring)
+          | join("\u001f")' <<<"${doc}")
   row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
+  (( owner_w > 0 )) && row+="   👤 $(status:paint 90 "$(status:cell "${author}" "${owner_w}")")"
   row+="   $(status:state-emoji "${state}")"
   row+=" $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
   row+="   $(status:paint 90 "$(status:cell "$(status:age "${age}")" "${age_w}")")"
   checks=$(status:check-cell "$(jq --compact-output .checks <<<"${doc}")")
   [[ -n "${checks}" ]] && row+="   ${checks}"
   (( unresolved > 0 )) && row+="   $(status:paint 33 "💬 ${unresolved} unresolved")"
-  [[ -n "${worktree}" ]] && row+="   $(status:paint 90 "🌿 ${worktree}")"
+  [[ -n "${worktree}" ]] && row+="   $(status:paint 90 "🌿 ${branch}")"
   printf '%s\n' "${row}" >&2
   while IFS= read -r issue
   do
@@ -303,20 +319,29 @@ status:pr-block() {
   return 0
 }
 
-# status:render [--no-fetch] [--json] draws the picture the file header describes, or prints it as one JSON
-# document.
+# status:render [--no-fetch] [--json] [--mine | --all | --owner=<login>…] draws the picture the file header
+# describes, or prints it as one JSON document.
 status:render() {
-  local no_fetch=false json=false arg main_root default_branch desk_branch path branch doc gone
+  local no_fetch=false json=false choice=all arg main_root default_branch desk_branch path branch doc gone
+  local -a owners=()
   for arg in "$@"
   do
     case "${arg}" in
       (--no-fetch) no_fetch=true ;;
       (--json) json=true ;;
+      (--mine) choice=mine ;;
+      (--all) choice=all ;;
+      (--owner=?*) choice=owner; owners+=("${arg#--owner=}") ;;
       (*)
-        error "unknown flag '${arg}' (usage: kit status [--no-fetch] [--json])"
+        error "unknown flag '${arg}' (usage: kit status [--no-fetch] [--json] [--mine | --all | --owner=<login>…])"
         return 2
     esac
   done
+  if [[ "${choice}" == mine ]]
+  then
+    use forge
+    owners=("$(forge:me)") || return 1
+  fi
   if [[ "${no_fetch}" != true ]]
   then
     git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
@@ -335,7 +360,7 @@ status:render() {
     [[ -n "${path}" ]] || continue
     worktrees+=("$(status:checkout "${path}" "${branch}" "${default_branch}")")
   done < <(git:worktrees | status:by-number)
-  prs=$(status:collect)
+  prs=$(status:collect | status:select "${owners[@]}")
 
   if [[ "${json}" == true ]]
   then
@@ -347,8 +372,8 @@ status:render() {
     return 0
   fi
 
-  # Column widths across the rows that share a column.
-  local label_w=0 width title_w=0 state_w=0 age_w=0 text state_text age_secs relative
+  # Column widths across the rows that share a column; the author column is there unless --mine chose the rows.
+  local label_w=0 width title_w=0 owner_w=0 state_w=0 age_w=0 text author state_text age_secs relative
   local -A worktree_on=()
   for doc in "${desk}" "${worktrees[@]}"
   do
@@ -357,15 +382,17 @@ status:render() {
     (( width > label_w )) && label_w=${width}
     [[ -n "${branch}" && "${doc}" != "${desk}" ]] && worktree_on[${branch}]=${relative}
   done
-  while IFS=$'\t' read -r text state_text age_secs
+  while IFS=$'\x1f' read -r text author state_text age_secs
   do
     [[ -n "${text}" ]] || continue
     (( ${#text} > title_w )) && title_w=${#text}
+    [[ "${choice}" != mine ]] && (( ${#author} > owner_w )) && owner_w=${#author}
     (( ${#state_text} > state_w )) && state_w=${#state_text}
     text=$(status:age "${age_secs}")
     (( ${#text} > age_w )) && age_w=${#text}
-  done < <(jq --raw-output '["#\(.number) \(.title)", .state, .age] | @tsv' <<<"${prs}")
-  width=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - 24 ))
+  done < <(jq --raw-output '["#\(.number) \(.title)", .author, .state, .age] | map(tostring) | join("\u001f")' \
+    <<<"${prs}")
+  width=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - 24 - (owner_w > 0 ? owner_w + 6 : 0) ))
   (( width < 20 )) && width=20
   (( title_w > width )) && title_w=${width}
 
@@ -382,7 +409,7 @@ status:render() {
     [[ -n "${doc}" ]] || continue
     printf '\n' >&2
     branch=$(jq --raw-output .branch <<<"${doc}")
-    status:pr-block "${doc}" "${title_w}" "${state_w}" "${age_w}" "${worktree_on[${branch}]:-}"
+    status:pr-block "${doc}" "${title_w}" "${owner_w}" "${state_w}" "${age_w}" "${worktree_on[${branch}]:-}"
   done <<<"${prs}"
   if [[ -n "${gone}" ]]
   then
diff --git a/justfile b/justfile
index 1fadc93..b87c1bc 100644
--- a/justfile
+++ b/justfile
@@ -49,7 +49,7 @@ ci:
   bin/kit lint --all-files
   ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
   ajv validate --spec=draft2020 -s .kit/settings.schema.json -d .kit/settings.yml
-  bats --print-output-on-failure tests/
+  bats --timing --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
 
diff --git a/tests/status.bats b/tests/status.bats
index 5b8eff0..a2b9a4a 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -108,17 +108,27 @@ commits-in() {
   [ "$output" = "$(printf 'topic on ../other\t17')" ]
 }
 
-@test "a pull request's row ends with its worktree, and the issues it closes follow" {
-  doc='{"number":2,"title":"The first","state":"queued","age":259200,"unresolved":0,'
-  doc+='"checks":{"state":"PENDING","passed":0,"total":1,"failing":0,"took":36},'
+@test "a pull request's row carries its author when asked and ends with its branch, and the issues it closes follow" {
+  doc='{"number":2,"title":"The first","author":"ada","branch":"2-the-first","state":"queued","age":259200,'
+  doc+='"unresolved":0,"checks":{"state":"PENDING","passed":0,"total":1,"failing":0,"took":36},'
   doc+='"closes":[{"number":1,"title":"One"},{"number":4,"title":"Four"}]}'
-  run in_status status:pr-block "${doc}" 12 6 2 worktrees/topic
-  [ "${lines[0]}" = "🔀 #2 The first   🚦 queued   3d   🏃 0 / 1 · 36s   🌿 worktrees/topic" ]
+  run in_status status:pr-block "${doc}" 12 0 6 2 worktrees/2-the-first
+  [ "${lines[0]}" = "🔀 #2 The first   🚦 queued   3d   🏃 0 / 1 · 36s   🌿 2-the-first" ]
   [ "${lines[1]}" = "   closes #1 One" ]
   [ "${lines[2]}" = "   closes #4 Four" ]
   [ "${#lines[@]}" -eq 3 ]
-  run in_status status:pr-block "${doc}" 12 6 2 ''
-  [ "${lines[0]}" = "🔀 #2 The first   🚦 queued   3d   🏃 0 / 1 · 36s" ]
+  run in_status status:pr-block "${doc}" 12 5 6 2 ''
+  [ "${lines[0]}" = "🔀 #2 The first   👤 ada     🚦 queued   3d   🏃 0 / 1 · 36s" ]
+}
+
+@test "the pull requests shown are everyone's, or the named authors' alone" {
+  docs=$(printf '{"number":1,"author":"ada"}\n{"number":2,"author":"bob"}\n{"number":3,"author":"cy"}\n')
+  run in_status status:select <<<"${docs}"
+  [ "$(jq --slurp --compact-output 'map(.number)' <<<"$output")" = "[1,2,3]" ]
+  run in_status status:select ada cy <<<"${docs}"
+  [ "$(jq --slurp 'map(.number) | join(",")' --raw-output <<<"$output")" = "1,3" ]
+  run in_status status:select nobody <<<"${docs}"
+  [ -z "$output" ]
 }
 
 @test "a path is printed relative to the current directory" {

From 212aac39050b3a9556288726e828c58f98a4457a Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 13:54:28 -0700
Subject: [PATCH 100/108] mise.toml: say why each tool is pinned

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 mise.toml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/mise.toml b/mise.toml
index 5757ed2..2c5457a 100644
--- a/mise.toml
+++ b/mise.toml
@@ -14,6 +14,15 @@ lockfile_platforms = ["linux-x64", "linux-arm64", "macos-arm64", "macos-x64"]
 [env]
 _.path = ["bin"]
 
+# Why each tool is here:
+#   actionlint          the workflows rule's linter, over .github/workflows/, in kit lint and the gate
+#   bats                runs tests/, the suite the gate runs
+#   gh                  the GitHub provider's tool: the loop's verbs, kit linked, and kit release publish and retire
+#   jq                  reads and writes JSON: the merged .claude/settings.json, the forge's documents, kit status
+#   just                runs the justfile: just ci, the gate, and just refresh, the installed copies
+#   ajv-cli             validates every module.yml and .kit/settings.yml against their schemas, in the gate
+#   markdownlint-cli2   the markdown rule's linter, over every .md file, in kit lint and the gate
+#   shellcheck          the bash rule's linter, over bin/ and tests/, in kit lint and the gate
 [tools]
 actionlint = "1.7"
 bats = "1.14"

From 9291160ff035826e88cd48fae1b45f5614e67717 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 13:59:51 -0700
Subject: [PATCH 101/108] Check every link in the markdown offline, in the gate

lychee is pinned and runs in just ci over the README, AGENTS.md, the docs, the modules, and
the installed copies: offline, so the gate stays deterministic, with fragments, so a section
link no heading matches is a red run. A link to a web page is excluded offline, and the
module pages point at GitHub on purpose, since a release ships without docs/.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 justfile  |  6 +++--
 mise.lock | 78 ++++++++++++++++++++++---------------------------------
 mise.toml |  2 ++
 3 files changed, 37 insertions(+), 49 deletions(-)

diff --git a/justfile b/justfile
index b87c1bc..266b4c3 100644
--- a/justfile
+++ b/justfile
@@ -37,18 +37,20 @@ _: help
 set export := true
 
 # The gate: kit lint over every tracked path, each rule's own linter, every module.yml and .kit/settings.yml
-# against their schemas, the bats suite, and bin/kit check over this repository's installed copy of its own kit.
+# against their schemas, every link in the markdown resolved offline with its fragment, the bats suite, and
+# bin/kit check over this repository's installed copy of its own kit.
 # The runner runs it on every pull request, and a desk runs it the same way; the pre-commit hook is the narrower,
 # faster check over the staged paths.
 #
 #   just ci
-[doc("🚦 The gate: kit lint, the schemas, bats, kit check")]
+[doc("🚦 The gate: kit lint, the schemas, the links, bats, kit check")]
 [script]
 ci:
   set -o errexit -o nounset -o pipefail
   bin/kit lint --all-files
   ajv validate --spec=draft2020 -s modules/module.schema.json -d 'modules/*/module.yml'
   ajv validate --spec=draft2020 -s .kit/settings.schema.json -d .kit/settings.yml
+  lychee --offline --include-fragments --no-progress README.md AGENTS.md docs modules .kit
   bats --timing --print-output-on-failure tests/
   bin/kit check
   echo "✅ ci passed"
diff --git a/mise.lock b/mise.lock
index 87f18eb..85ce098 100644
--- a/mise.lock
+++ b/mise.lock
@@ -37,10 +37,12 @@ backend = "aqua:bats-core/bats-core"
 specifiers = ["1.14"]
 
 [tools.bats."platforms.linux-arm64"]
+checksum = "sha256:bb537b70b15b732f6d8827dd6578e3d8ce166636ce1f18ea9a074184fcce9177"
 url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
 url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
 [tools.bats."platforms.linux-x64"]
+checksum = "sha256:bb537b70b15b732f6d8827dd6578e3d8ce166636ce1f18ea9a074184fcce9177"
 url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
 url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
@@ -50,6 +52,7 @@ url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
 url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
 [tools.bats."platforms.macos-x64"]
+checksum = "sha256:bb537b70b15b732f6d8827dd6578e3d8ce166636ce1f18ea9a074184fcce9177"
 url = "https://github.com/bats-core/bats-core/archive/refs/tags/v1.14.0.tar.gz"
 url_api = "https://api.github.com/repos/bats-core/bats-core/tarball/v1.14.0"
 
@@ -93,24 +96,12 @@ url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-arm64"
 url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012756"
 provenance = "github-attestations"
 
-[tools.jq."platforms.linux-arm64-musl"]
-checksum = "sha256:8b85c817833814ddca00a144c33705546355afccf0cf39b188f3cdb48b852309"
-url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-arm64"
-url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012756"
-provenance = "github-attestations"
-
 [tools.jq."platforms.linux-x64"]
 checksum = "sha256:b1c22172dd303f3be49e935aa56aa48a8b7a46e0bc838b4997d3bb451495870f"
 url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-amd64"
 url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012752"
 provenance = "github-attestations"
 
-[tools.jq."platforms.linux-x64-musl"]
-checksum = "sha256:b1c22172dd303f3be49e935aa56aa48a8b7a46e0bc838b4997d3bb451495870f"
-url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-amd64"
-url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012752"
-provenance = "github-attestations"
-
 [tools.jq."platforms.macos-arm64"]
 checksum = "sha256:2d75340ba57a4b4b4c8708a21c2dc8e958a48aaa8bba13b27f77f6e4c0eca07e"
 url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-macos-arm64"
@@ -123,12 +114,6 @@ url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-macos-amd64"
 url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012782"
 provenance = "github-attestations"
 
-[tools.jq."platforms.windows-x64"]
-checksum = "sha256:a6fc67fedaf9128a3309a1e2ebb8b986aeccf70122ee46d2cb4849e423f0c627"
-url = "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-windows-amd64.exe"
-url_api = "https://api.github.com/repos/jqlang/jq/releases/assets/453012788"
-provenance = "github-attestations"
-
 [[tools.just]]
 version = "1.59.0"
 backend = "aqua:casey/just"
@@ -139,21 +124,11 @@ checksum = "sha256:23871b1702bfd550fb5f901778fd4290ecf2ee034a45a889fbe96d89b1880
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-aarch64-unknown-linux-musl.tar.gz"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/642950086"
 
-[tools.just."platforms.linux-arm64-musl"]
-checksum = "sha256:23871b1702bfd550fb5f901778fd4290ecf2ee034a45a889fbe96d89b188086d"
-url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-aarch64-unknown-linux-musl.tar.gz"
-url_api = "https://api.github.com/repos/casey/just/releases/assets/642950086"
-
 [tools.just."platforms.linux-x64"]
 checksum = "sha256:409044617b6f06517c1035e55ca38c8c856ff8b650e41bc2aa1ef82d5903a23e"
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-unknown-linux-musl.tar.gz"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/642949555"
 
-[tools.just."platforms.linux-x64-musl"]
-checksum = "sha256:409044617b6f06517c1035e55ca38c8c856ff8b650e41bc2aa1ef82d5903a23e"
-url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-unknown-linux-musl.tar.gz"
-url_api = "https://api.github.com/repos/casey/just/releases/assets/642949555"
-
 [tools.just."platforms.macos-arm64"]
 checksum = "sha256:6574cea774ed4cae12e24b6aa11857de33e80dab4667cf628fd5840df96a2a9d"
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-aarch64-apple-darwin.tar.gz"
@@ -164,10 +139,34 @@ checksum = "sha256:036ead9df9bc31dbae9934ae3b4236ed124d0bafcffd33439460ae084d5c9
 url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-apple-darwin.tar.gz"
 url_api = "https://api.github.com/repos/casey/just/releases/assets/643131819"
 
-[tools.just."platforms.windows-x64"]
-checksum = "sha256:9c5463e2d0974e31bee71346aa5cbf19167de1585a4abc1bae7b3b04604ea9c0"
-url = "https://github.com/casey/just/releases/download/1.59.0/just-1.59.0-x86_64-pc-windows-msvc.zip"
-url_api = "https://api.github.com/repos/casey/just/releases/assets/643131303"
+[[tools.lychee]]
+version = "0.24.2"
+backend = "aqua:lycheeverse/lychee"
+specifiers = ["0.24"]
+
+[tools.lychee."platforms.linux-arm64"]
+checksum = "sha256:91a7bd65685da41b90ccb9bc867a3d649a7818042dae04ff405e55a25bddee4c"
+checksum_source = "mise-versions"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.24.2/lychee-aarch64-unknown-linux-gnu.tar.gz"
+url_api = "https://api.github.com/repos/lycheeverse/lychee/releases/assets/409959442"
+
+[tools.lychee."platforms.linux-x64"]
+checksum = "sha256:1f4e0ef7f6554a6ed33dd7ac144fb2e1bbed98598e7af973042fc5cd43951c9a"
+checksum_source = "mise-versions"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.24.2/lychee-x86_64-unknown-linux-gnu.tar.gz"
+url_api = "https://api.github.com/repos/lycheeverse/lychee/releases/assets/409959156"
+
+[tools.lychee."platforms.macos-arm64"]
+checksum = "sha256:c9d3740ea2d891854d37116c9fba840f37b6e7c89d330e7db84ac333631c4977"
+checksum_source = "mise-versions"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.24.2/lychee-aarch64-apple-darwin.tar.gz"
+url_api = "https://api.github.com/repos/lycheeverse/lychee/releases/assets/409957951"
+
+[tools.lychee."platforms.macos-x64"]
+checksum = "sha256:887503a9cff667d322b8d0892b40bf49976eb9507af8483220a3706cdad55978"
+checksum_source = "mise-versions"
+url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.24.2/lychee-x86_64-apple-darwin.tar.gz"
+url_api = "https://api.github.com/repos/lycheeverse/lychee/releases/assets/409957687"
 
 [[tools."npm:ajv-cli"]]
 version = "5.0.0"
@@ -191,21 +190,11 @@ checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14
 url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz"
 url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056934"
 
-[tools.shellcheck."platforms.linux-arm64-musl"]
-checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588"
-url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz"
-url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056934"
-
 [tools.shellcheck."platforms.linux-x64"]
 checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198"
 url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz"
 url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056942"
 
-[tools.shellcheck."platforms.linux-x64-musl"]
-checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198"
-url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz"
-url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056942"
-
 [tools.shellcheck."platforms.macos-arm64"]
 checksum = "sha256:56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79"
 url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.aarch64.tar.xz"
@@ -215,8 +204,3 @@ url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/2790
 checksum = "sha256:3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6"
 url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.x86_64.tar.xz"
 url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056930"
-
-[tools.shellcheck."platforms.windows-x64"]
-checksum = "sha256:8a4e35ab0b331c85d73567b12f2a444df187f483e5079ceffa6bda1faa2e740e"
-url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.zip"
-url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056944"
diff --git a/mise.toml b/mise.toml
index 2c5457a..438fc55 100644
--- a/mise.toml
+++ b/mise.toml
@@ -20,6 +20,7 @@ _.path = ["bin"]
 #   gh                  the GitHub provider's tool: the loop's verbs, kit linked, and kit release publish and retire
 #   jq                  reads and writes JSON: the merged .claude/settings.json, the forge's documents, kit status
 #   just                runs the justfile: just ci, the gate, and just refresh, the installed copies
+#   lychee              checks every link in the markdown, offline, fragments included, in the gate
 #   ajv-cli             validates every module.yml and .kit/settings.yml against their schemas, in the gate
 #   markdownlint-cli2   the markdown rule's linter, over every .md file, in kit lint and the gate
 #   shellcheck          the bash rule's linter, over bin/ and tests/, in kit lint and the gate
@@ -29,6 +30,7 @@ bats = "1.14"
 gh = "2.103"
 jq = "1.8"
 just = "1.59"
+lychee = "0.24"
 "npm:ajv-cli" = "5"
 "npm:markdownlint-cli2" = "0.24"
 shellcheck = "0.11"

From e0971fa5701faa146d0bf9009fecbc77de6ce272 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 17:58:25 -0700
Subject: [PATCH 102/108] #11 A module says what it expects of a file the
 repository owns, and kit check holds it

Where a format composes, the kit delivers a whole file under .kit/ and the repository's file
takes it with one include line. A module now says so under expects:, a path, an extended
regular expression some line must match, and a remedy. kit install and kit module add name
each unmet one as left to do, kit check refuses until it is met, and the kit writes nothing
into the file. The lefthook module is the first: it expects lefthook.yml to extend
.kit/lefthook.yml, which the README asked for and nothing checked.

The YAML subset gains a list of records, and a single-quoted value is taken literally, so a
pattern keeps its backslashes. The module schema grows the key. docs/modules.md states the
placement rule: an include where the format composes, a region where it has comments, a merge
by key where it has neither, a copy only where the file is the kit's own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                       |  3 ++-
 bin/kit-check.sh                |  7 ++++++
 bin/kit-module.sh               |  1 +
 bin/release.sh                  | 41 ++++++++++++++++++++++++++++++++-
 bin/yaml.sh                     | 36 +++++++++++++++++++++++++++++
 docs/modules.md                 | 18 +++++++++++++++
 modules/lefthook/docs/README.md |  3 ++-
 modules/lefthook/module.yml     |  4 ++++
 modules/module.schema.json      | 34 ++++++++++++++++++++++++++-
 tests/kit.bats                  | 18 +++++++++++++++
 10 files changed, 161 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6abb188..55a9d4a 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,8 @@ sees a new kit a day after it ships unless `[settings]` carries `minimum_release
   `kit linked`, from the delivered workflow or from any pipeline of your own, and refuses when there is none.
 - Run the linters before a commit. `kit lint` runs each rule's own linter over the staged paths with no hook
   manager at all. The `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
-  in `lefthook.yml`, and run `lefthook install` once per clone.
+  in `lefthook.yml`, and run `lefthook install` once per clone. `kit check` refuses until that line is there,
+  and the kit never writes it for you.
 
 `claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is present.
 The module places a region in `.claude/CLAUDE.md` importing `AGENTS.md`, so Claude reads what every agent reads in
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index 04ceb7e..bf28c97 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -67,6 +67,13 @@ do
     fi
   done <<<"${delivered}"
 done
+# Every line a module expects of a file the repository owns is there; the kit writes none of them.
+while IFS= read -r unmet
+do
+  [[ -n "${unmet}" ]] || continue
+  error "${unmet}"
+  findings=$(( findings + 1 ))
+done < <(release:unmet "${kit_root}" "${modules[@]}")
 # Every generated region, the kit's and the repository's own, is what its command makes it.
 generate:run --check || findings=$(( findings + 1 ))
 if (( findings > 0 ))
diff --git a/bin/kit-module.sh b/bin/kit-module.sh
index e143546..83f07e8 100755
--- a/bin/kit-module.sh
+++ b/bin/kit-module.sh
@@ -57,6 +57,7 @@ case "${verb}" in
     fi
     release:write-manifests "${wanted[@]}"
     ok "modules: ${wanted[*]}"
+    release:say-unmet "${wanted[@]}"
     ;;
   (remove)
     (( $# > 0 )) || { usage; exit 2; }
diff --git a/bin/release.sh b/bin/release.sh
index eccc4b9..0ef6887 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -196,7 +196,7 @@ release:validate() {
   for key in $(yaml:keys "${meta}")
   do
     case "${key}" in
-      (description | default | depends | answers) ;;
+      (description | default | depends | answers | expects) ;;
       (*)
         error "$(release:meta "${root}" "${module}") has a key the kit does not know: ${key}" \
           "(see modules/module.schema.json)"
@@ -224,6 +224,34 @@ release:validate() {
   done
 }
 
+# release:expectations <root> <module>… prints "<path>\x1f<pattern>\x1f<remedy>" for each line the modules expect
+# of a file the repository owns, the include a format composes by: lefthook's extends, just's import.
+release:expectations() {
+  local root=$1 module
+  shift
+  for module in "$@"
+  do
+    yaml:records "$(release:meta "${root}" "${module}")" expects path pattern remedy
+  done
+}
+
+# release:unmet <root> <module>… prints the remedy of every expectation the repository does not meet, one per
+# line: its file is missing, or no line of it matches the pattern, an extended regular expression. The kit
+# writes nothing into such a file; it only says what is missing.
+release:unmet() {
+  local root=$1 path pattern remedy
+  shift
+  while IFS=$'\x1f' read -r path pattern remedy
+  do
+    [[ -n "${path}" ]] || continue
+    if [[ ! -f "${path}" ]] || ! grep --quiet --extended-regexp -- "${pattern}" "${path}"
+    then
+      printf '%s: %s\n' "${path}" "${remedy:-a line matching ${pattern} is expected}"
+    fi
+  done < <(release:expectations "${root}" "$@")
+  return 0
+}
+
 # release:validate-settings refuses a settings file the schema would refuse, as far as bash can tell: a key the
 # kit does not know, a require_signing that is not true or false, an answer key outside [a-z_]. The gate
 # validates this repository's against .kit/settings.schema.json in full; the schema is delivered so an editor
@@ -958,7 +986,18 @@ release:require-manifest() {
 # release:finish <module>… reports a completed install or update.
 release:finish() {
   ok "kit $(release:version) is installed, modules: ${*:-none}; .kit/manifest is written."
+  release:say-unmet "$@"
   step "Commit the delivered files. The loop is in .kit/1st.md."
 }
 
+# release:say-unmet <module>… names, as a step left to do, every expectation of the modules not yet met.
+release:say-unmet() {
+  local line
+  while IFS= read -r line
+  do
+    [[ -n "${line}" ]] && warn "left to do in ${line}"
+  done < <(release:unmet "${kit_root}" "$@")
+  return 0
+}
+
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/yaml.sh b/bin/yaml.sh
index 8df9822..66bfc78 100644
--- a/bin/yaml.sh
+++ b/bin/yaml.sh
@@ -11,6 +11,12 @@
 #     - item
 #   key:                a map, one `  name: value` per line
 #     name: value
+#   key:                a list of records, each opened by `  - field: value` and continued by `    field: value`
+#     - field: value
+#       field: value
+#
+# A value may be double-quoted or single-quoted, and a single-quoted one is taken literally, backslashes and all,
+# which is how a pattern is written.
 #
 # A line starting with # is a comment. Nothing deeper is read, and a file that needs more is a file the kit does
 # not write. When the file opens with `---`, only the frontmatter up to the next `---` is read.
@@ -39,6 +45,36 @@ yaml:map() {
       gsub(/^"|"$/, "", v); print n "\t" v }'
 }
 
+# yaml:records <file> <key> <field>… prints one line per record of the list under <key>: the named fields' values,
+# in the order named, separated by the unit separator \x1f, since a pattern may hold a tab. A field a record
+# lacks is empty.
+yaml:records() {
+  local file=$1 key=$2
+  shift 2
+  yaml:read "${file}" | awk -v key="${key}" -v fields="$*" '
+    function unquote(v) {
+      if (v ~ /^".*"$/ || v ~ /^\x27.*\x27$/) v = substr(v, 2, length(v) - 2)
+      return v
+    }
+    function flush(   i, line) {
+      if (!open) return
+      line = ""
+      for (i = 1; i <= n; i++) line = line (i > 1 ? "\x1f" : "") value[names[i]]
+      print line
+      delete value
+      open = 0
+    }
+    BEGIN { n = split(fields, names, " ") }
+    $0 == key ":" { on = 1; next }
+    /^[A-Za-z0-9_-]/ { flush(); on = 0 }
+    on && /^  - [A-Za-z0-9_-]+: / { flush(); open = 1; sub(/^  - /, "") }
+    on && open && /^    [A-Za-z0-9_-]+: / { sub(/^    /, "") }
+    on && open && /^[A-Za-z0-9_-]+: / {
+      f = $0; sub(/: .*$/, "", f); v = $0; sub(/^[A-Za-z0-9_-]+: */, "", v); value[f] = unquote(v)
+    }
+    END { flush() }'
+}
+
 # yaml:keys <file> prints the top-level keys, one per line.
 yaml:keys() {
   yaml:read "$1" | awk '/^[A-Za-z0-9_-]+:/ { k = $0; sub(/:.*$/, "", k); print k }'
diff --git a/docs/modules.md b/docs/modules.md
index 7928860..f0443d7 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -47,6 +47,7 @@ answers:
 | `default` | `true` for a module active unless removed: `kit`. |
 | `depends` | Modules activated with this one. `kit module remove` refuses a module another active module depends on. |
 | `answers` | The default value of each template key. A repository overrides one under `answers:` in `.kit/settings.yml`. |
+| `expects` | Lines the module expects in files the repository owns, each a `path`, a `pattern`, and a `remedy`; see below. |
 
 [module.schema.json](../modules/module.schema.json) is the schema, JSON Schema 2020-12. This repository's gate validates
 every `module.yml` against it with `ajv`, and `kit install` holds a module to the same contract where no validator is: a
@@ -60,6 +61,23 @@ than a schema, `*.schema.json`, is merged by key: the kit's keys are set, its ar
 removal only the previous release's entries are taken out, so a repository's own keys and entries survive. Every other
 destination is a copy. Where two active modules deliver the same path, the later module in dependency order wins.
 
+Where a format composes, a module delivers a whole file of its own under `.kit/` and expects the repository's file to
+take it with one include line: lefthook's `extends`, just's `import`, git's `include`, markdownlint's `extends`. The
+module says so under `expects:`, a `path`, an extended regular expression some line of that file must match, and a
+`remedy`. `kit install` and `kit module add` name each one not yet met as left to do, `kit check` refuses until it is,
+and the kit writes nothing into the file, which stays the repository's entirely. The rule for any file the kit touches
+is then: an include where the format composes, a region where it has comments, a merge by key where it has neither, and
+a copy only where the file is the kit's own.
+
+```yaml
+expects:
+  - path: lefthook.yml
+    pattern: '\.kit/lefthook\.yml'
+    remedy: "put extends: [.kit/lefthook.yml] in lefthook.yml, so the kit's pre-commit commands run"
+```
+
+A single-quoted value is taken literally, backslashes and all, which is how a pattern is written.
+
 A file under `regions/<base>/` is the content of a region inside the file at the same path, rendered as a template
 is. What is placed there is the bare directive `kit:generate <path>`, the content, and the marker `kit:end <path>`, in
 the file's own comment syntax: `<!-- … -->` in markdown, `#` elsewhere, as [generate.md](generate.md) describes. Where
diff --git a/modules/lefthook/docs/README.md b/modules/lefthook/docs/README.md
index 15c17a4..e71c323 100644
--- a/modules/lefthook/docs/README.md
+++ b/modules/lefthook/docs/README.md
@@ -4,4 +4,5 @@ Places `.kit/lefthook.yml`, a pre-commit hook with two commands over the staged
 linter runs over the paths the rule governs before a commit, and `kit generate --check`, so a stale generated region is
 refused before it is committed. The repository's own `lefthook.yml` takes it with `extends: [.kit/lefthook.yml]` and
 adds commands of its own; Lefthook merges by name. The repository pins `lefthook` itself, since only a desk runs a hook,
-and `kit lint` and `kit generate` run the same way with no hook manager at all.
+and `kit lint` and `kit generate` run the same way with no hook manager at all. The module expects that line, so `kit
+install` names it as left to do and `kit check` refuses until it is there; the kit writes nothing into `lefthook.yml`.
diff --git a/modules/lefthook/module.yml b/modules/lefthook/module.yml
index 1316c6c..cc2e4e0 100644
--- a/modules/lefthook/module.yml
+++ b/modules/lefthook/module.yml
@@ -5,3 +5,7 @@
 description: "A pre-commit hook that runs kit lint over the staged paths, for the repository's lefthook.yml to extend"
 depends:
   - kit
+expects:
+  - path: lefthook.yml
+    pattern: '\.kit/lefthook\.yml'
+    remedy: "put extends: [.kit/lefthook.yml] in lefthook.yml, so the kit's pre-commit commands run"
diff --git a/modules/module.schema.json b/modules/module.schema.json
index 75c4299..b6206fb 100644
--- a/modules/module.schema.json
+++ b/modules/module.schema.json
@@ -5,7 +5,9 @@
   "description": "The metadata of one kit module, modules/<name>/module.yml; docs/modules.md says what each key means.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["description"],
+  "required": [
+    "description"
+  ],
   "properties": {
     "description": {
       "type": "string",
@@ -35,6 +37,36 @@
           "description": "The default value of a template key, written @key@ in the module's templates."
         }
       }
+    },
+    "expects": {
+      "type": "array",
+      "description": "Lines the module expects in files the repository owns, such as the include a format composes by; kit check reports one that is missing, with its remedy, and the kit writes none of them.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "pattern",
+          "remedy"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The file, relative to the repository root."
+          },
+          "pattern": {
+            "type": "string",
+            "minLength": 1,
+            "description": "An extended regular expression some line of the file must match."
+          },
+          "remedy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What to add, and why, printed when no line matches."
+          }
+        }
+      }
     }
   }
 }
diff --git a/tests/kit.bats b/tests/kit.bats
index 7ccb1af..50bfb86 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -349,6 +349,23 @@ later-release() {
   ! grep --quiet 'something else' AGENTS.md
 }
 
+@test "a module's expected include is named at install, refused by check until it is there, and never written" {
+  run "${kit_checkout}/bin/kit" install lefthook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"left to do in lefthook.yml: put extends: [.kit/lefthook.yml] in lefthook.yml"* ]]
+  [ ! -e lefthook.yml ]
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"lefthook.yml: put extends: [.kit/lefthook.yml] in lefthook.yml"* ]]
+  printf 'pre-commit:\n  commands: {}\n' > lefthook.yml
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 1 ]
+  printf 'extends:\n  - .kit/lefthook.yml\n' > lefthook.yml
+  run "${kit_checkout}/bin/kit" check
+  [ "$status" -eq 0 ]
+  [ "$(cat lefthook.yml)" = "$(printf 'extends:\n  - .kit/lefthook.yml')" ]
+}
+
 @test "install keeps the repository's own settings keys and deny entries" {
   mkdir .claude
   printf '{"model":"x","permissions":{"deny":["Bash(rm -rf /)"]}}\n' > .claude/settings.json
@@ -367,6 +384,7 @@ later-release() {
 
 @test "check passes after install and fails on a drifted, a missing, and a lost deny entry" {
   "${kit_checkout}/bin/kit" install claude lefthook
+  printf 'extends:\n  - .kit/lefthook.yml\n' > lefthook.yml
   run "${kit_checkout}/bin/kit" check
   [ "$status" -eq 0 ]
   printf 'edited\n' >> .kit/rules/yaml.md

From b48f45ae8297cbce83c5fb3bcd657d0917bed831 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 18:07:07 -0700
Subject: [PATCH 103/108] #12 A GitLab forge provider, the forge's noun, and a
 conformance suite every provider runs

bin/forge-gitlab.sh answers every call of the seam over glab and GitLab's REST API, folded with
jq in the provider so its logic is the kit's and a test can drive it. It is picked by an origin
at gitlab.com, or by forge: gitlab for a self-hosted GitLab. A merge request is the change, its
iid the number, its head pipeline's jobs the checks, its resolvable discussions the review
threads; GitLab has no command that makes a branch for an issue, so link-branch makes
<iid>-<slug> from the default branch, the name GitLab's issue page would give it.

The seam grows two calls. noun prints the change's sigil and name, "#" and "pull request" or
"!" and "merge request", and pr-url its browser URL, so kit status draws #3 or !3 in otherwise
identical rows, and kit linked and kit issue name the change in the forge's words. kit linked's
remedy is now a Closes #N line in the description, which both forges honor, in place of
GitHub's Development panel.

tests/forge-conformance.bats is one world seen through each forge's API: a routed fake stands
in for gh and glab, applying gh's --jq so the GitHub provider's own filters are what is
tested, and every call of both providers is held to the same answer. What only a real GitLab
can prove, that its API answers as the fixtures do, is not proven here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .kit/manifest                                 |   2 +-
 .kit/settings.schema.json                     |   4 +-
 README.md                                     |   6 +-
 bin/forge-github.sh                           |   8 +-
 bin/forge-gitlab.sh                           | 198 +++++++++++++++
 bin/forge.sh                                  |  11 +-
 bin/issue.sh                                  |   5 +-
 bin/kit-linked.sh                             |  27 +-
 bin/status.sh                                 |  11 +-
 docs/architecture.md                          |  14 +-
 docs/modules.md                               |   2 +-
 .../kit/files/repo/.kit/settings.schema.json  |   4 +-
 tests/fakes/fake-tool                         |  36 +++
 tests/forge-conformance.bats                  | 237 ++++++++++++++++++
 tests/forge.bats                              |  15 +-
 15 files changed, 537 insertions(+), 43 deletions(-)
 create mode 100644 bin/forge-gitlab.sh
 create mode 100755 tests/fakes/fake-tool
 create mode 100644 tests/forge-conformance.bats

diff --git a/.kit/manifest b/.kit/manifest
index f2d803d..9eb6ccc 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -15,5 +15,5 @@ bfa75fb42fd85d8c43034d910cff554fcbf1e273ad22806b481ebe985f1191f9  .kit/rules/jus
 87aa30f09c4d931d8c77731f0d6877d98e5ccfc32a775918f774bb5a5010b232  .kit/rules/markdown.md
 ceb28d32ae5522b1e0586551667bab18809c1f9be1ffcf0ed4eadbceffb2f99c  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
-b1d0219000842bd05d6e2b865854cd23ce4b221bfff5992f744de446b158da38  .kit/settings.schema.json
+80420c72402856b07e0171d80f45e750b3cc8c6142e31fe0740676a2ccd8f950  .kit/settings.schema.json
 dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
index 8a334ae..ecef373 100644
--- a/.kit/settings.schema.json
+++ b/.kit/settings.schema.json
@@ -8,8 +8,8 @@
   "properties": {
     "forge": {
       "type": "string",
-      "enum": ["github"],
-      "description": "The provider the loop's verbs use. Detected from origin's host when absent."
+      "enum": ["github", "gitlab"],
+      "description": "The provider the loop's verbs use: github or gitlab. Detected from origin's host, github.com or gitlab.com, when absent; a self-hosted forge is named here."
     },
     "gate": {
       "type": "string",
diff --git a/README.md b/README.md
index 55a9d4a..7c0ab52 100644
--- a/README.md
+++ b/README.md
@@ -58,9 +58,9 @@ export PATH="${PWD}/kit/bin:${PATH}"
 ```
 
 The kit needs bash 4.4 or later, git, and `jq`. The loop's verbs, `kit issue`, `kit status`, `kit tidy`, and `kit
-linked`, also need the tool of the forge, the service that hosts the repository: `gh` for GitHub. macOS ships bash 3.2,
-and `brew install bash` gives a current one. With mise, an exact pin installs the minute a release exists; a range pin
-sees a new kit a day after it ships unless `[settings]` carries `minimum_release_age_excludes =
+linked`, also need the tool of the forge, the service that hosts the repository: `gh` for GitHub, `glab` for GitLab.
+macOS ships bash 3.2, and `brew install bash` gives a current one. With mise, an exact pin installs the minute a release
+exists; a range pin sees a new kit a day after it ships unless `[settings]` carries `minimum_release_age_excludes =
 ["github:empowerite/kit"]`.
 
 ## Take the kit
diff --git a/bin/forge-github.sh b/bin/forge-github.sh
index 7461f66..7f493c8 100644
--- a/bin/forge-github.sh
+++ b/bin/forge-github.sh
@@ -27,6 +27,10 @@ forge-github:repo-url() {
     || { error "run: gh repo view (this checkout does not resolve to a GitHub repository)"; return 1; }
 }
 
+forge-github:noun() { printf '#\tpull request\n'; }
+
+forge-github:pr-url() { printf '%s/pull/%s\n' "$(forge-github:repo-url)" "$1"; }
+
 forge-github:me() {
   gh api user --jq '.login' 2>/dev/null && return 0
   error "run: gh auth login (the GitHub CLI is not authenticated)"
@@ -123,7 +127,7 @@ forge-github:pr-closing-issues() {
 }
 
 # One request: every open pull request with the issues it closes, its review threads, and the checks on its
-# head, folded into the document kit status draws: number, branch, title, author, createdAt, age in seconds,
+# head, folded into the document kit status draws: number, ref, branch, title, author, createdAt, age in seconds,
 # state, checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes [{number, title}].
 forge-github:open-prs() {
   local repo query filter
@@ -174,7 +178,7 @@ forge-github:open-prs() {
        elif $unresolved > 0 then "comments:open"
        elif (.reviewDecision // "") | IN("REVIEW_REQUIRED", "CHANGES_REQUESTED") then "blocked:approval"
        else "ready" end) as $state
-    | { number, branch: .headRefName, title, author: (.author.login // ""), createdAt,
+    | { number, ref: "#\(.number)", branch: .headRefName, title, author: (.author.login // ""), createdAt,
         age: ($now - (.createdAt | fromdateiso8601)), state: $state,
         checks: { state: $check, passed: $ok, total: $n, failing: $failing, took: $took },
         unresolved: $unresolved,
diff --git a/bin/forge-gitlab.sh b/bin/forge-gitlab.sh
new file mode 100644
index 0000000..c79c1a3
--- /dev/null
+++ b/bin/forge-gitlab.sh
@@ -0,0 +1,198 @@
+# shellcheck shell=bash
+# shellcheck disable=SC2016  # jq filters name their variables with $, in single quotes on purpose
+# forge-gitlab.sh - GitLab, through glab, as the forge the loop runs on (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/forge.sh loads for a repository whose forge is gitlab: gitlab.com by origin's host, or any
+# self-hosted GitLab by `forge: gitlab` in .kit/settings.yml, glab finding the host from origin as it does. Every
+# call is one of the names the seam's header lists, and answers in the same shape the GitHub provider does: a
+# merge request is the change, its iid the number, its pipeline's jobs the checks, its resolvable discussions the
+# review threads. glab is this file's requirement and nobody else's; the REST API is read through `glab api`, and
+# every document is folded here with jq, so the provider's logic is this file's and a test can drive it.
+
+# forge-gitlab:project prints the project's path with namespace, from origin: group/subgroup/name.
+forge-gitlab:project() {
+  local url
+  url=$(git remote get-url origin 2>/dev/null) || { error "this checkout has no origin; add one"; return 1; }
+  sed -E 's#^[a-z]+://[^/]+/##; s#^[^@/]+@[^:]+:##; s#\.git$##' <<<"${url}"
+}
+
+# forge-gitlab:api <path-under-the-project> [<glab api option>…] calls the REST API under the project, its path
+# encoded the way GitLab takes it in a URL.
+forge-gitlab:api() {
+  local path=$1 project
+  shift
+  project=$(forge-gitlab:project) || return 1
+  glab api "projects/${project//\//%2F}/${path}" "$@"
+}
+
+forge-gitlab:require() {
+  guard:require tool:glab || return 1
+  if ! glab api user >/dev/null 2>&1
+  then
+    error "run: glab auth login (the GitLab CLI is not authenticated)"
+    return 1
+  fi
+}
+
+forge-gitlab:repo() { forge-gitlab:project; }
+
+forge-gitlab:repo-url() {
+  local host
+  host=$(git remote get-url origin 2>/dev/null | sed -E 's#^([a-z]+://)?([^@/]+@)?([^/:]+).*#\3#')
+  printf 'https://%s/%s\n' "${host}" "$(forge-gitlab:project)"
+}
+
+forge-gitlab:noun() { printf '!\tmerge request\n'; }
+
+forge-gitlab:pr-url() { printf '%s/-/merge_requests/%s\n' "$(forge-gitlab:repo-url)" "$1"; }
+
+forge-gitlab:me() {
+  glab api user 2>/dev/null | jq --raw-output '.username' && return 0
+  error "run: glab auth login (the GitLab CLI is not authenticated)"
+  return 1
+}
+
+forge-gitlab:issue-create() {
+  local number
+  number=$(glab issue create --title "$1" --description "" --yes 2>/dev/null | sed -n 's@.*/-/issues/\([0-9]*\).*@\1@p' \
+    | tail -n 1)
+  if [[ ! "${number}" =~ ^[0-9]+$ ]]
+  then
+    error "run: glab auth status (the issue could not be created)"
+    return 1
+  fi
+  printf '%s\n' "${number}"
+}
+
+forge-gitlab:issue-title() {
+  forge-gitlab:api "issues/$1" 2>/dev/null | jq --raw-output '.title' \
+    || { error "run: glab auth status (the title of #$1 could not be read)"; return 1; }
+}
+
+forge-gitlab:issue-state() {
+  forge-gitlab:api "issues/$1" 2>/dev/null | jq --raw-output 'if .state == "closed" then "CLOSED" else "OPEN" end'
+}
+
+forge-gitlab:issue-assignees() {
+  forge-gitlab:api "issues/$1" 2>/dev/null | jq --raw-output '[.assignees[]?.username] | join(" ")'
+}
+
+forge-gitlab:issue-assign() {
+  glab issue update "$1" --assignee "+$2" >/dev/null 2>&1
+}
+
+forge-gitlab:branch-for-issue() {
+  forge-gitlab:api "merge_requests?state=opened&per_page=100" 2>/dev/null \
+    | jq --raw-output --arg n "$1" '[.[] | select(.source_branch | startswith($n + "-"))] | .[0].source_branch // empty' \
+    || true
+}
+
+# GitLab has no command that makes a branch for an issue, so the branch is made the way its issue page would make
+# it, <iid>-<slug of the title>, from the default branch; GitLab links a branch named so to the issue.
+forge-gitlab:link-branch() {
+  local title slug
+  title=$(forge-gitlab:issue-title "$1") || return 1
+  slug=$(tr '[:upper:]' '[:lower:]' <<<"${title}" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c 1-60)
+  slug=${slug%-}
+  forge-gitlab:api repository/branches --method POST --raw-field "branch=$1-${slug}" --raw-field "ref=$2" >/dev/null
+}
+
+forge-gitlab:pr-for-branch() {
+  forge-gitlab:api "merge_requests?state=opened&source_branch=$1" 2>/dev/null \
+    | jq --raw-output '.[0].iid // empty' || true
+}
+
+forge-gitlab:pr-create() {
+  local number
+  number=$(glab mr create --draft --source-branch "$1" --target-branch "$2" --title "$3" --description "" --yes \
+    | sed -n 's@.*/-/merge_requests/\([0-9]*\).*@\1@p' | tail -n 1) || return 1
+  [[ "${number}" =~ ^[0-9]+$ ]] || { error "the merge request could not be opened; see above"; return 1; }
+  printf '%s\n' "${number}"
+}
+
+forge-gitlab:pr-body() {
+  forge-gitlab:api "merge_requests/$1" | jq --raw-output '.description // ""'
+}
+
+forge-gitlab:pr-set-body() {
+  forge-gitlab:api "merge_requests/$1" --method PUT --raw-field "description=$2" >/dev/null
+}
+
+forge-gitlab:pr-state-for-branch() {
+  forge-gitlab:api "merge_requests?state=all&source_branch=$1&order_by=created_at&sort=desc" 2>/dev/null \
+    | jq --raw-output '.[0].state // empty | {merged: "MERGED", closed: "CLOSED", locked: "CLOSED"}[.] // "OPEN"' \
+    || true
+}
+
+# On a runner the pipeline names the merge request; on a desk the current branch does.
+forge-gitlab:pr-here() {
+  local number=${CI_MERGE_REQUEST_IID:-} branch
+  if [[ -z "${number}" ]]
+  then
+    branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+    [[ -n "${branch}" ]] && number=$(forge-gitlab:pr-for-branch "${branch}")
+  fi
+  printf '%s\n' "${number}"
+}
+
+forge-gitlab:pr-closing-issues() {
+  forge-gitlab:api "merge_requests/$1/closes_issues" 2>/dev/null \
+    | jq --raw-output '.[] | "\(.iid) \(if .state == "closed" then "CLOSED" else "OPEN" end) \(.references.full
+        | sub("#[0-9]+$"; ""))"' \
+    || { error "run: glab auth status (merge request !$1 could not be read)"; return 1; }
+}
+
+# Every open merge request folded into the document kit status draws, the GitHub provider's shape: number, ref,
+# branch, title, author, createdAt, age, state, checks {state, passed, total, failing, took}, unresolved, closes.
+# GitLab's REST API spreads these over four reads per merge request: the request, its pipeline's jobs, its
+# discussions, and the issues it closes.
+forge-gitlab:open-prs() {
+  local list iid mr jobs discussions closes pipeline
+  list=$(forge-gitlab:api "merge_requests?state=opened&per_page=100&order_by=created_at&sort=asc" 2>/dev/null) \
+    || { error "run: glab auth status (the merge requests could not be read)"; return 1; }
+  while IFS= read -r iid
+  do
+    [[ -n "${iid}" ]] || continue
+    mr=$(forge-gitlab:api "merge_requests/${iid}") || return 1
+    pipeline=$(jq --raw-output '.head_pipeline.id // empty' <<<"${mr}")
+    jobs='[]'
+    [[ -n "${pipeline}" ]] && jobs=$(forge-gitlab:api "pipelines/${pipeline}/jobs?per_page=100")
+    discussions=$(forge-gitlab:api "merge_requests/${iid}/discussions?per_page=100")
+    closes=$(forge-gitlab:api "merge_requests/${iid}/closes_issues")
+    jq --compact-output --null-input --argjson mr "${mr}" --argjson jobs "${jobs}" \
+      --argjson discussions "${discussions}" --argjson closes "${closes}" '
+      def pending: IN("created", "pending", "running", "preparing", "waiting_for_resource", "scheduled");
+      def passed: IN("success", "skipped", "manual");
+      (now | floor) as $now
+      | ($jobs | length) as $n
+      | ([$jobs[] | select(.status | pending)] | length) as $running
+      | ([$jobs[] | select(.status | passed)] | length) as $ok
+      | ([$jobs[] | select((.status | pending or passed) | not) | .name] | first // "") as $failing
+      | (if $n == 0 then "NONE" elif $failing != "" then "FAILURE" elif $running > 0 then "PENDING" else "SUCCESS" end)
+        as $check
+      | ([$jobs[] | .started_at // empty | sub("\\.[0-9]+"; "") | fromdateiso8601] | min) as $started
+      | ([$jobs[] | .finished_at // empty | sub("\\.[0-9]+"; "") | fromdateiso8601] | max) as $completed
+      | (if $started == null then null
+         elif $check == "PENDING" then $now - $started
+         elif $completed == null then null
+         else $completed - $started end) as $took
+      | ([$discussions[] | .notes[]? | select(.resolvable and (.resolved | not))] | length) as $unresolved
+      | (if $mr.draft then "draft"
+         elif $check == "PENDING" then "queued"
+         elif $mr.has_conflicts then "conflicted"
+         elif $check == "FAILURE" then "failing:gate"
+         elif $check == "NONE" then "no-check"
+         elif $unresolved > 0 then "comments:open"
+         elif ($mr.detailed_merge_status // "") == "not_approved" then "blocked:approval"
+         else "ready" end) as $state
+      | { number: $mr.iid, ref: "!\($mr.iid)", branch: $mr.source_branch, title: $mr.title,
+          author: ($mr.author.username // ""), createdAt: $mr.created_at,
+          age: ($now - ($mr.created_at | sub("\\.[0-9]+"; "") | fromdateiso8601)), state: $state,
+          checks: { state: $check, passed: $ok, total: $n, failing: $failing, took: $took },
+          unresolved: $unresolved,
+          closes: [$closes[] | { number: .iid, title }] }'
+  done < <(jq --raw-output '.[].iid' <<<"${list}")
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/forge.sh b/bin/forge.sh
index 8efbe5f..3a0c4e3 100644
--- a/bin/forge.sh
+++ b/bin/forge.sh
@@ -14,6 +14,8 @@
 #   require                       the provider's own tool is present and authenticated
 #   repo                          the repository as owner/name
 #   repo-url                      the repository's browser URL
+#   noun                          the change's reference sigil and its name, tab-separated: "#\tpull request"
+#   pr-url <n>                    the change's browser URL
 #   me                            the caller's login
 #   issue-create <title>          the number of the issue it creates
 #   issue-title <n>               the issue's title
@@ -33,8 +35,10 @@
 
 use release
 
-# forge:provider prints the provider's name: the forge setting, else github for an origin at github.com. It
-# fails, naming the remedy, where neither names a provider the kit carries.
+# forge:provider prints the provider's name: the forge setting, else github for an origin at github.com and
+# gitlab for one at gitlab.com. A self-hosted forge is named by the setting. It fails, naming the remedy, where
+# neither names a provider the kit carries. One origin is one forge: a repository on two is a mirror or a
+# migration, and the setting says which one the loop runs on.
 forge:provider() {
   local provider host=''
   provider=$(release:setting forge)
@@ -43,6 +47,7 @@ forge:provider() {
     host=$(git remote get-url origin 2>/dev/null | sed -E 's#^([a-z]+://)?([^@/]+@)?([^/:]+).*#\3#')
     case "${host}" in
       (github.com | *.github.com) provider=github ;;
+      (gitlab.com | *.gitlab.com) provider=gitlab ;;
     esac
   fi
   if [[ -z "${provider}" ]]
@@ -79,6 +84,8 @@ forge:require()             { forge:call require "$@"; }
 forge:repo()                { forge:call repo "$@"; }
 forge:repo-url()            { forge:call repo-url "$@"; }
 forge:me()                  { forge:call me "$@"; }
+forge:noun()                { forge:call noun "$@"; }
+forge:pr-url()              { forge:call pr-url "$@"; }
 forge:issue-create()        { forge:call issue-create "$@"; }
 forge:issue-title()         { forge:call issue-title "$@"; }
 forge:issue-state()         { forge:call issue-state "$@"; }
diff --git a/bin/issue.sh b/bin/issue.sh
index e5fe8dc..d210d88 100644
--- a/bin/issue.sh
+++ b/bin/issue.sh
@@ -177,7 +177,7 @@ issue:link-secondaries() {
 # issue:start [<number>…] is the on-ramp the file header describes. A desk without a signing key is refused
 # where the require_signing setting is true, before anything is written.
 issue:start() {
-  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr created
+  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr created sigil noun
   forge:require || return 1
   me=$(forge:me) || return 1
   if [[ "$(release:setting require_signing)" == true ]]
@@ -231,7 +231,8 @@ issue:start() {
   pr=$(issue:pull-request "${branch}" "${default_branch}" "${title}") || return
   (( $# > 1 )) && issue:link-secondaries "${pr}" "${@:2}"
 
-  ok "Draft pull request #${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
+  IFS=$'\t' read -r sigil noun < <(forge:noun)
+  ok "Draft ${noun} ${sigil}${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
   ok "Worktree ready: ${wt}"
   step "cd '${wt}'    # do all work there; this checkout stays on ${desk_branch}"
 }
diff --git a/bin/kit-linked.sh b/bin/kit-linked.sh
index ccc5fcb..e95446b 100755
--- a/bin/kit-linked.sh
+++ b/bin/kit-linked.sh
@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
-# kit-linked - refuse a pull request not linked to an open issue of this repository (kit verb)
+# kit-linked - refuse a change not linked to an open issue of this repository (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The delivered CI job's last check, and a check a desk can run on any pull request. The pull request is the
-# argument, else the one the forge says this checkout is working on. A linked issue of another repository, or a
+# The delivered CI job's last check, and a check a desk can run on any change: a pull request on GitHub, a merge
+# request on GitLab, named in the forge's own words. The change is the argument, else the one the forge says this
+# checkout is working on. A linked issue of another repository, or a
 # closed one, is noted and does not count. On a runner the remedy also lands in the step summary.
 #
 # see: bin/forge.sh
@@ -15,7 +16,7 @@ use forge
 
 if [[ "${1:-}" == --help ]]
 then
-  echo "usage: kit linked [<pull-request>]" >&2
+  echo "usage: kit linked [<number>]" >&2
   exit 0
 fi
 
@@ -23,21 +24,23 @@ number=${1:-}
 [[ -n "${number}" ]] || number=$(forge:pr-here)
 if [[ ! "${number}" =~ ^[0-9]+$ ]]
 then
-  error "name the pull request: kit linked <number> (none was given, and this checkout is working on none)"
+  error "name the change: kit linked <number> (none was given, and this checkout is working on none)"
   exit 2
 fi
+IFS=$'\t' read -r sigil noun < <(forge:noun) || exit 1
+change="${noun} ${sigil}${number}"
 repo=$(forge:repo) || exit 1
-url=$(forge:repo-url) || exit 1
+url=$(forge:pr-url "${number}") || exit 1
 remedy=$(printf '%s\n' \
-  "Link an open issue of this repository to [the pull request](${url}/pull/${number}):" "" \
-  "1. open it, and under **Development** pick one or more open issues" \
+  "Link an open issue of this repository to [the ${noun}](${url}):" "" \
+  "1. add a line \`Closes #<N>\` to its description for each open issue it resolves" \
   "2. re-run the check: linking fires no event, so it does not re-run on its own" "" \
   "\`kit issue <N>\` makes this link when it starts the work.")
 refs=$(forge:pr-closing-issues "${number}") || exit 1
 if [[ -z "${refs}" ]]
 then
-  error "pull request #${number} is not linked to any issue"
-  summary "### ❌ Pull request #${number} is not linked to any issue" "" "${remedy}"
+  error "${change} is not linked to any issue"
+  summary "### ❌ The ${change} is not linked to any issue" "" "${remedy}"
   exit 1
 fi
 open=0
@@ -55,12 +58,12 @@ do
 done <<<"${refs}"
 if (( open == 0 ))
 then
-  error "every issue pull request #${number} is linked to is closed or belongs to another repository"
+  error "every issue ${change} is linked to is closed or belongs to another repository"
   summary "### ❌ Every linked issue is closed or belongs to another repository" "" "${remedy}"
   exit 1
 fi
 closes=$(cut -d ' ' -f 1 <<<"${refs}" | sed 's/^/#/' | paste -s -d ' ' -)
-ok "pull request #${number} is linked to ${closes}"
+ok "${change} is linked to ${closes}"
 summary "✅ Linked to ${closes}."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/status.sh b/bin/status.sh
index 92a9fb2..b0f3f96 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -298,11 +298,12 @@ status:check-cell() {
 # a worktree here holds it, then the issues it closes.
 status:pr-block() {
   local doc=$1 title_w=$2 owner_w=$3 state_w=$4 age_w=$5 worktree=$6
-  local number title author branch state age unresolved row issue checks
-  IFS=$'\x1f' read -r number title author branch state age unresolved \
-    < <(jq --raw-output '[.number, .title, .author, .branch, .state, .age, .unresolved] | map(tostring)
+  local number ref title author branch state age unresolved row issue checks
+  IFS=$'\x1f' read -r number ref title author branch state age unresolved \
+    < <(jq --raw-output '[.number, (.ref // "#\(.number)"), .title, .author, .branch, .state, .age, .unresolved]
+          | map(tostring)
           | join("\u001f")' <<<"${doc}")
-  row="🔀 $(status:cell "#${number} ${title}" "${title_w}")"
+  row="🔀 $(status:cell "${ref} ${title}" "${title_w}")"
   (( owner_w > 0 )) && row+="   👤 $(status:paint 90 "$(status:cell "${author}" "${owner_w}")")"
   row+="   $(status:state-emoji "${state}")"
   row+=" $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
@@ -390,7 +391,7 @@ status:render() {
     (( ${#state_text} > state_w )) && state_w=${#state_text}
     text=$(status:age "${age_secs}")
     (( ${#text} > age_w )) && age_w=${#text}
-  done < <(jq --raw-output '["#\(.number) \(.title)", .author, .state, .age] | map(tostring) | join("\u001f")' \
+  done < <(jq --raw-output '["\(.ref // "#\(.number)") \(.title)", .author, .state, .age] | map(tostring) | join("\u001f")' \
     <<<"${prs}")
   width=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - 24 - (owner_w > 0 ? owner_w + 6 : 0) ))
   (( width < 20 )) && width=20
diff --git a/docs/architecture.md b/docs/architecture.md
index d316e6a..ddef8b6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -57,11 +57,15 @@ work off the desk into the worktree, the one change it makes to the desk, and sa
 the worktree: `kit context` before a change, `kit lint` for the pre-commit linters by hand, `kit rebase` to bring the
 branch onto the default branch at origin and push it, and `gh pr ready` when the pull request body is the report.
 
-Every call the loop makes to the forge, an issue's title, a branch linked to it, a pull request and its state,
-its checks and threads and linked issues, goes through one seam, `forge:` in `bin/forge.sh`, and a provider
-answers: `forge-github.sh` over `gh`, chosen by the `forge` setting or by origin's host. The core verbs never
-reach the seam, so a repository on no forge still installs, updates, checks, and runs `kit context`, and `gh` is
-the GitHub provider's requirement alone.
+Every call the loop makes to the forge, an issue's title, a branch linked to it, a change and its state, its checks and
+threads and linked issues, goes through one seam, `forge:` in `bin/forge.sh`, and a provider answers: `forge-github.sh`
+over `gh`, or `forge-gitlab.sh` over `glab`, chosen by the `forge` setting or by origin's host, github.com or
+gitlab.com; a self-hosted forge is named by the setting. Each answers in the same shape, so `kit status` draws the same
+picture on either, and each names the change in its own words, a pull request `#3` or a merge request `!3`. One origin
+is one forge: a repository on two is a mirror or a migration, and the setting says which one the loop runs on.
+tests/forge-conformance.bats drives every provider through a fake of its tool against one world and holds every answer
+to one shape. The core verbs never reach the seam, so a repository on no forge still installs, updates, checks, and runs
+`kit context`, and each forge's tool is its provider's requirement alone.
 The delivered check is `kit ci`, three checks that are each one kit command, run by the delivered GitHub Actions
 job for a pull request into the default branch, or by any pipeline. `kit gate` runs the repository's own gate,
 the `gate` setting or the detected justfile recipe, Makefile target, or `package.json` script, and refuses when
diff --git a/docs/modules.md b/docs/modules.md
index f0443d7..05ec7ed 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -114,7 +114,7 @@ answers:
 
 | Key | Meaning |
 | --- | --- |
-| `forge` | The provider the loop's verbs use, `github`; detected from origin's host when absent. |
+| `forge` | The provider the loop's verbs use, `github` or `gitlab`; detected from origin's host when absent, and named here for a self-hosted forge. |
 | `gate` | What `kit gate` runs; a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script is detected when absent. |
 | `require_signing` | `true` makes `kit issue` refuse a desk without a signing key. |
 | `answers` | The values a module's templates take, overriding the module's own defaults. |
diff --git a/modules/kit/files/repo/.kit/settings.schema.json b/modules/kit/files/repo/.kit/settings.schema.json
index 8a334ae..ecef373 100644
--- a/modules/kit/files/repo/.kit/settings.schema.json
+++ b/modules/kit/files/repo/.kit/settings.schema.json
@@ -8,8 +8,8 @@
   "properties": {
     "forge": {
       "type": "string",
-      "enum": ["github"],
-      "description": "The provider the loop's verbs use. Detected from origin's host when absent."
+      "enum": ["github", "gitlab"],
+      "description": "The provider the loop's verbs use: github or gitlab. Detected from origin's host, github.com or gitlab.com, when absent; a self-hosted forge is named here."
     },
     "gate": {
       "type": "string",
diff --git a/tests/fakes/fake-tool b/tests/fakes/fake-tool
new file mode 100755
index 0000000..5fcdc88
--- /dev/null
+++ b/tests/fakes/fake-tool
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# fake-tool - stands in for a forge's command-line tool in the conformance suite (test helper)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Linked as gh or glab on PATH. Every call is appended to ${FAKE_DIR}/<tool>.calls. The response is the first line
+# of ${FAKE_DIR}/<tool>.routes whose glob matches the arguments joined by spaces: "<glob>\t<file>", the file's
+# contents printed, or "<glob>\t!<status>" to fail with that status. A gh call carrying --jq has the filter applied
+# to the response, as gh does, so the provider's own filter is what is tested. An unrouted call fails.
+
+set -o errexit -o nounset -o pipefail
+tool=${0##*/}
+printf '%s\n' "$*" >> "${FAKE_DIR}/${tool}.calls"
+filter=''
+args=("$@")
+for (( i = 0; i < ${#args[@]}; i++ ))
+do
+  [[ "${args[i]}" == --jq ]] && filter=${args[i + 1]}
+done
+while IFS=$'\t' read -r glob response
+do
+  # shellcheck disable=SC2053  # the route is a glob on purpose
+  [[ -n "${glob}" && "$*" == ${glob} ]] || continue
+  if [[ "${response}" == '!'* ]]
+  then
+    exit "${response#!}"
+  fi
+  if [[ -n "${filter}" ]]
+  then
+    jq --raw-output "${filter}" "${FAKE_DIR}/${response}"
+  else
+    cat "${FAKE_DIR}/${response}"
+  fi
+  exit 0
+done < "${FAKE_DIR}/${tool}.routes"
+echo "${tool}: unrouted call: $*" >&2
+exit 1
diff --git a/tests/forge-conformance.bats b/tests/forge-conformance.bats
new file mode 100644
index 0000000..b322f6e
--- /dev/null
+++ b/tests/forge-conformance.bats
@@ -0,0 +1,237 @@
+#!/usr/bin/env bats
+# forge-conformance.bats - every forge provider answers the seam's calls in the same shape, through a fake of its tool
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# One world, seen through each forge's own API: the repository empowerite/example, the caller ada, issue 7 "Fix
+# the thing" assigned to bob, and change 3 on branch 7-fix-the-thing, opened by ada, closing issue 7, with two
+# checks that passed in a minute and one unresolved review thread. Each provider is driven by tests/fakes/fake-tool
+# standing in for its tool, so what is proven is the provider's own folding of its forge's answers into the seam's
+# shape. What only a real forge can prove, that the API answers as the fixtures do, is not proven here.
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  export FAKE_DIR="${BATS_TEST_TMPDIR}/fake"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}" "${FAKE_DIR}/bin"
+  ln -s "${BATS_TEST_DIRNAME}/fakes/fake-tool" "${FAKE_DIR}/bin/gh"
+  ln -s "${BATS_TEST_DIRNAME}/fakes/fake-tool" "${FAKE_DIR}/bin/glab"
+  export PATH="${FAKE_DIR}/bin:${PATH}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+  unset GITHUB_EVENT_PATH CI_MERGE_REQUEST_IID
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+# call <call> <argument>… runs one call of the seam, as a verb would.
+call() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use forge && "forge:$0" "$@"' "$@"
+}
+
+# provider prints the provider the seam picks here.
+provider() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use forge && forge:provider'
+}
+
+# fixture <name> writes stdin to a response file the routes name.
+fixture() { cat > "${FAKE_DIR}/$1"; }
+
+# route <tool> <glob> <response> adds a route, the more particular before the more general.
+route() { printf '%s\t%s\n' "$2" "$3" >> "${FAKE_DIR}/$1.routes"; }
+
+# world <forge> makes this repository's origin the forge's, and its tool's routes the world above.
+world() {
+  git remote remove origin 2>/dev/null || true
+  "world-$1"
+}
+
+world-github() {
+  git remote add origin https://github.com/empowerite/example.git
+  : > "${FAKE_DIR}/gh.routes"
+  fixture user.json <<<'{"login": "ada"}'
+  fixture repo.json <<<'{"nameWithOwner": "empowerite/example", "url": "https://github.com/empowerite/example"}'
+  fixture issue.json <<<'{"title": "Fix the thing", "state": "OPEN", "assignees": [{"login": "bob"}]}'
+  fixture open-heads.json <<<'[{"headRefName": "9-other"}, {"headRefName": "7-fix-the-thing"}]'
+  fixture pr-open.json <<<'[{"number": 3}]'
+  fixture pr-all.json <<<'[{"state": "OPEN"}]'
+  fixture pr-url.txt <<<'https://github.com/empowerite/example/pull/3'
+  fixture issue-url.txt <<<'https://github.com/empowerite/example/issues/7'
+  fixture closing.json <<'JSON'
+{"data": {"repository": {"pullRequest": {"closingIssuesReferences": {"nodes": [
+  {"number": 7, "state": "OPEN", "repository": {"nameWithOwner": "empowerite/example"}}]}}}}}
+JSON
+  fixture open-prs.json <<'JSON'
+{"data": {"repository": {"pullRequests": {"nodes": [{
+  "number": 3, "title": "Fix the thing", "isDraft": false, "headRefName": "7-fix-the-thing",
+  "createdAt": "2026-10-01T09:00:00Z", "mergeStateStatus": "CLEAN", "reviewDecision": null,
+  "author": {"login": "ada"},
+  "closingIssuesReferences": {"nodes": [{"number": 7, "title": "Fix the thing"}]},
+  "reviewThreads": {"nodes": [{"isResolved": true}, {"isResolved": false}]},
+  "commits": {"nodes": [{"commit": {"statusCheckRollup": {"contexts": {"nodes": [
+    {"__typename": "CheckRun", "name": "a", "status": "COMPLETED", "conclusion": "SUCCESS",
+     "startedAt": "2026-10-01T10:00:00Z", "completedAt": "2026-10-01T10:00:30Z"},
+    {"__typename": "CheckRun", "name": "b", "status": "COMPLETED", "conclusion": "SUCCESS",
+     "startedAt": "2026-10-01T10:00:10Z", "completedAt": "2026-10-01T10:01:00Z"}]}}}}]}}]}}}}
+JSON
+  route gh 'api user*' user.json
+  route gh 'repo view*' repo.json
+  route gh 'issue view 7 *' issue.json
+  route gh 'issue create*' issue-url.txt
+  route gh 'issue edit 7 --add-assignee ada' '!0'
+  route gh 'pr list --state open --json headRefName*' open-heads.json
+  route gh 'pr list --head 7-fix-the-thing --state open*' pr-open.json
+  route gh 'pr list --head 7-fix-the-thing --state all*' pr-all.json
+  route gh 'pr create --draft --base main --head 7-fix-the-thing --title Fix the thing*' pr-url.txt
+  route gh 'api graphql*number=3*' closing.json
+  route gh 'api graphql*' open-prs.json
+}
+
+world-gitlab() {
+  git remote add origin git@gitlab.com:empowerite/example.git
+  : > "${FAKE_DIR}/glab.routes"
+  local p='projects/empowerite%2Fexample'
+  fixture user.json <<<'{"username": "ada"}'
+  fixture issue.json <<<'{"iid": 7, "title": "Fix the thing", "state": "opened", "assignees": [{"username": "bob"}]}'
+  fixture mrs-open.json <<<'[{"iid": 2, "source_branch": "9-other"}, {"iid": 3, "source_branch": "7-fix-the-thing"}]'
+  fixture mrs-list.json <<<'[{"iid": 3}]'
+  fixture mr-by-branch.json <<<'[{"iid": 3}]'
+  fixture mr-states.json <<<'[{"state": "opened"}]'
+  fixture mr-url.txt <<<'https://gitlab.com/empowerite/example/-/merge_requests/3'
+  fixture issue-url.txt <<<'https://gitlab.com/empowerite/example/-/issues/7'
+  fixture mr.json <<'JSON'
+{"iid": 3, "title": "Fix the thing", "draft": false, "source_branch": "7-fix-the-thing",
+ "created_at": "2026-10-01T09:00:00.000Z", "author": {"username": "ada"}, "has_conflicts": false,
+ "detailed_merge_status": "mergeable", "description": "", "head_pipeline": {"id": 11, "status": "success"}}
+JSON
+  fixture jobs.json <<'JSON'
+[{"name": "a", "status": "success", "started_at": "2026-10-01T10:00:00.120Z", "finished_at": "2026-10-01T10:00:30.000Z"},
+ {"name": "b", "status": "success", "started_at": "2026-10-01T10:00:10.000Z", "finished_at": "2026-10-01T10:01:00.450Z"}]
+JSON
+  fixture discussions.json <<'JSON'
+[{"notes": [{"resolvable": true, "resolved": true}]}, {"notes": [{"resolvable": true, "resolved": false}]},
+ {"notes": [{"resolvable": false, "resolved": false}]}]
+JSON
+  fixture closes.json <<'JSON'
+[{"iid": 7, "title": "Fix the thing", "state": "opened", "references": {"full": "empowerite/example#7"}}]
+JSON
+  fixture none.json <<<'[]'
+  route glab 'api user' user.json
+  route glab "api ${p}/issues/7" issue.json
+  route glab 'issue create*' issue-url.txt
+  route glab 'issue update 7 --assignee +ada' '!0'
+  route glab "api ${p}/merge_requests?state=opened&per_page=100&order_by=*" mrs-list.json
+  route glab "api ${p}/merge_requests?state=opened&per_page=100" mrs-open.json
+  route glab "api ${p}/merge_requests?state=opened&source_branch=7-fix-the-thing" mr-by-branch.json
+  route glab "api ${p}/merge_requests?state=all&source_branch=7-fix-the-thing*" mr-states.json
+  route glab "api ${p}/merge_requests/3/closes_issues" "${GITLAB_CLOSES:-closes.json}"
+  route glab "api ${p}/merge_requests/3/discussions*" discussions.json
+  route glab "api ${p}/merge_requests/3" mr.json
+  route glab "api ${p}/pipelines/11/jobs*" jobs.json
+  route glab "api ${p}/repository/branches --method POST*" '!0'
+  route glab 'mr create --draft --source-branch 7-fix-the-thing --target-branch main --title Fix the thing*' mr-url.txt
+}
+
+@test "the forge is picked by origin's host, github.com or gitlab.com, and either answers the same plain calls" {
+  for forge in github gitlab
+  do
+    world "${forge}"
+    run provider
+    [ "$output" = "${forge}" ]
+    run call repo
+    [ "$output" = "empowerite/example" ]
+    run call me
+    [ "$output" = "ada" ]
+    run call issue-title 7
+    [ "$output" = "Fix the thing" ]
+    run call issue-state 7
+    [ "$output" = "OPEN" ]
+    run call issue-assignees 7
+    [ "$output" = "bob" ]
+    run call issue-create "Fix the thing"
+    [ "$output" = "7" ]
+    run call issue-assign 7 ada
+    [ "$status" -eq 0 ]
+  done
+}
+
+@test "every provider finds, opens, and reads a change by its branch the same way" {
+  for forge in github gitlab
+  do
+    world "${forge}"
+    run call branch-for-issue 7
+    [ "$output" = "7-fix-the-thing" ]
+    run call branch-for-issue 8
+    [ -z "$output" ]
+    run call pr-for-branch 7-fix-the-thing
+    [ "$output" = "3" ]
+    run call pr-state-for-branch 7-fix-the-thing
+    [ "$output" = "OPEN" ]
+    run call pr-create 7-fix-the-thing main "Fix the thing"
+    [ "$output" = "3" ]
+    run call pr-closing-issues 3
+    [ "$output" = "7 OPEN empowerite/example" ]
+  done
+}
+
+@test "every provider folds its open changes into the one document kit status draws" {
+  expected='{"number":3,"branch":"7-fix-the-thing","title":"Fix the thing","author":"ada",'
+  expected+='"state":"comments:open","checks":{"state":"SUCCESS","passed":2,"total":2,"failing":"","took":60},'
+  expected+='"unresolved":1,"closes":[{"number":7,"title":"Fix the thing"}]}'
+  for forge in github gitlab
+  do
+    world "${forge}"
+    run call open-prs
+    [ "$status" -eq 0 ]
+    [ "$(jq --compact-output --sort-keys 'del(.age, .createdAt, .ref)' <<<"$output")" \
+      = "$(jq --compact-output --sort-keys . <<<"${expected}")" ]
+  done
+}
+
+@test "each provider names the change in its own words, and the rest of the picture is identical" {
+  world github
+  run call noun
+  [ "$output" = "$(printf '#\tpull request')" ]
+  run call pr-url 3
+  [ "$output" = "https://github.com/empowerite/example/pull/3" ]
+  [ "$(call open-prs | jq --raw-output .ref)" = "#3" ]
+  world gitlab
+  run call noun
+  [ "$output" = "$(printf '!\tmerge request')" ]
+  run call pr-url 3
+  [ "$output" = "https://gitlab.com/empowerite/example/-/merge_requests/3" ]
+  [ "$(call open-prs | jq --raw-output .ref)" = "!3" ]
+}
+
+@test "GitLab makes the branch for an issue as its issue page would, and a self-hosted GitLab is the setting" {
+  world gitlab
+  run call link-branch 7 main
+  [ "$status" -eq 0 ]
+  grep --quiet -- '--raw-field branch=7-fix-the-thing --raw-field ref=main' "${FAKE_DIR}/glab.calls"
+  git remote set-url origin https://git.example.com/empowerite/example.git
+  run provider
+  [ "$status" -eq 1 ]
+  mkdir .kit && printf 'forge: gitlab\n' > .kit/settings.yml
+  run provider
+  [ "$output" = "gitlab" ]
+  run call repo-url
+  [ "$output" = "https://git.example.com/empowerite/example" ]
+}
+
+@test "kit linked speaks the forge's words: a merge request on GitLab, its URL in the remedy" {
+  export GITHUB_STEP_SUMMARY="${BATS_TEST_TMPDIR}/summary.md"
+  GITLAB_CLOSES=none.json world gitlab
+  run "${kit_root}/bin/kit" linked 3
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"merge request !3 is not linked to any issue"* ]]
+  grep --quiet 'https://gitlab.com/empowerite/example/-/merge_requests/3' "${GITHUB_STEP_SUMMARY}"
+  world gitlab
+  run "${kit_root}/bin/kit" linked 3
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"merge request !3 is linked to #7"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/forge.bats b/tests/forge.bats
index e6d0ee3..5e9e467 100644
--- a/tests/forge.bats
+++ b/tests/forge.bats
@@ -21,7 +21,7 @@ provider() {
   bash -c 'source "${kit_root}/bin/1st.sh" && use forge && forge:provider'
 }
 
-@test "an origin at github.com names the github provider, by https or ssh" {
+@test "an origin at github.com names the github provider, and one at gitlab.com the gitlab one, by https or ssh" {
   git remote add origin https://github.com/empowerite/kit.git
   run provider
   [ "$status" -eq 0 ]
@@ -29,14 +29,17 @@ provider() {
   git remote set-url origin git@github.com:empowerite/kit.git
   run provider
   [ "$output" = "github" ]
+  git remote set-url origin git@gitlab.com:empowerite/kit.git
+  run provider
+  [ "$output" = "gitlab" ]
 }
 
 @test "an origin elsewhere, or none, is refused naming the setting and the forges the kit knows" {
-  git remote add origin https://gitlab.com/empowerite/kit.git
+  git remote add origin https://codeberg.org/empowerite/kit.git
   run provider
   [ "$status" -eq 1 ]
-  [[ "$output" == *"set forge in .kit/settings.yml; origin's host 'gitlab.com' names no forge the kit knows"* ]]
-  [[ "$output" == *"(github)"* ]]
+  [[ "$output" == *"set forge in .kit/settings.yml; origin's host 'codeberg.org' names no forge the kit knows"* ]]
+  [[ "$output" == *"(github gitlab)"* ]]
   git remote remove origin
   run provider
   [ "$status" -eq 1 ]
@@ -44,7 +47,7 @@ provider() {
 }
 
 @test "the forge setting wins, and an unknown one is refused by name" {
-  git remote add origin https://gitlab.com/empowerite/kit.git
+  git remote add origin https://codeberg.org/empowerite/kit.git
   mkdir .kit && printf 'forge: github\n' > .kit/settings.yml
   run provider
   [ "$status" -eq 0 ]
@@ -52,7 +55,7 @@ provider() {
   printf 'forge: sourcehut\n' > .kit/settings.yml
   run provider
   [ "$status" -eq 1 ]
-  [[ "$output" == *"'sourcehut' is not a forge the kit knows; the forges are: github"* ]]
+  [[ "$output" == *"'sourcehut' is not a forge the kit knows; the forges are: github gitlab"* ]]
 }
 
 @test "the core verbs need no forge and no gh" {

From b8ecd9ad4024425e7259777d771939f1e9da2eac Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 18:15:30 -0700
Subject: [PATCH 104/108] #13 A tracker seam apart from the forge: GitHub or
 GitLab issues, ADO work items, and references that carry their tracker

An issue lives in a tracker, and the tracker is not always the forge. bin/tracker.sh is the
seam: a reference names its tracker by its prefix, #7 or a bare 7 for the forge's own issues
and AB#4521 for an Azure DevOps work item, and .kit/settings.yml declares every tracker but
the forge's own as a record, a prefix, a provider, and the provider's fields. Two providers:
tracker-forge.sh, which hands each call to the forge seam, and tracker-ado.sh over az boards,
closed in Closed, Done, and Removed, the caller being the identity az is signed in as.

kit issue takes references. Each issue is assigned as its tracker knows the caller; the
branch opens with the reference's key, 7-<slug> or ab4521-<slug>, made from the default
branch when the forge cannot link one; the start commit's subject opens with the reference;
and a primary the forge cannot link, like every secondary, gets a Closes <reference> line in
the change's body. kit linked accepts a body's closing keyword naming an open item of a
declared tracker beside the forge's own closing issues, and kit tidy reads a branch's issue
back from its key in any tracker.

tests/tracker.bats covers parsing, keys, body references, the ADO provider through a fake
az, kit linked on a work item, and the settings check. docs/trackers.md is the page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .kit/manifest                                 |   2 +-
 .kit/settings.schema.json                     |  44 ++++-
 README.md                                     |   4 +-
 bin/forge-gitlab.sh                           |   7 +-
 bin/generate.sh                               |   2 +-
 bin/git.sh                                    |  14 +-
 bin/issue.sh                                  | 141 +++++++-------
 bin/kit                                       |   2 +-
 bin/kit-issue.sh                              |   7 +-
 bin/kit-linked.sh                             |  25 ++-
 bin/release.sh                                |  32 ++--
 bin/status.sh                                 |   3 +-
 bin/tracker-ado.sh                            |  89 +++++++++
 bin/tracker-forge.sh                          |  26 +++
 bin/tracker.sh                                | 175 ++++++++++++++++++
 docs/modules.md                               |   1 +
 docs/trackers.md                              |  53 ++++++
 .../kit/files/repo/.kit/settings.schema.json  |  44 ++++-
 tests/tracker.bats                            | 147 +++++++++++++++
 19 files changed, 721 insertions(+), 97 deletions(-)
 create mode 100644 bin/tracker-ado.sh
 create mode 100644 bin/tracker-forge.sh
 create mode 100644 bin/tracker.sh
 create mode 100644 docs/trackers.md
 create mode 100644 tests/tracker.bats

diff --git a/.kit/manifest b/.kit/manifest
index 9eb6ccc..746cccb 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -15,5 +15,5 @@ bfa75fb42fd85d8c43034d910cff554fcbf1e273ad22806b481ebe985f1191f9  .kit/rules/jus
 87aa30f09c4d931d8c77731f0d6877d98e5ccfc32a775918f774bb5a5010b232  .kit/rules/markdown.md
 ceb28d32ae5522b1e0586551667bab18809c1f9be1ffcf0ed4eadbceffb2f99c  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
-80420c72402856b07e0171d80f45e750b3cc8c6142e31fe0740676a2ccd8f950  .kit/settings.schema.json
+9c97c48f4578df3af8ffdd4eec9a511281b79ae87aae2cb04d53a093f1301811  .kit/settings.schema.json
 dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
index ecef373..7691f78 100644
--- a/.kit/settings.schema.json
+++ b/.kit/settings.schema.json
@@ -8,7 +8,10 @@
   "properties": {
     "forge": {
       "type": "string",
-      "enum": ["github", "gitlab"],
+      "enum": [
+        "github",
+        "gitlab"
+      ],
       "description": "The provider the loop's verbs use: github or gitlab. Detected from origin's host, github.com or gitlab.com, when absent; a self-hosted forge is named here."
     },
     "gate": {
@@ -29,6 +32,45 @@
           "description": "The value a module's template takes for this key, written @key@ in the template."
         }
       }
+    },
+    "trackers": {
+      "type": "array",
+      "description": "The trackers whose issues the loop takes besides the forge's own, which answers # unless a record claims it. A reference names its tracker by its prefix: #7, AB#4521.",
+      "items": {
+        "type": "object",
+        "required": [
+          "prefix",
+          "provider"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "prefix": {
+            "type": "string",
+            "pattern": "^[A-Za-z]*#?$",
+            "description": "What a reference to this tracker opens with, before the number: AB# for Azure DevOps work items."
+          },
+          "provider": {
+            "type": "string",
+            "enum": [
+              "forge",
+              "ado"
+            ],
+            "description": "Which tracker answers: forge for the forge's own issues, ado for Azure DevOps work items."
+          },
+          "organization": {
+            "type": "string",
+            "description": "ado: the organization's URL, https://dev.azure.com/<name>."
+          },
+          "project": {
+            "type": "string",
+            "description": "ado: the project a new work item is created in."
+          },
+          "type": {
+            "type": "string",
+            "description": "ado: the type of a new work item, Task when absent."
+          }
+        }
+      }
     }
   }
 }
diff --git a/README.md b/README.md
index 7c0ab52..2927db0 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,9 @@ Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
 
 - An issue exists. A change without an issue has not started.
 - `kit issue <N>` makes `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a
-  draft pull request. It never switches the checkout it runs from.
+  draft pull request. It never switches the checkout it runs from. An issue in another tracker is named by its
+  own reference, `kit issue AB#4521` for an Azure DevOps work item; [docs/trackers.md](docs/trackers.md) says how a
+  repository declares one.
 - Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`. `kit rebase`
   brings the branch up to date with `main` and pushes it, and `kit status` shows every pull request in flight
   and the worktree it is written in.
diff --git a/bin/forge-gitlab.sh b/bin/forge-gitlab.sh
index c79c1a3..e685127 100644
--- a/bin/forge-gitlab.sh
+++ b/bin/forge-gitlab.sh
@@ -55,8 +55,8 @@ forge-gitlab:me() {
 
 forge-gitlab:issue-create() {
   local number
-  number=$(glab issue create --title "$1" --description "" --yes 2>/dev/null | sed -n 's@.*/-/issues/\([0-9]*\).*@\1@p' \
-    | tail -n 1)
+  number=$(glab issue create --title "$1" --description "" --yes 2>/dev/null \
+    | sed -n 's@.*/-/issues/\([0-9]*\).*@\1@p' | tail -n 1)
   if [[ ! "${number}" =~ ^[0-9]+$ ]]
   then
     error "run: glab auth status (the issue could not be created)"
@@ -84,7 +84,8 @@ forge-gitlab:issue-assign() {
 
 forge-gitlab:branch-for-issue() {
   forge-gitlab:api "merge_requests?state=opened&per_page=100" 2>/dev/null \
-    | jq --raw-output --arg n "$1" '[.[] | select(.source_branch | startswith($n + "-"))] | .[0].source_branch // empty' \
+    | jq --raw-output --arg n "$1" \
+      '[.[] | select(.source_branch | startswith($n + "-"))] | .[0].source_branch // empty' \
     || true
 }
 
diff --git a/bin/generate.sh b/bin/generate.sh
index ab77e56..4d5ad00 100644
--- a/bin/generate.sh
+++ b/bin/generate.sh
@@ -1,7 +1,7 @@
 # shellcheck shell=bash
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
 # shellcheck disable=SC2016  # the $ in a pattern anchors a line; nothing is meant to expand
-# generate.sh - a directive opens a named region a command fills: discovery, expansion, and the fixed point (sourced module)
+# generate.sh - a directive opens a named region a command fills, expanded to a fixed point (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # A line that is `kit:generate <name>`, or `kit:generate <name> `<command>``, with nothing but non-alphanumeric
diff --git a/bin/git.sh b/bin/git.sh
index 40ce195..105ede0 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -2,7 +2,8 @@
 # git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The sweep asks the forge, through bin/forge.sh, whether a worktree's pull request is merged or closed.
+# The sweep asks the forge, through bin/forge.sh, whether a worktree's change is merged or closed, and the issue's
+# tracker, through bin/tracker.sh, whether its issue is.
 
 use forge
 
@@ -61,7 +62,7 @@ git:clean() {
 # git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides one worktree and
 # says why. It returns 0 when the worktree was removed, or would be under a dry run, and 1 when it is kept.
 git:tidy-worktree() {
-  local path=$1 branch=$2 detached=$3 default_branch=$4 self_root=$5 dry_run=$6 state="" number
+  local path=$1 branch=$2 detached=$3 default_branch=$4 self_root=$5 dry_run=$6 state="" ref
   if [[ "${path}" == "${self_root}" ]]
   then
     step "keeping ${path} (this command runs in it)"
@@ -75,10 +76,11 @@ git:tidy-worktree() {
   if [[ -n "${branch}" ]]
   then
     state=$(forge:pr-state-for-branch "${branch}")
-    if [[ -z "${state}" && "${branch}" =~ ^([0-9]+)- ]]
+    if [[ -z "${state}" ]]
     then
-      number=${BASH_REMATCH[1]}
-      [[ "$(forge:issue-state "${number}")" == CLOSED ]] && state=CLOSED
+      use tracker
+      ref=$(tracker:branch-ref "${branch}")
+      [[ -n "${ref}" && "$(tracker:of "${ref}" state)" == CLOSED ]] && state=CLOSED
     fi
   elif [[ "${detached}" == true ]]
   then
@@ -104,7 +106,7 @@ git:tidy-worktree() {
       return 0
       ;;
     (*)
-      step "keeping ${path} (${branch:-detached}, pull request ${state:-open or unknown})"
+      step "keeping ${path} (${branch:-detached}, change ${state:-open or unknown})"
       return 1
   esac
 }
diff --git a/bin/issue.sh b/bin/issue.sh
index d210d88..7091c48 100644
--- a/bin/issue.sh
+++ b/bin/issue.sh
@@ -1,12 +1,15 @@
 # shellcheck shell=bash
-# issue.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft pull request (sourced module)
+# issue.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft change (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# issue:start [<number>…] is the one command the loop needs and no vendor provides. The first number is the
-# primary issue, linked to the branch the forge makes, which closes it on merge; any further number is a
-# secondary, closed by a `Closes #N` line in the pull request body. Every listed issue is assigned to the caller.
-# It never switches the checkout it runs from: the branch is checked out in worktrees/<N>-<slug> under the main
-# checkout, and an existing branch, worktree, or pull request is reused, so a re-run reconciles.
+# issue:start [<reference>…] is the one command the loop needs and no vendor provides. A reference names its
+# tracker, as bin/tracker.sh describes: `7` or `#7` for the forge's own issues, `AB#4521` for a declared one. The
+# first is the primary issue. One of the forge's own is linked to the branch the forge makes, which closes it on
+# merge; any other, and every further reference, a secondary, is closed by a `Closes <reference>` line in the
+# change's body. Every listed issue is assigned to the caller, as each tracker knows the caller. It never switches
+# the checkout it runs from: the branch is checked out in worktrees/<key>-<slug> under the main checkout, the key
+# being the reference as a branch name opens with it, 7 or ab4521, and an existing branch, worktree, or change is
+# reused, so a re-run reconciles.
 #
 # With no argument and a terminal on stdin it asks for a title and creates the issue; without a terminal the
 # usage error stands, so an agent never hangs on a prompt. Uncommitted work in the root checkout, the human's
@@ -14,12 +17,12 @@
 # the default branch; inside any other checkout, dirty files are that issue's own and stay. A sweep that cannot
 # apply leaves the stash in place and stops.
 #
-# Every call to the forge goes through bin/forge.sh. Each step below prints its one result on stdout and talks
-# on stderr, so issue:start reads them in order.
+# Every call to the forge goes through bin/forge.sh, and every call about an issue through bin/tracker.sh. Each
+# step below prints its one result on stdout and talks on stderr, so issue:start reads them in order.
 
-use git forge
+use git forge tracker
 
-# issue:create asks for a title at the terminal and prints the number of the issue the forge creates.
+# issue:create asks for a title at the terminal and prints the reference of the issue the forge's tracker creates.
 issue:create() {
   local title number
   read -r -p "Issue title: " title
@@ -28,44 +31,57 @@ issue:create() {
     error "an issue title is required"
     return 2
   fi
-  number=$(forge:issue-create "${title}") || return 1
+  number=$(tracker:at '#' create "${title}") || return 1
   ok "Created #${number}: ${title}"
-  printf '%s\n' "${number}"
+  printf '#%s\n' "${number}"
 }
 
-# issue:assign <me> <number>… adds <me> to each issue's assignees, warning where someone else is there already.
+# issue:assign <reference>… adds the caller, as each issue's tracker knows the caller, to each issue's assignees,
+# warning where someone else is there already.
 issue:assign() {
-  local me=$1 n assignees
-  shift
-  for n in "$@"
+  local ref prefix me assignees
+  local -A me_in=()
+  for ref in "$@"
   do
-    assignees=$(forge:issue-assignees "${n}")
+    prefix=$(tracker:parse "${ref}" | cut -f 1)
+    [[ -n "${me_in[${prefix}]:-}" ]] || me_in[${prefix}]=$(tracker:at "${prefix}" me) || return 1
+    me=${me_in[${prefix}]}
+    assignees=$(tracker:of "${ref}" assignees)
     [[ " ${assignees} " == *" ${me} "* ]] && continue
     [[ -z "${assignees}" ]] \
-      || warn "#${n} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
-    forge:issue-assign "${n}" "${me}" || warn "#${n} could not be assigned to ${me}; assign it by hand."
+      || warn "${ref} is already assigned to ${assignees}; adding you as well. Coordinate before continuing."
+    tracker:of "${ref}" assign "${me}" || warn "${ref} could not be assigned to ${me}; assign it by hand."
   done
 }
 
-# issue:branch <number> <default-branch> prints the branch linked to the issue, making and linking one if none
-# exists. An existing one is found by an open pull request's head, then by the remote ref, so a second run never
-# forks a duplicate.
+# issue:branch <reference> <default-branch> <title> prints the branch made for the issue, making one if none
+# exists: linked by the forge for one of its own issues, and named <key>-<slug of the title> from the default
+# branch for any other. An existing one is found by an open change's head, then by the remote ref, so a second run
+# never forks a duplicate.
 issue:branch() {
-  local number=$1 default_branch=$2 branch
-  branch=$(forge:branch-for-issue "${number}")
+  local ref=$1 default_branch=$2 title=$3 key branch slug
+  key=$(tracker:key "${ref}") || return 2
+  branch=$(forge:branch-for-issue "${key}")
   [[ -n "${branch}" ]] \
-    || branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
-  if [[ -z "${branch}" ]]
+    || branch=$(git ls-remote --heads origin "${key}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+  if [[ -z "${branch}" ]] && tracker:is-forge "${ref}"
   then
-    step "Linking a branch to #${number}"
-    forge:link-branch "${number}" "${default_branch}" || return 1
+    step "Linking a branch to ${ref}"
+    forge:link-branch "${key}" "${default_branch}" || return 1
     git fetch --quiet origin
-    branch=$(git ls-remote --heads origin "${number}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
+    branch=$(git ls-remote --heads origin "${key}-*" 2>/dev/null | sed -n '1s@.*refs/heads/@@p')
     if [[ -z "${branch}" ]]
     then
-      error "the branch the forge made for #${number} could not be found on origin; link one by hand and re-run"
+      error "the branch the forge made for ${ref} could not be found on origin; link one by hand and re-run"
       return 1
     fi
+  elif [[ -z "${branch}" ]]
+  then
+    slug=$(tr '[:upper:]' '[:lower:]' <<<"${title}" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c 1-60)
+    branch="${key}-${slug%-}"
+    step "Making ${branch} for ${ref} from ${default_branch}"
+    git push --quiet origin "refs/remotes/origin/${default_branch}:refs/heads/${branch}" || return 1
+    git fetch --quiet origin
   fi
   printf '%s\n' "${branch}"
 }
@@ -97,15 +113,15 @@ issue:worktree() {
   printf '%s\n' "${wt}"
 }
 
-# issue:start-commit <worktree> <default-branch> <number> <title> gives the branch its first commit when it has
-# none: a forge cannot open a pull request with nothing to compare. --only keeps the commit empty, so work
-# already staged in a reused worktree stays in the index. The subject follows the loop's shape.
+# issue:start-commit <worktree> <default-branch> <reference> <title> gives the branch its first commit when it has
+# none: a forge cannot open a change with nothing to compare. --only keeps the commit empty, so work already
+# staged in a reused worktree stays in the index. The subject follows the loop's shape, the reference first.
 issue:start-commit() {
-  local wt=$1 default_branch=$2 number=$3 title=$4
+  local wt=$1 default_branch=$2 ref=$3 title=$4
   if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
   then
     step "Adding the start commit"
-    git -C "${wt}" commit --quiet --allow-empty --only --message "#${number} start: ${title}"
+    git -C "${wt}" commit --quiet --allow-empty --only --message "${ref} start: ${title}"
   fi
 }
 
@@ -139,47 +155,48 @@ issue:sweep-apply() {
     || warn "${default_branch} could not fast-forward to origin; it is left as it was."
 }
 
-# issue:pull-request <branch> <default-branch> <title> prints the number of the open pull request for the
-# branch, opening a draft if there is none.
+# issue:pull-request <branch> <default-branch> <title> prints the number of the open change for the branch,
+# opening a draft if there is none.
 issue:pull-request() {
   local branch=$1 default_branch=$2 title=$3 pr
   pr=$(forge:pr-for-branch "${branch}")
   if [[ -z "${pr}" ]]
   then
-    step "Opening a draft pull request"
+    step "Opening a draft change"
     pr=$(forge:pr-create "${branch}" "${default_branch}" "${title}") || return 1
   fi
   printf '%s\n' "${pr}"
 }
 
-# issue:link-secondaries <pr> <number>… adds a `Closes #N` line to the pull request body for each number not
-# there.
-issue:link-secondaries() {
-  local pr=$1 n body changed=false
+# issue:link-in-body <change> <reference>… adds a `Closes <reference>` line to the change's body for each reference
+# not there: a secondary issue, or a primary the forge cannot link by itself.
+issue:link-in-body() {
+  local pr=$1 ref escaped body changed=false
   shift
   body=$(forge:pr-body "${pr}")
-  for n in "$@"
+  for ref in "$@"
   do
+    escaped=$(sed 's/[][\.*^$+?(){}|/]/\\&/g' <<<"${ref}")
     if ! grep --quiet --ignore-case --extended-regexp \
-      "(close[sd]?|fix(e[sd])?|resolve[sd]?):? #${n}([^0-9]|\$)" <<<"${body}"
+      "(close[sd]?|fix(e[sd])?|resolve[sd]?):? ${escaped}([^0-9]|\$)" <<<"${body}"
     then
-      body="${body}"$'\n'"Closes #${n}"
+      body="${body}"$'\n'"Closes ${ref}"
       changed=true
     fi
   done
   if [[ "${changed}" == true ]]
   then
-    step "Linking the secondary issues in the pull request body"
+    step "Linking the issues in the change's body"
     forge:pr-set-body "${pr}" "${body}"
   fi
 }
 
-# issue:start [<number>…] is the on-ramp the file header describes. A desk without a signing key is refused
+# issue:start [<reference>…] is the on-ramp the file header describes. A desk without a signing key is refused
 # where the require_signing setting is true, before anything is written.
 issue:start() {
-  local me n primary title default_branch main_root desk desk_branch branch wt stash="" pr created sigil noun
+  local n primary title default_branch main_root desk desk_branch branch wt stash="" pr created sigil noun
+  local -a refs=() in_body=()
   forge:require || return 1
-  me=$(forge:me) || return 1
   if [[ "$(release:setting require_signing)" == true ]]
   then
     guard:require signing-key || return 1
@@ -188,7 +205,7 @@ issue:start() {
   then
     if [[ ! -t 0 ]]
     then
-      error "usage: kit issue <issue-number> [<issue-number>…]"
+      error "usage: kit issue <reference> [<reference>…]"
       return 2
     fi
     created=$(issue:create) || return
@@ -196,28 +213,28 @@ issue:start() {
   fi
   for n in "$@"
   do
-    if [[ ! "${n}" =~ ^[0-9]+$ ]]
-    then
-      error "not an issue number: '${n}'"
-      return 2
-    fi
+    n=$(tracker:normal "${n}") || return 2
+    refs+=("${n}")
   done
+  set -- "${refs[@]}"
   primary=$1
+  tracker:is-forge "${primary}" || in_body+=("${primary}")
+  in_body+=("${@:2}")
 
   git fetch --quiet --prune origin
   default_branch=$(git:default-branch)
   main_root=$(git:main-root)
   desk=$(git rev-parse --show-toplevel)
   desk_branch=$(git -C "${desk}" rev-parse --abbrev-ref HEAD)
-  title=$(forge:issue-title "${primary}") || return 1
-  issue:assign "${me}" "$@"
-  section "Starting #${primary}: ${title}"
+  title=$(tracker:of "${primary}" title) || return 1
+  issue:assign "$@" || return
+  section "Starting ${primary}: ${title}"
 
-  branch=$(issue:branch "${primary}" "${default_branch}") || return
+  branch=$(issue:branch "${primary}" "${default_branch}" "${title}") || return
   if [[ "${desk}" == "${main_root}" ]] && ! git:clean "${desk}"
   then
     step "Sweeping the uncommitted work on ${desk_branch} into the worktree"
-    stash=$(issue:sweep-push "${desk}" "kit issue #${primary} → ${branch}") || return
+    stash=$(issue:sweep-push "${desk}" "kit issue ${primary} → ${branch}") || return
   fi
   wt=$(issue:worktree "${main_root}" "${branch}") || return
   git -C "${main_root}" check-ignore --quiet worktrees 2>/dev/null \
@@ -229,10 +246,10 @@ issue:start() {
     issue:sweep-apply "${desk}" "${wt}" "${stash}" "${default_branch}" || return
   fi
   pr=$(issue:pull-request "${branch}" "${default_branch}" "${title}") || return
-  (( $# > 1 )) && issue:link-secondaries "${pr}" "${@:2}"
+  (( ${#in_body[@]} > 0 )) && issue:link-in-body "${pr}" "${in_body[@]}"
 
   IFS=$'\t' read -r sigil noun < <(forge:noun)
-  ok "Draft ${noun} ${sigil}${pr} on ${branch}, primary #${primary}${2:+, secondaries: ${*:2}}"
+  ok "Draft ${noun} ${sigil}${pr} on ${branch}, primary ${primary}${2:+, secondaries: ${*:2}}"
   ok "Worktree ready: ${wt}"
   step "cd '${wt}'    # do all work there; this checkout stays on ${desk_branch}"
 }
diff --git a/bin/kit b/bin/kit
index 31f9657..a2ba1da 100755
--- a/bin/kit
+++ b/bin/kit
@@ -47,7 +47,7 @@ usage: kit <verb> [<argument>…]
   ci                    the delivered CI job's checks, anywhere: gate, check, and linked, every one reported
   gate                  run the repository's gate, the gate setting or the detected one; refuse when there is none
   linked [<number>]     refuse a pull request not linked to an open issue of this repository
-  issue [<number>…]     start or resume an issue: linked branch, worktree, start commit, draft pull request
+  issue [<reference>…]  start or resume an issue, #7 or AB#4521: linked branch, worktree, start commit, draft change
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
   status [--no-fetch] [--json] [--mine | --all | --owner=<login>…]
diff --git a/bin/kit-issue.sh b/bin/kit-issue.sh
index d3bac9b..5290b67 100755
--- a/bin/kit-issue.sh
+++ b/bin/kit-issue.sh
@@ -2,9 +2,10 @@
 # kit-issue - start or resume an issue (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A linked branch, a worktree, a start commit, and a draft pull request.
+# A linked branch, a worktree, a start commit, and a draft change, for an issue in any declared tracker: `7` or
+# `#7` for the forge's own, `AB#4521` for an Azure DevOps work item.
 #
-# see: bin/issue.sh, bin/forge.sh
+# see: bin/issue.sh, bin/forge.sh, bin/tracker.sh
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
@@ -13,7 +14,7 @@ use issue
 
 if [[ "${1:-}" == --help ]]
 then
-  echo "usage: kit issue [<number>…]    (no number, at a terminal: ask for a title and create the issue)" >&2
+  echo "usage: kit issue [<reference>…]    (none, at a terminal: ask for a title and create the issue)" >&2
   exit 0
 fi
 
diff --git a/bin/kit-linked.sh b/bin/kit-linked.sh
index e95446b..4e37b8b 100755
--- a/bin/kit-linked.sh
+++ b/bin/kit-linked.sh
@@ -12,7 +12,7 @@
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use forge
+use forge tracker
 
 if [[ "${1:-}" == --help ]]
 then
@@ -33,11 +33,13 @@ repo=$(forge:repo) || exit 1
 url=$(forge:pr-url "${number}") || exit 1
 remedy=$(printf '%s\n' \
   "Link an open issue of this repository to [the ${noun}](${url}):" "" \
-  "1. add a line \`Closes #<N>\` to its description for each open issue it resolves" \
+  "1. add a line \`Closes <reference>\` to its description for each open issue it resolves, #7 or AB#4521" \
   "2. re-run the check: linking fires no event, so it does not re-run on its own" "" \
   "\`kit issue <N>\` makes this link when it starts the work.")
 refs=$(forge:pr-closing-issues "${number}") || exit 1
-if [[ -z "${refs}" ]]
+# A tracker the forge does not link by itself is linked by a closing keyword in the change's body.
+others=$(tracker:body-refs "$(forge:pr-body "${number}")")
+if [[ -z "${refs}${others}" ]]
 then
   error "${change} is not linked to any issue"
   summary "### ❌ The ${change} is not linked to any issue" "" "${remedy}"
@@ -46,6 +48,7 @@ fi
 open=0
 while read -r n state issue_repo
 do
+  [[ -n "${n}" ]] || continue
   if [[ "${issue_repo}" != "${repo}" ]]
   then
     warn "skipping ${issue_repo}#${n}: it belongs to another repository"
@@ -56,13 +59,27 @@ do
     open=$(( open + 1 ))
   fi
 done <<<"${refs}"
+while read -r ref
+do
+  [[ -n "${ref}" ]] || continue
+  state=$(tracker:of "${ref}" state) || continue
+  if [[ "${state}" != OPEN ]]
+  then
+    warn "${ref} is ${state}; merging will not change it"
+  else
+    open=$(( open + 1 ))
+  fi
+done <<<"${others}"
 if (( open == 0 ))
 then
   error "every issue ${change} is linked to is closed or belongs to another repository"
   summary "### ❌ Every linked issue is closed or belongs to another repository" "" "${remedy}"
   exit 1
 fi
-closes=$(cut -d ' ' -f 1 <<<"${refs}" | sed 's/^/#/' | paste -s -d ' ' -)
+closes=$({
+  [[ -z "${refs}" ]] || cut -d ' ' -f 1 <<<"${refs}" | sed 's/^/#/'
+  [[ -z "${others}" ]] || printf '%s\n' "${others}"
+} | paste -s -d ' ' -)
 ok "${change} is linked to ${closes}"
 summary "✅ Linked to ${closes}."
 
diff --git a/bin/release.sh b/bin/release.sh
index 0ef6887..84fb8e5 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -4,17 +4,16 @@
 # release.sh - the release's modules, the one merge rule, the templates, and the manifests (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/,
-# mirrored at the base's root; templates/<base>/, with @key@ rendered from the repository's settings, then
-# mirrored the same way; and regions/<base>/, rendered the same way, each file placed as a region the kit owns
-# inside a file the repository owns, between a bare kit:generate line and a kit:end line that name the path,
-# so the rest of that file stays the repository's and kit generate makes the region what kit region prints. A
-# repository
-# defines modules of its own the same way under .kit/modules/<name>/, and a name is looked up in the release
-# first, then there. Two bases: repo, the repository root, recorded in .kit/manifest; and home, the user's home
-# directory, recorded in ~/.kit/manifest, which every repository on the desk shares. A destination ending in
-# .json is merged by key, the kit owning only the entries it writes, and a region is regenerated, never merged. The repository's choices live in .kit/settings.yml, which the kit reads and never
-# writes. docs/modules.md is the format's description.
+# A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/, mirrored at
+# the base's root; templates/<base>/, with @key@ rendered from the repository's settings, then mirrored the same way;
+# and regions/<base>/, rendered the same way, each file placed as a region the kit owns inside a file the repository
+# owns, between a bare kit:generate line and a kit:end line that name the path, so the rest of that file stays the
+# repository's and kit generate makes the region what kit region prints. A repository defines modules of its own the
+# same way under .kit/modules/<name>/, and a name is looked up in the release first, then there. Two bases: repo, the
+# repository root, recorded in .kit/manifest; and home, the user's home directory, recorded in ~/.kit/manifest, which
+# every repository on the desk shares. A destination ending in .json is merged by key, the kit owning only the entries
+# it writes, and a region is regenerated, never merged. The repository's choices live in .kit/settings.yml, which the
+# kit reads and never writes. docs/modules.md is the format's description.
 #
 # Every function reads a release from a root, kit_root by default, which bin/kit exports. bin/kit also moves to
 # the repository root, so .kit/manifest and every repo path here are relative to it. Every sort and comm here
@@ -263,7 +262,7 @@ release:validate-settings() {
   for key in $(yaml:keys "${settings}")
   do
     case "${key}" in
-      (forge | gate | require_signing | answers) ;;
+      (forge | gate | require_signing | answers | trackers) ;;
       (*)
         error "${settings} has a key the kit does not know: ${key} (see .kit/settings.schema.json)"
         return 1
@@ -281,6 +280,15 @@ release:validate-settings() {
     error "${settings}: the answer key '${key}' is not letters and underscores, as a template's @key@ must be"
     return 1
   done < <(yaml:map "${settings}" answers)
+  while IFS=$'\x1f' read -r key value
+  do
+    [[ -n "${key}${value}" ]] || continue
+    if [[ -z "${key}" || ! "${key}" =~ ^[A-Za-z]*#?$ || -z "${value}" ]]
+    then
+      error "${settings}: a tracker needs a prefix, letters and an optional #, and a provider (prefix '${key}')"
+      return 1
+    fi
+  done < <(yaml:records "${settings}" trackers prefix provider)
 }
 
 # release:context <root> <module> prints "<key>\t<value>" for every key a template or region of the module may
diff --git a/bin/status.sh b/bin/status.sh
index b0f3f96..96e21cc 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -391,7 +391,8 @@ status:render() {
     (( ${#state_text} > state_w )) && state_w=${#state_text}
     text=$(status:age "${age_secs}")
     (( ${#text} > age_w )) && age_w=${#text}
-  done < <(jq --raw-output '["\(.ref // "#\(.number)") \(.title)", .author, .state, .age] | map(tostring) | join("\u001f")' \
+  done < <(jq --raw-output '["\(.ref // "#\(.number)") \(.title)", .author, .state, .age] | map(tostring)
+      | join("\u001f")' \
     <<<"${prs}")
   width=$(( $(status:width) - 3 - 3 - 3 - state_w - 3 - age_w - 3 - 24 - (owner_w > 0 ? owner_w + 6 : 0) ))
   (( width < 20 )) && width=20
diff --git a/bin/tracker-ado.sh b/bin/tracker-ado.sh
new file mode 100644
index 0000000..1fc5622
--- /dev/null
+++ b/bin/tracker-ado.sh
@@ -0,0 +1,89 @@
+# shellcheck shell=bash
+# tracker-ado.sh - Azure DevOps work items, through az boards, as a tracker (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/tracker.sh loads for a prefix whose record names `provider: ado`. The record carries the
+# organization's URL and the project a new work item is created in, and optionally its type, Task by default:
+#
+#   trackers:
+#     - prefix: "AB#"
+#       provider: ado
+#       organization: https://dev.azure.com/example
+#       project: Claims
+#       type: Task
+#
+# The az CLI with its azure-devops extension is this file's requirement and nobody else's. A work item is CLOSED
+# in the states Closed, Done, and Removed, the closing states of Azure DevOps' process templates, and OPEN in
+# every other; the caller is the identity az is signed in as, which need not be the forge's login.
+
+# shellcheck disable=SC2154  # TRACKER_PREFIX is set by tracker:of and tracker:at for the call
+tracker-ado:organization() {
+  local org
+  org=$(tracker:field "${TRACKER_PREFIX}" organization)
+  if [[ -z "${org}" ]]
+  then
+    error "add organization: <https://dev.azure.com/name> to the ${TRACKER_PREFIX} tracker in .kit/settings.yml"
+    return 1
+  fi
+  printf '%s\n' "${org%/}"
+}
+
+# tracker-ado:show <id> prints the work item as az shows it.
+tracker-ado:show() {
+  local org
+  org=$(tracker-ado:organization) || return 1
+  guard:require tool:az || return 1
+  az boards work-item show --id "$1" --org "${org}" --output json 2>/dev/null \
+    || { error "run: az login (work item ${TRACKER_PREFIX}$1 could not be read from ${org})"; return 1; }
+}
+
+# tracker-ado:read <id> <filter> applies a jq filter to the work item, failing where az could not show it.
+tracker-ado:read() {
+  local item
+  item=$(tracker-ado:show "$1") || return 1
+  jq --raw-output "$2" <<<"${item}"
+}
+
+tracker-ado:title() { tracker-ado:read "$1" '.fields["System.Title"]'; }
+
+tracker-ado:state() {
+  tracker-ado:read "$1" 'if (.fields["System.State"] | IN("Closed", "Done", "Removed")) then "CLOSED" else "OPEN" end'
+}
+
+tracker-ado:assignees() { tracker-ado:read "$1" '.fields["System.AssignedTo"].uniqueName // ""'; }
+
+tracker-ado:assign() {
+  local org
+  org=$(tracker-ado:organization) || return 1
+  az boards work-item update --id "$1" --assigned-to "$2" --org "${org}" --output none 2>/dev/null
+}
+
+tracker-ado:me() {
+  guard:require tool:az || return 1
+  az account show --query user.name --output tsv 2>/dev/null \
+    || { error "run: az login (the Azure CLI is not signed in)"; return 1; }
+}
+
+tracker-ado:create() {
+  local org project type item
+  org=$(tracker-ado:organization) || return 1
+  project=$(tracker:field "${TRACKER_PREFIX}" project)
+  type=$(tracker:field "${TRACKER_PREFIX}" type)
+  if [[ -z "${project}" ]]
+  then
+    error "add project: <name> to the ${TRACKER_PREFIX} tracker in .kit/settings.yml"
+    return 1
+  fi
+  item=$(az boards work-item create --title "$1" --type "${type:-Task}" --project "${project}" --org "${org}" \
+    --output json 2>/dev/null) || { error "run: az login (the work item could not be created)"; return 1; }
+  jq --raw-output '.id' <<<"${item}"
+}
+
+tracker-ado:url() {
+  local org project
+  org=$(tracker-ado:organization) || return 1
+  project=$(tracker:field "${TRACKER_PREFIX}" project)
+  printf '%s/%s/_workitems/edit/%s\n' "${org}" "${project// /%20}" "$1"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/tracker-forge.sh b/bin/tracker-forge.sh
new file mode 100644
index 0000000..1d290f2
--- /dev/null
+++ b/bin/tracker-forge.sh
@@ -0,0 +1,26 @@
+# shellcheck shell=bash
+# tracker-forge.sh - the forge's own issues, GitHub's or GitLab's, as a tracker (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/tracker.sh loads for `#`, unless a declared tracker claims it: every call is the forge seam's
+# issue call of the same meaning, so the forge's provider answers and this file adds nothing of its own.
+
+use forge
+
+tracker-forge:title()     { forge:issue-title "$1"; }
+tracker-forge:state()     { forge:issue-state "$1"; }
+tracker-forge:assignees() { forge:issue-assignees "$1"; }
+tracker-forge:assign()    { forge:issue-assign "$1" "$2"; }
+tracker-forge:me()        { forge:me; }
+tracker-forge:create()    { forge:issue-create "$1"; }
+
+tracker-forge:url() {
+  local repo_url
+  repo_url=$(forge:repo-url) || return 1
+  if [[ "$(forge:provider)" == gitlab ]]
+  then printf '%s/-/issues/%s\n' "${repo_url}" "$1"
+  else printf '%s/issues/%s\n' "${repo_url}" "$1"
+  fi
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/tracker.sh b/bin/tracker.sh
new file mode 100644
index 0000000..5a9ea05
--- /dev/null
+++ b/bin/tracker.sh
@@ -0,0 +1,175 @@
+# shellcheck shell=bash
+# tracker.sh - the loop's seam over the trackers that hold its issues (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# An issue lives in a tracker, and the tracker is not the forge: GitHub issues and GitLab issues happen to live in
+# theirs, Azure DevOps work items and Jira do not, and a repository may use more than one at once. A reference
+# names its tracker in its syntax, as the trackers themselves write it: `#7` or `7` for the forge's own, `AB#4521`
+# for an Azure DevOps work item. `.kit/settings.yml` declares the others, a prefix and a provider each:
+#
+#   trackers:
+#     - prefix: "AB#"
+#       provider: ado
+#       organization: https://dev.azure.com/example
+#       project: Claims
+#
+# `#` is the forge's own tracker unless a record claims it. A provider is tracker-<name>.sh beside this file, its
+# functions named tracker-<name>:<call>, each taking the reference's number first and the prefix's record through
+# tracker:field. A provider answers these calls, printing its result on stdout and failing with a remedy:
+#
+#   title <id>              the issue's title
+#   state <id>              OPEN or CLOSED
+#   assignees <id>          the assignees' logins, space-separated
+#   assign <id> <login>     adds the assignee
+#   me                      the caller's login in this tracker, which need not be the forge's
+#   create <title>          the number of the issue it creates
+#   url <id>                the issue's browser URL
+#
+# see: docs/trackers.md
+
+use release yaml
+
+# tracker:records prints "<prefix>\x1f<provider>" for every declared tracker, then the forge's own as "#" unless a
+# record claims it.
+tracker:records() {
+  local prefix provider forge_claimed=false
+  while IFS=$'\x1f' read -r prefix provider
+  do
+    [[ -n "${prefix}" ]] || continue
+    [[ "${prefix}" == '#' ]] && forge_claimed=true
+    printf '%s\x1f%s\n' "${prefix}" "${provider}"
+  done < <(yaml:records "$(release:settings)" trackers prefix provider)
+  [[ "${forge_claimed}" == true ]] || printf '#\x1fforge\n'
+}
+
+# tracker:field <prefix> <field> prints a field of the prefix's record, or nothing. Every loop over records here
+# reads to the end, so the reader is never left writing into a pipe nobody reads.
+tracker:field() {
+  local prefix value found=''
+  while IFS=$'\x1f' read -r prefix value
+  do
+    [[ -z "${found}" && "${prefix}" == "$1" ]] && found=${value}
+  done < <(yaml:records "$(release:settings)" trackers prefix "$2")
+  [[ -z "${found}" ]] || printf '%s\n' "${found}"
+}
+
+# tracker:parse <reference> prints "<prefix>\t<number>": the longest declared prefix the reference opens with, and
+# the digits after it; a bare number is the forge's own. A reference no declared tracker answers is refused, naming
+# the prefixes there are.
+tracker:parse() {
+  local ref=$1 prefix best='' provider
+  [[ "${ref}" =~ ^[0-9]+$ ]] && ref="#${ref}"
+  while IFS=$'\x1f' read -r prefix provider
+  do
+    if [[ "${ref}" == "${prefix}"* && "${ref#"${prefix}"}" =~ ^[0-9]+$ && ${#prefix} -gt ${#best} ]]
+    then
+      best=${prefix}
+    fi
+  done < <(tracker:records)
+  if [[ -z "${best}" ]]
+  then
+    error "'$1' is not an issue reference here; the trackers answer $(tracker:records | cut -d $'\x1f' -f 1 \
+      | sed 's/$/<number>/' | paste -s -d ' ' -) (trackers in .kit/settings.yml)"
+    return 2
+  fi
+  printf '%s\t%s\n' "${best}" "${ref#"${best}"}"
+}
+
+# tracker:provider <prefix> prints the provider that answers the prefix.
+tracker:provider() {
+  local prefix provider found=''
+  while IFS=$'\x1f' read -r prefix provider
+  do
+    [[ -z "${found}" && "${prefix}" == "$1" ]] && found=${provider}
+  done < <(tracker:records)
+  if [[ -z "${found}" ]]
+  then
+    error "no tracker answers '$1'"
+    return 1
+  fi
+  printf '%s\n' "${found}"
+}
+
+# tracker:of <reference> <call> <argument>… runs the call of the tracker the reference names, with its number.
+tracker:of() {
+  local ref=$1 call=$2 prefix number provider
+  shift 2
+  IFS=$'\t' read -r prefix number < <(tracker:parse "${ref}") || return 2
+  [[ -n "${prefix}" ]] || return 2
+  provider=$(tracker:provider "${prefix}") || return 1
+  use "tracker-${provider}" || return 1
+  TRACKER_PREFIX=${prefix} "tracker-${provider}:${call}" "${number}" "$@"
+}
+
+# tracker:at <prefix> <call> <argument>… runs a call that names no issue, such as me or create, on the prefix's
+# tracker.
+tracker:at() {
+  local prefix=$1 call=$2 provider
+  shift 2
+  provider=$(tracker:provider "${prefix}") || return 1
+  use "tracker-${provider}" || return 1
+  TRACKER_PREFIX=${prefix} "tracker-${provider}:${call}" "$@"
+}
+
+# tracker:normal <reference> prints the reference as its tracker writes it: `7` becomes `#7`.
+tracker:normal() {
+  local prefix number
+  IFS=$'\t' read -r prefix number < <(tracker:parse "$1") || return 2
+  [[ -n "${prefix}" ]] || return 2
+  printf '%s%s\n' "${prefix}" "${number}"
+}
+
+# tracker:is-forge <reference> is true when the forge's own tracker answers the reference, so the forge can link a
+# branch to it and close it on merge by itself.
+tracker:is-forge() {
+  local prefix number
+  IFS=$'\t' read -r prefix number < <(tracker:parse "$1" 2>/dev/null) || return 1
+  [[ -n "${prefix}" && "$(tracker:provider "${prefix}")" == forge ]]
+}
+
+# tracker:key <reference> prints the reference as a branch name opens with it: the forge's own issue 7 as `7`, a
+# work item AB#4521 as `ab4521`, letters lowered and anything not a letter or a digit dropped.
+tracker:key() {
+  local ref
+  ref=$(tracker:normal "$1") || return 2
+  if tracker:is-forge "${ref}"
+  then
+    printf '%s\n' "${ref#\#}"
+  else
+    tr '[:upper:]' '[:lower:]' <<<"${ref}" | tr -cd 'a-z0-9'
+    printf '\n'
+  fi
+}
+
+# tracker:branch-ref <branch> prints the reference a branch was made for, read back from its key, or nothing.
+tracker:branch-ref() {
+  local branch=$1 prefix provider key found=''
+  while IFS=$'\x1f' read -r prefix provider
+  do
+    [[ -z "${found}" ]] || continue
+    if [[ "${provider}" == forge ]]
+    then
+      [[ "${branch}" =~ ^([0-9]+)- ]] && found="${prefix}${BASH_REMATCH[1]}"
+    else
+      key=$(tr '[:upper:]' '[:lower:]' <<<"${prefix}" | tr -cd 'a-z0-9')
+      [[ "${branch}" =~ ^${key}([0-9]+)- ]] && found="${prefix}${BASH_REMATCH[1]}"
+    fi
+  done < <(tracker:records)
+  [[ -z "${found}" ]] || printf '%s\n' "${found}"
+}
+
+# tracker:body-refs <body> prints every reference a closing keyword names in a change's body, for the trackers the
+# forge does not link by itself: `Closes AB#4521`, `fixes AB#4521`, `Resolves: AB#4521`.
+tracker:body-refs() {
+  local body=$1 prefix provider escaped
+  while IFS=$'\x1f' read -r prefix provider
+  do
+    [[ "${provider}" == forge ]] && continue
+    escaped=$(sed 's/[][\.*^$+?(){}|/]/\\&/g' <<<"${prefix}")
+    grep --only-matching --ignore-case --extended-regexp \
+      "(close[sd]?|fix(e[sd])?|resolve[sd]?):? ${escaped}[0-9]+" <<<"${body}" \
+      | grep --only-matching --extended-regexp "[0-9]+\$" | sed "s/^/${prefix//\//\\/}/" || true
+  done < <(tracker:records)
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/docs/modules.md b/docs/modules.md
index 05ec7ed..b420620 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -118,6 +118,7 @@ answers:
 | `gate` | What `kit gate` runs; a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script is detected when absent. |
 | `require_signing` | `true` makes `kit issue` refuse a desk without a signing key. |
 | `answers` | The values a module's templates take, overriding the module's own defaults. |
+| `trackers` | The trackers besides the forge's own whose issues the loop takes, a prefix and a provider each; see [trackers.md](trackers.md). |
 
 ## Modules a repository defines
 
diff --git a/docs/trackers.md b/docs/trackers.md
new file mode 100644
index 0000000..01a0bdb
--- /dev/null
+++ b/docs/trackers.md
@@ -0,0 +1,53 @@
+# Trackers
+
+An issue lives in a tracker, and the tracker is not always the forge. GitHub issues and GitLab issues live in their
+forges; Azure DevOps work items do not, and a repository may use more than one tracker at once, as one that files bugs
+in GitHub issues and plans its work in Azure DevOps does. The loop's verbs ask about an issue through one seam,
+`tracker:` in `bin/tracker.sh`, and the reference says which tracker answers.
+
+## References
+
+A reference names its tracker in its syntax, the way the trackers already write it:
+
+| Reference | Tracker |
+| --- | --- |
+| `7` or `#7` | the forge's own issues, GitHub's or GitLab's |
+| `AB#4521` | an Azure DevOps work item, under a prefix the repository declares |
+
+`.kit/settings.yml` declares every tracker but the forge's own, one record each: the prefix a reference opens with,
+the provider that answers it, and the provider's own fields.
+
+```yaml
+trackers:
+  - prefix: "AB#"
+    provider: ado
+    organization: https://dev.azure.com/example
+    project: Claims
+    type: Task
+```
+
+`#` is the forge's own tracker unless a record claims it. A reference no declared tracker answers is refused, naming
+the prefixes there are.
+
+## The verbs
+
+- `kit issue 7`, `kit issue AB#4521`, or both, primary first. Each issue is assigned to the caller as its tracker
+  knows the caller, which for Azure DevOps is the identity `az` is signed in as. The branch opens with the
+  reference's key, `7-<slug>` or `ab4521-<slug>`. The forge links a branch to one of its own issues and closes it on
+  merge; for any other, and for every secondary, `kit issue` adds a `Closes <reference>` line to the change's body,
+  which is what GitHub's Azure Boards integration reads as a link.
+- `kit linked` accepts a change that the forge says closes an open issue of the repository, or whose body names an
+  open issue of a declared tracker with a closing keyword: `Closes AB#4521`, `Fixes AB#4521`, `Resolves AB#4521`.
+- `kit tidy` reads a worktree's issue back from its branch's key and removes the worktree when the issue is closed
+  and the change is gone.
+
+## Providers
+
+| Provider | Tool | Fields | Closed in |
+| --- | --- | --- | --- |
+| `forge` | the forge's own, through `bin/forge.sh` | none | the forge's closed state |
+| `ado` | `az` with the `azure-devops` extension | `organization`, `project`, `type` | Closed, Done, Removed |
+
+A provider is `bin/tracker-<name>.sh`, answering `title`, `state`, `assignees`, `assign`, `me`, `create`, and `url`.
+`tests/tracker.bats` drives the Azure DevOps provider through a fake of `az`; what only a real organization can
+prove, that `az` answers as the fixtures do, is not proven there.
diff --git a/modules/kit/files/repo/.kit/settings.schema.json b/modules/kit/files/repo/.kit/settings.schema.json
index ecef373..7691f78 100644
--- a/modules/kit/files/repo/.kit/settings.schema.json
+++ b/modules/kit/files/repo/.kit/settings.schema.json
@@ -8,7 +8,10 @@
   "properties": {
     "forge": {
       "type": "string",
-      "enum": ["github", "gitlab"],
+      "enum": [
+        "github",
+        "gitlab"
+      ],
       "description": "The provider the loop's verbs use: github or gitlab. Detected from origin's host, github.com or gitlab.com, when absent; a self-hosted forge is named here."
     },
     "gate": {
@@ -29,6 +32,45 @@
           "description": "The value a module's template takes for this key, written @key@ in the template."
         }
       }
+    },
+    "trackers": {
+      "type": "array",
+      "description": "The trackers whose issues the loop takes besides the forge's own, which answers # unless a record claims it. A reference names its tracker by its prefix: #7, AB#4521.",
+      "items": {
+        "type": "object",
+        "required": [
+          "prefix",
+          "provider"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "prefix": {
+            "type": "string",
+            "pattern": "^[A-Za-z]*#?$",
+            "description": "What a reference to this tracker opens with, before the number: AB# for Azure DevOps work items."
+          },
+          "provider": {
+            "type": "string",
+            "enum": [
+              "forge",
+              "ado"
+            ],
+            "description": "Which tracker answers: forge for the forge's own issues, ado for Azure DevOps work items."
+          },
+          "organization": {
+            "type": "string",
+            "description": "ado: the organization's URL, https://dev.azure.com/<name>."
+          },
+          "project": {
+            "type": "string",
+            "description": "ado: the project a new work item is created in."
+          },
+          "type": {
+            "type": "string",
+            "description": "ado: the type of a new work item, Task when absent."
+          }
+        }
+      }
     }
   }
 }
diff --git a/tests/tracker.bats b/tests/tracker.bats
new file mode 100644
index 0000000..80d5bdf
--- /dev/null
+++ b/tests/tracker.bats
@@ -0,0 +1,147 @@
+#!/usr/bin/env bats
+# tracker.bats - a reference names its tracker, the forge's own or a declared one, and each answers the same calls
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  export FAKE_DIR="${BATS_TEST_TMPDIR}/fake"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}" "${FAKE_DIR}/bin"
+  for tool in gh az
+  do
+    ln -s "${BATS_TEST_DIRNAME}/fakes/fake-tool" "${FAKE_DIR}/bin/${tool}"
+    : > "${FAKE_DIR}/${tool}.routes"
+  done
+  export PATH="${FAKE_DIR}/bin:${PATH}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+  git remote add origin https://github.com/empowerite/example.git
+  mkdir .kit
+  cat > .kit/settings.yml <<'YAML'
+trackers:
+  - prefix: "AB#"
+    provider: ado
+    organization: https://dev.azure.com/example
+    project: Claims Team
+YAML
+  unset GITHUB_EVENT_PATH
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+# in_tracker <command>… runs a command with the tracker seam loaded, as a verb would.
+in_tracker() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use tracker && "$@"' _ "$@"
+}
+
+fixture() { cat > "${FAKE_DIR}/$1"; }
+route() { printf '%s\t%s\n' "$2" "$3" >> "${FAKE_DIR}/$1.routes"; }
+
+@test "a reference names its tracker by its prefix, a bare number is the forge's own, and an unknown one is refused" {
+  run in_tracker tracker:parse 7
+  [ "$output" = "$(printf '#\t7')" ]
+  run in_tracker tracker:parse '#7'
+  [ "$output" = "$(printf '#\t7')" ]
+  run in_tracker tracker:parse 'AB#4521'
+  [ "$output" = "$(printf 'AB#\t4521')" ]
+  run in_tracker tracker:parse 'JIRA-12'
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"'JIRA-12' is not an issue reference here; the trackers answer AB#<number> #<number>"* ]]
+  run in_tracker tracker:parse 'AB#x'
+  [ "$status" -eq 2 ]
+}
+
+@test "a reference's key opens its branch name, and a branch name is read back to its reference" {
+  run in_tracker tracker:key 7
+  [ "$output" = "7" ]
+  run in_tracker tracker:key 'AB#4521'
+  [ "$output" = "ab4521" ]
+  run in_tracker tracker:branch-ref 7-fix-the-thing
+  [ "$output" = "#7" ]
+  run in_tracker tracker:branch-ref ab4521-fix-the-thing
+  [ "$output" = "AB#4521" ]
+  run in_tracker tracker:branch-ref topic
+  [ -z "$output" ]
+  in_tracker tracker:is-forge '#7'
+  ! in_tracker tracker:is-forge 'AB#4521'
+}
+
+@test "the body's closing keywords name references to the trackers the forge does not link by itself" {
+  body=$'Some text.\nCloses AB#4521\nfixes ab#9 and Resolves: AB#10\nCloses #7'
+  run in_tracker tracker:body-refs "${body}"
+  [ "$(paste -s -d ' ' - <<<"$output")" = "AB#4521 AB#9 AB#10" ]
+}
+
+@test "an Azure DevOps work item answers the tracker's calls through az, its closing states read as CLOSED" {
+  fixture active.json <<'JSON'
+{"id": 4521, "fields": {"System.Title": "Fix the claim form", "System.State": "Active",
+ "System.AssignedTo": {"uniqueName": "bob@example.com"}}}
+JSON
+  fixture done.json <<<'{"id": 4522, "fields": {"System.Title": "Old", "System.State": "Done"}}'
+  fixture created.json <<<'{"id": 4600}'
+  fixture me.txt <<<'ada@example.com'
+  route az 'boards work-item show --id 4521 --org https://dev.azure.com/example*' active.json
+  route az 'boards work-item show --id 4522 *' done.json
+  route az 'boards work-item update --id 4521 --assigned-to ada@example.com *' '!0'
+  route az 'boards work-item create --title New work --type Task --project Claims Team *' created.json
+  route az 'account show*' me.txt
+  run in_tracker tracker:of 'AB#4521' title
+  [ "$output" = "Fix the claim form" ]
+  run in_tracker tracker:of 'AB#4521' state
+  [ "$output" = "OPEN" ]
+  run in_tracker tracker:of 'AB#4522' state
+  [ "$output" = "CLOSED" ]
+  run in_tracker tracker:of 'AB#4521' assignees
+  [ "$output" = "bob@example.com" ]
+  run in_tracker tracker:of 'AB#4521' assign ada@example.com
+  [ "$status" -eq 0 ]
+  run in_tracker tracker:at 'AB#' me
+  [ "$output" = "ada@example.com" ]
+  run in_tracker tracker:at 'AB#' create "New work"
+  [ "$output" = "4600" ]
+  run in_tracker tracker:of 'AB#4521' url
+  [ "$output" = "https://dev.azure.com/example/Claims%20Team/_workitems/edit/4521" ]
+}
+
+@test "a tracker record without its organization is refused with the setting to add" {
+  printf 'trackers:\n  - prefix: "AB#"\n    provider: ado\n' > .kit/settings.yml
+  run in_tracker tracker:of 'AB#4521' title
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"add organization: <https://dev.azure.com/name> to the AB# tracker in .kit/settings.yml"* ]]
+}
+
+@test "kit linked takes a work item a closing keyword names in the body, as it takes the forge's own issues" {
+  export GITHUB_STEP_SUMMARY="${BATS_TEST_TMPDIR}/summary.md"
+  fixture repo.json <<<'{"nameWithOwner": "empowerite/example", "url": "https://github.com/empowerite/example"}'
+  fixture no-closing.json <<<'{"data": {"repository": {"pullRequest": {"closingIssuesReferences": {"nodes": []}}}}}'
+  fixture body.json <<<'{"body": "Does the work.\nCloses AB#4521"}'
+  fixture active.json <<<'{"id": 4521, "fields": {"System.Title": "Fix it", "System.State": "Active"}}'
+  route gh 'repo view*' repo.json
+  route gh 'api graphql*number=3*' no-closing.json
+  route gh 'pr view 3 --json body*' body.json
+  route az 'boards work-item show --id 4521 *' active.json
+  run "${kit_root}/bin/kit" linked 3
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"pull request #3 is linked to AB#4521"* ]]
+  fixture body.json <<<'{"body": "Does the work."}'
+  run "${kit_root}/bin/kit" linked 3
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"pull request #3 is not linked to any issue"* ]]
+  grep --quiet 'Closes <reference>' "${GITHUB_STEP_SUMMARY}"
+}
+
+@test "the settings take a tracker with a prefix and a provider, and refuse one without" {
+  "${kit_root}/bin/kit" install >/dev/null 2>&1
+  run "${kit_root}/bin/kit" check
+  [ "$status" -eq 0 ]
+  printf 'trackers:\n  - prefix: "A B#"\n    provider: ado\n' > .kit/settings.yml
+  run "${kit_root}/bin/kit" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"a tracker needs a prefix, letters and an optional #, and a provider (prefix 'A B#')"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------

From e60c3652771256d13503a78a1084124c7f46003b Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 18:46:59 -0700
Subject: [PATCH 105/108] #14 #15 Toolchains for mise, brew, and docker, and a
 naming policy checked by patterns or Open Policy Agent

The toolchain seam, bin/toolchain.sh, asks every tool manager the same questions: install,
outdated, update, path, and run. mise reads mise.toml and its lock; brew reads a Brewfile and
moves only its formulae; docker builds an image from toolchain.Dockerfile, tagged by the file's
digest, runs a command in it with the checkout at /work as the caller's user, and pins its FROM
bases by digest. A repository declares its toolchains in .kit/settings.yml or the kit detects
them from those files. kit toolchain is the verb, kit gate runs the gate through the toolchain,
inside the image where docker is declared, and the delivered workflow installs with kit
toolchain install and appends kit toolchain path to the runner's PATH, its mise action kept only
to put the mise binary there. All three ran against the real tools on a desk.

The policy seam, bin/policy.sh, gathers one facts document, the branch, the commits past the
fork, the change and its title, and the patterns with the kit's defaults filled in, and an
engine names the refusals. patterns, the default, matches in bash; opa evaluates the Rego under
.kit/policy, and the policy-opa module delivers the same rules in Rego, so tests/policy.bats
holds both engines to identical refusals. kit policy is the verb, and kit ci runs it as its
fourth check; the workflow fetches full history for it. The defaults are the loop's names: a
branch <key>-<slug>, a commit subject opening with its issue's reference, a one-line title.
This repository turns the commit-subject rule off until #1 merges, since its early commits
predate the rule.

The forge seam grows pr-title. ere:quote in the loader escapes a pattern in bash, in place of
three sed escapes BSD sed refused. The YAML reader unquotes single-quoted scalars and map values
literally. opa is pinned for the suite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/kit-ci.yml                  |  18 ++-
 .kit/1st.md                                   |   9 +-
 .kit/manifest                                 |   6 +-
 .kit/settings.schema.json                     |  57 +++++++
 .kit/settings.yml                             |   4 +
 README.md                                     |  12 +-
 bin/1st.sh                                    |  15 ++
 bin/forge-github.sh                           |   4 +
 bin/forge-gitlab.sh                           |   4 +
 bin/forge.sh                                  |   2 +
 bin/issue.sh                                  |   2 +-
 bin/kit                                       |   5 +-
 bin/kit-ci.sh                                 |  10 +-
 bin/kit-gate.sh                               |   7 +-
 bin/kit-policy.sh                             |  52 +++++++
 bin/kit-toolchain.sh                          |  94 +++++++++++
 bin/policy-opa.sh                             |  26 ++++
 bin/policy-patterns.sh                        |  37 +++++
 bin/policy.sh                                 | 131 ++++++++++++++++
 bin/release.sh                                |   2 +-
 bin/toolchain-brew.sh                         |  65 ++++++++
 bin/toolchain-docker.sh                       | 112 +++++++++++++
 bin/toolchain-mise.sh                         |  45 ++++++
 bin/toolchain.sh                              | 126 +++++++++++++++
 bin/tracker.sh                                |   2 +-
 bin/yaml.sh                                   |   8 +-
 docs/architecture.md                          |  17 +-
 docs/modules.md                               |   4 +
 docs/policy.md                                |  66 ++++++++
 docs/toolchains.md                            |  49 ++++++
 mise.lock                                     |  28 ++++
 mise.toml                                     |   2 +
 modules/ci-github/docs/README.md              |  11 +-
 .../repo/.github/workflows/kit-ci.yml         |  18 ++-
 modules/kit/files/repo/.kit/1st.md            |   9 +-
 .../kit/files/repo/.kit/settings.schema.json  |  57 +++++++
 modules/policy-opa/docs/README.md             |   7 +
 .../files/repo/.kit/policy/kit.rego           |  33 ++++
 modules/policy-opa/module.yml                 |   7 +
 tests/ci.bats                                 |   5 +-
 tests/forge-conformance.bats                  |   8 +-
 tests/policy.bats                             | 139 +++++++++++++++++
 tests/toolchain.bats                          | 147 ++++++++++++++++++
 43 files changed, 1414 insertions(+), 48 deletions(-)
 create mode 100755 bin/kit-policy.sh
 create mode 100755 bin/kit-toolchain.sh
 create mode 100644 bin/policy-opa.sh
 create mode 100644 bin/policy-patterns.sh
 create mode 100644 bin/policy.sh
 create mode 100644 bin/toolchain-brew.sh
 create mode 100644 bin/toolchain-docker.sh
 create mode 100644 bin/toolchain-mise.sh
 create mode 100644 bin/toolchain.sh
 create mode 100644 docs/policy.md
 create mode 100644 docs/toolchains.md
 create mode 100644 modules/policy-opa/docs/README.md
 create mode 100644 modules/policy-opa/files/repo/.kit/policy/kit.rego
 create mode 100644 modules/policy-opa/module.yml
 create mode 100644 tests/policy.bats
 create mode 100644 tests/toolchain.bats

diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 08d1632..8f92fc8 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -3,8 +3,10 @@
 #
 # One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
 # takes the kit release .kit/manifest names from its public URL, or this checkout's own bin/ where the manifest
-# says unreleased, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported. mise is used
-# only where the repository has a mise.toml, so the gate's own tools come from wherever the repository pins them.
+# says unreleased, installs the gate's tools with `kit toolchain install`, whichever of mise, brew, or docker
+# manages them, and runs `kit ci`: the gate, `kit check`, `kit linked`, and `kit policy`, every one reported. The
+# one setup action puts the mise binary on the runner where the repository has a mise.toml; brew and docker are
+# on GitHub's runners already.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
 # answer, from answers: in .kit/settings.yml.
@@ -32,10 +34,15 @@ jobs:
     steps:
       - name: checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # kit policy reads every commit past the fork from the default branch.
+          fetch-depth: 0
 
-      - name: tools-from-mise
+      - name: mise-on-path
         uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
-        if: ${{ hashFiles('mise.toml') != '' }}
+        if: ${{ hashFiles('mise.toml', '.mise.toml') != '' }}
+        with:
+          install: false
 
       - name: kit-on-path
         run: |
@@ -62,6 +69,9 @@ jobs:
             printf '%s/kit/bin\n' "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
           fi
 
+      - name: toolchain
+        run: kit toolchain install && kit toolchain path >> "${GITHUB_PATH}"
+
       - name: kit-ci
         env:
           GH_TOKEN: ${{ github.token }}
diff --git a/.kit/1st.md b/.kit/1st.md
index dc9df03..924ebe9 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -106,9 +106,12 @@ as it is.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
-- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
-  `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
-  anywhere.
+- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that installs the gate's tools with
+  `kit toolchain install` and runs `kit ci`: the repository's gate, `kit check`, the refusal of a change not
+  linked to an open issue, and `kit policy`, the refusal of a branch, commit subject, or title off the
+  repository's policy. `kit ci` runs the same four anywhere.
+- `policy-opa`: `.kit/policy/kit.rego`, the naming policy in Rego, so `kit policy` runs on Open Policy Agent and a
+  rule can say what a pattern cannot.
 - `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: a region in
   `.claude/CLAUDE.md` importing `AGENTS.md`, so it is read in every case; the deny list above merged into
   `.claude/settings.json`; and a hook that runs `kit context` before every write so the rules are named to the agent
diff --git a/.kit/manifest b/.kit/manifest
index 746cccb..0593dbf 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,9 +3,9 @@ version unreleased
 modules kit ci-github claude lefthook
 7b50d15feae7b63b94d845b2fa6e19e3220527c5b0cac69303b7fc19bd7484a8  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-86f04faeb1b3c0dc237ac01cd405512970953d97f1e0e6820315e5bf93a4d667  .github/workflows/kit-ci.yml
+62f7be9db324ef4195af0e3932569d8a8b05cc31aac72794666c0611f4d9e745  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
-bb816c7d215b13f5d4f1da525b3254857e12d87aa9aca05158d8176e10d871fa  .kit/1st.md
+a5c6383b07c98794c1cc90749b3dddd0380db9267bfc11a81f3869bda99736de  .kit/1st.md
 a36cca49330228339ece2a2fd7fe4958f13496329de43d56e1e0534344c99d20  .kit/lefthook.yml
 acf52f60f178be28ca2f09bb22f8a982bba0e61eff611ca1a91f1f8dae2ccbce  .kit/markdownlint.jsonc
 bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
@@ -15,5 +15,5 @@ bfa75fb42fd85d8c43034d910cff554fcbf1e273ad22806b481ebe985f1191f9  .kit/rules/jus
 87aa30f09c4d931d8c77731f0d6877d98e5ccfc32a775918f774bb5a5010b232  .kit/rules/markdown.md
 ceb28d32ae5522b1e0586551667bab18809c1f9be1ffcf0ed4eadbceffb2f99c  .kit/rules/workflows.md
 158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
-9c97c48f4578df3af8ffdd4eec9a511281b79ae87aae2cb04d53a093f1301811  .kit/settings.schema.json
+1201987f5947fb543e6d3903050f14fb7ebb4557ed39dc4ccf4ff70f2beb357e  .kit/settings.schema.json
 dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
index 7691f78..b4bd794 100644
--- a/.kit/settings.schema.json
+++ b/.kit/settings.schema.json
@@ -71,6 +71,63 @@
           }
         }
       }
+    },
+    "toolchains": {
+      "type": "array",
+      "description": "The toolchains that put the gate's tools on PATH, in order. Detected from mise.toml, Brewfile, and toolchain.Dockerfile when absent.",
+      "items": {
+        "type": "object",
+        "required": [
+          "provider"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "mise",
+              "brew",
+              "docker"
+            ],
+            "description": "Which tool manager answers."
+          },
+          "file": {
+            "type": "string",
+            "description": "brew and docker: the file it reads, Brewfile or toolchain.Dockerfile by default."
+          },
+          "image": {
+            "type": "string",
+            "description": "docker: the built image's name, kit-toolchain by default."
+          }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The patterns the loop's names must match, extended regular expressions in the subset RE2 shares. A subject absent takes the kit's default; an empty pattern turns that rule off.",
+      "properties": {
+        "branch": {
+          "type": "string",
+          "description": "The branch's name. Default: ^[a-z0-9]+-[a-z0-9][a-z0-9-]*$, as kit issue makes it."
+        },
+        "commit_subject": {
+          "type": "string",
+          "description": "Every commit's subject past the fork. Default: ^([A-Z]+)?#[0-9]+ [^ ], opening with its issue's reference."
+        },
+        "change_title": {
+          "type": "string",
+          "description": "The open change's title. Default: ^[^[:cntrl:]]{1,120}$."
+        }
+      }
+    },
+    "policy_engine": {
+      "type": "string",
+      "enum": [
+        "patterns",
+        "opa"
+      ],
+      "description": "Which engine decides: patterns, matched in bash, or opa, over the Rego under .kit/policy. opa is chosen when absent and a .rego file is there."
     }
   }
 }
diff --git a/.kit/settings.yml b/.kit/settings.yml
index 47a39fd..fc21734 100644
--- a/.kit/settings.yml
+++ b/.kit/settings.yml
@@ -1,2 +1,6 @@
 # yaml-language-server: $schema=settings.schema.json
 require_signing: true
+# The commit-subject rule is off for the history of #1, the first release, whose early commits predate it. Remove
+# this comment and the two lines below once that pull request merges, and every later branch is held to the kit's default.
+policy:
+  commit_subject: ''
diff --git a/README.md b/README.md
index 2927db0..5f567b1 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,10 @@ agents to them, as a versioned release any repository can take and keep taking.
 
 The rules are the smaller part. The point is verification that does not depend on anyone's word:
 
-- `kit ci`, which refuses a pull request without a linked open issue and refuses to pass a gate that did not
-  run, from the delivered GitHub Actions job or from any pipeline;
+- `kit ci`, which refuses a pull request without a linked open issue, a branch, commit subject, or title off the
+  repository's policy, and a gate that did not run, from the delivered GitHub Actions job or from any pipeline;
+- `kit toolchain`, which installs, reports, and updates the gate's tools whether mise, Homebrew, or a container
+  image manages them, and runs the gate with them;
 - `kit check`, which holds every delivered file to its release and every generated region to its command;
 - `kit lint`, each rule's own linter over the paths it governs, before a commit or anywhere;
 - a deny list that refuses the spellings the rules forbid;
@@ -77,8 +79,10 @@ exists; a range pin sees a new kit a day after it ships unless `[settings]` carr
   [docs/generate.md](docs/generate.md) says how.
 - Commit what `install` wrote.
 - Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
-  or any command as `gate` in `.kit/settings.yml`. The delivered check, `kit ci`, runs it with `kit check` and
-  `kit linked`, from the delivered workflow or from any pipeline of your own, and refuses when there is none.
+  or any command as `gate` in `.kit/settings.yml`. The delivered check, `kit ci`, runs it with `kit check`,
+  `kit linked`, and `kit policy`, from the delivered workflow or from any pipeline of your own, and refuses when
+  there is none. The gate runs with the tools your toolchain manages, mise, Homebrew, or a container image; see
+  [docs/toolchains.md](docs/toolchains.md). The naming policy is in [docs/policy.md](docs/policy.md).
 - Run the linters before a commit. `kit lint` runs each rule's own linter over the staged paths with no hook
   manager at all. The `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
   in `lefthook.yml`, and run `lefthook install` once per clone. `kit check` refuses until that line is there,
diff --git a/bin/1st.sh b/bin/1st.sh
index a2db375..2defc35 100644
--- a/bin/1st.sh
+++ b/bin/1st.sh
@@ -41,6 +41,21 @@ else
   declare -gr out_color=0
 fi
 
+# ere:quote <text> prints the text with every extended-regular-expression metacharacter escaped, so it stands for
+# itself in a pattern. Done in bash, so no sed dialect decides what a bracket expression means.
+ere:quote() {
+  local text=$1 out='' c i
+  for (( i = 0; i < ${#text}; i++ ))
+  do
+    c=${text:i:1}
+    case "${c}" in
+      ('.' | '[' | ']' | '*' | '^' | '$' | "\\" | '+' | '?' | '(' | ')' | '{' | '}' | '|') out+="\\${c}" ;;
+      (*) out+=${c} ;;
+    esac
+  done
+  printf '%s\n' "${out}"
+}
+
 # out:sgr <code> prints the escape for one SGR code when color is on, and nothing otherwise.
 out:sgr() {
   (( out_color )) && printf '\x1b[%sm' "$1"
diff --git a/bin/forge-github.sh b/bin/forge-github.sh
index 7f493c8..dee415a 100644
--- a/bin/forge-github.sh
+++ b/bin/forge-github.sh
@@ -86,6 +86,10 @@ forge-github:pr-create() {
   printf '%s\n' "${url##*/}"
 }
 
+forge-github:pr-title() {
+  gh pr view "$1" --json title --jq '.title'
+}
+
 forge-github:pr-body() {
   gh pr view "$1" --json body --jq '.body // ""'
 }
diff --git a/bin/forge-gitlab.sh b/bin/forge-gitlab.sh
index e685127..234dfc3 100644
--- a/bin/forge-gitlab.sh
+++ b/bin/forge-gitlab.sh
@@ -112,6 +112,10 @@ forge-gitlab:pr-create() {
   printf '%s\n' "${number}"
 }
 
+forge-gitlab:pr-title() {
+  forge-gitlab:api "merge_requests/$1" | jq --raw-output '.title'
+}
+
 forge-gitlab:pr-body() {
   forge-gitlab:api "merge_requests/$1" | jq --raw-output '.description // ""'
 }
diff --git a/bin/forge.sh b/bin/forge.sh
index 3a0c4e3..d7b701b 100644
--- a/bin/forge.sh
+++ b/bin/forge.sh
@@ -26,6 +26,7 @@
 #   link-branch <n> <default>     makes a branch linked to the issue, from <default>, pushed to origin
 #   pr-for-branch <branch>        the number of the open pull request on the branch, or nothing
 #   pr-create <branch> <default> <title>   opens a draft pull request and prints its number
+#   pr-title <n>                  the pull request's title
 #   pr-body <n>                   the pull request's body
 #   pr-set-body <n> <body>        replaces it
 #   pr-state-for-branch <branch>  MERGED, CLOSED, or OPEN for the latest pull request on the branch, or nothing
@@ -95,6 +96,7 @@ forge:branch-for-issue()    { forge:call branch-for-issue "$@"; }
 forge:link-branch()         { forge:call link-branch "$@"; }
 forge:pr-for-branch()       { forge:call pr-for-branch "$@"; }
 forge:pr-create()           { forge:call pr-create "$@"; }
+forge:pr-title()            { forge:call pr-title "$@"; }
 forge:pr-body()             { forge:call pr-body "$@"; }
 forge:pr-set-body()         { forge:call pr-set-body "$@"; }
 forge:pr-state-for-branch() { forge:call pr-state-for-branch "$@"; }
diff --git a/bin/issue.sh b/bin/issue.sh
index 7091c48..d9e0860 100644
--- a/bin/issue.sh
+++ b/bin/issue.sh
@@ -176,7 +176,7 @@ issue:link-in-body() {
   body=$(forge:pr-body "${pr}")
   for ref in "$@"
   do
-    escaped=$(sed 's/[][\.*^$+?(){}|/]/\\&/g' <<<"${ref}")
+    escaped=$(ere:quote "${ref}")
     if ! grep --quiet --ignore-case --extended-regexp \
       "(close[sd]?|fix(e[sd])?|resolve[sd]?):? ${escaped}([^0-9]|\$)" <<<"${body}"
     then
diff --git a/bin/kit b/bin/kit
index a2ba1da..85e0902 100755
--- a/bin/kit
+++ b/bin/kit
@@ -44,9 +44,12 @@ usage: kit <verb> [<argument>…]
                         expand every kit:generate region to what its command makes, or check that it is
   region [--home] [<path>]
                         print the content the active modules deliver as the region at a path
-  ci                    the delivered CI job's checks, anywhere: gate, check, and linked, every one reported
+  ci                    the delivered CI job's checks, anywhere: gate, check, linked, and policy, every one reported
+  policy [--input]      refuse a branch, commit subject, or change title the repository's policy does not allow
   gate                  run the repository's gate, the gate setting or the detected one; refuse when there is none
   linked [<number>]     refuse a pull request not linked to an open issue of this repository
+  toolchain <list|install|outdated|update|path|run> …
+                        the tools the gate runs, whatever manages them: mise, brew, or docker
   issue [<reference>…]  start or resume an issue, #7 or AB#4521: linked branch, worktree, start commit, draft change
   rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
diff --git a/bin/kit-ci.sh b/bin/kit-ci.sh
index f8fc647..be8c02f 100755
--- a/bin/kit-ci.sh
+++ b/bin/kit-ci.sh
@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# kit-ci - the three checks of the delivered CI job, run anywhere: the gate, the kit's own check, and the issue link
+# kit-ci - the delivered CI job's checks, run anywhere: the gate, the kit's own check, the issue link, and the policy
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # Every check runs even when an earlier one refused, so one run reports every finding. The exit status is the
 # number of checks that refused.
 #
-# see: bin/kit-gate.sh, bin/kit-check.sh, bin/kit-linked.sh
+# see: bin/kit-gate.sh, bin/kit-check.sh, bin/kit-linked.sh, bin/kit-policy.sh
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
@@ -18,16 +18,16 @@ then
 fi
 
 refused=0
-for verb in gate check linked
+for verb in gate check linked policy
 do
   section "kit ${verb}"
   "${kit_root}/bin/kit-${verb}.sh" || refused=$(( refused + 1 ))
 done
 if (( refused > 0 ))
 then
-  error "${refused} of 3 checks refused; see above"
+  error "${refused} of 4 checks refused; see above"
   exit "${refused}"
 fi
-ok "kit ci: the gate, the kit's check, and the issue link all passed."
+ok "kit ci: the gate, the kit's check, the issue link, and the policy all passed."
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-gate.sh b/bin/kit-gate.sh
index aecd577..b17d591 100755
--- a/bin/kit-gate.sh
+++ b/bin/kit-gate.sh
@@ -5,14 +5,15 @@
 # The gate is the `gate` setting in .kit/settings.yml, else the first of: a root justfile with a ci recipe, a
 # Makefile with a ci target, a package.json with a ci script. A gate that cannot run clears nothing: a repository
 # with none, or one whose justfile cannot be read, is refused, naming the remedy. On a runner, each outcome also
-# lands in the step summary.
+# lands in the step summary. The gate runs with the declared toolchains' tools, inside the container where the
+# toolchain is docker; see bin/toolchain.sh.
 #
 # see: modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use release
+use release toolchain
 
 if [[ "${1:-}" == --help ]]
 then
@@ -57,7 +58,7 @@ then
   exit 1
 fi
 step "the gate: ${gate}"
-if ! bash -c "${gate}"
+if ! toolchain:run bash -c "${gate}"
 then
   error "the gate failed: ${gate}"
   summary "### ❌ The gate failed: \`${gate}\`"
diff --git a/bin/kit-policy.sh b/bin/kit-policy.sh
new file mode 100755
index 0000000..4512084
--- /dev/null
+++ b/bin/kit-policy.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# kit-policy - refuse a branch, a commit subject, or a change title the repository's policy does not allow (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The facts are gathered once, the branch, the commits past the fork, and the open change, and the policy engine,
+# patterns by default or Open Policy Agent, names every refusal. --input prints the facts instead, the document a
+# rule is written against. kit ci runs this beside the gate. On a runner the refusals land in the step summary.
+#
+# see: bin/policy.sh, docs/policy.md
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use policy
+
+case "${1:-}" in
+  (--help)
+    echo "usage: kit policy [--input]" >&2
+    exit 0
+    ;;
+  (--input)
+    policy:input
+    exit 0
+    ;;
+  ('') ;;
+  (*)
+    echo "usage: kit policy [--input]" >&2
+    exit 2
+esac
+
+input=$(mktemp)
+trap 'rm -f "${input}"' EXIT
+policy:input > "${input}"
+engine=$(policy:engine)
+refusals=$(policy:deny "${input}") || exit 1
+if [[ -n "${refusals}" ]]
+then
+  while IFS= read -r refusal
+  do
+    error "${refusal}"
+  done <<<"${refusals}"
+  count=$(wc -l <<<"${refusals}" | tr -d ' ')
+  error "${count} refusal(s) by the ${engine} policy; .kit/settings.yml holds the patterns, docs/policy.md says how"
+  summary "### ❌ ${count} refusal(s) by the policy" "" "- ${refusals//$'\n'/$'\n'- }"
+  exit 1
+fi
+subjects=$(jq --raw-output '[if .branch then "the branch" else empty end,
+  "\(.commits | length) commit(s)", if .change then "the change title" else empty end] | join(", ")' "${input}")
+ok "the ${engine} policy allows ${subjects}"
+summary "✅ The policy allows ${subjects}."
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-toolchain.sh b/bin/kit-toolchain.sh
new file mode 100755
index 0000000..f1ec344
--- /dev/null
+++ b/bin/kit-toolchain.sh
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# kit-toolchain - install, report, and update the tools the repository's gate runs, whatever manages them (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# One verb over every declared toolchain, mise, brew, or docker, so a desk, a runner, and the delivered CI job say
+# the same thing whichever manages the tools:
+#
+#   list                    each declared toolchain and the file it reads
+#   install                 every toolchain's pinned tools installed
+#   outdated [--check]      one line per tool behind its source; --check fails when there is one
+#   update                  every toolchain moved to its latest, its pins and lock rewritten
+#   path                    the directories that put the tools first on PATH, one per line, for a runner's PATH
+#   run <command>…          the command with the tools: inside the container for docker, else with the path first
+#
+# see: bin/toolchain.sh, docs/toolchains.md
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use toolchain
+
+# Every subcommand reads the declared toolchains once, so a refused declaration stops it.
+providers=$(toolchain:declared) || exit 1
+
+usage() { echo "usage: kit toolchain list | install | outdated [--check] | update | path | run <command>…" >&2; }
+
+verb=${1:-}
+[[ -n "${verb}" ]] && shift
+case "${verb}" in
+  (--help | '')
+    usage
+    exit 0
+    ;;
+  (list)
+    for provider in ${providers}
+    do
+      printf '%-8s %s\n' "${provider}" "$(toolchain:call "${provider}" file)"
+    done
+    ;;
+  (install)
+    if [[ -z "${providers}" ]]
+    then
+      ok "no toolchain is declared or detected; the gate runs with the tools already on PATH"
+      exit 0
+    fi
+    for provider in ${providers}
+    do
+      step "${provider}: installing from $(toolchain:call "${provider}" file)"
+      toolchain:call "${provider}" install || { error "${provider}: the tools could not be installed; see above"; exit 1; }
+    done
+    ok "toolchains installed: ${providers//$'\n'/ }"
+    summary "✅ Toolchains installed: ${providers//$'\n'/ }."
+    ;;
+  (outdated)
+    check=false
+    [[ "${1:-}" == --check ]] && check=true
+    behind=0
+    for provider in ${providers}
+    do
+      while IFS=$'\t' read -r name installed latest
+      do
+        [[ -n "${name}" ]] || continue
+        printf '%-8s %-32s %-16s → %s\n' "${provider}" "${name}" "${installed}" "${latest}"
+        behind=$(( behind + 1 ))
+      done < <(toolchain:call "${provider}" outdated)
+    done
+    if (( behind == 0 ))
+    then
+      ok "every tool is at its latest"
+    elif [[ "${check}" == true ]]
+    then
+      error "${behind} tool(s) are behind; run: kit toolchain update"
+      exit 1
+    else
+      warn "${behind} tool(s) are behind; run: kit toolchain update"
+    fi
+    ;;
+  (update)
+    toolchain:each update
+    ok "every toolchain is updated; commit the pins and the locks it rewrote"
+    ;;
+  (path)
+    toolchain:path
+    ;;
+  (run)
+    (( $# > 0 )) || { usage; exit 2; }
+    toolchain:run "$@"
+    ;;
+  (*)
+    usage
+    exit 2
+esac
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/policy-opa.sh b/bin/policy-opa.sh
new file mode 100644
index 0000000..c264a49
--- /dev/null
+++ b/bin/policy-opa.sh
@@ -0,0 +1,26 @@
+# shellcheck shell=bash
+# policy-opa.sh - Open Policy Agent as the policy engine: the Rego under .kit/policy decides (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The engine bin/policy.sh uses for `policy_engine: opa`, or where .kit/policy holds a .rego file. Every .rego
+# file there is loaded, and the set `data.kit.policy.deny` is the refusals, each a string. The facts document is
+# the input, so a rule reads input.branch, input.commits, input.change, and input.policy, the patterns with the
+# kit's defaults filled in. opa is the requirement, pinned by the repository's toolchain like any tool its gate
+# runs. The policy-opa module delivers .kit/policy/kit.rego, the patterns engine's rules in Rego, to build on.
+
+policy-opa:deny() {
+  local input=$1 out
+  if ! command -v opa >/dev/null 2>&1
+  then
+    error "pin opa in the repository's toolchain and run: kit toolchain install (the opa policy engine needs it)"
+    return 1
+  fi
+  if ! out=$(opa eval --format json --data .kit/policy --input "${input}" 'data.kit.policy.deny' 2>&1)
+  then
+    error "opa could not evaluate .kit/policy: ${out}"
+    return 1
+  fi
+  jq --raw-output '.result[0].expressions[0].value // [] | .[]' <<<"${out}"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/policy-patterns.sh b/bin/policy-patterns.sh
new file mode 100644
index 0000000..6b60eff
--- /dev/null
+++ b/bin/policy-patterns.sh
@@ -0,0 +1,37 @@
+# shellcheck shell=bash
+# policy-patterns.sh - the default policy engine: each subject matched against its pattern in bash (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The engine bin/policy.sh uses unless the repository names another. It needs no tool: each rule of the facts'
+# policy object is matched with bash's =~ against its subject, and a rule whose pattern is empty is off. The
+# refusals are worded exactly as the policy-opa module's Rego words them, so either engine says the same thing.
+
+# policy-patterns:deny <input-file> prints one refusal per subject that does not match its pattern.
+policy-patterns:deny() {
+  local input=$1 branch pattern subject sha title
+  branch=$(jq --raw-output '.branch // ""' "${input}")
+  pattern=$(jq --raw-output '.policy.branch' "${input}")
+  if [[ -n "${branch}" && -n "${pattern}" && ! "${branch}" =~ ${pattern} ]]
+  then
+    printf "branch '%s' does not match policy.branch: %s\n" "${branch}" "${pattern}"
+  fi
+  pattern=$(jq --raw-output '.policy.commit_subject' "${input}")
+  if [[ -n "${pattern}" ]]
+  then
+    while IFS=$'\x1f' read -r sha subject
+    do
+      [[ -n "${sha}" && ! "${subject}" =~ ${pattern} ]] || continue
+      printf "commit %s '%s' does not match policy.commit_subject: %s\n" "${sha:0:7}" "${subject}" "${pattern}"
+    done < <(jq --raw-output '.commits[] | "\(.sha)\u001f\(.subject)"' "${input}")
+  fi
+  title=$(jq --raw-output '.change.title // ""' "${input}")
+  pattern=$(jq --raw-output '.policy.change_title' "${input}")
+  [[ "$(jq --raw-output '.change != null' "${input}")" == true ]] || return 0
+  if [[ -n "${pattern}" && ! "${title}" =~ ${pattern} ]]
+  then
+    printf "change title '%s' does not match policy.change_title: %s\n" "${title}" "${pattern}"
+  fi
+  return 0
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/policy.sh b/bin/policy.sh
new file mode 100644
index 0000000..4030e2f
--- /dev/null
+++ b/bin/policy.sh
@@ -0,0 +1,131 @@
+# shellcheck shell=bash
+# policy.sh - the seam over what the loop's names must be: the facts, the rules, and the engine (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# What a branch, a commit subject, or a change's title may be is a policy, and a policy is checked, not described.
+# The seam has three parts:
+#
+#   the facts     policy:input gathers one JSON document: the branch, the default branch, the commits past the
+#                 fork, the change on the branch with its title and body, and the policy settings with the kit's
+#                 defaults filled in. `kit policy --input` prints it, so a rule can be written against it.
+#   the rules     `policy:` in .kit/settings.yml, one extended regular expression per subject:
+#                   branch            the branch's name
+#                   commit_subject    every commit's subject past the fork, merges aside
+#                   change_title      the open change's title
+#                 A subject absent takes the kit's default below; an empty pattern turns that rule off.
+#   the engine    policy-<name>.sh beside this file answers `deny <input-file>`, one refusal per line:
+#                   patterns          the default: each pattern matched in bash, no tool needed
+#                   opa               Open Policy Agent over the Rego under .kit/policy/, package kit.policy, rule
+#                                     deny; chosen by `policy_engine: opa`, or by a .rego file there
+#                 Both read the same document, so a rule a pattern cannot say is written in Rego beside the
+#                 patterns, and the policy-opa module delivers the patterns themselves as Rego to start from.
+#
+# A pattern is matched as an extended regular expression by bash and as RE2 by OPA; the two agree on the common
+# subset, character classes, anchors, alternation, and counted repetition, which is the subset to write in.
+#
+# see: docs/policy.md
+
+use release yaml git
+
+# The kit's defaults, the loop's own names from .kit/1st.md: a branch is <key>-<slug>, as kit issue makes it; a
+# commit subject opens with its issue's reference, #7 or AB#4521; a change's title is a line of at most 120.
+declare -gr policy_default_branch='^[a-z0-9]+-[a-z0-9][a-z0-9-]*$'
+declare -gr policy_default_commit_subject='^([A-Z]+)?#[0-9]+ [^ ]'
+declare -gr policy_default_change_title='^[^[:cntrl:]]{1,120}$'
+
+# policy:rules prints the policy settings with the kit's defaults filled in, as a JSON object.
+policy:rules() {
+  local settings key value
+  local -A rule=(
+    [branch]=${policy_default_branch}
+    [commit_subject]=${policy_default_commit_subject}
+    [change_title]=${policy_default_change_title}
+  )
+  settings=$(release:settings)
+  while IFS=$'\t' read -r key value
+  do
+    [[ -n "${key}" ]] || continue
+    if [[ -z "${rule[${key}]+x}" ]]
+    then
+      error "${settings}: policy has a subject the kit does not know: ${key} (the subjects: branch," \
+        "commit_subject, change_title)"
+      return 1
+    fi
+    rule[${key}]=${value}
+  done < <(yaml:map "${settings}" policy)
+  jq --null-input --arg branch "${rule[branch]}" --arg commit_subject "${rule[commit_subject]}" \
+    --arg change_title "${rule[change_title]}" \
+    '{branch: $branch, commit_subject: $commit_subject, change_title: $change_title}'
+}
+
+# policy:branch prints the branch under check: the change's head on a runner, else the current branch, else
+# nothing for a detached checkout.
+policy:branch() {
+  local branch=${GITHUB_HEAD_REF:-${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:-}}
+  [[ -n "${branch}" ]] || branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+  printf '%s\n' "${branch}"
+}
+
+# policy:input prints the facts document the file header describes. The commits are those past the fork from the
+# default branch at origin; where the fork cannot be found, a shallow clone, they are omitted with a warning
+# rather than guessed. The change is read through the forge, and omitted where no forge or no change answers.
+policy:input() {
+  local default_branch branch commits='[]' change='null' rules number title body
+  rules=$(policy:rules) || return 1
+  default_branch=$(git:default-branch)
+  branch=$(policy:branch)
+  if [[ -n "${branch}" && "${branch}" != "${default_branch}" ]]
+  then
+    if git rev-parse --verify --quiet "origin/${default_branch}" >/dev/null \
+      && git merge-base "origin/${default_branch}" HEAD >/dev/null 2>&1
+    then
+      commits=$(git log --no-merges --format='%H%x1f%s' "origin/${default_branch}..HEAD" \
+        | jq --raw-input --slurp 'split("\n") | map(select(. != "") | split("\u001f") | {sha: .[0], subject: .[1]})')
+    else
+      warn "the fork from origin/${default_branch} is not here, so no commit is checked; fetch with full history"
+    fi
+    if use forge 2>/dev/null && number=$(forge:pr-here 2>/dev/null) && [[ -n "${number}" ]]
+    then
+      title=$(forge:pr-title "${number}" 2>/dev/null || true)
+      body=$(forge:pr-body "${number}" 2>/dev/null || true)
+      change=$(jq --null-input --argjson number "${number}" --arg title "${title}" --arg body "${body}" \
+        '{number: $number, title: $title, body: $body}')
+    fi
+  else
+    branch=''
+  fi
+  jq --null-input --arg branch "${branch}" --arg default_branch "${default_branch}" --argjson commits "${commits}" \
+    --argjson change "${change}" --argjson policy "${rules}" \
+    '{branch: (if $branch == "" then null else $branch end), default_branch: $default_branch, commits: $commits,
+      change: $change, policy: $policy}'
+}
+
+# policy:engine prints the engine: the policy_engine setting, else opa where .kit/policy holds a .rego file, else
+# patterns. An engine the kit does not carry is refused by name.
+policy:engine() {
+  local engine
+  engine=$(release:setting policy_engine)
+  if [[ -z "${engine}" ]]
+  then
+    engine=patterns
+    compgen -G '.kit/policy/*.rego' >/dev/null && engine=opa
+  fi
+  # shellcheck disable=SC2154  # kit_bin_dir is declared by bin/1st.sh
+  if [[ ! -f "${kit_bin_dir}/policy-${engine}.sh" ]]
+  then
+    error "'${engine}' is not a policy engine the kit knows; the engines are: patterns opa (policy_engine in" \
+      ".kit/settings.yml)"
+    return 1
+  fi
+  printf '%s\n' "${engine}"
+}
+
+# policy:deny <input-file> prints every refusal the engine finds in the facts, one per line, sorted.
+policy:deny() {
+  local engine
+  engine=$(policy:engine) || return 1
+  use "policy-${engine}" || return 1
+  "policy-${engine}:deny" "$1" | LC_ALL=C sort --unique
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/release.sh b/bin/release.sh
index 84fb8e5..5cc946a 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -262,7 +262,7 @@ release:validate-settings() {
   for key in $(yaml:keys "${settings}")
   do
     case "${key}" in
-      (forge | gate | require_signing | answers | trackers) ;;
+      (forge | gate | require_signing | answers | trackers | toolchains | policy | policy_engine) ;;
       (*)
         error "${settings} has a key the kit does not know: ${key} (see .kit/settings.schema.json)"
         return 1
diff --git a/bin/toolchain-brew.sh b/bin/toolchain-brew.sh
new file mode 100644
index 0000000..a0c7a90
--- /dev/null
+++ b/bin/toolchain-brew.sh
@@ -0,0 +1,65 @@
+# shellcheck shell=bash
+# toolchain-brew.sh - Homebrew as a toolchain: a Brewfile names the formulae and casks (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/toolchain.sh loads for `provider: brew`, or for a Brewfile at the root; `file:` names another.
+# A Brewfile pins a formula by name, so a version floats with Homebrew unless the name carries it, node@22; what
+# the kit can do is say which are behind and move them. brew is the requirement, found on PATH or at Homebrew's
+# own prefixes, so a Linux runner whose brew is installed but not on PATH still has it.
+
+toolchain-brew:file() {
+  local file
+  file=$(toolchain:field brew file)
+  printf '%s\n' "${file:-Brewfile}"
+}
+
+# toolchain-brew:brew prints the brew executable, on PATH or at one of Homebrew's prefixes.
+toolchain-brew:brew() {
+  local brew
+  for brew in "$(command -v brew 2>/dev/null)" /opt/homebrew/bin/brew /usr/local/bin/brew \
+    /home/linuxbrew/.linuxbrew/bin/brew
+  do
+    [[ -n "${brew}" && -x "${brew}" ]] && { printf '%s\n' "${brew}"; return 0; }
+  done
+  error "install Homebrew: https://brew.sh (the brew toolchain needs it)"
+  return 1
+}
+
+toolchain-brew:require() { toolchain-brew:brew >/dev/null; }
+
+toolchain-brew:install() {
+  local brew
+  brew=$(toolchain-brew:brew) || return 1
+  "${brew}" bundle install --file "$(toolchain-brew:file)" --no-upgrade --quiet
+}
+
+# The Brewfile's formulae and casks, intersected with what brew says is behind.
+toolchain-brew:outdated() {
+  local brew names doc
+  brew=$(toolchain-brew:brew) || return 1
+  names=$("${brew}" bundle list --file "$(toolchain-brew:file)" --formula --cask 2>/dev/null) || return 1
+  doc=$("${brew}" outdated --json=v2 2>/dev/null) || return 1
+  jq --raw-output --arg names "${names}" '
+    ($names | split("\n") | map(select(. != ""))) as $wanted
+    | (.formulae + .casks)[]
+    | select(.name as $n | $wanted | index($n))
+    | "\(.name)\t\(.installed_versions | last)\t\(.current_version)"' <<<"${doc}"
+}
+
+toolchain-brew:update() {
+  local brew outdated
+  brew=$(toolchain-brew:brew) || return 1
+  outdated=$(toolchain-brew:outdated | cut -f 1) || return 1
+  [[ -z "${outdated}" ]] && return 0
+  # shellcheck disable=SC2086  # one formula or cask per word
+  "${brew}" upgrade ${outdated}
+}
+
+toolchain-brew:path() {
+  local brew prefix
+  brew=$(toolchain-brew:brew) || return 1
+  prefix=$("${brew}" --prefix)
+  printf '%s/bin\n%s/sbin\n' "${prefix}" "${prefix}"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/toolchain-docker.sh b/bin/toolchain-docker.sh
new file mode 100644
index 0000000..037250d
--- /dev/null
+++ b/bin/toolchain-docker.sh
@@ -0,0 +1,112 @@
+# shellcheck shell=bash
+# toolchain-docker.sh - a container image as a toolchain: a Dockerfile holds the tools (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/toolchain.sh loads for `provider: docker`, or for a toolchain.Dockerfile at the root; `file:`
+# names another and `image:` the image's name, kit-toolchain by default. The image is built from the file and
+# tagged by the file's digest, so a change to the file is a new image and an unchanged one is never rebuilt. A
+# command runs in it with the checkout mounted at /work, as the caller's user, so what it writes is the caller's.
+#
+# What the file pins is its base: `FROM name:tag@sha256:<digest>`. outdated asks the registry for the tag's
+# current digest and names every base whose pin is behind it, or that has no pin; update rewrites the pins. docker
+# with buildx is the requirement.
+
+toolchain-docker:file() {
+  local file
+  file=$(toolchain:field docker file)
+  printf '%s\n' "${file:-toolchain.Dockerfile}"
+}
+
+toolchain-docker:require() {
+  command -v docker >/dev/null 2>&1 && return 0
+  error "install Docker: https://docs.docker.com/get-docker/ (the docker toolchain needs it)"
+  return 1
+}
+
+# toolchain-docker:tag prints the image's tag: its name and the first twelve hex digits of the file's digest.
+toolchain-docker:tag() {
+  local file name
+  file=$(toolchain-docker:file)
+  name=$(toolchain:field docker image)
+  if [[ ! -f "${file}" ]]
+  then
+    error "${file} is missing; the docker toolchain builds its image from it"
+    return 1
+  fi
+  printf '%s:%s\n' "${name:-kit-toolchain}" "$(release:digest < "${file}" | cut -c 1-12)"
+}
+
+toolchain-docker:install() {
+  local file tag
+  toolchain-docker:require || return 1
+  file=$(toolchain-docker:file)
+  tag=$(toolchain-docker:tag) || return 1
+  docker image inspect "${tag}" >/dev/null 2>&1 && return 0
+  docker build --quiet --file "${file}" --tag "${tag}" "$(dirname "${file}")" >/dev/null
+}
+
+# toolchain-docker:bases prints "<name:tag>\t<pinned digest or nothing>" for every FROM line naming an image: not
+# scratch, and not an earlier stage of the same file named by `AS <stage>`.
+toolchain-docker:bases() {
+  awk '
+    toupper($1) == "FROM" {
+      i = 2
+      if ($i ~ /^--platform=/) i++
+      ref = $i
+      if (toupper($(i + 1)) == "AS") stage[tolower($(i + 2))] = 1
+      if (ref == "scratch" || (tolower(ref) in stage)) next
+      name = ref; digest = ""
+      if (index(ref, "@") > 0) { name = substr(ref, 1, index(ref, "@") - 1); digest = substr(ref, index(ref, "@") + 1) }
+      print name "\t" digest
+    }' "$(toolchain-docker:file)"
+}
+
+# toolchain-docker:latest <name:tag> prints the digest the registry now gives the tag.
+toolchain-docker:latest() {
+  docker buildx imagetools inspect "$1" --format '{{json .Manifest}}' 2>/dev/null | jq --raw-output '.digest'
+}
+
+toolchain-docker:outdated() {
+  local base pinned latest
+  toolchain-docker:require || return 1
+  while IFS=$'\t' read -r base pinned
+  do
+    [[ -n "${base}" ]] || continue
+    latest=$(toolchain-docker:latest "${base}") || { warn "${base}: the registry did not answer"; continue; }
+    [[ "${latest}" == "${pinned}" ]] || printf '%s\t%s\t%s\n' "${base}" "${pinned:-unpinned}" "${latest}"
+  done < <(toolchain-docker:bases)
+}
+
+toolchain-docker:update() {
+  local file base pinned latest quoted from
+  file=$(toolchain-docker:file)
+  while IFS=$'\t' read -r base pinned latest
+  do
+    [[ -n "${base}" ]] || continue
+    # An image reference never holds a comma, so a comma delimits each sed command.
+    quoted=$(ere:quote "${base}")
+    if [[ "${pinned}" == unpinned ]]
+    then
+      from='^([[:space:]]*[Ff][Rr][Oo][Mm][[:space:]]+(--platform=[^[:space:]]+[[:space:]]+)?)'
+      sed -i.kit-old -E "s,${from}${quoted}([[:space:]]|\$),\\1${base}@${latest}\\3," "${file}"
+    else
+      sed -i.kit-old "s,${quoted}@${pinned},${base}@${latest}," "${file}"
+    fi
+    rm -f "${file}.kit-old"
+  done < <(toolchain-docker:outdated)
+  toolchain-docker:install
+}
+
+# The tools live in the image, so nothing is put on PATH here; a command reaches them through run.
+toolchain-docker:path() { return 0; }
+
+toolchain-docker:run() {
+  local tag
+  toolchain-docker:require || return 1
+  tag=$(toolchain-docker:tag) || return 1
+  toolchain-docker:install || return 1
+  docker run --rm --volume "${PWD}:/work" --workdir /work --user "$(id -u):$(id -g)" --env HOME=/tmp \
+    "${tag}" "$@"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/toolchain-mise.sh b/bin/toolchain-mise.sh
new file mode 100644
index 0000000..158f09c
--- /dev/null
+++ b/bin/toolchain-mise.sh
@@ -0,0 +1,45 @@
+# shellcheck shell=bash
+# toolchain-mise.sh - mise as a toolchain: mise.toml pins the tools, mise.lock records them (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# The provider bin/toolchain.sh loads for `provider: mise`, or for a mise.toml or .mise.toml at the root. mise is
+# its requirement; MISE_ENV, where the caller sets it, layers mise.<env>.toml on top as mise does.
+
+toolchain-mise:file() {
+  if [[ -f .mise.toml && ! -f mise.toml ]]
+  then printf '.mise.toml\n'
+  else printf 'mise.toml\n'
+  fi
+}
+
+toolchain-mise:require() {
+  command -v mise >/dev/null 2>&1 && return 0
+  error "install mise: https://mise.jdx.dev/installing-mise.html (the mise toolchain needs it)"
+  return 1
+}
+
+toolchain-mise:install() {
+  toolchain-mise:require || return 1
+  mise trust --quiet "$(toolchain-mise:file)" >/dev/null 2>&1 || true
+  mise install --quiet
+}
+
+# mise outdated --json is an object keyed by tool, each with its current and latest version.
+toolchain-mise:outdated() {
+  local doc
+  toolchain-mise:require || return 1
+  doc=$(mise outdated --json 2>/dev/null) || { error "mise outdated could not run; see: mise doctor"; return 1; }
+  jq --raw-output 'to_entries[] | "\(.key)\t\(.value.current // "none")\t\(.value.latest)"' <<<"${doc:-{\}}"
+}
+
+toolchain-mise:update() {
+  toolchain-mise:require || return 1
+  mise upgrade --quiet
+}
+
+toolchain-mise:path() {
+  toolchain-mise:require || return 1
+  mise bin-paths 2>/dev/null
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/toolchain.sh b/bin/toolchain.sh
new file mode 100644
index 0000000..db395af
--- /dev/null
+++ b/bin/toolchain.sh
@@ -0,0 +1,126 @@
+# shellcheck shell=bash
+# toolchain.sh - the seam over how a checkout gets the tools its gate runs: mise, brew, or docker (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Which tool manager puts a repository's tools on a desk or a runner is the repository's decision. A repository
+# declares its toolchains in .kit/settings.yml, or the kit detects them from the files each one reads:
+#
+#   toolchains:
+#     - provider: mise                       detected from mise.toml or .mise.toml
+#     - provider: brew                       detected from Brewfile
+#       file: Brewfile
+#     - provider: docker                     detected from toolchain.Dockerfile
+#       file: toolchain.Dockerfile
+#       image: example/toolchain
+#
+# A provider is toolchain-<name>.sh beside this file, its functions named toolchain-<name>:<call>, each reading its
+# record's fields through toolchain:field. A provider answers:
+#
+#   file                    the file it reads, relative to the repository root
+#   require                 its own tool is present, or a remedy
+#   install                 every pinned tool installed, from the file and its lock
+#   outdated                one line per tool behind its source: "<name>\t<installed>\t<latest>"
+#   update                  every tool moved to its latest, and the pins and the lock rewritten
+#   path                    the directories that put its tools first on PATH, one per line
+#   run <command>…          the command run with its tools; only a provider that isolates, docker, answers
+#
+# A command runs with every toolchain's path first on PATH, or inside the container where docker is declared, so
+# the gate sees the same tools on a desk and on a runner.
+#
+# see: docs/toolchains.md
+
+use release yaml
+
+# toolchain:providers prints the providers this release carries, space-separated.
+toolchain:providers() {
+  # shellcheck disable=SC2154  # kit_bin_dir is declared by bin/1st.sh
+  (cd "${kit_bin_dir}" && find . -maxdepth 1 -name 'toolchain-*.sh' | sed 's@^\./toolchain-@@; s@\.sh$@@' \
+    | LC_ALL=C sort | paste -s -d ' ' -)
+}
+
+# toolchain:declared prints the declared providers, one per line, in the order the settings name them; with none
+# declared, the ones whose file is here, in the order mise, brew, docker. A provider the kit does not carry is
+# refused by name.
+toolchain:declared() {
+  local provider found=''
+  local -a declared=()
+  while IFS=$'\x1f' read -r provider
+  do
+    [[ -n "${provider}" ]] && declared+=("${provider}")
+  done < <(yaml:records "$(release:settings)" toolchains provider)
+  if (( ${#declared[@]} > 0 ))
+  then
+    for provider in "${declared[@]}"
+    do
+      if [[ ! -f "${kit_bin_dir}/toolchain-${provider}.sh" ]]
+      then
+        error "'${provider}' is not a toolchain the kit knows; the toolchains are: $(toolchain:providers)" \
+          "(toolchains in .kit/settings.yml)"
+        return 1
+      fi
+    done
+    printf '%s\n' "${declared[@]}"
+    return 0
+  fi
+  [[ -f mise.toml || -f .mise.toml ]] && found+=$'mise\n'
+  [[ -f Brewfile ]] && found+=$'brew\n'
+  [[ -f toolchain.Dockerfile ]] && found+=$'docker\n'
+  printf '%s' "${found}"
+}
+
+# toolchain:field <provider> <field> prints a field of the provider's record, or nothing. The loop reads to the
+# end, so the reader is never left writing into a pipe nobody reads.
+toolchain:field() {
+  local provider value found=''
+  while IFS=$'\x1f' read -r provider value
+  do
+    [[ -z "${found}" && "${provider}" == "$1" ]] && found=${value}
+  done < <(yaml:records "$(release:settings)" toolchains provider "$2")
+  [[ -z "${found}" ]] || printf '%s\n' "${found}"
+}
+
+# toolchain:call <provider> <call> <argument>… runs the provider's function for the call.
+toolchain:call() {
+  local provider=$1 call=$2
+  shift 2
+  use "toolchain-${provider}" || return 1
+  "toolchain-${provider}:${call}" "$@"
+}
+
+# toolchain:each <call> runs the call on every declared toolchain in order, stopping at the first that fails.
+toolchain:each() {
+  local provider providers
+  providers=$(toolchain:declared) || return 1
+  for provider in ${providers}
+  do
+    toolchain:call "${provider}" "$@" || return 1
+  done
+}
+
+# toolchain:path prints the directories every declared toolchain puts first on PATH, in order, one per line.
+toolchain:path() {
+  toolchain:each path
+}
+
+# toolchain:isolating prints the declared toolchain that runs a command in a place of its own, docker, or nothing.
+toolchain:isolating() {
+  local providers
+  providers=$(toolchain:declared) || return 1
+  grep --line-regexp docker <<<"${providers}" || true
+}
+
+# toolchain:run <command>… runs the command with the declared toolchains' tools: inside the container where docker
+# is declared, else with every toolchain's path first on PATH. With none declared the command runs as it is.
+toolchain:run() {
+  local isolating dirs
+  isolating=$(toolchain:isolating) || return 1
+  if [[ -n "${isolating}" ]]
+  then
+    toolchain:call "${isolating}" run "$@"
+    return
+  fi
+  dirs=$(toolchain:path | paste -s -d ':' -) || return 1
+  PATH="${dirs:+${dirs}:}${PATH}" "$@"
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/tracker.sh b/bin/tracker.sh
index 5a9ea05..e3fe39b 100644
--- a/bin/tracker.sh
+++ b/bin/tracker.sh
@@ -165,7 +165,7 @@ tracker:body-refs() {
   while IFS=$'\x1f' read -r prefix provider
   do
     [[ "${provider}" == forge ]] && continue
-    escaped=$(sed 's/[][\.*^$+?(){}|/]/\\&/g' <<<"${prefix}")
+    escaped=$(ere:quote "${prefix}")
     grep --only-matching --ignore-case --extended-regexp \
       "(close[sd]?|fix(e[sd])?|resolve[sd]?):? ${escaped}[0-9]+" <<<"${body}" \
       | grep --only-matching --extended-regexp "[0-9]+\$" | sed "s/^/${prefix//\//\\/}/" || true
diff --git a/bin/yaml.sh b/bin/yaml.sh
index 66bfc78..39cba3d 100644
--- a/bin/yaml.sh
+++ b/bin/yaml.sh
@@ -24,7 +24,11 @@
 # yaml:value <file> <key> prints the scalar under <key>, unquoted, or nothing.
 yaml:value() {
   yaml:read "$1" | awk -v key="$2" '
-    $0 ~ "^" key ": " { v = $0; sub("^" key ": *", "", v); gsub(/^"|"$/, "", v); print v; exit }'
+    $0 ~ "^" key ": " {
+      v = $0; sub("^" key ": *", "", v)
+      if (v ~ /^".*"$/ || v ~ /^\x27.*\x27$/) v = substr(v, 2, length(v) - 2)
+      print v; exit
+    }'
 }
 
 # yaml:list <file> <key> prints the items of the list under <key>, unquoted, one per line.
@@ -42,7 +46,7 @@ yaml:map() {
     /^[A-Za-z0-9_-]/ { on = 0 }
     on && /^  [A-Za-z0-9_-]+: / {
       n = $0; sub(/^  /, "", n); sub(/: .*$/, "", n); v = $0; sub(/^  [A-Za-z0-9_-]+: */, "", v);
-      gsub(/^"|"$/, "", v); print n "\t" v }'
+      if (v ~ /^".*"$/ || v ~ /^\x27.*\x27$/) v = substr(v, 2, length(v) - 2); print n "\t" v }'
 }
 
 # yaml:records <file> <key> <field>… prints one line per record of the list under <key>: the named fields' values,
diff --git a/docs/architecture.md b/docs/architecture.md
index ddef8b6..811795e 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -66,11 +66,14 @@ is one forge: a repository on two is a mirror or a migration, and the setting sa
 tests/forge-conformance.bats drives every provider through a fake of its tool against one world and holds every answer
 to one shape. The core verbs never reach the seam, so a repository on no forge still installs, updates, checks, and runs
 `kit context`, and each forge's tool is its provider's requirement alone.
-The delivered check is `kit ci`, three checks that are each one kit command, run by the delivered GitHub Actions
-job for a pull request into the default branch, or by any pipeline. `kit gate` runs the repository's own gate,
-the `gate` setting or the detected justfile recipe, Makefile target, or `package.json` script, and refuses when
-there is none, since a gate that cannot run clears nothing. `kit check` holds the delivered files to
-the release. `kit linked` refuses a pull request not linked to an open issue of the repository. A human merges, and
+The delivered check is `kit ci`, four checks that are each one kit command, run by the delivered GitHub Actions job for
+a pull request into the default branch, or by any pipeline. `kit gate` runs the repository's own gate, the `gate`
+setting or the detected justfile recipe, Makefile target, or `package.json` script, and refuses when there is none,
+since a gate that cannot run clears nothing; it runs with the tools the repository's toolchains manage, mise, Homebrew,
+or a container image, as [toolchains.md](toolchains.md) describes. `kit check` holds the delivered files to the release.
+`kit linked` refuses a change not linked to an open issue. `kit policy` refuses a branch, a commit subject, or a change
+title off the repository's policy, matched by patterns or decided by Open Policy Agent, as [policy.md](policy.md)
+describes. A human merges, and
 `kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: the desk, every
 worktree with its commits past the fork, and every open pull request with its state, age, and checks.
 
@@ -81,7 +84,9 @@ worktree with its commits past the fork, and every open pull request with its st
 | A delivered file is the release's | `kit check`, in the gate and on a desk, against the release's files and the manifest's version |
 | A change has an issue | `kit linked` in the gate; `kit issue` makes the link when it starts the work |
 | The repository's own gate ran | `kit gate`, which refuses when there is no gate to run |
-| All three held, wherever CI runs | `kit ci`, the delivered check, the three as one verb, every one reported |
+| The loop's names follow the policy | `kit policy`, patterns or Open Policy Agent over the same facts |
+| The gate ran with the pinned tools | `kit toolchain install`, then the gate through the toolchain, on a desk and a runner |
+| All four held, wherever CI runs | `kit ci`, the delivered check, the four as one verb, every one reported |
 | A file's rules were named to the agent | the Claude Code hook; `kit context` in every other harness |
 | A file's rules were asked for | `.git/kit/context.log`, one line per ask |
 | A file keeps its rule's mechanical part | `kit lint`, each rule's own linter over the paths it governs |
diff --git a/docs/modules.md b/docs/modules.md
index b420620..e626288 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -118,6 +118,9 @@ answers:
 | `gate` | What `kit gate` runs; a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script is detected when absent. |
 | `require_signing` | `true` makes `kit issue` refuse a desk without a signing key. |
 | `answers` | The values a module's templates take, overriding the module's own defaults. |
+| `toolchains` | The tool managers that put the gate's tools on `PATH`, `mise`, `brew`, or `docker`; see [toolchains.md](toolchains.md). |
+| `policy` | The patterns a branch, a commit subject, and a change title must match; see [policy.md](policy.md). |
+| `policy_engine` | `patterns` or `opa`; see [policy.md](policy.md). |
 | `trackers` | The trackers besides the forge's own whose issues the loop takes, a prefix and a provider each; see [trackers.md](trackers.md). |
 
 ## Modules a repository defines
@@ -147,5 +150,6 @@ found by `kit context` like any other.
 | `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` |
 | `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
 | `claude` | no | `kit` | a region in `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
+| `policy-opa` | no | `kit` | `.kit/policy/kit.rego`, the naming policy in Rego, so `kit policy` runs on Open Policy Agent |
 
 No module in this release delivers to `home`. Each module's `docs/README.md` says what it places and why.
diff --git a/docs/policy.md b/docs/policy.md
new file mode 100644
index 0000000..c0ba695
--- /dev/null
+++ b/docs/policy.md
@@ -0,0 +1,66 @@
+# Policy
+
+What a branch, a commit subject, or a change's title may be is a policy, and a policy is checked, not described.
+`kit policy` gathers the facts once and an engine names every refusal; `kit ci` runs it beside the gate, so a name
+off the policy fails the delivered check like a failing test.
+
+## The facts
+
+`kit policy --input` prints the document every engine reads:
+
+```json
+{
+  "branch": "7-fix-the-thing",
+  "default_branch": "main",
+  "commits": [{"sha": "56d4f4b…", "subject": "#7 cli: fix the thing"}],
+  "change": {"number": 3, "title": "Fix the thing", "body": "Closes #7"},
+  "policy": {"branch": "…", "commit_subject": "…", "change_title": "…"}
+}
+```
+
+The branch is the change's head on a runner and the current branch on a desk; on the default branch, or detached,
+nothing is under check. The commits are those past the fork from the default branch at origin, merges aside, which
+is why the delivered workflow fetches full history. The change is read through the forge, and is `null` where no
+forge or no change answers.
+
+## The rules
+
+`policy:` in `.kit/settings.yml` holds one extended regular expression per subject. A subject absent takes the
+kit's default, the loop's own names from `.kit/1st.md`; an empty pattern turns that rule off.
+
+| Subject | Checks | Default |
+| --- | --- | --- |
+| `branch` | the branch's name | `^[a-z0-9]+-[a-z0-9][a-z0-9-]*$`, as `kit issue` makes it |
+| `commit_subject` | every commit's subject past the fork | `^([A-Z]+)?#[0-9]+ [^ ]`, opening with its issue's reference |
+| `change_title` | the open change's title | `^[^[:cntrl:]]{1,120}$`, one line of at most 120 |
+
+```yaml
+policy:
+  branch: '^(feature|fix)/[a-z0-9-]+$'
+  commit_subject: ''
+```
+
+A single-quoted pattern is taken literally. Write in the subset bash's extended regular expressions and OPA's RE2
+share, character classes, anchors, alternation, and counted repetition, so either engine reads it the same way.
+
+## The engines
+
+- `patterns`, the default, matches each rule in bash and needs no tool.
+- `opa`, Open Policy Agent, evaluates every `.rego` file under `.kit/policy/`, package `kit.policy`, the set
+  `deny` of strings being the refusals. It is chosen by `policy_engine: opa`, or by a `.rego` file being there. The
+  `policy-opa` module delivers `.kit/policy/kit.rego`, the patterns engine's rules in Rego, refusal for refusal, so
+  taking it changes nothing until the repository adds a rule a pattern cannot say in a file of its own beside it.
+  The repository pins `opa` in its toolchain.
+
+```rego
+package kit.policy
+
+import rego.v1
+
+deny contains msg if {
+    count(input.commits) > 20
+    msg := sprintf("%d commits; split the change", [count(input.commits)])
+}
+```
+
+`tests/policy.bats` holds the two engines to the same refusals on the same facts.
diff --git a/docs/toolchains.md b/docs/toolchains.md
new file mode 100644
index 0000000..b3e1001
--- /dev/null
+++ b/docs/toolchains.md
@@ -0,0 +1,49 @@
+# Toolchains
+
+The gate runs tools, and which tool manager puts them on a desk or a runner is the repository's decision: mise,
+Homebrew, or a container image. The kit asks every one the same questions through one seam, `toolchain:` in
+`bin/toolchain.sh`, so a desk, a runner, and the delivered CI job say the same thing whichever manages the tools.
+
+## Declaring
+
+A repository declares its toolchains in `.kit/settings.yml`, in order, or the kit detects them from the files each
+one reads:
+
+```yaml
+toolchains:
+  - provider: mise
+  - provider: brew
+    file: Brewfile
+  - provider: docker
+    file: toolchain.Dockerfile
+    image: example/toolchain
+```
+
+| Provider | Detected from | Pins | Outdated means |
+| --- | --- | --- | --- |
+| `mise` | `mise.toml` or `.mise.toml` | each tool's version, resolved in `mise.lock` | `mise outdated` names it |
+| `brew` | `Brewfile` | a formula by name; a version only where the name carries it, `node@22` | `brew outdated` names it |
+| `docker` | `toolchain.Dockerfile` | each base image by digest, `FROM name:tag@sha256:…` | the registry's digest for the tag differs, or there is none |
+
+## The verbs
+
+- `kit toolchain install` installs every declared toolchain's pinned tools: `mise install`, `brew bundle install
+  --no-upgrade`, or a `docker build` of the image, tagged by the file's digest so an unchanged file is never rebuilt.
+- `kit toolchain outdated` prints one line per tool behind its source, and `--check` fails when there is one.
+- `kit toolchain update` moves every tool to its latest and rewrites the pins: `mise upgrade`, `brew upgrade` of the
+  Brewfile's outdated formulae, or the Dockerfile's `FROM` digests. Commit what it rewrote.
+- `kit toolchain path` prints the directories that put the tools first on `PATH`, for a runner's `GITHUB_PATH`.
+- `kit toolchain run <command>…` runs a command with the tools.
+
+`kit gate` runs the gate the same way: with every toolchain's path first on `PATH`, or, where docker is declared,
+inside the image, the checkout mounted at `/work` and the caller's user, so what the gate writes is the caller's.
+The image needs `bash`, since the gate runs as `bash -c`.
+
+## On a runner
+
+The delivered workflow runs `kit toolchain install` and appends `kit toolchain path` to the runner's `PATH`. Its
+one setup action puts the `mise` binary on the runner where the repository has a `mise.toml`, with its own install
+turned off; Homebrew and Docker are already on GitHub's hosted runners, and the brew provider finds Homebrew at
+its own prefix where the runner leaves it off `PATH`.
+
+`tests/toolchain.bats` drives each provider through a fake of its tool.
diff --git a/mise.lock b/mise.lock
index 85ce098..9556d59 100644
--- a/mise.lock
+++ b/mise.lock
@@ -180,6 +180,34 @@ aube = { path = ".mise/locks/npm-markdownlint-cli2/0.24.0", digest = "sha256:689
 backend = "npm:markdownlint-cli2"
 specifiers = ["0.24"]
 
+[[tools.opa]]
+version = "1.21.4"
+backend = "aqua:open-policy-agent/opa"
+specifiers = ["1.21"]
+
+[tools.opa."platforms.linux-arm64"]
+checksum = "sha256:810aa96e44f1f852d044888cf830324e44eafd0f510345339011347ab4deaab1"
+checksum_source = "mise-versions"
+url = "https://github.com/open-policy-agent/opa/releases/download/v1.21.4/opa_linux_arm64_static"
+url_api = "https://api.github.com/repos/open-policy-agent/opa/releases/assets/669241510"
+
+[tools.opa."platforms.linux-x64"]
+checksum = "sha256:2ab571f367f293bb19523b76f92f1945bbf245003392c7f392903f95c2b9b630"
+checksum_source = "mise-versions"
+url = "https://github.com/open-policy-agent/opa/releases/download/v1.21.4/opa_linux_amd64_static"
+url_api = "https://api.github.com/repos/open-policy-agent/opa/releases/assets/669241335"
+
+[tools.opa."platforms.macos-arm64"]
+checksum = "sha256:4c105208a9282f590385bccbe600875c011f0894ccf9431782dfe855e1f99aa6"
+url = "https://github.com/open-policy-agent/opa/releases/download/v1.21.4/opa_darwin_arm64_static"
+url_api = "https://api.github.com/repos/open-policy-agent/opa/releases/assets/669241240"
+
+[tools.opa."platforms.macos-x64"]
+checksum = "sha256:8802bd39bc14b58a705e6b3d4f4dd14f7f24ee657f0362c737338be243190c7e"
+checksum_source = "mise-versions"
+url = "https://github.com/open-policy-agent/opa/releases/download/v1.21.4/opa_darwin_amd64"
+url_api = "https://api.github.com/repos/open-policy-agent/opa/releases/assets/669241237"
+
 [[tools.shellcheck]]
 version = "0.11.0"
 backend = "aqua:koalaman/shellcheck"
diff --git a/mise.toml b/mise.toml
index 438fc55..52ff7bc 100644
--- a/mise.toml
+++ b/mise.toml
@@ -23,6 +23,7 @@ _.path = ["bin"]
 #   lychee              checks every link in the markdown, offline, fragments included, in the gate
 #   ajv-cli             validates every module.yml and .kit/settings.yml against their schemas, in the gate
 #   markdownlint-cli2   the markdown rule's linter, over every .md file, in kit lint and the gate
+#   opa                 the opa policy engine, which tests/policy.bats holds to the patterns engine's refusals
 #   shellcheck          the bash rule's linter, over bin/ and tests/, in kit lint and the gate
 [tools]
 actionlint = "1.7"
@@ -33,4 +34,5 @@ just = "1.59"
 lychee = "0.24"
 "npm:ajv-cli" = "5"
 "npm:markdownlint-cli2" = "0.24"
+opa = "1.21"
 shellcheck = "0.11"
diff --git a/modules/ci-github/docs/README.md b/modules/ci-github/docs/README.md
index 8ac1bf4..36be0dc 100644
--- a/modules/ci-github/docs/README.md
+++ b/modules/ci-github/docs/README.md
@@ -1,11 +1,14 @@
 # The ci-github module
 
 Places `.github/workflows/kit-ci.yml`: one GitHub Actions job, `CI`, run for a pull request into the default branch. It
-puts `kit` on `PATH`, from the kit's own checkout where `.kit/manifest` says `unreleased` and from the release the
-manifest names otherwise, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported.
+fetches full history, which `kit policy` reads; puts `kit` on `PATH`, from the kit's own checkout where `.kit/manifest`
+says `unreleased` and from the release the manifest names otherwise; installs the gate's tools with `kit toolchain
+install`, whichever of mise, Homebrew, or a container image manages them; and runs `kit ci`: the gate, `kit check`, `kit
+linked`, and `kit policy`, every one reported.
 
-mise is used only where the repository has a `mise.toml`. A repository that pins its tools another way gives the
-gate its tools its own way, and a repository on another CI calls `kit ci` from its own pipeline.
+Its one setup action, `jdx/mise-action` with its own install turned off, puts the `mise` binary on the runner where the
+repository has a `mise.toml`; Homebrew and Docker are on GitHub's hosted runners already. A repository on another CI
+calls `kit toolchain install` and `kit ci` from its own pipeline.
 
 The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
 a repository with runners of its own sets `ci_runner` under `answers:` in `.kit/settings.yml`.
diff --git a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
index 66dbd19..a78a148 100644
--- a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
@@ -3,8 +3,10 @@
 #
 # One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
 # takes the kit release .kit/manifest names from its public URL, or this checkout's own bin/ where the manifest
-# says unreleased, and runs `kit ci`: the gate, `kit check`, and `kit linked`, every one reported. mise is used
-# only where the repository has a mise.toml, so the gate's own tools come from wherever the repository pins them.
+# says unreleased, installs the gate's tools with `kit toolchain install`, whichever of mise, brew, or docker
+# manages them, and runs `kit ci`: the gate, `kit check`, `kit linked`, and `kit policy`, every one reported. The
+# one setup action puts the mise binary on the runner where the repository has a mise.toml; brew and docker are
+# on GitHub's runners already.
 #
 # Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
 # answer, from answers: in .kit/settings.yml.
@@ -32,10 +34,15 @@ jobs:
     steps:
       - name: checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # kit policy reads every commit past the fork from the default branch.
+          fetch-depth: 0
 
-      - name: tools-from-mise
+      - name: mise-on-path
         uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c  # v4.3.0
-        if: ${{ hashFiles('mise.toml') != '' }}
+        if: ${{ hashFiles('mise.toml', '.mise.toml') != '' }}
+        with:
+          install: false
 
       - name: kit-on-path
         run: |
@@ -62,6 +69,9 @@ jobs:
             printf '%s/kit/bin\n' "${RUNNER_TEMP}" >> "${GITHUB_PATH}"
           fi
 
+      - name: toolchain
+        run: kit toolchain install && kit toolchain path >> "${GITHUB_PATH}"
+
       - name: kit-ci
         env:
           GH_TOKEN: ${{ github.token }}
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index dc9df03..924ebe9 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -106,9 +106,12 @@ as it is.
 - `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
   `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
   it runs each rule's linter over the paths the rule governs.
-- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that runs `kit ci`: the repository's gate,
-  `kit check`, and the refusal of a pull request not linked to an open issue. `kit ci` runs the same three
-  anywhere.
+- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that installs the gate's tools with
+  `kit toolchain install` and runs `kit ci`: the repository's gate, `kit check`, the refusal of a change not
+  linked to an open issue, and `kit policy`, the refusal of a branch, commit subject, or title off the
+  repository's policy. `kit ci` runs the same four anywhere.
+- `policy-opa`: `.kit/policy/kit.rego`, the naming policy in Rego, so `kit policy` runs on Open Policy Agent and a
+  rule can say what a pattern cannot.
 - `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: a region in
   `.claude/CLAUDE.md` importing `AGENTS.md`, so it is read in every case; the deny list above merged into
   `.claude/settings.json`; and a hook that runs `kit context` before every write so the rules are named to the agent
diff --git a/modules/kit/files/repo/.kit/settings.schema.json b/modules/kit/files/repo/.kit/settings.schema.json
index 7691f78..b4bd794 100644
--- a/modules/kit/files/repo/.kit/settings.schema.json
+++ b/modules/kit/files/repo/.kit/settings.schema.json
@@ -71,6 +71,63 @@
           }
         }
       }
+    },
+    "toolchains": {
+      "type": "array",
+      "description": "The toolchains that put the gate's tools on PATH, in order. Detected from mise.toml, Brewfile, and toolchain.Dockerfile when absent.",
+      "items": {
+        "type": "object",
+        "required": [
+          "provider"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "mise",
+              "brew",
+              "docker"
+            ],
+            "description": "Which tool manager answers."
+          },
+          "file": {
+            "type": "string",
+            "description": "brew and docker: the file it reads, Brewfile or toolchain.Dockerfile by default."
+          },
+          "image": {
+            "type": "string",
+            "description": "docker: the built image's name, kit-toolchain by default."
+          }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The patterns the loop's names must match, extended regular expressions in the subset RE2 shares. A subject absent takes the kit's default; an empty pattern turns that rule off.",
+      "properties": {
+        "branch": {
+          "type": "string",
+          "description": "The branch's name. Default: ^[a-z0-9]+-[a-z0-9][a-z0-9-]*$, as kit issue makes it."
+        },
+        "commit_subject": {
+          "type": "string",
+          "description": "Every commit's subject past the fork. Default: ^([A-Z]+)?#[0-9]+ [^ ], opening with its issue's reference."
+        },
+        "change_title": {
+          "type": "string",
+          "description": "The open change's title. Default: ^[^[:cntrl:]]{1,120}$."
+        }
+      }
+    },
+    "policy_engine": {
+      "type": "string",
+      "enum": [
+        "patterns",
+        "opa"
+      ],
+      "description": "Which engine decides: patterns, matched in bash, or opa, over the Rego under .kit/policy. opa is chosen when absent and a .rego file is there."
     }
   }
 }
diff --git a/modules/policy-opa/docs/README.md b/modules/policy-opa/docs/README.md
new file mode 100644
index 0000000..2ea4f81
--- /dev/null
+++ b/modules/policy-opa/docs/README.md
@@ -0,0 +1,7 @@
+# The policy-opa module
+
+Places `.kit/policy/kit.rego`, the kit's naming policy in Rego, package `kit.policy`. With a `.rego` file under
+`.kit/policy/`, `kit policy` evaluates the policy with Open Policy Agent instead of the default patterns engine.
+The rules here are the patterns engine's, refusal for refusal, so taking the module changes nothing until the
+repository adds a rule of its own: a `.rego` file of its own beside this one, in the same package, adding to `deny`.
+`kit policy --input` prints the input document a rule reads. The repository pins `opa` in its toolchain.
diff --git a/modules/policy-opa/files/repo/.kit/policy/kit.rego b/modules/policy-opa/files/repo/.kit/policy/kit.rego
new file mode 100644
index 0000000..e2788c1
--- /dev/null
+++ b/modules/policy-opa/files/repo/.kit/policy/kit.rego
@@ -0,0 +1,33 @@
+# kit.rego - the kit's naming policy in Rego: the patterns engine's rules, word for word
+# ----------------------------------------------------------------------------------------------------------------------
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. A repository's own rules go in
+# a file of its own beside this one, in the same package, adding to deny; `kit policy --input` prints the input.
+
+package kit.policy
+
+import rego.v1
+
+deny contains msg if {
+	input.branch != null
+	pattern := input.policy.branch
+	pattern != ""
+	not regex.match(pattern, input.branch)
+	msg := sprintf("branch '%s' does not match policy.branch: %s", [input.branch, pattern])
+}
+
+deny contains msg if {
+	pattern := input.policy.commit_subject
+	pattern != ""
+	some commit in input.commits
+	not regex.match(pattern, commit.subject)
+	msg := sprintf("commit %s '%s' does not match policy.commit_subject: %s",
+		[substring(commit.sha, 0, 7), commit.subject, pattern])
+}
+
+deny contains msg if {
+	input.change != null
+	pattern := input.policy.change_title
+	pattern != ""
+	not regex.match(pattern, input.change.title)
+	msg := sprintf("change title '%s' does not match policy.change_title: %s", [input.change.title, pattern])
+}
diff --git a/modules/policy-opa/module.yml b/modules/policy-opa/module.yml
new file mode 100644
index 0000000..52464f3
--- /dev/null
+++ b/modules/policy-opa/module.yml
@@ -0,0 +1,7 @@
+# modules/policy-opa/module.yml - the policy-opa module: the kit's naming policy as Rego, for Open Policy Agent
+# ----------------------------------------------------------------------------------------------------------------------
+# docs/modules.md says what each key means.
+
+description: "The kit's naming policy as Rego, so kit policy runs on Open Policy Agent and rules can grow beyond patterns"
+depends:
+  - kit
diff --git a/tests/ci.bats b/tests/ci.bats
index 4c7166c..2e28d8a 100644
--- a/tests/ci.bats
+++ b/tests/ci.bats
@@ -27,12 +27,13 @@ teardown() {
   [[ "$output" == *"gate ran"* ]]
   [[ "$output" == *"every delivered file matches"* ]]
   [[ "$output" == *"kit linked <number>"* ]]
-  [[ "$output" == *"1 of 3 checks refused"* ]]
+  [[ "$output" == *"the patterns policy allows"* ]]
+  [[ "$output" == *"1 of 4 checks refused"* ]]
   printf 'edited\n' >> .kit/1st.md
   rm justfile
   run env -u GITHUB_EVENT_PATH "${kit_checkout}/bin/kit" ci
   [ "$status" -eq 3 ]
-  [[ "$output" == *"3 of 3 checks refused"* ]]
+  [[ "$output" == *"3 of 4 checks refused"* ]]
 }
 
 # ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/forge-conformance.bats b/tests/forge-conformance.bats
index b322f6e..aafc710 100644
--- a/tests/forge-conformance.bats
+++ b/tests/forge-conformance.bats
@@ -60,6 +60,7 @@ world-github() {
   fixture pr-all.json <<<'[{"state": "OPEN"}]'
   fixture pr-url.txt <<<'https://github.com/empowerite/example/pull/3'
   fixture issue-url.txt <<<'https://github.com/empowerite/example/issues/7'
+  fixture pr.json <<<'{"title": "Fix the thing", "body": "Closes #7"}'
   fixture closing.json <<'JSON'
 {"data": {"repository": {"pullRequest": {"closingIssuesReferences": {"nodes": [
   {"number": 7, "state": "OPEN", "repository": {"nameWithOwner": "empowerite/example"}}]}}}}}
@@ -86,6 +87,7 @@ JSON
   route gh 'pr list --head 7-fix-the-thing --state open*' pr-open.json
   route gh 'pr list --head 7-fix-the-thing --state all*' pr-all.json
   route gh 'pr create --draft --base main --head 7-fix-the-thing --title Fix the thing*' pr-url.txt
+  route gh 'pr view 3 --json *' pr.json
   route gh 'api graphql*number=3*' closing.json
   route gh 'api graphql*' open-prs.json
 }
@@ -105,7 +107,7 @@ world-gitlab() {
   fixture mr.json <<'JSON'
 {"iid": 3, "title": "Fix the thing", "draft": false, "source_branch": "7-fix-the-thing",
  "created_at": "2026-10-01T09:00:00.000Z", "author": {"username": "ada"}, "has_conflicts": false,
- "detailed_merge_status": "mergeable", "description": "", "head_pipeline": {"id": 11, "status": "success"}}
+ "detailed_merge_status": "mergeable", "description": "Closes #7", "head_pipeline": {"id": 11, "status": "success"}}
 JSON
   fixture jobs.json <<'JSON'
 [{"name": "a", "status": "success", "started_at": "2026-10-01T10:00:00.120Z", "finished_at": "2026-10-01T10:00:30.000Z"},
@@ -174,6 +176,10 @@ JSON
     [ "$output" = "3" ]
     run call pr-closing-issues 3
     [ "$output" = "7 OPEN empowerite/example" ]
+    run call pr-title 3
+    [ "$output" = "Fix the thing" ]
+    run call pr-body 3
+    [ "$output" = "Closes #7" ]
   done
 }
 
diff --git a/tests/policy.bats b/tests/policy.bats
new file mode 100644
index 0000000..c91a5c7
--- /dev/null
+++ b/tests/policy.bats
@@ -0,0 +1,139 @@
+#!/usr/bin/env bats
+# policy.bats - the facts, the patterns and their defaults, and two engines that refuse the same things the same way
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  export FAKE_DIR="${BATS_TEST_TMPDIR}/fake"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}" "${FAKE_DIR}/bin"
+  ln -s "${BATS_TEST_DIRNAME}/fakes/fake-tool" "${FAKE_DIR}/bin/gh"
+  : > "${FAKE_DIR}/gh.routes"
+  export PATH="${FAKE_DIR}/bin:${PATH}"
+  unset GITHUB_HEAD_REF CI_MERGE_REQUEST_SOURCE_BRANCH_NAME GITHUB_EVENT_PATH
+  work=$(mktemp -d)
+  cd "${work}"
+  git init --quiet --bare --initial-branch=main origin.git
+  git clone --quiet origin.git desk 2>/dev/null
+  cd desk
+  git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+  git commit --quiet --allow-empty --message "#1 start: the first" && git push --quiet origin main
+  git remote set-head origin main
+  mkdir .kit
+}
+
+teardown() {
+  rm -rf "${work}"
+}
+
+fixture() { cat > "${FAKE_DIR}/$1"; }
+route() { printf '%s\t%s\n' "$2" "$3" >> "${FAKE_DIR}/$1.routes"; }
+
+# branch <name> <subject>… makes a branch past main with one empty commit per subject.
+branch() {
+  git switch --quiet --create "$1"
+  shift
+  for subject in "$@"
+  do
+    git commit --quiet --allow-empty --message "${subject}"
+  done
+}
+
+# change <title> makes the forge, GitHub by the setting since origin is a local path, answer a change on the
+# branch with that title.
+change() {
+  grep --quiet '^forge:' .kit/settings.yml 2>/dev/null || printf 'forge: github\n' >> .kit/settings.yml
+  fixture pr.json <<<"{\"number\": 3, \"title\": \"$1\", \"body\": \"Closes #7\"}"
+  route gh 'pr view --json number*' pr.json
+  route gh 'pr view 3 --json *' pr.json
+}
+
+@test "the facts are the branch, the commits past the fork, the change, and the rules with the kit's defaults" {
+  branch 7-fix-the-thing "#7 cli: fix the thing" "AB#4521 docs: say so"
+  change "Fix the thing"
+  run "${kit_root}/bin/kit" policy --input
+  [ "$status" -eq 0 ]
+  [ "$(jq --raw-output .branch <<<"$output")" = "7-fix-the-thing" ]
+  [ "$(jq --raw-output '[.commits[].subject] | join("|")' <<<"$output")" = "AB#4521 docs: say so|#7 cli: fix the thing" ]
+  [ "$(jq --raw-output .change.title <<<"$output")" = "Fix the thing" ]
+  [ "$(jq --raw-output '.policy | keys | join(" ")' <<<"$output")" = "branch change_title commit_subject" ]
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"the patterns policy allows the branch, 2 commit(s), the change title"* ]]
+}
+
+@test "the defaults refuse a branch, a commit subject, and a title off the loop's shape, each named" {
+  branch topic "#7 cli: fine" "wip"
+  change ""
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"branch 'topic' does not match policy.branch"* ]]
+  [[ "$output" == *"'wip' does not match policy.commit_subject"* ]]
+  [[ "$output" == *"change title '' does not match policy.change_title"* ]]
+  [[ "$output" == *"3 refusal(s) by the patterns policy"* ]]
+}
+
+@test "the repository's patterns override the defaults, an empty one turns a rule off, and an unknown subject is refused" {
+  branch feature/login "wip"
+  printf "policy:\n  branch: '^feature/[a-z-]+\$'\n  commit_subject: ''\n" > .kit/settings.yml
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 0 ]
+  printf "policy:\n  branche: '^x\$'\n" > .kit/settings.yml
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"policy has a subject the kit does not know: branche"* ]]
+}
+
+@test "on the default branch, or detached, nothing is under check" {
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"allows 0 commit(s)"* ]]
+  git commit --quiet --allow-empty --message "not checked"
+  git switch --quiet --detach
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 0 ]
+}
+
+@test "the opa engine, given the policy-opa module's Rego, refuses exactly what the patterns engine does" {
+  command -v opa >/dev/null || skip "opa, the opa policy engine, is not on PATH"
+  "${kit_root}/bin/kit" install policy-opa >/dev/null 2>&1
+  [ -f .kit/policy/kit.rego ]
+  branch topic "#7 cli: fine" "wip" "Also wrong"
+  change "A title that is fine"
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"by the opa policy"* ]]
+  by_opa=$(grep '^❌ ' <<<"$output" | grep --invert-match 'refusal(s)' | LC_ALL=C sort)
+  printf 'forge: github\npolicy_engine: patterns\n' > .kit/settings.yml
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 1 ]
+  by_patterns=$(grep '^❌ ' <<<"$output" | grep --invert-match 'refusal(s)' | LC_ALL=C sort)
+  [ "$(wc -l <<<"${by_opa}")" -eq 3 ]
+  [ "${by_opa}" = "${by_patterns}" ]
+}
+
+@test "a rule of the repository's own in Rego adds to the kit's, and a policy engine the kit does not know is refused" {
+  command -v opa >/dev/null || skip "opa, the opa policy engine, is not on PATH"
+  "${kit_root}/bin/kit" install policy-opa >/dev/null 2>&1
+  cat > .kit/policy/ours.rego <<'REGO'
+package kit.policy
+
+import rego.v1
+
+deny contains msg if {
+	count(input.commits) > 2
+	msg := sprintf("%d commits; split the change", [count(input.commits)])
+}
+REGO
+  branch 7-many "#7 a: one" "#7 a: two" "#7 a: three"
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"3 commits; split the change"* ]]
+  printf 'policy_engine: cue\n' > .kit/settings.yml
+  run "${kit_root}/bin/kit" policy
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"'cue' is not a policy engine the kit knows"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/toolchain.bats b/tests/toolchain.bats
new file mode 100644
index 0000000..fecadfc
--- /dev/null
+++ b/tests/toolchain.bats
@@ -0,0 +1,147 @@
+#!/usr/bin/env bats
+# toolchain.bats - mise, brew, and docker each answer the toolchain seam, through a fake of their tool
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# Each provider is driven by tests/fakes/fake-tool standing in for its tool, so what is proven is how the provider
+# reads its tool's answers and what it asks of it. What only the real tool can prove, that it answers as the
+# fixtures do, is proven by running kit toolchain on a desk that has it.
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  export FAKE_DIR="${BATS_TEST_TMPDIR}/fake"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}" "${FAKE_DIR}/bin"
+  for tool in mise brew docker
+  do
+    ln -s "${BATS_TEST_DIRNAME}/fakes/fake-tool" "${FAKE_DIR}/bin/${tool}"
+    : > "${FAKE_DIR}/${tool}.routes"
+  done
+  export PATH="${FAKE_DIR}/bin:${PATH}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+fixture() { cat > "${FAKE_DIR}/$1"; }
+route() { printf '%s\t%s\n' "$2" "$3" >> "${FAKE_DIR}/$1.routes"; }
+
+@test "the toolchains are detected from their files, in order, and a declared one wins" {
+  run "${kit_root}/bin/kit" toolchain list
+  [ -z "$output" ]
+  run "${kit_root}/bin/kit" toolchain install
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no toolchain is declared or detected"* ]]
+  touch mise.toml Brewfile toolchain.Dockerfile
+  run "${kit_root}/bin/kit" toolchain list
+  [ "$(awk '{ print $1 "=" $2 }' <<<"$output" | paste -s -d ' ' -)" = "mise=mise.toml brew=Brewfile docker=toolchain.Dockerfile" ]
+  mkdir .kit && printf 'toolchains:\n  - provider: brew\n    file: tools/Brewfile\n' > .kit/settings.yml
+  run "${kit_root}/bin/kit" toolchain list
+  [ "$output" = "brew     tools/Brewfile" ]
+  printf 'toolchains:\n  - provider: nix\n' > .kit/settings.yml
+  run "${kit_root}/bin/kit" toolchain list
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"'nix' is not a toolchain the kit knows; the toolchains are: brew docker mise"* ]]
+}
+
+@test "mise installs, reports, updates, and puts its bin paths first" {
+  touch mise.toml
+  fixture outdated.json <<<'{"jq": {"requested": "1.8", "current": "1.8.0", "latest": "1.8.1"}}'
+  fixture paths.txt <<<$'/m/jq/bin\n/m/just/bin'
+  route mise 'trust*' '!0'
+  route mise 'install --quiet' '!0'
+  route mise 'outdated --json' outdated.json
+  route mise 'upgrade --quiet' '!0'
+  route mise 'bin-paths' paths.txt
+  run "${kit_root}/bin/kit" toolchain install
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"mise: installing from mise.toml"* ]]
+  run "${kit_root}/bin/kit" toolchain outdated
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"mise     jq                               1.8.0            → 1.8.1"* ]]
+  run "${kit_root}/bin/kit" toolchain outdated --check
+  [ "$status" -eq 1 ]
+  run "${kit_root}/bin/kit" toolchain update
+  [ "$status" -eq 0 ]
+  grep --quiet --line-regexp 'upgrade --quiet' "${FAKE_DIR}/mise.calls"
+  run "${kit_root}/bin/kit" toolchain path
+  [ "$output" = $'/m/jq/bin\n/m/just/bin' ]
+  run "${kit_root}/bin/kit" toolchain run bash -c 'printf "%s" "${PATH%%:*}"'
+  [ "$output" = "/m/jq/bin" ]
+}
+
+@test "brew installs from the Brewfile without upgrading, and reports and moves only the Brewfile's tools" {
+  touch Brewfile
+  fixture names.txt <<<$'jq\nshellcheck'
+  fixture outdated.json <<'JSON'
+{"formulae": [{"name": "jq", "installed_versions": ["1.7.1"], "current_version": "1.8.1"},
+              {"name": "wget", "installed_versions": ["1.24"], "current_version": "1.25"}],
+ "casks": []}
+JSON
+  fixture prefix.txt <<<'/opt/brew'
+  route brew 'bundle install --file Brewfile --no-upgrade --quiet' '!0'
+  route brew 'bundle list --file Brewfile --formula --cask' names.txt
+  route brew 'outdated --json=v2' outdated.json
+  route brew 'upgrade jq' '!0'
+  route brew '--prefix' prefix.txt
+  run "${kit_root}/bin/kit" toolchain install
+  [ "$status" -eq 0 ]
+  run "${kit_root}/bin/kit" toolchain outdated
+  [[ "$output" == *"brew     jq                               1.7.1            → 1.8.1"* ]]
+  [[ "$output" != *"wget"* ]]
+  run "${kit_root}/bin/kit" toolchain update
+  [ "$status" -eq 0 ]
+  grep --quiet --line-regexp 'upgrade jq' "${FAKE_DIR}/brew.calls"
+  run "${kit_root}/bin/kit" toolchain path
+  [ "$output" = $'/opt/brew/bin\n/opt/brew/sbin' ]
+}
+
+@test "docker builds its image once per file digest, runs a command in it, and pins its bases" {
+  printf 'FROM alpine:3.20@sha256:old AS tools\nRUN true\nFROM tools\nFROM debian:12\n' > toolchain.Dockerfile
+  fixture alpine.json <<<'{"digest": "sha256:new"}'
+  fixture debian.json <<<'{"digest": "sha256:deb"}'
+  route docker 'image inspect *' '!1'
+  route docker 'build --quiet --file toolchain.Dockerfile --tag kit-toolchain:* .' '!0'
+  route docker 'run --rm *' '!0'
+  route docker 'buildx imagetools inspect alpine:3.20 *' alpine.json
+  route docker 'buildx imagetools inspect debian:12 *' debian.json
+  run "${kit_root}/bin/kit" toolchain install
+  [ "$status" -eq 0 ]
+  tag=$(sed -n 's/^build --quiet --file toolchain.Dockerfile --tag \(kit-toolchain:[0-9a-f]*\) \.$/\1/p' "${FAKE_DIR}/docker.calls")
+  [ "${#tag}" -eq 26 ]
+  run "${kit_root}/bin/kit" toolchain run just ci
+  [ "$status" -eq 0 ]
+  grep --quiet -- "run --rm --volume $(pwd -P):/work --workdir /work --user $(id -u):$(id -g) --env HOME=/tmp ${tag} just ci" \
+    "${FAKE_DIR}/docker.calls"
+  run "${kit_root}/bin/kit" toolchain outdated
+  [[ "$output" == *"alpine:3.20"*"sha256:old"*"→ sha256:new"* ]]
+  [[ "$output" == *"debian:12"*"unpinned"*"→ sha256:deb"* ]]
+  [[ "$output" != *"tools"*"→"* ]]
+  run "${kit_root}/bin/kit" toolchain update
+  [ "$status" -eq 0 ]
+  [ "$(cat toolchain.Dockerfile)" = "$(printf 'FROM alpine:3.20@sha256:new AS tools\nRUN true\nFROM tools\nFROM debian:12@sha256:deb')" ]
+}
+
+@test "the gate runs inside the docker toolchain, and with mise's path first otherwise" {
+  mkdir .kit && printf 'gate: echo gated\ntoolchains:\n  - provider: docker\n' > .kit/settings.yml
+  printf 'FROM alpine:3.20\n' > toolchain.Dockerfile
+  route docker 'image inspect *' '!0'
+  route docker 'run --rm *' '!0'
+  run "${kit_root}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  grep --quiet -- ' bash -c echo gated$' "${FAKE_DIR}/docker.calls"
+  printf 'gate: echo "${PATH%%%%:*}"\n' > .kit/settings.yml
+  mv toolchain.Dockerfile elsewhere.Dockerfile
+  touch mise.toml
+  fixture paths.txt <<<'/m/tools/bin'
+  route mise 'bin-paths' paths.txt
+  run "${kit_root}/bin/kit" gate
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"/m/tools/bin"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------

From 8168874cb79ddb70e809737fc553a742f2becf1d Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 21:43:26 -0700
Subject: [PATCH 106/108] #1 kit status: what the fetch brought, each
 checkout's uncommitted paths, and the forge asked first

The first line says what the fetch moved: the commits new on the default branch, the branches updated, new, and
pruned, and the tags new. Each checkout lists its uncommitted paths, with git's status, before its commits. The
forge's query starts in the background before the fetch, so the checkouts are drawn while it answers, and its
warnings are held for the pull requests' place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 bin/status.sh        | 181 +++++++++++++++++++++++++++++++++++--------
 docs/architecture.md |   6 +-
 tests/status.bats    |  45 ++++++++++-
 3 files changed, 196 insertions(+), 36 deletions(-)

diff --git a/bin/status.sh b/bin/status.sh
index 96e21cc..643e913 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -4,9 +4,11 @@
 #
 # status:render [--no-fetch] [--json] [--mine | --all | --owner=<login>…] prints the checkouts and the open pull
 # requests, and changes nothing. It asks the forge once, for every open pull request with the issues it closes,
-# its review threads, and the checks on its head; everything else is a local git read.
+# its review threads, and the checks on its head; everything else is a local git read. The forge is asked first,
+# in the background, so its answer arrives while the fetch and the checkouts are drawn.
 #
-# The picture: the desk, the root checkout, first; then each worktree under worktrees/; then each open pull request with
+# The picture: what the fetch brought, unless --no-fetch; the desk, the root checkout; then each worktree under
+# worktrees/, each with its uncommitted paths before its commits; then each open pull request with
 # its author, state, age, checks, the worktree holding its branch, and the issues it closes; then the branches whose
 # upstream is gone. --mine shows the pull requests the caller opened and no author column; --all, the default, shows
 # every open one, and --owner=<login>, given once or more, those the named authors opened, each with the author before
@@ -100,6 +102,69 @@ status:age() {
   fi
 }
 
+# status:refs prints "<ref> <sha>" for origin's branches and the tags, the refs a fetch moves.
+status:refs() {
+  git for-each-ref --format='%(refname) %(objectname)' refs/remotes/origin refs/tags | grep --invert-match '/HEAD '
+  return 0
+}
+
+# status:plural <count> <singular> <plural> prints "<count> <singular>" or "<count> <plural>".
+status:plural() {
+  if (( $1 == 1 ))
+  then printf '1 %s' "$2"
+  else printf '%s %s' "$1" "$3"
+  fi
+}
+
+# status:fetch-summary <before> <after> <default-branch> prints one line naming what moved between two status:refs
+# snapshots: the commits new on origin's default branch, then the branches updated, new, and pruned, then the tags
+# new; "nothing new" when nothing moved.
+status:fetch-summary() {
+  local default_ref="refs/remotes/origin/$3" kind ref old new commits=0 updated=0 added=0 pruned=0 tags=0 line part
+  local -a parts=()
+  while IFS=' ' read -r kind ref old new
+  do
+    case "${kind}:${ref}" in
+      (moved:"${default_ref}") commits=$(git rev-list --count "${old}..${new}" 2>/dev/null || printf 0) ;;
+      (moved:refs/remotes/*) updated=$(( updated + 1 )) ;;
+      (new:refs/remotes/*) added=$(( added + 1 )) ;;
+      (gone:refs/remotes/*) pruned=$(( pruned + 1 )) ;;
+      (new:refs/tags/*) tags=$(( tags + 1 )) ;;
+    esac
+  done < <(awk 'NR == FNR { old[$1] = $2; next }
+                !($1 in old) { print "new", $1, "-", $2; next }
+                old[$1] != $2 { print "moved", $1, old[$1], $2 }
+                { delete old[$1] }
+                END { for (ref in old) print "gone", ref, old[ref], "-" }' \
+             <(printf '%s\n' "$1" | grep .) <(printf '%s\n' "$2" | grep .))
+  (( commits > 0 )) && parts+=("$(status:plural "${commits}" 'new commit' 'new commits') on $3")
+  (( updated > 0 )) && parts+=("$(status:plural "${updated}" 'branch updated' 'branches updated')")
+  (( added > 0 )) && parts+=("$(status:plural "${added}" 'new branch' 'new branches')")
+  (( pruned > 0 )) && parts+=("$(status:plural "${pruned}" 'branch pruned' 'branches pruned')")
+  (( tags > 0 )) && parts+=("$(status:plural "${tags}" 'new tag' 'new tags')")
+  (( ${#parts[@]} > 0 )) || parts=('nothing new')
+  line=${parts[0]}
+  for part in "${parts[@]:1}"
+  do
+    line+=" · ${part}"
+  done
+  printf '📥 fetched origin: %s\n' "${line}"
+}
+
+# status:fetch <default-branch> fetches origin, pruning, and prints status:fetch-summary's line and a blank line;
+# where the fetch fails, a warning in its place.
+status:fetch() {
+  local before
+  before=$(status:refs)
+  if git fetch --quiet --prune origin
+  then
+    status:fetch-summary "${before}" "$(status:refs)" "$1" >&2
+  else
+    warn "git fetch --prune failed; ahead and behind counts may be stale"
+  fi
+  printf '\n' >&2
+}
+
 # status:collect prints one JSON object per open pull request, the documents the forge provider folds, or
 # nothing with a warning where the forge cannot be asked.
 status:collect() {
@@ -154,11 +219,11 @@ status:relative() {
 
 # status:checkout <path> <branch> <default-branch> prints one JSON object measuring the checkout at <path>: path,
 # relative, branch (empty when detached), detached, ahead of and behind the point where the branch left origin's
-# default branch, the lines the working tree adds and removes against that point, the count of uncommitted paths,
-# and the commits past that point as [{sha, subject}]. A detached checkout measures its lines against its own head
+# default branch, the lines the working tree adds and removes against that point, the count of uncommitted paths
+# and each as {status, path} with git's two-letter status, and the commits past that point as [{sha, subject}]. A detached checkout measures its lines against its own head
 # and lists no commits.
 status:checkout() {
-  local path=$1 branch=$2 default_branch=$3 fork='' ahead=0 behind=0 added=0 removed=0 uncommitted a r _
+  local path=$1 branch=$2 default_branch=$3 fork='' ahead=0 behind=0 added=0 removed=0 changes a r _
   [[ -n "${branch}" ]] && fork=$(status:fork "${branch}" "${default_branch}")
   if [[ -n "${fork}" ]]
   then
@@ -170,17 +235,19 @@ status:checkout() {
     [[ -n "${a}" && "${a}" != '-' ]] && added=$(( added + a ))
     [[ -n "${r}" && "${r}" != '-' ]] && removed=$(( removed + r ))
   done < <(git -C "${path}" diff --numstat "${fork:-HEAD}" 2>/dev/null || true)
-  uncommitted=$(git -C "${path}" status --porcelain | grep --count . || true)
+  changes=$(git -C "${path}" status --porcelain 2>/dev/null || true)
   {
     [[ -n "${fork}" ]] && git -C "${path}" log --format='%h%x09%s' "${fork}..${branch}" 2>/dev/null
     true
   } | jq --raw-input --slurp --compact-output \
     --arg path "${path}" --arg relative "$(status:relative "${path}")" --arg branch "${branch}" \
     --argjson ahead "${ahead}" --argjson behind "${behind}" --argjson added "${added}" --argjson removed "${removed}" \
-    --argjson uncommitted "${uncommitted}" '
-    { path: $path, relative: $relative, branch: $branch, detached: ($branch == ""),
-      ahead: $ahead, behind: $behind, added: $added, removed: $removed, uncommitted: $uncommitted,
-      commits: [split("\n")[] | select(. != "") | split("\t") | { sha: .[0], subject: (.[1:] | join("\t")) }] }'
+    --arg changes "${changes}" '
+    [$changes | split("\n")[] | select(. != "") | { status: .[0:2], path: .[3:] }] as $changes
+    | { path: $path, relative: $relative, branch: $branch, detached: ($branch == ""),
+        ahead: $ahead, behind: $behind, added: $added, removed: $removed, uncommitted: ($changes | length),
+        changes: $changes,
+        commits: [split("\n")[] | select(. != "") | split("\t") | { sha: .[0], subject: (.[1:] | join("\t")) }] }'
 }
 
 # status:label <relative> <branch> prints the label of a checkout and its plain width, tab-separated: the path with
@@ -247,15 +314,32 @@ status:count-widths() {
 }
 
 # status:checkout-block <glyph> <checkout-json> <label-width> [<widths>] prints a checkout: its row, with the
-# counts in status:count-widths' columns, then its commits, dim hash and subject. Past status_commit_cap it prints
-# the newest, a dim count of the hidden, and the oldest.
+# counts in status:count-widths' columns, then its uncommitted paths, yellow status and path, then its commits,
+# dim hash and subject. Past status_commit_cap it prints the first paths and a count of the rest, and the newest
+# commits, a dim count of the hidden, and the oldest.
 status:checkout-block() {
-  local glyph=$1 doc=$2 label_w=$3 widths=${4:-} relative branch label width mark='' sha subject
+  local glyph=$1 doc=$2 label_w=$3 widths=${4:-} relative branch label width mark='' sha subject code path
   IFS=$'\x1f' read -r relative branch < <(jq --raw-output '[.relative, .branch] | join("\u001f")' <<<"${doc}")
   IFS=$'\t' read -r label width < <(status:label "${relative}" "${branch}")
   [[ -n "${branch}" ]] || mark="   $(status:paint 33 '❗ detached HEAD')"
   printf '%s %s%*s%s   %s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" \
     "$(status:measures "${doc}" "${widths}")" >&2
+  # A status can open with a blank, which a tab read would drop, so the separator is one it cannot.
+  while IFS=$'\x1f' read -r code path
+  do
+    [[ -n "${path}" ]] || continue
+    if [[ "${code}" == '…' ]]
+    then
+      printf '   %s\n' "$(status:paint 90 "… ${path}")" >&2
+    else
+      printf '   %s %s\n' "$(status:paint 33 "${code}")" "${path}" >&2
+    fi
+  done < <(jq --raw-output --argjson cap "${status_commit_cap}" '
+    (.changes // []) as $c | ($c | length) as $n
+    | (if $n > $cap + 1
+       then ($c[:$cap][] | [.status, .path]), ["…", "and \($n - $cap) more"]
+       else $c[] | [.status, .path] end)
+    | join("\u001f")' <<<"${doc}")
   while IFS=$'\t' read -r sha subject
   do
     [[ -n "${sha}" ]] || continue
@@ -338,21 +422,38 @@ status:render() {
         return 2
     esac
   done
-  if [[ "${choice}" == mine ]]
+  # The forge is the slow read and needs nothing local, so it starts first and runs while the fetch and the local
+  # reads do; its warnings are held for the pull requests' place in the picture, so they do not land among the
+  # checkouts. --mine asks the forge who the caller is in the same job.
+  local scratch prs_job prs_failed=false
+  scratch=$(mktemp -d "${TMPDIR:-/tmp}/kit-status.XXXXXX")
+  # shellcheck disable=SC2064  # the path is fixed now; the trap outlives this function's locals
+  trap "rm -rf '${scratch}'" EXIT
+  (
+    if [[ "${choice}" == mine ]]
+    then
+      use forge
+      owners=("$(forge:me)") || exit 1
+    fi
+    status:collect | status:select "${owners[@]}"
+  ) > "${scratch}/prs" 2> "${scratch}/prs.err" &
+  prs_job=$!
+
+  main_root=$(git:main-root)
+  default_branch=$(git:default-branch)
+  if [[ "${no_fetch}" == true ]]
   then
-    use forge
-    owners=("$(forge:me)") || return 1
-  fi
-  if [[ "${no_fetch}" != true ]]
+    true
+  elif [[ "${json}" == true ]]
   then
-    git fetch --quiet --prune origin || warn "git fetch --prune failed; ahead and behind counts may be stale"
+    status:fetch "${default_branch}" 2>/dev/null
+  else
+    status:fetch "${default_branch}"
   fi
-  main_root=$(git:main-root)
-  default_branch=$(git:default-branch)
   desk_branch=$(git -C "${main_root}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
   gone=$(git:gone-branches)
 
-  # The desk, the worktrees by issue number, and the pull requests, each as JSON.
+  # The desk and the worktrees by issue number, each as JSON.
   local desk prs
   local -a worktrees=()
   desk=$(status:checkout "${main_root}" "${desk_branch}" "${default_branch}")
@@ -361,10 +462,13 @@ status:render() {
     [[ -n "${path}" ]] || continue
     worktrees+=("$(status:checkout "${path}" "${branch}" "${default_branch}")")
   done < <(git:worktrees | status:by-number)
-  prs=$(status:collect | status:select "${owners[@]}")
 
   if [[ "${json}" == true ]]
   then
+    wait "${prs_job}" || prs_failed=true
+    cat "${scratch}/prs.err" >&2
+    [[ "${prs_failed}" == false ]] || return 1
+    prs=$(<"${scratch}/prs")
     jq --null-input --argjson desk "${desk}" \
       --argjson worktrees "$(printf '%s\n' "${worktrees[@]}" | jq --slurp .)" \
       --argjson pullRequests "$(jq --slurp . <<<"${prs}")" \
@@ -373,8 +477,8 @@ status:render() {
     return 0
   fi
 
-  # Column widths across the rows that share a column; the author column is there unless --mine chose the rows.
-  local label_w=0 width title_w=0 owner_w=0 state_w=0 age_w=0 text author state_text age_secs relative
+  # The checkouts are drawn while the forge may still be answering.
+  local label_w=0 width relative widths
   local -A worktree_on=()
   for doc in "${desk}" "${worktrees[@]}"
   do
@@ -383,6 +487,25 @@ status:render() {
     (( width > label_w )) && label_w=${width}
     [[ -n "${branch}" && "${doc}" != "${desk}" ]] && worktree_on[${branch}]=${relative}
   done
+  widths=$(status:count-widths "${desk}" "${worktrees[@]}")
+  status:checkout-block '🏠' "${desk}" "${label_w}" "${widths}"
+  for doc in "${worktrees[@]}"
+  do
+    printf '\n' >&2
+    status:checkout-block '🌿' "${doc}" "${label_w}" "${widths}"
+  done
+
+  wait "${prs_job}" || prs_failed=true
+  if [[ -s "${scratch}/prs.err" ]]
+  then
+    printf '\n' >&2
+    cat "${scratch}/prs.err" >&2
+  fi
+  [[ "${prs_failed}" == false ]] || return 1
+  prs=$(<"${scratch}/prs")
+
+  # Column widths across the pull requests; the author column is there unless --mine chose the rows.
+  local title_w=0 owner_w=0 state_w=0 age_w=0 text author state_text age_secs
   while IFS=$'\x1f' read -r text author state_text age_secs
   do
     [[ -n "${text}" ]] || continue
@@ -398,14 +521,6 @@ status:render() {
   (( width < 20 )) && width=20
   (( title_w > width )) && title_w=${width}
 
-  local widths
-  widths=$(status:count-widths "${desk}" "${worktrees[@]}")
-  status:checkout-block '🏠' "${desk}" "${label_w}" "${widths}"
-  for doc in "${worktrees[@]}"
-  do
-    printf '\n' >&2
-    status:checkout-block '🌿' "${doc}" "${label_w}" "${widths}"
-  done
   while IFS= read -r doc
   do
     [[ -n "${doc}" ]] || continue
diff --git a/docs/architecture.md b/docs/architecture.md
index 811795e..bb49b52 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -74,8 +74,10 @@ or a container image, as [toolchains.md](toolchains.md) describes. `kit check` h
 `kit linked` refuses a change not linked to an open issue. `kit policy` refuses a branch, a commit subject, or a change
 title off the repository's policy, matched by patterns or decided by Open Policy Agent, as [policy.md](policy.md)
 describes. A human merges, and
-`kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: the desk, every
-worktree with its commits past the fork, and every open pull request with its state, age, and checks.
+`kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: what the fetch
+brought, the desk and every worktree with its uncommitted paths and its commits past the fork, and every open pull
+request with its state, age, and checks. It asks the forge first, in the background, so the checkouts are drawn while
+the forge answers.
 
 ## What verifies what
 
diff --git a/tests/status.bats b/tests/status.bats
index a2b9a4a..ebf52d3 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -55,6 +55,7 @@ commits-in() {
   [ "$status" -eq 0 ]
   fields='[.relative, .branch, .ahead, .behind, .added, .removed, .uncommitted, (.commits | length)] | @tsv'
   [ "$(jq -r "${fields}" <<<"$output")" = "$(printf 'worktrees/topic\ttopic\t1\t1\t2\t0\t1\t1')" ]
+  [ "$(jq --compact-output .changes <<<"$output")" = '[{"status":"??","path":"x"}]' ]
 }
 
 @test "a block shows the newest commits, counts the hidden ones, and ends with the oldest" {
@@ -78,7 +79,49 @@ commits-in() {
   run in_status status:checkout-block 🏠 "${doc}" 4
   [ "$status" -eq 0 ]
   [ "${lines[0]}" = "🏠 main   ↑1 ↓0 · +1 -0 · 1 uncommitted" ]
-  [[ "${lines[1]}" == *" two" ]]
+  [ "${lines[1]}" = "   ?? c" ]
+  [[ "${lines[2]}" == *" two" ]]
+  [ "${#lines[@]}" -eq 3 ]
+}
+
+@test "a block lists its uncommitted paths with git's status, the first ten and a count of the rest" {
+  printf 'changed\n' > a
+  for i in $(seq 1 12); do printf '%s\n' "${i}" > "n${i}"; done
+  doc=$(in_status status:checkout "${PWD}" main main)
+  run in_status status:checkout-block 🏠 "${doc}" 4
+  [ "${lines[0]}" = "🏠 main   ↑0 ↓0 · +1 -1 · 13 uncommitted" ]
+  [ "${lines[1]}" = "    M a" ]
+  [ "${lines[2]}" = "   ?? n1" ]
+  [ "${lines[11]}" = "   … and 3 more" ]
+  [ "${#lines[@]}" -eq 12 ]
+}
+
+@test "the fetch's line names the commits new on the default branch and the branches and tags it moved" {
+  git push --quiet origin main:old main:stays
+  git fetch --quiet origin
+  git clone --quiet ../origin.git ../other 2>/dev/null
+  (
+    cd ../other
+    git config user.name t && git config user.email t@example.com && git config commit.gpgsign false
+    printf 'b\n' > b && git add b && git commit --quiet --message b
+    printf 'c\n' > c && git add c && git commit --quiet --message c
+    git push --quiet origin main main:fresh main:stays HEAD:refs/tags/v1
+    git push --quiet origin --delete old
+  )
+  run in_status status:fetch main
+  [ "$status" -eq 0 ]
+  [ "${lines[0]}" = "📥 fetched origin: 2 new commits on main · 1 branch updated · 1 new branch · 1 branch pruned · 1 new tag" ]
+  run in_status status:fetch main
+  [ "${lines[0]}" = "📥 fetched origin: nothing new" ]
+}
+
+@test "kit status prints the fetch first, then the checkouts, then what the forge said, held until its place" {
+  printf 'x\n' > c
+  run "${kit_root}/bin/kit" status
+  [ "${lines[0]}" = "📥 fetched origin: nothing new" ]
+  [ "${lines[1]}" = "🏠 main   ↑0 ↓0 · +0 -0 · 1 uncommitted" ]
+  [ "${lines[2]}" = "   ?? c" ]
+  [[ "${lines[3]}" == *"forge"* ]]
 }
 
 @test "a detached checkout is marked and lists no commits" {

From 243ad010fc399fafb3b45c5aeb5be296833af902 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 23:09:17 -0700
Subject: [PATCH 107/108] #1 kit new file, templates that make and check a
 file's shape, and the documentation in plain English

A rule now carries templates, one per variant of the file it governs, under .kit/templates/<rule>/<variant>. kit
new file <path> makes a file from the most specific rule's template, the path taken from the repository root, its
holes filled from the path and from flags, and refuses a hole left empty or a file already there. kit lint holds
every governed file to the shape of one of its rule's templates, naming the line where a file leaves it; a
template, a module's region, and a path .gitattributes marks generated are held to none. The check found four
modules with shellcheck directives above their banner, a fixture without its closing rule, and two mise lock files,
now marked generated.

kit update needs the base release only to merge, by key or over an edited file, and finds every such path before
writing anything, so an update is whole or not at all. kit generate passes over templates.

The documentation, the comments, and the rules are rewritten in plain English; the code is unchanged but for kit's
usage text and one step message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .gitattributes                                |   7 +
 .github/workflows/kit-ci.yml                  |  22 +-
 .kit/1st.md                                   | 214 ++++++-----
 .kit/lefthook.yml                             |  12 +-
 .kit/manifest                                 |  34 +-
 .kit/rules/bash.md                            |  62 ++--
 .kit/rules/gitignore.md                       |  23 +-
 .kit/rules/json.md                            |  16 +-
 .kit/rules/just.md                            |  62 ++--
 .kit/rules/markdown.md                        |  51 +--
 .kit/rules/workflows.md                       |  28 +-
 .kit/rules/yaml.md                            |  13 +-
 .kit/settings.schema.json                     |  36 +-
 .kit/templates/bash/module                    |   5 +
 .kit/templates/bash/script                    |   7 +
 .kit/templates/gitignore/file                 |   4 +
 .kit/templates/gitignore/region               |   3 +
 .kit/templates/just/module                    |  22 ++
 .kit/templates/just/root                      |  22 ++
 .kit/templates/markdown/agents                |   1 +
 .kit/templates/markdown/document              |   2 +
 .kit/templates/markdown/frontmatter           |   4 +
 .kit/templates/markdown/notice                |   3 +
 .kit/templates/workflows/workflow             |  10 +
 .kit/templates/yaml/document                  |   2 +
 README.md                                     | 289 +++++++++------
 bin/1st.sh                                    |  29 +-
 bin/context.sh                                |  54 +--
 bin/forge-github.sh                           |  35 +-
 bin/forge-gitlab.sh                           |  54 ++-
 bin/forge.sh                                  |  29 +-
 bin/generate.sh                               | 135 ++++---
 bin/git.sh                                    |  65 ++--
 bin/issue.sh                                  |  96 +++--
 bin/kit                                       |  42 ++-
 bin/kit-check.sh                              |  22 +-
 bin/kit-ci.sh                                 |  14 +-
 bin/kit-context.sh                            |  14 +-
 bin/kit-gate.sh                               |  23 +-
 bin/kit-generate.sh                           |  16 +-
 bin/kit-install.sh                            |  15 +-
 bin/kit-issue.sh                              |  17 +-
 bin/kit-linked.sh                             |  17 +-
 bin/kit-lint.sh                               |  49 ++-
 bin/kit-module.sh                             |  14 +-
 bin/kit-new.sh                                | 165 +++++++++
 bin/kit-policy.sh                             |  17 +-
 bin/kit-rebase.sh                             |  11 +-
 bin/kit-region.sh                             |  18 +-
 bin/kit-release.sh                            |  34 +-
 bin/kit-status.sh                             |  10 +
 bin/kit-tidy.sh                               |  14 +
 bin/kit-toolchain.sh                          |  25 +-
 bin/kit-update.sh                             |  74 +++-
 bin/kit-version.sh                            |   3 +
 bin/policy-opa.sh                             |  16 +-
 bin/policy-patterns.sh                        |   8 +-
 bin/policy.sh                                 |  83 +++--
 bin/release.sh                                | 340 +++++++++++-------
 bin/status.sh                                 | 182 ++++++----
 bin/template.sh                               | 228 ++++++++++++
 bin/toolchain-brew.sh                         |  16 +-
 bin/toolchain-docker.sh                       |  31 +-
 bin/toolchain-mise.sh                         |  10 +-
 bin/toolchain.sh                              |  58 +--
 bin/tracker-ado.sh                            |  17 +-
 bin/tracker-forge.sh                          |   7 +-
 bin/tracker.sh                                |  73 ++--
 bin/yaml.sh                                   |  24 +-
 docs/architecture.md                          | 251 ++++++++-----
 docs/context.md                               |  69 ++--
 docs/generate.md                              | 202 +++++++----
 docs/modules.md                               | 223 ++++++++----
 docs/policy.md                                |  68 ++--
 docs/templates.md                             | 104 ++++++
 docs/toolchains.md                            |  66 ++--
 docs/trackers.md                              |  69 ++--
 justfile                                      |  56 +--
 lefthook.yml                                  |   8 +-
 mise.toml                                     |  22 +-
 modules/ci-github/docs/README.md              |  29 +-
 modules/ci-github/module.yml                  |   2 +-
 .../repo/.github/workflows/kit-ci.yml         |  22 +-
 modules/claude/docs/README.md                 |  35 +-
 modules/claude/module.yml                     |   4 +-
 modules/kit/docs/README.md                    |  21 +-
 modules/kit/files/repo/.kit/1st.md            | 214 ++++++-----
 modules/kit/files/repo/.kit/rules/bash.md     |  62 ++--
 .../kit/files/repo/.kit/rules/gitignore.md    |  23 +-
 modules/kit/files/repo/.kit/rules/json.md     |  16 +-
 modules/kit/files/repo/.kit/rules/just.md     |  62 ++--
 modules/kit/files/repo/.kit/rules/markdown.md |  51 +--
 .../kit/files/repo/.kit/rules/workflows.md    |  28 +-
 modules/kit/files/repo/.kit/rules/yaml.md     |  13 +-
 .../kit/files/repo/.kit/settings.schema.json  |  36 +-
 .../kit/files/repo/.kit/templates/bash/module |   5 +
 .../kit/files/repo/.kit/templates/bash/script |   7 +
 .../files/repo/.kit/templates/gitignore/file  |   4 +
 .../repo/.kit/templates/gitignore/region      |   3 +
 .../kit/files/repo/.kit/templates/just/module |  22 ++
 .../kit/files/repo/.kit/templates/just/root   |  22 ++
 .../files/repo/.kit/templates/markdown/agents |   1 +
 .../repo/.kit/templates/markdown/document     |   2 +
 .../repo/.kit/templates/markdown/frontmatter  |   4 +
 .../files/repo/.kit/templates/markdown/notice |   3 +
 .../repo/.kit/templates/workflows/workflow    |  10 +
 .../files/repo/.kit/templates/yaml/document   |   2 +
 modules/kit/module.yml                        |   4 +-
 modules/lefthook/docs/README.md               |  17 +-
 modules/lefthook/files/repo/.kit/lefthook.yml |  12 +-
 modules/lefthook/module.yml                   |   4 +-
 modules/module.schema.json                    |   6 +-
 modules/policy-opa/docs/README.md             |  12 +-
 .../files/repo/.kit/policy/kit.rego           |   6 +-
 modules/policy-opa/module.yml                 |   2 +-
 tests/fakes/fake-tool                         |   2 +
 tests/kit.bats                                |  18 +
 tests/lint.bats                               |  15 +-
 tests/template.bats                           | 143 ++++++++
 119 files changed, 3604 insertions(+), 1636 deletions(-)
 create mode 100644 .gitattributes
 create mode 100644 .kit/templates/bash/module
 create mode 100644 .kit/templates/bash/script
 create mode 100644 .kit/templates/gitignore/file
 create mode 100644 .kit/templates/gitignore/region
 create mode 100644 .kit/templates/just/module
 create mode 100644 .kit/templates/just/root
 create mode 100644 .kit/templates/markdown/agents
 create mode 100644 .kit/templates/markdown/document
 create mode 100644 .kit/templates/markdown/frontmatter
 create mode 100644 .kit/templates/markdown/notice
 create mode 100644 .kit/templates/workflows/workflow
 create mode 100644 .kit/templates/yaml/document
 create mode 100755 bin/kit-new.sh
 create mode 100644 bin/template.sh
 create mode 100644 docs/templates.md
 create mode 100644 modules/kit/files/repo/.kit/templates/bash/module
 create mode 100644 modules/kit/files/repo/.kit/templates/bash/script
 create mode 100644 modules/kit/files/repo/.kit/templates/gitignore/file
 create mode 100644 modules/kit/files/repo/.kit/templates/gitignore/region
 create mode 100644 modules/kit/files/repo/.kit/templates/just/module
 create mode 100644 modules/kit/files/repo/.kit/templates/just/root
 create mode 100644 modules/kit/files/repo/.kit/templates/markdown/agents
 create mode 100644 modules/kit/files/repo/.kit/templates/markdown/document
 create mode 100644 modules/kit/files/repo/.kit/templates/markdown/frontmatter
 create mode 100644 modules/kit/files/repo/.kit/templates/markdown/notice
 create mode 100644 modules/kit/files/repo/.kit/templates/workflows/workflow
 create mode 100644 modules/kit/files/repo/.kit/templates/yaml/document
 create mode 100644 tests/template.bats

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..96e3e74
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,7 @@
+# .gitattributes - how git and the forge treat paths
+# ----------------------------------------------------------------------------------------------------------------------
+
+# mise writes these lock files; marked generated, the forge folds their diffs, and kit lint holds them to no template.
+/.mise/locks/** linguist-generated
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.github/workflows/kit-ci.yml b/.github/workflows/kit-ci.yml
index 8f92fc8..61fe5a8 100644
--- a/.github/workflows/kit-ci.yml
+++ b/.github/workflows/kit-ci.yml
@@ -1,15 +1,17 @@
 # kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request into the default branch
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
-# takes the kit release .kit/manifest names from its public URL, or this checkout's own bin/ where the manifest
-# says unreleased, installs the gate's tools with `kit toolchain install`, whichever of mise, brew, or docker
-# manages them, and runs `kit ci`: the gate, `kit check`, `kit linked`, and `kit policy`, every one reported. The
-# one setup action puts the mise binary on the runner where the repository has a mise.toml; brew and docker are
-# on GitHub's runners already.
+# Runs one job, CI, on each pull request into the default branch. CI is the check name a ruleset requires. The job:
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
-# answer, from answers: in .kit/settings.yml.
+#   1. puts mise on the runner, when the repository has a mise.toml (brew and docker are already on GitHub's
+#      runners)
+#   2. puts kit on PATH: the release .kit/manifest records, downloaded from its public URL, or this checkout's own
+#      bin/ when the manifest records unreleased
+#   3. installs the gate's tools with `kit toolchain install`, whichever of mise, brew, or docker manages them
+#   4. runs `kit ci`: the gate, `kit check`, `kit linked`, and `kit policy`, and reports every result
+#
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner value
+# under answers: in .kit/settings.yml.
 #
 # see: .kit/1st.md
 
@@ -29,13 +31,13 @@ jobs:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
     runs-on: "ubuntu-latest"
     env:
-      # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
+      # mise also reads mise.ci.toml, on top of mise.toml, for the tools only a runner needs.
       MISE_ENV: ci
     steps:
       - name: checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
-          # kit policy reads every commit past the fork from the default branch.
+          # kit policy reads every commit since the branch forked from the default branch.
           fetch-depth: 0
 
       - name: mise-on-path
diff --git a/.kit/1st.md b/.kit/1st.md
index 924ebe9..a55c780 100644
--- a/.kit/1st.md
+++ b/.kit/1st.md
@@ -1,81 +1,114 @@
 <!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
 # Read this first
 
-This file is the kit's entry. It binds every agent and every session in a repository that carries `.kit/`, and
-the repository's own rules in `AGENTS.md` bind beside it. Where the two differ, the repository's rule wins.
+This file is the kit's entry point. Every agent follows it in every session, in any repository that has a `.kit/`
+directory. The repository's own rules in `AGENTS.md` apply as well. Where the two differ, `AGENTS.md` wins.
 
 ## Integrity
 
-1. Report only what happened. Write "done", "passing", or "verified" only for what ran and held.
-2. A skip is a skip. A check not run, not implemented, or not implementable is reported as exactly that. It
-   clears no gate and earns no credit.
-3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
+1. Report only what happened. Write "done", "passing", or "verified" only for something that ran and succeeded.
+2. Report a skip as a skip. A check that was not run, is not implemented, or cannot be implemented is reported as
+   exactly that. It passes no gate and earns no credit.
+3. Give the evidence for every claim, or say there is none. Name the command that ran and what it printed.
 4. Being wrong is recoverable. Misreporting is not.
-5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
-   written, through the loop, into `AGENTS.md`, a module of the repository's own under `.kit/modules/`, or a kit
-   release, where every agent and every person reads it.
+5. Rules live in the repository, never in a session's memory. When you learn a convention or receive a correction,
+   write it down, through the workflow, in one of these places, where every agent and every person reads it:
+   - `AGENTS.md`
+   - a module of the repository's own under `.kit/modules/`
+   - a kit release
 
 ## The root checkout is the human's desk
 
-The checkout at the repository root is the human's. It is where they type, review, and leave work in progress.
-It usually has `main` checked out, and may have any branch no worktree holds. An agent never checks out, resets,
-rebases, or otherwise changes it in place. Work happens in a worktree under `worktrees/`, one per issue, and
-reaches `main` only through a merged pull request.
+The desk is the root checkout on the human's machine, on whatever branch it currently has. It belongs to the human.
+They type, review, and leave work in progress there. It usually has `main` checked out, and may have any branch that
+no worktree has checked out.
 
-## The loop
+An agent never checks out, resets, rebases, or otherwise changes the desk in place. An agent works in a worktree
+under `worktrees/`, one per issue. Work reaches `main` only through a merged pull request.
 
-1. An issue exists. A change without an issue has not started.
-2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
-   pull request. It never switches the checkout it is run from.
-3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`. `kit rebase`
-   brings the branch up to date with the default branch and pushes it.
-4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
-   and how, and what was left out and why.
-5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
-   observed.
+## The workflow
 
-## Spellings an agent uses
+1. Start from an issue. A change without an issue has not started.
+2. `kit issue <N>` creates the following, and never switches the checkout you run it from:
+   - the worktree `worktrees/<N>-<slug>`
+   - a branch, linked to the issue under Development
+   - a draft pull request
+3. Work in that worktree. Sign every commit. Write each commit subject as `#<N> <area>: <subject>`. Run
+   `kit rebase` to bring the branch up to date with the default branch and push it.
+4. Run `gh pr ready` when the work is done. The pull request body is the report. It states:
+   - what changed
+   - what was checked, and how
+   - what was left out, and why
+5. A human merges. Nothing reaches `main` any other way. Do not call anything merged until you see the merge.
 
-Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. Each kit spelling
-carries the check its rule requires, and a harness with a deny list refuses the raw git spelling.
+## Kit commands instead of git commands
 
-- `kit rebase`, never `git rebase`. It refuses the root checkout and the default branch, and otherwise rebases the
-  worktree's branch onto the default branch at origin and pushes it.
+Some git commands have a kit replacement that adds the check its rule requires. An agent uses only the kit
+command. A harness with a deny list refuses the raw git command.
+
+- `kit rebase`, never `git rebase`. `kit rebase` refuses to run in the root checkout or on the default branch.
+  Otherwise it rebases the worktree's branch onto the default branch at origin and pushes it.
 - `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
 - `kit tidy`, never `git worktree remove` or `git branch -D`.
-- The desk is never switched or reset by an agent: `git checkout main`, `git switch main`, `git reset --hard`,
-  and `git push --force` are refused as well.
+- An agent never switches or resets the desk. `git checkout main`, `git switch main`, `git reset --hard`, and
+  `git push --force` are refused as well.
 
-The human at the desk is not bound by this; the root checkout is theirs.
+These limits do not apply to the human at the desk.
 
 ## Plans are prose
 
-A design, a spec, or a plan is the body of an issue, written in prose. It is never a committed file. When
-the design is written, the issue is the deliverable, and the loop above starts from it.
+Write a design, a spec, or a plan as prose in the body of an issue. Never commit it as a file. When the design is
+written, the issue is the deliverable, and the workflow above starts from it.
 
 ## The worker contract
 
-A worker is whoever implements one issue in the worktree that issue names.
+A worker is whoever implements one issue, in the worktree named for that issue.
 
-1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints a branch name
-   beginning `<N>-`.
-2. Do every command from there. Never touch the repository root checkout.
-3. Never run `kit issue`, make a branch, or make a worktree. Those were done before the handoff.
-4. Implement what the issue asks and nothing beside it.
+1. `cd` into the worktree named in the task. Confirm that `git rev-parse --abbrev-ref HEAD` prints a branch name
+   that begins with `<N>-`.
+2. Run every command from there. Never touch the root checkout.
+3. Never run `kit issue`, create a branch, or create a worktree. These were done before the handoff.
+4. Implement what the issue asks and nothing else.
 5. Push as you go.
-6. Run the repository's gate before calling anything done, and run it through the pinned toolchain.
-7. End with `gh pr ready` and the report in the pull request body.
-8. If the gate fails or the work is partial, leave the pull request a draft and say why.
+6. Before you call anything done, run the repository's gate (its own CI command, such as `just ci`) through
+   the pinned toolchain.
+7. Finish with `gh pr ready`, with the report in the pull request body.
+8. If the gate fails or the work is partial, leave the pull request as a draft and say why.
 9. Never merge.
-10. Report what ran and what it printed, nothing more.
+10. Report what ran and what it printed. Nothing more.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`, and each rule file's header names what it governs: `paths:`,
-globs on the repository path, and `content:`, patterns on the first line; `lint:` names the linter `kit lint`
-runs over the paths it governs. Before you create or change a file, run
-`kit context <path>`. It names the rules that govern the file and records that you asked. Read what it names. No
-harness holds a copy of a rule; this call is how every harness, and every person, finds it.
+Each kind of file has a rule file under `.kit/rules/`. The frontmatter at the top of a rule file has these keys:
+
+| Key | Contains |
+| --- | --- |
+| `paths:` | Globs matched against a file's path from the repository root. The rule governs a file that matches. |
+| `content:` | Patterns matched against a file's first line. The rule governs a file that matches. |
+| `lint:` | The linter that `kit lint` runs over the files the rule governs. |
+| `templates:` | The shapes a file of this kind can take. The templates are under `.kit/templates/`. |
+
+Before you change a file:
+
+1. Run `kit context <path>`. It prints the rules that govern the file, and records that you asked.
+2. Read every rule it prints.
+
+No harness keeps a copy of the rules. `kit context` is how every harness, and every person, finds them.
+
+Create a new file with `kit new file <path>`, giving the path from the repository root. Never write a new file
+from nothing. `kit new file`:
+
+- writes the file from its rule's template
+- fills the template's holes that the path supplies
+- refuses a hole you left empty, and names the flag that fills it, such as `--purpose=<…>` or `--title=<…>`
+- prints the rules to read before you write the rest of the file
+
+Two flags choose the template:
+
+- `--variant=<…>` picks another of the rule's shapes, such as a sourced bash module.
+- `--rule=<…>` names the rule for a path with no extension.
+
+`kit lint` fails any file, including one written by hand, whose shape matches none of its rule's templates.
 
 | Kind | Rule |
 | --- | --- |
@@ -87,35 +120,56 @@ harness holds a copy of a rule; this call is how every harness, and every person
 | JSON | [rules/json.md](rules/json.md) |
 | Ignore lists | [rules/gitignore.md](rules/gitignore.md) |
 
-## What the kit carries
-
-The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
-release version, the active modules, and a checksum per delivered file. The release, where it is installed,
-carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
-`kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
-delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
-`kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
-lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
-key, the kit owning only the entries it writes; a region inside a file the repository owns is opened by a
-directive, `kit:generate`, and made by the command it names, through `kit generate`; everything else is copied
-as it is.
-
-- `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
-  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a directive
-  of the repository's own, `kit:generate` naming any command, and `kit check` holds every region to its command.
-- `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
-  `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
-  it runs each rule's linter over the paths the rule governs.
-- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that installs the gate's tools with
-  `kit toolchain install` and runs `kit ci`: the repository's gate, `kit check`, the refusal of a change not
-  linked to an open issue, and `kit policy`, the refusal of a branch, commit subject, or title off the
-  repository's policy. `kit ci` runs the same four anywhere.
-- `policy-opa`: `.kit/policy/kit.rego`, the naming policy in Rego, so `kit policy` runs on Open Policy Agent and a
-  rule can say what a pattern cannot.
-- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: a region in
-  `.claude/CLAUDE.md` importing `AGENTS.md`, so it is read in every case; the deny list above merged into
-  `.claude/settings.json`; and a hook that runs `kit context` before every write so the rules are named to the agent
-  without being asked for.
-
-`kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
-new release and running `kit update`, never by editing them in place.
+## What the kit delivers
+
+The repository contains the text:
+
+- this file
+- the rules under `.kit/rules/`
+- `.kit/manifest`, which records the release version, the active modules, and a checksum for each delivered file
+
+The installed release contains the code. You run it through the `kit` command on `PATH`. The workflow commands
+are `kit issue`, `kit rebase`, `kit tidy`, `kit status`, `kit context`, `kit new file`, and `kit lint`. Run them
+exactly as written here, and in no other way.
+
+Everything the release delivers belongs to a module. A repository activates the modules it wants:
+
+- `kit install ci-github lefthook claude` activates modules when the kit is installed.
+- `kit module add claude` activates a module later.
+- `kit module remove` deactivates a module.
+
+A module of the repository's own lives under `.kit/modules/` and is activated the same way.
+
+How a delivered file is placed depends on its destination:
+
+- A `.json` file, other than a schema, is merged by key. The kit owns only the entries it writes.
+- A region inside a file the repository owns starts at a `kit:generate` directive. `kit generate` fills the region
+  by running the command the directive names.
+- Every other file is copied as it is.
+
+The modules:
+
+- `kit`: this file, the rules, and their templates, and two regions that `kit region` fills:
+  - the sentence in the repository's `AGENTS.md` that points to this file
+  - the `/worktrees/` entry in the repository's `.gitignore`
+- `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` and `kit generate --check` over the
+  staged paths. A repository's `lefthook.yml` includes it with `extends` and adds its own commands. `kit lint`
+  does not need a hook manager: it runs each rule's linter over the paths the rule governs.
+- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job. The job installs the gate's tools with
+  `kit toolchain install`, then runs `kit ci`. `kit ci` runs four checks, and runs the same four on any machine:
+  - the repository's gate
+  - `kit check`
+  - `kit linked`, which refuses a change that is not linked to an open issue
+  - `kit policy`, which refuses a branch name, commit subject, or title that breaks the repository's policy
+- `policy-opa`: `.kit/policy/kit.rego`, the naming policy in Rego. With it, `kit policy` runs on Open Policy
+  Agent, and a rule can express what a pattern cannot.
+- `claude`: support for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`. It delivers:
+  - a region in `.claude/CLAUDE.md` that imports `AGENTS.md`, so Claude Code reads `AGENTS.md` in every case
+  - the deny list above, merged into `.claude/settings.json`
+  - a hook that runs `kit context` before every write, so the agent sees the rules without asking
+
+Any file may also contain a `kit:generate` directive of the repository's own, naming any command. `kit check` fails
+when any region differs from what its command produces.
+
+`kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a new
+release and running `kit update`, never by editing them in place.
diff --git a/.kit/lefthook.yml b/.kit/lefthook.yml
index 46fc359..f1121a3 100644
--- a/.kit/lefthook.yml
+++ b/.kit/lefthook.yml
@@ -1,9 +1,13 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# The pre-commit hook runs kit lint over the staged paths: each rule's own linter, declared in the rule's
-# frontmatter, over the paths the rule governs. The repository's lefthook.yml takes this with
-# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name. Once per clone:
-# lefthook install
+# The pre-commit hook runs two commands over the staged files:
+#
+#   - kit-lint runs kit lint: each rule's own linter, declared in the rule's frontmatter, over the files the rule
+#     governs
+#   - kit-generate runs kit generate --check, which fails when a generated region is stale
+#
+# The repository's lefthook.yml includes this file with `extends: [.kit/lefthook.yml]`, and can add commands of its
+# own. Lefthook merges commands by name. Run `lefthook install` once per clone.
 #
 # see: https://lefthook.dev
 
diff --git a/.kit/manifest b/.kit/manifest
index 0593dbf..18e97c0 100644
--- a/.kit/manifest
+++ b/.kit/manifest
@@ -3,17 +3,29 @@ version unreleased
 modules kit ci-github claude lefthook
 7b50d15feae7b63b94d845b2fa6e19e3220527c5b0cac69303b7fc19bd7484a8  .claude/CLAUDE.md
 deaba46bfba4fa7787fa0bf98832225b1f6926b12cececd921bc935ae5e7da94  .claude/settings.json
-62f7be9db324ef4195af0e3932569d8a8b05cc31aac72794666c0611f4d9e745  .github/workflows/kit-ci.yml
+05de28f9c629c2ae0364cf268d51f48afa6a80ccb023667ac763370e8c9a733d  .github/workflows/kit-ci.yml
 919cc90013e2c104fe87c56c5192d327518d3f2adc2eb2da2b0536c6b5c890f4  .gitignore
-a5c6383b07c98794c1cc90749b3dddd0380db9267bfc11a81f3869bda99736de  .kit/1st.md
-a36cca49330228339ece2a2fd7fe4958f13496329de43d56e1e0534344c99d20  .kit/lefthook.yml
+35f31c081db3393a9d79fac0e6dc707f685a45e8252c5360cf0b44d2a74cabb5  .kit/1st.md
+88cfa681c54a2c2f5822d41e25a0c387f4e03a53a10aa612a65f8a2f5e04a0e4  .kit/lefthook.yml
 acf52f60f178be28ca2f09bb22f8a982bba0e61eff611ca1a91f1f8dae2ccbce  .kit/markdownlint.jsonc
-bf1dc00e9f451e3a408aa878e5430cd0511645a1c59f4ab75ed43c33d1c99d7c  .kit/rules/bash.md
-b0f6e0e6ac1c2d1271082459f53b0cfdc7ad5028a6cd9a5d3a899bf160b5cde9  .kit/rules/gitignore.md
-693815dcde0979638e20f021a6e879e5a3cc1420374f1d1329fc92d936e3461d  .kit/rules/json.md
-bfa75fb42fd85d8c43034d910cff554fcbf1e273ad22806b481ebe985f1191f9  .kit/rules/just.md
-87aa30f09c4d931d8c77731f0d6877d98e5ccfc32a775918f774bb5a5010b232  .kit/rules/markdown.md
-ceb28d32ae5522b1e0586551667bab18809c1f9be1ffcf0ed4eadbceffb2f99c  .kit/rules/workflows.md
-158d1fc1a6561a94e386291317032d80eed2973e67dba27140afe21f4027847e  .kit/rules/yaml.md
-1201987f5947fb543e6d3903050f14fb7ebb4557ed39dc4ccf4ff70f2beb357e  .kit/settings.schema.json
+09a3355a208c31d0ff7684c6c42d423305aed85315166219fbe12584750960d3  .kit/rules/bash.md
+db3c9f89c38d8890530f8276323cd0e87306876fc7c490004a3f4d10aad911c2  .kit/rules/gitignore.md
+9c2ec9138933576774ab176d58e69bfb672eba33f0cf55b11ee8a6822b9739f5  .kit/rules/json.md
+63288173fb2da9e215e86d0339cb41a1534ddd9f4bbbb1b94203f9c782d4d587  .kit/rules/just.md
+a6b792b7ccca4bd378fcfcef2cd719e1f5c32bcc70539f8c59fa719c46678d09  .kit/rules/markdown.md
+651d22705944023b1e043448c2b61204379985f4c45f76cd20546e839842819f  .kit/rules/workflows.md
+ea7f66ea35c18a8fbc12d601bcc59d5906d3db51977715bb04535b7750e8cc1b  .kit/rules/yaml.md
+b0fa97914c1194769f5e6e899d5a4fefc71336f14ed23d94e469ababa149f7d2  .kit/settings.schema.json
+fe662eb346060b6810f00e447bc982425fed30ee4b43b038a42dd5599a1fe849  .kit/templates/bash/module
+940c173655e2158eca3f7e0aedc62f64f94ecc7910c9eb806f9bb654ae7353ae  .kit/templates/bash/script
+3dc3428c169ffe8d9556e3d544d9ef94b87856deb64480842ab828e8ae467327  .kit/templates/gitignore/file
+2d4b394ac3507c23d691be5012af7514417b3622419175df9d77b802f651d095  .kit/templates/gitignore/region
+0cf8ab5d48fbc64df6c468fba13b34ab5b6959b1806078888fc7d8d35e043b04  .kit/templates/just/module
+3a62d89541cec4c0b08cce135ff9f1d0755688c1adcc4cdd75afd0402bcf13c8  .kit/templates/just/root
+82da8fdcf6e46d6a355562a120fe310b808cdaf6635b3d85d5d17a472872cfdb  .kit/templates/markdown/agents
+e98a16d7ded9d7519f99e83a21c5bc1ec8cf3b6b9cb3c704310cc7224cf24251  .kit/templates/markdown/document
+86d1e04b3bd5297b047f9cd1ab088519201ab836b434cb370477f4ee8cf34747  .kit/templates/markdown/frontmatter
+4be51fb91d50535d4e898bea86955567653e6d5f4c81970ca981f11474c13b55  .kit/templates/markdown/notice
+1892249ef31e1842e99c5316edd4ec500bf52046dc082352bb78f863daef791a  .kit/templates/workflows/workflow
+f258e584de3af1288947bdcccc10da7efdd3580ec59805f21709e2147d4a5f00  .kit/templates/yaml/document
 dddbf2a2466df80288c312eb39bfb1454cd5c0bcb65e4b2975ddcb3d39d5a9cf  AGENTS.md
diff --git a/.kit/rules/bash.md b/.kit/rules/bash.md
index 7cdc937..a45543a 100644
--- a/.kit/rules/bash.md
+++ b/.kit/rules/bash.md
@@ -6,51 +6,61 @@ paths:
 content:
   - "^#!.*/(env +)?(ba)?sh( |$)"
 lint: shellcheck --shell=bash --external-sources
+templates:
+  - variant: script
+    executable: true
+  - variant: module
 ---
 # Bash
 
-Applies to `*.sh` and `*.bash`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
-workflows.
+Applies to:
+
+- `*.sh` and `*.bash` files
+- recipe bodies under `#!/usr/bin/env bash`
+- `run:` blocks in workflows
 
 ## Shape
 
-1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
-   rule of dashes to column 120, a blank line, and an optional comment paragraph, then
-   `set -o errexit -o nounset -o pipefail`.
-2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
-   would change the caller's.
-3. The file closes with the same rule of dashes.
+1. An executed script opens with these lines, in order:
+   1. `#!/usr/bin/env bash`
+   2. a `# <file> - <purpose>` banner under 120 columns
+   3. a line of dashes to column 120
+   4. a blank line
+   5. an optional comment paragraph
+   6. `set -o errexit -o nounset -o pipefail`
+2. A sourced module opens with `# shellcheck shell=bash`, then the same banner. It sets no shell options, because
+   they would change the caller's options.
+3. The file ends with the same line of dashes.
 
 ## Style
 
 1. `then`, `do`, and `else` go on their own line, never after a semicolon.
 2. Spell `set` options out: `set -o errexit`, never `set -e`.
-3. Spell a tool's options out where every platform accepts the long form: `--raw-output`, `--field`,
-   `--quiet`. Where BSD and GNU differ, use the form both accept, which is the short one: `sed -n`, `head -n 1`,
-   `mkdir -p`, `rm -f`, `cut -d`, `cp -R`, `find -type`, `read -r`, and `git -C`.
+3. Use a tool's long options where every platform accepts them: `--raw-output`, `--field`, `--quiet`. Where BSD
+   and GNU differ, use the short form, which both accept: `sed -n`, `head -n 1`, `mkdir -p`, `rm -f`, `cut -d`,
+   `cp -R`, `find -type`, `read -r`, and `git -C`.
 4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
 5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
-6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
+6. A `case` label has both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
-8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
-   loader, `1st.sh`, is the exception: its verbs stay bare, `use`, `info`, `step`, `ok`, `section`, `warn`,
-   `error`, and `summary`, and its helpers are the `out:` and `guard:` families.
-9. A function private to one executed script is bare kebab-case.
+8. Name a function in a sourced module `<module>:<kebab-name>`, where `<module>` is the file's basename. The
+   loader, `1st.sh`, is the exception. Its verbs have bare names (`use`, `info`, `step`, `ok`, `section`, `warn`,
+   `error`, and `summary`), and its helpers use the `out:` and `guard:` prefixes.
+9. Name a function private to one executed script in bare kebab-case.
 
 ## Behavior
 
-1. An error message is one line, names the remedy where there is one, and is the same wherever the same
-   condition arises.
-2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
+1. An error message is one line. It names the remedy, if any. The same condition gives the same message everywhere.
+2. A helper that refuses returns non-zero and lets the caller end the script. It does not call `exit` itself.
 3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
-4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
-5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
-   to do, and a `--dry-run` where the mutation removes work, as a sweep of worktrees or branches does.
-6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
-7. shellcheck passes with no directive, or the directive carries the reason on the same line.
+4. Diagnostics go to stderr. Stdout is for data a caller can pipe.
+5. A command that changes a remote, a branch, or a worktree is guarded by a check that names what it is about to
+   do. If the change removes work, as a sweep of worktrees or branches does, the command also has `--dry-run`.
+6. Read the default branch from `origin/HEAD`, with `main` as the fallback. Never hard-code it.
+7. shellcheck passes with no directive. Where a directive is needed, its reason is on the same line.
 
 ## Comments
 
-1. A comment states what the code does and the non-obvious why. It carries no history and defends no obvious
-   choice.
+1. A comment states what the code does and any non-obvious reason for it. It contains no history and does not
+   defend an obvious choice.
 2. A pointer is `# see: <ref>`, on its own line after the comment it supports.
diff --git a/.kit/rules/gitignore.md b/.kit/rules/gitignore.md
index 2712da0..505efbe 100644
--- a/.kit/rules/gitignore.md
+++ b/.kit/rules/gitignore.md
@@ -3,6 +3,10 @@
 paths:
   - ".gitignore"
   - "**/.gitignore"
+templates:
+  - variant: file
+  - variant: region
+    path: .gitignore
 ---
 # Ignore lists
 
@@ -10,22 +14,21 @@ Applies to `.gitignore` at any depth.
 
 ## Shape
 
-1. A file the repository writes opens with `# .gitignore - untracked files and folders`, a rule of dashes to
-   column 120, and a blank line. One the kit made of its region alone is the kit's until the repository adds
-   to it.
-2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
-   line.
-3. The file closes with a rule of dashes.
+1. A file the repository writes opens with `# .gitignore - untracked files and folders`, a line of dashes to
+   column 120, and a blank line. A file the kit created that contains only the kit's region belongs to the kit
+   until the repository adds to it.
+2. Group the entries. Each group opens with `# <what produces it>; see: <ref>` and ends with a blank line.
+3. The file ends with a line of dashes.
 
 ## Entries
 
 1. Every entry names a file the repository itself produces. Editor and operating-system files belong in the
    user's global ignore list, not here.
-2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
-   repository.
+2. Put an entry in the deepest directory where it applies. The root `.gitignore` contains only patterns that apply
+   across the whole repository.
 3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
-4. Ignore `/worktrees/` at the root: it is where the loop checks out a branch per issue.
+4. Ignore `/worktrees/` at the root. The workflow checks out a branch for each issue there.
 
-## Adding one
+## Adding an entry
 
 Ask what produces the file. If nothing in the repository does, do not add it.
diff --git a/.kit/rules/json.md b/.kit/rules/json.md
index f89871b..c6430da 100644
--- a/.kit/rules/json.md
+++ b/.kit/rules/json.md
@@ -10,18 +10,18 @@ Applies to `*.json` and `*.jsonc`.
 
 ## Shape
 
-1. Two-space indentation. Keys in a stable order: the order the consuming tool documents, else alphabetical.
-2. One trailing newline. No trailing commas in `.json`.
-3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where
-   it reads plain JSON, the reason for a setting lives in the document that describes the file.
+1. Indent with two spaces. Keep keys in a stable order: as the consuming tool documents, else alphabetical.
+2. End with one trailing newline. No trailing commas in `.json`.
+3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where it
+   reads plain JSON, explain a setting in the document that describes the file.
 
 ## Settings
 
-1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
-2. Do not edit an entry the kit wrote in a merged settings file; change it through a release and `kit update`.
-   Everything else in the file is the repository's to edit.
+1. A disabled linter rule has a comment that names the rule and the convention it conflicts with.
+2. In a merged settings file, do not edit an entry the kit wrote. Change it through a release and `kit update`.
+   The repository may edit everything else in the file.
 
 ## Comments
 
-1. A comment states what the entry does and the non-obvious why. It carries no history.
+1. A comment states what the entry does and any non-obvious reason for it. It contains no history.
 2. A pointer is `// see: <ref>`.
diff --git a/.kit/rules/just.md b/.kit/rules/just.md
index d15175d..0a74945 100644
--- a/.kit/rules/just.md
+++ b/.kit/rules/just.md
@@ -6,22 +6,30 @@ paths:
   - "**/*.just"
 content:
   - "^#!.*/(env +)?just( |$)"
+templates:
+  - variant: root
+    path: justfile
+  - variant: module
 ---
 # Just
 
-Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the bash rule applies to it as well.
+Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, so the bash rule also applies to it.
 
 ## Shape
 
-1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120,
-   and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
-   --justfile` shebang above that; a module does not.
-2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), `set positional-arguments := true`, and `set script-interpreter := ['bash']`,
-   the interpreter named bare so the pinned bash wins. `set export := true` comes after the default-and-help
-   pair, so that pair reads the same in every justfile.
-3. The root puts the mise-pinned toolchain first on `PATH` once, at parse time, from `mise bin-paths`, so every
-   recipe calls its tools bare and the pinned tool wins over any other copy, on a desk and on a runner alike:
+1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a line of dashes to column 120,
+   and a description of what the file is and who imports it. The root justfile has the
+   `#!/usr/bin/env just --justfile` shebang above those lines. A module does not.
+2. The settings block comes next:
+   - `set dotenv-load := true`
+   - `set fallback := true`, only in a module, never in the root, because the root has no parent
+   - `set positional-arguments := true`
+   - `set script-interpreter := ['bash']`, with the interpreter named bare so the pinned bash is used
+
+   `set export := true` comes after the default-and-help pair, so that the pair is identical in every justfile.
+3. The root justfile puts the mise-pinned tools first on `PATH`, once, at parse time, from `mise bin-paths`.
+   Every recipe then calls its tools by bare name, and the pinned tool runs instead of any other copy, both
+   locally and on a CI runner:
 
    ````just
    export PATH := ```
@@ -32,7 +40,7 @@ Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the ba
      ``` + env('PATH')
    ````
 
-4. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
+4. Every justfile has the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
    # This file's own path, assigned at parse time so the body below needs no interpolation.
@@ -47,28 +55,28 @@ Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the ba
      just --justfile "${<name>_justfile}" --list
    ```
 
-5. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
-   the invoking root rather than the module's directory.
-6. The file closes with a rule of dashes.
+5. In a module the root imports with `mod <name> "<path>"`, every recipe has `[no-cd]`. The recipe body then
+   runs from the invoking root, not from the module's directory.
+6. The file ends with a line of dashes.
 
 ## Recipes
 
-1. Every recipe but the default-and-help pair carries `[doc("<emoji> <short, action-first description>")]`.
+1. Every recipe except the default-and-help pair has `[doc("<emoji> <short, action-first description>")]`.
    Related recipes share an emoji.
-2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
-   recipe does, when to run it, and what it produces.
-3. A non-trivial body is a `[script]` recipe, never a shebang recipe, with `set -o errexit -o nounset -o pipefail`
-   as its first line. A tool in it is called bare, never through `mise exec`.
-4. A body says what runs. Logic longer than a dozen lines lives in a bash script the body calls.
-5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
-   variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
-   `${name}` and nothing else.
-6. Two-space indentation inside a body. Never a tab.
-7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
+2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. The comment states what
+   the recipe does, when to run it, and what it produces.
+3. Write a non-trivial body as a `[script]` recipe, never a shebang recipe. Its first line is
+   `set -o errexit -o nounset -o pipefail`. Call a tool in it by bare name, never through `mise exec`.
+4. A body shows what runs. Move logic longer than a dozen lines into a bash script that the body calls.
+5. Use no `{{...}}` interpolation anywhere, in a body or a comment. Pass a value that `just` computes to a body as
+   an exported variable: `export <name> := <expression>`. `set export := true` exports every parameter. A body
+   refers to values only as `${name}`.
+6. Indent a body with two spaces. Never use a tab.
+7. Spell out recipe and module names. Never abbreviate them. A second `mod` at the same target is an alias.
 8. Comments wrap at 118 columns. Bodies do not wrap.
 
 ## Invocation
 
-1. The idiom is the space form, `just tools check`, never `just tools/check` and never `tools::check` outside a
-   dependency list.
+1. Call a module's recipe with spaces: `just tools check`. Never write `just tools/check`, and never write
+   `tools::check` outside a dependency list.
 2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/.kit/rules/markdown.md b/.kit/rules/markdown.md
index 4feb54c..aa3f6a3 100644
--- a/.kit/rules/markdown.md
+++ b/.kit/rules/markdown.md
@@ -3,6 +3,12 @@
 paths:
   - "**/*.md"
 lint: markdownlint-cli2 --config .kit/markdownlint.jsonc
+templates:
+  - variant: agents
+    path: AGENTS.md
+  - variant: document
+  - variant: notice
+  - variant: frontmatter
 ---
 # Markdown
 
@@ -10,46 +16,45 @@ Applies to `*.md`.
 
 ## Prose
 
-1. Write plain declarative sentences with the thing under discussion as the subject.
+1. Write plain declarative sentences, with the thing under discussion as the subject.
 2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
-3. Use a list where the content is a list, and for a procedure or a loop, so it scans. Use a table where the
-   content has columns.
+3. Use a list for a list, a procedure, or a workflow, so it scans. Use a table where the content has columns.
 4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
-5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
+5. Do not end a paragraph on a slogan. Do not restate what the code or config already states.
 6. Use the serial comma in every list of three or more.
 7. Expand an uncommon acronym the first time it appears.
 8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
-   when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
+   when it keeps the sentence on one line. Otherwise put it on its own line at the end of the paragraph.
 
 ## Snippets
 
-1. A value the reader supplies is a shell variable the prose names, `"${signing_key}"`, never an angle-bracket
-   placeholder, so the block pastes after one export.
+1. Write a value the reader supplies as a shell variable that the prose names, such as `"${signing_key}"`, never
+   as an angle-bracket placeholder. The block then works when pasted after one `export`.
 2. Where a reader may lack a prerequisite, link the page that creates it beside the command that uses it.
 
 ## Layout
 
-1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
-   per nesting level, to a limit of 12.
-2. Balance the wrap: no line, in particular the last, reads as a stub.
-3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
-4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
-5. Headings are ATX (`#`). One `#` heading per file, at the top; `AGENTS.md` is the exception, opening with the
-   sentence a harness reads first.
-6. Fenced code blocks declare a language and have a blank line on each side.
+1. Wrap prose at 118 columns, with 120 as the ceiling. Inside a list item, pull the right margin in by 4
+   columns per nesting level, to a limit of 12.
+2. Balance the wrap: no line, especially the last, is a short stub.
+3. Do not wrap fenced code, tables, HTML comments, or a line that contains only a link.
+4. Keep a list tight or loose as it was written. Reflowing never changes one into the other.
+5. Use ATX headings (`#`). Use one `#` heading per file, at the top. `AGENTS.md` is the exception: it opens with
+   the sentence a harness reads first.
+6. A fenced code block declares a language and has a blank line before and after it.
 7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
 
 ## Links
 
 1. Use inline links with descriptive text, never a bare URL in angle brackets.
-2. Use the same anchor text every time the same URL appears in a file.
-3. When a label and the link text would say the same thing, make the label the link.
-4. A relative link resolves from the file that carries it, and it resolves.
+2. Use the same link text every time the same URL appears in a file.
+3. When a label and the link text would be the same, make the label the link.
+4. A relative link resolves from the file that contains it, and it must resolve.
 
 ## Files
 
-1. Name an index file `1st.md`. It lists its siblings and says what each is for.
-2. A file says what its subject is in its first paragraph, before how to use it.
-3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
-   what the repository is.
-4. A delivered file names no repository as the source of a rule.
+1. Name an index file `1st.md`. It lists its siblings and states what each is for.
+2. The first paragraph of a file states what its subject is, before explaining how to use it.
+3. A README states what the repository is. It has no Status section and no paragraph on what the repository
+   will do or does not yet do.
+4. A delivered file does not name any repository as the source of a rule.
diff --git a/.kit/rules/workflows.md b/.kit/rules/workflows.md
index 4d02c2b..3a9400b 100644
--- a/.kit/rules/workflows.md
+++ b/.kit/rules/workflows.md
@@ -4,29 +4,31 @@ paths:
   - ".github/workflows/*.yml"
   - ".github/workflows/*.yaml"
 lint: actionlint
+templates:
+  - variant: workflow
 ---
 # Workflows
 
-Applies to GitHub Actions workflows, under `.github/workflows/`. The YAML rule applies to them as well.
+Applies to GitHub Actions workflows under `.github/workflows/`. The YAML rule also applies to them.
 
 ## Shape
 
 1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
    reader would not guess from the keys.
 2. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
-3. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
-   breaks the requirement.
-4. `permissions` is declared at the top and names the least the jobs need.
+3. Use one job per scope and one step per policy. A job's key is the check name a ruleset requires, so renaming
+   the job breaks the requirement.
+4. Declare `permissions` at the top, granting the least the jobs need.
 
 ## Steps
 
-1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
-2. A step has a `name` that is the policy it enforces, in kebab-case.
+1. Every `uses:` pins a full commit SHA, with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. Every step has a `name`: the policy it enforces, in kebab-case.
 3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
-   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
-5. A step whose verdict a reader looks for writes one `✅` line to the summary.
-6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step. The one
-   exception is the kit itself, which the delivered job fetches from the release `.kit/manifest` names, since
-   nothing else can put it there first.
+4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. If a reader will act on the
+   refusal, it also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
+5. A step whose result a reader looks for writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal has `if: ${{ !cancelled() }}`.
+7. A tool gets on `PATH` because the repository pins it and a step installs it, never through `curl` in a step.
+   The one exception is the kit itself. The delivered job downloads the release that `.kit/manifest` names,
+   because nothing else can install the kit first.
diff --git a/.kit/rules/yaml.md b/.kit/rules/yaml.md
index 222fa95..01f2215 100644
--- a/.kit/rules/yaml.md
+++ b/.kit/rules/yaml.md
@@ -3,19 +3,20 @@
 paths:
   - "**/*.yml"
   - "**/*.yaml"
+templates:
+  - variant: document
 ---
 # YAML
 
-Applies to `*.yml` and `*.yaml`. A GitHub Actions workflow follows the workflows rule as well.
+Applies to `*.yml` and `*.yaml`. A GitHub Actions workflow also follows the workflows rule.
 
 ## Shape
 
-1. The file opens with a comment: what the file configures and the one thing a reader would not guess from the
-   keys.
-2. Two-space indentation. No tabs. No trailing whitespace.
-3. A scalar that holds a colon followed by a space, or opens with a reserved character, is quoted.
+1. The file opens with a comment: what it configures, and the one thing a reader would not guess from the keys.
+2. Indent with two spaces. No tabs. No trailing whitespace.
+3. Quote a scalar that contains a colon followed by a space, or that starts with a reserved character.
 
 ## Comments
 
-1. A comment states the non-obvious why. It carries no history.
+1. A comment states the non-obvious reason. It contains no history.
 2. A pointer is `# see: <ref>`.
diff --git a/.kit/settings.schema.json b/.kit/settings.schema.json
index b4bd794..906a759 100644
--- a/.kit/settings.schema.json
+++ b/.kit/settings.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
   "title": ".kit/settings.yml",
-  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; https://github.com/empowerite/kit/blob/main/docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "description": "The repository's settings. The kit reads this file and never writes it. This schema is delivered by kit, not edited by hand. Each key is described in https://github.com/empowerite/kit/blob/main/docs/modules.md. To have an editor validate the file against this schema, add the modeline: # yaml-language-server: $schema=settings.schema.json",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -12,16 +12,16 @@
         "github",
         "gitlab"
       ],
-      "description": "The provider the loop's verbs use: github or gitlab. Detected from origin's host, github.com or gitlab.com, when absent; a self-hosted forge is named here."
+      "description": "The forge (the service that hosts the repository) the workflow commands use: github or gitlab. When absent, it is detected from origin's host, github.com or gitlab.com. A self-hosted forge must be set here."
     },
     "gate": {
       "type": "string",
       "minLength": 1,
-      "description": "What kit gate runs. A justfile ci recipe, a Makefile ci target, or a package.json ci script is detected when absent."
+      "description": "The command kit gate runs. When absent, kit gate detects a root justfile ci recipe, a Makefile ci target, or a package.json ci script."
     },
     "require_signing": {
       "type": "boolean",
-      "description": "true makes kit issue refuse a desk without a signing key."
+      "description": "When true, kit issue fails before writing anything if git has no signing key configured."
     },
     "answers": {
       "type": "object",
@@ -29,13 +29,13 @@
       "patternProperties": {
         "^[a-z_]+$": {
           "type": "string",
-          "description": "The value a module's template takes for this key, written @key@ in the template."
+          "description": "The value a module's templates use for this key, written @key@ in a template."
         }
       }
     },
     "trackers": {
       "type": "array",
-      "description": "The trackers whose issues the loop takes besides the forge's own, which answers # unless a record claims it. A reference names its tracker by its prefix: #7, AB#4521.",
+      "description": "The issue trackers the workflow uses in addition to the forge's own issues. The forge's tracker handles the # prefix unless an entry here claims it. A reference names its tracker by its prefix: #7, AB#4521.",
       "items": {
         "type": "object",
         "required": [
@@ -47,7 +47,7 @@
           "prefix": {
             "type": "string",
             "pattern": "^[A-Za-z]*#?$",
-            "description": "What a reference to this tracker opens with, before the number: AB# for Azure DevOps work items."
+            "description": "The text a reference to this tracker starts with, before the number: AB# for Azure DevOps work items."
           },
           "provider": {
             "type": "string",
@@ -55,7 +55,7 @@
               "forge",
               "ado"
             ],
-            "description": "Which tracker answers: forge for the forge's own issues, ado for Azure DevOps work items."
+            "description": "The tracker that handles the prefix: forge for the forge's own issues, ado for Azure DevOps work items."
           },
           "organization": {
             "type": "string",
@@ -67,14 +67,14 @@
           },
           "type": {
             "type": "string",
-            "description": "ado: the type of a new work item, Task when absent."
+            "description": "ado: the type of a new work item. Default: Task."
           }
         }
       }
     },
     "toolchains": {
       "type": "array",
-      "description": "The toolchains that put the gate's tools on PATH, in order. Detected from mise.toml, Brewfile, and toolchain.Dockerfile when absent.",
+      "description": "The toolchains that put the gate's tools on PATH, in order. When absent, they are detected from mise.toml, Brewfile, and toolchain.Dockerfile.",
       "items": {
         "type": "object",
         "required": [
@@ -89,15 +89,15 @@
               "brew",
               "docker"
             ],
-            "description": "Which tool manager answers."
+            "description": "The tool manager: mise, brew, or docker."
           },
           "file": {
             "type": "string",
-            "description": "brew and docker: the file it reads, Brewfile or toolchain.Dockerfile by default."
+            "description": "brew and docker: the file the tool manager reads. Default: Brewfile or toolchain.Dockerfile."
           },
           "image": {
             "type": "string",
-            "description": "docker: the built image's name, kit-toolchain by default."
+            "description": "docker: the name of the built image. Default: kit-toolchain."
           }
         }
       }
@@ -105,19 +105,19 @@
     "policy": {
       "type": "object",
       "additionalProperties": false,
-      "description": "The patterns the loop's names must match, extended regular expressions in the subset RE2 shares. A subject absent takes the kit's default; an empty pattern turns that rule off.",
+      "description": "The patterns that the branch name, commit subjects, and pull request title must match. Each is an extended regular expression, limited to the subset RE2 also supports. An absent key uses the kit's default. An empty pattern turns that rule off.",
       "properties": {
         "branch": {
           "type": "string",
-          "description": "The branch's name. Default: ^[a-z0-9]+-[a-z0-9][a-z0-9-]*$, as kit issue makes it."
+          "description": "The pattern for the branch name. Default: ^[a-z0-9]+-[a-z0-9][a-z0-9-]*$, the shape kit issue gives a branch."
         },
         "commit_subject": {
           "type": "string",
-          "description": "Every commit's subject past the fork. Default: ^([A-Z]+)?#[0-9]+ [^ ], opening with its issue's reference."
+          "description": "The pattern for the subject of every commit since the branch forked. Default: ^([A-Z]+)?#[0-9]+ [^ ], a subject that starts with its issue's reference."
         },
         "change_title": {
           "type": "string",
-          "description": "The open change's title. Default: ^[^[:cntrl:]]{1,120}$."
+          "description": "The pattern for the open pull request's title. Default: ^[^[:cntrl:]]{1,120}$."
         }
       }
     },
@@ -127,7 +127,7 @@
         "patterns",
         "opa"
       ],
-      "description": "Which engine decides: patterns, matched in bash, or opa, over the Rego under .kit/policy. opa is chosen when absent and a .rego file is there."
+      "description": "The policy engine: patterns, matched in bash, or opa, which evaluates the Rego under .kit/policy. When absent, opa is used if a .rego file is there, and patterns otherwise."
     }
   }
 }
diff --git a/.kit/templates/bash/module b/.kit/templates/bash/module
new file mode 100644
index 0000000..b4c4b63
--- /dev/null
+++ b/.kit/templates/bash/module
@@ -0,0 +1,5 @@
+# shellcheck shell=bash
+# «name» - «purpose»
+# ----------------------------------------------------------------------------------------------------------------------
+«body»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/templates/bash/script b/.kit/templates/bash/script
new file mode 100644
index 0000000..ddfdf99
--- /dev/null
+++ b/.kit/templates/bash/script
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# «name» - «purpose»
+# ----------------------------------------------------------------------------------------------------------------------
+«about»
+set -o errexit -o nounset -o pipefail
+«body»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/templates/gitignore/file b/.kit/templates/gitignore/file
new file mode 100644
index 0000000..904cc2f
--- /dev/null
+++ b/.kit/templates/gitignore/file
@@ -0,0 +1,4 @@
+# .gitignore - untracked files and folders
+# ----------------------------------------------------------------------------------------------------------------------
+«entries»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/templates/gitignore/region b/.kit/templates/gitignore/region
new file mode 100644
index 0000000..083cc3e
--- /dev/null
+++ b/.kit/templates/gitignore/region
@@ -0,0 +1,3 @@
+# kit:generate .gitignore
+«entries»
+# kit:end .gitignore
diff --git a/.kit/templates/just/module b/.kit/templates/just/module
new file mode 100644
index 0000000..5c3a322
--- /dev/null
+++ b/.kit/templates/just/module
@@ -0,0 +1,22 @@
+# «name» - see: https://just.systems/man/en/
+# ----------------------------------------------------------------------------------------------------------------------
+«about»
+set dotenv-load := true
+set fallback := true
+«settings»
+set positional-arguments := true
+«settings»
+set script-interpreter := ['bash']
+«settings»
+# This file's own path, assigned at parse time so the body below needs no interpolation.
+export «stem»_justfile := source_file()
+
+# Default recipe: list this justfile's recipes.
+_: help
+
+# List recipes in this justfile.
+[no-exit-message]
+@help *options:
+  just --justfile "${«stem»_justfile}" --list
+«recipes»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/templates/just/root b/.kit/templates/just/root
new file mode 100644
index 0000000..8e63eec
--- /dev/null
+++ b/.kit/templates/just/root
@@ -0,0 +1,22 @@
+#!/usr/bin/env just --justfile
+# justfile - see: https://just.systems/man/en/
+# ----------------------------------------------------------------------------------------------------------------------
+«about»
+set dotenv-load := true
+«settings»
+set positional-arguments := true
+«settings»
+set script-interpreter := ['bash']
+«settings»
+# This file's own path, assigned at parse time so the body below needs no interpolation.
+export root_justfile := source_file()
+
+# Default recipe: list this justfile's recipes.
+_: help
+
+# List recipes in this justfile.
+[no-exit-message]
+@help *options:
+  just --justfile "${root_justfile}" --list
+«recipes»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/.kit/templates/markdown/agents b/.kit/templates/markdown/agents
new file mode 100644
index 0000000..df26dab
--- /dev/null
+++ b/.kit/templates/markdown/agents
@@ -0,0 +1 @@
+«body»
diff --git a/.kit/templates/markdown/document b/.kit/templates/markdown/document
new file mode 100644
index 0000000..7a12cfe
--- /dev/null
+++ b/.kit/templates/markdown/document
@@ -0,0 +1,2 @@
+# «title»
+«body»
diff --git a/.kit/templates/markdown/frontmatter b/.kit/templates/markdown/frontmatter
new file mode 100644
index 0000000..5dea690
--- /dev/null
+++ b/.kit/templates/markdown/frontmatter
@@ -0,0 +1,4 @@
+---
+«frontmatter»
+---
+«body»
diff --git a/.kit/templates/markdown/notice b/.kit/templates/markdown/notice
new file mode 100644
index 0000000..aa92f12
--- /dev/null
+++ b/.kit/templates/markdown/notice
@@ -0,0 +1,3 @@
+<!-- «notice» -->
+# «title»
+«body»
diff --git a/.kit/templates/workflows/workflow b/.kit/templates/workflows/workflow
new file mode 100644
index 0000000..0eefc0a
--- /dev/null
+++ b/.kit/templates/workflows/workflow
@@ -0,0 +1,10 @@
+# «purpose»
+«about»
+name: «workflow»
+«body»
+on:
+«triggers»
+permissions:
+«permissions»
+jobs:
+«jobs»
diff --git a/.kit/templates/yaml/document b/.kit/templates/yaml/document
new file mode 100644
index 0000000..9b74360
--- /dev/null
+++ b/.kit/templates/yaml/document
@@ -0,0 +1,2 @@
+# «purpose»
+«body»
diff --git a/README.md b/README.md
index 5f567b1..c6e5fa8 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,67 @@
 # empowerite/kit: **k**eep **i**t **t**rustworthy
 
-Do you trust your agents? They were trained on the whole of what people have written, and that includes every shortcut
-anyone ever took: the "done" that was not, the test that was skipped and reported as passing, the rebase that quietly
-rewrote a colleague's branch. An agent is a tireless new colleague who has read everything and holds none of your house
-rules, unless you put them where it looks. kit is the house rules, put where agents look, and the checks that hold
-agents to them, as a versioned release any repository can take and keep taking.
-
-The rules are the smaller part. The point is verification that does not depend on anyone's word:
-
-- `kit ci`, which refuses a pull request without a linked open issue, a branch, commit subject, or title off the
-  repository's policy, and a gate that did not run, from the delivered GitHub Actions job or from any pipeline;
-- `kit toolchain`, which installs, reports, and updates the gate's tools whether mise, Homebrew, or a container
-  image manages them, and runs the gate with them;
-- `kit check`, which holds every delivered file to its release and every generated region to its command;
-- `kit lint`, each rule's own linter over the paths it governs, before a commit or anywhere;
-- a deny list that refuses the spellings the rules forbid;
-- `kit status`, which shows what every pull request's checks said.
-
-The text those checks hold the work against is the entry file an agent reads first and a rule file per kind of file. Two
-more things come with it. The root checkout is kept as the human's desk. And `kit issue`, the one command no harness
-provides, turns an issue into a worktree with a draft pull request. A tag on `main` publishes a release. A repository
-pins it, installs it, and keeps rules of its own beside it. The design is
-[#1](https://github.com/empowerite/kit/issues/1) and [#4](https://github.com/empowerite/kit/issues/4), and the entry
-file every agent reads is [.kit/1st.md](.kit/1st.md).
+kit is a versioned set of rules for AI coding agents, plus the checks that enforce them. A repository installs a
+release, pins it, and updates it like any other tool.
+
+Agents learn from everything people have written, including the shortcuts: work called done that was not, a skipped
+test reported as passing, a rebase that overwrote a colleague's branch. kit puts the rules where agents read them and
+checks the work in CI, so the result does not depend on an agent's word.
+
+What kit checks:
+
+- `kit ci` refuses a pull request when:
+  - it is not linked to an open issue,
+  - its branch name, commit subjects, or title break the repository's naming policy, or
+  - the repository's gate did not run.
+
+  It runs in the delivered GitHub Actions job or in any other pipeline.
+- `kit check` fails when a delivered file differs from the release, or a generated region differs from the output
+  of its command.
+- `kit lint` runs each rule's linter over the files the rule covers, before a commit or at any time.
+- A deny list blocks the raw git commands the rules forbid, such as `git rebase`.
+
+What else kit provides:
+
+- `.kit/1st.md`, the file every agent reads first, and one rule file per kind of file.
+- `kit issue`, which turns an issue into a worktree, a linked branch, and a draft pull request.
+- `kit toolchain`, which installs, lists, and updates the gate's tools (mise, Homebrew, or a container image) and
+  runs the gate with them.
+- `kit status`, which shows every open pull request and the result of its checks.
+- A rule that agents never change the desk: the root checkout on your machine, on whatever branch it currently has.
+
+A repository keeps its own rules next to the delivered ones. The design is in
+[#1](https://github.com/empowerite/kit/issues/1) and [#4](https://github.com/empowerite/kit/issues/4).
 
 ## Why a release, and not a copy
 
-A copy drifts. A release is pinned, so a repository knows which rules bind it; updated, so a change reaches every
-repository as a pull request that bumps a version; and checked, so `kit check` fails the build when a delivered
-file was edited in place. The rules a repository adds live beside the delivered ones, in its own files, and
-survive every update.
+A copied file drifts. A release does not:
+
+- It is pinned, so a repository knows which version of the rules applies.
+- It is updated by a pull request that bumps the version, so every repository gets the change the same way.
+- It is checked: `kit check` fails the build when someone edits a delivered file in place.
+
+A repository's own rules live in its own files, and updates leave them alone.
 
 ## Install
 
-The kit ships as a release: a tarball holding `bin/`, `modules/`, and a stamped `version`. Take it whichever way
-the repository takes its other tools.
+A release is a tarball containing `bin/`, `modules/`, and a `version` file. Install it the same way the
+repository installs its other tools.
 
-With mise, pin it in `mise.toml` and the version is part of the repository:
+With mise, pin it in `mise.toml`:
 
 ```toml
 [tools]
 "github:empowerite/kit" = { version = "0.1.0", version_prefix = "release/" }
 ```
 
-With Homebrew, from the empowerite tap:
+With Homebrew:
 
 ```sh
 brew install empowerite/tap/kit
 ```
 
-Or by hand, with `gh`, which the kit needs anyway. Without a tag this takes the latest release, never a
-pre-release; `gh release download "release/${version}" ...` takes a particular one. Unpack it and put its `bin/` on
-`PATH`:
+By hand, with `gh`. This downloads the latest release, never a pre-release. For a specific version, run
+`gh release download "release/${version}" ...` instead. Unpack it and put its `bin/` on `PATH`:
 
 ```sh
 gh release download --repo empowerite/kit --pattern 'kit-*.tar.gz' --output kit.tar.gz
@@ -59,61 +69,91 @@ mkdir kit && tar --extract --gzip --file kit.tar.gz --directory kit --strip-comp
 export PATH="${PWD}/kit/bin:${PATH}"
 ```
 
-The kit needs bash 4.4 or later, git, and `jq`. The loop's verbs, `kit issue`, `kit status`, `kit tidy`, and `kit
-linked`, also need the tool of the forge, the service that hosts the repository: `gh` for GitHub, `glab` for GitLab.
-macOS ships bash 3.2, and `brew install bash` gives a current one. With mise, an exact pin installs the minute a release
-exists; a range pin sees a new kit a day after it ships unless `[settings]` carries `minimum_release_age_excludes =
-["github:empowerite/kit"]`.
+Requirements:
+
+- bash 4.4 or later. macOS ships bash 3.2; run `brew install bash`.
+- git and `jq`.
+- For `kit issue`, `kit status`, `kit tidy`, and `kit linked`: the command-line tool of the forge, the service that
+  hosts the repository. That is `gh` for GitHub or `glab` for GitLab.
+
+With mise, an exact version pin installs as soon as a release exists. A range pin waits one day after a release
+unless `[settings]` contains `minimum_release_age_excludes = ["github:empowerite/kit"]`.
 
 ## Take the kit
 
-- In the repository, run `kit install` with the modules it should take. `kit`, the entry file and the rules, is
-  always in; `ci-github` is the GitHub Actions workflow, `lefthook` the pre-commit linters, and `claude` the
-  Claude Code adapter. `kit install ci-github lefthook claude` takes all three, and `kit module add` takes one
-  later.
-- `install` writes the sentence every agent reads into a region of `AGENTS.md`, between a `kit:generate` line
-  and a `kit:end` line that both name the file, making the file where there is none and leaving the rest of it
-  yours, and the `/worktrees/` entry into a region of `.gitignore` the same way. Move the region where you like
-  and write what you like around it; `kit generate` makes the region what `kit region` prints, and `kit check`
-  holds it there. Any file of yours may carry a directive of its own, naming any command;
-  [docs/generate.md](docs/generate.md) says how.
-- Commit what `install` wrote.
-- Keep a gate: a `ci` recipe in the root justfile, a `ci` target in a Makefile, a `ci` script in `package.json`,
-  or any command as `gate` in `.kit/settings.yml`. The delivered check, `kit ci`, runs it with `kit check`,
-  `kit linked`, and `kit policy`, from the delivered workflow or from any pipeline of your own, and refuses when
-  there is none. The gate runs with the tools your toolchain manages, mise, Homebrew, or a container image; see
-  [docs/toolchains.md](docs/toolchains.md). The naming policy is in [docs/policy.md](docs/policy.md).
-- Run the linters before a commit. `kit lint` runs each rule's own linter over the staged paths with no hook
-  manager at all. The `lefthook` module wires lefthook to it: pin `lefthook`, put `extends: [.kit/lefthook.yml]`
-  in `lefthook.yml`, and run `lefthook install` once per clone. `kit check` refuses until that line is there,
-  and the kit never writes it for you.
-
-`claude` is the adapter for Claude Code, which reads `AGENTS.md` only as a fallback, when no `CLAUDE.md` is present.
-The module places a region in `.claude/CLAUDE.md` importing `AGENTS.md`, so Claude reads what every agent reads in
-every case, and the rest of that file is yours. A repository with no adapter still binds every agent that reads
-`AGENTS.md`. `kit module list`, `kit module add`, and `kit module remove` show and change the set, and
-[docs/modules.md](docs/modules.md) describes a module.
-
-Before an agent creates or changes a file, it asks `kit context "${path}"` which rules govern it;
-[docs/context.md](docs/context.md) describes the call and the Claude Code hook that makes it for the agent.
-
-To move to a new release, bump the pin or reinstall, then run `kit update`. A delivered file you left alone is
-replaced. One you edited is three-way merged with the previous release as the base, which `update` fetches from
-GitHub when it is not on the machine; `KIT_BASE` names a copy of it where that fetch is not possible. Your own
-deny entries and settings keys stay. `kit check` fails, locally and in CI, when a delivered file differs from
-the pinned release.
+1. Run `kit install` with the modules you want. The `kit` module (the entry file and the rules) is always
+   installed. The optional modules are:
+
+   | Module | Delivers |
+   | --- | --- |
+   | `ci-github` | the GitHub Actions workflow that runs `kit ci` |
+   | `lefthook` | a pre-commit hook that runs `kit lint` |
+   | `claude` | the Claude Code adapter |
+   | `policy-opa` | the naming policy as Open Policy Agent rules |
+
+   `kit install ci-github lefthook claude` takes three of them. `kit module add` adds one later.
+
+   `install` also writes a line into `AGENTS.md` telling every agent to read `.kit/1st.md`, and adds `/worktrees/`
+   to `.gitignore`. Each sits in a region between a `kit:generate` line and a `kit:end` line. The rest of each file
+   is yours, and you can move the region anywhere in it. `kit generate` rewrites a region from its command, and
+   `kit check` fails when a region is out of date. Your own files can contain regions too; see
+   [docs/generate.md](docs/generate.md).
+2. Commit what `install` wrote.
+3. Give the repository a gate, the command that CI runs. kit looks for one of these:
+   - a `ci` recipe in the root justfile
+   - a `ci` target in a Makefile
+   - a `ci` script in `package.json`
+   - any command, set as `gate` in `.kit/settings.yml`
+
+   `kit ci` runs the gate together with `kit check`, `kit linked`, and `kit policy`, and fails when there is no gate.
+   The gate runs with the tools your toolchain manages; see [docs/toolchains.md](docs/toolchains.md). The naming
+   policy is described in [docs/policy.md](docs/policy.md).
+4. Run the linters before each commit. `kit lint` lints the staged files and needs no hook manager. To run it from
+   lefthook instead:
+   - pin `lefthook`,
+   - add `extends: [.kit/lefthook.yml]` to `lefthook.yml`, and
+   - run `lefthook install` once per clone.
+
+   With the `lefthook` module installed, `kit check` fails until `lefthook.yml` has that `extends` line. kit never
+   writes it for you.
+
+Claude Code reads `AGENTS.md` only when there is no `CLAUDE.md`. The `claude` module adds a region to
+`.claude/CLAUDE.md` that imports `AGENTS.md`, so Claude always reads the same instructions as every other agent. The
+rest of `.claude/CLAUDE.md` is yours. Without the module, any agent that reads `AGENTS.md` still gets the rules.
+
+`kit module list`, `kit module add`, and `kit module remove` show and change the installed modules. The module format
+is in [docs/modules.md](docs/modules.md).
+
+### Working with the rules
+
+- Before an agent changes a file, it runs `kit context "${path}"` to find the rules that apply. The `claude` module
+  makes this call automatically through a Claude Code hook; see [docs/context.md](docs/context.md).
+- `kit new file "${path}"` creates a file from its rule's template, and `kit lint` checks that every file keeps the
+  shape of a template; see [docs/templates.md](docs/templates.md).
+
+### Updating
+
+Bump the pin or reinstall, then run `kit update`:
+
+- A delivered file you never edited is replaced.
+- A delivered file you edited is merged three ways, with the previous release as the base. `kit update` downloads
+  the previous release from GitHub when it is not on the machine. Where it cannot, set `KIT_BASE` to a copy of it.
+- Your own deny list entries and settings keys are kept.
+
+`kit check` fails, locally and in CI, when a delivered file differs from the pinned release.
 
 ## Setup
 
-The sections from here on are about working on this repository, the kit's own source, which uses its own kit.
+The rest of this README is about working on this repository, which is the kit's own source and also uses the kit.
 
-Its tools come from mise. Every commit is signed, and the branch ruleset refuses one that is not. If you have no
-signing key GitHub verifies, make one and register it, following these two pages, then run the commands below
-once per clone, with the key's id in `signing_key`:
+Tools come from mise. Every commit must be signed; the branch ruleset rejects unsigned commits. If you have no signing
+key that GitHub verifies, create and register one:
 
 - [generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key)
 - [adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account)
 
+Then, once per clone, with the key's id in `signing_key`:
+
 ```sh
 git config gpg.format openpgp
 git config user.signingkey "${signing_key}"
@@ -123,63 +163,80 @@ mise install
 lefthook install
 ```
 
-`MISE_ENV=desk` belongs in your shell profile: it makes mise read `mise.desk.toml`, the tools only a desk runs,
-on top of `mise.toml`. The delivered `CI` job sets `MISE_ENV=ci` the same way, for a `mise.ci.toml` where a
-repository has one.
+Put `export MISE_ENV=desk` in your shell profile. It makes mise read `mise.desk.toml`, the tools only a developer
+machine needs, on top of `mise.toml`. The delivered CI job sets `MISE_ENV=ci` the same way, for repositories that have
+a `mise.ci.toml`.
 
 ## Getting started
 
-Work here moves by the loop in [.kit/1st.md](.kit/1st.md):
+Work here follows the workflow in [.kit/1st.md](.kit/1st.md):
 
-- An issue exists. A change without an issue has not started.
-- `kit issue <N>` makes `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens a
-  draft pull request. It never switches the checkout it runs from. An issue in another tracker is named by its
-  own reference, `kit issue AB#4521` for an Azure DevOps work item; [docs/trackers.md](docs/trackers.md) says how a
-  repository declares one.
-- Work happens in that worktree. Commits are signed, and their subject is `#<N> <area>: <subject>`. `kit rebase`
-  brings the branch up to date with `main` and pushes it, and `kit status` shows every pull request in flight
-  and the worktree it is written in.
-- `just ci` is the gate; the justfile says what it runs.
-- `gh pr ready` says the work is done, and the pull request body is the report.
-- A human merges. `kit tidy` then removes the worktree and its branch.
+1. Start from an issue. A change without an issue has not started.
+2. Run `kit issue <N>`. It creates `worktrees/<N>-<slug>`, links the branch to the issue under Development, and opens
+   a draft pull request. It never switches the branch of the checkout you run it from. For an issue in another
+   tracker, use that tracker's reference, such as `kit issue AB#4521` for an Azure DevOps work item; see
+   [docs/trackers.md](docs/trackers.md).
+3. Work in that worktree. Commits are signed, with the subject `#<N> <area>: <subject>`.
+   - `kit rebase` rebases the branch onto `main` and pushes it.
+   - `kit status` shows every open pull request and the worktree it lives in.
+4. Run the gate, `just ci`. The justfile lists what it runs.
+5. Run `gh pr ready` when the work is done. The pull request body is the report.
+6. A human merges. Then `kit tidy` removes the worktree and its branch.
 
 ## Maintaining
 
-The release is the checkout: `bin/` is the machinery, `modules/` is everything delivered, and `docs/` with each
-module's `docs/` is the documentation. [docs/architecture.md](docs/architecture.md) is the shape of the whole, with
-its figures, and [docs/modules.md](docs/modules.md) is the module format.
+| Directory | Contents |
+| --- | --- |
+| `bin/` | the `kit` command and its verbs |
+| `modules/` | everything a release delivers |
+| `docs/`, `modules/*/docs/` | the documentation |
+
+[docs/architecture.md](docs/architecture.md) describes how the pieces fit, with diagrams.
+[docs/modules.md](docs/modules.md) describes the module format.
 
-The installed copies are written by `bin/kit install` and not edited by hand:
+This repository installs its own kit. The installed copies are written by `bin/kit install`; do not edit them by hand:
 
 | Installed copy | Written from |
 | --- | --- |
 | `.kit/1st.md`, `.kit/rules/`, `.kit/settings.schema.json` | `modules/kit/files/repo/.kit/` |
 | `.kit/lefthook.yml` | `modules/lefthook/files/repo/.kit/lefthook.yml` |
-| `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` answered |
-| `.claude/CLAUDE.md` | `modules/claude/regions/repo/.claude/CLAUDE.md`, a region `kit region` fills; the rest of the file is the repository's |
+| `.github/workflows/kit-ci.yml` | `modules/ci-github/templates/repo/.github/workflows/kit-ci.yml`, with `ci_runner` filled in |
+| `.claude/CLAUDE.md` | `modules/claude/regions/repo/.claude/CLAUDE.md`, a region; the rest of the file belongs to this repository |
 | `.claude/settings.json` | `modules/claude/files/repo/.claude/settings.json`, merged by key; here only the kit's entries |
-| `AGENTS.md`, `.gitignore` | `modules/kit/regions/repo/`, regions `kit region` fills; the rest of each file is the repository's |
+| `AGENTS.md`, `.gitignore` | `modules/kit/regions/repo/`, regions; the rest of each file belongs to this repository |
 | `.kit/manifest` | the release version (`unreleased` here), the active modules, and a digest per delivered path |
 
-`.kit/settings.yml` is this repository's own.
+`.kit/settings.yml` belongs to this repository and is not delivered.
+
+When a commit changes a file under `modules/`, the installed copies must change in the same commit:
+
+- With the pre-commit hook installed, this happens automatically: the hook runs `just refresh`, which regenerates the
+  copies from the index and stages them.
+- Without the hook, stage your change, run `just refresh`, and commit.
 
-A commit that changes a file under `modules/` rewrites the installed copies in the same commit: the pre-commit
-hook runs `just refresh`, which regenerates them from the index and stages the result. On a desk without the
-hook, stage the change, run `just refresh`, and commit. `bin/kit check`, which `just ci` runs, names any installed
-copy that does not match its source. Each delivered whole file says in its header that it is delivered by kit; a
-region's directive is its notice, and this table is `settings.json`'s.
+`bin/kit check`, which `just ci` runs, names any installed copy that does not match its source. Each delivered file
+says in its header that kit delivered it. A region's `kit:generate` line serves as its notice, and the table above
+serves as the notice for `settings.json`.
 
 ## Release
 
-A release is the tag `release/<version>` on a commit on `main`, not only its head. A pre-release is
-`release/<version>-<suffix>`, say `release/0.1.0-rc.1`, on a commit that is not on `main`, and it is published as a
-GitHub pre-release. The tag is the version: the repository carries no version file, the workflow stamps the part after
-`release/` into the packed kit and names the release by it, and a published release is immutable, so a tag is never
-reused. The workflow is two kit commands: `kit release verify`, which refuses a tag that is not `release/` and a
-version, a release tag off `main`, and a pre-release tag on `main`; and `kit release publish`, which packs `bin/`,
-`modules/`, and `version` into `kit-<version>.tar.gz` and publishes the release. `kit release pack` makes the same
-tarball on a desk, and `kit release publish` refuses a release tag anywhere but on the runner, so a release is published
-by the workflow and nowhere else; a desk may publish a pre-release. A release is permanent. A pre-release is retired,
-tag and all, when the branch it was tagged on is deleted and no other branch reaches its commit.
+- A release is the tag `release/<version>` on any commit on `main`, not only the latest one.
+- A pre-release is `release/<version>-<suffix>`, such as `release/0.1.0-rc.1`, on a commit that is not on `main`.
+  It is published as a GitHub pre-release.
+- The tag is the version. The repository has no version file. The release workflow writes the part after `release/`
+  into the packed kit and names the release after it.
+- Published releases are immutable, so a tag is never reused.
+
+The release workflow runs two commands:
+
+1. `kit release verify` rejects a tag that is not `release/<version>`, a release tag on a commit not on `main`, and a
+   pre-release tag on a commit on `main`.
+2. `kit release publish` packs `bin/`, `modules/`, and `version` into `kit-<version>.tar.gz` and publishes it.
+
+`kit release pack` builds the same tarball locally. `kit release publish` refuses to publish a release anywhere but
+the CI runner, so only the workflow publishes releases. A pre-release can be published from a developer machine.
+
+A release is permanent. A pre-release is deleted, tag and all, once the branch it was tagged on is deleted and no
+other branch contains its commit.
 
 The branch ruleset is managed in [empowerite/infrastructure](https://github.com/empowerite/infrastructure).
diff --git a/bin/1st.sh b/bin/1st.sh
index 2defc35..28cdb5b 100644
--- a/bin/1st.sh
+++ b/bin/1st.sh
@@ -2,19 +2,22 @@
 # 1st.sh - the kit's bash loader: output verbs, guards, and lazy module loading (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Sourced by every verb, bin/kit-<verb>.sh, which bin/kit dispatches to with kit_root exported. It defines
-# functions only and sets no shell option, so the caller's options stand. A module is a sourced <module>.sh
-# beside this file, loaded once with `use <module>` by the verb or module that needs it. A verb is an executable
-# kit-<verb>.sh beside it.
+# Every verb, bin/kit-<verb>.sh, sources this file. bin/kit runs the verb with kit_root exported. This file only
+# defines functions and sets no shell options, so the caller's options stay in effect.
 #
-# Every message goes to stderr, so stdout stays clean for data. Color is off when stderr is not a terminal or
-# NO_COLOR is set. Under GitHub Actions, warn and error also emit the matching workflow command.
+#   - A verb is an executable kit-<verb>.sh in this directory.
+#   - A module is a sourced <module>.sh in this directory. The verb or module that needs it loads it with
+#     `use <module>`, which sources it at most once.
+#
+# Every message goes to stderr, so stdout carries only data. Color is off when stderr is not a terminal or NO_COLOR
+# is set. Under GitHub Actions, warn and error also print the matching workflow command (::warning::, ::error::).
 
 kit_bin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 declare -gr kit_bin_dir
 declare -Ag kit_modules=([1st]=1)
 
-# use <module>… loads bin/<module>.sh once. An unknown module is a bug in the caller, so it is fatal.
+# use <module>… sources bin/<module>.sh, once per module. An unknown module is a bug in the caller: use prints an
+# error and returns 2.
 use() {
   local module
   for module in "$@"
@@ -41,8 +44,8 @@ else
   declare -gr out_color=0
 fi
 
-# ere:quote <text> prints the text with every extended-regular-expression metacharacter escaped, so it stands for
-# itself in a pattern. Done in bash, so no sed dialect decides what a bracket expression means.
+# ere:quote <text> prints the text with every extended-regular-expression metacharacter escaped, so it matches
+# literally in a pattern. It is pure bash, so BSD and GNU sed differences in bracket expressions do not matter.
 ere:quote() {
   local text=$1 out='' c i
   for (( i = 0; i < ${#text}; i++ ))
@@ -56,7 +59,7 @@ ere:quote() {
   printf '%s\n' "${out}"
 }
 
-# out:sgr <code> prints the escape for one SGR code when color is on, and nothing otherwise.
+# out:sgr <code> prints the escape sequence for one SGR code when color is on, and nothing otherwise.
 out:sgr() {
   (( out_color )) && printf '\x1b[%sm' "$1"
   return 0
@@ -86,13 +89,15 @@ error() {
   return 0
 }
 
-# summary <line>… appends lines to the runner's step summary, where there is one, and is silent elsewhere.
+# summary <line>… appends lines to the GitHub Actions step summary when GITHUB_STEP_SUMMARY is set, and does
+# nothing otherwise.
 summary() {
   [[ -n "${GITHUB_STEP_SUMMARY:-}" ]] || return 0
   printf '%s\n' "$@" >> "${GITHUB_STEP_SUMMARY}"
 }
 
-# guard:require <predicate>… returns non-zero on the first predicate that does not hold, with the remedy.
+# guard:require <predicate>… checks each predicate in order. At the first one that fails, it prints the remedy and
+# returns non-zero. The predicates:
 #   signing-key  git user.signingkey is set
 #   tool:<name>  <name> is on PATH
 guard:require() {
diff --git a/bin/context.sh b/bin/context.sh
index a57fd24..cea3df8 100644
--- a/bin/context.sh
+++ b/bin/context.sh
@@ -2,28 +2,34 @@
 # context.sh - which rules govern a file (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# context:render <path>… [--json] names the rule files under .kit/rules/ that govern each path, and records each
-# ask in the repository's context log. A rule's frontmatter declares what it governs: `paths:`, globs matched
-# against the repository-relative path, where ** stands for any depth; and `content:`, patterns matched against
-# the first line of a file that exists, so a bash script with no extension is bash by its shebang. The rules are
-# discovered here and copied nowhere, which is what lets every harness, and every person, find them the same way.
+# context:render <path>… [--json] prints the rule files under .kit/rules/ that govern each path. It also logs each
+# request in the repository's context log. A rule's frontmatter declares what it governs:
 #
-# context:claude is the same answer in Claude Code's hook protocol: the hook input on stdin, the rules' paths as
-# additional context on stdout. It names, never quotes: reading the rule stays the agent's own act, one a hook on
-# Read can record. docs/context.md is the description.
+#   - `paths:` globs matched against the repository-relative path, where ** matches any depth
+#   - `content:` patterns matched against the first line of a file that exists, so a bash script with no extension
+#     is matched by its shebang
+#
+# The rules are found where they are and copied nowhere, so every harness and every person finds them the same way.
+#
+# context:claude gives the same answer in Claude Code's hook protocol. It reads the hook input on stdin and prints
+# the rules' paths as additional context on stdout. It names the rules but does not quote them, so the agent still
+# reads each rule itself, and a hook on Read can record that.
+#
+# see: docs/context.md
 
 use yaml
 shopt -s extglob
 
-# context:log-path prints where every ask is recorded: under the repository's git directory, shared by its worktrees.
+# context:log-path prints the path of the context log. It is under the repository's common git directory, so every
+# worktree shares it.
 context:log-path() {
   printf '%s/kit/context.log\n' "$(git rev-parse --path-format=absolute --git-common-dir)"
 }
 
-# context:relative <path> prints <path> relative to the repository root. A relative path is taken from the
-# directory the command was typed in, which bin/kit exports as kit_invoked_in before it moves to the root. The
-# nearest directory of the path that exists is resolved physically, as git reports the root, so a path through a
-# symlinked directory, or to a file not yet created, still cuts at the root.
+# context:relative <path> prints <path> relative to the repository root. A relative <path> starts from the
+# directory the command was typed in, which bin/kit exports as kit_invoked_in before it changes to the root. The
+# nearest existing directory in the path is resolved physically (pwd -P), the way git reports the root. So a path
+# through a symlinked directory, or to a file not yet created, still comes out relative to the root.
 context:relative() {
   local path=$1 root dir rest
   root=$(git rev-parse --show-toplevel)
@@ -40,9 +46,9 @@ context:relative() {
   printf '%s\n' "${path#"${root}"/}"
 }
 
-# context:glob-matches <path> <glob> is true when the repository-relative path matches the glob. ** stands for any
-# depth, and a lone * also crosses directories, as bash's [[ == ]] has it: *.md governs every depth, while a glob
-# with no wildcard, such as justfile, names one path.
+# context:glob-matches <path> <glob> is true when the repository-relative path matches the glob. ** matches any
+# depth. A lone * also matches across directories, as in bash's [[ == ]], so *.md matches at every depth. A glob
+# with no wildcard, such as justfile, matches one path.
 context:glob-matches() {
   local path=$1 glob=$2
   glob=${glob//\*\*\//*(*\/)}
@@ -51,14 +57,14 @@ context:glob-matches() {
   [[ "${path}" == ${glob} ]]
 }
 
-# context:rules <path> prints the rule files governing <path>, by its path or by its first line.
+# context:rules <path> prints each rule file that governs <path>, by a `paths:` glob or a `content:` pattern.
 context:rules() {
   local path=$1 rule glob pattern first=''
   [[ -f "${path}" ]] && first=$(head -n 1 "${path}" 2>/dev/null || true)
   for rule in .kit/rules/*.md
   do
     [[ -f "${rule}" ]] || continue
-    # Read, never word-split: an unquoted glob would be expanded against the working tree before it is matched.
+    # Read each glob with read, not word splitting: an unquoted glob would expand against the working tree first.
     while IFS= read -r glob
     do
       [[ -n "${glob}" ]] || continue
@@ -81,7 +87,7 @@ context:rules() {
   done
 }
 
-# context:log <path> records that the context of <path> was asked for.
+# context:log <path> appends the time and <path> to the context log, recording that its rules were requested.
 context:log() {
   local log
   log=$(context:log-path)
@@ -89,8 +95,8 @@ context:log() {
   printf '%s\t%s\n' "$(date +%s)" "$1" >> "${log}"
 }
 
-# context:render <path>… [--json] prints the rules governing the paths: once each, as paths to read; with --json,
-# one object per path with its rules.
+# context:render <path>… [--json] logs each path and prints the rules that govern the paths. Without --json, it
+# prints each rule's path once. With --json, it prints one object per path with its rules.
 context:render() {
   local json=false arg path rule
   local -a paths=()
@@ -131,9 +137,9 @@ context:render() {
   done
 }
 
-# context:claude reads Claude Code's PreToolUse hook input on stdin and answers with the rules governing the file
-# the tool is about to write, as additional context naming each rule's path. A tool input with no file path, or
-# a file no rule governs, gets no answer.
+# context:claude reads Claude Code's PreToolUse hook input on stdin and logs the file the tool is about to write.
+# It prints, as additional context, the paths of the rules that govern that file. It prints nothing when the tool
+# input has no file path or no rule governs the file.
 context:claude() {
   local input path rules text=''
   input=$(cat)
diff --git a/bin/forge-github.sh b/bin/forge-github.sh
index dee415a..bedd98e 100644
--- a/bin/forge-github.sh
+++ b/bin/forge-github.sh
@@ -1,13 +1,15 @@
 # shellcheck shell=bash
-# shellcheck disable=SC2016  # jq filters and GraphQL queries name their variables with $, in single quotes on purpose
-# forge-github.sh - GitHub, through gh, as the forge the loop runs on (sourced module)
+# forge-github.sh - the GitHub forge provider, through the gh CLI (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
+# shellcheck disable=SC2016  # jq filters and GraphQL queries name their variables with $, in single quotes on purpose
 #
-# The provider bin/forge.sh loads for a repository whose forge is github. Every call is one of the names the
-# seam's header lists; gh is this file's requirement and nobody else's.
+# bin/forge.sh loads this provider when the repository's forge is github. It implements the calls listed in the
+# header of bin/forge.sh. Only this file requires gh.
+#
+# see: bin/forge.sh
 
-# forge-github:require refuses where gh is absent or not authenticated. A revoked token passes `gh auth status`,
-# so the probe is a real call.
+# forge-github:require fails when gh is missing or not authenticated. It makes a real API call, because
+# `gh auth status` passes with a revoked token.
 forge-github:require() {
   guard:require tool:gh || return 1
   if ! gh api user --jq '.login' >/dev/null 2>&1
@@ -65,13 +67,14 @@ forge-github:issue-assign() {
   gh issue edit "$1" --add-assignee "$2" >/dev/null 2>&1
 }
 
-# The branch is found by an open pull request's head, so a second run never forks a <N>-<slug>-1 duplicate.
+# Find the branch through an open pull request's head branch, so a second run never creates a duplicate
+# <N>-<slug>-1 branch.
 forge-github:branch-for-issue() {
   gh pr list --state open --json headRefName \
     --jq "[.[] | select(.headRefName | test(\"^$1-\"))] | .[0].headRefName // empty" 2>/dev/null || true
 }
 
-# gh issue develop names the branch <N>-<slug> itself, links it under Development, and pushes it.
+# gh issue develop names the branch <N>-<slug>, links it to the issue under Development, and pushes it.
 forge-github:link-branch() {
   gh issue develop "$1" --base "$2" >/dev/null
 }
@@ -102,7 +105,8 @@ forge-github:pr-state-for-branch() {
   gh pr list --head "$1" --state all --json state --jq '.[0].state // empty' 2>/dev/null || true
 }
 
-# On a runner the event names the pull request; on a desk the current branch does.
+# On a GitHub Actions runner, the event payload gives the pull request. Otherwise gh finds the pull request for
+# the current branch.
 forge-github:pr-here() {
   local number=''
   if [[ -n "${GITHUB_EVENT_PATH:-}" ]]
@@ -130,9 +134,16 @@ forge-github:pr-closing-issues() {
     || { error "run: gh auth status (pull request #$1 could not be read)"; return 1; }
 }
 
-# One request: every open pull request with the issues it closes, its review threads, and the checks on its
-# head, folded into the document kit status draws: number, ref, branch, title, author, createdAt, age in seconds,
-# state, checks {state, passed, total, failing, took in seconds or null}, unresolved, and closes [{number, title}].
+# forge-github:open-prs makes one GraphQL request for every open pull request, with the issues it closes, its
+# review threads, and the checks on its head commit. It prints one JSON object per pull request, the document
+# kit status renders. The fields:
+#
+#   number, ref, branch, title, author, createdAt
+#   age         seconds since the pull request was created
+#   state       draft, queued, conflicted, failing:gate, no-check, comments:open, blocked:approval, or ready
+#   checks      {state, passed, total, failing, took}, where took is in seconds or null
+#   unresolved  the number of unresolved review threads
+#   closes      [{number, title}] of the issues it closes
 forge-github:open-prs() {
   local repo query filter
   repo=$(forge-github:repo) || return 1
diff --git a/bin/forge-gitlab.sh b/bin/forge-gitlab.sh
index 234dfc3..1d0e14c 100644
--- a/bin/forge-gitlab.sh
+++ b/bin/forge-gitlab.sh
@@ -1,24 +1,35 @@
 # shellcheck shell=bash
-# shellcheck disable=SC2016  # jq filters name their variables with $, in single quotes on purpose
-# forge-gitlab.sh - GitLab, through glab, as the forge the loop runs on (sourced module)
+# forge-gitlab.sh - the GitLab forge provider, through the glab CLI (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
+# shellcheck disable=SC2016  # jq filters name their variables with $, in single quotes on purpose
+#
+# bin/forge.sh loads this provider when the repository's forge is gitlab:
+#
+#   - gitlab.com, detected from origin's host
+#   - a self-hosted GitLab, set with `forge: gitlab` in .kit/settings.yml; glab finds the host from origin
+#
+# It implements the calls listed in the header of bin/forge.sh, with the same output as the GitHub provider. The
+# GitLab equivalents:
 #
-# The provider bin/forge.sh loads for a repository whose forge is gitlab: gitlab.com by origin's host, or any
-# self-hosted GitLab by `forge: gitlab` in .kit/settings.yml, glab finding the host from origin as it does. Every
-# call is one of the names the seam's header lists, and answers in the same shape the GitHub provider does: a
-# merge request is the change, its iid the number, its pipeline's jobs the checks, its resolvable discussions the
-# review threads. glab is this file's requirement and nobody else's; the REST API is read through `glab api`, and
-# every document is folded here with jq, so the provider's logic is this file's and a test can drive it.
-
-# forge-gitlab:project prints the project's path with namespace, from origin: group/subgroup/name.
+#   pull request    a merge request
+#   number          the merge request's iid
+#   checks          the jobs of its pipeline
+#   review threads  its resolvable discussions
+#
+# Only this file requires glab. It reads the REST API through `glab api` and builds every result here with jq, so
+# all of the provider's logic is in this file and a test can drive it.
+#
+# see: bin/forge.sh
+
+# forge-gitlab:project prints the project's full path, read from origin: group/subgroup/name.
 forge-gitlab:project() {
   local url
   url=$(git remote get-url origin 2>/dev/null) || { error "this checkout has no origin; add one"; return 1; }
   sed -E 's#^[a-z]+://[^/]+/##; s#^[^@/]+@[^:]+:##; s#\.git$##' <<<"${url}"
 }
 
-# forge-gitlab:api <path-under-the-project> [<glab api option>…] calls the REST API under the project, its path
-# encoded the way GitLab takes it in a URL.
+# forge-gitlab:api <path-under-the-project> [<glab api option>…] calls the REST API under the project, with the
+# project's path URL-encoded as GitLab expects.
 forge-gitlab:api() {
   local path=$1 project
   shift
@@ -89,8 +100,8 @@ forge-gitlab:branch-for-issue() {
     || true
 }
 
-# GitLab has no command that makes a branch for an issue, so the branch is made the way its issue page would make
-# it, <iid>-<slug of the title>, from the default branch; GitLab links a branch named so to the issue.
+# GitLab has no command that creates a branch for an issue. This creates the branch the issue page would:
+# <iid>-<slug of the title>, from the default branch. GitLab links a branch with that name to the issue.
 forge-gitlab:link-branch() {
   local title slug
   title=$(forge-gitlab:issue-title "$1") || return 1
@@ -130,7 +141,8 @@ forge-gitlab:pr-state-for-branch() {
     || true
 }
 
-# On a runner the pipeline names the merge request; on a desk the current branch does.
+# On a GitLab CI runner, CI_MERGE_REQUEST_IID gives the merge request. Otherwise it is the open merge request for
+# the current branch.
 forge-gitlab:pr-here() {
   local number=${CI_MERGE_REQUEST_IID:-} branch
   if [[ -z "${number}" ]]
@@ -148,10 +160,14 @@ forge-gitlab:pr-closing-issues() {
     || { error "run: glab auth status (merge request !$1 could not be read)"; return 1; }
 }
 
-# Every open merge request folded into the document kit status draws, the GitHub provider's shape: number, ref,
-# branch, title, author, createdAt, age, state, checks {state, passed, total, failing, took}, unresolved, closes.
-# GitLab's REST API spreads these over four reads per merge request: the request, its pipeline's jobs, its
-# discussions, and the issues it closes.
+# forge-gitlab:open-prs prints one JSON object per open merge request, the document kit status renders. The fields
+# match forge-github:open-prs: number, ref, branch, title, author, createdAt, age, state, checks {state, passed,
+# total, failing, took}, unresolved, and closes. GitLab's REST API needs four reads per merge request:
+#
+#   - the merge request
+#   - its pipeline's jobs
+#   - its discussions
+#   - the issues it closes
 forge-gitlab:open-prs() {
   local list iid mr jobs discussions closes pipeline
   list=$(forge-gitlab:api "merge_requests?state=opened&per_page=100&order_by=created_at&sort=asc" 2>/dev/null) \
diff --git a/bin/forge.sh b/bin/forge.sh
index d7b701b..50aa6d6 100644
--- a/bin/forge.sh
+++ b/bin/forge.sh
@@ -1,15 +1,20 @@
 # shellcheck shell=bash
-# forge.sh - the loop's seam over the forge that hosts the repository (sourced module)
+# forge.sh - one interface to the forge (GitHub, GitLab) that hosts the repository (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The loop speaks of an issue, a branch linked to it, a pull request, its checks and review threads and linked
-# issues. Every verb that needs one asks here, by these names, and a provider answers: forge-<name>.sh beside this
-# file, its functions named forge-<name>:<call>. The provider is the `forge` setting in .kit/settings.yml, else
-# the one origin's host names. The core verbs never come here, so a repository on no forge still installs,
-# updates, checks, and runs kit context and kit lint.
+# Verbs that read or change issues, branches, and pull requests call forge:<call> here. Each call is passed to a
+# provider, forge-<name>.sh in this directory, whose functions are named forge-<name>:<call>.
 #
-# A provider answers these calls, each printing its result on stdout and failing with a remedy on stderr, or
-# printing nothing where the call says so:
+# The provider is chosen by:
+#
+#   1. the `forge` setting in .kit/settings.yml, if set
+#   2. otherwise origin's host: github.com is github, gitlab.com is gitlab
+#
+# kit install, update, check, context, and lint never call the forge, so they work in a repository that has no
+# forge.
+#
+# Every provider implements the calls below. Each prints its result on stdout. On failure it prints a remedy on
+# stderr. A call marked "or nothing" prints nothing when there is no match.
 #
 #   require                       the provider's own tool is present and authenticated
 #   repo                          the repository as owner/name
@@ -33,13 +38,15 @@
 #   pr-here                       the number of the pull request this checkout is working on, or nothing
 #   pr-closing-issues <n>         one line per issue the pull request closes: "<number> <state> <owner/name>"
 #   open-prs                      one JSON object per open pull request, the documents kit status draws
+#
+# see: docs/architecture.md
 
 use release
 
 # forge:provider prints the provider's name: the forge setting, else github for an origin at github.com and
-# gitlab for one at gitlab.com. A self-hosted forge is named by the setting. It fails, naming the remedy, where
-# neither names a provider the kit carries. One origin is one forge: a repository on two is a mirror or a
-# migration, and the setting says which one the loop runs on.
+# gitlab for one at gitlab.com. A self-hosted forge needs the setting. It fails with a remedy when neither gives
+# a provider the kit has. A repository hosted on two forges (a mirror, or mid-migration) uses the setting to pick
+# one.
 forge:provider() {
   local provider host=''
   provider=$(release:setting forge)
diff --git a/bin/generate.sh b/bin/generate.sh
index 4d5ad00..8c24f10 100644
--- a/bin/generate.sh
+++ b/bin/generate.sh
@@ -1,61 +1,80 @@
 # shellcheck shell=bash
+# generate.sh - fill each kit:generate region with its command's output, until nothing changes (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
 # shellcheck disable=SC2016  # the $ in a pattern anchors a line; nothing is meant to expand
-# generate.sh - a directive opens a named region a command fills, expanded to a fixed point (sourced module)
-# ----------------------------------------------------------------------------------------------------------------------
 #
-# A line that is `kit:generate <name>`, or `kit:generate <name> `<command>``, with nothing but non-alphanumeric
-# characters before and after it, opens a region; a line that is `kit:end <name>` framed the same way closes it.
-# So the directive sits in any comment syntax, and is read without knowing one: `#`, `//`, `--`, `;`, `%`, `'`,
-# `<!-- -->`, `/* */`, and whatever else a language frames a comment with, since every such frame is punctuation,
-# and a line of prose has letters before the marker. The directive and the end marker stay; the command's
-# standard output replaces the lines between them. With no command, the command is `kit region`, which reads the
-# region's name as the path of a region an active module delivers.
+# A region starts at a directive line and ends at an end line:
+#
+#   - opened by a line that is `kit:generate <name>`, or `kit:generate <name> `<command>``
+#   - closed by a line that is `kit:end <name>`
+#
+# Only non-alphanumeric characters may come before or after the marker on its line. So a directive works inside
+# any comment syntax without the kit knowing that syntax: `#`, `//`, `--`, `;`, `%`, `'`, `<!-- -->`, `/* */`,
+# and any other, since comment delimiters are punctuation. A line of prose has letters before the marker, so it is
+# not read at all.
+#
+# The directive and end lines stay. The command's standard output replaces the lines between them. With no
+# command, the command is `kit region`, which reads the region's name as the path of a region an active module
+# delivers.
+#
+# The command is a bash command line, pipes included. It runs:
 #
-# The command is a bash command line, pipes and all, run from the repository root with the running kit's bin/
-# first on PATH, stdin closed, errexit and pipefail on, and the file and the region's name exported as
-# KIT_GENERATE_FILE and KIT_GENERATE_REGION. A literal backtick is the one thing a command cannot carry; $() does.
+#   - from the repository root
+#   - with the running kit's bin/ first on PATH
+#   - with stdin closed
+#   - with errexit and pipefail on
+#   - with KIT_GENERATE_FILE and KIT_GENERATE_REGION set to the file and the region's name
 #
-# Every unit is balanced on its own: the file as written, and each command's output. An output may open regions
-# of its own, each closed in that same output, and they are expanded in turn, depth first, so a region nests and
-# one pass settles a file. An output that closes a region it did not open, or opens one it does not close, holds
-# the file. A line that opens with the marker and is not a directive holds the file too, so a misspelled one is
-# never silently skipped; a line of prose, with letters before the marker, is not read at all. In markdown, a
-# fenced code block is not live, so a page may show a directive whole, and a fence that opens and never closes,
-# in the file or in an output, is refused, since the directives after it could not be read.
+# A command cannot contain a literal backtick. Use $() instead.
 #
-# A file is rewritten only on a clean expansion. A command that fails, an unbalanced unit, a malformed marker, a
-# name opened twice, or a conflict marker in the file leaves the file as it was and fails the run, naming the
-# file and the line.
+# The file and each command's output are expanded as separate units, and each must be balanced on its own. An
+# output may open regions of its own if it also closes them. Those regions are expanded in turn, depth first, so
+# regions can nest and one pass settles a file. In markdown, directives inside a fenced code block are ignored, so
+# a page can show a directive as an example.
+#
+# The file is rewritten only when the whole expansion succeeds. Otherwise the file is left unchanged and the run
+# fails, naming the file and the line. The run fails when:
+#
+#   - a command fails
+#   - a unit closes a region it did not open, or opens one it does not close
+#   - a line starts with the marker but is not a valid directive, so a misspelled directive is never silently
+#     skipped
+#   - a region name is opened twice
+#   - in markdown, a fenced code block opens and never closes (in the file or in an output), since the directives
+#     after it could not be read
+#   - the file contains an unresolved conflict marker
 #
 # see: bin/kit-generate.sh, bin/kit-region.sh, docs/generate.md
 
-# The marker's shapes. A line is read as a directive only when nothing but non-alphanumeric characters frames it:
-# the comment opener before, the comment closer after. The name is any run without whitespace or a backtick,
-# the command everything between the first backtick after the name and the last one before the closer.
+# The directive patterns. A line is a directive only when nothing but non-alphanumeric characters (the comment
+# opener and closer) come before and after the marker. The name is any run of characters without whitespace or a
+# backtick. The command is everything between the first backtick after the name and the last backtick on the line.
 declare -g generate_open_re='^[^[:alnum:]]*kit:generate[[:space:]]+([^[:space:]`]+)([[:space:]]+`(.+)`)?[^[:alnum:]]*$'
 declare -g generate_end_re='^[^[:alnum:]]*kit:end[[:space:]]+([^[:space:]`]+)[^[:alnum:]]*$'
-# A line that opens with a marker is a directive or an error, never prose.
+# A line that starts with a marker must be a valid directive, or it is an error. It is never read as prose.
 declare -g generate_marker_re='^[^[:alnum:]]*kit:(generate|end)([^[:alnum:]]|$)'
 declare -g generate_fence_re='^[[:space:]]*(```|~~~)'
 
-# An unresolved conflict's shape: a line of seven < or > alone or followed by git's label. The middle marker,
-# seven =, is also a markdown heading underline and is never written without the opening one, so it is not read.
+# An unresolved merge conflict: a line of seven < or seven >, alone or followed by git's label. The middle marker
+# (seven =) is not matched: it is also a markdown heading underline, and git never writes it without the opening one.
 declare -g generate_conflict_re='^(<{7}|>{7})([[:space:]].*)?$'
 
-# generate:carries <file> is true when the file has a line that opens with a marker.
+# generate:carries <file> is true when the file has a line that starts with a marker. Files under .kit/templates/
+# never count: a template is the skeleton of a file, and its directive belongs to the file made from it.
 generate:carries() {
-  [[ -f "$1" ]] && grep --quiet --extended-regexp "${generate_marker_re}" "$1"
+  [[ -f "$1" && ! "$1" =~ (^|/)\.kit/templates/ ]] && grep --quiet --extended-regexp "${generate_marker_re}" "$1"
 }
 
-# generate:markdown <file> is true for a markdown file, the one kind where a fenced code block is not live.
+# generate:markdown <file> is true for a markdown file (.md or .markdown), the only kind where fenced code blocks
+# are skipped.
 generate:markdown() {
   [[ "$1" == *.md || "$1" == *.markdown ]]
 }
 
-# generate:discover [<path>…] prints every file under the paths, or the whole repository, that carries a
-# directive: tracked files and untracked ones git does not ignore, so a file install just wrote counts before
-# it is added. A named file is printed when it carries one, wherever it is.
+# generate:discover [<path>…] prints every file that contains a directive. With no paths, it searches tracked
+# files and untracked files git does not ignore, so a file kit install just wrote counts before it is added. With
+# paths, it prints each named file that contains a directive, wherever it is.
 generate:discover() {
   local path
   if (( $# == 0 ))
@@ -73,7 +92,7 @@ generate:discover() {
   return 0
 }
 
-# generate:target <file> prints the file a write lands in: the file, or what a symlink there points at.
+# generate:target <file> prints the file a write goes to: <file> itself, or the target of a symlink at <file>.
 generate:target() {
   if [[ -L "$1" ]]
   then readlink -f "$1"
@@ -81,8 +100,8 @@ generate:target() {
   fi
 }
 
-# generate:command <file> <where> <line> <name> <command> <out> runs one region's command with its stdout in
-# <out>; a failure is named by <where> and the line, the unit the directive is in.
+# generate:command <file> <where> <line> <name> <command> <out> runs one region's command and writes its stdout
+# to <out>. On failure it prints an error naming <where> and <line> (the unit and line of the directive).
 generate:command() {
   local file=$1 where=$2 number=$3 name=$4 command=$5 out=$6
   if ! KIT_GENERATE_FILE="${file}" KIT_GENERATE_REGION="${name}" PATH="${kit_root}/bin:${PATH}" \
@@ -93,7 +112,7 @@ generate:command() {
   fi
 }
 
-# generate:flip toggles the caller's fence state, its variable fence, at a fence line.
+# generate:flip toggles the caller's fence variable (true inside a fenced code block) at a fence line.
 generate:flip() {
   if [[ "${fence}" == true ]]
   then fence=false
@@ -101,11 +120,14 @@ generate:flip() {
   fi
 }
 
-# generate:unit <in> <out> <file> <where> <markdown> expands one unit, the file or a command's output, from <in>
-# into <out>. <where> opens every message: the file's path for the file, and for an output the file, the line
-# of the directive, and the command. Two passes: the first holds the unit to its shape, every marker line a
-# directive and every region opened and closed here, in order; the second runs each top-level region's command,
-# expands the output as a unit of its own, and writes the result between the markers.
+# generate:unit <in> <out> <file> <where> <markdown> expands one unit (the file, or a command's output) from <in>
+# into <out>. Every message starts with <where>: the file's path for the file, or, for an output, the file, the
+# directive's line, and the command. It makes two passes:
+#
+#   1. check the unit's shape: every marker line is a directive, and every region opens and closes in this unit,
+#      in order
+#   2. run each top-level region's command, expand its output as a unit of its own, and write the result between
+#      the directive and end lines
 generate:unit() {
   local in=$1 out=$2 file=$3 where=$4 markdown=$5
   local -a lines stack opened
@@ -187,7 +209,7 @@ generate:unit() {
     fi
     cat "${result}" >> "${out}"
     rm -f "${body}" "${result}"
-    # The old body is skipped to this region's end, by depth, since the first pass proved the nesting.
+    # Skip the old body up to this region's end line, counting depth. The first pass already checked the nesting.
     depth=1
     for (( j = i + 1; depth > 0; j++ ))
     do
@@ -209,8 +231,8 @@ generate:unit() {
   done
 }
 
-# generate:twice <expanded> <file> prints "<name>\t<line>" for the first region the expanded text opens twice,
-# outside a markdown fence when <file> is markdown, or nothing.
+# generate:twice <expanded> <file> prints "<name>\t<line>" for the first region the expanded text opens a second
+# time, or nothing. When <file> is markdown, fenced code blocks are skipped.
 generate:twice() {
   local expanded=$1 line fence=false markdown=false number=0
   local -A seen=()
@@ -233,9 +255,12 @@ generate:twice() {
   done < "${expanded}"
 }
 
-# generate:expand <file> <mode> expands the file's regions into a sibling temp file and compares. It returns 0
-# when nothing changed, 1 when the file was rewritten (mode write) or is stale (mode check), and 2 when it could
-# not be cleanly expanded, in which case the file is left as it was. Only mode write ever writes.
+# generate:expand <file> <mode> expands the file's regions into a temp file beside it and compares the two. Only
+# mode write writes the file. It returns:
+#
+#   0  nothing changed
+#   1  the file was rewritten (mode write) or is stale (mode check)
+#   2  the file could not be expanded cleanly, and is left unchanged
 generate:expand() {
   local file=$1 mode=${2:-write} target temp markdown=false twice number
   if [[ ! -f "${file}" ]]
@@ -280,10 +305,14 @@ generate:expand() {
   return 1
 }
 
-# generate:run [--check] [--iterations=<n>] [<path>…] is the driver. Named files are expanded for one pass, or
-# <n>; with none named every file carrying a directive is expanded until a pass changes nothing, at most twenty
-# passes or <n>, since a command may read another file's region. --check runs one pass without writing and fails
-# naming every stale file. A file that could not be cleanly expanded fails the run whatever the mode.
+# generate:run [--check] [--iterations=<n>] [<path>…] is the driver:
+#
+#   - Named files get one pass, or up to <n>.
+#   - With no paths, every file containing a directive is expanded until a pass changes nothing, for at most 20
+#     passes or <n>. More than one pass can be needed because a command may read another file's region.
+#   - --check runs one pass without writing and fails naming every stale file.
+#
+# A file that cannot be expanded cleanly fails the run in every mode.
 generate:run() {
   local check=false limit=0 explicit=false arg file rc pass=0 changed failed stale
   local -a files=() targets=()
diff --git a/bin/git.sh b/bin/git.sh
index 105ede0..a9ae45d 100644
--- a/bin/git.sh
+++ b/bin/git.sh
@@ -1,9 +1,13 @@
 # shellcheck shell=bash
-# git.sh - the default branch, the worktrees, the sweep, and the rebase (sourced module)
+# git.sh - git helpers: the default branch, worktrees, kit tidy, and kit rebase (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The sweep asks the forge, through bin/forge.sh, whether a worktree's change is merged or closed, and the issue's
-# tracker, through bin/tracker.sh, whether its issue is.
+# kit tidy (git:tidy) decides whether a worktree's work is finished by asking:
+#
+#   - the forge, the service that hosts the repository (GitHub, GitLab), through bin/forge.sh: is the branch's pull
+#     request merged or closed?
+#   - when the branch has no pull request, the issue's tracker, through bin/tracker.sh: is the branch's issue
+#     closed?
 
 use forge
 
@@ -16,14 +20,15 @@ git:default-branch() {
   printf '%s\n' "${branch}"
 }
 
-# git:main-root [<path>] prints the root of the main checkout, under which worktrees/ lives, from the main
-# checkout or any linked worktree.
+# git:main-root [<path>] prints the root of the main checkout, which contains worktrees/. It works from the main
+# checkout or from any linked worktree.
 git:main-root() {
   dirname "$(git -C "${1:-.}" rev-parse --path-format=absolute --git-common-dir)"
 }
 
 # git:worktrees prints "<path>\t<detached>\t<branch>" for every linked worktree under worktrees/. <detached> is
-# true or false, and <branch> is empty for a detached checkout; the empty field is last so a tab read keeps it.
+# true or false. <branch> is empty for a detached checkout. The empty field comes last so a tab-separated read
+# keeps it.
 git:worktrees() {
   local worktree_root path="" branch="" detached=false line
   worktree_root="$(git:main-root)/worktrees"
@@ -42,7 +47,7 @@ git:worktrees() {
         detached=true
         ;;
       ("")
-        # git ends every record with a blank line; the printf below adds one so the last record ends too.
+        # git ends each record with a blank line. The printf below adds one more so the last record is printed too.
         [[ "${path}" == "${worktree_root}"/* ]] && printf '%s\t%s\t%s\n' "${path}" "${detached}" "${branch}"
         path=""
     esac
@@ -54,13 +59,14 @@ git:gone-branches() {
   git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/ | awk '$2 == "[gone]" { print $1 }'
 }
 
-# git:clean <path> is true when the checkout at <path> has no uncommitted change.
+# git:clean <path> is true when the checkout at <path> has no uncommitted changes.
 git:clean() {
   [[ -z "$(git -C "$1" status --porcelain 2>/dev/null)" ]]
 }
 
-# git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides one worktree and
-# says why. It returns 0 when the worktree was removed, or would be under a dry run, and 1 when it is kept.
+# git:tidy-worktree <path> <branch> <detached> <default-branch> <self-root> <dry-run> decides whether to remove
+# one worktree and prints the reason. It returns 0 when the worktree was removed (or would be, under a dry run)
+# and 1 when it is kept.
 git:tidy-worktree() {
   local path=$1 branch=$2 detached=$3 default_branch=$4 self_root=$5 dry_run=$6 state="" ref
   if [[ "${path}" == "${self_root}" ]]
@@ -84,8 +90,8 @@ git:tidy-worktree() {
     fi
   elif [[ "${detached}" == true ]]
   then
-    # A detached checkout is residue only when its commit is already on the default branch; otherwise its HEAD
-    # may be the only thing that reaches that commit.
+    # Remove a detached checkout only when its commit is already on the default branch. Otherwise its HEAD may be
+    # the only ref that reaches that commit.
     if git -C "${path}" merge-base --is-ancestor HEAD "origin/${default_branch}" 2>/dev/null
     then
       state=DETACHED
@@ -111,11 +117,23 @@ git:tidy-worktree() {
   esac
 }
 
-# git:tidy [--dry-run] removes every worktree under worktrees/ whose pull request is merged or closed, or that is
-# detached, clean, and at a commit the default branch already has; prunes the worktree bookkeeping; and deletes
-# every local branch whose upstream is gone. It never touches the default branch, a branch checked out in a
-# live worktree, a dirty worktree, a detached worktree whose commit nothing else reaches, or the worktree it
-# runs in. --dry-run says what a sweep would do and changes nothing.
+# git:tidy [--dry-run] cleans up finished work. It:
+#
+#   1. fetches origin with --prune
+#   2. removes every clean worktree under worktrees/ whose pull request is merged or closed (or, with no pull
+#      request, whose issue is closed), or that is detached at a commit the default branch already has
+#   3. prunes git's worktree bookkeeping
+#   4. deletes every local branch whose upstream is gone
+#
+# It never touches:
+#
+#   - the default branch
+#   - a branch checked out in a worktree it keeps
+#   - a worktree with uncommitted changes
+#   - a detached worktree whose commit nothing else reaches
+#   - the worktree it runs in
+#
+# --dry-run prints what it would do and changes nothing.
 git:tidy() {
   local dry_run=false flag repo default_branch self_root found=false path branch detached
   local removed_worktrees=0 removed_branches=0 checked_out
@@ -202,10 +220,15 @@ git:tidy() {
   fi
 }
 
-# git:rebase [<path>] rebases the branch checked out at <path>, the current checkout by default, onto the
-# default branch at origin and pushes it with --force-with-lease. It refuses the root checkout, the human's desk,
-# whatever branch it has; the default branch anywhere; and a dirty worktree. On a conflict it aborts and leaves
-# the worktree as it was.
+# git:rebase [<path>] rebases the branch checked out at <path> (default: the current checkout) onto the default
+# branch at origin, then pushes it with --force-with-lease. It refuses:
+#
+#   - a checkout with no branch checked out
+#   - the root checkout (the desk, which belongs to the human), whatever branch it has
+#   - the default branch, in any checkout
+#   - a worktree with uncommitted changes
+#
+# On a conflict it aborts the rebase and leaves the worktree as it was.
 git:rebase() {
   local worktree=${1:-.} branch default_branch
   branch=$(git -C "${worktree}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
diff --git a/bin/issue.sh b/bin/issue.sh
index d9e0860..fd321c8 100644
--- a/bin/issue.sh
+++ b/bin/issue.sh
@@ -1,28 +1,41 @@
 # shellcheck shell=bash
-# issue.sh - the issue on-ramp: a linked branch, a worktree, a start commit, and a draft change (sourced module)
+# issue.sh - start an issue: a linked branch, a worktree, a start commit, and a draft pull request (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# issue:start [<reference>…] is the one command the loop needs and no vendor provides. A reference names its
-# tracker, as bin/tracker.sh describes: `7` or `#7` for the forge's own issues, `AB#4521` for a declared one. The
-# first is the primary issue. One of the forge's own is linked to the branch the forge makes, which closes it on
-# merge; any other, and every further reference, a secondary, is closed by a `Closes <reference>` line in the
-# change's body. Every listed issue is assigned to the caller, as each tracker knows the caller. It never switches
-# the checkout it runs from: the branch is checked out in worktrees/<key>-<slug> under the main checkout, the key
-# being the reference as a branch name opens with it, 7 or ab4521, and an existing branch, worktree, or change is
-# reused, so a re-run reconciles.
+# issue:start [<reference>…] starts or resumes work on one or more issues. Each reference names its tracker, as
+# bin/tracker.sh describes:
 #
-# With no argument and a terminal on stdin it asks for a title and creates the issue; without a terminal the
-# usage error stands, so an agent never hangs on a prompt. Uncommitted work in the root checkout, the human's
-# desk, is swept into the new worktree, uncommitted, and the desk is left clean, and fast-forwarded when it is on
-# the default branch; inside any other checkout, dirty files are that issue's own and stay. A sweep that cannot
-# apply leaves the stash in place and stops.
+#   - `7` or `#7`: an issue in the forge's own tracker (the forge is the service that hosts the repository, GitHub
+#     or GitLab)
+#   - `AB#4521`: a work item in a declared Azure DevOps tracker
 #
-# Every call to the forge goes through bin/forge.sh, and every call about an issue through bin/tracker.sh. Each
-# step below prints its one result on stdout and talks on stderr, so issue:start reads them in order.
+# The first reference is the primary issue. The others are secondary. Each issue is closed on merge by:
+#
+#   - a primary issue in the forge's tracker: the forge links it to the branch the forge creates
+#   - any other primary issue, and every secondary one: a `Closes <reference>` line in the pull request's body
+#
+# Every listed issue is assigned to the caller, as each tracker identifies the caller.
+#
+# issue:start never switches the checkout it runs from. It checks the branch out in worktrees/<key>-<slug> under
+# the main checkout. The key is the reference as it starts a branch name: 7 or ab4521. An existing branch,
+# worktree, or pull request is reused, so running it again fills in whatever is missing.
+#
+# With no argument and a terminal on stdin, it asks for a title and creates the issue. Without a terminal it fails
+# with a usage error, so an agent never waits on a prompt.
+#
+# Uncommitted work is handled by where it is:
+#
+#   - in the root checkout (the desk, which belongs to the human): moved into the new worktree, still uncommitted.
+#     The desk is left clean, and is fast-forwarded when it is on the default branch. If the work cannot be
+#     applied in the worktree, it stays in the stash and the command stops.
+#   - in any other checkout: left in place, since it belongs to that checkout's issue
+#
+# Every forge call goes through bin/forge.sh, and every issue call through bin/tracker.sh. Each helper below
+# prints its one result on stdout and its messages on stderr, so issue:start can capture the results in order.
 
 use git forge tracker
 
-# issue:create asks for a title at the terminal and prints the reference of the issue the forge's tracker creates.
+# issue:create asks for a title at the terminal, creates the issue in the forge's tracker, and prints its reference.
 issue:create() {
   local title number
   read -r -p "Issue title: " title
@@ -36,8 +49,8 @@ issue:create() {
   printf '#%s\n' "${number}"
 }
 
-# issue:assign <reference>… adds the caller, as each issue's tracker knows the caller, to each issue's assignees,
-# warning where someone else is there already.
+# issue:assign <reference>… adds the caller (as each issue's tracker identifies the caller) to each issue's
+# assignees. It warns when someone else is already assigned, and when the assignment fails.
 issue:assign() {
   local ref prefix me assignees
   local -A me_in=()
@@ -54,10 +67,16 @@ issue:assign() {
   done
 }
 
-# issue:branch <reference> <default-branch> <title> prints the branch made for the issue, making one if none
-# exists: linked by the forge for one of its own issues, and named <key>-<slug of the title> from the default
-# branch for any other. An existing one is found by an open change's head, then by the remote ref, so a second run
-# never forks a duplicate.
+# issue:branch <reference> <default-branch> <title> prints the issue's branch. It reuses an existing branch, so a
+# second run never creates a duplicate. It looks, in order, for:
+#
+#   1. the branch of an open pull request for the issue
+#   2. a branch on origin named <key>-*
+#
+# When neither exists, it creates the branch:
+#
+#   - for an issue in the forge's tracker, the forge creates a branch linked to the issue
+#   - for any other issue, kit pushes <key>-<slug of the title> to origin from the default branch
 issue:branch() {
   local ref=$1 default_branch=$2 title=$3 key branch slug
   key=$(tracker:key "${ref}") || return 2
@@ -86,7 +105,8 @@ issue:branch() {
   printf '%s\n' "${branch}"
 }
 
-# issue:worktree <main-root> <branch> prints the worktree the branch is checked out in, making it if there is none.
+# issue:worktree <main-root> <branch> prints the worktree the branch is checked out in. If there is none, it
+# creates <main-root>/worktrees/<branch>.
 issue:worktree() {
   local main_root=$1 branch=$2 wt
   wt=$(git worktree list --porcelain 2>/dev/null \
@@ -113,9 +133,10 @@ issue:worktree() {
   printf '%s\n' "${wt}"
 }
 
-# issue:start-commit <worktree> <default-branch> <reference> <title> gives the branch its first commit when it has
-# none: a forge cannot open a change with nothing to compare. --only keeps the commit empty, so work already
-# staged in a reused worktree stays in the index. The subject follows the loop's shape, the reference first.
+# issue:start-commit <worktree> <default-branch> <reference> <title> adds an empty first commit when the branch has
+# no commits beyond the default branch, because a forge cannot open a pull request with nothing to compare. --only
+# keeps the commit empty, so work already staged in a reused worktree stays in the index. The subject starts with
+# the reference, as the workflow's commit subjects do: "<reference> start: <title>".
 issue:start-commit() {
   local wt=$1 default_branch=$2 ref=$3 title=$4
   if [[ -z "$(git -C "${wt}" rev-list "origin/${default_branch}..HEAD" 2>/dev/null)" ]]
@@ -125,8 +146,8 @@ issue:start-commit() {
   fi
 }
 
-# issue:sweep-push <root> <message> stashes everything uncommitted at <root>, untracked files included, and
-# prints the stash's commit, which stays valid however the stash list shifts.
+# issue:sweep-push <root> <message> stashes all uncommitted work at <root>, including untracked files, and prints
+# the stash's commit hash. The hash stays valid even when other entries are pushed onto or dropped from the stash.
 issue:sweep-push() {
   local root=$1 message=$2
   if ! git -C "${root}" stash push --include-untracked --message "${message}" >/dev/null
@@ -137,9 +158,9 @@ issue:sweep-push() {
   git -C "${root}" rev-parse 'stash@{0}'
 }
 
-# issue:sweep-apply <root> <worktree> <stash> <default-branch> lands the stash in the worktree, uncommitted,
-# drops it, and fast-forwards the now-clean desk when it is on the default branch. On a conflict the stash is
-# kept and the caller stops.
+# issue:sweep-apply <root> <worktree> <stash> <default-branch> applies the stash in the worktree, uncommitted, and
+# drops it. Then, if the desk is on the default branch, it fast-forwards the now-clean desk. On a conflict it keeps
+# the stash and returns non-zero, so the caller stops.
 issue:sweep-apply() {
   local root=$1 wt=$2 stash=$3 default_branch=$4 slot
   if ! git -C "${wt}" stash apply "${stash}" >/dev/null 2>&1
@@ -155,7 +176,7 @@ issue:sweep-apply() {
     || warn "${default_branch} could not fast-forward to origin; it is left as it was."
 }
 
-# issue:pull-request <branch> <default-branch> <title> prints the number of the open change for the branch,
+# issue:pull-request <branch> <default-branch> <title> prints the number of the branch's open pull request,
 # opening a draft if there is none.
 issue:pull-request() {
   local branch=$1 default_branch=$2 title=$3 pr
@@ -168,8 +189,9 @@ issue:pull-request() {
   printf '%s\n' "${pr}"
 }
 
-# issue:link-in-body <change> <reference>… adds a `Closes <reference>` line to the change's body for each reference
-# not there: a secondary issue, or a primary the forge cannot link by itself.
+# issue:link-in-body <change> <reference>… adds a `Closes <reference>` line to the pull request's body for each
+# reference the body does not already close, fix, or resolve. The references are the secondary issues, and a
+# primary issue the forge cannot link by itself.
 issue:link-in-body() {
   local pr=$1 ref escaped body changed=false
   shift
@@ -191,8 +213,8 @@ issue:link-in-body() {
   fi
 }
 
-# issue:start [<reference>…] is the on-ramp the file header describes. A desk without a signing key is refused
-# where the require_signing setting is true, before anything is written.
+# issue:start [<reference>…] does what the file header describes. When the require_signing setting is true, it
+# fails before writing anything if git has no signing key configured.
 issue:start() {
   local n primary title default_branch main_root desk desk_branch branch wt stash="" pr created sigil noun
   local -a refs=() in_body=()
diff --git a/bin/kit b/bin/kit
index 85e0902..5cee9ca 100755
--- a/bin/kit
+++ b/bin/kit
@@ -1,12 +1,16 @@
 #!/usr/bin/env bash
-# kit - the kit's command: each verb is the executable bin/kit-<verb>.sh beside it (executed entrypoint)
+# kit - the kit's command: runs the verb script bin/kit-<verb>.sh (executed entrypoint)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The release is the directory above bin/, found through any symlink this file is reached by, as when Homebrew
-# links it into its own bin. This file resolves it, exports it as kit_root, moves to the repository root so every
-# verb reads and writes the same paths wherever it was typed, and hands the verb its arguments. The directory it
-# was typed in is exported as kit_invoked_in for the verbs that take relative paths. Everything else, the usage
-# text included, lives with the verb.
+# kit <verb> runs bin/kit-<verb>.sh with the remaining arguments. Before it does, it:
+#
+#   1. finds the release: the directory above bin/, following any symlink to this file (Homebrew links it into
+#      its own bin)
+#   2. exports the release directory as kit_root
+#   3. exports the directory the command was typed in as kit_invoked_in, for verbs that take relative paths
+#   4. changes to the repository root, so every verb reads and writes the same paths wherever it was typed
+#
+# Each verb script does everything else, including printing its own usage.
 #
 # see: .kit/1st.md
 
@@ -18,7 +22,7 @@ then
   exit 1
 fi
 
-# readlink -f needs macOS 12.3 or later, the first with a GNU-compatible readlink; older macOS lacks it.
+# readlink -f needs macOS 12.3 or later. Older macOS has no GNU-compatible readlink.
 kit_root=$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)
 export kit_root
 kit_invoked_in=$(pwd -P)
@@ -38,23 +42,25 @@ usage: kit <verb> [<argument>…]
   update                after the pin is bumped: replace unchanged files, three-way merge changed ones
   check                 fail when a delivered file differs from the pinned release
   module <list|add|remove> [<module>…]
-                        the modules this repository takes
-  context <path>…       name the rules that govern a file, and record the ask
+                        list, add, or remove the modules this repository uses
+  context <path>…       print the rules that govern each path, and log the request
+  new file <path> [--rule=<rule>] [--variant=<variant>] [--<hole>=<value>]…
+                        create a file from the template of the rule that governs it; <path> is from the root
   generate [--check] [<path>…]
-                        expand every kit:generate region to what its command makes, or check that it is
+                        rewrite every kit:generate region with its command's output; --check fails if one is stale
   region [--home] [<path>]
                         print the content the active modules deliver as the region at a path
-  ci                    the delivered CI job's checks, anywhere: gate, check, linked, and policy, every one reported
+  ci                    run the delivered CI job's checks anywhere (gate, check, linked, policy); report every failure
   policy [--input]      refuse a branch, commit subject, or change title the repository's policy does not allow
-  gate                  run the repository's gate, the gate setting or the detected one; refuse when there is none
-  linked [<number>]     refuse a pull request not linked to an open issue of this repository
+  gate                  run the repository's gate (the gate setting, else the detected one); fail when there is none
+  linked [<number>]     fail when the pull request is not linked to an open issue of this repository
   toolchain <list|install|outdated|update|path|run> …
-                        the tools the gate runs, whatever manages them: mise, brew, or docker
-  issue [<reference>…]  start or resume an issue, #7 or AB#4521: linked branch, worktree, start commit, draft change
-  rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk
+                        manage the tools the gate runs, through mise, brew, or docker
+  issue [<reference>…]  start or resume an issue (#7, AB#4521): linked branch, worktree, start commit, draft change
+  rebase [<path>]       rebase a worktree's branch onto the default branch and push it; never the desk (root checkout)
   tidy [--dry-run]      remove worktrees whose pull request is merged or closed, and gone branches
   status [--no-fetch] [--json] [--mine | --all | --owner=<login>…]
-                        the desk, the worktrees, and the open pull requests: everyone's, yours, or the named
+                        show the desk, the worktrees, and the open pull requests: everyone's, yours, or the named
                         authors'
   lint [--all-files] [<path>…]
                         run each rule's linter over the paths it governs: staged, named, or every tracked one
@@ -62,7 +68,7 @@ usage: kit <verb> [<argument>…]
                         the kit's own release: verify a tag, pack a checkout, publish it, retire pre-releases
   version               print this release's version
 
-Each verb answers --help.
+Run kit <verb> --help for a verb's usage.
 USAGE
     ;;
   (*)
diff --git a/bin/kit-check.sh b/bin/kit-check.sh
index bf28c97..df7fb52 100755
--- a/bin/kit-check.sh
+++ b/bin/kit-check.sh
@@ -2,8 +2,20 @@
 # kit-check - fail when a delivered file differs from the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Every path under the repository is compared with the release's file. A path under home is compared where
-# ~/.kit/manifest exists, that is, on a desk that installed; a machine with none, such as a runner, is told so.
+# kit check takes no arguments. It compares the repository with the release pinned in .kit/manifest, and reports
+# a finding when:
+#
+#   - .kit/manifest records a kit version other than the pinned release
+#   - a delivered file is missing, or differs from the release's copy
+#   - a merged JSON file is missing an entry the kit writes, or jq is not on PATH to read it
+#   - a file that should contain a kit region has none
+#   - a file the repository owns is missing a line a module expects in it
+#   - a generated region differs from what its command makes
+#
+# Files delivered to the home directory are checked only when ~/.kit/manifest exists, that is, on a machine where
+# kit install ran. On a machine without it, such as a CI runner, kit check prints a note and skips them.
+#
+# Exits 0 when there are no findings, and 1 otherwise.
 #
 # see: bin/release.sh
 
@@ -51,7 +63,7 @@ do
       findings=$(( findings + 1 ))
     elif [[ "${kind}" == region ]]
     then
-      # The directive must be there; what it makes is held below, with every other generated region.
+      # Only the directive is checked here. Its content is checked below, with every other generated region.
       if ! release:installed "${src}" "${dest}" >/dev/null
       then
         error "${dest} has no kit region; run: kit update"
@@ -67,14 +79,14 @@ do
     fi
   done <<<"${delivered}"
 done
-# Every line a module expects of a file the repository owns is there; the kit writes none of them.
+# Report each line a module expects in a file the repository owns that is missing. The kit never writes these lines.
 while IFS= read -r unmet
 do
   [[ -n "${unmet}" ]] || continue
   error "${unmet}"
   findings=$(( findings + 1 ))
 done < <(release:unmet "${kit_root}" "${modules[@]}")
-# Every generated region, the kit's and the repository's own, is what its command makes it.
+# Check that every generated region, the kit's and the repository's own, matches what its command makes.
 generate:run --check || findings=$(( findings + 1 ))
 if (( findings > 0 ))
 then
diff --git a/bin/kit-ci.sh b/bin/kit-ci.sh
index be8c02f..6337d89 100755
--- a/bin/kit-ci.sh
+++ b/bin/kit-ci.sh
@@ -1,9 +1,17 @@
 #!/usr/bin/env bash
-# kit-ci - the delivered CI job's checks, run anywhere: the gate, the kit's own check, the issue link, and the policy
+# kit-ci - run the delivered CI job's four checks on any machine (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Every check runs even when an earlier one refused, so one run reports every finding. The exit status is the
-# number of checks that refused.
+# kit ci takes no arguments. It runs these checks in order:
+#
+#   1. kit gate: the repository's gate (its own CI command) passes
+#   2. kit check: every delivered file matches the pinned release
+#   3. kit linked: the pull request is linked to an open issue
+#   4. kit policy: the branch, commit subjects, and pull request title match the policy
+#
+# Every check runs even when an earlier one fails, so one run reports every finding.
+#
+# Exits 0 when all four pass. Otherwise the exit status is the number of checks that failed.
 #
 # see: bin/kit-gate.sh, bin/kit-check.sh, bin/kit-linked.sh, bin/kit-policy.sh
 
diff --git a/bin/kit-context.sh b/bin/kit-context.sh
index 0faa33c..605727a 100755
--- a/bin/kit-context.sh
+++ b/bin/kit-context.sh
@@ -1,7 +1,19 @@
 #!/usr/bin/env bash
-# kit-context - name the rules that govern a file, and record the ask (kit verb)
+# kit-context - print the rules that govern a file, and log the request (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# kit context <path>… [--json]
+#
+# Prints the path of each rule that governs the given paths, once each. With --json, it prints one JSON object per
+# path with that path's rules. Each request is logged to kit/context.log in git's common directory.
+#
+# kit context --claude
+#
+# Runs as Claude Code's PreToolUse hook. It reads the hook's input on stdin, and returns the rules that govern the
+# file the tool is about to write, as additional context.
+#
+# Exits 2 on a usage error.
+#
 # see: bin/context.sh, docs/context.md
 
 set -o errexit -o nounset -o pipefail
diff --git a/bin/kit-gate.sh b/bin/kit-gate.sh
index b17d591..03a4c35 100755
--- a/bin/kit-gate.sh
+++ b/bin/kit-gate.sh
@@ -2,13 +2,22 @@
 # kit-gate - run the repository's gate, and refuse when there is none (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The gate is the `gate` setting in .kit/settings.yml, else the first of: a root justfile with a ci recipe, a
-# Makefile with a ci target, a package.json with a ci script. A gate that cannot run clears nothing: a repository
-# with none, or one whose justfile cannot be read, is refused, naming the remedy. On a runner, each outcome also
-# lands in the step summary. The gate runs with the declared toolchains' tools, inside the container where the
-# toolchain is docker; see bin/toolchain.sh.
+# kit gate takes no arguments. It runs the repository's gate, the repository's own CI command. The gate is the
+# first of:
 #
-# see: modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
+#   1. the `gate` setting in .kit/settings.yml
+#   2. `just ci`, when the root justfile has a ci recipe
+#   3. `make ci`, when the Makefile has a ci target
+#   4. `npm run ci`, when package.json has a ci script
+#
+# The gate runs with the declared toolchains' tools, inside the container when the toolchain is docker.
+#
+# kit gate fails, and prints the remedy, when the repository has no gate or the root justfile cannot be read. A
+# gate that cannot run never counts as a pass. On a CI runner, each outcome is also written to the step summary.
+#
+# Exits 0 when the gate passes, and 1 otherwise.
+#
+# see: bin/toolchain.sh, modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
@@ -21,7 +30,7 @@ then
   exit 0
 fi
 
-# gate:detect prints the command of the first gate found, or nothing.
+# detect-gate prints the command of the first gate found, or nothing. It fails when the root justfile cannot be read.
 detect-gate() {
   local recipes
   if [[ -f justfile || -f Justfile || -f .justfile ]]
diff --git a/bin/kit-generate.sh b/bin/kit-generate.sh
index 6b48fe5..6797929 100755
--- a/bin/kit-generate.sh
+++ b/bin/kit-generate.sh
@@ -2,10 +2,18 @@
 # kit-generate - expand every kit:generate region to what its command makes, or check that it is (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The paths are the arguments, taken from the directory the command was typed in, else every tracked file and
-# every untracked one git does not ignore. Named files are expanded once, or --iterations=<n> times; the whole
-# repository is expanded until a pass changes nothing. --check writes nothing and fails naming every stale file;
-# kit check runs it, and the lefthook fragment runs it over the staged paths.
+# kit generate [--check] [--iterations=<n>] [<path>…]
+#
+# Paths are relative to the current directory. With no paths, kit generate expands every tracked file and every
+# untracked file git does not ignore.
+#
+#   - Named files are expanded once, or <n> times with --iterations=<n>.
+#   - With no paths, kit generate repeats until a pass changes nothing.
+#   - --check writes nothing, and fails naming every stale file.
+#
+# kit check runs kit generate --check, and the lefthook pre-commit hook runs it over the staged paths.
+#
+# Exits 0 on success, 2 on an unknown flag, and non-zero when a file is stale (with --check) or cannot be expanded.
 #
 # see: bin/generate.sh, docs/generate.md
 
diff --git a/bin/kit-install.sh b/bin/kit-install.sh
index 3835c38..12bda08 100755
--- a/bin/kit-install.sh
+++ b/bin/kit-install.sh
@@ -2,9 +2,18 @@
 # kit-install - mirror the release into the repository, and into the home directory (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Activates the default modules and the named ones, with the modules they depend on, places what they deliver
-# under each base, and writes the manifests. A different file already at a delivered path is refused, named, and
-# left alone, and no manifest is written until every path is clear.
+# kit install [<module>…]
+#
+# Sets up kit in a repository that does not have it yet:
+#
+#   1. Activates the default modules, the named modules, and the modules they depend on.
+#   2. Places the files those modules deliver, in the repository and in the home directory.
+#   3. Writes .kit/manifest, and ~/.kit/manifest when the modules deliver files to the home directory.
+#
+# When a different file is already at a delivered path, kit install names it and leaves it alone. It writes no
+# manifest until every path is clear. A repository that already has .kit/manifest is refused: run kit update.
+#
+# Exits 0 on success, 2 for a module the release does not have, and 1 for any other failure.
 #
 # see: bin/release.sh
 
diff --git a/bin/kit-issue.sh b/bin/kit-issue.sh
index 5290b67..a3e401f 100755
--- a/bin/kit-issue.sh
+++ b/bin/kit-issue.sh
@@ -2,8 +2,21 @@
 # kit-issue - start or resume an issue (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# A linked branch, a worktree, a start commit, and a draft change, for an issue in any declared tracker: `7` or
-# `#7` for the forge's own, `AB#4521` for an Azure DevOps work item.
+# kit issue [<reference>…]
+#
+# Starts work on an issue, or resumes it. kit issue makes each of these, and reuses any that already exists:
+#
+#   - a branch linked to the issue
+#   - a worktree for the branch
+#   - a start commit
+#   - a draft pull request (a merge request on GitLab)
+#
+# A reference names the issue and its tracker:
+#
+#   - `7` or `#7` for an issue on the forge (the service that hosts the repository, GitHub or GitLab)
+#   - `AB#4521` for an Azure DevOps work item, when that tracker is declared in .kit/settings.yml
+#
+# With no reference, at a terminal, kit issue asks for a title and creates the issue.
 #
 # see: bin/issue.sh, bin/forge.sh, bin/tracker.sh
 
diff --git a/bin/kit-linked.sh b/bin/kit-linked.sh
index 4e37b8b..f8614a6 100755
--- a/bin/kit-linked.sh
+++ b/bin/kit-linked.sh
@@ -2,10 +2,16 @@
 # kit-linked - refuse a change not linked to an open issue of this repository (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The delivered CI job's last check, and a check a desk can run on any change: a pull request on GitHub, a merge
-# request on GitLab, named in the forge's own words. The change is the argument, else the one the forge says this
-# checkout is working on. A linked issue of another repository, or a
-# closed one, is noted and does not count. On a runner the remedy also lands in the step summary.
+# kit linked [<number>]
+#
+# Fails when a pull request is not linked to an open issue of this repository. kit ci runs it in the delivered CI
+# job, and anyone can run it on any pull request. On GitLab it checks a merge request, and its messages say so.
+#
+# The pull request is <number>, or else the one this checkout is working on. A linked issue counts when it is
+# open and belongs to this repository. A closed issue, or one in another repository, is reported and does not
+# count. On a CI runner, the remedy is also written to the step summary.
+#
+# Exits 0 when at least one linked issue counts, 1 when none does, and 2 when there is no pull request to check.
 #
 # see: bin/forge.sh
 
@@ -37,7 +43,8 @@ remedy=$(printf '%s\n' \
   "2. re-run the check: linking fires no event, so it does not re-run on its own" "" \
   "\`kit issue <N>\` makes this link when it starts the work.")
 refs=$(forge:pr-closing-issues "${number}") || exit 1
-# A tracker the forge does not link by itself is linked by a closing keyword in the change's body.
+# The forge does not link issues of other trackers, such as Azure DevOps. A closing keyword in the pull request's
+# body links them: `Closes AB#4521`.
 others=$(tracker:body-refs "$(forge:pr-body "${number}")")
 if [[ -z "${refs}${others}" ]]
 then
diff --git a/bin/kit-lint.sh b/bin/kit-lint.sh
index d493b48..6764f6a 100755
--- a/bin/kit-lint.sh
+++ b/bin/kit-lint.sh
@@ -2,18 +2,33 @@
 # kit-lint - run each rule's linter over the paths it governs (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The paths are the arguments, else the staged ones, else with --all-files every tracked one. Each is matched to
-# the rules that govern it, as kit context matches, and every rule whose frontmatter carries a `lint:` command
-# runs it once over its paths. A linter the rule names that is not on PATH is a refusal, not a skip. The exit
-# status is the number of rules whose linter refused. No hook manager is assumed; the lefthook module wires its
-# pre-commit hook to this verb.
+# kit lint [--all-files] [<path>…]
 #
-# see: bin/context.sh, docs/context.md
+# Runs each rule's checks over the files the rule governs. The files are:
+#
+#   - the paths given, relative to the current directory
+#   - with no paths, the staged files
+#   - with no paths and --all-files, every tracked file
+#
+# Each file is matched to the rules that govern it, the same way kit context matches. Then, for each rule:
+#
+#   - When the rule's frontmatter has a `lint:` command, kit lint runs it once over all the rule's files. A linter
+#     that is not on PATH is a failure, not a skip.
+#   - When the rule has templates, each of its files must have the shape of one of them (see bin/template.sh).
+#
+# Files under .kit/templates/ are templates, not files of their kind, and are not linted.
+#
+# kit lint assumes no hook manager. The lefthook module runs it from a pre-commit hook.
+#
+# Exits 0 when every rule passes, and 2 on an unknown flag. Otherwise the exit status is the number of rules that
+# failed.
+#
+# see: bin/context.sh, bin/template.sh, docs/context.md, docs/templates.md
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
-use context yaml
+use context template yaml
 
 all=false
 paths=()
@@ -32,8 +47,9 @@ do
     (*) paths+=("${arg}")
   esac
 done
-# A named path is taken from the directory the command was typed in; git's lists are root-relative already,
-# read NUL-separated so a name with a space or a non-ASCII character survives.
+# A named path is relative to the current directory, and is converted to a path from the repository root. git's
+# lists are already root-relative. They are read NUL-separated, so a name with a space or a non-ASCII character
+# survives.
 for i in "${!paths[@]}"
 do
   paths[i]=$(context:relative "${paths[i]}")
@@ -57,7 +73,7 @@ fi
 declare -A governed=()
 for path in "${paths[@]}"
 do
-  [[ -f "${path}" ]] || continue
+  [[ -f "${path}" && ! "${path}" =~ (^|/)\.kit/templates/ ]] || continue
   while IFS= read -r rule
   do
     [[ -n "${rule}" ]] || continue
@@ -68,6 +84,19 @@ done
 refused=0
 for rule in $(printf '%s\n' "${!governed[@]}" | LC_ALL=C sort)
 do
+  if [[ -n "$(template:variants "${rule}")" ]]
+  then
+    held=()
+    while IFS= read -r path
+    do
+      [[ -n "${path}" ]] && ! template:exempt "${path}" && held+=("${path}")
+    done < <(printf '%s' "${governed[${rule}]}")
+    step "${rule}: the shape of its templates over ${#held[@]} path(s)"
+    if (( ${#held[@]} > 0 )) && ! template:check "${rule}" "${held[@]}"
+    then
+      refused=$(( refused + 1 ))
+    fi
+  fi
   lint=$(yaml:value "${rule}" lint)
   [[ -n "${lint}" ]] || continue
   read -r -a command <<<"${lint}"
diff --git a/bin/kit-module.sh b/bin/kit-module.sh
index 83f07e8..f532a68 100755
--- a/bin/kit-module.sh
+++ b/bin/kit-module.sh
@@ -2,6 +2,18 @@
 # kit-module - list, activate, or deactivate the modules this repository takes (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# kit module list | add <module>… | remove <module>…
+#
+#   list                 prints every module in reach, with a ✅ beside the active ones, its origin (release or
+#                        repository), and its description. This is the default.
+#   add <module>…        activates the modules and the modules they depend on, places the files they deliver,
+#                        and rewrites the manifests. When a different file is already at a delivered path, it is
+#                        named and left alone, and no manifest is written.
+#   remove <module>…     takes out what the modules delivered (files, the kit's JSON entries, and the kit's
+#                        regions) and rewrites the manifests. A module that an active module depends on is refused.
+#
+# Exits 0 on success, 2 on a usage error or a module the release does not have, and 1 for any other failure.
+#
 # see: bin/release.sh, docs/modules.md
 
 set -o errexit -o nounset -o pipefail
@@ -69,7 +81,7 @@ case "${verb}" in
       release:among "${module}" "${active[@]}" || step "${module}: not active"
       readarray -t remaining < <(release:without "${module}" "${remaining[@]}")
     done
-    # Dependents are judged against what stays, so the order the modules are named in does not matter.
+    # Dependents are checked against the modules that remain, so the order of the named modules does not matter.
     for module in "$@"
     do
       readarray -t dependents < <(release:dependents "${kit_root}" "${module}" "${remaining[@]}")
diff --git a/bin/kit-new.sh b/bin/kit-new.sh
new file mode 100755
index 0000000..dfd46cc
--- /dev/null
+++ b/bin/kit-new.sh
@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# kit-new - make a new file from the template of the rule that governs it (kit verb)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# kit new file <path> [--rule=<rule>] [--variant=<variant>] [--<hole>=<value>]…
+#
+# Makes a new file from a rule's template. Then it prints the rules to read before writing the rest of the file,
+# as kit context does.
+#
+#   <path>                the new file, relative to the repository root wherever the command runs. An absolute
+#                         path inside the repository is accepted. A path outside it is refused.
+#   --rule=<rule>         the rule whose template to use. Default: the most specific rule that governs the path
+#                         and has templates. A script with no extension needs this flag.
+#   --variant=<variant>   the template to use. Default: the first variant the rule lists that the path allows.
+#   --<hole>=<value>      the value of a hole («name») within a line of the template. The holes path, name, and
+#                         stem default to values taken from the path. Every other hole needs its flag.
+#
+# kit new never overwrites a file: an existing path is refused.
+#
+# Exits 0 when the file is made, 1 when the path exists or the template is missing, and 2 on a usage error.
+#
+# see: bin/template.sh, docs/templates.md
+
+set -o errexit -o nounset -o pipefail
+# shellcheck source=bin/1st.sh
+source "${kit_root:?run through bin/kit}/bin/1st.sh"
+use context template
+
+usage="usage: kit new file <path> [--rule=<rule>] [--variant=<variant>] [--<hole>=<value>]…"
+if [[ "${1:-}" == --help ]]
+then
+  echo "${usage}" >&2
+  exit 0
+fi
+if [[ "${1:-}" != file ]]
+then
+  error "kit new makes a file: ${usage}"
+  exit 2
+fi
+shift
+
+path='' rule_name='' variant=''
+declare -A values=()
+for arg in "$@"
+do
+  case "${arg}" in
+    (--rule=?*) rule_name=${arg#--rule=} ;;
+    (--variant=?*) variant=${arg#--variant=} ;;
+    (--[a-z_]*=*)
+      key=${arg%%=*}
+      key=${key#--}
+      values[${key}]=${arg#*=}
+      ;;
+    (-*)
+      error "unknown flag '${arg}' (${usage})"
+      exit 2
+      ;;
+    (*)
+      if [[ -n "${path}" ]]
+      then
+        error "one path at a time (${usage})"
+        exit 2
+      fi
+      path=${arg}
+  esac
+done
+if [[ -z "${path}" ]]
+then
+  error "${usage}"
+  exit 2
+fi
+
+# An absolute path inside the repository is made relative to the root. A path outside the repository is refused.
+root=$(pwd -P)
+if [[ "${path}" == /* ]]
+then
+  path=$(context:relative "${path}")
+  if [[ "${path}" == /* ]]
+  then
+    error "${path} is outside the repository at ${root}"
+    exit 2
+  fi
+fi
+path=${path#./}
+if [[ "${path}" == ../* || "${path}" == */../* ]]
+then
+  error "${path} climbs out of the repository; name it from the root"
+  exit 2
+fi
+if [[ -e "${path}" ]]
+then
+  error "${path} is there already; kit new makes a file, it never overwrites one"
+  exit 1
+fi
+
+if [[ -n "${rule_name}" ]]
+then
+  rule=".kit/rules/${rule_name}.md"
+  if [[ ! -f "${rule}" ]]
+  then
+    error "there is no rule ${rule_name}; the rules are: $(find .kit/rules -maxdepth 1 -name '*.md' \
+      | sed 's@^.*/@@; s/\.md$//' | LC_ALL=C sort | paste -s -d ' ' -)"
+    exit 2
+  fi
+else
+  rule=$(template:rules "${path}" | head -n 1)
+  if [[ -z "${rule}" ]]
+  then
+    error "no rule with a template governs ${path}; name one with --rule=<rule>, or write the file by hand"
+    exit 2
+  fi
+fi
+
+chosen='' executable=''
+while IFS=$'\x1f' read -r name _ exec_flag
+do
+  [[ -n "${name}" ]] || continue
+  if [[ -z "${variant}" || "${name}" == "${variant}" ]]
+  then
+    chosen=${name}
+    executable=${exec_flag}
+    break
+  fi
+done < <(if [[ -n "${variant}" ]]; then template:variants "${rule}"; else template:applies "${rule}" "${path}"; fi)
+if [[ -z "${chosen}" ]]
+then
+  error "the $(template:rule-name "${rule}") rule has no template ${variant:-for ${path}}; its templates are:" \
+    "$(template:variants "${rule}" | cut -d $'\x1f' -f 1 | paste -s -d ' ' -)"
+  exit 2
+fi
+template=$(template:file "${rule}" "${chosen}")
+if [[ ! -f "${template}" ]]
+then
+  error "${rule} lists the template ${chosen}, and ${template} is not here; run: kit update"
+  exit 1
+fi
+
+name=${path##*/}
+values[path]=${values[path]:-${path}}
+values[name]=${values[name]:-${name}}
+values[stem]=${values[stem]:-${name%.*}}
+missing=()
+while IFS= read -r hole
+do
+  [[ -n "${hole}" && -z "${values[${hole}]+x}" ]] && missing+=("--${hole}=<…>")
+done < <(template:holes "${template}")
+if (( ${#missing[@]} > 0 ))
+then
+  error "the ${chosen} template of the $(template:rule-name "${rule}") rule needs ${missing[*]}"
+  exit 2
+fi
+
+json='{}'
+for key in "${!values[@]}"
+do
+  json=$(jq --compact-output --arg k "${key}" --arg v "${values[${key}]}" '.[$k] = $v' <<<"${json}")
+done
+mkdir -p "$(dirname "${path}")"
+template:render "${template}" "${json}" > "${path}"
+[[ "${executable}" == true ]] && chmod +x "${path}"
+context:log "${path}"
+ok "made ${path} from ${template}; read the rules below before writing the rest"
+context:rules "${path}"
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/kit-policy.sh b/bin/kit-policy.sh
index 4512084..0d204bd 100755
--- a/bin/kit-policy.sh
+++ b/bin/kit-policy.sh
@@ -2,9 +2,20 @@
 # kit-policy - refuse a branch, a commit subject, or a change title the repository's policy does not allow (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The facts are gathered once, the branch, the commits past the fork, and the open change, and the policy engine,
-# patterns by default or Open Policy Agent, names every refusal. --input prints the facts instead, the document a
-# rule is written against. kit ci runs this beside the gate. On a runner the refusals land in the step summary.
+# kit policy [--input]
+#
+# Fails when a name breaks the repository's policy. kit policy collects these facts once:
+#
+#   - the branch name
+#   - the subject of each commit since the branch forked from the default branch
+#   - the open pull request's title
+#
+# The policy engine then reports every refusal. The engine is patterns (the default) or Open Policy Agent. With
+# --input, kit policy prints the facts as JSON instead: the document a rule is written against.
+#
+# kit ci runs kit policy alongside the gate. On a CI runner, refusals are also written to the step summary.
+#
+# Exits 0 when the policy allows every name, 1 on any refusal, and 2 on a usage error.
 #
 # see: bin/policy.sh, docs/policy.md
 
diff --git a/bin/kit-rebase.sh b/bin/kit-rebase.sh
index e9e7e6e..907417b 100755
--- a/bin/kit-rebase.sh
+++ b/bin/kit-rebase.sh
@@ -2,7 +2,16 @@
 # kit-rebase - rebase a worktree's branch onto the default branch and push it (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Never the root checkout, the human's desk, and never the default branch.
+# kit rebase [<path>]
+#
+# Rebases the branch checked out at <path> (default: the current checkout) onto the default branch at origin, and
+# pushes it with --force-with-lease. kit rebase refuses:
+#
+#   - the root checkout (the desk), which belongs to the human, whatever branch it has
+#   - the default branch, in any checkout
+#   - a worktree with uncommitted changes
+#
+# On a conflict, kit rebase aborts and leaves the worktree as it was.
 #
 # see: bin/git.sh
 
diff --git a/bin/kit-region.sh b/bin/kit-region.sh
index 2fd14ac..b92746f 100755
--- a/bin/kit-region.sh
+++ b/bin/kit-region.sh
@@ -2,11 +2,19 @@
 # kit-region - print the content the active modules deliver as the region at a path (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The command behind every region the kit delivers. Install writes a bare directive, `kit:generate AGENTS.md`,
-# and kit generate fills it by running `kit region` with the region's name in KIT_GENERATE_REGION; the path is
-# that name, or the argument, relative to the repository, or with --home to the home directory. One active
-# module delivers a region at a path, so the answer is that module's regions/<base>/<path>, and a path no
-# active module delivers is refused.
+# kit region [--home] [<path>]
+#
+# Prints the content an active module delivers as the region at <path>. Every region the kit delivers is filled
+# this way: kit install writes a bare directive, such as `kit:generate AGENTS.md`, and kit generate fills it by
+# running `kit region` with the region's name in KIT_GENERATE_REGION.
+#
+#   <path>    the region's path, relative to the repository root. Default: KIT_GENERATE_REGION.
+#   --home    makes the path relative to the home directory instead.
+#
+# Only one active module delivers a region at a given path, so kit region prints that module's
+# regions/<base>/<path>.
+#
+# Exits 0 when it prints the region, 1 when no active module delivers a region at <path>, and 2 on a usage error.
 #
 # see: bin/generate.sh, bin/release.sh
 
diff --git a/bin/kit-release.sh b/bin/kit-release.sh
index 2962ed0..ec85127 100755
--- a/bin/kit-release.sh
+++ b/bin/kit-release.sh
@@ -2,21 +2,25 @@
 # kit-release - verify a release tag, pack a checkout as a release, publish it, and retire pre-releases (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The kit releasing itself, as verbs a workflow step or a desk calls alike:
+# kit release verify <tag> | pack <tag> [<directory>] | publish <tag> | retire [<branch>]
 #
-#   verify <tag>              the tag is release/<major>.<minor>.<patch>, on the default branch, or the same with
-#                             a -<suffix>, a pre-release, on a commit off it; refused otherwise, naming why
-#   pack <tag> [<directory>]  kit-<version>.tar.gz and its .sha256 in <directory>, the current one by default:
-#                             one directory kit-<version>/ with bin/, modules/, and the version stamped in
-#   publish <tag>             pack, then a GitHub release carrying both files, marked pre-release for a suffix.
-#                             A release is published by the runner alone, from the release workflow a pushed
-#                             tag starts; a desk may publish a pre-release
-#   retire [<branch>]         delete every pre-release whose commit no remaining branch reaches, after <branch>
-#                             was deleted; the branch is the runner's delete event when none is given. A
-#                             pre-release merged by a merge commit stays reachable from the default branch and
-#                             is kept; a squash merge frees it.
+# Releases the kit itself. The release workflows and the root checkout (the desk) run the same subcommands.
 #
-# A release is permanent and immutable; only a pre-release is ever retired.
+#   verify <tag>              checks the tag. A release tag is release/<major>.<minor>.<patch>, on the default
+#                             branch. A pre-release tag adds -<suffix>, and is on a commit off the default
+#                             branch. Any other tag is refused, with the reason.
+#   pack <tag> [<directory>]  writes kit-<version>.tar.gz and its .sha256 to <directory> (default: the current
+#                             directory). The tarball holds one directory, kit-<version>/, with bin/, modules/,
+#                             and a version file.
+#   publish <tag>             packs, then creates a GitHub release with both files. A tag with a suffix is marked
+#                             pre-release. Only a runner publishes a release, from the release workflow that a
+#                             pushed tag starts. A desk may publish a pre-release.
+#   retire [<branch>]         deletes every pre-release whose commit no remaining branch reaches. It runs after
+#                             <branch> is deleted. Default: the branch in the runner's delete event. A pre-release
+#                             merged by a merge commit stays reachable from the default branch, so it is kept. A
+#                             squash merge leaves it unreachable, so it is deleted.
+#
+# A release is permanent and never changes. Only a pre-release is ever retired.
 #
 # see: .github/workflows/release.yml, .github/workflows/retire-pre-releases.yml
 
@@ -27,14 +31,14 @@ use git release
 
 usage() { echo "usage: kit release verify <tag> | pack <tag> [<directory>] | publish <tag> | retire [<branch>]" >&2; }
 
-# refuse-tag <message> is the one refusal: the message, the runner's error line, the summary, exit 1.
+# refuse-tag <message> prints the message as an error and to the step summary, then exits 1.
 refuse-tag() {
   error "$1"
   summary "### ❌ $1"
   exit 1
 }
 
-# tag-version <tag> prints the version a tag names, the part after release/, refusing a tag that is not one.
+# tag-version <tag> prints the tag's version, the part after release/. It refuses a tag that is not a release tag.
 tag-version() {
   local version=${1#release/}
   if [[ "$1" != release/* || ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
diff --git a/bin/kit-status.sh b/bin/kit-status.sh
index 32da89a..17994d6 100755
--- a/bin/kit-status.sh
+++ b/bin/kit-status.sh
@@ -2,6 +2,16 @@
 # kit-status - show every worktree with its branch, pull request, and state (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# kit status [--no-fetch] [--json] [--mine | --all | --owner=<login>…]
+#
+# Shows every worktree with its branch, pull request, and state. It changes nothing.
+#
+#   --no-fetch          skips the git fetch
+#   --json              prints the same facts as one JSON document
+#   --mine              shows only the pull requests the caller opened
+#   --all               shows every open pull request (the default)
+#   --owner=<login>     shows only the pull requests the named author opened; give it once or more
+#
 # see: bin/status.sh
 
 set -o errexit -o nounset -o pipefail
diff --git a/bin/kit-tidy.sh b/bin/kit-tidy.sh
index d604c9a..99e1533 100755
--- a/bin/kit-tidy.sh
+++ b/bin/kit-tidy.sh
@@ -2,6 +2,20 @@
 # kit-tidy - remove merged worktrees and gone branches (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
+# kit tidy [--dry-run]
+#
+# Removes finished worktrees under worktrees/, and deletes each local branch whose upstream is gone. A worktree is
+# finished when its pull request is merged or closed, or when it is detached, clean, and at a commit the default
+# branch already has. kit tidy also prunes git's worktree records. It never touches:
+#
+#   - the default branch
+#   - a branch checked out in a live worktree
+#   - a worktree with uncommitted changes
+#   - a detached worktree whose commit nothing else reaches
+#   - the worktree it runs in
+#
+# --dry-run prints what kit tidy would do, and changes nothing.
+#
 # see: bin/git.sh
 
 set -o errexit -o nounset -o pipefail
diff --git a/bin/kit-toolchain.sh b/bin/kit-toolchain.sh
index f1ec344..9c6a777 100755
--- a/bin/kit-toolchain.sh
+++ b/bin/kit-toolchain.sh
@@ -2,15 +2,22 @@
 # kit-toolchain - install, report, and update the tools the repository's gate runs, whatever manages them (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One verb over every declared toolchain, mise, brew, or docker, so a desk, a runner, and the delivered CI job say
-# the same thing whichever manages the tools:
+# kit toolchain list | install | outdated [--check] | update | path | run <command>…
 #
-#   list                    each declared toolchain and the file it reads
-#   install                 every toolchain's pinned tools installed
-#   outdated [--check]      one line per tool behind its source; --check fails when there is one
-#   update                  every toolchain moved to its latest, its pins and lock rewritten
-#   path                    the directories that put the tools first on PATH, one per line, for a runner's PATH
-#   run <command>…          the command with the tools: inside the container for docker, else with the path first
+# Manages the tools the gate runs, through each declared toolchain: mise, brew, or docker. The same subcommands work
+# on a developer's machine and in the delivered CI job, whichever tool manager is in use. The toolchains are the
+# `toolchains` setting in .kit/settings.yml, or else the ones whose file is present: mise.toml, Brewfile, or
+# toolchain.Dockerfile.
+#
+#   list                    prints each declared toolchain and the file it reads
+#   install                 installs every toolchain's pinned tools
+#   outdated [--check]      prints one line per tool behind its latest version. --check fails when any is behind.
+#   update                  updates every toolchain to its latest versions, and rewrites its pins and lock
+#   path                    prints the directories that put the tools first on PATH, one per line, for a runner
+#   run <command>…          runs the command with the tools: inside the container for docker, else with the
+#                           toolchains' directories first on PATH
+#
+# Exits 0 on success, 2 on a usage error, and 1 when a subcommand fails.
 #
 # see: bin/toolchain.sh, docs/toolchains.md
 
@@ -19,7 +26,7 @@ set -o errexit -o nounset -o pipefail
 source "${kit_root:?run through bin/kit}/bin/1st.sh"
 use toolchain
 
-# Every subcommand reads the declared toolchains once, so a refused declaration stops it.
+# Every subcommand reads the declared toolchains once, here, so an invalid declaration stops every subcommand.
 providers=$(toolchain:declared) || exit 1
 
 usage() { echo "usage: kit toolchain list | install | outdated [--check] | update | path | run <command>…" >&2; }
diff --git a/bin/kit-update.sh b/bin/kit-update.sh
index e190ee9..0e2b315 100755
--- a/bin/kit-update.sh
+++ b/bin/kit-update.sh
@@ -2,9 +2,26 @@
 # kit-update - move the repository, and the home directory, to the pinned release (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The previous release is the base of every merge. KIT_BASE names its root; the same release as the current
-# one is its own base; otherwise release:fetch finds or fetches it. A path left for lack of a base keeps the
-# manifest at the previous version, so the next run starts where this one stopped.
+# kit update takes no arguments. It moves the repository and the home directory from the release .kit/manifest
+# records (the previous release) to the pinned release. For each delivered file:
+#
+#   - a file new in this release is written when nothing, or the same content, is there, and refused otherwise
+#   - a merged JSON file is merged by key
+#   - a region is regenerated
+#   - a missing file is written
+#   - a file unchanged since the previous release is replaced
+#   - a file edited since the previous release gets a three-way merge, which leaves conflict markers on a conflict
+#
+# A merge by key, or a three-way merge, needs the previous release as its base. The base is the first of:
+#
+#   1. the directory KIT_BASE names
+#   2. this release, when the previous release is the same version
+#   3. the previous release, which release:fetch finds or fetches (never for an unreleased previous version)
+#
+# kit update checks that every merge has its base before it writes anything. When a base is missing, it writes
+# nothing and the manifest stays at the previous version, so the next run starts from the same place.
+#
+# Exits 0 when the update is complete, and 1 when a base is missing or a file needs to be resolved by hand.
 #
 # see: bin/release.sh
 
@@ -44,9 +61,43 @@ then
   exit 1
 fi
 
-conflicts=0
+# lacks-base <base> <path> <src> is true when updating the path needs the base release, and the base release is
+# missing.
+lacks-base() {
+  local base=$1 path=$2 src=$3 dest recorded kind
+  dest=$(release:dest "${base}" "${path}")
+  recorded=$(release:recorded "${base}" "${path}")
+  [[ -n "${recorded}" ]] || return 1
+  [[ -z "${base_root}" || -z "$(release:source-of "${base_root}" "${base}" "${path}" "${modules[@]}")" ]] || return 1
+  kind=$(release:kind "${src}" "${dest}")
+  [[ "${kind}" == merge ]] && return 0
+  [[ "${kind}" != region ]] && release:installed "${src}" "${dest}" >/dev/null 2>&1 \
+    && [[ "${recorded}" != "$(release:installed "${src}" "${dest}" | release:digest)" ]]
+}
+
+# Find every path that lacks its base before writing anything, so an update is all or nothing.
 skipped=0
 for base in $(release:bases)
+do
+  while IFS=$'\t' read -r path src
+  do
+    [[ -n "${path}" ]] || continue
+    if lacks-base "${base}" "${path}" "${src}"
+    then
+      error "$(release:dest "${base}" "${path}") cannot be updated without the base release ${previous};" \
+        "set KIT_BASE to a copy of it"
+      skipped=$(( skipped + 1 ))
+    fi
+  done < <(release:delivered "${kit_root}" "${base}" "${modules[@]}")
+done
+if (( skipped > 0 ))
+then
+  error "${skipped} path(s) stay at ${previous}, and so does the manifest; set KIT_BASE, then run: kit update"
+  exit 1
+fi
+
+conflicts=0
+for base in $(release:bases)
 do
   while IFS=$'\t' read -r path src
   do
@@ -55,18 +106,12 @@ do
     recorded=$(release:recorded "${base}" "${path}")
     if [[ -z "${recorded}" ]]
     then
-      # New in this release: written where there is nothing, or the same thing, and refused over anything else.
+      # New in this release: written when nothing, or the same content, is there, and refused otherwise.
       release:place-new "${src}" "${dest}" "new in ${current}" || conflicts=$(( conflicts + 1 ))
       continue
     fi
     previous_src=""
     [[ -n "${base_root}" ]] && previous_src=$(release:source-of "${base_root}" "${base}" "${path}" "${modules[@]}")
-    if [[ -z "${previous_src}" ]]
-    then
-      error "${dest} cannot be updated without the base release ${previous}; set KIT_BASE to a copy of it"
-      skipped=$(( skipped + 1 ))
-      continue
-    fi
     kind=$(release:kind "${src}" "${dest}")
     if [[ "${kind}" == merge ]]
     then
@@ -74,7 +119,7 @@ do
       release:place "${src}" "${dest}" "${previous_src}"
     elif [[ "${kind}" == region ]]
     then
-      # A region is what its command makes it, so it is regenerated, never merged.
+      # A region's content comes from its command, so it is regenerated, never merged.
       step "${dest}: the region regenerated"
       release:place "${src}" "${dest}"
     elif ! release:installed "${src}" "${dest}" >/dev/null 2>&1
@@ -97,11 +142,6 @@ do
   release:retire "${base_root}" "${base}" "${previous}" "${current}" "${modules[@]}"
 done
 
-if (( skipped > 0 ))
-then
-  error "${skipped} path(s) stay at ${previous}, and so does the manifest; set KIT_BASE, then run: kit update"
-  exit 1
-fi
 release:write-manifests "${modules[@]}"
 if (( conflicts > 0 ))
 then
diff --git a/bin/kit-version.sh b/bin/kit-version.sh
index 5f2e04a..a581bc0 100755
--- a/bin/kit-version.sh
+++ b/bin/kit-version.sh
@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # kit-version - print this release's version (kit verb)
 # ----------------------------------------------------------------------------------------------------------------------
+#
+# kit version takes no arguments. It prints the version of the kit that runs, or unreleased for a checkout of the
+# kit that has no version file.
 
 set -o errexit -o nounset -o pipefail
 # shellcheck source=bin/1st.sh
diff --git a/bin/policy-opa.sh b/bin/policy-opa.sh
index c264a49..5c979f8 100644
--- a/bin/policy-opa.sh
+++ b/bin/policy-opa.sh
@@ -1,12 +1,16 @@
 # shellcheck shell=bash
-# policy-opa.sh - Open Policy Agent as the policy engine: the Rego under .kit/policy decides (sourced module)
+# policy-opa.sh - the policy provider that runs Open Policy Agent over the Rego in .kit/policy (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The engine bin/policy.sh uses for `policy_engine: opa`, or where .kit/policy holds a .rego file. Every .rego
-# file there is loaded, and the set `data.kit.policy.deny` is the refusals, each a string. The facts document is
-# the input, so a rule reads input.branch, input.commits, input.change, and input.policy, the patterns with the
-# kit's defaults filled in. opa is the requirement, pinned by the repository's toolchain like any tool its gate
-# runs. The policy-opa module delivers .kit/policy/kit.rego, the patterns engine's rules in Rego, to build on.
+# bin/policy.sh uses this provider when the policy_engine setting is opa, or when the setting is not set and
+# .kit/policy/ contains a .rego file.
+#
+# opa loads every .rego file in .kit/policy/. Each string in the set data.kit.policy.deny is a refusal. The input
+# is the facts document, so a rule reads input.branch, input.commits, input.change, and input.policy (the
+# patterns, with the kit's defaults filled in).
+#
+# The repository's toolchain must pin opa, like any tool its gate runs. The policy-opa module delivers
+# .kit/policy/kit.rego, the patterns provider's rules written in Rego, to build on.
 
 policy-opa:deny() {
   local input=$1 out
diff --git a/bin/policy-patterns.sh b/bin/policy-patterns.sh
index 6b60eff..1af24b6 100644
--- a/bin/policy-patterns.sh
+++ b/bin/policy-patterns.sh
@@ -1,10 +1,10 @@
 # shellcheck shell=bash
-# policy-patterns.sh - the default policy engine: each subject matched against its pattern in bash (sourced module)
+# policy-patterns.sh - the default policy provider: matches each subject against its pattern in bash (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The engine bin/policy.sh uses unless the repository names another. It needs no tool: each rule of the facts'
-# policy object is matched with bash's =~ against its subject, and a rule whose pattern is empty is off. The
-# refusals are worded exactly as the policy-opa module's Rego words them, so either engine says the same thing.
+# bin/policy.sh uses this provider unless the repository picks another. It needs no tool. It matches each rule in
+# the facts' policy object against its subject with bash's =~. A rule with an empty pattern is off. The refusals
+# use the same wording as the policy-opa module's Rego, so both providers print the same messages.
 
 # policy-patterns:deny <input-file> prints one refusal per subject that does not match its pattern.
 policy-patterns:deny() {
diff --git a/bin/policy.sh b/bin/policy.sh
index 4030e2f..82d32da 100644
--- a/bin/policy.sh
+++ b/bin/policy.sh
@@ -1,34 +1,56 @@
 # shellcheck shell=bash
-# policy.sh - the seam over what the loop's names must be: the facts, the rules, and the engine (sourced module)
+# policy.sh - one interface to the engine that checks branch names, commit subjects, and change titles (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# What a branch, a commit subject, or a change's title may be is a policy, and a policy is checked, not described.
-# The seam has three parts:
+# A policy sets what a branch name, a commit subject, or a change title may be. kit policy enforces it: it gathers
+# the facts, reads the rules, and calls a provider (the policy engine) to list every refusal. A provider is
+# policy-<name>.sh in this directory, whose functions are named policy-<name>:<call>.
 #
-#   the facts     policy:input gathers one JSON document: the branch, the default branch, the commits past the
-#                 fork, the change on the branch with its title and body, and the policy settings with the kit's
-#                 defaults filled in. `kit policy --input` prints it, so a rule can be written against it.
-#   the rules     `policy:` in .kit/settings.yml, one extended regular expression per subject:
-#                   branch            the branch's name
-#                   commit_subject    every commit's subject past the fork, merges aside
-#                   change_title      the open change's title
-#                 A subject absent takes the kit's default below; an empty pattern turns that rule off.
-#   the engine    policy-<name>.sh beside this file answers `deny <input-file>`, one refusal per line:
-#                   patterns          the default: each pattern matched in bash, no tool needed
-#                   opa               Open Policy Agent over the Rego under .kit/policy/, package kit.policy, rule
-#                                     deny; chosen by `policy_engine: opa`, or by a .rego file there
-#                 Both read the same document, so a rule a pattern cannot say is written in Rego beside the
-#                 patterns, and the policy-opa module delivers the patterns themselves as Rego to start from.
+# The facts are one JSON document, built by policy:input. `kit policy --input` prints it, to write a rule against.
+# It contains:
 #
-# A pattern is matched as an extended regular expression by bash and as RE2 by OPA; the two agree on the common
-# subset, character classes, anchors, alternation, and counted repetition, which is the subset to write in.
+#   - the branch and the default branch
+#   - the commits past the fork from the default branch, merges excluded
+#   - the open change on the branch, with its title and body
+#   - the policy settings, with the kit's defaults filled in
+#
+# The rules are the `policy:` map in .kit/settings.yml, one extended regular expression per subject. A subject
+# that is not set uses the kit's default below. An empty pattern turns that rule off.
+#
+#   branch            the branch's name
+#   commit_subject    the subject of every commit past the fork, merges excluded
+#   change_title      the open change's title
+#
+# The provider is chosen by:
+#
+#   1. the `policy_engine` setting in .kit/settings.yml, if set
+#   2. otherwise opa, if .kit/policy/ contains a .rego file
+#   3. otherwise patterns
+#
+# The providers:
+#
+#   patterns          the default: matches each pattern in bash, with no tool needed
+#   opa               runs Open Policy Agent over the Rego in .kit/policy/ (package kit.policy, rule deny)
+#
+# Every provider implements one call:
+#
+#   deny <input-file>       one refusal per line for the facts document in <input-file>
+#
+# Both providers read the same facts document. A rule that a pattern cannot express can be written in Rego
+# alongside the patterns. The policy-opa module delivers the default patterns as Rego, to start from.
+#
+# Bash matches a pattern as an extended regular expression; OPA matches it as RE2. Write patterns in the subset
+# both support: character classes, anchors, alternation, and counted repetition.
 #
 # see: docs/policy.md
 
 use release yaml git
 
-# The kit's defaults, the loop's own names from .kit/1st.md: a branch is <key>-<slug>, as kit issue makes it; a
-# commit subject opens with its issue's reference, #7 or AB#4521; a change's title is a line of at most 120.
+# The kit's defaults follow the workflow in .kit/1st.md:
+#
+#   - a branch is <key>-<slug>, as kit issue makes it
+#   - a commit subject starts with its issue's reference, #7 or AB#4521
+#   - a change title is one line of at most 120 characters
 declare -gr policy_default_branch='^[a-z0-9]+-[a-z0-9][a-z0-9-]*$'
 declare -gr policy_default_commit_subject='^([A-Z]+)?#[0-9]+ [^ ]'
 declare -gr policy_default_change_title='^[^[:cntrl:]]{1,120}$'
@@ -58,17 +80,19 @@ policy:rules() {
     '{branch: $branch, commit_subject: $commit_subject, change_title: $change_title}'
 }
 
-# policy:branch prints the branch under check: the change's head on a runner, else the current branch, else
-# nothing for a detached checkout.
+# policy:branch prints the branch to check: the change's source branch on a CI runner, otherwise the current
+# branch, or nothing on a detached HEAD.
 policy:branch() {
   local branch=${GITHUB_HEAD_REF:-${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:-}}
   [[ -n "${branch}" ]] || branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
   printf '%s\n' "${branch}"
 }
 
-# policy:input prints the facts document the file header describes. The commits are those past the fork from the
-# default branch at origin; where the fork cannot be found, a shallow clone, they are omitted with a warning
-# rather than guessed. The change is read through the forge, and omitted where no forge or no change answers.
+# policy:input prints the facts document described in the file header. The commits are those past the fork from
+# origin's default branch. When the fork point is missing, as in a shallow clone, it warns and omits the commits
+# instead of guessing. The change is read from the forge (GitHub or GitLab). It is omitted when there is no forge
+# or no open change. On the default branch or a detached HEAD, the branch is null and there are no commits or
+# change.
 policy:input() {
   local default_branch branch commits='[]' change='null' rules number title body
   rules=$(policy:rules) || return 1
@@ -100,8 +124,8 @@ policy:input() {
       change: $change, policy: $policy}'
 }
 
-# policy:engine prints the engine: the policy_engine setting, else opa where .kit/policy holds a .rego file, else
-# patterns. An engine the kit does not carry is refused by name.
+# policy:engine prints the provider's name, chosen as the file header describes. It fails, naming the engine,
+# when the kit has no provider by that name.
 policy:engine() {
   local engine
   engine=$(release:setting policy_engine)
@@ -120,7 +144,8 @@ policy:engine() {
   printf '%s\n' "${engine}"
 }
 
-# policy:deny <input-file> prints every refusal the engine finds in the facts, one per line, sorted.
+# policy:deny <input-file> prints every refusal the provider finds in the facts, one per line, sorted and without
+# duplicates.
 policy:deny() {
   local engine
   engine=$(policy:engine) || return 1
diff --git a/bin/release.sh b/bin/release.sh
index 5cc946a..2f29d5b 100644
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -1,28 +1,49 @@
 # shellcheck shell=bash
+# release.sh - reads a release's modules, renders templates and regions, merges JSON, writes manifests (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
 # shellcheck disable=SC2016  # jq filters name jq variables with $, in single quotes on purpose
 # shellcheck disable=SC2154  # kit_root is exported by bin/kit
-# release.sh - the release's modules, the one merge rule, the templates, and the manifests (sourced module)
-# ----------------------------------------------------------------------------------------------------------------------
 #
-# A release is bin/ and modules/. Each modules/<name>/ is a module: module.yml, its metadata; files/<base>/, mirrored at
-# the base's root; templates/<base>/, with @key@ rendered from the repository's settings, then mirrored the same way;
-# and regions/<base>/, rendered the same way, each file placed as a region the kit owns inside a file the repository
-# owns, between a bare kit:generate line and a kit:end line that name the path, so the rest of that file stays the
-# repository's and kit generate makes the region what kit region prints. A repository defines modules of its own the
-# same way under .kit/modules/<name>/, and a name is looked up in the release first, then there. Two bases: repo, the
-# repository root, recorded in .kit/manifest; and home, the user's home directory, recorded in ~/.kit/manifest, which
-# every repository on the desk shares. A destination ending in .json is merged by key, the kit owning only the entries
-# it writes, and a region is regenerated, never merged. The repository's choices live in .kit/settings.yml, which the
-# kit reads and never writes. docs/modules.md is the format's description.
+# A release is bin/ and modules/. Each modules/<name>/ is a module, which contains:
+#
+#   module.yml          the module's metadata
+#   files/<base>/       files copied to the base's root, at the same paths
+#   templates/<base>/   files whose @key@ placeholders are filled from the repository's settings, then copied the
+#                       same way
+#   regions/<base>/     files rendered like templates, each placed as a region inside a file the repository owns
+#
+# A region is the part of a repository's file that the kit owns. It sits between a bare kit:generate line and an
+# end line, both naming the path. The rest of the file belongs to the repository. kit generate replaces the
+# region's content with what kit region prints.
+#
+# A repository can define its own modules the same way, under .kit/modules/<name>/. A module name is looked up in
+# the release first, then there.
+#
+# The bases a module delivers to:
+#
+#   repo    the repository root, recorded in .kit/manifest
+#   home    the user's home directory, recorded in ~/.kit/manifest, which every repository on the machine shares
+#
+# How a delivered file is placed:
 #
-# Every function reads a release from a root, kit_root by default, which bin/kit exports. bin/kit also moves to
-# the repository root, so .kit/manifest and every repo path here are relative to it. Every sort and comm here
-# collates in the C locale, so an order written on one machine is the order read on another.
+#   - a destination ending in .json (except *.schema.json) is merged by key; the kit owns only the entries it
+#     writes
+#   - a region is regenerated, never merged
+#   - every other file is copied
+#
+# The repository's choices are in .kit/settings.yml. The kit reads that file and never writes it.
+#
+# Every function reads a release from a root directory: kit_root by default, which bin/kit exports. bin/kit also
+# changes to the repository root, so .kit/manifest and every repo path here are relative to it. Every sort and
+# comm here uses the C locale, so an order written on one machine reads the same on another.
+#
+# see: docs/modules.md
 
 use yaml
 
-# release:unreleased prints the version of a checkout: the release workflow stamps a version file, a checkout
-# has none, and this is the one version kit update never fetches.
+# release:unreleased prints `unreleased`, the version of a kit checkout. The release workflow
+# (.github/workflows/release.yml) writes a version file into each release; a checkout has none. kit update never
+# fetches this version.
 release:unreleased() { printf 'unreleased\n'; }
 
 # release:version prints this release's version.
@@ -30,12 +51,13 @@ release:version() {
   cat "${kit_root}/version" 2>/dev/null || release:unreleased
 }
 
-# release:bases prints the destinations a module may deliver to: the subdirectories of files/, templates/, and
-# regions/.
+# release:bases prints the bases a module can deliver to. Each base is a subdirectory name under files/,
+# templates/, and regions/.
 release:bases() { printf 'repo\nhome\n'; }
 
-# release:base-root <base> prints the directory the base's files are mirrored at: the repository root, which the
-# verbs run from, or the home directory, KIT_HOME when set so a test can stand in for it.
+# release:base-root <base> prints the directory a base's files are copied to: `.` (the repository root, where the
+# verbs run) for repo, and the home directory for home. KIT_HOME, when set, replaces the home directory, so a test
+# can use a stand-in.
 release:base-root() {
   case "$1" in
     (repo) printf '.\n' ;;
@@ -46,7 +68,7 @@ release:base-root() {
   esac
 }
 
-# release:dest <base> <path> prints where a delivered path lands.
+# release:dest <base> <path> prints where a delivered path is written.
 release:dest() {
   if [[ "$1" == repo ]]
   then printf '%s\n' "$2"
@@ -57,17 +79,17 @@ release:dest() {
 # release:manifest <base> prints the base's manifest: .kit/manifest in the repository, ~/.kit/manifest for home.
 release:manifest() { release:dest "$1" .kit/manifest; }
 
-# release_local is where a repository keeps modules of its own: .kit/modules/<name>/, in the release's shape.
+# release_local is the root of the repository's own modules, .kit/modules/<name>/, laid out like the release's.
 declare -gr release_local=.kit
 
-# release:settings prints the repository's settings file, which the kit reads and never writes.
+# release:settings prints the path of the repository's settings file.
 release:settings() { printf '.kit/settings.yml\n'; }
 
 # release:setting <key> prints the value of one top-level setting, or nothing.
 release:setting() { yaml:value "$(release:settings)" "$1"; }
 
-# release:modules [<root>] prints the modules in reach: every modules/<name>/ with a module.yml under the release
-# at <root>, and under .kit/modules/ in the repository.
+# release:modules [<root>] prints the modules in reach: every modules/<name>/ that contains a module.yml, in the
+# release at <root> and in the repository's .kit/modules/.
 release:modules() {
   local root=${1:-${kit_root}} dir
   for dir in "${root}" "${release_local}"
@@ -77,8 +99,8 @@ release:modules() {
   done | LC_ALL=C sort --unique
 }
 
-# release:home <root> <module> prints where the module lives: the release at <root> when it carries the module,
-# else the repository's own .kit, so a path under it is <home>/modules/<module>/.
+# release:home <root> <module> prints the directory that contains the module: <root> when the release has the
+# module, otherwise the repository's .kit. The module's files are under <home>/modules/<module>/.
 release:home() {
   if [[ -f "$1/modules/$2/module.yml" || ! -f "${release_local}/modules/$2/module.yml" ]]
   then printf '%s\n' "$1"
@@ -86,7 +108,7 @@ release:home() {
   fi
 }
 
-# release:origin <root> <module> prints "release" or "repository", where the module comes from.
+# release:origin <root> <module> prints where the module comes from: "release" or "repository".
 release:origin() {
   if [[ "$(release:home "$1" "$2")" == "$1" ]]
   then printf 'release\n'
@@ -103,7 +125,7 @@ release:description() { yaml:value "$(release:meta "$1" "$2")" description; }
 # release:depends <root> <module> prints the modules this one depends on, one per line.
 release:depends() { yaml:list "$(release:meta "$1" "$2")" depends; }
 
-# release:default-modules <root> prints the modules active unless removed: those whose default is true.
+# release:default-modules <root> prints the modules whose default is true. They are active unless removed.
 release:default-modules() {
   local module
   for module in $(release:modules "$1")
@@ -113,7 +135,7 @@ release:default-modules() {
   return 0
 }
 
-# release:require-modules <root> <name>… refuses a module the release does not carry, naming the ones it does.
+# release:require-modules <root> <name>… fails on a module that is not in reach, and lists the modules that are.
 release:require-modules() {
   local root=$1 module
   shift
@@ -128,9 +150,9 @@ release:require-modules() {
   done
 }
 
-# release:resolve <root> <name>… prints the named modules and everything they depend on, each once: a module
-# after the modules it depends on, and alphabetical where that leaves a choice, so the order is the same on
-# every machine. A cycle is refused.
+# release:resolve <root> <name>… prints the named modules and all their dependencies, each once. Each module
+# comes after the modules it depends on. Ties are broken alphabetically, so the order is the same on every
+# machine. It fails on a dependency cycle.
 release:resolve() {
   local root=$1 module dep ready placed_count=0
   shift
@@ -186,9 +208,15 @@ release:dependents() {
   done
 }
 
-# release:validate <root> <module> refuses metadata the schema would refuse, as far as bash can tell without a
-# validator: a key the kit does not know, a default that is not true or false, a dependency on a module the
-# release lacks. The gate validates against modules/module.schema.json in full.
+# release:validate <root> <module> fails on metadata that the schema rejects, as far as bash can check without a
+# validator:
+#
+#   - a key the kit does not know
+#   - a missing description
+#   - a default that is not true or false
+#   - a dependency on a module that is not in reach
+#
+# The gate validates against modules/module.schema.json in full.
 release:validate() {
   local root=$1 module=$2 meta key value dep
   meta=$(release:meta "${root}" "${module}")
@@ -224,7 +252,8 @@ release:validate() {
 }
 
 # release:expectations <root> <module>… prints "<path>\x1f<pattern>\x1f<remedy>" for each line the modules expect
-# of a file the repository owns, the include a format composes by: lefthook's extends, just's import.
+# in a file the repository owns. Such a line is the include that pulls in the kit's file, such as lefthook's
+# extends or just's import.
 release:expectations() {
   local root=$1 module
   shift
@@ -234,9 +263,9 @@ release:expectations() {
   done
 }
 
-# release:unmet <root> <module>… prints the remedy of every expectation the repository does not meet, one per
-# line: its file is missing, or no line of it matches the pattern, an extended regular expression. The kit
-# writes nothing into such a file; it only says what is missing.
+# release:unmet <root> <module>… prints the remedy for each expectation the repository does not meet, one per
+# line. An expectation is unmet when its file is missing, or when no line in the file matches its pattern (an
+# extended regular expression). The kit never writes to such a file; it only reports what is missing.
 release:unmet() {
   local root=$1 path pattern remedy
   shift
@@ -251,10 +280,15 @@ release:unmet() {
   return 0
 }
 
-# release:validate-settings refuses a settings file the schema would refuse, as far as bash can tell: a key the
-# kit does not know, a require_signing that is not true or false, an answer key outside [a-z_]. The gate
-# validates this repository's against .kit/settings.schema.json in full; the schema is delivered so an editor
-# can do the same anywhere.
+# release:validate-settings fails on a settings file that the schema rejects, as far as bash can check:
+#
+#   - a key the kit does not know
+#   - a require_signing that is not true or false
+#   - an answer key with characters outside [a-z_]
+#   - a tracker without a prefix (letters and an optional #) or without a provider
+#
+# The gate validates this repository's settings against .kit/settings.schema.json in full. The kit delivers the
+# schema so an editor can validate against it anywhere.
 release:validate-settings() {
   local settings key value
   settings=$(release:settings)
@@ -291,10 +325,14 @@ release:validate-settings() {
   done < <(yaml:records "${settings}" trackers prefix provider)
 }
 
-# release:context <root> <module> prints "<key>\t<value>" for every key a template or region of the module may
-# use: the module's defaults under its answers:, as <key> and answers.<key>; then the whole of .kit/settings.yml,
-# a top-level scalar as <key>, a map's entries as <map>.<name>, and the answers map's as <name> too. A later
-# line overrides an earlier one, so the repository's answer wins over the module's default.
+# release:context <root> <module> prints "<key>\t<value>" for every key a template or region of the module can
+# use. The keys come from:
+#
+#   1. the module's defaults under answers: in module.yml, as <key> and as answers.<key>
+#   2. .kit/settings.yml: each top-level scalar as <key>, each map entry as <map>.<name>, and each entry of the
+#      answers map also as <name>
+#
+# A later source overrides an earlier one, so the repository's answer wins over the module's default.
 release:context() {
   local settings key name value
   settings=$(release:settings)
@@ -318,8 +356,8 @@ release:context() {
   } | awk -F '\t' '{ a[$1] = $2 } END { for (k in a) print k "\t" a[k] }'
 }
 
-# release:tmp prints a directory for this process's rendered templates, made once and removed at exit. The
-# rendering happens in release:render-all, which every verb runs before it reads a release.
+# release:tmp prints a directory for this process's rendered templates. It is created on first use and removed
+# at exit. release:render-all does the rendering; every verb runs it before reading a release.
 release:tmp() {
   if [[ -z "${release_tmp:-}" ]]
   then
@@ -330,11 +368,12 @@ release:tmp() {
   printf '%s\n' "${release_tmp}"
 }
 
-# release:render <root> <module> <kind> <base> renders the module's templates or regions, the <kind>, for <base>
-# once per process and prints the directory holding them, or prints nothing where the module has none. The
-# directory keeps the modules/<module>/<kind>/<base> shape, so a rendered region still reads as one. A key is
-# written @key@, autoconf's form, which neither bash's ${var} nor GitHub's ${{ }} can be mistaken for, and may
-# be dotted, @answers.key@; one with no value refuses, naming the key.
+# release:render <root> <module> <kind> <base> renders the module's <kind> (templates or regions) for <base>, once
+# per process, and prints the directory that contains the result. It prints nothing when the module has none. The
+# directory keeps the modules/<module>/<kind>/<base> layout, so a rendered region is still recognized as a region.
+#
+# A placeholder is written @key@ (autoconf's form), which cannot be confused with bash's ${var} or GitHub's
+# ${{ }}. A key can be dotted: @answers.key@. A key with no value fails, and the error names the key.
 release:render() {
   local root=$1 module=$2 kind=$3 base=$4 source out key value text file rel map
   local -A answer=()
@@ -370,9 +409,14 @@ release:render() {
   printf '%s\n' "${out}"
 }
 
-# release:render-all <root> <module>… makes the release at <root> ready to read for the named modules: it refuses
-# a module the release lacks, validates every module the release carries, refuses a base the kit does not deliver
-# to, renders the named modules' templates and regions, and refuses a link to nothing among the delivered files.
+# release:render-all <root> <module>… prepares the release at <root> for the named modules. In order, it:
+#
+#   1. validates the settings
+#   2. fails on a named module that is not in reach
+#   3. validates every module in reach
+#   4. fails on a base the kit does not deliver to
+#   5. renders the named modules' templates and regions
+#   6. fails on a delivered file that is a link to nothing, and on regions that release:regions-apart rejects
 release:render-all() {
   local root=$1 module kind base
   shift
@@ -413,8 +457,9 @@ release:render-all() {
   done
 }
 
-# release:regions-apart <root> <base> <module>… refuses a region path two of the modules both deliver, since one
-# file holds one kit region, and a region in a file whose comment syntax the kit does not know.
+# release:regions-apart <root> <base> <module>… fails when two of the modules deliver a region to the same path (a
+# file can have only one kit region), or when a region is in a kind of file whose comment syntax the kit does not
+# know.
 release:regions-apart() {
   local root=$1 base=$2 module home file rel owner
   shift 2
@@ -443,7 +488,7 @@ release:regions-apart() {
   done
 }
 
-# release:layers <root> <base> <module>… prints the directories mirrored at the base's root, in module order: each
+# release:layers <root> <base> <module>… prints the directories copied to the base's root, in module order: each
 # module's files/<base>, its rendered templates/<base>, and its rendered regions/<base>.
 release:layers() {
   local root=$1 base=$2 module home kind rendered
@@ -461,9 +506,14 @@ release:layers() {
   return 0
 }
 
-# release:kind <source> <path> prints how the content is placed: region for a source under a module's
-# regions/<base>/, merge for a .json destination, copy otherwise. A source is a region by its last modules/
-# segment, so a checkout under a directory named modules reads the same as one anywhere else.
+# release:kind <source> <path> prints how the content is placed:
+#
+#   region   the source is under a module's regions/<base>/
+#   merge    the destination is a merged .json file (see release:merged)
+#   copy     anything else
+#
+# The region test looks only at the source's last modules/ segment, so a checkout under a directory named modules
+# works the same as one anywhere else.
 release:kind() {
   if [[ "${1##*/modules/}" =~ ^[^/]+/regions/(repo|home)/ ]]
   then printf 'region\n'
@@ -473,9 +523,7 @@ release:kind() {
   fi
 }
 
-# release:region-name <dest> prints the region's name, which is the path relative to the base's root, and
-# release:region-command the command behind it: nothing under the repository, where the bare directive means
-# `kit region <name>`, and `kit region --home <name>` under the home directory, which the bare form cannot say.
+# release:region-name <dest> prints the region's name: the path relative to the base's root.
 release:region-name() {
   local home
   home=$(release:base-root home)
@@ -484,6 +532,10 @@ release:region-name() {
   else printf '%s\n' "$1"
   fi
 }
+
+# release:region-command <dest> prints the command that generates the region. Under the repository it prints
+# nothing, because the bare directive means `kit region <name>`. Under the home directory it prints
+# `kit region --home <name>`, which the bare form cannot express.
 release:region-command() {
   local home
   home=$(release:base-root home)
@@ -492,10 +544,10 @@ release:region-command() {
   fi
 }
 
-# release:region-markers <dest> prints the region's two lines in the file's own comment syntax, by its extension,
-# an HTML comment, a double slash, a double dash, or a hash: the directive that opens it, `kit:generate <name>`
-# with the command in backticks where there is one, and the end marker, `kit:end <name>`. A kind of file with no
-# comment syntax the kit knows is refused where the module is read, in release:render-all.
+# release:region-markers <dest> prints the region's two marker lines in the file's comment syntax, chosen by
+# extension: an HTML comment, //, --, or #. The first line is the directive, `kit:generate <name>`, followed by
+# the command in backticks when there is one. The second is the end marker, `kit:end <name>`. A kind of file with
+# no comment syntax the kit knows is rejected earlier, by release:render-all, when it reads the module.
 release:region-markers() {
   local open close name command
   case "${1##*.}" in
@@ -511,7 +563,8 @@ release:region-markers() {
     "${open}" "${name}" "${close}"
 }
 
-# release:region-known <path> is true where the kit knows the file's comment syntax, so a region can be marked.
+# release:region-known <path> succeeds when the kit knows the file's comment syntax, so a region can be marked in
+# it.
 release:region-known() {
   case "${1##*/}" in
     (*.json | *.jsonc | *.json5) return 1 ;;
@@ -525,8 +578,9 @@ release:region-known() {
   esac
 }
 
-# release:target <path> prints the file a write to <path> lands in: the path, or what a symlink there points at,
-# so a repository that keeps AGENTS.md or a settings file as a link into another directory keeps its link.
+# release:target <path> prints the file that a write to <path> changes: the path itself, or the target of a
+# symlink there. A repository that keeps AGENTS.md or a settings file as a link into another directory keeps the
+# link.
 release:target() {
   if [[ -L "$1" ]]
   then readlink -f "$1"
@@ -534,8 +588,8 @@ release:target() {
   fi
 }
 
-# release:region-has <dest> is true when the file carries the region's directive; a directive with no end
-# marker is refused, naming the file, since a write would drop everything after it.
+# release:region-has <dest> succeeds when the file contains the region's directive. A directive with no end
+# marker fails (status 2) and names the file, because a write would drop everything after the directive.
 release:region-has() {
   local path=$1 begin end
   [[ -f "${path}" ]] || return 1
@@ -548,8 +602,8 @@ release:region-has() {
   fi
 }
 
-# release:region-read <dest> prints the region's content, between its directive and its end marker, and fails
-# where the file or the region is absent.
+# release:region-read <dest> prints the region's content, between its directive and its end marker. It fails
+# when the file or the region is missing.
 release:region-read() {
   local path=$1 begin end
   release:region-has "$1" || return $?
@@ -557,9 +611,12 @@ release:region-read() {
   awk -v b="${begin}" -v e="${end}" '$0 == e { on = 0 } on { print } $0 == b { on = 1 }' "${path}"
 }
 
-# release:region-write <dest> <content-file> makes the region what its command makes it, which is the content:
-# between the directive and the end marker where the file carries them, appended after a blank line where it
-# does not, and as the whole file where there is none.
+# release:region-write <dest> <content-file> sets the region's content to <content-file>, the output of the
+# region's command. It writes the content:
+#
+#   - between the directive and the end marker, when the file has them
+#   - after a blank line at the end of the file, when the file has no region
+#   - as the whole file, when there is no file
 release:region-write() {
   local path content=$2 begin end status=0
   path=$(release:target "$1")
@@ -589,8 +646,8 @@ release:region-write() {
   mv "${path}.kit-new" "${path}"
 }
 
-# release:region-remove <dest> takes the region, its directive, and its end marker out, and the blank line
-# before it; a file left empty is removed.
+# release:region-remove <dest> removes the region, its directive, its end marker, and the blank line before it.
+# A file left empty is deleted.
 release:region-remove() {
   local path begin end
   path=$(release:target "$1")
@@ -610,8 +667,9 @@ release:region-remove() {
 }
 
 # release:delivered <root> <base> <module>… prints "<path>\t<source>" for every path under the base's root that
-# the release at <root> delivers for those modules, sorted by path, the last layer winning. A symlink is a source
-# only when it points at a file; a dangling one is refused here, where it is found.
+# the release at <root> delivers for those modules, sorted by path. When layers deliver the same path, the last
+# layer wins. A symlink counts as a source only when it points at a file. A dangling symlink fails here, where it
+# is found.
 release:delivered() {
   local layer path src
   while IFS= read -r layer
@@ -638,8 +696,8 @@ release:source-of() {
   release:delivered "${root}" "${base}" "$@" | awk -F '\t' -v p="${path}" '$1 == p { print $2 }'
 }
 
-# release:paths-beyond <root> <base> <before> <after> prints the paths the module set <after> delivers under the
-# base that <before> does not; each set is one space-separated word.
+# release:paths-beyond <root> <base> <before> <after> prints the paths under the base that the module set <after>
+# delivers and <before> does not. Each set is passed as one space-separated word.
 release:paths-beyond() {
   local root=$1 base=$2
   local -a before after
@@ -649,13 +707,17 @@ release:paths-beyond() {
     <(release:delivered "${root}" "${base}" "${after[@]}" | cut -f 1)
 }
 
-# release:merged <path> is true for a destination that is merged by key rather than copied: a .json file that is
-# a settings file, which every .json is here except a schema, *.schema.json.
+# release:merged <path> succeeds for a destination that is merged by key instead of copied: a .json settings
+# file. Every .json file the kit delivers is a settings file, except a schema (*.schema.json).
 release:merged() { [[ "$1" == *.json && "$1" != *.schema.json ]]; }
 
-# release:fetch <version> prints the root of that release, fetching it if need be: the kit's cache first, then a
-# mise install if mise is here, then the release's public tarball with curl, unpacked into the cache. The version
-# comes from a manifest, so it is held to a version's shape before it is used in a path.
+# release:fetch <version> prints the root of that release, fetching it if needed. It tries, in order:
+#
+#   1. the kit's cache
+#   2. a copy installed by mise, when mise is present
+#   3. the release's public tarball, downloaded with curl and unpacked into the cache
+#
+# The version comes from a manifest, so it must have a version's shape before it is used in a path.
 release:fetch() {
   local version=$1 root cache fresh
   if [[ ! "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]]
@@ -693,7 +755,7 @@ release:fetch() {
   printf '%s\n' "${cache}"
 }
 
-# release:among <name> <name>… is true when the first name is among the rest.
+# release:among <name> <name>… succeeds when the first name is one of the rest.
 release:among() {
   local needle=$1 item
   shift
@@ -714,7 +776,14 @@ release:without() {
   done
 }
 
-# The merge, as jq. The parameters are values ($), not filters, so each is read once at the right level.
+# The JSON merge functions, in jq:
+#
+#   merge($cur; $base; $new)   applies the release's $new over the current $cur, key by key. For an array, it keeps
+#                              the current entries that were not in the previous release's $base, then adds $new's
+#   unmerge($cur; $base)       removes $base's array entries from $cur, key by key; scalar values stay
+#   holds($cur; $new)          true when $cur contains every key, array entry, and value in $new
+#
+# The parameters are values ($name), not filters, so each is evaluated once, at the right level.
 release_jq='
   def merge($cur; $base; $new):
     if ($new | type) == "object" then
@@ -734,8 +803,8 @@ release_jq='
     else $cur == $new end;
 '
 
-# release:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>, making it if
-# missing.
+# release:json-write <path> <filter> [<jq option>…] rewrites the JSON at <path> through <filter>. It creates the
+# file, as {}, when it is missing.
 release:json-write() {
   local path filter=$2
   path=$(release:target "$1")
@@ -746,13 +815,13 @@ release:json-write() {
   mv "${path}.kit-new" "${path}"
 }
 
-# release:json-holds <path> <source> is true when the JSON at <path> carries every entry the release's <source>
-# writes.
+# release:json-holds <path> <source> succeeds when the JSON at <path> contains every entry that the release's
+# <source> writes.
 release:json-holds() {
   jq --exit-status "${release_jq} holds(.; \$new[0])" --slurpfile new "$2" "$1" >/dev/null
 }
 
-# release:digest prints the sha256 of stdin, by whichever tool the machine carries.
+# release:digest prints the sha256 of stdin, using sha256sum or shasum, whichever the machine has.
 release:digest() {
   if command -v sha256sum >/dev/null 2>&1
   then
@@ -762,8 +831,8 @@ release:digest() {
   fi
 }
 
-# release:place <source> <path> [<base-source>] puts the release's content at <path>: a merge for .json, the
-# region for a region source, else a copy that keeps the source's mode.
+# release:place <source> <path> [<base-source>] writes the release's content to <path>. It merges a .json file,
+# writes the region for a region source, and otherwise copies the file, keeping the source's mode.
 release:place() {
   local src=$1 path=$2 base=${3:-/dev/null}
   case "$(release:kind "${src}" "${path}")" in
@@ -781,8 +850,8 @@ release:place() {
   esac
 }
 
-# release:installed <source> <path> prints what the repository holds of the release's content at <path>: the
-# file, or the region's content; nothing, failing, where there is none.
+# release:installed <source> <path> prints the repository's copy of the release's content at <path>: the file,
+# or the region's content. It prints nothing and fails when there is none.
 release:installed() {
   local src=$1 path=$2
   case "$(release:kind "${src}" "${path}")" in
@@ -791,8 +860,8 @@ release:installed() {
   esac
 }
 
-# release:holds <source> <path> is true when the repository holds the release's content at <path>: the same
-# file, every merged entry, or the same region.
+# release:holds <source> <path> succeeds when the repository has the release's content at <path>: the same file,
+# every merged entry, or the same region.
 release:holds() {
   local src=$1 path=$2
   case "$(release:kind "${src}" "${path}")" in
@@ -801,9 +870,15 @@ release:holds() {
   esac
 }
 
-# release:place-new <source> <path> [<label>] places content the repository did not record: where there is
-# nothing, or the same thing, a .json to merge into, or a file to carry a region. A region already there is made
-# what its command makes it. A different file is refused, named, and left as it is.
+# release:place-new <source> <path> [<label>] places content the repository has not recorded. It writes the
+# content when:
+#
+#   - nothing is at <path>
+#   - the destination is a .json file to merge into
+#   - the file exists but has no region yet, for a region source
+#
+# When the same content is already there, it reports that and writes nothing. A region already there is
+# regenerated. A different file fails, and is named and left as it is.
 release:place-new() {
   local src=$1 path=$2 label=${3:-} kind
   kind=$(release:kind "${src}" "${path}")
@@ -830,8 +905,8 @@ release:place-new() {
   fi
 }
 
-# release:place-all <root> <base> <module>… places every path the modules deliver under the base, refusing where
-# a different file is. It returns the number of refusals.
+# release:place-all <root> <base> <module>… places every path the modules deliver under the base. A path where a
+# different file exists fails. It returns the number of failures.
 release:place-all() {
   local root=$1 base=$2 path src refused=0
   shift 2
@@ -843,8 +918,8 @@ release:place-all() {
   return "${refused}"
 }
 
-# release:unplace <source> <path> takes the release's content back out of <path>: the kit's entries for .json,
-# the kit's region for a region, the file itself otherwise.
+# release:unplace <source> <path> removes the release's content from <path>: the kit's entries from a .json
+# file, the kit's region from a region file, and otherwise the file itself.
 release:unplace() {
   local src=$1 path=$2
   case "$(release:kind "${src}" "${path}")" in
@@ -863,11 +938,17 @@ release:unplace() {
   esac
 }
 
-# release:retire <base-root> <base> <previous> <current> <module>… handles the paths the base's manifest records
-# that the current release no longer delivers: removed when still the previous release's own content, their
-# entries taken out of a merged .json when the base release is at hand, left with a warning otherwise. Under
-# home, whose manifest every repository shares, only paths the previous release delivered for these modules are
-# touched, and none without the base release.
+# release:retire <base-root> <base> <previous> <current> <module>… handles the paths that the base's manifest
+# records and the current release no longer delivers. <base-root> is the base release (the previous version), or
+# empty when it is not available. For each such path that still exists:
+#
+#   - a merged .json file: the previous release's entries are removed when the base release is available;
+#     otherwise it warns and leaves the file as it is
+#   - any other file: it is removed when its content still matches the digest the manifest records; otherwise it
+#     warns that the file was edited and leaves it as it is
+#
+# Under home, whose manifest every repository shares, it touches only paths the previous release delivered for
+# these modules, and nothing at all without the base release.
 release:retire() {
   local base_root=$1 base=$2 previous=$3 current=$4 path dest previous_src candidates
   shift 4
@@ -906,10 +987,11 @@ release:retire() {
   done <<<"${candidates}"
 }
 
-# release:write-manifest <base> <module>… records, in the base's manifest, the version, the active modules, and
-# the release's digest of every path delivered under the base. The repository's manifest is always written.
-# Home's is shared by every repository on the desk: it is written when these modules deliver there, and when they
-# do not, the lines whose paths are gone are dropped and the file is removed once nothing is left.
+# release:write-manifest <base> <module>… writes the base's manifest: the version, the active modules, and the
+# digest of the release's file for every path delivered under the base. The repository's manifest is always
+# written. Home's manifest is shared by every repository on the machine. It is written when these modules deliver
+# to home. When they do not, it drops the lines whose paths no longer exist, and removes the file once no line
+# is left.
 release:write-manifest() {
   local base=$1 manifest path src delivered kept
   shift
@@ -941,7 +1023,7 @@ release:write-manifest() {
     fi
     while IFS=$'\t' read -r path src
     do
-      # An if, not an && list: as the loop's last command, a false list would end the script under errexit.
+      # Use if, not &&: as the last command in the loop body, a false && list would end the script under errexit.
       if [[ -n "${path}" ]]
       then
         printf '%s  %s\n' "$(release:digest < "${src}")" "${path}"
@@ -965,8 +1047,8 @@ release:manifest-version() { sed -n 's/^version //p' .kit/manifest; }
 # release:manifest-modules prints the active modules the repository's manifest records, one per line.
 release:manifest-modules() { sed -n 's/^modules *//p' .kit/manifest | tr ' ' '\n' | awk 'NF'; }
 
-# release:manifest-paths <base> prints every path the base's manifest records. A record line is a 64-digit
-# digest, two spaces, and the path, which may itself hold spaces.
+# release:manifest-paths <base> prints every path the base's manifest records. A record line is a 64-character
+# hex digest, two spaces, and the path, which can contain spaces.
 release:manifest-paths() {
   local manifest
   manifest=$(release:manifest "$1")
@@ -982,7 +1064,7 @@ release:recorded() {
   awk -v p="$2" 'length($1) == 64 && substr($0, 67) == p { print $1 }' "${manifest}"
 }
 
-# release:require-manifest refuses to go on in a repository that never took the kit.
+# release:require-manifest fails in a repository where the kit was never installed.
 release:require-manifest() {
   if [[ ! -f .kit/manifest ]]
   then
@@ -991,14 +1073,14 @@ release:require-manifest() {
   fi
 }
 
-# release:finish <module>… reports a completed install or update.
+# release:finish <module>… reports a finished install or update.
 release:finish() {
   ok "kit $(release:version) is installed, modules: ${*:-none}; .kit/manifest is written."
   release:say-unmet "$@"
-  step "Commit the delivered files. The loop is in .kit/1st.md."
+  step "Commit the delivered files. The workflow is in .kit/1st.md."
 }
 
-# release:say-unmet <module>… names, as a step left to do, every expectation of the modules not yet met.
+# release:say-unmet <module>… warns about each unmet expectation of the modules, as a step left to do.
 release:say-unmet() {
   local line
   while IFS= read -r line
diff --git a/bin/status.sh b/bin/status.sh
index 643e913..18579e0 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -1,34 +1,55 @@
 # shellcheck shell=bash
-# status.sh - the picture of the work in flight (sourced module)
+# status.sh - shows the checkouts and the open pull requests in progress (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
 # status:render [--no-fetch] [--json] [--mine | --all | --owner=<login>…] prints the checkouts and the open pull
-# requests, and changes nothing. It asks the forge once, for every open pull request with the issues it closes,
-# its review threads, and the checks on its head; everything else is a local git read. The forge is asked first,
-# in the background, so its answer arrives while the fetch and the checkouts are drawn.
+# requests. It changes nothing.
 #
-# The picture: what the fetch brought, unless --no-fetch; the desk, the root checkout; then each worktree under
-# worktrees/, each with its uncommitted paths before its commits; then each open pull request with
-# its author, state, age, checks, the worktree holding its branch, and the issues it closes; then the branches whose
-# upstream is gone. --mine shows the pull requests the caller opened and no author column; --all, the default, shows
-# every open one, and --owner=<login>, given once or more, those the named authors opened, each with the author before
-# the state. Color is by family, never by state: green when nothing is left to decide, yellow when a human owes a
-# decision, blue when the next move is a machine's or a reviewer's, dim for detail. The states, in the order the first
-# that holds wins:
+# It calls the forge (GitHub or GitLab) once, for every open pull request with the issues it closes, its review
+# threads, and the checks on its head commit. Everything else is read from local git. The forge call starts
+# first, in the background, so it runs while the fetch runs and the checkouts are drawn.
 #
-#   draft 🔨, queued 🚦, conflicted 💥, failing:gate 🔥, no-check 📭, comments:open 💬,
-#   blocked:approval 👀,
-#   ready 🛬
+# The output, in order:
 #
-# --json prints the same facts as one document: {desk, worktrees, pullRequests, goneBranches}, the pull requests
-# chosen the same way.
+#   1. what the fetch brought in, unless --no-fetch
+#   2. the root checkout (the desk)
+#   3. each worktree under worktrees/, with its uncommitted paths and then its commits
+#   4. each open pull request, with its author, state, age, checks, the worktree that has its branch checked out,
+#      and the issues it closes
+#   5. the branches whose upstream is gone
+#
+# Which pull requests are shown:
+#
+#   --all              every open pull request (the default)
+#   --mine             the pull requests the caller opened, without the author column
+#   --owner=<login>    the pull requests the named author opened; repeat the flag for more authors
+#
+# Every choice except --mine shows the author before the state.
+#
+# A pull request's state is the first of these that applies. Its color shows the state's family, never the
+# single state: green when nothing is left to decide, yellow when a human owes a decision, and blue when the next
+# move is a machine's or a reviewer's. Detail is dim.
+#
+#   state              glyph   color
+#   draft              🔨      dim
+#   queued             🚦      blue
+#   conflicted         💥      yellow
+#   failing:gate       🔥      yellow
+#   no-check           📭      blue
+#   comments:open      💬      yellow
+#   blocked:approval   👀      blue
+#   ready              🛬      green
+#
+# --json prints the same data as one JSON document, {desk, worktrees, pullRequests, goneBranches}, with the pull
+# requests chosen the same way.
 
 use git
 
-# status_commit_cap is how many commits a block lists before counting the rest.
+# status_commit_cap is how many uncommitted paths or commits a checkout block lists before it counts the rest.
 status_commit_cap=10
 
-# status:width prints the terminal's width in columns: COLUMNS, else the terminal on stderr, else 100.
+# status:width prints the terminal's width in columns: COLUMNS, else the width of the terminal on stderr, else
+# 100. A width under 60 also gives 100.
 status:width() {
   local cols=''
   if [[ "${COLUMNS:-}" =~ ^[0-9]+$ ]]
@@ -62,7 +83,7 @@ status:paint() {
   printf '%s%s%s' "$(out:sgr "$1")" "$2" "$(out:sgr 0)"
 }
 
-# status:state-sgr <state> prints the family color of a state.
+# status:state-sgr <state> prints the color code of a state's family.
 status:state-sgr() {
   case "$1" in
     (ready)                                     printf '32' ;;
@@ -72,8 +93,8 @@ status:state-sgr() {
   esac
 }
 
-# status:state-emoji <state> prints the glyph of a state. Every glyph is one code point drawn two columns wide, so
-# the column after it stays aligned.
+# status:state-emoji <state> prints a state's glyph. Each glyph is one code point drawn two columns wide, so the
+# next column stays aligned.
 status:state-emoji() {
   case "$1" in
     (draft)            printf '🔨' ;;
@@ -102,7 +123,7 @@ status:age() {
   fi
 }
 
-# status:refs prints "<ref> <sha>" for origin's branches and the tags, the refs a fetch moves.
+# status:refs prints "<ref> <sha>" for origin's branches and for the tags: the refs a fetch moves.
 status:refs() {
   git for-each-ref --format='%(refname) %(objectname)' refs/remotes/origin refs/tags | grep --invert-match '/HEAD '
   return 0
@@ -116,9 +137,9 @@ status:plural() {
   fi
 }
 
-# status:fetch-summary <before> <after> <default-branch> prints one line naming what moved between two status:refs
-# snapshots: the commits new on origin's default branch, then the branches updated, new, and pruned, then the tags
-# new; "nothing new" when nothing moved.
+# status:fetch-summary <before> <after> <default-branch> prints one line listing what changed between two
+# status:refs snapshots: new commits on origin's default branch, then branches updated, new, and pruned, then new
+# tags. It prints "nothing new" when nothing changed.
 status:fetch-summary() {
   local default_ref="refs/remotes/origin/$3" kind ref old new commits=0 updated=0 added=0 pruned=0 tags=0 line part
   local -a parts=()
@@ -151,8 +172,8 @@ status:fetch-summary() {
   printf '📥 fetched origin: %s\n' "${line}"
 }
 
-# status:fetch <default-branch> fetches origin, pruning, and prints status:fetch-summary's line and a blank line;
-# where the fetch fails, a warning in its place.
+# status:fetch <default-branch> fetches origin with --prune, then prints status:fetch-summary's line and a blank
+# line. When the fetch fails, it prints a warning instead of the summary.
 status:fetch() {
   local before
   before=$(status:refs)
@@ -165,15 +186,15 @@ status:fetch() {
   printf '\n' >&2
 }
 
-# status:collect prints one JSON object per open pull request, the documents the forge provider folds, or
-# nothing with a warning where the forge cannot be asked.
+# status:collect prints one JSON object per open pull request, as the forge provider builds them. When the forge
+# cannot be reached, it prints nothing and a warning.
 status:collect() {
   use forge
   forge:open-prs || warn "no pull request is shown; see above"
 }
 
-# status:select <login>… keeps, of the pull request documents on stdin, those an author named here opened; with
-# no login named, every one.
+# status:select <login>… reads pull request documents on stdin and keeps those opened by one of the named
+# authors. With no login, it keeps every one.
 status:select() {
   if (( $# == 0 ))
   then cat
@@ -186,9 +207,9 @@ status:fork() {
   git merge-base "origin/$2" "$1" 2>/dev/null || git merge-base "$2" "$1" 2>/dev/null || true
 }
 
-# status:relative <path> prints <path> relative to the directory the command was typed in: ".", a descent, or a
-# climb. Both sides are resolved physically, the target through its nearest directory that exists, so a symlinked
-# directory on either side still climbs correctly.
+# status:relative <path> prints <path> relative to the directory the command was run from: ".", a path down, or
+# a path up through ../. Both paths are resolved physically (the target through its nearest existing directory),
+# so a symlinked directory on either side still gives the right ../ path.
 status:relative() {
   local target=$1 here=${kit_invoked_in:-$(pwd -P)} up='' dir rest=''
   dir=${target}
@@ -217,11 +238,18 @@ status:relative() {
   fi
 }
 
-# status:checkout <path> <branch> <default-branch> prints one JSON object measuring the checkout at <path>: path,
-# relative, branch (empty when detached), detached, ahead of and behind the point where the branch left origin's
-# default branch, the lines the working tree adds and removes against that point, the count of uncommitted paths
-# and each as {status, path} with git's two-letter status, and the commits past that point as [{sha, subject}]. A detached checkout measures its lines against its own head
-# and lists no commits.
+# status:checkout <path> <branch> <default-branch> prints one JSON object that measures the checkout at <path>.
+# The fork point is where the branch left origin's default branch. The fields:
+#
+#   path, relative      the checkout's path, and that path relative to the caller's directory
+#   branch, detached    the branch (empty when detached), and whether the checkout is detached
+#   ahead, behind       the commits on the branch past the fork point, and on origin's default branch past it
+#   added, removed      the lines the working tree adds and removes against the fork point
+#   uncommitted         the number of uncommitted paths
+#   changes             each uncommitted path as {status, path}, with git's two-letter status
+#   commits             the commits past the fork point, as [{sha, subject}]
+#
+# A detached checkout measures its lines against its own HEAD and lists no commits.
 status:checkout() {
   local path=$1 branch=$2 default_branch=$3 fork='' ahead=0 behind=0 added=0 removed=0 changes a r _
   [[ -n "${branch}" ]] && fork=$(status:fork "${branch}" "${default_branch}")
@@ -250,9 +278,13 @@ status:checkout() {
         commits: [split("\n")[] | select(. != "") | split("\t") | { sha: .[0], subject: (.[1:] | join("\t")) }] }'
 }
 
-# status:label <relative> <branch> prints the label of a checkout and its plain width, tab-separated: the path with
-# the directory dim and the branch underlined when the path's last component is the branch or ends in "-<branch>",
-# the branch alone at ".", or "branch on path" otherwise. A detached checkout is its path.
+# status:label <relative> <branch> prints a checkout's label and its plain width, tab-separated. The label is:
+#
+#   - for a detached checkout: its path
+#   - at ".": the branch alone
+#   - when the path's last component is the branch or ends in "-<branch>": the path, with the directory dim and
+#     the branch underlined
+#   - otherwise: "<branch> on <path>"
 status:label() {
   local relative=$1 branch=$2 dir
   if [[ -z "${branch}" ]]
@@ -270,9 +302,9 @@ status:label() {
   fi
 }
 
-# status:paint-count <count> <sign> <sgr> <width> <side> prints <sign><count> padded to <width> characters on the
-# left or the right, in <sgr> above zero and dim at zero. The padding is by character, since the arrows are
-# multibyte and printf's field width counts bytes.
+# status:paint-count <count> <sign> <sgr> <width> <side> prints <sign><count> padded to <width> characters,
+# aligned to <side> (left or right). The text is in <sgr> above zero and dim at zero. It pads by characters,
+# because the arrows are multibyte and printf's field width counts bytes.
 status:paint-count() {
   local count=$1 sign=$2 sgr=$3 width=$4 side=$5 text pad=''
   (( count > 0 )) || sgr=90
@@ -286,15 +318,15 @@ status:paint-count() {
   fi
 }
 
-# status:measures <checkout-json> [<widths>] prints "↑a ↓b · +x -y", and " · n uncommitted" in yellow when n is
-# above zero. <widths> is status:count-widths' line; with it, ahead and added are right-aligned and behind and
-# removed left-aligned in columns of those widths, so the dots of every row fall under each other.
+# status:measures <checkout-json> [<widths>] prints "↑a ↓b · +x -y", then " · n uncommitted" in yellow when n is
+# above zero. <widths> is status:count-widths' line. With it, ahead and added are right-aligned, and behind and
+# removed left-aligned, in columns of those widths, so the dots line up across rows.
 status:measures() {
   local ahead behind added removed uncommitted ahead_w=0 behind_w=0 added_w=0 removed_w=0
   IFS=$'\t' read -r ahead behind added removed uncommitted \
     < <(jq --raw-output '[.ahead, .behind, .added, .removed, .uncommitted] | @tsv' <<<"$1")
   [[ -n "${2:-}" ]] && IFS=' ' read -r ahead_w behind_w added_w removed_w <<<"$2"
-  # The last column is padded only when something follows it, so no row ends in blanks.
+  # The last column is padded only when something follows it, so no row ends in trailing spaces.
   (( uncommitted > 0 )) || removed_w=0
   printf '%s %s · %s %s' \
     "$(status:paint-count "${ahead}" '↑' '1;32' "${ahead_w}" right)" \
@@ -313,10 +345,14 @@ status:count-widths() {
     | map(tostring | length + 1) | join(" ")'
 }
 
-# status:checkout-block <glyph> <checkout-json> <label-width> [<widths>] prints a checkout: its row, with the
-# counts in status:count-widths' columns, then its uncommitted paths, yellow status and path, then its commits,
-# dim hash and subject. Past status_commit_cap it prints the first paths and a count of the rest, and the newest
-# commits, a dim count of the hidden, and the oldest.
+# status:checkout-block <glyph> <checkout-json> <label-width> [<widths>] prints a checkout:
+#
+#   1. its row, with the counts in status:count-widths' columns
+#   2. its uncommitted paths, each with its status in yellow
+#   3. its commits, each with its hash dim
+#
+# Past status_commit_cap, it prints the first paths and a count of the rest. For commits, it prints the newest
+# ones, a dim count of the hidden ones, and the oldest one.
 status:checkout-block() {
   local glyph=$1 doc=$2 label_w=$3 widths=${4:-} relative branch label width mark='' sha subject code path
   IFS=$'\x1f' read -r relative branch < <(jq --raw-output '[.relative, .branch] | join("\u001f")' <<<"${doc}")
@@ -324,7 +360,7 @@ status:checkout-block() {
   [[ -n "${branch}" ]] || mark="   $(status:paint 33 '❗ detached HEAD')"
   printf '%s %s%*s%s   %s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" \
     "$(status:measures "${doc}" "${widths}")" >&2
-  # A status can open with a blank, which a tab read would drop, so the separator is one it cannot.
+  # A status can start with a space, which a tab-separated read would drop, so the separator is \x1f instead.
   while IFS=$'\x1f' read -r code path
   do
     [[ -n "${path}" ]] || continue
@@ -358,12 +394,16 @@ status:checkout-block() {
     | @tsv' <<<"${doc}")
 }
 
-# status:check-cell <checks-json> prints the checks as "✅ <passed> / <total> · <took>", the duration dim, or
-# "❌ <failing> · <passed> / <total> · <took>", or "🏃 <passed> / <total> · <elapsed>"; nothing when none has
-# reported.
+# status:check-cell <checks-json> prints the checks cell, with the duration dim:
+#
+#   - passed: "✅ <passed> / <total> · <took>"
+#   - failed: "❌ <failing> · <passed> / <total> · <took>"
+#   - running: "🏃 <passed> / <total> · <elapsed>"
+#
+# It prints nothing when no check has reported.
 status:check-cell() {
   local state passed total failing took text
-  # A field here can be empty, and a tab read collapses an empty field, so the separator is one that cannot.
+  # A field can be empty, and a tab-separated read collapses an empty field, so the separator is \x1f instead.
   IFS=$'\x1f' read -r state passed total failing took \
     < <(jq --raw-output '[.state, .passed, .total, .failing, (.took // "")] | map(tostring) | join("\u001f")' <<<"$1")
   case "${state}" in
@@ -378,8 +418,8 @@ status:check-cell() {
 }
 
 # status:pr-block <pr-json> <title-width> <owner-width> <state-width> <age-width> <worktree> prints a pull request:
-# its row, with the author before the state where the owner width is above zero and ending with its branch where
-# a worktree here holds it, then the issues it closes.
+# its row, then the issues it closes. The row shows the author before the state when <owner-width> is above zero,
+# and ends with the branch when a worktree here has it checked out.
 status:pr-block() {
   local doc=$1 title_w=$2 owner_w=$3 state_w=$4 age_w=$5 worktree=$6
   local number ref title author branch state age unresolved row issue checks
@@ -404,8 +444,8 @@ status:pr-block() {
   return 0
 }
 
-# status:render [--no-fetch] [--json] [--mine | --all | --owner=<login>…] draws the picture the file header
-# describes, or prints it as one JSON document.
+# status:render [--no-fetch] [--json] [--mine | --all | --owner=<login>…] prints the output the file header
+# describes, or the same data as one JSON document.
 status:render() {
   local no_fetch=false json=false choice=all arg main_root default_branch desk_branch path branch doc gone
   local -a owners=()
@@ -422,9 +462,9 @@ status:render() {
         return 2
     esac
   done
-  # The forge is the slow read and needs nothing local, so it starts first and runs while the fetch and the local
-  # reads do; its warnings are held for the pull requests' place in the picture, so they do not land among the
-  # checkouts. --mine asks the forge who the caller is in the same job.
+  # The forge call is the slow one and needs nothing local, so it starts first and runs during the fetch and the
+  # local reads. Its warnings are saved and printed where the pull requests appear, so they do not land among the
+  # checkouts. With --mine, the same background job also asks the forge for the caller's login.
   local scratch prs_job prs_failed=false
   scratch=$(mktemp -d "${TMPDIR:-/tmp}/kit-status.XXXXXX")
   # shellcheck disable=SC2064  # the path is fixed now; the trap outlives this function's locals
@@ -453,7 +493,7 @@ status:render() {
   desk_branch=$(git -C "${main_root}" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
   gone=$(git:gone-branches)
 
-  # The desk and the worktrees by issue number, each as JSON.
+  # Measure the desk, then the worktrees in issue-number order, each as JSON.
   local desk prs
   local -a worktrees=()
   desk=$(status:checkout "${main_root}" "${desk_branch}" "${default_branch}")
@@ -477,7 +517,7 @@ status:render() {
     return 0
   fi
 
-  # The checkouts are drawn while the forge may still be answering.
+  # Draw the checkouts while the forge call may still be running.
   local label_w=0 width relative widths
   local -A worktree_on=()
   for doc in "${desk}" "${worktrees[@]}"
@@ -504,7 +544,7 @@ status:render() {
   [[ "${prs_failed}" == false ]] || return 1
   prs=$(<"${scratch}/prs")
 
-  # Column widths across the pull requests; the author column is there unless --mine chose the rows.
+  # Compute the column widths across the pull requests. The author column is shown unless --mine is given.
   local title_w=0 owner_w=0 state_w=0 age_w=0 text author state_text age_secs
   while IFS=$'\x1f' read -r text author state_text age_secs
   do
@@ -538,8 +578,8 @@ status:render() {
   fi
 }
 
-# status:by-number sorts git:worktrees lines by the issue number their directory opens with; a directory that
-# opens with no number sorts first.
+# status:by-number sorts git:worktrees lines by the issue number their directory name starts with. A directory
+# name that does not start with a number sorts first.
 status:by-number() {
   local path rest dir number
   while IFS=$'\t' read -r path rest
diff --git a/bin/template.sh b/bin/template.sh
new file mode 100644
index 0000000..5e8acd6
--- /dev/null
+++ b/bin/template.sh
@@ -0,0 +1,228 @@
+# shellcheck shell=bash
+# template.sh - a rule's templates: make a new file from one, and check a file still matches one (sourced module)
+# ----------------------------------------------------------------------------------------------------------------------
+#
+# A rule can have templates, one per variant of the file it governs, at .kit/templates/<rule>/<variant>. The rule's
+# frontmatter lists them in the order they are tried. Each entry can limit its template to a path glob, and can
+# mark the file as executable:
+#
+#   templates:
+#     - variant: root
+#       path: justfile
+#     - variant: module
+#
+# A template is the file itself, with holes written «name». There are two kinds of hole:
+#
+#   a hole within a line      making a file fills it with a value. Checking a file matches it against any text on
+#                             that line. A hole used twice must match the same text each time.
+#   a hole that is a line     making a file fills it with the value's lines, else one blank line. Checking a file
+#                             matches it against any run of lines, including none.
+#
+# The values of path, name, and stem come from the path. The caller gives the value of every other hole within a
+# line.
+#
+# The same template both makes a file (kit new file) and checks one (kit lint). A file passes when it matches any
+# variant its path allows. To change a template, a repository adds a module of its own that places the same path.
+# The later module in dependency order wins.
+#
+# see: docs/templates.md
+
+use context yaml
+
+# template_dir is the directory the templates are installed in.
+declare -gr template_dir=.kit/templates
+
+# template:exempt <path> is true for a path that no template checks:
+#
+#   - a template itself
+#   - a module's region, which is a fragment of a file
+#   - a path .gitattributes marks linguist-generated, because a tool writes it
+template:exempt() {
+  [[ "$1" =~ (^|/)\.kit/templates/ || "$1" =~ (^|/)modules/[^/]+/regions/ ]] && return 0
+  [[ "$(git check-attr linguist-generated -- "$1" 2>/dev/null)" == *': linguist-generated: set' ]]
+}
+
+# template:rule-name <rule-file> prints the rule's name: its file's name without .md.
+template:rule-name() {
+  local name=${1##*/}
+  printf '%s\n' "${name%.md}"
+}
+
+# template:variants <rule-file> prints "<variant>\x1f<path-glob>\x1f<executable>" for each template the rule lists,
+# in order.
+template:variants() {
+  yaml:records "$1" templates variant path executable
+}
+
+# template:file <rule-file> <variant> prints the template's path.
+template:file() {
+  printf '%s/%s/%s\n' "${template_dir}" "$(template:rule-name "$1")" "$2"
+}
+
+# template:applies <rule-file> <path> prints the variants whose path glob matches <path>, or that have no glob. It
+# prints them in order, in the same format as template:variants.
+template:applies() {
+  local variant glob executable
+  while IFS=$'\x1f' read -r variant glob executable
+  do
+    [[ -n "${variant}" ]] || continue
+    if [[ -z "${glob}" ]] || context:glob-matches "$2" "${glob}"
+    then
+      printf '%s\x1f%s\x1f%s\n' "${variant}" "${glob}" "${executable}"
+    fi
+  done < <(template:variants "$1")
+}
+
+# template:regex reads a template on stdin and prints the regular expression that matches a file with its shape,
+# in Oniguruma syntax, which jq uses.
+template:regex() {
+  jq --raw-input --slurp --raw-output '
+    def literal: gsub("(?<c>[.^$|?*+()\\[\\]{}\\\\])"; "\\\(.c)");
+    reduce (split("\n") | if .[-1] == "" then .[:-1] else . end)[] as $line
+      ({re: "", seen: {}};
+       if ($line | test("^«[a-z_]+»$")) then .re += "(?:[^\\n]*\\n)*?"
+       else
+         ([$line | match("«([a-z_]+)»"; "g") | .captures[0].string]) as $names
+         | ([$line | splits("«[a-z_]+»")] | map(literal)) as $parts
+         | reduce range(0; $names | length) as $i
+             (.line = $parts[0];
+              if .seen[$names[$i]] then .line += "\\k<\($names[$i])>"
+              else .line += "(?<\($names[$i])>[^\\n]*?)" | .seen[$names[$i]] = true end
+              | .line += $parts[$i + 1])
+         | .re += .line + "\\n" | del(.line)
+       end)
+    | "\\A" + .re + "\\z"'
+}
+
+# template:test <regex> <file> is true when the file matches template:regex's expression.
+template:test() {
+  [[ "$(jq --raw-input --slurp --arg re "$1" 'test($re)' < "$2")" == true ]]
+}
+
+# template:matches <template> <file> is true when the file matches the template.
+template:matches() {
+  template:test "$(template:regex < "$1")" "$2"
+}
+
+# template:diverges <template> <file> prints "<line>\t<text>" for the first template line the file does not match.
+# It finds the longest run of the template's first lines that the file still starts with.
+template:diverges() {
+  local total n
+  total=$(wc -l < "$1")
+  for (( n = 1; n <= total; n++ ))
+  do
+    if ! template:test "$({ head -n "${n}" "$1"; printf '«rest»\n'; } | template:regex)" "$2"
+    then
+      printf '%s\t%s\n' "${n}" "$(sed -n "${n}p" "$1")"
+      return 0
+    fi
+  done
+}
+
+# template:holes <template> prints the holes within a line (the ones a value must fill), once each, in order.
+template:holes() {
+  grep --invert-match --extended-regexp '^«[a-z_]+»$' "$1" | grep --only-matching --extended-regexp '«[a-z_]+»' \
+    | tr -d '«»' | awk '!seen[$0]++'
+  return 0
+}
+
+# template:render <template> <values-json> prints the template with every hole filled from the values object:
+#
+#   - a hole within a line gets its value
+#   - a hole that is a line gets its value's lines, else one blank line. When it is the template's last line and
+#     has no value, it gets nothing, so the file never ends in a blank line.
+template:render() {
+  jq --raw-input --slurp --join-output --argjson v "$2" '
+    split("\n") | if .[-1] == "" then .[:-1] else . end
+    | length as $n
+    | to_entries
+    | map(.key as $i | .value
+          | if test("^«[a-z_]+»$") then ($v[ltrimstr("«") | rtrimstr("»")] // (if $i == $n - 1 then null else "" end))
+            else gsub("«(?<k>[a-z_]+)»"; $v[.k] // "«\(.k)»") end
+          | select(. != null) | . + "\n")
+    | add // ""' < "$1"
+}
+
+# template:rules <path> prints the rules that govern the path and have templates, most specific first. The most
+# specific rule has the matching glob with the most non-wildcard characters. A rule matched only by the file's
+# first line sorts last.
+template:rules() {
+  local path=$1 rule glob best literal
+  while IFS= read -r rule
+  do
+    [[ -n "${rule}" && -n "$(template:variants "${rule}")" ]] || continue
+    best=0
+    while IFS= read -r glob
+    do
+      if [[ -n "${glob}" ]] && context:glob-matches "${path}" "${glob}"
+      then
+        literal=${glob//\*/}
+        (( ${#literal} > best )) && best=${#literal}
+      fi
+    done < <(yaml:list "${rule}" paths)
+    printf '%s\t%s\n' "${best}" "${rule}"
+  done < <(context:rules "${path}") | LC_ALL=C sort -t $'\t' -k1,1nr -k2,2 | cut -f2
+}
+
+# template:check <rule-file> <path>… is true when every file matches a variant the rule allows at its path. For
+# each file that matches none, it prints an error naming the variants it was checked against, and the line where
+# the file stops matching the variant it follows furthest. A rule with no templates passes every file. Each
+# template is compiled once, and all the files are read and tested in one pass, so checking every tracked file
+# stays fast.
+template:check() {
+  local rule=$1 path variant glob executable file line text best where failed=0
+  shift
+  local -A regex=() allowed=()
+  while IFS=$'\x1f' read -r variant glob executable
+  do
+    [[ -n "${variant}" ]] || continue
+    file=$(template:file "${rule}" "${variant}")
+    if [[ ! -f "${file}" ]]
+    then
+      error "${rule} lists the template ${variant}, and ${file} is not here; run: kit update"
+      return 1
+    fi
+    regex[${variant}]=$(template:regex < "${file}")
+  done < <(template:variants "${rule}")
+  (( ${#regex[@]} > 0 )) || return 0
+  for path in "$@"
+  do
+    allowed[${path}]=$(template:applies "${rule}" "${path}" | cut -d $'\x1f' -f 1 | paste -s -d ' ' -)
+  done
+  while IFS=$'\t' read -r path variants
+  do
+    [[ -n "${path}" ]] || continue
+    failed=$(( failed + 1 ))
+    best=0
+    where='the template at its end'
+    for variant in ${variants}
+    do
+      file=$(template:file "${rule}" "${variant}")
+      IFS=$'\t' read -r line text < <(template:diverges "${file}" "${path}")
+      if [[ -n "${line}" ]] && (( line > best ))
+      then
+        best=${line}
+        where="${file} line ${line}: ${text}"
+      fi
+    done
+    error "${path} does not have the shape of the $(template:rule-name "${rule}") template (${variants// /, });" \
+      "it leaves ${where}"
+  done < <(jq --null-input --raw-output \
+      --rawfile files <(for path in "$@"; do printf '%s\t%s\n' "${path}" "${allowed[${path}]}"; done) \
+      --rawfile regexes <(for variant in "${!regex[@]}"
+                          do
+                            printf '%s\x1f%s\x1e' "${variant}" "${regex[${variant}]}"
+                          done) \
+      --rawfile contents <(for path in "$@"; do cat "${path}"; printf '\x1e'; done) '
+    ($regexes | split("\u001e") | map(select(. != "") | split("\u001f") | {(.[0]): .[1]}) | add) as $regex
+    | ($contents | split("\u001e")) as $text
+    | ($files | split("\n") | map(select(. != "") | split("\t") | {path: .[0], variants: (.[1] | split(" "))}))
+    | to_entries[]
+    | .key as $i | .value
+    | select((.variants | length) > 0)
+    | select(any(.variants[]; . as $v | $text[$i] | test($regex[$v])) | not)
+    | "\(.path)\t\(.variants | join(" "))"')
+  (( failed == 0 ))
+}
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/bin/toolchain-brew.sh b/bin/toolchain-brew.sh
index a0c7a90..ce3c38e 100644
--- a/bin/toolchain-brew.sh
+++ b/bin/toolchain-brew.sh
@@ -1,11 +1,15 @@
 # shellcheck shell=bash
-# toolchain-brew.sh - Homebrew as a toolchain: a Brewfile names the formulae and casks (sourced module)
+# toolchain-brew.sh - the Homebrew toolchain provider: a Brewfile lists the formulae and casks (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The provider bin/toolchain.sh loads for `provider: brew`, or for a Brewfile at the root; `file:` names another.
-# A Brewfile pins a formula by name, so a version floats with Homebrew unless the name carries it, node@22; what
-# the kit can do is say which are behind and move them. brew is the requirement, found on PATH or at Homebrew's
-# own prefixes, so a Linux runner whose brew is installed but not on PATH still has it.
+# bin/toolchain.sh loads this provider for `provider: brew`, or when a Brewfile is at the repository root. The
+# `file:` field names a different file.
+#
+# A Brewfile pins a formula by name only, so its version moves with Homebrew unless the name includes it
+# (node@22). The kit can only report which formulae are behind and upgrade them.
+#
+# The provider needs brew, on PATH or at one of Homebrew's own prefixes. That covers a Linux runner where brew is
+# installed but not on PATH.
 
 toolchain-brew:file() {
   local file
@@ -33,7 +37,7 @@ toolchain-brew:install() {
   "${brew}" bundle install --file "$(toolchain-brew:file)" --no-upgrade --quiet
 }
 
-# The Brewfile's formulae and casks, intersected with what brew says is behind.
+# toolchain-brew:outdated prints the Brewfile's formulae and casks that brew reports as outdated.
 toolchain-brew:outdated() {
   local brew names doc
   brew=$(toolchain-brew:brew) || return 1
diff --git a/bin/toolchain-docker.sh b/bin/toolchain-docker.sh
index 037250d..ec7234b 100644
--- a/bin/toolchain-docker.sh
+++ b/bin/toolchain-docker.sh
@@ -1,15 +1,17 @@
 # shellcheck shell=bash
-# toolchain-docker.sh - a container image as a toolchain: a Dockerfile holds the tools (sourced module)
+# toolchain-docker.sh - the container image toolchain provider: a Dockerfile installs the tools (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The provider bin/toolchain.sh loads for `provider: docker`, or for a toolchain.Dockerfile at the root; `file:`
-# names another and `image:` the image's name, kit-toolchain by default. The image is built from the file and
-# tagged by the file's digest, so a change to the file is a new image and an unchanged one is never rebuilt. A
-# command runs in it with the checkout mounted at /work, as the caller's user, so what it writes is the caller's.
+# bin/toolchain.sh loads this provider for `provider: docker`, or when toolchain.Dockerfile is at the repository
+# root. The `file:` field names a different file. The `image:` field names the image (default: kit-toolchain).
 #
-# What the file pins is its base: `FROM name:tag@sha256:<digest>`. outdated asks the registry for the tag's
-# current digest and names every base whose pin is behind it, or that has no pin; update rewrites the pins. docker
-# with buildx is the requirement.
+# The image is built from the file and tagged with the file's digest. A changed file builds a new image; an
+# unchanged file is never rebuilt. A command runs in the container with the checkout mounted at /work, as the
+# caller's user, so the files it writes belong to the caller.
+#
+# The file pins its base images: `FROM name:tag@sha256:<digest>`. outdated asks the registry for each tag's
+# current digest and lists every base that has no pin or is pinned to an older digest. update rewrites the pins.
+# The provider needs docker with buildx.
 
 toolchain-docker:file() {
   local file
@@ -23,7 +25,8 @@ toolchain-docker:require() {
   return 1
 }
 
-# toolchain-docker:tag prints the image's tag: its name and the first twelve hex digits of the file's digest.
+# toolchain-docker:tag prints the image's tag: the image name, then the first twelve hex digits of the file's
+# digest.
 toolchain-docker:tag() {
   local file name
   file=$(toolchain-docker:file)
@@ -45,8 +48,8 @@ toolchain-docker:install() {
   docker build --quiet --file "${file}" --tag "${tag}" "$(dirname "${file}")" >/dev/null
 }
 
-# toolchain-docker:bases prints "<name:tag>\t<pinned digest or nothing>" for every FROM line naming an image: not
-# scratch, and not an earlier stage of the same file named by `AS <stage>`.
+# toolchain-docker:bases prints "<name:tag>\t<pinned digest or nothing>" for every FROM line that names an image.
+# It skips scratch and earlier stages of the same file (named by `AS <stage>`).
 toolchain-docker:bases() {
   awk '
     toupper($1) == "FROM" {
@@ -61,7 +64,7 @@ toolchain-docker:bases() {
     }' "$(toolchain-docker:file)"
 }
 
-# toolchain-docker:latest <name:tag> prints the digest the registry now gives the tag.
+# toolchain-docker:latest <name:tag> prints the tag's current digest in the registry.
 toolchain-docker:latest() {
   docker buildx imagetools inspect "$1" --format '{{json .Manifest}}' 2>/dev/null | jq --raw-output '.digest'
 }
@@ -83,7 +86,7 @@ toolchain-docker:update() {
   while IFS=$'\t' read -r base pinned latest
   do
     [[ -n "${base}" ]] || continue
-    # An image reference never holds a comma, so a comma delimits each sed command.
+    # An image reference never contains a comma, so each sed command uses a comma as its delimiter.
     quoted=$(ere:quote "${base}")
     if [[ "${pinned}" == unpinned ]]
     then
@@ -97,7 +100,7 @@ toolchain-docker:update() {
   toolchain-docker:install
 }
 
-# The tools live in the image, so nothing is put on PATH here; a command reaches them through run.
+# The tools are in the image, so path prints nothing. A command reaches them through run.
 toolchain-docker:path() { return 0; }
 
 toolchain-docker:run() {
diff --git a/bin/toolchain-mise.sh b/bin/toolchain-mise.sh
index 158f09c..51a26c3 100644
--- a/bin/toolchain-mise.sh
+++ b/bin/toolchain-mise.sh
@@ -1,9 +1,10 @@
 # shellcheck shell=bash
-# toolchain-mise.sh - mise as a toolchain: mise.toml pins the tools, mise.lock records them (sourced module)
+# toolchain-mise.sh - the mise toolchain provider: mise.toml pins the tools, mise.lock records them (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The provider bin/toolchain.sh loads for `provider: mise`, or for a mise.toml or .mise.toml at the root. mise is
-# its requirement; MISE_ENV, where the caller sets it, layers mise.<env>.toml on top as mise does.
+# bin/toolchain.sh loads this provider for `provider: mise`, or when mise.toml or .mise.toml is at the repository
+# root. The provider needs mise. When the caller sets MISE_ENV, mise layers mise.<env>.toml on top, as it always
+# does.
 
 toolchain-mise:file() {
   if [[ -f .mise.toml && ! -f mise.toml ]]
@@ -24,7 +25,8 @@ toolchain-mise:install() {
   mise install --quiet
 }
 
-# mise outdated --json is an object keyed by tool, each with its current and latest version.
+# toolchain-mise:outdated reads mise outdated --json: an object keyed by tool name, with each tool's current and
+# latest version.
 toolchain-mise:outdated() {
   local doc
   toolchain-mise:require || return 1
diff --git a/bin/toolchain.sh b/bin/toolchain.sh
index db395af..d88b8f5 100644
--- a/bin/toolchain.sh
+++ b/bin/toolchain.sh
@@ -1,31 +1,41 @@
 # shellcheck shell=bash
-# toolchain.sh - the seam over how a checkout gets the tools its gate runs: mise, brew, or docker (sourced module)
+# toolchain.sh - one interface to the tool managers (mise, brew, docker) that install the gate's tools (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Which tool manager puts a repository's tools on a desk or a runner is the repository's decision. A repository
-# declares its toolchains in .kit/settings.yml, or the kit detects them from the files each one reads:
+# Each repository picks the tool managers that install the tools its gate runs, on the root checkout (the desk)
+# and on a CI runner. Each tool manager is a provider: toolchain-<name>.sh in this directory, whose functions are
+# named toolchain-<name>:<call>. A provider reads the fields of its settings record with toolchain:field.
+#
+# A repository can use more than one provider. They are chosen by:
+#
+#   1. the `toolchains` list in .kit/settings.yml, in the order listed
+#   2. otherwise every provider whose file is at the repository root, in this order:
+#        - mise: mise.toml or .mise.toml
+#        - brew: Brewfile
+#        - docker: toolchain.Dockerfile
+#
+# A `toolchains` setting looks like this:
 #
 #   toolchains:
-#     - provider: mise                       detected from mise.toml or .mise.toml
-#     - provider: brew                       detected from Brewfile
+#     - provider: mise
+#     - provider: brew
 #       file: Brewfile
-#     - provider: docker                     detected from toolchain.Dockerfile
+#     - provider: docker
 #       file: toolchain.Dockerfile
 #       image: example/toolchain
 #
-# A provider is toolchain-<name>.sh beside this file, its functions named toolchain-<name>:<call>, each reading its
-# record's fields through toolchain:field. A provider answers:
+# Every provider implements the calls below, except where noted.
 #
 #   file                    the file it reads, relative to the repository root
-#   require                 its own tool is present, or a remedy
-#   install                 every pinned tool installed, from the file and its lock
-#   outdated                one line per tool behind its source: "<name>\t<installed>\t<latest>"
-#   update                  every tool moved to its latest, and the pins and the lock rewritten
-#   path                    the directories that put its tools first on PATH, one per line
-#   run <command>…          the command run with its tools; only a provider that isolates, docker, answers
+#   require                 succeeds when its own tool is present; otherwise fails with a remedy
+#   install                 installs every pinned tool, from the file and its lock
+#   outdated                one line per tool that is behind its source: "<name>\t<installed>\t<latest>"
+#   update                  moves every tool to its latest version, and rewrites the pins and the lock
+#   path                    the directories to put first on PATH for its tools, one per line
+#   run <command>…          runs the command with its tools; only docker implements it, because it isolates
 #
-# A command runs with every toolchain's path first on PATH, or inside the container where docker is declared, so
-# the gate sees the same tools on a desk and on a runner.
+# toolchain:run runs a command inside the container when docker is declared, and otherwise with every
+# toolchain's path first on PATH. Either way the gate sees the same tools on the desk and on a runner.
 #
 # see: docs/toolchains.md
 
@@ -38,9 +48,8 @@ toolchain:providers() {
     | LC_ALL=C sort | paste -s -d ' ' -)
 }
 
-# toolchain:declared prints the declared providers, one per line, in the order the settings name them; with none
-# declared, the ones whose file is here, in the order mise, brew, docker. A provider the kit does not carry is
-# refused by name.
+# toolchain:declared prints the chosen providers, one per line, as the file header describes. It fails, naming
+# the provider, when a declared provider is not one the kit has.
 toolchain:declared() {
   local provider found=''
   local -a declared=()
@@ -68,8 +77,8 @@ toolchain:declared() {
   printf '%s' "${found}"
 }
 
-# toolchain:field <provider> <field> prints a field of the provider's record, or nothing. The loop reads to the
-# end, so the reader is never left writing into a pipe nobody reads.
+# toolchain:field <provider> <field> prints a field of the provider's record, or nothing. The while loop reads
+# every record, even after a match, so yaml:records never writes into a pipe that nobody reads.
 toolchain:field() {
   local provider value found=''
   while IFS=$'\x1f' read -r provider value
@@ -102,15 +111,16 @@ toolchain:path() {
   toolchain:each path
 }
 
-# toolchain:isolating prints the declared toolchain that runs a command in a place of its own, docker, or nothing.
+# toolchain:isolating prints docker when docker is declared, otherwise nothing. docker is the only provider that
+# runs a command in its own container.
 toolchain:isolating() {
   local providers
   providers=$(toolchain:declared) || return 1
   grep --line-regexp docker <<<"${providers}" || true
 }
 
-# toolchain:run <command>… runs the command with the declared toolchains' tools: inside the container where docker
-# is declared, else with every toolchain's path first on PATH. With none declared the command runs as it is.
+# toolchain:run <command>… runs the command with the declared toolchains' tools: inside the container when docker
+# is declared, otherwise with every toolchain's path first on PATH. With no toolchain, the command runs as is.
 toolchain:run() {
   local isolating dirs
   isolating=$(toolchain:isolating) || return 1
diff --git a/bin/tracker-ado.sh b/bin/tracker-ado.sh
index 1fc5622..a8d06eb 100644
--- a/bin/tracker-ado.sh
+++ b/bin/tracker-ado.sh
@@ -1,9 +1,10 @@
 # shellcheck shell=bash
-# tracker-ado.sh - Azure DevOps work items, through az boards, as a tracker (sourced module)
+# tracker-ado.sh - the Azure DevOps tracker provider: work items, through az boards (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The provider bin/tracker.sh loads for a prefix whose record names `provider: ado`. The record carries the
-# organization's URL and the project a new work item is created in, and optionally its type, Task by default:
+# bin/tracker.sh loads this provider for a prefix whose record sets `provider: ado`. The record gives the
+# organization's URL, the project that new work items are created in, and optionally the work item type (default:
+# Task):
 #
 #   trackers:
 #     - prefix: "AB#"
@@ -12,9 +13,11 @@
 #       project: Claims
 #       type: Task
 #
-# The az CLI with its azure-devops extension is this file's requirement and nobody else's. A work item is CLOSED
-# in the states Closed, Done, and Removed, the closing states of Azure DevOps' process templates, and OPEN in
-# every other; the caller is the identity az is signed in as, which need not be the forge's login.
+# The provider needs the az CLI with its azure-devops extension. No other part of the kit needs az.
+#
+# A work item is CLOSED in the states Closed, Done, and Removed (the closing states of Azure DevOps' process
+# templates) and OPEN in every other state. The caller (me) is the identity az is signed in as, which can differ
+# from the login on the forge (GitHub or GitLab).
 
 # shellcheck disable=SC2154  # TRACKER_PREFIX is set by tracker:of and tracker:at for the call
 tracker-ado:organization() {
@@ -37,7 +40,7 @@ tracker-ado:show() {
     || { error "run: az login (work item ${TRACKER_PREFIX}$1 could not be read from ${org})"; return 1; }
 }
 
-# tracker-ado:read <id> <filter> applies a jq filter to the work item, failing where az could not show it.
+# tracker-ado:read <id> <filter> applies a jq filter to the work item. It fails when az cannot show the item.
 tracker-ado:read() {
   local item
   item=$(tracker-ado:show "$1") || return 1
diff --git a/bin/tracker-forge.sh b/bin/tracker-forge.sh
index 1d290f2..0635972 100644
--- a/bin/tracker-forge.sh
+++ b/bin/tracker-forge.sh
@@ -1,9 +1,10 @@
 # shellcheck shell=bash
-# tracker-forge.sh - the forge's own issues, GitHub's or GitLab's, as a tracker (sourced module)
+# tracker-forge.sh - the tracker provider for the forge's own issues, on GitHub or GitLab (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The provider bin/tracker.sh loads for `#`, unless a declared tracker claims it: every call is the forge seam's
-# issue call of the same meaning, so the forge's provider answers and this file adds nothing of its own.
+# bin/tracker.sh loads this provider for the prefix `#`, unless a record in `trackers` declares `#`. Each call
+# except url passes straight to the matching issue call of the forge interface, bin/forge.sh, so the forge's
+# provider does the work. url builds the issue's address from the repository's URL.
 
 use forge
 
diff --git a/bin/tracker.sh b/bin/tracker.sh
index e3fe39b..ce00d3f 100644
--- a/bin/tracker.sh
+++ b/bin/tracker.sh
@@ -1,11 +1,29 @@
 # shellcheck shell=bash
-# tracker.sh - the loop's seam over the trackers that hold its issues (sourced module)
+# tracker.sh - one interface to the issue trackers: forge issues, Azure DevOps work items (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# An issue lives in a tracker, and the tracker is not the forge: GitHub issues and GitLab issues happen to live in
-# theirs, Azure DevOps work items and Jira do not, and a repository may use more than one at once. A reference
-# names its tracker in its syntax, as the trackers themselves write it: `#7` or `7` for the forge's own, `AB#4521`
-# for an Azure DevOps work item. `.kit/settings.yml` declares the others, a prefix and a provider each:
+# Verbs that read, assign, or create issues call tracker:of or tracker:at here. Each call is passed to the
+# provider for the issue's tracker: tracker-<name>.sh in this directory, whose functions are named
+# tracker-<name>:<call>.
+#
+# The tracker is not always the forge, the service that hosts the repository (GitHub or GitLab). GitHub and GitLab
+# issues are on the forge; Azure DevOps work items and Jira issues are not. A repository can use more than one
+# tracker at once.
+#
+# An issue reference names its tracker with a prefix, written the way that tracker writes it:
+#
+#   - `#7` or `7`: an issue in the forge's own tracker
+#   - `AB#4521`: an Azure DevOps work item
+#
+# The provider for a reference is chosen by:
+#
+#   1. a bare number is read as `#<number>`
+#   2. the longest prefix that the reference starts with, followed only by digits, picks a record: one in the
+#      `trackers` list in .kit/settings.yml, or the built-in `#` record for the forge's own tracker
+#   3. that record's `provider` field names the provider
+#
+# A record in `trackers` declares a prefix, a provider, and the provider's own fields. A record with the prefix
+# `#` replaces the built-in one.
 #
 #   trackers:
 #     - prefix: "AB#"
@@ -13,15 +31,15 @@
 #       organization: https://dev.azure.com/example
 #       project: Claims
 #
-# `#` is the forge's own tracker unless a record claims it. A provider is tracker-<name>.sh beside this file, its
-# functions named tracker-<name>:<call>, each taking the reference's number first and the prefix's record through
-# tracker:field. A provider answers these calls, printing its result on stdout and failing with a remedy:
+# Every provider implements the calls below. Each prints its result on stdout. On failure it prints a remedy. A
+# call about one issue gets the reference's number, without the prefix, as <id>. TRACKER_PREFIX is set to the
+# prefix, and the provider reads its record's fields with tracker:field.
 #
 #   title <id>              the issue's title
 #   state <id>              OPEN or CLOSED
 #   assignees <id>          the assignees' logins, space-separated
 #   assign <id> <login>     adds the assignee
-#   me                      the caller's login in this tracker, which need not be the forge's
+#   me                      the caller's login in this tracker, which can differ from the forge login
 #   create <title>          the number of the issue it creates
 #   url <id>                the issue's browser URL
 #
@@ -29,8 +47,8 @@
 
 use release yaml
 
-# tracker:records prints "<prefix>\x1f<provider>" for every declared tracker, then the forge's own as "#" unless a
-# record claims it.
+# tracker:records prints "<prefix>\x1f<provider>" for every declared tracker, then "#\x1fforge" for the forge's
+# own tracker, unless a record declares the prefix `#`.
 tracker:records() {
   local prefix provider forge_claimed=false
   while IFS=$'\x1f' read -r prefix provider
@@ -42,8 +60,9 @@ tracker:records() {
   [[ "${forge_claimed}" == true ]] || printf '#\x1fforge\n'
 }
 
-# tracker:field <prefix> <field> prints a field of the prefix's record, or nothing. Every loop over records here
-# reads to the end, so the reader is never left writing into a pipe nobody reads.
+# tracker:field <prefix> <field> prints a field of the prefix's record, or nothing. Every while loop over records
+# here reads every record, even after a match, so the command feeding it never writes into a pipe that nobody
+# reads.
 tracker:field() {
   local prefix value found=''
   while IFS=$'\x1f' read -r prefix value
@@ -53,9 +72,9 @@ tracker:field() {
   [[ -z "${found}" ]] || printf '%s\n' "${found}"
 }
 
-# tracker:parse <reference> prints "<prefix>\t<number>": the longest declared prefix the reference opens with, and
-# the digits after it; a bare number is the forge's own. A reference no declared tracker answers is refused, naming
-# the prefixes there are.
+# tracker:parse <reference> prints "<prefix>\t<number>": the longest declared prefix that the reference starts
+# with, and the digits after it. A bare number is in the forge's own tracker. When no tracker matches the
+# reference, it fails and lists the prefixes.
 tracker:parse() {
   local ref=$1 prefix best='' provider
   [[ "${ref}" =~ ^[0-9]+$ ]] && ref="#${ref}"
@@ -75,7 +94,7 @@ tracker:parse() {
   printf '%s\t%s\n' "${best}" "${ref#"${best}"}"
 }
 
-# tracker:provider <prefix> prints the provider that answers the prefix.
+# tracker:provider <prefix> prints the provider for the prefix.
 tracker:provider() {
   local prefix provider found=''
   while IFS=$'\x1f' read -r prefix provider
@@ -90,7 +109,8 @@ tracker:provider() {
   printf '%s\n' "${found}"
 }
 
-# tracker:of <reference> <call> <argument>… runs the call of the tracker the reference names, with its number.
+# tracker:of <reference> <call> <argument>… runs the call on the reference's tracker, passing the reference's
+# number first.
 tracker:of() {
   local ref=$1 call=$2 prefix number provider
   shift 2
@@ -111,7 +131,7 @@ tracker:at() {
   TRACKER_PREFIX=${prefix} "tracker-${provider}:${call}" "$@"
 }
 
-# tracker:normal <reference> prints the reference as its tracker writes it: `7` becomes `#7`.
+# tracker:normal <reference> prints the reference in its tracker's own form: `7` becomes `#7`.
 tracker:normal() {
   local prefix number
   IFS=$'\t' read -r prefix number < <(tracker:parse "$1") || return 2
@@ -119,16 +139,16 @@ tracker:normal() {
   printf '%s%s\n' "${prefix}" "${number}"
 }
 
-# tracker:is-forge <reference> is true when the forge's own tracker answers the reference, so the forge can link a
-# branch to it and close it on merge by itself.
+# tracker:is-forge <reference> succeeds when the reference is in the forge's own tracker. The forge can then link
+# a branch to the issue and close the issue on merge by itself.
 tracker:is-forge() {
   local prefix number
   IFS=$'\t' read -r prefix number < <(tracker:parse "$1" 2>/dev/null) || return 1
   [[ -n "${prefix}" && "$(tracker:provider "${prefix}")" == forge ]]
 }
 
-# tracker:key <reference> prints the reference as a branch name opens with it: the forge's own issue 7 as `7`, a
-# work item AB#4521 as `ab4521`, letters lowered and anything not a letter or a digit dropped.
+# tracker:key <reference> prints the reference in the form a branch name starts with: forge issue 7 as `7`, work
+# item AB#4521 as `ab4521` (lowercased, with everything but letters and digits removed).
 tracker:key() {
   local ref
   ref=$(tracker:normal "$1") || return 2
@@ -141,7 +161,8 @@ tracker:key() {
   fi
 }
 
-# tracker:branch-ref <branch> prints the reference a branch was made for, read back from its key, or nothing.
+# tracker:branch-ref <branch> prints the reference a branch was made for, read back from the key the branch name
+# starts with, or nothing.
 tracker:branch-ref() {
   local branch=$1 prefix provider key found=''
   while IFS=$'\x1f' read -r prefix provider
@@ -158,8 +179,8 @@ tracker:branch-ref() {
   [[ -z "${found}" ]] || printf '%s\n' "${found}"
 }
 
-# tracker:body-refs <body> prints every reference a closing keyword names in a change's body, for the trackers the
-# forge does not link by itself: `Closes AB#4521`, `fixes AB#4521`, `Resolves: AB#4521`.
+# tracker:body-refs <body> prints every reference that follows a closing keyword in a change's body, for the
+# trackers the forge does not link by itself: `Closes AB#4521`, `fixes AB#4521`, `Resolves: AB#4521`.
 tracker:body-refs() {
   local body=$1 prefix provider escaped
   while IFS=$'\x1f' read -r prefix provider
diff --git a/bin/yaml.sh b/bin/yaml.sh
index 39cba3d..5f04708 100644
--- a/bin/yaml.sh
+++ b/bin/yaml.sh
@@ -2,9 +2,14 @@
 # yaml.sh - the subset of YAML the kit's own files are written in (sourced module)
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# Three kinds of file are read here: a module's module.yml, the repository's .kit/settings.yml, and the
-# frontmatter between the opening and closing `---` of a rule file. All are written in the same small subset,
-# and one reader serves them so they cannot drift:
+# The kit reads three kinds of file with this module:
+#
+#   - a module's module.yml
+#   - the repository's .kit/settings.yml
+#   - a rule file's frontmatter, between the opening and closing `---`
+#
+# All three use the same small subset of YAML. One reader handles all of them, so their formats cannot drift
+# apart:
 #
 #   key: value          a scalar, quoted or not
 #   key:                a list, one `  - item` per line
@@ -15,11 +20,11 @@
 #     - field: value
 #       field: value
 #
-# A value may be double-quoted or single-quoted, and a single-quoted one is taken literally, backslashes and all,
+# A value may be double-quoted or single-quoted. A single-quoted value is read literally, backslashes included,
 # which is how a pattern is written.
 #
-# A line starting with # is a comment. Nothing deeper is read, and a file that needs more is a file the kit does
-# not write. When the file opens with `---`, only the frontmatter up to the next `---` is read.
+# A line starting with # is a comment. Nothing nested more deeply is read; the kit writes no file that needs more.
+# When the file starts with `---`, only the frontmatter up to the next `---` is read.
 
 # yaml:value <file> <key> prints the scalar under <key>, unquoted, or nothing.
 yaml:value() {
@@ -50,8 +55,8 @@ yaml:map() {
 }
 
 # yaml:records <file> <key> <field>… prints one line per record of the list under <key>: the named fields' values,
-# in the order named, separated by the unit separator \x1f, since a pattern may hold a tab. A field a record
-# lacks is empty.
+# in the order named, separated by the unit separator \x1f (not a tab, because a pattern may contain a tab). A
+# field the record does not have is empty.
 yaml:records() {
   local file=$1 key=$2
   shift 2
@@ -84,7 +89,8 @@ yaml:keys() {
   yaml:read "$1" | awk '/^[A-Za-z0-9_-]+:/ { k = $0; sub(/:.*$/, "", k); print k }'
 }
 
-# yaml:read <file> prints the file's YAML: the frontmatter when the file opens with ---, the whole file otherwise.
+# yaml:read <file> prints the file's YAML, without comment lines: the frontmatter when the file starts with ---,
+# otherwise the whole file.
 yaml:read() {
   [[ -f "$1" ]] || return 0
   awk '
diff --git a/docs/architecture.md b/docs/architecture.md
index bb49b52..43be6f1 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,99 +1,184 @@
 # Architecture
 
-The kit is a release that a repository installs, a set of verbs an agent and a person both run, and the checks
-that hold the work to the rules. This page is the shape of it: what a release is, how it reaches a repository, how
-a file's rules are found, and how a change moves from an issue to `main`. [modules.md](modules.md) and
-[context.md](context.md) are the two mechanisms in detail.
+kit has three parts: a release that a repository installs, commands that agents and people both run, and checks that
+verify the work follows the rules. This page covers:
+
+- what a release contains and how it reaches a repository,
+- how kit finds the rules for a file,
+- how a change moves from an issue to `main`, and
+- which check verifies which claim.
+
+[modules.md](modules.md) and [context.md](context.md) describe the module format and the rule lookup in detail.
 
 ## The release and its delivery
 
 ![Delivery: a release's modules, through the verbs, into a repository and a home](delivery.svg)
 
-A release is one tarball, `kit-<version>.tar.gz`, and its layout is the checkout's: `bin/` is the machinery, and
-`modules/` is everything delivered. `bin/kit` is the command; each verb is an executable `bin/kit-<verb>.sh`
-beside it, and the verbs share bash modules loaded with `use`. The release workflow stamps the tag's version into
-a `version` file; a checkout has none and is `unreleased`.
-
-A module is a directory under `modules/`, and the directory names it. `module.yml` describes it: whether it is active by
-default, which modules it depends on, and the default answers for its templates; `files/<base>/` is mirrored at the
-base's root; `templates/<base>/` is rendered first, every `@key@` replaced by a setting; `regions/<base>/`, rendered
-the same way, holds what the kit owns inside a file the repository owns; `docs/` is packed with the release and placed
-in no repository. Two bases exist: `repo`, the repository root, and `home`, the user's `~`.
-
-The verbs are the only way content moves. `kit install` resolves the active set, `kit` plus those named plus their
-dependencies, renders, places, and writes the manifests. `kit update` moves to a new pinned release:
-an untouched file is replaced, an edited one three-way merged with the previous release as the base. `kit check`
-fails when a delivered file differs from the release's. `kit module` changes the active set. Three rules govern
-placement: a `.json` destination, other than a schema, is merged by key, the kit owning only the entries it writes; a
-region is opened inside a file the repository owns by a bare `kit:generate` directive naming its path, and `kit
-generate` makes it what `kit region` prints, as it makes every region any file in the repository declares, see
-[generate.md](generate.md); everything else is a copy.
-
-Each base has a manifest: `.kit/manifest`, committed with the repository, and `~/.kit/manifest` on the desk when a
-module delivers there. A manifest records the version, the active modules, and the release's digest of every
-delivered path, which is how `kit update` tells an edited file from an untouched one.
+A release is one tarball, `kit-<version>.tar.gz`, with the same layout as this checkout:
+
+- `bin/kit` is the command. Each verb is an executable `bin/kit-<verb>.sh` beside it. The verbs share bash modules,
+  loaded with `use`.
+- `modules/` holds everything a release delivers.
+- `version` holds the release version. The release workflow writes it from the tag. A checkout has no `version` file
+  and reports `unreleased`.
+
+### Modules
+
+A module is a directory under `modules/`, named after the module. It contains:
+
+| Path | Purpose |
+| --- | --- |
+| `module.yml` | whether the module is on by default, which modules it depends on, and default answers for its templates |
+| `files/<base>/` | files copied as they are to the same path under the base |
+| `templates/<base>/` | files copied after each `@key@` is replaced by a setting |
+| `regions/<base>/` | content kit owns inside a file the repository owns, rendered like a template |
+| `docs/` | documentation, packed with the release and never installed |
+
+There are two bases: `repo` is the repository root, and `home` is the user's home directory.
+
+### The verbs that move content
+
+Content reaches a repository only through these verbs:
+
+- `kit install` resolves the active modules (`kit`, the ones named, and their dependencies), renders them, places the
+  files, and writes the manifests.
+- `kit update` moves to a newly pinned release. It replaces each file the repository never edited and merges each
+  edited file three ways, with the previous release as the base.
+- `kit check` fails when a delivered file differs from the release.
+- `kit module` changes the set of active modules.
+
+How a file is placed depends on its destination:
+
+- A `.json` file, other than a schema, is merged by key. kit owns only the entries it writes.
+- A region lives inside a file the repository owns. It starts at a `kit:generate` line naming the file's path and
+  ends at a matching end line. `kit generate` replaces the region with the output of `kit region`. It does the same
+  for every region any file in the repository declares; see [generate.md](generate.md).
+- Every other file is copied.
+
+### Manifests
+
+Each base has a manifest:
+
+- `.kit/manifest`, committed with the repository.
+- `~/.kit/manifest` on a developer machine, when a module delivers to the home directory.
+
+A manifest records the version, the active modules, and the release's digest of every delivered path. `kit update`
+compares a file against its digest to tell whether the repository edited it.
 
 ## Finding a file's rules
 
 ![Context: how any agent, and Claude Code's hook, find the rules that govern a file](context.svg)
 
-A rule is written once, in `.kit/rules/<kind>.md`, and copied into no harness's directory. Its frontmatter says what it
-governs: `paths:`, globs on the repository-relative path, and `content:`, patterns on the first line of a file that
-exists. `kit context <path>` names the rules governing a path and appends the ask to `.git/kit/context.log`. Every
-caller gets the same answer: an agent of any harness following the sentence in `.kit/1st.md`, a person at the shell, a
-tool reading `--json`, and Claude Code's `PreToolUse` hook, which the `claude` module wires to `kit context --claude` so
-the rules are named before every write. The log of asks is the record of what was named. A rule also names its linter,
-and `kit lint` runs each rule's linter over the paths the rule governs, so the hook manager a repository uses, if any,
-only has to call the verb.
-
-## The loop and the gate
-
-![The loop: an issue becomes a worktree and a draft pull request, the gate holds it, a human merges](loop.svg)
-
-The desk is the root checkout and belongs to the human; it usually has `main` checked out and may have any branch no
-worktree holds, and no agent changes it in place. Work starts from an issue: `kit issue <N>` makes
-`worktrees/<N>-<slug>`, a branch linked to the issue, a start commit, and a draft pull request. It sweeps uncommitted
-work off the desk into the worktree, the one change it makes to the desk, and says so. Everything after that happens in
-the worktree: `kit context` before a change, `kit lint` for the pre-commit linters by hand, `kit rebase` to bring the
-branch onto the default branch at origin and push it, and `gh pr ready` when the pull request body is the report.
-
-Every call the loop makes to the forge, an issue's title, a branch linked to it, a change and its state, its checks and
-threads and linked issues, goes through one seam, `forge:` in `bin/forge.sh`, and a provider answers: `forge-github.sh`
-over `gh`, or `forge-gitlab.sh` over `glab`, chosen by the `forge` setting or by origin's host, github.com or
-gitlab.com; a self-hosted forge is named by the setting. Each answers in the same shape, so `kit status` draws the same
-picture on either, and each names the change in its own words, a pull request `#3` or a merge request `!3`. One origin
-is one forge: a repository on two is a mirror or a migration, and the setting says which one the loop runs on.
-tests/forge-conformance.bats drives every provider through a fake of its tool against one world and holds every answer
-to one shape. The core verbs never reach the seam, so a repository on no forge still installs, updates, checks, and runs
-`kit context`, and each forge's tool is its provider's requirement alone.
-The delivered check is `kit ci`, four checks that are each one kit command, run by the delivered GitHub Actions job for
-a pull request into the default branch, or by any pipeline. `kit gate` runs the repository's own gate, the `gate`
-setting or the detected justfile recipe, Makefile target, or `package.json` script, and refuses when there is none,
-since a gate that cannot run clears nothing; it runs with the tools the repository's toolchains manage, mise, Homebrew,
-or a container image, as [toolchains.md](toolchains.md) describes. `kit check` holds the delivered files to the release.
-`kit linked` refuses a change not linked to an open issue. `kit policy` refuses a branch, a commit subject, or a change
-title off the repository's policy, matched by patterns or decided by Open Policy Agent, as [policy.md](policy.md)
-describes. A human merges, and
-`kit tidy` removes the worktree and the branch afterwards. `kit status` draws the whole picture: what the fetch
-brought, the desk and every worktree with its uncommitted paths and its commits past the fork, and every open pull
-request with its state, age, and checks. It asks the forge first, in the background, so the checkouts are drawn while
-the forge answers.
+Each rule lives in one file, `.kit/rules/<kind>.md`, and is not copied into any agent tool's own directory. Its
+frontmatter says which files it covers:
+
+- `paths:` lists globs matched against the repository-relative path.
+- `content:` lists patterns matched against the first line of an existing file.
+
+`kit context <path>` prints the rules that cover a path and appends a line to `.git/kit/context.log`. Every caller
+gets the same answer:
+
+- an agent in any harness, following the instruction in `.kit/1st.md`,
+- a person at the shell,
+- a tool reading `--json`, and
+- Claude Code's `PreToolUse` hook, which the `claude` module wires to `kit context --claude`, so the rules are shown
+  before every write.
+
+The log records which rules were shown, and when.
+
+A rule also names its linter. `kit lint` runs each rule's linter over the files the rule covers, so a hook manager
+only has to call `kit lint`. A rule's templates are skeleton files of its kind: `kit new file <path>` creates a file
+from one, and `kit lint` checks that every file the rule covers keeps the shape of one; see
+[templates.md](templates.md).
+
+## The workflow and the gate
+
+![The workflow: an issue becomes a worktree and a draft pull request, the gate checks it, a human merges](loop.svg)
+
+The desk is the root checkout on the human's machine, on whatever branch it currently has, and it belongs to the
+human. It usually has `main` checked out, and it may have any branch that no worktree is using. No agent changes it
+in place.
+
+Work starts from an issue:
+
+1. `kit issue <N>` creates `worktrees/<N>-<slug>`, a branch linked to the issue, a start commit, and a draft pull
+   request. If the desk has uncommitted work, `kit issue` moves it into the new worktree and says so. That is the
+   only change it makes to the desk.
+2. In the worktree:
+   - `kit context` before changing a file,
+   - `kit lint` to run the pre-commit linters by hand,
+   - `kit rebase` to rebase the branch onto the default branch at origin and push it.
+3. `gh pr ready` once the pull request body holds the report.
+4. A human merges, and `kit tidy` removes the worktree and the branch.
+
+### Forges, interfaces, and providers
+
+A forge is the service that hosts a repository with its issues and pull requests, such as GitHub or GitLab. kit says
+forge rather than GitHub because the workflow runs on more than one.
+
+Four files each define an interface: a list of calls, and the rule that picks which provider implements them. Shell
+has no types, so the choice is made at run time: a setting, or origin's host, becomes part of a function name. In
+Michael Feathers' terms (*Working Effectively with Legacy Code*), each is a seam.
+
+| Interface | Providers | Chosen by |
+| --- | --- | --- |
+| `bin/forge.sh` | `forge-github.sh` over `gh`, `forge-gitlab.sh` over `glab` | the `forge` setting, else origin's host |
+| `bin/tracker.sh` | `tracker-forge.sh`, `tracker-ado.sh` | the reference's prefix, `#7` or `AB#4521`; see [trackers.md](trackers.md) |
+| `bin/toolchain.sh` | `toolchain-mise.sh`, `toolchain-brew.sh`, `toolchain-docker.sh` | the `toolchains` setting, else the files present; see [toolchains.md](toolchains.md) |
+| `bin/policy.sh` | `policy-patterns.sh`, `policy-opa.sh` | `policy_engine: opa` or a `.rego` file under `.kit/policy/`, else patterns; see [policy.md](policy.md) |
+
+Every forge call the workflow makes goes through `forge:` in `bin/forge.sh`: an issue's title, the branch linked to
+it, a pull request and its state, checks, review threads, and linked issues. A self-hosted forge must be named in the
+`forge` setting.
+
+- Every provider returns the same shape, so `kit status` shows the same picture on either forge.
+- Each provider uses its forge's own name for a change: pull request `#3` on GitHub, merge request `!3` on GitLab.
+- A repository with one origin has one forge. A repository on two forges is a mirror or a migration, and the setting
+  picks the one the workflow uses.
+- `tests/forge-conformance.bats` runs every provider against a fake of its tool and checks that each returns the
+  same shape.
+- The core verbs never call the forge, so a repository with no forge can still install, update, check, and run
+  `kit context`. Only a provider needs its forge's tool.
+
+### The checks
+
+`kit ci` is the delivered check. The delivered GitHub Actions job runs it on every pull request into the default
+branch, and any other pipeline can run it too. It runs four checks, each a kit command:
+
+- `kit gate` runs the repository's own gate: the `gate` setting, or a detected justfile recipe, Makefile target, or
+  `package.json` script. It fails when there is no gate, because a gate that cannot run verifies nothing. The gate
+  runs with the tools the repository's toolchains manage (mise, Homebrew, or a container image); see
+  [toolchains.md](toolchains.md).
+- `kit check` fails when a delivered file differs from the release.
+- `kit linked` fails when a pull request is not linked to an open issue.
+- `kit policy` fails when a branch name, commit subject, or pull request title breaks the repository's policy. The
+  policy is a set of patterns or an Open Policy Agent policy; see [policy.md](policy.md).
+
+`kit status` shows everything in flight:
+
+- what the last fetch brought in,
+- the desk and every worktree, with its uncommitted paths and its commits since the branch point, and
+- every open pull request, with its state, age, and checks.
+
+It queries the forge in the background and draws the local checkouts while it waits.
 
 ## What verifies what
 
-| Claim | Held by |
+| Claim | Verified by |
 | --- | --- |
-| A delivered file is the release's | `kit check`, in the gate and on a desk, against the release's files and the manifest's version |
-| A change has an issue | `kit linked` in the gate; `kit issue` makes the link when it starts the work |
-| The repository's own gate ran | `kit gate`, which refuses when there is no gate to run |
-| The loop's names follow the policy | `kit policy`, patterns or Open Policy Agent over the same facts |
-| The gate ran with the pinned tools | `kit toolchain install`, then the gate through the toolchain, on a desk and a runner |
-| All four held, wherever CI runs | `kit ci`, the delivered check, the four as one verb, every one reported |
-| A file's rules were named to the agent | the Claude Code hook; `kit context` in every other harness |
-| A file's rules were asked for | `.git/kit/context.log`, one line per ask |
-| A file keeps its rule's mechanical part | `kit lint`, each rule's own linter over the paths it governs |
-| The forbidden spellings were not used | the harness's deny list, delivered by its adapter module |
-| The desk was not disturbed | `kit rebase` refusing the root checkout; `kit issue` never switching its branch |
-
-No check holds whether a rule, once read, was followed. The linters hold the mechanical part of that for the kinds
-they cover; the rest is the pull request body's report, which the integrity rules in `.kit/1st.md` bind.
+| A delivered file matches the release | `kit check`, in the gate and locally, against the release's files and the manifest's version |
+| A change has an issue | `kit linked` in the gate; `kit issue` creates the link when it starts the work |
+| The repository's own gate ran | `kit gate`, which fails when there is no gate to run |
+| Branch names, commit subjects, and titles follow the policy | `kit policy`, with patterns or Open Policy Agent |
+| The gate ran with the pinned tools | `kit toolchain install`, then the gate run through the toolchain, locally and in CI |
+| All four held, wherever CI runs | `kit ci`, which runs all four and reports each one |
+| An agent was shown a file's rules | the Claude Code hook; `kit context` in other harnesses |
+| An agent asked for a file's rules | `.git/kit/context.log`, one line per request |
+| A file follows its rule's mechanical checks | `kit lint`, each rule's linter over the files it covers |
+| A file keeps its rule's shape | `kit lint`, against the rule's templates; `kit new file` creates it in that shape |
+| The forbidden git commands were not used | the harness's deny list, delivered by its adapter module |
+| The desk was not changed | `kit rebase` refusing the root checkout; `kit issue` never switching its branch |
+
+No check verifies that an agent followed a rule after reading it. The linters cover the mechanical part for the kinds
+of file they handle. The rest is the report in the pull request body, which the integrity rules in `.kit/1st.md`
+govern.
diff --git a/docs/context.md b/docs/context.md
index 90fac8a..43adc26 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -1,18 +1,21 @@
 # Context
 
-A rule is written once, in `.kit/rules/<kind>.md`, and copied nowhere. Before an agent creates or changes a file,
-it asks which rules govern that file:
+`kit context` prints the rule files that govern a path. Run it before you create or change a file, then
+read each rule it names.
 
 ```sh
 kit context "${path}"
 ```
 
-The answer is the rule files to read, one per line. `--json` gives one object per path with its rules. Every ask
-is appended to `.git/kit/context.log`, one line of epoch and path per ask.
+- The output is the rule files to read, one per line. Given several paths, it prints each rule once.
+- `--json` prints one object per path, with that path's rules.
+- Every call appends one line to `.git/kit/context.log`: the epoch time and the path.
 
-## How a rule declares what it governs
+Each rule is written once, in `.kit/rules/<kind>.md`, and copied nowhere else.
 
-A rule file opens with a frontmatter of two optional lists and one optional command:
+## How a rule declares the files it governs
+
+A rule file opens with a frontmatter block. Every key in it is optional:
 
 ```yaml
 ---
@@ -21,40 +24,58 @@ paths:
 content:
   - "^#!.*/(env +)?(ba)?sh( |$)"
 lint: shellcheck --shell=bash --external-sources
+templates:
+  - variant: script
+    executable: true
+  - variant: module
 ---
 ```
 
-- `paths:` are globs matched against the repository-relative path. `**` stands for any depth, and a lone `*`
-  crosses directories too, so `**/*.sh` and `*.sh` both name every `.sh` file; a glob with no wildcard, such as
-  `justfile`, names the one path.
-- `content:` are extended regular expressions matched against the first line of a file that already exists, so a
-  bash script with no extension is bash by its shebang, and a file about to be created is governed by its path
-  alone.
+| Key | Contents |
+| --- | --- |
+| `paths:` | Globs matched against the repository-relative path. |
+| `content:` | Extended regular expressions matched against the first line of a file that already exists. |
+| `lint:` | The linter command for the files the rule governs. |
+| `templates:` | The shapes a file of this kind takes; see [templates.md](templates.md). |
+
+A rule governs a file when any of its globs or any of its patterns matches.
+
+- In a glob, `**` matches any depth, and a lone `*` also crosses directories. So `**/*.sh` and `*.sh` both match
+  every `.sh` file.
+- A glob with no wildcard, such as `justfile`, matches that one path.
+- A `content:` pattern lets a bash script with no extension match by its shebang.
+- A file that does not exist yet is matched by its path alone.
 
-A rule governs a file when any glob or any pattern matches. `lint:` names the linter for the paths the rule
-governs: `kit lint` runs it once over the staged paths, the named ones, or with `--all-files` every tracked one,
-and a linter not on `PATH` is a refusal, not a skip. No hook manager is assumed; the `lefthook` module wires its
-pre-commit hook to the verb.
+`kit lint` runs each rule's `lint:` command once over the paths that rule governs. The paths are the staged paths,
+the paths you name, or every tracked path with `--all-files`. A linter that is not on `PATH` is a failure, not a
+skip. The kit assumes no hook manager; the `lefthook` module adds a pre-commit hook that runs `kit lint`.
+
+[templates.md](templates.md) describes templates, `kit new file` (which makes a file from one), and the shape check
+`kit lint` runs against them.
 
 ## Harness adapters
 
-A harness that can run a command before a write runs `kit context` itself, so the rules reach the agent without
-the agent remembering to ask. The `claude` module wires Claude Code's `PreToolUse` hook on `Write`, `Edit`, and
-`MultiEdit` to:
+A harness that can run a command before a write can call `kit context` itself, so the agent gets the rules without
+having to remember to ask. The `claude` module adds a Claude Code `PreToolUse` hook on `Write`, `Edit`, and
+`MultiEdit` that runs:
 
 ```sh
 kit context --claude
 ```
 
-It reads the hook's input on stdin, takes the file path from the tool's input, and answers in the hook's output,
-naming the rules and never quoting them, so reading a rule stays an act the agent takes:
+This command:
+
+1. Reads the hook's input on stdin.
+2. Takes the file path from the tool's input.
+3. Prints the hook's output, naming the rules without quoting them, so the agent still reads each rule itself.
 
 ```json
 {"hookSpecificOutput": {"hookEventName": "PreToolUse",
   "additionalContext": "kit: lib/run.sh is governed by .kit/rules/bash.md; read it before this change."}}
 ```
 
-Nothing is kept between calls but the log line.
+It prints nothing when the tool input has no file path or no rule governs the file. Nothing is kept
+between calls except the log line.
 
-A harness with no hook, and a person, use the plain call. `.kit/1st.md` names it as the step before any file is
-created or changed.
+A harness with no hook, and a person, run `kit context "${path}"` directly. `.kit/1st.md` lists it as the step
+before creating or changing any file.
diff --git a/docs/generate.md b/docs/generate.md
index 1537363..05efefc 100644
--- a/docs/generate.md
+++ b/docs/generate.md
@@ -1,15 +1,21 @@
 # Generate
 
-A region is a stretch of a file that a command makes and a person does not edit: a table drawn from the
-manifests, a list of verbs drawn from their help, the sentence the kit puts in `AGENTS.md`. The file itself says
-how each region is made, with a directive in its own comment syntax, and `kit generate` makes every region what
-its command makes it. A hand edit is then a stale region, and `kit check` fails on one wherever `kit ci` runs.
+A region is a part of a file that a command writes and a person does not edit. Mark a region with a directive in
+the file's own comment syntax, then run `kit generate` to replace the region's content with its command's output.
+
+Examples of regions:
+
+- a table built from the manifests
+- a list of commands built from their help text
+- the sentence the kit puts in `AGENTS.md`
+
+A hand edit makes a region stale. `kit check` fails on a stale region, so `kit ci` fails wherever it runs.
 
 ## The directive
 
-A region opens on a line that is the marker `kit:generate`, a name, and optionally a command in backticks, and
-closes on a line that is `kit:end` and the same name. Nothing but punctuation may surround either: the comment
-opener before, the comment closer after.
+A region opens on a line with the marker `kit:generate`, a name, and optionally a command in backticks. It closes on
+a line with `kit:end` and the same name. On either line, only punctuation may come before or after the marker: the
+comment opener before, and the comment closer after.
 
 ```text
 <!-- kit:generate <name> -->
@@ -18,7 +24,7 @@ opener before, the comment closer after.
 <!-- kit:end <name> -->
 ```
 
-Both lines stay. The command's standard output replaces the lines between them. So a markdown page carries:
+Both marker lines stay. The command's standard output replaces the lines between them. A markdown page contains:
 
 ```markdown
 <!-- kit:generate AGENTS.md -->
@@ -27,84 +33,130 @@ repository trustworthy.
 <!-- kit:end AGENTS.md -->
 ```
 
-and a shell script or a `.gitignore` carries the same with `#`, a JavaScript file with `//`, a SQL file with
-`--`, a Visual Basic file with `'`. The reader knows no list of comment syntaxes. It reads a line as a directive
-when only non-alphanumeric characters come before the marker and after the closing backtick, which every comment
-frame satisfies and no line of prose does, since prose has letters before the marker. A line that opens with
-the marker and is not a well-formed directive is an error, never a line silently skipped, so a misspelled
-directive is found rather than left stale. A page that wants to show the syntax puts it in a fenced code block,
-which is not live, or in prose, with a word before the marker.
-
-The **name** is any run of characters without whitespace or a backtick, set off by whitespace. It pairs the
-directive with its end marker, and it is unique in a file. A region the kit delivers is named by its path, so
-the name says what the region is.
-
-The **command** is a bash command line: pipes, redirections, and `$()` are all its own. It runs from the
-repository root with the running kit's `bin/` first on `PATH`, standard input closed, `errexit` and `pipefail`
-set, and two variables in its environment: `KIT_GENERATE_FILE`, the file, and `KIT_GENERATE_REGION`, the name.
-The command is everything between the first backtick after the name and the last backtick before the closer, so
-the one thing it cannot carry is a literal backtick; `$()` says the same thing. A region whose command needs
-more than a line is a script in the tree, where it is read and tested.
-
-With **no command**, the command is `kit region`, which reads the region's name from its environment as the path
-of a region an active module delivers. A name no module delivers fails, naming the directive's line, so a
-forgotten command is never a silent no-op. The directive may sit in any file; the name says only which region.
+Other files use their own comment syntax:
+
+- `#` in a shell script or a `.gitignore`
+- `//` in a JavaScript file
+- `--` in a SQL file
+- `'` in a Visual Basic file
+
+`kit generate` has no list of comment syntaxes. It reads a line as a directive when only non-alphanumeric
+characters come before the marker and after the closing backtick. Every comment syntax passes this test. A line of
+prose does not, because it has letters before the marker.
+
+A line that starts with the marker but is not a well-formed directive is an error. It is never skipped, so a
+misspelled directive is reported instead of left stale. To show the syntax on a markdown page, put it in a fenced
+code block, which `kit generate` does not read, or in prose with a word before the marker.
+
+### The name
+
+The name is any run of characters with no whitespace and no backtick, separated from the marker by
+whitespace. It pairs the directive with its end marker, and it must be unique in the file. A region the kit
+delivers is named by its path.
+
+### The command
+
+The command is a bash command line, so pipes, redirections, and `$()` all work. It runs:
+
+- from the repository root
+- with the running kit's `bin/` first on `PATH`
+- with standard input closed
+- with `errexit` and `pipefail` set
+- with `KIT_GENERATE_FILE` set to the file and `KIT_GENERATE_REGION` set to the region's name
+
+The command is everything between the first backtick after the name and the last backtick before the comment
+closer. It cannot contain a literal backtick; use `$()` instead. A command that needs more than one line belongs
+in a script in the tree, where it can be read and tested.
+
+### No command
+
+A directive with no command runs `kit region`. `kit region` reads the region's name from its environment and
+treats it as the path of a region an active module delivers. A name no module delivers fails, and the error names
+the directive's line, so a forgotten command never passes silently. The directive can be in any file; the name
+only selects the region.
 
 ## Nesting and balance
 
-Every unit is balanced on its own: the file as written, and each command's output. A directive opened in a unit
-closes in that unit; an end marker closes the region most recently opened there. A command's output may open
-regions of its own, each closed in that same output, and `kit generate` expands those in turn, depth first, so a
-region nests and one pass settles a file. An output that closes a region it did not open, or opens one it does
-not close, is refused, naming the file, the directive's line, and the command. A region that nests is therefore
-always one the enclosing command wrote; a hand-written directive inside a region is replaced with the rest of the
-region's content.
+Each unit must be balanced on its own. A unit is either the file as written or one command's output.
+
+- A region opened in a unit must close in that unit.
+- An end marker closes the region most recently opened in that unit.
+- A command's output may open regions of its own, as long as it closes them in the same output. `kit generate`
+  expands those too, depth first, so regions can nest and one pass settles a file.
+- An output that closes a region it did not open, or opens one it does not close, is refused. The error names the
+  file, the directive's line, and the command.
+
+So a nested region is always one the enclosing command wrote. A hand-written directive inside a region is
+replaced along with the rest of the region's content.
+
+## Commands
+
+`kit generate [<path>…]` expands the regions in files.
+
+- Named paths are relative to the directory you typed the command in. Each named file gets one pass, or up to
+  `--iterations=<n>` passes.
+- With no paths, it expands every tracked file and every untracked file git does not ignore. It repeats passes
+  until a pass changes nothing, up to twenty passes or `--iterations=<n>`, because one command may read another
+  file's region.
+- A run over the whole repository that is still changing at the limit fails. The cause is a command whose output
+  depends on its own output.
 
-## The verbs
+`kit generate --check [<path>…]` runs one pass, writes nothing, and fails naming every stale file. It runs
+in two places:
 
-`kit generate [<path>…]` expands the named files, taken from the directory the command was typed in, or with
-none named every tracked file and every untracked one git does not ignore. Named files are expanded once, or
-`--iterations=<n>` times. The whole repository is expanded until a pass changes nothing, at most twenty passes or
-`--iterations=<n>`, since a command may read another file's region. A run that is still changing at the bound
-fails, naming the cause: a command whose output depends on its own output.
+- `kit check`, over the whole repository, so `kit ci` checks every generated region, the kit's and the
+  repository's own.
+- The `lefthook` module's pre-commit hook, over the staged paths.
 
-`kit generate --check [<path>…]` runs one pass without writing and fails naming every stale file. `kit check`
-runs it over the whole repository, so the gate holds every generated region, the kit's and the repository's own,
-and the lefthook module's pre-commit hook runs it over the staged paths.
+`kit region [--home] [<path>]` prints the content the active modules deliver as the region at a path, rendered
+the way a template is. It is the command behind every region the kit delivers.
 
-`kit region [--home] [<path>]` prints the content the active modules deliver as the region at a path, rendered as
-a template is, the command behind every region the kit delivers. The path defaults to `KIT_GENERATE_REGION`, so
-a bare directive needs none. One active module delivers a region at a path, so the answer is that module's
-`regions/<base>/<path>`, and a path no active module delivers is refused.
+- The path defaults to `KIT_GENERATE_REGION`, so a bare directive needs no argument.
+- Only one active module can deliver a region at a given path. `kit region` prints that module's
+  `regions/<base>/<path>`.
+- A path no active module delivers is refused.
 
 ## What is refused
 
-A file is rewritten only on a clean expansion. Each of these leaves the file as it was and fails the run, naming
-the file and the line:
+`kit generate` rewrites a file only when the whole expansion succeeds. Each of these leaves the file unchanged and
+fails the run, naming the file and the line:
 
-- a command that fails;
-- a line that opens with the marker and is not a directive;
-- an end marker with no open region, or naming a region other than the one open;
-- a directive whose region never closes, in the file or in a command's output;
-- a name opened twice in the expanded file;
-- a fenced code block in a markdown file, or in a command's output, that opens and never closes, since the
-  directives after it could not be read;
-- a conflict marker in the file, a line of seven `<` or `>`, since a conflicted file is not input a region
-  expander can read.
+- a command that fails
+- a line that starts with the marker and is not a directive
+- an end marker with no open region, or one that names a region other than the open one
+- a directive whose region never closes, in the file or in a command's output
+- a name opened twice in the expanded file
+- in a markdown file or a command's output, a fenced code block that never closes, since the directives after it
+  could not be read
+- a conflict marker in the file (a line of seven `<` or `>`), since a conflicted file cannot be expanded
 
 ## The kit's regions
 
-A file under a module's `regions/<base>/<path>` is a template for the content of a region: every `@key@` in it
-is rendered from `.kit/settings.yml` and the module's defaults, as [modules.md](modules.md) describes. What
-`kit install` writes into the file at `<path>` is the bare directive naming the path, the rendered content, and
-the end marker, in the file's comment syntax: between the directive and the end marker where the file already
-carries them, appended after a blank line where it does not, and as the whole file where there is none. The
-repository moves the block where it likes and writes what it likes around it. `kit update` regenerates the
-region, and there is no three-way merge of one, since its content is never the repository's to edit;
-`kit module remove` takes the block out, and removes a file it leaves empty. A directive with no end marker is
-refused by name, and two modules delivering a region to one file are refused where the modules are read. A region
-under `home` spells its command, `kit region --home <path>`, since the bare form cannot.
-
-The `kit` module places two: the sentence in `AGENTS.md` that sends every agent to `.kit/1st.md`, and the
-`/worktrees/` entry in `.gitignore`. The `claude` module places one in `.claude/CLAUDE.md`, importing
-`AGENTS.md`. [modules.md](modules.md) describes a module, and [architecture.md](architecture.md) the whole.
+A file under a module's `regions/<base>/<path>` is a template for a region's content. Every `@key@` in it is
+rendered from `.kit/settings.yml` and the module's defaults, as [modules.md](modules.md) describes.
+
+`kit install` writes the region into the file at `<path>`: the bare directive naming the path, the rendered
+content, and the end marker, in the file's comment syntax. Where the block goes depends on the file:
+
+- The file has the directive and end marker: the content goes between them.
+- The file exists without them: the block is appended after a blank line.
+- The file does not exist: the block becomes the whole file.
+
+After that:
+
+- The repository can move the block anywhere in the file and write anything around it.
+- `kit update` regenerates the region. There is no three-way merge, because the region's content is never the
+  repository's to edit.
+- `kit module remove` takes the block out, and removes the file if that leaves it empty.
+- A directive with no end marker is refused, by name.
+- Two modules that deliver a region to the same file are refused when the kit reads the modules.
+- A region under `home` must spell out its command, `kit region --home <path>`, because the bare directive cannot
+  select the home directory.
+
+| Module | File | Region |
+| --- | --- | --- |
+| `kit` | `AGENTS.md` | the sentence that sends every agent to `.kit/1st.md` |
+| `kit` | `.gitignore` | the `/worktrees/` entry |
+| `claude` | `.claude/CLAUDE.md` | an import of `AGENTS.md` |
+
+[modules.md](modules.md) describes modules, and [architecture.md](architecture.md) describes the whole kit.
diff --git a/docs/modules.md b/docs/modules.md
index e626288..1dcc1aa 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -1,7 +1,16 @@
 # Modules
 
-Everything the kit delivers is a module: a directory under `modules/` in the release. A repository activates the
-modules it wants, and `kit install`, `kit update`, and `kit check` work over the active set.
+A module is a directory under `modules/` in a release, and everything the kit delivers comes from one. A repository
+activates the modules it wants, and `kit install`, `kit update`, and `kit check` work on that active set.
+
+## Activation
+
+- `kit install [<module>…]` activates `kit`, the one default module, plus the named modules and their
+  dependencies. It records the set on the `modules` line of `.kit/manifest`.
+- `kit module list` shows every module the release has, and which are active.
+- `kit module add <module>…` activates more modules, placing only the paths the new set adds to the old one.
+- `kit module remove <module>…` deactivates modules. It removes the paths only the removed modules delivered,
+  and takes the kit's entries back out of any merged `.json` file.
 
 ## Layout
 
@@ -14,23 +23,25 @@ modules/<name>/
   docs/               the module's documentation; packed with the release, placed in no repository
 ```
 
-A module may have any of `files/`, `templates/`, `regions/`, and `docs/`; `module.yml` it must have. A base names
-where a file lands:
+A module must have `module.yml`. `files/`, `templates/`, `regions/`, and `docs/` are optional. The base
+sets where a file lands:
 
 | Base | Root | Record |
 | --- | --- | --- |
 | `repo` | the repository root | `.kit/manifest`, committed with the repository |
-| `home` | the user's home directory, `~` | `~/.kit/manifest`, the desk's own; a runner has none |
+| `home` | the user's home directory, `~` | `~/.kit/manifest`, on the user's machine; a CI runner has none |
 
-So `files/home/.kit/<name>` is a user-level setting, delivered once per desk by whichever repository installs or
-updates last. `kit check` holds home paths to the release where `~/.kit/manifest` exists and says so where it does
-not, since a runner installs nothing there. A module naming any other base is refused at install with the known
-bases listed. `KIT_HOME` stands in for the home directory, which is how the tests keep out of the real one.
+- `files/home/.kit/<name>` is a user-level setting. Each machine has one copy, from whichever repository installed
+  or updated last.
+- `kit check` compares home paths with the release where `~/.kit/manifest` exists. Where it does not, as on a
+  runner, which installs nothing there, `kit check` reports that it did not check them.
+- A module that names any other base is refused at install, and the error lists the known bases.
+- `KIT_HOME` replaces the home directory. The tests use it to stay out of the real one.
 
 ## Metadata
 
-`module.yml` is the small subset of YAML `bin/yaml.sh` reads: scalars, lists of `- item`, and one level of map.
-A line starting with `#` is a comment.
+`module.yml`, a rule's frontmatter, and `.kit/settings.yml` all use the small subset of YAML that `bin/yaml.sh`
+reads: scalars, lists of `- item`, and one level of map. A line starting with `#` is a comment.
 
 ```yaml
 description: "One GitHub Actions job that runs kit ci"
@@ -43,31 +54,51 @@ answers:
 
 | Key | Meaning |
 | --- | --- |
-| `description` | One line, shown by `kit module list`. |
-| `default` | `true` for a module active unless removed: `kit`. |
+| `description` | Required. One line, shown by `kit module list`. |
+| `default` | `true` makes the module active unless removed. In this release only `kit` sets it. |
 | `depends` | Modules activated with this one. `kit module remove` refuses a module another active module depends on. |
 | `answers` | The default value of each template key. A repository overrides one under `answers:` in `.kit/settings.yml`. |
 | `expects` | Lines the module expects in files the repository owns, each a `path`, a `pattern`, and a `remedy`; see below. |
 
-[module.schema.json](../modules/module.schema.json) is the schema, JSON Schema 2020-12. This repository's gate validates
-every `module.yml` against it with `ajv`, and `kit install` holds a module to the same contract where no validator is: a
-key it does not know, a `default` that is not `true` or `false`, or a dependency the release lacks is refused, naming
-it.
+[module.schema.json](../modules/module.schema.json) is the schema, in JSON Schema 2020-12. This repository's gate
+(its own CI command) validates every `module.yml` against it with `ajv`. Without a validator, `kit install` applies
+the same contract and refuses, naming the problem:
+
+- a key it does not know
+- a missing `description`
+- a `default` that is not `true` or `false`
+- a dependency the release does not have
 
 ## Delivery
 
-A file under `files/<base>/` is placed at the same path under the base's root. A destination ending in `.json`, other
-than a schema, `*.schema.json`, is merged by key: the kit's keys are set, its array entries added, and on update or
-removal only the previous release's entries are taken out, so a repository's own keys and entries survive. Every other
-destination is a copy. Where two active modules deliver the same path, the later module in dependency order wins.
+Each kind of source file is placed differently:
+
+| Source | How it is placed |
+| --- | --- |
+| `files/<base>/<path>` | At `<path>` under the base's root: merged by key for a `.json` file, copied otherwise. |
+| `templates/<base>/<path>` | Rendered, then placed like a `files/` file. |
+| `regions/<base>/<path>` | Rendered, then written as a region inside the file at `<path>`. |
+
+### Copies and merges
+
+- A destination ending in `.json` is merged by key, except a schema (`*.schema.json`). The kit sets its keys and
+  adds its array entries. On update or removal it takes out only the previous release's entries, so the
+  repository's own keys and entries stay.
+- Every other destination is a copy.
+- Where two active modules deliver the same path, the later module in dependency order wins.
 
-Where a format composes, a module delivers a whole file of its own under `.kit/` and expects the repository's file to
-take it with one include line: lefthook's `extends`, just's `import`, git's `include`, markdownlint's `extends`. The
-module says so under `expects:`, a `path`, an extended regular expression some line of that file must match, and a
-`remedy`. `kit install` and `kit module add` name each one not yet met as left to do, `kit check` refuses until it is,
-and the kit writes nothing into the file, which stays the repository's entirely. The rule for any file the kit touches
-is then: an include where the format composes, a region where it has comments, a merge by key where it has neither, and
-a copy only where the file is the kit's own.
+### Includes
+
+Where a file format supports includes, a module delivers a whole file of its own under `.kit/`. It then expects
+the repository's file to include it with one line:
+
+- lefthook's `extends`
+- just's `import`
+- git's `include`
+- markdownlint's `extends`
+
+The module declares each such line under `expects:`. An entry has a `path`, a `pattern` (an extended regular
+expression that some line of that file must match), and a `remedy`.
 
 ```yaml
 expects:
@@ -76,36 +107,74 @@ expects:
     remedy: "put extends: [.kit/lefthook.yml] in lefthook.yml, so the kit's pre-commit commands run"
 ```
 
-A single-quoted value is taken literally, backslashes and all, which is how a pattern is written.
-
-A file under `regions/<base>/` is the content of a region inside the file at the same path, rendered as a template
-is. What is placed there is the bare directive `kit:generate <path>`, the content, and the marker `kit:end <path>`, in
-the file's own comment syntax: `<!-- … -->` in markdown, `#` elsewhere, as [generate.md](generate.md) describes. Where
-the file carries the directive already, the content between it and the end marker is made what `kit region` prints;
-where it does not, the block is appended after a blank line; where there is no file, it is made of the block alone. The
-repository may move the block anywhere in the file and write what it likes around it. `kit check` holds the region to
-its command, `kit update` regenerates it, never merges it, and removal takes the block out and leaves the rest, removing
-a file it leaves empty. One file holds one kit region, and two modules delivering a region to the same path are refused
-by name. A kind of file the kit cannot mark is refused. The `kit` module places two: the sentence in `AGENTS.md` that
-sends every agent to `.kit/1st.md`, and the `/worktrees/` entry in `.gitignore`.
-
-A file under `templates/<base>/`, and one under `regions/<base>/`, is rendered first. Every `@key@` in it, autoconf's
-form, is replaced by the key's value, then the result is placed, digested, and merged exactly as a `files/` file is.
-The form is one neither bash's `${var}` nor GitHub's `${{ }}` can be mistaken for, so a template may carry both
-untouched. The context is the whole of `.kit/settings.yml`: a top-level setting as `@require_signing@`, a map's entry
-as `@answers.ci_runner@`, and a bare `@ci_runner@` meaning the entry under `answers:`. A key with no value there takes
-the module's default under its own `answers`, and a key with neither refuses the install, naming the key and the module.
-
-The same YAML subset is what a rule's frontmatter and `.kit/settings.yml` are written in, read by `bin/yaml.sh` in
-all three places, so a rule's lists, a module's `depends:`, and the settings have one reader among them.
+- `kit install` and `kit module add` list each unmet expectation as left to do.
+- `kit check` fails until every expectation is met.
+- The kit writes nothing into the file. It belongs entirely to the repository.
+
+A single-quoted value is taken literally, backslashes included. Write patterns that way.
+
+The kit changes a file it touches in one of four ways:
+
+| When the file | The kit uses |
+| --- | --- |
+| has a format that supports includes | an include line the repository adds |
+| has a format with comments | a region |
+| supports neither | a merge by key |
+| belongs entirely to the kit | a copy |
+
+### Regions
+
+A file under `regions/<base>/` is the content of a region inside the file at the same path. It is rendered first,
+like a template. The kit writes three things in the file's comment syntax: the bare directive `kit:generate <path>`,
+the content, and the marker `kit:end <path>`. [generate.md](generate.md) describes directives. The comment syntax
+follows the file's extension:
+
+- `<!-- … -->` for markdown, HTML, XML, and SVG
+- `//` for JavaScript, TypeScript, Go, Rust, C, C++, Java, Kotlin, Swift, C#, and Scala
+- `--` for SQL, Lua, and Haskell
+- `#` for everything else
+
+The block is placed like this:
+
+- The file has the directive: the content between the directive and the end marker becomes what `kit region`
+  prints.
+- The file exists without the directive: the block is appended after a blank line.
+- The file does not exist: the block becomes the whole file.
+
+After that:
+
+- The repository can move the block anywhere in the file and write anything around it.
+- `kit check` checks the region against its command.
+- `kit update` regenerates the region and never merges it.
+- Removal takes the block out, leaves the rest of the file, and removes the file if that leaves it empty.
+- A file holds at most one kit region. Two modules that deliver a region to the same path are refused by name.
+- A kind of file whose comment syntax the kit does not know, such as JSON, is refused.
+
+### Templates
+
+Files under `templates/<base>/` and `regions/<base>/` are rendered before they are placed. Each `@key@`
+(autoconf's form) is replaced by the key's value. A template's result is then placed, digested, and merged exactly
+like a `files/` file. Bash's `${var}` and GitHub's `${{ }}` cannot be mistaken for `@key@`, so a template can
+contain both unchanged.
+
+The values come from the whole of `.kit/settings.yml`:
+
+- `@require_signing@` is a top-level setting.
+- `@answers.ci_runner@` is an entry in a map.
+- `@ci_runner@` is the entry under `answers:`.
+
+A key with no value in `.kit/settings.yml` takes the module's default from its own `answers`. A key with neither
+fails the install, and the error names the key and the module.
 
 ## Settings
 
-`.kit/settings.yml` is the repository's, read by the kit and never written by it, in the same YAML subset.
-[settings.schema.json](../modules/kit/files/repo/.kit/settings.schema.json) is its schema, delivered beside it as
-`.kit/settings.schema.json`, so an editor validates the file through the modeline
-`# yaml-language-server: $schema=settings.schema.json`; the kit holds the file to the schema's main points before
-every install, update, and check, naming an unknown key.
+`.kit/settings.yml` belongs to the repository. The kit reads it and never writes it.
+
+- Its schema is [settings.schema.json](../modules/kit/files/repo/.kit/settings.schema.json), delivered beside it as
+  `.kit/settings.schema.json`.
+- An editor validates the file through the modeline `# yaml-language-server: $schema=settings.schema.json`.
+- Before every install, update, and check, the kit checks the file against the schema's main points, and
+  names any unknown key.
 
 ```yaml
 answers:
@@ -114,42 +183,38 @@ answers:
 
 | Key | Meaning |
 | --- | --- |
-| `forge` | The provider the loop's verbs use, `github` or `gitlab`; detected from origin's host when absent, and named here for a self-hosted forge. |
-| `gate` | What `kit gate` runs; a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script is detected when absent. |
-| `require_signing` | `true` makes `kit issue` refuse a desk without a signing key. |
-| `answers` | The values a module's templates take, overriding the module's own defaults. |
-| `toolchains` | The tool managers that put the gate's tools on `PATH`, `mise`, `brew`, or `docker`; see [toolchains.md](toolchains.md). |
+| `forge` | The forge provider the workflow commands use, `github` or `gitlab`. The forge is the service that hosts the repository. When absent, it is detected from origin's host. Set it for a self-hosted forge. |
+| `gate` | What `kit gate` runs. When absent, the kit detects a justfile `ci` recipe, a Makefile `ci` target, or a `package.json` `ci` script. |
+| `require_signing` | `true` makes `kit issue` refuse to start when git has no `user.signingkey`. |
+| `answers` | The values a module's templates use, overriding the module's own defaults. |
+| `toolchains` | The tool managers that put the gate's tools on `PATH`: `mise`, `brew`, or `docker`; see [toolchains.md](toolchains.md). |
 | `policy` | The patterns a branch, a commit subject, and a change title must match; see [policy.md](policy.md). |
 | `policy_engine` | `patterns` or `opa`; see [policy.md](policy.md). |
-| `trackers` | The trackers besides the forge's own whose issues the loop takes, a prefix and a provider each; see [trackers.md](trackers.md). |
+| `trackers` | Trackers other than the forge's own whose issues the workflow accepts, each with a prefix and a provider; see [trackers.md](trackers.md). |
 
 ## Modules a repository defines
 
-A directory `.kit/modules/<name>/` in the repository is a module in every respect: `module.yml`, `files/<base>/`,
-`templates/<base>/`, `regions/<base>/`, and `docs/`. A name is looked up in the release first, then there. It is
-validated like a delivered module, may depend on delivered ones, is activated with `kit install <name>` or `kit module
-add <name>`, and `kit module list` shows it with its origin. Its paths are recorded in the manifest with their digests,
-so `kit check` tells an edited installed copy from its source, and on update its files are compared with its own current
-source, so an edit under `.kit/modules/` is never merged against a release. A rule file it places under `.kit/rules/` is
-found by `kit context` like any other.
-
-## Activation
+A directory `.kit/modules/<name>/` in the repository is a module in every respect. It has the same parts:
+`module.yml`, `files/<base>/`, `templates/<base>/`, `regions/<base>/`, and `docs/`.
 
-- `kit install [<module>…]` activates `kit`, the one default module, and the named ones, with their dependencies,
-  and records the set on the `modules` line of `.kit/manifest`.
-- `kit module list` shows every module the release carries and which are active.
-- `kit module add <module>…` activates more, placing only the paths the new set delivers beyond the old.
-- `kit module remove <module>…` deactivates, removing the paths only the removed modules delivered and taking the
-  kit's entries back out of a merged `.json`.
+- The kit looks up a module name in the release first, then in `.kit/modules/`.
+- It is validated like a delivered module, and it may depend on delivered modules.
+- Activate it with `kit install <name>` or `kit module add <name>`.
+- `kit module list` shows it with its origin.
+- Its paths are recorded in the manifest with their digests, so `kit check` can tell an edited installed copy
+  from its source.
+- On update, its files are compared with its own current source. An edit under `.kit/modules/` is never merged
+  against a release.
+- `kit context` finds a rule file it places under `.kit/rules/` like any other rule.
 
 ## This release's modules
 
 | Module | Default | Depends on | Delivers |
 | --- | --- | --- | --- |
-| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md`, `.kit/settings.schema.json`; regions in `AGENTS.md` and `.gitignore` |
-| `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` |
+| `kit` | yes | | `.kit/1st.md`, `.kit/rules/<kind>.md`, `.kit/templates/`, `.kit/settings.schema.json`, `.kit/markdownlint.jsonc`; regions in `AGENTS.md` and `.gitignore` |
+| `lefthook` | no | `kit` | `.kit/lefthook.yml`, a pre-commit hook running `kit lint` and `kit generate --check` |
 | `ci-github` | no | `kit` | `.github/workflows/kit-ci.yml`, from a template, running `kit ci`; answer `ci_runner` |
 | `claude` | no | `kit` | a region in `.claude/CLAUDE.md` importing `AGENTS.md`; `.claude/settings.json`, merged: the deny list and the `kit context --claude` hook |
 | `policy-opa` | no | `kit` | `.kit/policy/kit.rego`, the naming policy in Rego, so `kit policy` runs on Open Policy Agent |
 
-No module in this release delivers to `home`. Each module's `docs/README.md` says what it places and why.
+No module in this release delivers to `home`. Each module's `docs/README.md` describes what it places and why.
diff --git a/docs/policy.md b/docs/policy.md
index c0ba695..0b1c232 100644
--- a/docs/policy.md
+++ b/docs/policy.md
@@ -1,12 +1,21 @@
 # Policy
 
-What a branch, a commit subject, or a change's title may be is a policy, and a policy is checked, not described.
-`kit policy` gathers the facts once and an engine names every refusal; `kit ci` runs it beside the gate, so a name
-off the policy fails the delivered check like a failing test.
+A policy is the set of patterns that a branch name, a commit subject, and a change's title must match. A change is
+a pull request on GitHub or a merge request on GitLab. Run `kit policy` to check the current branch; it prints each
+name that breaks the policy and fails.
+
+```sh
+kit policy
+```
+
+- `kit policy` gathers the facts once, then the policy engine reports every refusal.
+- `kit ci` runs it beside the gate (the repository's own CI command), so a name that breaks the policy fails the
+  delivered check like a failing test.
+- On a runner, the refusals also appear in the step summary.
 
 ## The facts
 
-`kit policy --input` prints the document every engine reads:
+`kit policy --input` prints the JSON document every engine reads:
 
 ```json
 {
@@ -18,21 +27,27 @@ off the policy fails the delivered check like a failing test.
 }
 ```
 
-The branch is the change's head on a runner and the current branch on a desk; on the default branch, or detached,
-nothing is under check. The commits are those past the fork from the default branch at origin, merges aside, which
-is why the delivered workflow fetches full history. The change is read through the forge, and is `null` where no
-forge or no change answers.
+| Field | Contents |
+| --- | --- |
+| `branch` | On a runner, the change's head branch. In the root checkout (the desk), the current branch. On the default branch or a detached checkout it is `null`, and nothing is checked. |
+| `default_branch` | The repository's default branch. |
+| `commits` | Each commit past the fork from the default branch at origin, merges excluded. The delivered workflow fetches full history for this. When the fork is not found, as in a shallow clone, no commit is checked and `kit policy` warns. |
+| `change` | The change's number, title, and body, read through the forge (the service that hosts the repository). `null` when there is no forge or no change. |
+| `policy` | The patterns, with the kit's defaults filled in. |
 
 ## The rules
 
-`policy:` in `.kit/settings.yml` holds one extended regular expression per subject. A subject absent takes the
-kit's default, the loop's own names from `.kit/1st.md`; an empty pattern turns that rule off.
+`policy:` in `.kit/settings.yml` holds one extended regular expression per subject.
+
+- A subject that is absent takes the kit's default: the workflow's own naming from `.kit/1st.md`.
+- An empty pattern turns that rule off.
+- A subject the kit does not know is refused.
 
 | Subject | Checks | Default |
 | --- | --- | --- |
-| `branch` | the branch's name | `^[a-z0-9]+-[a-z0-9][a-z0-9-]*$`, as `kit issue` makes it |
-| `commit_subject` | every commit's subject past the fork | `^([A-Z]+)?#[0-9]+ [^ ]`, opening with its issue's reference |
-| `change_title` | the open change's title | `^[^[:cntrl:]]{1,120}$`, one line of at most 120 |
+| `branch` | the branch's name | `^[a-z0-9]+-[a-z0-9][a-z0-9-]*$`, the form `kit issue` creates |
+| `commit_subject` | every commit's subject past the fork | `^([A-Z]+)?#[0-9]+ [^ ]`, starting with its issue's reference |
+| `change_title` | the open change's title | `^[^[:cntrl:]]{1,120}$`, one line of at most 120 characters |
 
 ```yaml
 policy:
@@ -40,17 +55,26 @@ policy:
   commit_subject: ''
 ```
 
-A single-quoted pattern is taken literally. Write in the subset bash's extended regular expressions and OPA's RE2
-share, character classes, anchors, alternation, and counted repetition, so either engine reads it the same way.
+A single-quoted pattern is taken literally. Write patterns in the subset that bash's extended regular expressions
+and OPA's RE2 share, so both engines read them the same way:
+
+- character classes
+- anchors
+- alternation
+- counted repetition
 
 ## The engines
 
-- `patterns`, the default, matches each rule in bash and needs no tool.
-- `opa`, Open Policy Agent, evaluates every `.rego` file under `.kit/policy/`, package `kit.policy`, the set
-  `deny` of strings being the refusals. It is chosen by `policy_engine: opa`, or by a `.rego` file being there. The
-  `policy-opa` module delivers `.kit/policy/kit.rego`, the patterns engine's rules in Rego, refusal for refusal, so
-  taking it changes nothing until the repository adds a rule a pattern cannot say in a file of its own beside it.
-  The repository pins `opa` in its toolchain.
+| Engine | How it checks | Chosen by |
+| --- | --- | --- |
+| `patterns` | Matches each rule in bash. Needs no other tool. | Default. |
+| `opa` | Open Policy Agent evaluates every `.rego` file under `.kit/policy/`, package `kit.policy`. The set `deny` of strings is the refusals. | `policy_engine: opa`, or any `.rego` file in `.kit/policy/`. |
+
+The `opa` engine needs `opa`. Pin it in the repository's toolchain.
+
+The `policy-opa` module delivers `.kit/policy/kit.rego`: the patterns engine's rules written in Rego, with the same
+refusals. Because it is a `.rego` file, adding the module selects the `opa` engine, and the results stay the same.
+Write a rule that a pattern cannot express in a separate `.rego` file beside it:
 
 ```rego
 package kit.policy
@@ -63,4 +87,4 @@ deny contains msg if {
 }
 ```
 
-`tests/policy.bats` holds the two engines to the same refusals on the same facts.
+`tests/policy.bats` checks that both engines give the same refusals for the same facts.
diff --git a/docs/templates.md b/docs/templates.md
new file mode 100644
index 0000000..79c0292
--- /dev/null
+++ b/docs/templates.md
@@ -0,0 +1,104 @@
+# Templates
+
+A template is a file of one kind with holes in it, attached to the rule for that kind. `kit new file` fills
+the holes to make a new file, and `kit lint` checks that every existing file still has the shape of one of
+its rule's templates.
+
+```sh
+kit new file "${path}" --purpose="${purpose}"
+```
+
+## Where a template lives
+
+A rule lists its templates in its frontmatter, in the order they are tried. Each template is a variant of the file,
+stored at `.kit/templates/<rule>/<variant>`. A variant can be limited to one path glob (`path:`) or marked
+executable (`executable: true`):
+
+```yaml
+templates:
+  - variant: root
+    path: justfile
+  - variant: module
+```
+
+| Rule | Variant | Limited to | Notes |
+| --- | --- | --- | --- |
+| bash | `script` | | executable |
+| bash | `module` | | a sourced file |
+| just | `root` | `justfile` | |
+| just | `module` | | |
+| markdown | `agents` | `AGENTS.md` | |
+| markdown | `document` | | |
+| markdown | `notice` | | |
+| markdown | `frontmatter` | | |
+| yaml | `document` | | |
+| workflows | `workflow` | | |
+| gitignore | `file` | | |
+| gitignore | `region` | `.gitignore` | a file the kit made of its region alone |
+
+The JSON rule has no template. A JSON file has no comments and no fixed opening, so there is no shape to check.
+
+The `kit` module delivers the templates. To change one, write a module of your own under `.kit/modules/` that
+depends on `kit` and places a file at the same path. The later module in dependency order wins.
+see: [modules.md](modules.md)
+
+## Holes
+
+A hole is a name between guillemets, `«name»`. No file kind the rules govern uses guillemets.
+
+| Hole | When making a file | When checking a file |
+| --- | --- | --- |
+| Within a line | Replaced by a value. | Matches any text on that line. A hole used twice must match the same text each time. |
+| A line of its own | Replaced by the value's lines. With no value, one blank line, or nothing when it is the template's last line. | Matches any run of lines, including none. |
+
+For example, the just module template's `«stem»_justfile` appears twice, because it is the variable its help
+recipe reads.
+
+`path`, `name`, and `stem` come from the path. For `bin/deploy.sh` they are `bin/deploy.sh`, `deploy.sh`, and
+`deploy`. Every other hole within a line takes its value from the flag of the same name, such as `--purpose=<…>`
+or `--title=<…>`. A missing flag is refused, and the error names it.
+
+## Making a file
+
+```sh
+kit new file "${path}" [--rule="${rule}"] [--variant="${variant}"] [--"${hole}"="${value}"]…
+```
+
+- The path is relative to the repository root, wherever you type the command. A path outside the repository, or
+  one that already exists, is refused. Nothing is overwritten.
+- The rule is the most specific rule that governs the path and has templates: the one whose matching glob has the
+  most characters other than wildcards. So `.github/workflows/check.yml` gets the workflows rule, not the YAML
+  rule. Use `--rule` when the path alone cannot select a rule, such as a script with no extension.
+- The variant is the first one the rule lists that the path allows. Use `--variant` to pick another.
+- An executable variant is made executable.
+- The command then prints the rules to read before you write the rest, as `kit context` does, and records the call
+  in the context log.
+
+A new file is a starting point, not a finished file. For example, a workflow made from its template has empty
+`on:`, `permissions:`, and `jobs:` keys, and actionlint rejects it until you fill them in.
+
+## Checking a file
+
+For each path governed by a rule with templates, `kit lint` checks that the file has the shape of one
+variant its path allows. It does this in addition to running the rule's linter. When a file matches no
+variant, `kit lint` reports:
+
+- the variants it was checked against
+- the variant it follows furthest, and the line of that variant where the file stops matching
+
+```text
+❌ bin/release.sh does not have the shape of the bash template (script, module); it leaves .kit/templates/bash/module line 2: # «name» - «purpose»
+```
+
+Three kinds of path are not checked against any template:
+
+- a template itself
+- a module's region, which is a fragment of a file
+- a path that `.gitattributes` marks `linguist-generated`, because a tool writes it
+
+```text
+/.mise/locks/** linguist-generated
+```
+
+A template fixes the shape a rule requires: the lines a file must have, and their order. Style that varies line by
+line, such as the inside of a recipe or a function, is left to the rule's linter and the rule's text.
diff --git a/docs/toolchains.md b/docs/toolchains.md
index b3e1001..cba2d23 100644
--- a/docs/toolchains.md
+++ b/docs/toolchains.md
@@ -1,13 +1,20 @@
 # Toolchains
 
-The gate runs tools, and which tool manager puts them on a desk or a runner is the repository's decision: mise,
-Homebrew, or a container image. The kit asks every one the same questions through one seam, `toolchain:` in
-`bin/toolchain.sh`, so a desk, a runner, and the delivered CI job say the same thing whichever manages the tools.
+A toolchain is the tool manager that installs the tools the gate (the repository's own CI command) runs: mise,
+Homebrew, or a Docker container image. `kit toolchain` installs, reports on, and updates those tools the same way
+whichever manager the repository uses.
+
+```sh
+kit toolchain install
+```
+
+`bin/toolchain.sh` defines the interface, and each manager has a provider, `bin/toolchain-<name>.sh`, that
+implements it. Every provider answers the same calls, so the root checkout (the desk), a CI runner, and the
+delivered CI job report the same results whichever manager the repository uses.
 
 ## Declaring
 
-A repository declares its toolchains in `.kit/settings.yml`, in order, or the kit detects them from the files each
-one reads:
+A repository declares its toolchains in `.kit/settings.yml`, in order:
 
 ```yaml
 toolchains:
@@ -19,31 +26,42 @@ toolchains:
     image: example/toolchain
 ```
 
-| Provider | Detected from | Pins | Outdated means |
+- With no declaration, the kit detects toolchains from the files they read, in the order mise, brew, docker.
+- `file:` names a different file for brew or docker.
+- `image:` names the docker image. The default is `kit-toolchain`.
+- A provider the kit does not have is refused.
+
+| Provider | Detected from | Pins | Outdated when |
 | --- | --- | --- | --- |
-| `mise` | `mise.toml` or `.mise.toml` | each tool's version, resolved in `mise.lock` | `mise outdated` names it |
-| `brew` | `Brewfile` | a formula by name; a version only where the name carries it, `node@22` | `brew outdated` names it |
+| `mise` | `mise.toml` or `.mise.toml` | each tool's version, resolved in `mise.lock` | `mise outdated` lists it |
+| `brew` | `Brewfile` | a formula by name; a version only where the name contains it, `node@22` | `brew outdated` lists it |
 | `docker` | `toolchain.Dockerfile` | each base image by digest, `FROM name:tag@sha256:…` | the registry's digest for the tag differs, or there is none |
 
-## The verbs
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `kit toolchain list` | Prints each declared toolchain and the file it reads. |
+| `kit toolchain install` | Installs every toolchain's pinned tools: `mise install`, `brew bundle install --no-upgrade`, or a `docker build` of the image. The image is tagged by the file's digest, so an unchanged file is never rebuilt. |
+| `kit toolchain outdated` | Prints one line per tool that is behind its source. With `--check`, fails when there is one. |
+| `kit toolchain update` | Moves every tool to its latest version and rewrites the pins: `mise upgrade`, `brew upgrade` of the Brewfile's outdated formulae, or new `FROM` digests in the Dockerfile. Commit the files it rewrote. |
+| `kit toolchain path` | Prints the directories that put the tools first on `PATH`, for a runner's `GITHUB_PATH`. |
+| `kit toolchain run <command>…` | Runs a command with the tools. |
 
-- `kit toolchain install` installs every declared toolchain's pinned tools: `mise install`, `brew bundle install
-  --no-upgrade`, or a `docker build` of the image, tagged by the file's digest so an unchanged file is never rebuilt.
-- `kit toolchain outdated` prints one line per tool behind its source, and `--check` fails when there is one.
-- `kit toolchain update` moves every tool to its latest and rewrites the pins: `mise upgrade`, `brew upgrade` of the
-  Brewfile's outdated formulae, or the Dockerfile's `FROM` digests. Commit what it rewrote.
-- `kit toolchain path` prints the directories that put the tools first on `PATH`, for a runner's `GITHUB_PATH`.
-- `kit toolchain run <command>…` runs a command with the tools.
+`kit gate` runs the gate the same way:
 
-`kit gate` runs the gate the same way: with every toolchain's path first on `PATH`, or, where docker is declared,
-inside the image, the checkout mounted at `/work` and the caller's user, so what the gate writes is the caller's.
-The image needs `bash`, since the gate runs as `bash -c`.
+- Normally, with every toolchain's directories first on `PATH`.
+- When docker is declared, inside the image, with the checkout mounted at `/work` and run as the caller's user, so
+  the files the gate writes belong to the caller. The image needs `bash`, because the gate runs as `bash -c`.
 
 ## On a runner
 
-The delivered workflow runs `kit toolchain install` and appends `kit toolchain path` to the runner's `PATH`. Its
-one setup action puts the `mise` binary on the runner where the repository has a `mise.toml`, with its own install
-turned off; Homebrew and Docker are already on GitHub's hosted runners, and the brew provider finds Homebrew at
-its own prefix where the runner leaves it off `PATH`.
+The delivered workflow runs `kit toolchain install`, then appends the output of `kit toolchain path` to the
+runner's `PATH`.
+
+- Its one setup action puts the `mise` binary on the runner when the repository has a `mise.toml`. The action's
+  own install step is turned off.
+- Homebrew and Docker are already on GitHub's hosted runners.
+- The brew provider finds Homebrew at its own prefix when the runner leaves it off `PATH`.
 
-`tests/toolchain.bats` drives each provider through a fake of its tool.
+`tests/toolchain.bats` tests each provider against a fake of its tool.
diff --git a/docs/trackers.md b/docs/trackers.md
index 01a0bdb..69d5f3b 100644
--- a/docs/trackers.md
+++ b/docs/trackers.md
@@ -1,9 +1,15 @@
 # Trackers
 
-An issue lives in a tracker, and the tracker is not always the forge. GitHub issues and GitLab issues live in their
-forges; Azure DevOps work items do not, and a repository may use more than one tracker at once, as one that files bugs
-in GitHub issues and plans its work in Azure DevOps does. The loop's verbs ask about an issue through one seam,
-`tracker:` in `bin/tracker.sh`, and the reference says which tracker answers.
+A tracker is the system that holds a repository's issues. It can be the forge (the service that hosts
+the repository, GitHub or GitLab) or a separate system such as Azure DevOps. The syntax of an issue
+reference selects its tracker:
+
+```sh
+kit issue AB#4521
+```
+
+The workflow commands look up issues through one interface, `bin/tracker.sh`. A repository can use more than one
+tracker at once, for example GitHub issues for bugs and Azure DevOps for planned work.
 
 ## References
 
@@ -14,8 +20,11 @@ A reference names its tracker in its syntax, the way the trackers already write
 | `7` or `#7` | the forge's own issues, GitHub's or GitLab's |
 | `AB#4521` | an Azure DevOps work item, under a prefix the repository declares |
 
-`.kit/settings.yml` declares every tracker but the forge's own, one record each: the prefix a reference opens with,
-the provider that answers it, and the provider's own fields.
+`.kit/settings.yml` declares every tracker except the forge's own. Each record has:
+
+- `prefix`, the text a reference starts with
+- `provider`, the provider that handles the reference
+- the provider's own fields
 
 ```yaml
 trackers:
@@ -26,28 +35,42 @@ trackers:
     type: Task
 ```
 
-`#` is the forge's own tracker unless a record claims it. A reference no declared tracker answers is refused, naming
-the prefixes there are.
+`#` is the forge's own tracker unless a record claims it. A reference that matches no declared tracker is refused,
+and the error lists the known prefixes.
 
-## The verbs
+## Commands
 
-- `kit issue 7`, `kit issue AB#4521`, or both, primary first. Each issue is assigned to the caller as its tracker
-  knows the caller, which for Azure DevOps is the identity `az` is signed in as. The branch opens with the
-  reference's key, `7-<slug>` or `ab4521-<slug>`. The forge links a branch to one of its own issues and closes it on
-  merge; for any other, and for every secondary, `kit issue` adds a `Closes <reference>` line to the change's body,
-  which is what GitHub's Azure Boards integration reads as a link.
-- `kit linked` accepts a change that the forge says closes an open issue of the repository, or whose body names an
-  open issue of a declared tracker with a closing keyword: `Closes AB#4521`, `Fixes AB#4521`, `Resolves AB#4521`.
-- `kit tidy` reads a worktree's issue back from its branch's key and removes the worktree when the issue is closed
-  and the change is gone.
+- `kit issue 7`, `kit issue AB#4521`, or both, primary first:
+  - Each issue is assigned to the caller as its tracker knows the caller. For Azure DevOps, that is the
+    identity `az` is signed in as.
+  - The branch name starts with the reference's key: `7-<slug>` or `ab4521-<slug>`.
+  - The forge links a branch to one of its own issues and closes the issue on merge. For any other issue, and
+    for every secondary issue, `kit issue` adds a `Closes <reference>` line to the body of the change (the
+    pull request or merge request). GitHub's Azure Boards integration reads that line as a link.
+- `kit linked` passes when the forge reports that the change closes an open issue of the repository. It also
+  passes when the change's body names an open issue of a declared tracker with a closing keyword:
+  `Closes AB#4521`, `Fixes AB#4521`, or `Resolves AB#4521`.
+- `kit tidy` reads a worktree's issue from its branch's key. It removes the worktree when that issue is closed and
+  the branch has no change.
 
 ## Providers
 
-| Provider | Tool | Fields | Closed in |
+| Provider | Tool | Fields | Closed when the state is |
 | --- | --- | --- | --- |
 | `forge` | the forge's own, through `bin/forge.sh` | none | the forge's closed state |
-| `ado` | `az` with the `azure-devops` extension | `organization`, `project`, `type` | Closed, Done, Removed |
+| `ado` | `az` with the `azure-devops` extension | `organization`, `project`, `type` (default `Task`) | Closed, Done, or Removed |
+
+A provider is `bin/tracker-<name>.sh`. It implements these calls:
+
+| Call | Prints |
+| --- | --- |
+| `title <id>` | the issue's title |
+| `state <id>` | `OPEN` or `CLOSED` |
+| `assignees <id>` | the assignees' logins, space-separated |
+| `assign <id> <login>` | nothing; adds the assignee |
+| `me` | the caller's login in this tracker, which can differ from the forge's |
+| `create <title>` | the number of the issue it creates |
+| `url <id>` | the issue's browser URL |
 
-A provider is `bin/tracker-<name>.sh`, answering `title`, `state`, `assignees`, `assign`, `me`, `create`, and `url`.
-`tests/tracker.bats` drives the Azure DevOps provider through a fake of `az`; what only a real organization can
-prove, that `az` answers as the fixtures do, is not proven there.
+`tests/tracker.bats` tests the Azure DevOps provider against a fake `az`. It cannot prove that a real organization's
+`az` responds the way the fixtures do.
diff --git a/justfile b/justfile
index 266b4c3..fa337f4 100644
--- a/justfile
+++ b/justfile
@@ -1,21 +1,20 @@
 #!/usr/bin/env just --justfile
 # justfile - see: https://just.systems/man/en/
 # ----------------------------------------------------------------------------------------------------------------------
-# The root justfile: the gate, and the refresh of this repository's own installed copy. The loop's commands are
-# kit issue, rebase, tidy, and status, spelled that way and no other; mise.toml puts bin/ on PATH.
+# The root justfile: the gate (just ci) and just refresh, which rebuilds this repository's installed copy of its
+# own kit. For the workflow, use kit issue, rebase, tidy, and status, not the raw git commands. mise.toml puts bin/
+# on PATH.
 
 set dotenv-load := true
 set positional-arguments := true
 
-# A bash recipe body is hosted by the interpreter named here and marked [script], as the just rule asks. The
-# interpreter is named bare so it resolves through the PATH built below; bash comes from the machine, 4.4 or
-# later, as the kit itself requires.
+# Recipes marked [script] run under this interpreter, as the just rule requires. It is named bare so it resolves
+# through the PATH set below. bash comes from the machine and must be 4.4 or later, as for the kit itself.
 set script-interpreter := ['bash']
 
-# The mise-pinned toolchain's bin directories go first on PATH once, at parse time, so every recipe calls its
-# tools bare and the pinned tool wins over any other copy: the same directories mise-action puts on the
-# runner's PATH, so a desk and the runner cannot disagree about which tool ran. Idempotent by inspecting
-# PATH rather than a sentinel, so a nested just adds nothing.
+# Put mise's pinned tool directories first on PATH, once, at parse time. Recipes then call each tool by its bare
+# name and get the pinned version. mise-action puts the same directories on the runner's PATH, so a desk and the
+# runner run the same tools. A directory already on PATH is not added again, so a nested just changes nothing.
 export PATH := ```
   mise bin-paths 2>/dev/null | while IFS= read -r d
   do
@@ -36,11 +35,16 @@ _: help
 
 set export := true
 
-# The gate: kit lint over every tracked path, each rule's own linter, every module.yml and .kit/settings.yml
-# against their schemas, every link in the markdown resolved offline with its fragment, the bats suite, and
-# bin/kit check over this repository's installed copy of its own kit.
-# The runner runs it on every pull request, and a desk runs it the same way; the pre-commit hook is the narrower,
-# faster check over the staged paths.
+# The gate. It runs, in order:
+#
+#   - kit lint over every tracked path
+#   - ajv: every module.yml and .kit/settings.yml against its schema
+#   - lychee: every link in the markdown, offline, including fragments
+#   - the bats suite
+#   - bin/kit check over this repository's installed copy of its own kit
+#
+# CI runs it on every pull request, and a desk runs it the same way. The pre-commit hook is a faster check over the
+# staged paths only.
 #
 #   just ci
 [doc("🚦 The gate: kit lint, the schemas, the links, bats, kit check")]
@@ -55,15 +59,19 @@ ci:
   bin/kit check
   echo "✅ ci passed"
 
-# Bring this repository's own installed copies up to the index and stage the result. Here the checkout is the
-# release, so an edit under modules/ is an edit to the release, not a consumer's drift. Everything is done
-# against the index, what the commit will carry: the sources and the copies are exported from it, kit update
-# runs over the export with HEAD's release as the base of every merge, the release the copies were last made
-# from, and the export is staged back. A desk's unstaged text outside a region, or outside the kit's entries in
-# a merged JSON file, is not staged with it, and an entry the source dropped is retired, since the base still
-# carries it. The working tree then takes the same step, so a desk's copies agree with the index inside the
-# kit's parts. The pre-commit hook runs this on a commit that touches the source; by hand it is for a desk
-# without the hook.
+# Rebuild this repository's installed copies of its own kit from the index, and stage the result. In this
+# repository the checkout is the release, so an edit under modules/ is a change to the release, not drift.
+#
+# The recipe works on the index, which is what the commit will contain:
+#
+#   1. Export the index. Export HEAD's bin/ and modules/ as the base release, the one the copies were last built
+#      from.
+#   2. Run kit update over the exported index with that base, and stage the result.
+#   3. Run kit update in the working tree too, so the desk's copies match the index in the parts kit owns.
+#
+# Unstaged edits outside a region, or outside kit's entries in a merged JSON file, are not staged. An entry the
+# source removed is removed from the copy, because the base still has it. The pre-commit hook runs this when a
+# commit touches the source. Run it by hand on a desk without the hook.
 #
 #   just refresh
 [doc("🔁 Bring this repository's own installed copies up to the index, and stage the result")]
@@ -76,7 +84,7 @@ refresh:
   git checkout-index --all --prefix="${work}/index/"
   git archive HEAD bin modules | tar -x -C "${work}/base"
   cp "$(git rev-parse --git-path index)" "${work}/index.file"
-  # The export is no repository of its own: the ceiling keeps git from finding this one above the temp directory.
+  # The export is not a git repository. The ceiling stops git from finding this one above the temp directory.
   (cd "${work}/index" && GIT_CEILING_DIRECTORIES="${work}" KIT_BASE="${work}/base" bin/kit update >/dev/null)
   GIT_DIR=$(git rev-parse --absolute-git-dir) GIT_WORK_TREE="${work}/index" GIT_INDEX_FILE="${work}/index.file" \
     git -C "${work}/index" add --all
diff --git a/lefthook.yml b/lefthook.yml
index 1d14761..99e0e7e 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,8 +1,8 @@
 # lefthook.yml - this repository's git hooks; see: https://lefthook.dev
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# The linters come from the kit's installed fragment, the way a consumer takes them: kit lint over the staged
-# paths, each rule's own linter. This repository adds the refresh of its installed copies. Once per clone:
+# The linters come from the kit's installed .kit/lefthook.yml, as in any consumer repository: kit lint over the
+# staged paths. This repository adds a step that refreshes its installed copies. Once per clone, run:
 # lefthook install
 
 extends:
@@ -10,8 +10,8 @@ extends:
 
 pre-commit:
   commands:
-    # A change to a delivered file's source rewrites the installed copies in the same commit; the recipe stages
-    # what it rewrote.
+    # When a commit changes a delivered file's source, rebuild the installed copies in the same commit. The recipe
+    # stages what it rebuilt.
     refresh:
       glob: "modules/**"
       run: just refresh
diff --git a/mise.toml b/mise.toml
index 52ff7bc..442e20e 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,29 +1,33 @@
 # mise.toml - the pinned tools a desk and a runner share; see: https://mise.jdx.dev/configuration/environments.html
 #
-# mise reads this file always, mise.desk.toml on top of it when MISE_ENV=desk, which a desk exports in its shell
-# profile, and mise.ci.toml when MISE_ENV=ci, which the CI workflow sets. A tool goes in the file of whoever runs
-# it; Lefthook is a desk's alone, and nothing is the runner's alone. `lockfile = true` records each pin's
-# exact resolution in a lock beside its file. git and bash come from the machine.
+# mise always reads this file. It also reads:
+#
+#   - mise.desk.toml when MISE_ENV=desk, which a desk exports in its shell profile
+#   - mise.ci.toml when MISE_ENV=ci, which the CI workflow sets
+#
+# Put a tool in the file for whoever runs it. Lefthook runs only on a desk; no tool runs only on the runner.
+# `lockfile = true` records each pin's exact version in a lock file beside its file. git and bash come from the
+# machine.
 
 [settings]
 lockfile = true
-# A lock written on a desk carries the runner's platform too; see: https://mise.jdx.dev/dev-tools/mise-lock.html
+# A lock written on a desk also covers the runner's platforms; see: https://mise.jdx.dev/dev-tools/mise-lock.html
 lockfile_platforms = ["linux-x64", "linux-arm64", "macos-arm64", "macos-x64"]
 
-# bin/ on PATH, so `kit` is spelled here as a consumer spells it.
+# Put bin/ on PATH, so `kit` runs here the same way it runs in a consumer repository.
 [env]
 _.path = ["bin"]
 
 # Why each tool is here:
 #   actionlint          the workflows rule's linter, over .github/workflows/, in kit lint and the gate
 #   bats                runs tests/, the suite the gate runs
-#   gh                  the GitHub provider's tool: the loop's verbs, kit linked, and kit release publish and retire
+#   gh                  the GitHub provider's tool: workflow commands, kit linked, kit release publish and retire
 #   jq                  reads and writes JSON: the merged .claude/settings.json, the forge's documents, kit status
-#   just                runs the justfile: just ci, the gate, and just refresh, the installed copies
+#   just                runs the justfile: just ci (the gate) and just refresh (the installed copies)
 #   lychee              checks every link in the markdown, offline, fragments included, in the gate
 #   ajv-cli             validates every module.yml and .kit/settings.yml against their schemas, in the gate
 #   markdownlint-cli2   the markdown rule's linter, over every .md file, in kit lint and the gate
-#   opa                 the opa policy engine, which tests/policy.bats holds to the patterns engine's refusals
+#   opa                 the OPA policy engine; tests/policy.bats checks it matches the patterns engine
 #   shellcheck          the bash rule's linter, over bin/ and tests/, in kit lint and the gate
 [tools]
 actionlint = "1.7"
diff --git a/modules/ci-github/docs/README.md b/modules/ci-github/docs/README.md
index 36be0dc..d3a599e 100644
--- a/modules/ci-github/docs/README.md
+++ b/modules/ci-github/docs/README.md
@@ -1,14 +1,19 @@
 # The ci-github module
 
-Places `.github/workflows/kit-ci.yml`: one GitHub Actions job, `CI`, run for a pull request into the default branch. It
-fetches full history, which `kit policy` reads; puts `kit` on `PATH`, from the kit's own checkout where `.kit/manifest`
-says `unreleased` and from the release the manifest names otherwise; installs the gate's tools with `kit toolchain
-install`, whichever of mise, Homebrew, or a container image manages them; and runs `kit ci`: the gate, `kit check`, `kit
-linked`, and `kit policy`, every one reported.
-
-Its one setup action, `jdx/mise-action` with its own install turned off, puts the `mise` binary on the runner where the
-repository has a `mise.toml`; Homebrew and Docker are on GitHub's hosted runners already. A repository on another CI
-calls `kit toolchain install` and `kit ci` from its own pipeline.
-
-The workflow is a template with one key, `ci_runner`, the label the job runs on. Its default is `ubuntu-latest`;
-a repository with runners of its own sets `ci_runner` under `answers:` in `.kit/settings.yml`.
+Delivers `.github/workflows/kit-ci.yml`: one GitHub Actions job, `CI`, that runs for each pull request into the
+default branch. The job:
+
+1. Fetches the full history, which `kit policy` reads.
+2. Puts `kit` on `PATH`. Where `.kit/manifest` says `unreleased`, it uses the kit's own checkout. Otherwise it
+   uses the release the manifest names.
+3. Installs the gate's tools with `kit toolchain install`, whether mise, Homebrew, or a container image manages
+   them. The gate is the repository's own CI command, such as `just ci`.
+4. Runs `kit ci`, which runs the gate, `kit check`, `kit linked`, and `kit policy`, and reports each one.
+
+The workflow has one setup action: `jdx/mise-action`, with its own install turned off. It puts the `mise` binary
+on the runner when the repository has a `mise.toml`. GitHub's hosted runners already have Homebrew and Docker.
+
+A repository on another CI system calls `kit toolchain install` and `kit ci` from its own pipeline.
+
+The workflow is a template with one key, `ci_runner`: the label of the runner the job runs on. The default is
+`ubuntu-latest`. A repository with its own runners sets `ci_runner` under `answers:` in `.kit/settings.yml`.
diff --git a/modules/ci-github/module.yml b/modules/ci-github/module.yml
index 76ad45e..4aa4f98 100644
--- a/modules/ci-github/module.yml
+++ b/modules/ci-github/module.yml
@@ -1,6 +1,6 @@
 # modules/ci-github/module.yml - the ci-github module: one GitHub Actions job that runs kit ci
 # ----------------------------------------------------------------------------------------------------------------------
-# docs/modules.md says what each key means.
+# see: docs/modules.md
 
 description: "One GitHub Actions job that runs kit ci: the gate, kit check, and the linked-open-issue refusal"
 depends:
diff --git a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
index a78a148..e1fc752 100644
--- a/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
+++ b/modules/ci-github/templates/repo/.github/workflows/kit-ci.yml
@@ -1,15 +1,17 @@
 # kit-ci.yml - the check the kit delivers for GitHub Actions: kit ci on every pull request into the default branch
 # ----------------------------------------------------------------------------------------------------------------------
 #
-# One job, CI, which is the check name a ruleset requires, run for a pull request into the default branch. It
-# takes the kit release .kit/manifest names from its public URL, or this checkout's own bin/ where the manifest
-# says unreleased, installs the gate's tools with `kit toolchain install`, whichever of mise, brew, or docker
-# manages them, and runs `kit ci`: the gate, `kit check`, `kit linked`, and `kit policy`, every one reported. The
-# one setup action puts the mise binary on the runner where the repository has a mise.toml; brew and docker are
-# on GitHub's runners already.
+# Runs one job, CI, on each pull request into the default branch. CI is the check name a ruleset requires. The job:
 #
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner
-# answer, from answers: in .kit/settings.yml.
+#   1. puts mise on the runner, when the repository has a mise.toml (brew and docker are already on GitHub's
+#      runners)
+#   2. puts kit on PATH: the release .kit/manifest records, downloaded from its public URL, or this checkout's own
+#      bin/ when the manifest records unreleased
+#   3. installs the gate's tools with `kit toolchain install`, whichever of mise, brew, or docker manages them
+#   4. runs `kit ci`: the gate, `kit check`, `kit linked`, and `kit policy`, and reports every result
+#
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. runs-on is the ci_runner value
+# under answers: in .kit/settings.yml.
 #
 # see: .kit/1st.md
 
@@ -29,13 +31,13 @@ jobs:
     if: github.event.pull_request.base.ref == github.event.repository.default_branch
     runs-on: "@ci_runner@"
     env:
-      # mise reads mise.ci.toml on top of mise.toml: the tools only a runner runs.
+      # mise also reads mise.ci.toml, on top of mise.toml, for the tools only a runner needs.
       MISE_ENV: ci
     steps:
       - name: checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
-          # kit policy reads every commit past the fork from the default branch.
+          # kit policy reads every commit since the branch forked from the default branch.
           fetch-depth: 0
 
       - name: mise-on-path
diff --git a/modules/claude/docs/README.md b/modules/claude/docs/README.md
index 6811111..33f4296 100644
--- a/modules/claude/docs/README.md
+++ b/modules/claude/docs/README.md
@@ -1,19 +1,26 @@
 # The claude module
 
-The adapter for Claude Code. Claude Code reads `AGENTS.md` only as a fallback: when no `CLAUDE.md`,
+Adapts the kit for Claude Code. Claude Code reads `AGENTS.md` only as a fallback: when no `CLAUDE.md`,
 `.claude/CLAUDE.md`, or `CLAUDE.local.md` is present in the working directory or above it, and where its
-configuration allows. A repository with a `CLAUDE.md` of its own would have `AGENTS.md` skipped. So the module
-places a region in `.claude/CLAUDE.md` holding `@../AGENTS.md`, opened by a `kit:generate` directive `kit
-generate` fills: Claude then reads what every other agent reads in every case, the rest of that file and a root
-`CLAUDE.md` are the repository's own, and `kit check` holds only the region. It also merges into
-`.claude/settings.json`, by key, leaving the repository's own entries:
+configuration allows. In a repository with its own `CLAUDE.md`, Claude Code would skip `AGENTS.md`.
 
-- `permissions.deny`: the spellings `.kit/1st.md` forbids an agent, `git rebase`, `git worktree add`,
-  `git checkout -b`, `git switch -c`, `git worktree remove`, `git branch -D`, `git checkout main`,
-  `git switch main`, `git reset --hard`, `git push --force`, and `git push -f`, which the kit's verbs and the
-  loop replace.
-- `hooks.PreToolUse`: on `Write`, `Edit`, and `MultiEdit`, `kit context --claude`, which puts the rules governing the
-  file before the agent, described in [docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md).
+So the module delivers a region in `.claude/CLAUDE.md` that contains `@../AGENTS.md`. The region starts at
+a `kit:generate` directive, and `kit generate` fills it. As a result:
 
-`.claude/rules/` is the repository's own, and `AGENTS.md` carries no `@` import of Claude's, since every harness
-reads it.
+- Claude Code reads what every other agent reads, in every case.
+- The rest of `.claude/CLAUDE.md`, and any root `CLAUDE.md`, belong to the repository.
+- `kit check` checks only the region.
+
+The module also merges two entries into `.claude/settings.json`, by key, and leaves the repository's own entries
+alone:
+
+- `permissions.deny`: the git commands that `.kit/1st.md` forbids an agent, because the kit's commands and the
+  workflow replace them. They are `git rebase`, `git worktree add`, `git checkout -b`, `git switch -c`,
+  `git worktree remove`, `git branch -D`, `git checkout main`, `git switch main`, `git reset --hard`,
+  `git push --force`, and `git push -f`.
+- `hooks.PreToolUse`: on `Write`, `Edit`, and `MultiEdit`, runs `kit context --claude`, which shows the agent the
+  rules that govern the file. It is described in
+  [docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md).
+
+`.claude/rules/` belongs to the repository. `AGENTS.md` contains no `@` import for Claude Code, because every
+harness reads `AGENTS.md`.
diff --git a/modules/claude/module.yml b/modules/claude/module.yml
index 7ae8a27..5821d0b 100644
--- a/modules/claude/module.yml
+++ b/modules/claude/module.yml
@@ -1,6 +1,6 @@
-# modules/claude/module.yml - the claude module: Claude Code's deny list and its hook into kit context
+# modules/claude/module.yml - the claude module: Claude Code's deny list, and a hook that runs kit context
 # ----------------------------------------------------------------------------------------------------------------------
-# docs/modules.md says what each key means.
+# see: docs/modules.md
 
 description: "Claude Code: the deny list of the spellings the rules forbid, and the hook that names a file's rules"
 depends:
diff --git a/modules/kit/docs/README.md b/modules/kit/docs/README.md
index 2ed0d81..9a61f2c 100644
--- a/modules/kit/docs/README.md
+++ b/modules/kit/docs/README.md
@@ -1,14 +1,17 @@
 # The kit module
 
-The core, active in every repository that takes the kit. It places:
+The core module. It is active in every repository that uses the kit. It delivers:
 
-- `.kit/1st.md`, the entry every agent reads, named by the repository's `AGENTS.md`.
-- `.kit/rules/<kind>.md`, one rule file per kind of file, each declaring in its frontmatter which paths and which
+- `.kit/1st.md`, the entry file every agent reads. The repository's `AGENTS.md` points to it.
+- `.kit/rules/<kind>.md`, one rule file per kind of file. Each rule file's frontmatter declares the paths and
   first lines it governs, and the linter `kit lint` runs over them.
-- A region in `AGENTS.md`, the sentence that sends every agent to `.kit/1st.md`, and a region in `.gitignore`,
-  the `/worktrees/` entry the loop needs; each opened by a `kit:generate` directive that `kit generate` fills
-  through `kit region`, and the rest of each file is the repository's.
+- A region in `AGENTS.md`: the sentence that sends every agent to `.kit/1st.md`.
+- A region in `.gitignore`: the `/worktrees/` entry the workflow needs.
 
-The rules are discovered through `kit context`, described in
-[docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md). Adding a kind is adding one rule
-file here and one row to the table in `1st.md`.
+Each region starts at a `kit:generate` directive, and `kit generate` fills it through `kit region`. The rest of
+`AGENTS.md` and `.gitignore` belongs to the repository.
+
+Agents and people find the rules through `kit context`, described in
+[docs/context.md](https://github.com/empowerite/kit/blob/main/docs/context.md).
+
+To add a kind of file, add one rule file here and one row to the table in `1st.md`.
diff --git a/modules/kit/files/repo/.kit/1st.md b/modules/kit/files/repo/.kit/1st.md
index 924ebe9..a55c780 100644
--- a/modules/kit/files/repo/.kit/1st.md
+++ b/modules/kit/files/repo/.kit/1st.md
@@ -1,81 +1,114 @@
 <!-- Delivered by kit, not edited by hand. A change is a new release, then kit update. -->
 # Read this first
 
-This file is the kit's entry. It binds every agent and every session in a repository that carries `.kit/`, and
-the repository's own rules in `AGENTS.md` bind beside it. Where the two differ, the repository's rule wins.
+This file is the kit's entry point. Every agent follows it in every session, in any repository that has a `.kit/`
+directory. The repository's own rules in `AGENTS.md` apply as well. Where the two differ, `AGENTS.md` wins.
 
 ## Integrity
 
-1. Report only what happened. Write "done", "passing", or "verified" only for what ran and held.
-2. A skip is a skip. A check not run, not implemented, or not implementable is reported as exactly that. It
-   clears no gate and earns no credit.
-3. A claim carries its evidence, or says it has none. Name the command that ran and what it printed.
+1. Report only what happened. Write "done", "passing", or "verified" only for something that ran and succeeded.
+2. Report a skip as a skip. A check that was not run, is not implemented, or cannot be implemented is reported as
+   exactly that. It passes no gate and earns no credit.
+3. Give the evidence for every claim, or say there is none. Name the command that ran and what it printed.
 4. Being wrong is recoverable. Misreporting is not.
-5. A rule lives in the repository, never in a session's memory. A convention learned or a correction given is
-   written, through the loop, into `AGENTS.md`, a module of the repository's own under `.kit/modules/`, or a kit
-   release, where every agent and every person reads it.
+5. Rules live in the repository, never in a session's memory. When you learn a convention or receive a correction,
+   write it down, through the workflow, in one of these places, where every agent and every person reads it:
+   - `AGENTS.md`
+   - a module of the repository's own under `.kit/modules/`
+   - a kit release
 
 ## The root checkout is the human's desk
 
-The checkout at the repository root is the human's. It is where they type, review, and leave work in progress.
-It usually has `main` checked out, and may have any branch no worktree holds. An agent never checks out, resets,
-rebases, or otherwise changes it in place. Work happens in a worktree under `worktrees/`, one per issue, and
-reaches `main` only through a merged pull request.
+The desk is the root checkout on the human's machine, on whatever branch it currently has. It belongs to the human.
+They type, review, and leave work in progress there. It usually has `main` checked out, and may have any branch that
+no worktree has checked out.
 
-## The loop
+An agent never checks out, resets, rebases, or otherwise changes the desk in place. An agent works in a worktree
+under `worktrees/`, one per issue. Work reaches `main` only through a merged pull request.
 
-1. An issue exists. A change without an issue has not started.
-2. `kit issue <N>` makes `worktrees/<N>-<slug>`, a branch linked to the issue under Development, and a draft
-   pull request. It never switches the checkout it is run from.
-3. Work happens in that worktree. Every commit is signed, and its subject is `#<N> <area>: <subject>`. `kit rebase`
-   brings the branch up to date with the default branch and pushes it.
-4. `gh pr ready` says the work is done. The pull request body is the report: what changed, what was checked
-   and how, and what was left out and why.
-5. A human merges. Nothing reaches `main` any other way, and nothing is called merged until the merge is
-   observed.
+## The workflow
 
-## Spellings an agent uses
+1. Start from an issue. A change without an issue has not started.
+2. `kit issue <N>` creates the following, and never switches the checkout you run it from:
+   - the worktree `worktrees/<N>-<slug>`
+   - a branch, linked to the issue under Development
+   - a draft pull request
+3. Work in that worktree. Sign every commit. Write each commit subject as `#<N> <area>: <subject>`. Run
+   `kit rebase` to bring the branch up to date with the default branch and push it.
+4. Run `gh pr ready` when the work is done. The pull request body is the report. It states:
+   - what changed
+   - what was checked, and how
+   - what was left out, and why
+5. A human merges. Nothing reaches `main` any other way. Do not call anything merged until you see the merge.
 
-Where the kit adds a rule to a git verb, the kit's spelling is the only one an agent uses. Each kit spelling
-carries the check its rule requires, and a harness with a deny list refuses the raw git spelling.
+## Kit commands instead of git commands
 
-- `kit rebase`, never `git rebase`. It refuses the root checkout and the default branch, and otherwise rebases the
-  worktree's branch onto the default branch at origin and pushes it.
+Some git commands have a kit replacement that adds the check its rule requires. An agent uses only the kit
+command. A harness with a deny list refuses the raw git command.
+
+- `kit rebase`, never `git rebase`. `kit rebase` refuses to run in the root checkout or on the default branch.
+  Otherwise it rebases the worktree's branch onto the default branch at origin and pushes it.
 - `kit issue`, never `git worktree add`, `git checkout -b`, or `git switch -c`.
 - `kit tidy`, never `git worktree remove` or `git branch -D`.
-- The desk is never switched or reset by an agent: `git checkout main`, `git switch main`, `git reset --hard`,
-  and `git push --force` are refused as well.
+- An agent never switches or resets the desk. `git checkout main`, `git switch main`, `git reset --hard`, and
+  `git push --force` are refused as well.
 
-The human at the desk is not bound by this; the root checkout is theirs.
+These limits do not apply to the human at the desk.
 
 ## Plans are prose
 
-A design, a spec, or a plan is the body of an issue, written in prose. It is never a committed file. When
-the design is written, the issue is the deliverable, and the loop above starts from it.
+Write a design, a spec, or a plan as prose in the body of an issue. Never commit it as a file. When the design is
+written, the issue is the deliverable, and the workflow above starts from it.
 
 ## The worker contract
 
-A worker is whoever implements one issue in the worktree that issue names.
+A worker is whoever implements one issue, in the worktree named for that issue.
 
-1. `cd` into the worktree named in the task and confirm `git rev-parse --abbrev-ref HEAD` prints a branch name
-   beginning `<N>-`.
-2. Do every command from there. Never touch the repository root checkout.
-3. Never run `kit issue`, make a branch, or make a worktree. Those were done before the handoff.
-4. Implement what the issue asks and nothing beside it.
+1. `cd` into the worktree named in the task. Confirm that `git rev-parse --abbrev-ref HEAD` prints a branch name
+   that begins with `<N>-`.
+2. Run every command from there. Never touch the root checkout.
+3. Never run `kit issue`, create a branch, or create a worktree. These were done before the handoff.
+4. Implement what the issue asks and nothing else.
 5. Push as you go.
-6. Run the repository's gate before calling anything done, and run it through the pinned toolchain.
-7. End with `gh pr ready` and the report in the pull request body.
-8. If the gate fails or the work is partial, leave the pull request a draft and say why.
+6. Before you call anything done, run the repository's gate (its own CI command, such as `just ci`) through
+   the pinned toolchain.
+7. Finish with `gh pr ready`, with the report in the pull request body.
+8. If the gate fails or the work is partial, leave the pull request as a draft and say why.
 9. Never merge.
-10. Report what ran and what it printed, nothing more.
+10. Report what ran and what it printed. Nothing more.
 
 ## Rules by file type
 
-Each file kind has a rule file under `.kit/rules/`, and each rule file's header names what it governs: `paths:`,
-globs on the repository path, and `content:`, patterns on the first line; `lint:` names the linter `kit lint`
-runs over the paths it governs. Before you create or change a file, run
-`kit context <path>`. It names the rules that govern the file and records that you asked. Read what it names. No
-harness holds a copy of a rule; this call is how every harness, and every person, finds it.
+Each kind of file has a rule file under `.kit/rules/`. The frontmatter at the top of a rule file has these keys:
+
+| Key | Contains |
+| --- | --- |
+| `paths:` | Globs matched against a file's path from the repository root. The rule governs a file that matches. |
+| `content:` | Patterns matched against a file's first line. The rule governs a file that matches. |
+| `lint:` | The linter that `kit lint` runs over the files the rule governs. |
+| `templates:` | The shapes a file of this kind can take. The templates are under `.kit/templates/`. |
+
+Before you change a file:
+
+1. Run `kit context <path>`. It prints the rules that govern the file, and records that you asked.
+2. Read every rule it prints.
+
+No harness keeps a copy of the rules. `kit context` is how every harness, and every person, finds them.
+
+Create a new file with `kit new file <path>`, giving the path from the repository root. Never write a new file
+from nothing. `kit new file`:
+
+- writes the file from its rule's template
+- fills the template's holes that the path supplies
+- refuses a hole you left empty, and names the flag that fills it, such as `--purpose=<…>` or `--title=<…>`
+- prints the rules to read before you write the rest of the file
+
+Two flags choose the template:
+
+- `--variant=<…>` picks another of the rule's shapes, such as a sourced bash module.
+- `--rule=<…>` names the rule for a path with no extension.
+
+`kit lint` fails any file, including one written by hand, whose shape matches none of its rule's templates.
 
 | Kind | Rule |
 | --- | --- |
@@ -87,35 +120,56 @@ harness holds a copy of a rule; this call is how every harness, and every person
 | JSON | [rules/json.md](rules/json.md) |
 | Ignore lists | [rules/gitignore.md](rules/gitignore.md) |
 
-## What the kit carries
-
-The repository carries the text: this file, the rules under `.kit/rules/`, and `.kit/manifest`, which records the
-release version, the active modules, and a checksum per delivered file. The release, where it is installed,
-carries the machinery, reached through the `kit` command on `PATH`: the loop's commands, `kit issue`, `kit rebase`,
-`kit tidy`, `kit status`, `kit context`, and `kit lint`, spelled that way and no other. Everything the release
-delivers is a module, and a repository activates the modules it takes: `kit install ci-github lefthook claude`, or
-`kit module add claude` later, and `kit module remove` to take one back out; a module of the repository's own
-lives under `.kit/modules/` and is taken the same way. A `.json` destination, other than a schema, is merged by
-key, the kit owning only the entries it writes; a region inside a file the repository owns is opened by a
-directive, `kit:generate`, and made by the command it names, through `kit generate`; everything else is copied
-as it is.
-
-- `kit`: this file and the rules; the sentence in `AGENTS.md` that points here and the `/worktrees/` entry in
-  `.gitignore`, each a region `kit region` fills inside a file the repository owns. Any file may carry a directive
-  of the repository's own, `kit:generate` naming any command, and `kit check` holds every region to its command.
-- `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` over the staged paths. A repository's
-  `lefthook.yml` takes it with `extends` and adds commands of its own. `kit lint` itself needs no hook manager:
-  it runs each rule's linter over the paths the rule governs.
-- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job that installs the gate's tools with
-  `kit toolchain install` and runs `kit ci`: the repository's gate, `kit check`, the refusal of a change not
-  linked to an open issue, and `kit policy`, the refusal of a branch, commit subject, or title off the
-  repository's policy. `kit ci` runs the same four anywhere.
-- `policy-opa`: `.kit/policy/kit.rego`, the naming policy in Rego, so `kit policy` runs on Open Policy Agent and a
-  rule can say what a pattern cannot.
-- `claude`: for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`: a region in
-  `.claude/CLAUDE.md` importing `AGENTS.md`, so it is read in every case; the deny list above merged into
-  `.claude/settings.json`; and a hook that runs `kit context` before every write so the rules are named to the agent
-  without being asked for.
-
-`kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a
-new release and running `kit update`, never by editing them in place.
+## What the kit delivers
+
+The repository contains the text:
+
+- this file
+- the rules under `.kit/rules/`
+- `.kit/manifest`, which records the release version, the active modules, and a checksum for each delivered file
+
+The installed release contains the code. You run it through the `kit` command on `PATH`. The workflow commands
+are `kit issue`, `kit rebase`, `kit tidy`, `kit status`, `kit context`, `kit new file`, and `kit lint`. Run them
+exactly as written here, and in no other way.
+
+Everything the release delivers belongs to a module. A repository activates the modules it wants:
+
+- `kit install ci-github lefthook claude` activates modules when the kit is installed.
+- `kit module add claude` activates a module later.
+- `kit module remove` deactivates a module.
+
+A module of the repository's own lives under `.kit/modules/` and is activated the same way.
+
+How a delivered file is placed depends on its destination:
+
+- A `.json` file, other than a schema, is merged by key. The kit owns only the entries it writes.
+- A region inside a file the repository owns starts at a `kit:generate` directive. `kit generate` fills the region
+  by running the command the directive names.
+- Every other file is copied as it is.
+
+The modules:
+
+- `kit`: this file, the rules, and their templates, and two regions that `kit region` fills:
+  - the sentence in the repository's `AGENTS.md` that points to this file
+  - the `/worktrees/` entry in the repository's `.gitignore`
+- `lefthook`: `.kit/lefthook.yml`, a pre-commit hook that runs `kit lint` and `kit generate --check` over the
+  staged paths. A repository's `lefthook.yml` includes it with `extends` and adds its own commands. `kit lint`
+  does not need a hook manager: it runs each rule's linter over the paths the rule governs.
+- `ci-github`: `.github/workflows/kit-ci.yml`, one GitHub Actions job. The job installs the gate's tools with
+  `kit toolchain install`, then runs `kit ci`. `kit ci` runs four checks, and runs the same four on any machine:
+  - the repository's gate
+  - `kit check`
+  - `kit linked`, which refuses a change that is not linked to an open issue
+  - `kit policy`, which refuses a branch name, commit subject, or title that breaks the repository's policy
+- `policy-opa`: `.kit/policy/kit.rego`, the naming policy in Rego. With it, `kit policy` runs on Open Policy
+  Agent, and a rule can express what a pattern cannot.
+- `claude`: support for Claude Code, which reads `AGENTS.md` only when it finds no `CLAUDE.md`. It delivers:
+  - a region in `.claude/CLAUDE.md` that imports `AGENTS.md`, so Claude Code reads `AGENTS.md` in every case
+  - the deny list above, merged into `.claude/settings.json`
+  - a hook that runs `kit context` before every write, so the agent sees the rules without asking
+
+Any file may also contain a `kit:generate` directive of the repository's own, naming any command. `kit check` fails
+when any region differs from what its command produces.
+
+`kit check` fails when a delivered file differs from the pinned release. Change the kit's files by pinning a new
+release and running `kit update`, never by editing them in place.
diff --git a/modules/kit/files/repo/.kit/rules/bash.md b/modules/kit/files/repo/.kit/rules/bash.md
index 7cdc937..a45543a 100644
--- a/modules/kit/files/repo/.kit/rules/bash.md
+++ b/modules/kit/files/repo/.kit/rules/bash.md
@@ -6,51 +6,61 @@ paths:
 content:
   - "^#!.*/(env +)?(ba)?sh( |$)"
 lint: shellcheck --shell=bash --external-sources
+templates:
+  - variant: script
+    executable: true
+  - variant: module
 ---
 # Bash
 
-Applies to `*.sh` and `*.bash`, recipe bodies under `#!/usr/bin/env bash`, and `run:` blocks in
-workflows.
+Applies to:
+
+- `*.sh` and `*.bash` files
+- recipe bodies under `#!/usr/bin/env bash`
+- `run:` blocks in workflows
 
 ## Shape
 
-1. An executed script opens with `#!/usr/bin/env bash`, a `# <file> - <purpose>` banner under 120 columns, a
-   rule of dashes to column 120, a blank line, and an optional comment paragraph, then
-   `set -o errexit -o nounset -o pipefail`.
-2. A sourced module opens with `# shellcheck shell=bash` and the same banner, and sets no shell options: they
-   would change the caller's.
-3. The file closes with the same rule of dashes.
+1. An executed script opens with these lines, in order:
+   1. `#!/usr/bin/env bash`
+   2. a `# <file> - <purpose>` banner under 120 columns
+   3. a line of dashes to column 120
+   4. a blank line
+   5. an optional comment paragraph
+   6. `set -o errexit -o nounset -o pipefail`
+2. A sourced module opens with `# shellcheck shell=bash`, then the same banner. It sets no shell options, because
+   they would change the caller's options.
+3. The file ends with the same line of dashes.
 
 ## Style
 
 1. `then`, `do`, and `else` go on their own line, never after a semicolon.
 2. Spell `set` options out: `set -o errexit`, never `set -e`.
-3. Spell a tool's options out where every platform accepts the long form: `--raw-output`, `--field`,
-   `--quiet`. Where BSD and GNU differ, use the form both accept, which is the short one: `sed -n`, `head -n 1`,
-   `mkdir -p`, `rm -f`, `cut -d`, `cp -R`, `find -type`, `read -r`, and `git -C`.
+3. Use a tool's long options where every platform accepts them: `--raw-output`, `--field`, `--quiet`. Where BSD
+   and GNU differ, use the short form, which both accept: `sed -n`, `head -n 1`, `mkdir -p`, `rm -f`, `cut -d`,
+   `cp -R`, `find -type`, `read -r`, and `git -C`.
 4. Arithmetic uses `(( ))`. String and file tests use `[[ ]]`.
 5. Brace every variable longer than one character: `${name}`. `$1`, `$@`, `$?`, and `$#` stay bare.
-6. A `case` label carries both parentheses: `(vanilla)`. The last group has no `;;`.
+6. A `case` label has both parentheses: `(vanilla)`. The last group has no `;;`.
 7. Quote every expansion outside `[[ ]]` and `(( ))`.
-8. A function in a sourced module is named `<module>:<kebab-name>`, the module being the file's basename. The
-   loader, `1st.sh`, is the exception: its verbs stay bare, `use`, `info`, `step`, `ok`, `section`, `warn`,
-   `error`, and `summary`, and its helpers are the `out:` and `guard:` families.
-9. A function private to one executed script is bare kebab-case.
+8. Name a function in a sourced module `<module>:<kebab-name>`, where `<module>` is the file's basename. The
+   loader, `1st.sh`, is the exception. Its verbs have bare names (`use`, `info`, `step`, `ok`, `section`, `warn`,
+   `error`, and `summary`), and its helpers use the `out:` and `guard:` prefixes.
+9. Name a function private to one executed script in bare kebab-case.
 
 ## Behavior
 
-1. An error message is one line, names the remedy where there is one, and is the same wherever the same
-   condition arises.
-2. A helper that refuses returns non-zero and lets the caller end the script. It does not `exit` itself.
+1. An error message is one line. It names the remedy, if any. The same condition gives the same message everywhere.
+2. A helper that refuses returns non-zero and lets the caller end the script. It does not call `exit` itself.
 3. A secret never appears in `argv`. Pipe it: `printf '%s' "${secret}" | gh secret set NAME`.
-4. Diagnostics go to stderr. Stdout carries data a caller can pipe.
-5. A command that mutates a remote, a branch, or a worktree is guarded by a check that names what it is about
-   to do, and a `--dry-run` where the mutation removes work, as a sweep of worktrees or branches does.
-6. The default branch is read from `origin/HEAD`, with `main` as the fallback, never hard-coded.
-7. shellcheck passes with no directive, or the directive carries the reason on the same line.
+4. Diagnostics go to stderr. Stdout is for data a caller can pipe.
+5. A command that changes a remote, a branch, or a worktree is guarded by a check that names what it is about to
+   do. If the change removes work, as a sweep of worktrees or branches does, the command also has `--dry-run`.
+6. Read the default branch from `origin/HEAD`, with `main` as the fallback. Never hard-code it.
+7. shellcheck passes with no directive. Where a directive is needed, its reason is on the same line.
 
 ## Comments
 
-1. A comment states what the code does and the non-obvious why. It carries no history and defends no obvious
-   choice.
+1. A comment states what the code does and any non-obvious reason for it. It contains no history and does not
+   defend an obvious choice.
 2. A pointer is `# see: <ref>`, on its own line after the comment it supports.
diff --git a/modules/kit/files/repo/.kit/rules/gitignore.md b/modules/kit/files/repo/.kit/rules/gitignore.md
index 2712da0..505efbe 100644
--- a/modules/kit/files/repo/.kit/rules/gitignore.md
+++ b/modules/kit/files/repo/.kit/rules/gitignore.md
@@ -3,6 +3,10 @@
 paths:
   - ".gitignore"
   - "**/.gitignore"
+templates:
+  - variant: file
+  - variant: region
+    path: .gitignore
 ---
 # Ignore lists
 
@@ -10,22 +14,21 @@ Applies to `.gitignore` at any depth.
 
 ## Shape
 
-1. A file the repository writes opens with `# .gitignore - untracked files and folders`, a rule of dashes to
-   column 120, and a blank line. One the kit made of its region alone is the kit's until the repository adds
-   to it.
-2. Entries are grouped. Each group opens with `# <what produces it>; see: <ref>` and is followed by a blank
-   line.
-3. The file closes with a rule of dashes.
+1. A file the repository writes opens with `# .gitignore - untracked files and folders`, a line of dashes to
+   column 120, and a blank line. A file the kit created that contains only the kit's region belongs to the kit
+   until the repository adds to it.
+2. Group the entries. Each group opens with `# <what produces it>; see: <ref>` and ends with a blank line.
+3. The file ends with a line of dashes.
 
 ## Entries
 
 1. Every entry names a file the repository itself produces. Editor and operating-system files belong in the
    user's global ignore list, not here.
-2. An entry lives in the deepest directory where it applies. The root carries only patterns that span the
-   repository.
+2. Put an entry in the deepest directory where it applies. The root `.gitignore` contains only patterns that apply
+   across the whole repository.
 3. A pattern that names a directory ends with `/`. A pattern anchored to the file's directory starts with `/`.
-4. Ignore `/worktrees/` at the root: it is where the loop checks out a branch per issue.
+4. Ignore `/worktrees/` at the root. The workflow checks out a branch for each issue there.
 
-## Adding one
+## Adding an entry
 
 Ask what produces the file. If nothing in the repository does, do not add it.
diff --git a/modules/kit/files/repo/.kit/rules/json.md b/modules/kit/files/repo/.kit/rules/json.md
index f89871b..c6430da 100644
--- a/modules/kit/files/repo/.kit/rules/json.md
+++ b/modules/kit/files/repo/.kit/rules/json.md
@@ -10,18 +10,18 @@ Applies to `*.json` and `*.jsonc`.
 
 ## Shape
 
-1. Two-space indentation. Keys in a stable order: the order the consuming tool documents, else alphabetical.
-2. One trailing newline. No trailing commas in `.json`.
-3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where
-   it reads plain JSON, the reason for a setting lives in the document that describes the file.
+1. Indent with two spaces. Keep keys in a stable order: as the consuming tool documents, else alphabetical.
+2. End with one trailing newline. No trailing commas in `.json`.
+3. Where the consuming tool reads JSONC, name the file `.jsonc` and comment every non-obvious setting. Where it
+   reads plain JSON, explain a setting in the document that describes the file.
 
 ## Settings
 
-1. A disabled linter rule carries a comment naming the rule and the convention it would fight.
-2. Do not edit an entry the kit wrote in a merged settings file; change it through a release and `kit update`.
-   Everything else in the file is the repository's to edit.
+1. A disabled linter rule has a comment that names the rule and the convention it conflicts with.
+2. In a merged settings file, do not edit an entry the kit wrote. Change it through a release and `kit update`.
+   The repository may edit everything else in the file.
 
 ## Comments
 
-1. A comment states what the entry does and the non-obvious why. It carries no history.
+1. A comment states what the entry does and any non-obvious reason for it. It contains no history.
 2. A pointer is `// see: <ref>`.
diff --git a/modules/kit/files/repo/.kit/rules/just.md b/modules/kit/files/repo/.kit/rules/just.md
index d15175d..0a74945 100644
--- a/modules/kit/files/repo/.kit/rules/just.md
+++ b/modules/kit/files/repo/.kit/rules/just.md
@@ -6,22 +6,30 @@ paths:
   - "**/*.just"
 content:
   - "^#!.*/(env +)?just( |$)"
+templates:
+  - variant: root
+    path: justfile
+  - variant: module
 ---
 # Just
 
-Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the bash rule applies to it as well.
+Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, so the bash rule also applies to it.
 
 ## Shape
 
-1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a rule of dashes to column 120,
-   and a description of what the file is and who imports it. The root carries the `#!/usr/bin/env just
-   --justfile` shebang above that; a module does not.
-2. The settings block follows: `set dotenv-load := true`, `set fallback := true` in a module (never in the
-   root, which has no parent), `set positional-arguments := true`, and `set script-interpreter := ['bash']`,
-   the interpreter named bare so the pinned bash wins. `set export := true` comes after the default-and-help
-   pair, so that pair reads the same in every justfile.
-3. The root puts the mise-pinned toolchain first on `PATH` once, at parse time, from `mise bin-paths`, so every
-   recipe calls its tools bare and the pinned tool wins over any other copy, on a desk and on a runner alike:
+1. Every justfile opens with `# <file> - see: https://just.systems/man/en/`, a line of dashes to column 120,
+   and a description of what the file is and who imports it. The root justfile has the
+   `#!/usr/bin/env just --justfile` shebang above those lines. A module does not.
+2. The settings block comes next:
+   - `set dotenv-load := true`
+   - `set fallback := true`, only in a module, never in the root, because the root has no parent
+   - `set positional-arguments := true`
+   - `set script-interpreter := ['bash']`, with the interpreter named bare so the pinned bash is used
+
+   `set export := true` comes after the default-and-help pair, so that the pair is identical in every justfile.
+3. The root justfile puts the mise-pinned tools first on `PATH`, once, at parse time, from `mise bin-paths`.
+   Every recipe then calls its tools by bare name, and the pinned tool runs instead of any other copy, both
+   locally and on a CI runner:
 
    ````just
    export PATH := ```
@@ -32,7 +40,7 @@ Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the ba
      ``` + env('PATH')
    ````
 
-4. Every justfile carries the default-and-help pair, with the file's own path in an exported variable:
+4. Every justfile has the default-and-help pair, with the file's own path in an exported variable:
 
    ```just
    # This file's own path, assigned at parse time so the body below needs no interpolation.
@@ -47,28 +55,28 @@ Applies to `justfile` and `*.just`. A `[script]` recipe body is bash, and the ba
      just --justfile "${<name>_justfile}" --list
    ```
 
-5. A module the root takes with `mod <name> "<path>"` carries `[no-cd]` on every recipe, so its body runs from
-   the invoking root rather than the module's directory.
-6. The file closes with a rule of dashes.
+5. In a module the root imports with `mod <name> "<path>"`, every recipe has `[no-cd]`. The recipe body then
+   runs from the invoking root, not from the module's directory.
+6. The file ends with a line of dashes.
 
 ## Recipes
 
-1. Every recipe but the default-and-help pair carries `[doc("<emoji> <short, action-first description>")]`.
+1. Every recipe except the default-and-help pair has `[doc("<emoji> <short, action-first description>")]`.
    Related recipes share an emoji.
-2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. It answers what the
-   recipe does, when to run it, and what it produces.
-3. A non-trivial body is a `[script]` recipe, never a shebang recipe, with `set -o errexit -o nounset -o pipefail`
-   as its first line. A tool in it is called bare, never through `mise exec`.
-4. A body says what runs. Logic longer than a dozen lines lives in a bash script the body calls.
-5. No `{{...}}` interpolation anywhere, in a body or a comment. A value just computes reaches a body as an exported
-   variable, `export <name> := <expression>`, and `set export := true` exports every parameter, so a body reads
-   `${name}` and nothing else.
-6. Two-space indentation inside a body. Never a tab.
-7. Recipe and module names are spelled out, never abbreviated. A second `mod` at the same target is an alias.
+2. A comment block precedes every recipe: a paragraph of intent, then the usage lines. The comment states what
+   the recipe does, when to run it, and what it produces.
+3. Write a non-trivial body as a `[script]` recipe, never a shebang recipe. Its first line is
+   `set -o errexit -o nounset -o pipefail`. Call a tool in it by bare name, never through `mise exec`.
+4. A body shows what runs. Move logic longer than a dozen lines into a bash script that the body calls.
+5. Use no `{{...}}` interpolation anywhere, in a body or a comment. Pass a value that `just` computes to a body as
+   an exported variable: `export <name> := <expression>`. `set export := true` exports every parameter. A body
+   refers to values only as `${name}`.
+6. Indent a body with two spaces. Never use a tab.
+7. Spell out recipe and module names. Never abbreviate them. A second `mod` at the same target is an alias.
 8. Comments wrap at 118 columns. Bodies do not wrap.
 
 ## Invocation
 
-1. The idiom is the space form, `just tools check`, never `just tools/check` and never `tools::check` outside a
-   dependency list.
+1. Call a module's recipe with spaces: `just tools check`. Never write `just tools/check`, and never write
+   `tools::check` outside a dependency list.
 2. A recipe that mutates a remote or a worktree names what it is about to do before doing it.
diff --git a/modules/kit/files/repo/.kit/rules/markdown.md b/modules/kit/files/repo/.kit/rules/markdown.md
index 4feb54c..aa3f6a3 100644
--- a/modules/kit/files/repo/.kit/rules/markdown.md
+++ b/modules/kit/files/repo/.kit/rules/markdown.md
@@ -3,6 +3,12 @@
 paths:
   - "**/*.md"
 lint: markdownlint-cli2 --config .kit/markdownlint.jsonc
+templates:
+  - variant: agents
+    path: AGENTS.md
+  - variant: document
+  - variant: notice
+  - variant: frontmatter
 ---
 # Markdown
 
@@ -10,46 +16,45 @@ Applies to `*.md`.
 
 ## Prose
 
-1. Write plain declarative sentences with the thing under discussion as the subject.
+1. Write plain declarative sentences, with the thing under discussion as the subject.
 2. Describe the current state. Leave the history to git: no "previously", "used to", "replaced", or "ported from".
-3. Use a list where the content is a list, and for a procedure or a loop, so it scans. Use a table where the
-   content has columns.
+3. Use a list for a list, a procedure, or a workflow, so it scans. Use a table where the content has columns.
 4. Do not bold words for emphasis. Do not open a list item with a bolded term and a colon.
-5. Do not close a paragraph on a slogan, and do not restate what the code or config already says.
+5. Do not end a paragraph on a slogan. Do not restate what the code or config already states.
 6. Use the serial comma in every list of three or more.
 7. Expand an uncommon acronym the first time it appears.
 8. A pointer is `see: <ref>`, where `<ref>` is a URL, a repository-relative path, or `issue #N`. Put it inline
-   when it keeps the sentence on one line, otherwise on its own line at the end of the paragraph.
+   when it keeps the sentence on one line. Otherwise put it on its own line at the end of the paragraph.
 
 ## Snippets
 
-1. A value the reader supplies is a shell variable the prose names, `"${signing_key}"`, never an angle-bracket
-   placeholder, so the block pastes after one export.
+1. Write a value the reader supplies as a shell variable that the prose names, such as `"${signing_key}"`, never
+   as an angle-bracket placeholder. The block then works when pasted after one `export`.
 2. Where a reader may lack a prerequisite, link the page that creates it beside the command that uses it.
 
 ## Layout
 
-1. Wrap prose at 118 columns, 120 being the ceiling. Inside a list item, pull the right margin in by 4 columns
-   per nesting level, to a limit of 12.
-2. Balance the wrap: no line, in particular the last, reads as a stub.
-3. Do not wrap fenced code, tables, HTML comments, or a line whose only content is a link.
-4. Keep a list tight or loose as it was written. Reflow never flips one to the other.
-5. Headings are ATX (`#`). One `#` heading per file, at the top; `AGENTS.md` is the exception, opening with the
-   sentence a harness reads first.
-6. Fenced code blocks declare a language and have a blank line on each side.
+1. Wrap prose at 118 columns, with 120 as the ceiling. Inside a list item, pull the right margin in by 4
+   columns per nesting level, to a limit of 12.
+2. Balance the wrap: no line, especially the last, is a short stub.
+3. Do not wrap fenced code, tables, HTML comments, or a line that contains only a link.
+4. Keep a list tight or loose as it was written. Reflowing never changes one into the other.
+5. Use ATX headings (`#`). Use one `#` heading per file, at the top. `AGENTS.md` is the exception: it opens with
+   the sentence a harness reads first.
+6. A fenced code block declares a language and has a blank line before and after it.
 7. Table rows use ` | ` with spaces around each pipe, including the delimiter row.
 
 ## Links
 
 1. Use inline links with descriptive text, never a bare URL in angle brackets.
-2. Use the same anchor text every time the same URL appears in a file.
-3. When a label and the link text would say the same thing, make the label the link.
-4. A relative link resolves from the file that carries it, and it resolves.
+2. Use the same link text every time the same URL appears in a file.
+3. When a label and the link text would be the same, make the label the link.
+4. A relative link resolves from the file that contains it, and it must resolve.
 
 ## Files
 
-1. Name an index file `1st.md`. It lists its siblings and says what each is for.
-2. A file says what its subject is in its first paragraph, before how to use it.
-3. A README has no Status section and no paragraph on what the repository will do or does not yet do. It says
-   what the repository is.
-4. A delivered file names no repository as the source of a rule.
+1. Name an index file `1st.md`. It lists its siblings and states what each is for.
+2. The first paragraph of a file states what its subject is, before explaining how to use it.
+3. A README states what the repository is. It has no Status section and no paragraph on what the repository
+   will do or does not yet do.
+4. A delivered file does not name any repository as the source of a rule.
diff --git a/modules/kit/files/repo/.kit/rules/workflows.md b/modules/kit/files/repo/.kit/rules/workflows.md
index 4d02c2b..3a9400b 100644
--- a/modules/kit/files/repo/.kit/rules/workflows.md
+++ b/modules/kit/files/repo/.kit/rules/workflows.md
@@ -4,29 +4,31 @@ paths:
   - ".github/workflows/*.yml"
   - ".github/workflows/*.yaml"
 lint: actionlint
+templates:
+  - variant: workflow
 ---
 # Workflows
 
-Applies to GitHub Actions workflows, under `.github/workflows/`. The YAML rule applies to them as well.
+Applies to GitHub Actions workflows under `.github/workflows/`. The YAML rule also applies to them.
 
 ## Shape
 
 1. The file opens with a comment: what the workflow verifies or produces, when it runs, and the one thing a
    reader would not guess from the keys.
 2. Keys are in the order GitHub documents them: `name`, `on`, `permissions`, `jobs`.
-3. One job per scope, one step per policy. A job's key is the check's name a ruleset requires, so renaming it
-   breaks the requirement.
-4. `permissions` is declared at the top and names the least the jobs need.
+3. Use one job per scope and one step per policy. A job's key is the check name a ruleset requires, so renaming
+   the job breaks the requirement.
+4. Declare `permissions` at the top, granting the least the jobs need.
 
 ## Steps
 
-1. Every `uses:` pins a full commit SHA with the version as a trailing comment: `@<sha>  # v1.2.3`.
-2. A step has a `name` that is the policy it enforces, in kebab-case.
+1. Every `uses:` pins a full commit SHA, with the version as a trailing comment: `@<sha>  # v1.2.3`.
+2. Every step has a `name`: the policy it enforces, in kebab-case.
 3. A `run:` block is bash and follows the bash rule: `set -o errexit -o nounset -o pipefail` first.
-4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. A refusal a reader will act on
-   also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
-5. A step whose verdict a reader looks for writes one `✅` line to the summary.
-6. A later step that must run after an earlier refusal carries `if: ${{ !cancelled() }}`.
-7. A tool is on `PATH` because the repository pins it and a step installs it, never by `curl` in a step. The one
-   exception is the kit itself, which the delivered job fetches from the release `.kit/manifest` names, since
-   nothing else can put it there first.
+4. A refusal prints `::error::<message>` naming the remedy, and returns non-zero. If a reader will act on the
+   refusal, it also writes `### ❌ <Message>` and the remedy to `${GITHUB_STEP_SUMMARY}`.
+5. A step whose result a reader looks for writes one `✅` line to the summary.
+6. A later step that must run after an earlier refusal has `if: ${{ !cancelled() }}`.
+7. A tool gets on `PATH` because the repository pins it and a step installs it, never through `curl` in a step.
+   The one exception is the kit itself. The delivered job downloads the release that `.kit/manifest` names,
+   because nothing else can install the kit first.
diff --git a/modules/kit/files/repo/.kit/rules/yaml.md b/modules/kit/files/repo/.kit/rules/yaml.md
index 222fa95..01f2215 100644
--- a/modules/kit/files/repo/.kit/rules/yaml.md
+++ b/modules/kit/files/repo/.kit/rules/yaml.md
@@ -3,19 +3,20 @@
 paths:
   - "**/*.yml"
   - "**/*.yaml"
+templates:
+  - variant: document
 ---
 # YAML
 
-Applies to `*.yml` and `*.yaml`. A GitHub Actions workflow follows the workflows rule as well.
+Applies to `*.yml` and `*.yaml`. A GitHub Actions workflow also follows the workflows rule.
 
 ## Shape
 
-1. The file opens with a comment: what the file configures and the one thing a reader would not guess from the
-   keys.
-2. Two-space indentation. No tabs. No trailing whitespace.
-3. A scalar that holds a colon followed by a space, or opens with a reserved character, is quoted.
+1. The file opens with a comment: what it configures, and the one thing a reader would not guess from the keys.
+2. Indent with two spaces. No tabs. No trailing whitespace.
+3. Quote a scalar that contains a colon followed by a space, or that starts with a reserved character.
 
 ## Comments
 
-1. A comment states the non-obvious why. It carries no history.
+1. A comment states the non-obvious reason. It contains no history.
 2. A pointer is `# see: <ref>`.
diff --git a/modules/kit/files/repo/.kit/settings.schema.json b/modules/kit/files/repo/.kit/settings.schema.json
index b4bd794..906a759 100644
--- a/modules/kit/files/repo/.kit/settings.schema.json
+++ b/modules/kit/files/repo/.kit/settings.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/empowerite/kit/.kit/settings.schema.json",
   "title": ".kit/settings.yml",
-  "description": "The repository's choices, read by the kit and never written by it. Delivered by kit, not edited by hand; https://github.com/empowerite/kit/blob/main/docs/modules.md says what each key means. An editor validates the file against it through a modeline: # yaml-language-server: $schema=settings.schema.json",
+  "description": "The repository's settings. The kit reads this file and never writes it. This schema is delivered by kit, not edited by hand. Each key is described in https://github.com/empowerite/kit/blob/main/docs/modules.md. To have an editor validate the file against this schema, add the modeline: # yaml-language-server: $schema=settings.schema.json",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -12,16 +12,16 @@
         "github",
         "gitlab"
       ],
-      "description": "The provider the loop's verbs use: github or gitlab. Detected from origin's host, github.com or gitlab.com, when absent; a self-hosted forge is named here."
+      "description": "The forge (the service that hosts the repository) the workflow commands use: github or gitlab. When absent, it is detected from origin's host, github.com or gitlab.com. A self-hosted forge must be set here."
     },
     "gate": {
       "type": "string",
       "minLength": 1,
-      "description": "What kit gate runs. A justfile ci recipe, a Makefile ci target, or a package.json ci script is detected when absent."
+      "description": "The command kit gate runs. When absent, kit gate detects a root justfile ci recipe, a Makefile ci target, or a package.json ci script."
     },
     "require_signing": {
       "type": "boolean",
-      "description": "true makes kit issue refuse a desk without a signing key."
+      "description": "When true, kit issue fails before writing anything if git has no signing key configured."
     },
     "answers": {
       "type": "object",
@@ -29,13 +29,13 @@
       "patternProperties": {
         "^[a-z_]+$": {
           "type": "string",
-          "description": "The value a module's template takes for this key, written @key@ in the template."
+          "description": "The value a module's templates use for this key, written @key@ in a template."
         }
       }
     },
     "trackers": {
       "type": "array",
-      "description": "The trackers whose issues the loop takes besides the forge's own, which answers # unless a record claims it. A reference names its tracker by its prefix: #7, AB#4521.",
+      "description": "The issue trackers the workflow uses in addition to the forge's own issues. The forge's tracker handles the # prefix unless an entry here claims it. A reference names its tracker by its prefix: #7, AB#4521.",
       "items": {
         "type": "object",
         "required": [
@@ -47,7 +47,7 @@
           "prefix": {
             "type": "string",
             "pattern": "^[A-Za-z]*#?$",
-            "description": "What a reference to this tracker opens with, before the number: AB# for Azure DevOps work items."
+            "description": "The text a reference to this tracker starts with, before the number: AB# for Azure DevOps work items."
           },
           "provider": {
             "type": "string",
@@ -55,7 +55,7 @@
               "forge",
               "ado"
             ],
-            "description": "Which tracker answers: forge for the forge's own issues, ado for Azure DevOps work items."
+            "description": "The tracker that handles the prefix: forge for the forge's own issues, ado for Azure DevOps work items."
           },
           "organization": {
             "type": "string",
@@ -67,14 +67,14 @@
           },
           "type": {
             "type": "string",
-            "description": "ado: the type of a new work item, Task when absent."
+            "description": "ado: the type of a new work item. Default: Task."
           }
         }
       }
     },
     "toolchains": {
       "type": "array",
-      "description": "The toolchains that put the gate's tools on PATH, in order. Detected from mise.toml, Brewfile, and toolchain.Dockerfile when absent.",
+      "description": "The toolchains that put the gate's tools on PATH, in order. When absent, they are detected from mise.toml, Brewfile, and toolchain.Dockerfile.",
       "items": {
         "type": "object",
         "required": [
@@ -89,15 +89,15 @@
               "brew",
               "docker"
             ],
-            "description": "Which tool manager answers."
+            "description": "The tool manager: mise, brew, or docker."
           },
           "file": {
             "type": "string",
-            "description": "brew and docker: the file it reads, Brewfile or toolchain.Dockerfile by default."
+            "description": "brew and docker: the file the tool manager reads. Default: Brewfile or toolchain.Dockerfile."
           },
           "image": {
             "type": "string",
-            "description": "docker: the built image's name, kit-toolchain by default."
+            "description": "docker: the name of the built image. Default: kit-toolchain."
           }
         }
       }
@@ -105,19 +105,19 @@
     "policy": {
       "type": "object",
       "additionalProperties": false,
-      "description": "The patterns the loop's names must match, extended regular expressions in the subset RE2 shares. A subject absent takes the kit's default; an empty pattern turns that rule off.",
+      "description": "The patterns that the branch name, commit subjects, and pull request title must match. Each is an extended regular expression, limited to the subset RE2 also supports. An absent key uses the kit's default. An empty pattern turns that rule off.",
       "properties": {
         "branch": {
           "type": "string",
-          "description": "The branch's name. Default: ^[a-z0-9]+-[a-z0-9][a-z0-9-]*$, as kit issue makes it."
+          "description": "The pattern for the branch name. Default: ^[a-z0-9]+-[a-z0-9][a-z0-9-]*$, the shape kit issue gives a branch."
         },
         "commit_subject": {
           "type": "string",
-          "description": "Every commit's subject past the fork. Default: ^([A-Z]+)?#[0-9]+ [^ ], opening with its issue's reference."
+          "description": "The pattern for the subject of every commit since the branch forked. Default: ^([A-Z]+)?#[0-9]+ [^ ], a subject that starts with its issue's reference."
         },
         "change_title": {
           "type": "string",
-          "description": "The open change's title. Default: ^[^[:cntrl:]]{1,120}$."
+          "description": "The pattern for the open pull request's title. Default: ^[^[:cntrl:]]{1,120}$."
         }
       }
     },
@@ -127,7 +127,7 @@
         "patterns",
         "opa"
       ],
-      "description": "Which engine decides: patterns, matched in bash, or opa, over the Rego under .kit/policy. opa is chosen when absent and a .rego file is there."
+      "description": "The policy engine: patterns, matched in bash, or opa, which evaluates the Rego under .kit/policy. When absent, opa is used if a .rego file is there, and patterns otherwise."
     }
   }
 }
diff --git a/modules/kit/files/repo/.kit/templates/bash/module b/modules/kit/files/repo/.kit/templates/bash/module
new file mode 100644
index 0000000..b4c4b63
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/bash/module
@@ -0,0 +1,5 @@
+# shellcheck shell=bash
+# «name» - «purpose»
+# ----------------------------------------------------------------------------------------------------------------------
+«body»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/templates/bash/script b/modules/kit/files/repo/.kit/templates/bash/script
new file mode 100644
index 0000000..ddfdf99
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/bash/script
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# «name» - «purpose»
+# ----------------------------------------------------------------------------------------------------------------------
+«about»
+set -o errexit -o nounset -o pipefail
+«body»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/templates/gitignore/file b/modules/kit/files/repo/.kit/templates/gitignore/file
new file mode 100644
index 0000000..904cc2f
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/gitignore/file
@@ -0,0 +1,4 @@
+# .gitignore - untracked files and folders
+# ----------------------------------------------------------------------------------------------------------------------
+«entries»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/templates/gitignore/region b/modules/kit/files/repo/.kit/templates/gitignore/region
new file mode 100644
index 0000000..083cc3e
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/gitignore/region
@@ -0,0 +1,3 @@
+# kit:generate .gitignore
+«entries»
+# kit:end .gitignore
diff --git a/modules/kit/files/repo/.kit/templates/just/module b/modules/kit/files/repo/.kit/templates/just/module
new file mode 100644
index 0000000..5c3a322
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/just/module
@@ -0,0 +1,22 @@
+# «name» - see: https://just.systems/man/en/
+# ----------------------------------------------------------------------------------------------------------------------
+«about»
+set dotenv-load := true
+set fallback := true
+«settings»
+set positional-arguments := true
+«settings»
+set script-interpreter := ['bash']
+«settings»
+# This file's own path, assigned at parse time so the body below needs no interpolation.
+export «stem»_justfile := source_file()
+
+# Default recipe: list this justfile's recipes.
+_: help
+
+# List recipes in this justfile.
+[no-exit-message]
+@help *options:
+  just --justfile "${«stem»_justfile}" --list
+«recipes»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/templates/just/root b/modules/kit/files/repo/.kit/templates/just/root
new file mode 100644
index 0000000..8e63eec
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/just/root
@@ -0,0 +1,22 @@
+#!/usr/bin/env just --justfile
+# justfile - see: https://just.systems/man/en/
+# ----------------------------------------------------------------------------------------------------------------------
+«about»
+set dotenv-load := true
+«settings»
+set positional-arguments := true
+«settings»
+set script-interpreter := ['bash']
+«settings»
+# This file's own path, assigned at parse time so the body below needs no interpolation.
+export root_justfile := source_file()
+
+# Default recipe: list this justfile's recipes.
+_: help
+
+# List recipes in this justfile.
+[no-exit-message]
+@help *options:
+  just --justfile "${root_justfile}" --list
+«recipes»
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/modules/kit/files/repo/.kit/templates/markdown/agents b/modules/kit/files/repo/.kit/templates/markdown/agents
new file mode 100644
index 0000000..df26dab
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/markdown/agents
@@ -0,0 +1 @@
+«body»
diff --git a/modules/kit/files/repo/.kit/templates/markdown/document b/modules/kit/files/repo/.kit/templates/markdown/document
new file mode 100644
index 0000000..7a12cfe
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/markdown/document
@@ -0,0 +1,2 @@
+# «title»
+«body»
diff --git a/modules/kit/files/repo/.kit/templates/markdown/frontmatter b/modules/kit/files/repo/.kit/templates/markdown/frontmatter
new file mode 100644
index 0000000..5dea690
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/markdown/frontmatter
@@ -0,0 +1,4 @@
+---
+«frontmatter»
+---
+«body»
diff --git a/modules/kit/files/repo/.kit/templates/markdown/notice b/modules/kit/files/repo/.kit/templates/markdown/notice
new file mode 100644
index 0000000..aa92f12
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/markdown/notice
@@ -0,0 +1,3 @@
+<!-- «notice» -->
+# «title»
+«body»
diff --git a/modules/kit/files/repo/.kit/templates/workflows/workflow b/modules/kit/files/repo/.kit/templates/workflows/workflow
new file mode 100644
index 0000000..0eefc0a
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/workflows/workflow
@@ -0,0 +1,10 @@
+# «purpose»
+«about»
+name: «workflow»
+«body»
+on:
+«triggers»
+permissions:
+«permissions»
+jobs:
+«jobs»
diff --git a/modules/kit/files/repo/.kit/templates/yaml/document b/modules/kit/files/repo/.kit/templates/yaml/document
new file mode 100644
index 0000000..9b74360
--- /dev/null
+++ b/modules/kit/files/repo/.kit/templates/yaml/document
@@ -0,0 +1,2 @@
+# «purpose»
+«body»
diff --git a/modules/kit/module.yml b/modules/kit/module.yml
index d183e78..21e6a07 100644
--- a/modules/kit/module.yml
+++ b/modules/kit/module.yml
@@ -1,6 +1,6 @@
-# modules/kit/module.yml - the kit module: the entry every agent reads, the rules by file kind, and kit context
+# modules/kit/module.yml - the kit module: the agents' entry point, the rules for each file kind, and kit context
 # ----------------------------------------------------------------------------------------------------------------------
-# docs/modules.md says what each key means.
+# see: docs/modules.md
 
 description: "The entry every agent reads, the rules by file kind, and the context call that names them"
 default: true
diff --git a/modules/lefthook/docs/README.md b/modules/lefthook/docs/README.md
index e71c323..eb0aeaa 100644
--- a/modules/lefthook/docs/README.md
+++ b/modules/lefthook/docs/README.md
@@ -1,8 +1,13 @@
 # The lefthook module
 
-Places `.kit/lefthook.yml`, a pre-commit hook with two commands over the staged paths: `kit lint`, so each rule's own
-linter runs over the paths the rule governs before a commit, and `kit generate --check`, so a stale generated region is
-refused before it is committed. The repository's own `lefthook.yml` takes it with `extends: [.kit/lefthook.yml]` and
-adds commands of its own; Lefthook merges by name. The repository pins `lefthook` itself, since only a desk runs a hook,
-and `kit lint` and `kit generate` run the same way with no hook manager at all. The module expects that line, so `kit
-install` names it as left to do and `kit check` refuses until it is there; the kit writes nothing into `lefthook.yml`.
+Delivers `.kit/lefthook.yml`, a pre-commit hook with two commands over the staged paths:
+
+- `kit lint` runs each rule's own linter over the paths the rule governs, before the commit.
+- `kit generate --check` refuses a stale generated region before it is committed.
+
+The repository's own `lefthook.yml` includes the hook with `extends: [.kit/lefthook.yml]` and adds its own
+commands. Lefthook merges commands by name. The kit writes nothing into `lefthook.yml`. The module requires the
+`extends` line: `kit install` lists it as a step left to do, and `kit check` fails until it is there.
+
+The repository pins `lefthook` itself, because only a developer's machine runs a hook. `kit lint` and
+`kit generate` run the same way without any hook manager.
diff --git a/modules/lefthook/files/repo/.kit/lefthook.yml b/modules/lefthook/files/repo/.kit/lefthook.yml
index 46fc359..f1121a3 100644
--- a/modules/lefthook/files/repo/.kit/lefthook.yml
+++ b/modules/lefthook/files/repo/.kit/lefthook.yml
@@ -1,9 +1,13 @@
 # Delivered by kit, not edited by hand. A change is a new release, then kit update.
 #
-# The pre-commit hook runs kit lint over the staged paths: each rule's own linter, declared in the rule's
-# frontmatter, over the paths the rule governs. The repository's lefthook.yml takes this with
-# `extends: [.kit/lefthook.yml]` and adds commands of its own; Lefthook merges by name. Once per clone:
-# lefthook install
+# The pre-commit hook runs two commands over the staged files:
+#
+#   - kit-lint runs kit lint: each rule's own linter, declared in the rule's frontmatter, over the files the rule
+#     governs
+#   - kit-generate runs kit generate --check, which fails when a generated region is stale
+#
+# The repository's lefthook.yml includes this file with `extends: [.kit/lefthook.yml]`, and can add commands of its
+# own. Lefthook merges commands by name. Run `lefthook install` once per clone.
 #
 # see: https://lefthook.dev
 
diff --git a/modules/lefthook/module.yml b/modules/lefthook/module.yml
index cc2e4e0..f2be1c1 100644
--- a/modules/lefthook/module.yml
+++ b/modules/lefthook/module.yml
@@ -1,6 +1,6 @@
-# modules/lefthook/module.yml - the lefthook module: which linter runs over which paths before a commit
+# modules/lefthook/module.yml - the lefthook module: a pre-commit hook for kit lint and kit generate --check
 # ----------------------------------------------------------------------------------------------------------------------
-# docs/modules.md says what each key means.
+# see: docs/modules.md
 
 description: "A pre-commit hook that runs kit lint over the staged paths, for the repository's lefthook.yml to extend"
 depends:
diff --git a/modules/module.schema.json b/modules/module.schema.json
index b6206fb..c3537d7 100644
--- a/modules/module.schema.json
+++ b/modules/module.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/empowerite/kit/modules/module.schema.json",
   "title": "module.yml",
-  "description": "The metadata of one kit module, modules/<name>/module.yml; docs/modules.md says what each key means.",
+  "description": "The metadata of one kit module, modules/<name>/module.yml. Each key is described in docs/modules.md.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -17,7 +17,7 @@
     },
     "default": {
       "type": "boolean",
-      "description": "true for a module active unless removed; kit install activates every default module."
+      "description": "When true, the module is active unless removed. kit install activates every default module."
     },
     "depends": {
       "type": "array",
@@ -40,7 +40,7 @@
     },
     "expects": {
       "type": "array",
-      "description": "Lines the module expects in files the repository owns, such as the include a format composes by; kit check reports one that is missing, with its remedy, and the kit writes none of them.",
+      "description": "Lines the module expects in files the repository owns, such as the line that includes a delivered file (extends: [.kit/lefthook.yml]). kit check reports each missing line with its remedy. The kit never writes these lines.",
       "items": {
         "type": "object",
         "additionalProperties": false,
diff --git a/modules/policy-opa/docs/README.md b/modules/policy-opa/docs/README.md
index 2ea4f81..b54c026 100644
--- a/modules/policy-opa/docs/README.md
+++ b/modules/policy-opa/docs/README.md
@@ -1,7 +1,11 @@
 # The policy-opa module
 
-Places `.kit/policy/kit.rego`, the kit's naming policy in Rego, package `kit.policy`. With a `.rego` file under
-`.kit/policy/`, `kit policy` evaluates the policy with Open Policy Agent instead of the default patterns engine.
-The rules here are the patterns engine's, refusal for refusal, so taking the module changes nothing until the
-repository adds a rule of its own: a `.rego` file of its own beside this one, in the same package, adding to `deny`.
+Delivers `.kit/policy/kit.rego`, the kit's naming policy in Rego, in package `kit.policy`. When a `.rego` file is
+present under `.kit/policy/`, `kit policy` evaluates the policy with Open Policy Agent instead of the default
+patterns engine.
+
+The rules in `kit.rego` refuse exactly what the patterns engine refuses. Taking the module changes nothing until
+the repository adds a rule of its own. To add one, put a `.rego` file of the repository's own beside `kit.rego`,
+in the same package, that adds to `deny`.
+
 `kit policy --input` prints the input document a rule reads. The repository pins `opa` in its toolchain.
diff --git a/modules/policy-opa/files/repo/.kit/policy/kit.rego b/modules/policy-opa/files/repo/.kit/policy/kit.rego
index e2788c1..4b706c1 100644
--- a/modules/policy-opa/files/repo/.kit/policy/kit.rego
+++ b/modules/policy-opa/files/repo/.kit/policy/kit.rego
@@ -1,7 +1,7 @@
-# kit.rego - the kit's naming policy in Rego: the patterns engine's rules, word for word
+# kit.rego - the kit's naming policy in Rego: the same rules as the patterns engine
 # ----------------------------------------------------------------------------------------------------------------------
-# Delivered by kit, not edited by hand. A change is a new release, then kit update. A repository's own rules go in
-# a file of its own beside this one, in the same package, adding to deny; `kit policy --input` prints the input.
+# Delivered by kit, not edited by hand. A change is a new release, then kit update. Put the repository's own rules
+# in a separate file beside this one, in the same package, adding to deny. `kit policy --input` prints the input.
 
 package kit.policy
 
diff --git a/modules/policy-opa/module.yml b/modules/policy-opa/module.yml
index 52464f3..a7e6d19 100644
--- a/modules/policy-opa/module.yml
+++ b/modules/policy-opa/module.yml
@@ -1,6 +1,6 @@
 # modules/policy-opa/module.yml - the policy-opa module: the kit's naming policy as Rego, for Open Policy Agent
 # ----------------------------------------------------------------------------------------------------------------------
-# docs/modules.md says what each key means.
+# see: docs/modules.md
 
 description: "The kit's naming policy as Rego, so kit policy runs on Open Policy Agent and rules can grow beyond patterns"
 depends:
diff --git a/tests/fakes/fake-tool b/tests/fakes/fake-tool
index 5fcdc88..1ca6afc 100755
--- a/tests/fakes/fake-tool
+++ b/tests/fakes/fake-tool
@@ -34,3 +34,5 @@ do
 done < "${FAKE_DIR}/${tool}.routes"
 echo "${tool}: unrouted call: $*" >&2
 exit 1
+
+# ----------------------------------------------------------------------------------------------------------------------
diff --git a/tests/kit.bats b/tests/kit.bats
index 50bfb86..b2f5624 100644
--- a/tests/kit.bats
+++ b/tests/kit.bats
@@ -478,6 +478,7 @@ later-release() {
   grep --quiet '^version 9.9.9$' .kit/manifest
   mkdir -p "${repo}.newer" && cp -R "${repo}.later/bin" "${repo}.later/modules" "${repo}.newer/"
   printf '9.9.10\n' > "${repo}.newer/version"
+  printf 'Added in 9.9.10.\n' >> "${repo}.newer/modules/kit/files/repo/.kit/rules/json.md"
   printf 'edited\n' >> .kit/rules/bash.md
   # neither the cache, nor mise, nor the release can produce 9.9.9
   run env PATH="$(shims mise curl)" "${repo}.newer/bin/kit" update
@@ -485,6 +486,23 @@ later-release() {
   [[ "$output" == *"could not be fetched"* ]]
   [[ "$output" == *".kit/rules/bash.md cannot be updated without the base release 9.9.9"* ]]
   grep --quiet '^version 9.9.9$' .kit/manifest
+  # whole or not at all: the file that needed no base was not written either
+  ! grep --quiet 'Added in 9.9.10' .kit/rules/json.md
+  rm -rf "${repo}.newer"
+}
+
+@test "update without the base release replaces every file still as it was placed, where none is merged by key" {
+  later-release "${repo}.later"
+  "${repo}.later/bin/kit" install
+  mkdir -p "${repo}.newer" && cp -R "${repo}.later/bin" "${repo}.later/modules" "${repo}.newer/"
+  printf '9.9.10\n' > "${repo}.newer/version"
+  printf 'Added in 9.9.10.\n' >> "${repo}.newer/modules/kit/files/repo/.kit/rules/json.md"
+  run env PATH="$(shims mise curl)" "${repo}.newer/bin/kit" update
+  [ "$status" -eq 0 ]
+  grep --quiet 'Added in 9.9.10' .kit/rules/json.md
+  grep --quiet '^version 9.9.10$' .kit/manifest
+  run "${repo}.newer/bin/kit" check
+  [ "$status" -eq 0 ]
   rm -rf "${repo}.newer"
 }
 
diff --git a/tests/lint.bats b/tests/lint.bats
index c306fb0..968f7af 100644
--- a/tests/lint.bats
+++ b/tests/lint.bats
@@ -11,9 +11,18 @@ setup() {
   cd "${repo}"
   git init --quiet --initial-branch=main
   "${kit_checkout}/bin/kit" install >/dev/null
-  printf '#!/usr/bin/env bash\necho $x\n' > bad.sh
-  printf '#!/usr/bin/env bash\necho "${x:-}"\n' > good.sh
-  printf '#!/usr/bin/env bash\necho $y\n' > tool
+  script bad.sh 'echo $x'
+  script good.sh 'echo "${x:-}"'
+  script tool 'echo $y'
+}
+
+# script <path> <line> writes an executed bash script in the bash template's shape, its body the one line, so the
+# only thing a test's linter can refuse is that line.
+script() {
+  local rule
+  printf -v rule '# %s' "$(printf '%.0s-' $(seq 1 118))"
+  printf '#!/usr/bin/env bash\n# %s - a fixture\n%s\n\nset -o errexit -o nounset -o pipefail\n\n%s\n\n%s\n' \
+    "$1" "${rule}" "$2" "${rule}" > "$1"
 }
 
 teardown() {
diff --git a/tests/template.bats b/tests/template.bats
new file mode 100644
index 0000000..c3350cb
--- /dev/null
+++ b/tests/template.bats
@@ -0,0 +1,143 @@
+#!/usr/bin/env bats
+# template.bats - a rule's template makes a new file, kit new file, and holds every file to its shape, kit lint
+# ----------------------------------------------------------------------------------------------------------------------
+
+setup() {
+  export kit_root NO_COLOR=1
+  kit_root=$(cd "${BATS_TEST_DIRNAME}/.." && pwd)
+  export KIT_HOME="${BATS_TEST_TMPDIR}/home" XDG_CACHE_HOME="${BATS_TEST_TMPDIR}/cache"
+  mkdir -p "${KIT_HOME}" "${XDG_CACHE_HOME}"
+  repo=$(mktemp -d)
+  cd "${repo}"
+  git init --quiet --initial-branch=main
+  "${kit_root}/bin/kit" install >/dev/null 2>&1
+}
+
+teardown() {
+  rm -rf "${repo}"
+}
+
+# in_template <command>… runs a command with the template module loaded, from the repository, as a verb would.
+in_template() {
+  bash -c 'source "${kit_root}/bin/1st.sh" && use template && "$@"' _ "$@"
+}
+
+# shape <path>… runs only the shape check of every rule governing the paths, as kit lint does, without the linters.
+shape() {
+  local path rule status=0
+  for path in "$@"
+  do
+    while IFS= read -r rule
+    do
+      in_template template:check "${rule}" "${path}" || status=1
+    done < <(bash -c 'source "${kit_root}/bin/1st.sh" && use context && context:rules "$1"' _ "${path}")
+  done
+  return "${status}"
+}
+
+@test "a new file is made at the root from its rule's first template, its holes filled, and made executable" {
+  mkdir -p deep/er
+  cd deep/er
+  run "${kit_root}/bin/kit" new file bin/deploy.sh --purpose="push the build"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"made bin/deploy.sh from .kit/templates/bash/script"* ]]
+  [[ "$output" == *".kit/rules/bash.md"* ]]
+  cd "${repo}"
+  [ -x bin/deploy.sh ]
+  [ "$(sed -n 1,2p bin/deploy.sh)" = "$(printf '#!/usr/bin/env bash\n# deploy.sh - push the build')" ]
+  [ "$(tail -c 1 bin/deploy.sh | od -An -c | tr -d ' ')" = '\n' ]
+  [ "$(tail -n 1 bin/deploy.sh)" != "" ]
+  grep --quiet 'bin/deploy.sh' "$(git rev-parse --git-common-dir)/kit/context.log"
+}
+
+@test "every file kit new file makes has the shape of its own template" {
+  "${kit_root}/bin/kit" new file bin/a.sh --purpose=a
+  "${kit_root}/bin/kit" new file lib/b.sh --variant=module --purpose=b
+  [ ! -x lib/b.sh ]
+  "${kit_root}/bin/kit" new file justfile
+  "${kit_root}/bin/kit" new file tools.just
+  grep --quiet --fixed-strings 'export tools_justfile := source_file()' tools.just
+  grep --quiet --fixed-strings '"${tools_justfile}"' tools.just
+  "${kit_root}/bin/kit" new file docs/guide.md --title=Guide
+  [ "$(cat docs/guide.md)" = "# Guide" ]
+  "${kit_root}/bin/kit" new file conf/app.yml --purpose=app
+  "${kit_root}/bin/kit" new file sub/.gitignore
+  "${kit_root}/bin/kit" new file .github/workflows/check.yml --purpose=gate --workflow=check
+  grep --quiet '^name: check$' .github/workflows/check.yml
+  run shape bin/a.sh lib/b.sh justfile tools.just docs/guide.md conf/app.yml sub/.gitignore \
+    .github/workflows/check.yml
+  [ "$status" -eq 0 ]
+}
+
+@test "a hole left empty, a path that exists or leaves the root, and an unknown rule or variant are refused" {
+  run "${kit_root}/bin/kit" new file docs/guide.md
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"the document template of the markdown rule needs --title=<…>"* ]]
+  [ ! -e docs/guide.md ]
+  printf 'keep\n' > kept.sh
+  run "${kit_root}/bin/kit" new file kept.sh --purpose=x
+  [ "$status" -eq 1 ]
+  [ "$(cat kept.sh)" = "keep" ]
+  run "${kit_root}/bin/kit" new file ../out.sh --purpose=x
+  [ "$status" -eq 2 ]
+  run "${kit_root}/bin/kit" new file data.json
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"no rule with a template governs data.json"* ]]
+  run "${kit_root}/bin/kit" new file x.sh --variant=nope --purpose=x
+  [[ "$output" == *"its templates are: script module"* ]]
+  run "${kit_root}/bin/kit" new file x --rule=nope
+  [[ "$output" == *"there is no rule nope; the rules are: bash gitignore json just markdown workflows yaml"* ]]
+  run "${kit_root}/bin/kit" new file bin/tool --rule=bash --purpose="no extension"
+  [ "$status" -eq 0 ]
+  [ "$(head -n 1 bin/tool)" = "#!/usr/bin/env bash" ]
+}
+
+@test "the most specific rule's template is chosen, and a path-limited variant is the default only on its path" {
+  run in_template template:rules .github/workflows/check.yml
+  [ "${lines[0]}" = ".kit/rules/workflows.md" ]
+  [ "${lines[1]}" = ".kit/rules/yaml.md" ]
+  run in_template template:applies .kit/rules/just.md justfile
+  [ "$(cut -d $'\x1f' -f 1 <<<"$output" | paste -s -d ' ' -)" = "root module" ]
+  run in_template template:applies .kit/rules/just.md tools.just
+  [ "$(cut -d $'\x1f' -f 1 <<<"$output")" = "module" ]
+}
+
+@test "a file off its template's shape is named with the line it leaves, and a hole named twice must agree" {
+  "${kit_root}/bin/kit" new file bin/a.sh --purpose=a
+  sed -i.bak '/^set -o/d' bin/a.sh
+  run shape bin/a.sh
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"bin/a.sh does not have the shape of the bash template (script, module)"* ]]
+  [[ "$output" == *".kit/templates/bash/script line 5: set -o errexit -o nounset -o pipefail"* ]]
+  "${kit_root}/bin/kit" new file tools.just
+  sed -i.bak 's/"${tools_justfile}"/"${other_justfile}"/' tools.just
+  run shape tools.just
+  [ "$status" -ne 0 ]
+}
+
+@test "a hole that is a line matches any run of lines, none included, and one within a line any text on it" {
+  printf 'head «title» tail\n«body»\nend\n' > "${BATS_TEST_TMPDIR}/t"
+  printf 'head anything at all tail\nend\n' > none
+  printf 'head x tail\none\ntwo\nend\n' > two
+  printf 'head x tail\nend\nmore\n' > after
+  in_template template:matches "${BATS_TEST_TMPDIR}/t" none
+  in_template template:matches "${BATS_TEST_TMPDIR}/t" two
+  ! in_template template:matches "${BATS_TEST_TMPDIR}/t" after
+  printf 'a.b «x»\n' > "${BATS_TEST_TMPDIR}/dot"
+  printf 'aXb y\n' > dot
+  ! in_template template:matches "${BATS_TEST_TMPDIR}/dot" dot
+}
+
+@test "kit lint holds a governed file to its shape, and skips templates, regions, and generated paths" {
+  printf '#!/usr/bin/env bash\necho hi\n' > loose.sh
+  mkdir -p locks
+  printf 'lockfileVersion: 9\n' > locks/a.yaml
+  printf '/locks/** linguist-generated\n' > .gitattributes
+  run "${kit_root}/bin/kit" lint loose.sh locks/a.yaml .kit/templates/bash/script
+  [[ "$output" == *"loose.sh does not have the shape of the bash template"* ]]
+  [[ "$output" != *"locks/a.yaml does not"* ]]
+  [[ "$output" != *"templates/bash/script does not"* ]]
+  [[ "$output" == *".kit/rules/yaml.md: the shape of its templates over 0 path(s)"* ]]
+}
+
+# ----------------------------------------------------------------------------------------------------------------------

From 8e817bff623de8d1c5976bee0ef99404a4059921 Mon Sep 17 00:00:00 2001
From: Jeffrey Aguilera <jeffrey.aguilera@me.com>
Date: Tue, 27 Oct 2026 23:50:05 -0700
Subject: [PATCH 108/108] #1 kit status: one separator between every cell, and
 a heading for AGENTS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every row of kit status separates its cells with " · ": the checkout's label from its counts, a pull request's
title, author, state, checks, comments, and branch. A pull request's state and its age share a cell, and a failed
checks cell reads "<failing> failing <passed> / <total> <took>". AGENTS.md opens with its heading, above the kit's
region.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md         |  2 ++
 bin/status.sh     | 43 ++++++++++++++++++++++++-------------------
 tests/status.bats | 22 ++++++++++++++--------
 3 files changed, 40 insertions(+), 27 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 078a923..772c286 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,5 @@
+# AGENTS.md
+
 <!-- kit:generate AGENTS.md -->
 Read .kit/1st.md at the start of every session. It defines how any agent uses empowerite/kit to keep this
 repository trustworthy.
diff --git a/bin/status.sh b/bin/status.sh
index 18579e0..ff5e259 100644
--- a/bin/status.sh
+++ b/bin/status.sh
@@ -48,6 +48,9 @@ use git
 # status_commit_cap is how many uncommitted paths or commits a checkout block lists before it counts the rest.
 status_commit_cap=10
 
+# status_sep separates the cells of every row kit status prints.
+status_sep=' · '
+
 # status:width prints the terminal's width in columns: COLUMNS, else the width of the terminal on stderr, else
 # 100. A width under 60 also gives 100.
 status:width() {
@@ -167,7 +170,7 @@ status:fetch-summary() {
   line=${parts[0]}
   for part in "${parts[@]:1}"
   do
-    line+=" · ${part}"
+    line+="${status_sep}${part}"
   done
   printf '📥 fetched origin: %s\n' "${line}"
 }
@@ -328,12 +331,13 @@ status:measures() {
   [[ -n "${2:-}" ]] && IFS=' ' read -r ahead_w behind_w added_w removed_w <<<"$2"
   # The last column is padded only when something follows it, so no row ends in trailing spaces.
   (( uncommitted > 0 )) || removed_w=0
-  printf '%s %s · %s %s' \
+  printf '%s %s%s%s %s' \
     "$(status:paint-count "${ahead}" '↑' '1;32' "${ahead_w}" right)" \
     "$(status:paint-count "${behind}" '↓' '1;31' "${behind_w}" left)" \
+    "${status_sep}" \
     "$(status:paint-count "${added}" '+' '1;32' "${added_w}" right)" \
     "$(status:paint-count "${removed}" '-' '1;31' "${removed_w}" left)"
-  (( uncommitted > 0 )) && printf ' · %s' "$(status:paint 33 "${uncommitted} uncommitted")"
+  (( uncommitted > 0 )) && printf '%s%s' "${status_sep}" "$(status:paint 33 "${uncommitted} uncommitted")"
   return 0
 }
 
@@ -357,8 +361,8 @@ status:checkout-block() {
   local glyph=$1 doc=$2 label_w=$3 widths=${4:-} relative branch label width mark='' sha subject code path
   IFS=$'\x1f' read -r relative branch < <(jq --raw-output '[.relative, .branch] | join("\u001f")' <<<"${doc}")
   IFS=$'\t' read -r label width < <(status:label "${relative}" "${branch}")
-  [[ -n "${branch}" ]] || mark="   $(status:paint 33 '❗ detached HEAD')"
-  printf '%s %s%*s%s   %s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" \
+  [[ -n "${branch}" ]] || mark="${status_sep}$(status:paint 33 '❗ detached HEAD')"
+  printf '%s %s%*s%s%s%s\n' "${glyph}" "${label}" $(( label_w - width )) '' "${mark}" "${status_sep}" \
     "$(status:measures "${doc}" "${widths}")" >&2
   # A status can start with a space, which a tab-separated read would drop, so the separator is \x1f instead.
   while IFS=$'\x1f' read -r code path
@@ -396,9 +400,9 @@ status:checkout-block() {
 
 # status:check-cell <checks-json> prints the checks cell, with the duration dim:
 #
-#   - passed: "✅ <passed> / <total> · <took>"
-#   - failed: "❌ <failing> · <passed> / <total> · <took>"
-#   - running: "🏃 <passed> / <total> · <elapsed>"
+#   - passed: "✅ <passed> / <total> <took>"
+#   - failed: "❌ <failing> failing <passed> / <total> <took>"
+#   - running: "🏃 <passed> / <total> <elapsed>"
 #
 # It prints nothing when no check has reported.
 status:check-cell() {
@@ -408,18 +412,18 @@ status:check-cell() {
     < <(jq --raw-output '[.state, .passed, .total, .failing, (.took // "")] | map(tostring) | join("\u001f")' <<<"$1")
   case "${state}" in
     (SUCCESS) text="✅ ${total} / ${total}" ;;
-    (FAILURE) text="❌ ${failing} · ${passed} / ${total}" ;;
+    (FAILURE) text="❌ ${failing} failing ${passed} / ${total}" ;;
     (PENDING) text="🏃 ${passed} / ${total}" ;;
     (*) return 0 ;;
   esac
   printf '%s' "${text}"
-  [[ -n "${took}" ]] && printf ' · %s' "$(status:paint 90 "$(status:age "${took}")")"
+  [[ -n "${took}" ]] && printf ' %s' "$(status:paint 90 "$(status:age "${took}")")"
   return 0
 }
 
 # status:pr-block <pr-json> <title-width> <owner-width> <state-width> <age-width> <worktree> prints a pull request:
-# its row, then the issues it closes. The row shows the author before the state when <owner-width> is above zero,
-# and ends with the branch when a worktree here has it checked out.
+# its row, then the issues it closes. The state and its age share a cell. The row shows the author before the state
+# when <owner-width> is above zero, and ends with the branch when a worktree here has it checked out.
 status:pr-block() {
   local doc=$1 title_w=$2 owner_w=$3 state_w=$4 age_w=$5 worktree=$6
   local number ref title author branch state age unresolved row issue checks
@@ -428,14 +432,14 @@ status:pr-block() {
           | map(tostring)
           | join("\u001f")' <<<"${doc}")
   row="🔀 $(status:cell "${ref} ${title}" "${title_w}")"
-  (( owner_w > 0 )) && row+="   👤 $(status:paint 90 "$(status:cell "${author}" "${owner_w}")")"
-  row+="   $(status:state-emoji "${state}")"
+  (( owner_w > 0 )) && row+="${status_sep}👤 $(status:paint 90 "$(status:cell "${author}" "${owner_w}")")"
+  row+="${status_sep}$(status:state-emoji "${state}")"
   row+=" $(status:paint "$(status:state-sgr "${state}")" "$(status:cell "${state}" "${state_w}")")"
-  row+="   $(status:paint 90 "$(status:cell "$(status:age "${age}")" "${age_w}")")"
+  row+=" $(status:paint 90 "$(status:cell "$(status:age "${age}")" "${age_w}")")"
   checks=$(status:check-cell "$(jq --compact-output .checks <<<"${doc}")")
-  [[ -n "${checks}" ]] && row+="   ${checks}"
-  (( unresolved > 0 )) && row+="   $(status:paint 33 "💬 ${unresolved} unresolved")"
-  [[ -n "${worktree}" ]] && row+="   $(status:paint 90 "🌿 ${branch}")"
+  [[ -n "${checks}" ]] && row+="${status_sep}${checks}"
+  (( unresolved > 0 )) && row+="${status_sep}$(status:paint 33 "💬 ${unresolved} unresolved")"
+  [[ -n "${worktree}" ]] && row+="${status_sep}$(status:paint 90 "🌿 ${branch}")"
   printf '%s\n' "${row}" >&2
   while IFS= read -r issue
   do
@@ -573,7 +577,8 @@ status:render() {
     printf '\n' >&2
     while IFS= read -r branch
     do
-      printf '🔖 %s   %s\n' "${branch}" "$(status:paint 90 'upstream gone · kit tidy removes it')" >&2
+      printf '🔖 %s%s%s\n' "${branch}" "${status_sep}" \
+        "$(status:paint 90 "upstream gone${status_sep}kit tidy removes it")" >&2
     done <<<"${gone}"
   fi
 }
diff --git a/tests/status.bats b/tests/status.bats
index ebf52d3..0232104 100644
--- a/tests/status.bats
+++ b/tests/status.bats
@@ -64,7 +64,7 @@ commits-in() {
   doc=$(in_status status:checkout "${PWD}/worktrees/topic" topic main)
   run in_status status:checkout-block 🌿 "${doc}" 15
   [ "$status" -eq 0 ]
-  [ "${lines[0]}" = "🌿 worktrees/topic   ↑15 ↓0 · +15 -0" ]
+  [ "${lines[0]}" = "🌿 worktrees/topic · ↑15 ↓0 · +15 -0" ]
   [ "${#lines[@]}" -eq 12 ]
   [[ "${lines[1]}" == *" c15" ]]
   [[ "${lines[9]}" == *" c7" ]]
@@ -78,7 +78,7 @@ commits-in() {
   doc=$(in_status status:checkout "${PWD}" main main)
   run in_status status:checkout-block 🏠 "${doc}" 4
   [ "$status" -eq 0 ]
-  [ "${lines[0]}" = "🏠 main   ↑1 ↓0 · +1 -0 · 1 uncommitted" ]
+  [ "${lines[0]}" = "🏠 main · ↑1 ↓0 · +1 -0 · 1 uncommitted" ]
   [ "${lines[1]}" = "   ?? c" ]
   [[ "${lines[2]}" == *" two" ]]
   [ "${#lines[@]}" -eq 3 ]
@@ -89,7 +89,7 @@ commits-in() {
   for i in $(seq 1 12); do printf '%s\n' "${i}" > "n${i}"; done
   doc=$(in_status status:checkout "${PWD}" main main)
   run in_status status:checkout-block 🏠 "${doc}" 4
-  [ "${lines[0]}" = "🏠 main   ↑0 ↓0 · +1 -1 · 13 uncommitted" ]
+  [ "${lines[0]}" = "🏠 main · ↑0 ↓0 · +1 -1 · 13 uncommitted" ]
   [ "${lines[1]}" = "    M a" ]
   [ "${lines[2]}" = "   ?? n1" ]
   [ "${lines[11]}" = "   … and 3 more" ]
@@ -110,7 +110,8 @@ commits-in() {
   )
   run in_status status:fetch main
   [ "$status" -eq 0 ]
-  [ "${lines[0]}" = "📥 fetched origin: 2 new commits on main · 1 branch updated · 1 new branch · 1 branch pruned · 1 new tag" ]
+  expected='📥 fetched origin: 2 new commits on main · 1 branch updated · 1 new branch · 1 branch pruned'
+  [ "${lines[0]}" = "${expected} · 1 new tag" ]
   run in_status status:fetch main
   [ "${lines[0]}" = "📥 fetched origin: nothing new" ]
 }
@@ -119,7 +120,7 @@ commits-in() {
   printf 'x\n' > c
   run "${kit_root}/bin/kit" status
   [ "${lines[0]}" = "📥 fetched origin: nothing new" ]
-  [ "${lines[1]}" = "🏠 main   ↑0 ↓0 · +0 -0 · 1 uncommitted" ]
+  [ "${lines[1]}" = "🏠 main · ↑0 ↓0 · +0 -0 · 1 uncommitted" ]
   [ "${lines[2]}" = "   ?? c" ]
   [[ "${lines[3]}" == *"forge"* ]]
 }
@@ -128,7 +129,7 @@ commits-in() {
   git worktree add --quiet --detach worktrees/loose main
   doc=$(in_status status:checkout "${PWD}/worktrees/loose" '' main)
   run in_status status:checkout-block 🌿 "${doc}" 15
-  [ "$output" = "🌿 worktrees/loose   ❗ detached HEAD   ↑0 ↓0 · +0 -0" ]
+  [ "$output" = "🌿 worktrees/loose · ❗ detached HEAD · ↑0 ↓0 · +0 -0" ]
 }
 
 @test "the counts of every checkout sit in columns, ahead and added right-aligned, behind and removed left-aligned" {
@@ -156,12 +157,17 @@ commits-in() {
   doc+='"unresolved":0,"checks":{"state":"PENDING","passed":0,"total":1,"failing":0,"took":36},'
   doc+='"closes":[{"number":1,"title":"One"},{"number":4,"title":"Four"}]}'
   run in_status status:pr-block "${doc}" 12 0 6 2 worktrees/2-the-first
-  [ "${lines[0]}" = "🔀 #2 The first   🚦 queued   3d   🏃 0 / 1 · 36s   🌿 2-the-first" ]
+  [ "${lines[0]}" = "🔀 #2 The first · 🚦 queued 3d · 🏃 0 / 1 36s · 🌿 2-the-first" ]
   [ "${lines[1]}" = "   closes #1 One" ]
   [ "${lines[2]}" = "   closes #4 Four" ]
   [ "${#lines[@]}" -eq 3 ]
   run in_status status:pr-block "${doc}" 12 5 6 2 ''
-  [ "${lines[0]}" = "🔀 #2 The first   👤 ada     🚦 queued   3d   🏃 0 / 1 · 36s" ]
+  [ "${lines[0]}" = "🔀 #2 The first · 👤 ada   · 🚦 queued 3d · 🏃 0 / 1 36s" ]
+}
+
+@test "a failed checks cell names the failing count, then passed of total, then the time taken" {
+  run in_status status:check-cell '{"state":"FAILURE","passed":3,"total":5,"failing":2,"took":31}'
+  [ "$output" = "❌ 2 failing 3 / 5 31s" ]
 }
 
 @test "the pull requests shown are everyone's, or the named authors' alone" {