@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/INSTALL.md

@@ -0,0 +1,623 @@
+# Build Installation Guide
+
+Build is MIT-licensed open-source software distributed through the public npm
+package `@ebrindley/build`; see the [MIT License](./LICENSE).
+
+This is the installation and first-use path for local machines, agents, CI,
+and cloud VMs. Follow prerequisites, choose an installation channel, verify
+the installed executable, then configure a provider and initialize a target
+repository. Cloud dogfooding uses this same path; VM provisioning supplies the
+machine, provider CLIs, and runtime credentials.
+
+## Choose your path
+
+| Goal | Installation channel |
+| --- | --- |
+| Latest published release | [Quick Install](#quick-install): npm `latest` |
+| Current GitHub code, including unreleased changes | [Contributor / Git Source](#contributor--git-source): `--source git --version main` |
+| Repeat an exact build | Pin the package version, or pin both the script and source to a full Git commit |
+| Edit Build itself | [Contributor checkout](#contributor-checkout) |
+
+Downloading `install.sh` from GitHub chooses the script, not the code it will
+install. With `--source auto` (the default), a fresh install uses npm; an
+existing `~/.build/install.json` can select its recorded channel. Use an
+explicit source when the intended channel matters. Installing from GitHub
+source requires no npm publication, but its build downloads dependencies from npm.
+
+## Prerequisites
+
+- Node.js 24.x or 26.x and npm 9+. The installer checks the active Node version; it
+  does not install or switch Node for you.
+- A writable npm prefix owned by your user; do not use sudo. With nvm, keep
+  its prefix rather than setting a persistent `prefix` in `.npmrc`.
+- Git — required for normal operation, including isolated worktrees, and for
+  source installation. Source builds also need npm lifecycle scripts enabled
+  (`ignore-scripts` must be false); package installs do not.
+- No Python, make or C/C++ compiler. The native SQLite dependency ships prebuilt
+  binaries for macOS and Linux (x64 and arm64, glibc and musl), and neither
+  install channel compiles it. You do not need `--allow-scripts`.
+  The bundled Linux glibc prebuild needs glibc 2.34 or newer and libstdc++
+  providing `GLIBCXX_3.4.29`; meeting Node's version requirement alone is not
+  sufficient on older distributions. There is no automatic source-build fallback.
+- macOS. Build is built and tested on macOS; Linux and Windows (through WSL2)
+  work but are best-effort and not officially supported. On Linux
+  VMs/containers, write-capable runs use the isolated-host policy. Desktop Linux
+  requires the documented consent flow. See [runtime security boundaries](docs/reference/SECURITY.md#runtime-security-boundaries).
+- Network access to npm and, for private source installs, authenticated GitHub
+  access for both the script download and the Git fetch.
+- The target project's own toolchain and dependencies for its tests/build.
+  Build reports unavailable verification when that tooling is missing.
+
+### Select Node 24 or 26
+
+With nvm installed and loaded in the current shell (the examples use 24;
+substitute 26 to run on Node 26):
+
+```bash
+nvm install 24
+nvm use 24
+export PATH="$(dirname "$(nvm which 24)"):$PATH"
+hash -r
+command -v node
+node --version
+npm --version
+npm config get prefix
+```
+
+`node --version` must report `v24.x` or `v26.x`. A VM can have Node 24 installed while
+another Node earlier on PATH still wins, even after `nvm use`. For a shell
+without nvm, install/activate Node 24 using your platform's supported method
+and perform the same version checks. On Apple Silicon with Homebrew Node 24
+installed, its directory is `/opt/homebrew/opt/node@24/bin`.
+
+## Quick Install
+
+Install npm's latest published release:
+
+```bash
+npm install -g @ebrindley/build
+```
+
+The self-checking bootstrap is `npx --yes @ebrindley/build-install`. It uses
+its bundled installer and pins Build to the bootstrap package's version.
+A published bootstrap need not contain the newest installer from GitHub.
+
+For an exact published package, use
+`npm install -g @ebrindley/build@<version>`.
+After the repository becomes public, an explicit npm-channel installer is:
+
+```bash
+set -o pipefail
+curl -fsSL https://raw.githubusercontent.com/ebrindley/build/main/install.sh | bash -s -- --source package
+```
+
+For reproducible release automation, pin both inputs:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ebrindley/build/v<version>/install.sh \
+  | bash -s -- --source package --version <version> --strict
+```
+
+Continue with [Verify the installation](#verify-the-installation).
+
+## Contributor / Git Source
+
+### Private GitHub access
+
+While the repository is private, `gh api` retrieves the installer. Provision
+GitHub access in the shell first (`gh auth login` for an interactive user;
+platform-provided credentials for automation). A cloud platform's repository
+clone permission alone does not establish shell access.
+
+The installer also uses Git to fetch the source. An authenticated `gh` command
+alone does not configure Git. When `gh` is authenticated but Git has no gh
+credential helper, the installer passes gh's active token to Git through a
+temporary askpass helper for that install only, writing no Git config. In an
+interactive install it first asks to add `!gh auth git-credential` as a
+GitHub credential helper; noninteractive installs add it only with the opt-in
+below. The helper goes in the current user's global Git config, preserving
+existing helpers. Do not print credentials or put tokens in commands.
+
+```bash
+export BUILD_INSTALL_MODIFY_GIT_CREDENTIALS=1
+```
+
+If Git already authenticates, neither path is needed. Without `gh`, the
+installer uses an ambient `GITHUB_TOKEN` through the same temporary askpass
+helper.
+
+### Install current main
+
+With the prerequisites above, run the source one-liner:
+
+```bash
+installer="$(mktemp)"
+gh api -H 'Accept: application/vnd.github.raw+json' 'repos/ebrindley/build/contents/install.sh?ref=main' > "$installer" \
+  && bash "$installer" --source git --version main
+rm -f "$installer"
+```
+
+Download to a file rather than piping `gh api` into `bash`: when the API call
+fails, `gh` writes the error response to stdout, and a pipe would hand that
+text to the shell. `set -o pipefail` only changes the pipeline's exit status;
+it does not stop `bash` from running what it received. The `&&` runs the
+installer only if `gh api` exited 0.
+
+The installer resolves `main` to a full commit, fetches that commit, runs
+`npm ci` and `npm pack` (the `prepack` lifecycle builds `dist/`), and installs
+the resulting tarball. No prebuilt `dist/` is needed in Git. Expect several
+minutes on a cold machine. `BUILD_INSTALL_BUILD_TIMEOUT` defaults to 1800
+seconds per build step. If main advances afterward, rerun this command to
+install the newer commit.
+
+For an exact source build, replace **both** `ref=main` and `--version main`
+with the same full commit SHA. `--source git` alone also defaults to `main`.
+
+`BUILD_INSTALL_REPO=owner/repo` selects another GitHub upstream for the
+installer. The installer does not read `BUILD_REPO`, which the CLI uses to
+select a local project root.
+
+### Unattended installs
+
+Use the same source command. Add `--skip-setup --skip-doctor` to separate
+package installation from provider/project setup, then follow the setup
+sections below explicitly. Without a TTY the installer already skips its
+interactive wizard; it does not configure a complete consumer project. It
+reports provider readiness and what `build config instructions import --check`
+would bring in from your agents, and changes neither.
+
+The default destination is the active npm prefix. For a separate writable
+installation, add `--install-dir /absolute/prefix` and use that prefix in the
+PATH checks below. This also lets a VM test a new install while preserving
+its preinstalled copy. A new VM is not necessarily an empty image.
+Relative `--install-dir` paths are resolved against the installer's starting
+directory before installation and saved as absolute paths.
+
+For fresh-install tests, give each fixture a separate HOME and installation
+prefix. Changing HOME can hide an existing `gh` login even when `GH_CONFIG_DIR`
+still points at its configuration. Supply private Git-source credentials through
+the installer's temporary bridge, for example a CI-provided `GITHUB_TOKEN`;
+do not copy the operator's auth files into the fixture. Unattended installs
+already avoid persistent Git-helper changes. `--no-github-auth` skips all
+installer-managed authentication, including temporary gh/GITHUB_TOKEN credentials;
+Git's own configured authentication still applies.
+
+PATH and Git-helper changes are explicit opt-ins: `--modify-path` enables
+shell-rc updates in automation; `BUILD_INSTALL_MODIFY_GIT_CREDENTIALS=1` enables the
+helper change described above. `--yes` does not opt into either. The requested
+`--modify-path` update is persisted even when the installer's current PATH
+already includes that prefix's bin directory. It does not change the calling
+shell and may leave an existing command
+earlier on PATH; verify the executable next.
+
+`--strict --skip-setup --skip-doctor` makes package identity and conflicting
+fresh-shell PATH checks fail the install without gating on provider readiness.
+If it fails, inspect the error and existing installation before retrying.
+A failed post-install check can leave the package installed.
+For an isolated prefix that deliberately preserves the system PATH, use
+`--no-modify-path` and verify `/absolute/prefix/bin/build debug version --json`
+directly. Do not add `--strict` when another Build command wins in a fresh shell;
+its PATH-conflict failure is intentional.
+
+## Verify the installation
+
+For the default npm prefix, activate its bin directory in the current shell:
+
+```bash
+export PATH="$(npm config get prefix)/bin:$PATH"
+hash -r
+command -v build
+build --version
+build debug version --json
+```
+
+If you used `--install-dir`, substitute that exact prefix's `bin` directory.
+Check that `command -v build` selects it and `debug version` reports the
+package entry under that prefix, rather than a preinstalled `repo-dist`
+launcher. The installer pins its generated launcher to the selected Node.
+
+Reopen your usual shell and check `command -v build` again. If another
+command wins, put the desired prefix first in that shell's startup PATH;
+`--modify-path` adds missing directories but does not necessarily reorder
+existing ones. The installer preserves conflicting commands and warns by
+default. Installation exit zero alone does not establish future shell selection.
+On Debian/Ubuntu, Bash's `.profile` can prepend `~/.local/bin` after sourcing
+`.bashrc`. Put the desired prefix's PATH export after that step in `.profile`
+for login shells, and in `.bashrc` for interactive non-login shells.
+
+For a Git-source install, inspect the manifest's nonsecret identity fields:
+
+```bash
+node -e 'const fs = require("node:fs"); const p = require("node:path"); const m = JSON.parse(fs.readFileSync(p.join(require("node:os").homedir(), ".build/install.json"), "utf8")); console.log({source:m.source, ref:m.ref, commit:m.commit, prefix:m.prefix});'
+```
+
+Expect `source: git`, the requested ref, the resolved full commit printed by
+the installer, and the selected prefix. For a pinned build the commit must
+match the requested SHA. A version such as an RC can cover several commits.
+`debug version`'s `gitHead` describes the **current working directory**, not
+the installed source revision; use the manifest together with the selected
+package entry and the successful source-build output.
+
+`install.sh` writes its manifest at `$HOME/.build/install.json` even when
+runtime `BUILD_HOME` is set. See [state locations](https://github.com/ebrindley/build/blob/main/docs/reference/TELEMETRY_PRIVACY.md)
+for isolating Build runtime config/data while retaining provisioned provider
+settings. Changing HOME also changes where Git and provider CLIs find settings.
+
+## Set up a provider
+
+Install and authenticate your chosen provider CLI using
+[provider setup](docs/PROVIDER_SETUP.md). For example, an interactive Claude
+user installs `npm install -g @anthropic-ai/claude-code` and runs
+`claude auth login`; Codex uses `npm install -g @openai/codex` and `codex login`.
+In automation, provision credentials and backend configuration externally.
+With Bedrock, preserve the provider CLI's Bedrock configuration and the VM's
+runtime secret environment; browser/subscription login is unnecessary.
+
+Interactive users can run `build provider setup --first-run`; with several
+ready providers it asks which one is the default. To set the default without
+prompts, run
+`build provider setup --first-run --providers <id> --non-interactive`. For an
+unattended Claude setup:
+
+```bash
+build provider setup --providers claude --non-interactive
+build config resolved --summary --json
+```
+
+Substitute `codex` or your intended provider. Inspect resolved configuration
+before relying on zero-flag routing. An active profile overrides project and
+user configuration. With `--providers <ids>`, first-run checks and completion
+consider only those providers. At least one selected CLI must be installed and
+healthy with no known auth failure; unknown auth is deferred to its first
+invocation and reported as execution unverified. To choose a persistent Codex
+profile explicitly:
+
+```bash
+build profile list
+build profile create codex-work --provider codex
+build profile use codex-work
+build config resolved --summary --json
+```
+
+If the intended profile already exists, inspect and use it instead of creating
+it again. Choose a distinct name if `codex-work` exists with other settings.
+CLI `--provider` selects a provider for one invocation. With model `auto`,
+Claude and Codex use their configured CLI defaults; no model pin is needed here.
+Project config edits can leave timestamped backups beside the config file.
+`build config cleanup --backups` removes older backups and keeps the three
+most recent.
+
+`build provider list` and `build doctor` provide diagnostics. Deferred or
+unobserved auth is a normal cold state; it does not prove bad credentials.
+A real provider invocation establishes whether execution works. For providers
+supported by `ask`, a small check is:
+
+```bash
+build ask --to claude --timeout 120 "Reply with exactly: pong"
+```
+
+Substitute the intended provider. If it is not ask-eligible, use a small
+`build run task` below. Diagnose actual execution errors rather than making
+passive readiness a prerequisite for trying the provider.
+
+## Initialize a project and run a task
+
+Use the target Git repository, not Build's source checkout. Set your Git
+commit identity and make an initial commit in a new repository before running
+a pipeline. Its test/build tools must be available. Then:
+
+```bash
+cd /path/to/your/project
+build init --safe-branch fix/first-build-task
+build config resolved --summary --json
+build config validate
+build doctor
+```
+
+On a dedicated Linux cloud VM or container, if `build doctor` reports that
+Linux write consent is missing, record the isolated host class before running
+a write task:
+
+```bash
+build sandbox trust linux --host isolated
+```
+
+For a Linux desktop, follow the separate
+[desktop consent flow](docs/reference/SECURITY.md#runtime-security-boundaries).
+
+Interactive init offers optional knowledge and CI setup, with previews before
+CI changes, and once per machine the instructions import. Noninteractive init
+leaves those choices unchanged. `build init`
+is the full scaffold, and `--safe-branch <name>` first creates and switches to a
+working branch; `build init quickstart` is an optional readiness check afterward. Agents can inspect compact context with `build context --json`.
+Review and commit the generated project instructions and scaffold before
+running a task: isolated worktrees start from commits, so untracked instructions
+such as `AGENTS.md` will not be included.
+
+For a small local test with an explicitly selected provider:
+
+```bash
+build run task --provider codex --profile speed --no-push "Create first-task-marker.txt with exactly one line: FIRST_TASK_OK. Do not modify any other files."
+```
+
+Substitute the provider you configured. Inspect the output's task ID,
+provider, preserved worktree/patch, and delivered file. `build run` normally
+edits an isolated worktree; changes may not appear in the target root. Inspect
+the patch, then apply it with `build run apply <task-id>` when desired. For a
+code-change dogfood, provide a tiny fixture with predetermined tests, inspect
+the returned implementation, and verify those tests against the delivered code.
+For your first real task, follow the
+[quick start](docs/getting-started/QUICK_START.md#step-3-first-success--run-a-task-3-minutes),
+the canonical first-success path: it starts with `build`, then covers judged
+competitions and planned builds.
+
+## Contributor checkout
+
+For developing Build itself, clone the authenticated repository, activate
+Node 24 or 26 as above, then run `npm ci` and `./scripts/compile-dist.sh` from that
+checkout. The build script rebuilds the CLI and wires the contributor command.
+Rebuild native dependencies under the active Node when moving an existing checkout
+from another Node major. Verify the selected executable after building; a
+contributor launcher and a package install can coexist on PATH.
+
+## Flags and Environment Variables
+
+Flags go after `--` when piping through bash. Flags take precedence over env.
+
+| Flag                  | Env var                   | Default                              | Purpose                                                                                                                                                                                                                                               |
+| --------------------- | ------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--source <source>`   | `BUILD_INSTALL_SOURCE`   | `auto`                               | `auto` (recorded channel, otherwise npm), `package`/`stable`, or `git`                                                                                                                                                                                                                  |
+| `--version <ref>`     | `BUILD_INSTALL_VERSION`          | `latest` for package, `main` for git | npm version/dist-tag or git ref                                                                                                                                                                                                                       |
+| `--package <name>`    | `BUILD_INSTALL_PACKAGE`          | `@ebrindley/build`                        | npm package name                                                                                                                                                                                                                                      |
+| `--force`             | `BUILD_INSTALL_FORCE=1`          | off                                  | reinstall even if manifest matches                                                                                                                                                                                                                    |
+| `--dry-run`           | `BUILD_INSTALL_DRY_RUN=1`        | off                                  | print plan, make no changes                                                                                                                                                                                                                           |
+| `--install-dir <dir>` | `BUILD_INSTALL_DIR`      | npm prefix                           | override install location                                                                                                                                                                                                                             |
+| `--no-modify-path`    | `BUILD_INSTALL_NO_MODIFY_PATH=1` | off                                  | never write to shell rc                                                                                                                                                                                                                               |
+| `--modify-path`       | `BUILD_INSTALL_MODIFY_PATH=1`    | off                                  | allow adding a missing bin directory to shell rc when noninteractive; verify ordering separately |
+| `--skip-setup`        | `BUILD_INSTALL_SKIP_SETUP=1`     | off                                  | skip first-run wizard hand-off                                                                                                                                                                                                                        |
+| `--skip-doctor`       | `BUILD_INSTALL_SKIP_DOCTOR=1`    | off                                  | skip post-install `build doctor`                                                                                                                                                                                                                     |
+| `--strict`            | `BUILD_INSTALL_STRICT=1` | off                                  | fail install when prefix identity integrity fails or provider-only readiness probing finds no runnable provider. Unrelated target-repository doctor advisories remain visible but do not fail package installation. Without `--strict`, health warnings and an unconfigured-provider state are logged but do not fail the install. |
+| `--yes` / `-y`        | `BUILD_INSTALL_YES=1`            | off                                  | answer eligible confirmations; a TTY remains interactive-capable, and the flag does not opt into PATH, credential-helper, or provider-install mutations                                                                                               |
+|                       | `BUILD_INSTALL_MODIFY_GIT_CREDENTIALS=1` | off                         | allow non-interactive installs to configure the global GitHub credential helper when authenticated `gh` is available                                                                                                                                  |
+
+`--strict` runs a provider-only doctor probe and requires a ready provider. A readiness failure can leave
+the package installed, but it does not write a success manifest. Use
+`--skip-setup --skip-doctor --strict` for an identity-only CI install; selected
+prefix integrity still runs and a successful install writes the manifest.
+
+Without `--strict`, selected-prefix identity is still checked unless
+`--skip-doctor` is set (non-strict `--skip-doctor` skips the check). When the
+check fails, the installer exits 0 but warns in place of `Installation
+complete.` (or `Done.` when it reuses an existing install) and does not write
+or update the manifest. A manifest from an earlier install keeps naming that
+install, so a plain `--uninstall` targets the earlier prefix; pass
+`--install-dir <prefix>` to uninstall the new one.
+
+Other recognized env vars: `GITHUB_TOKEN`, `NO_COLOR`, `CI`,
+`DEBIAN_FRONTEND`, `BUILD_ALLOW_UNSUPPORTED_NODE`.
+
+## Updating Build
+
+Use the update path matching your installation:
+
+| Installation | Update |
+| --- | --- |
+| Git-source package | Repeat [Install current main](#install-current-main), or pin a newer commit; preserve your chosen prefix |
+| Published npm package | `build upgrade --source package`, or `--target-version <version>` for an exact release |
+| Contributor checkout | Fast-forward the checkout, activate Node 24, run `npm ci`, then `./scripts/compile-dist.sh` |
+
+For source packages, `install.sh` builds the resolved commit before
+installation. `build upgrade --source git` builds it the same way, without
+needing Python or a C toolchain for prebuilt native dependencies, then installs
+the packed tarball. Upgrade installs into the prefix the running `build` is
+installed under (refusing if the manifest records a different one) unless
+`--install-dir` names another. The commands share a manifest; their
+setup, verification, and recovery behavior can differ.
+
+Recheck the selected executable and manifest after an update. Repeating the
+same source commit/prefix can reuse a verified installation; `--force`
+requests a reinstall. `build upgrade --refresh-integrations` separately
+refreshes installed cleanup integrations.
+
+## Idempotency and Rollback
+
+A successful pinned package install writes `~/.build/install.json`:
+
+```json
+{
+  "schema": 2,
+  "source": "package",
+  "ref": "<version>",
+  "package": "@ebrindley/build",
+  "version": "<version>",
+  "prefix": "/opt/homebrew",
+  "installedAt": "2026-05-16T18:00:00.000Z"
+}
+```
+
+Git-source installs record `source: "git"` and the resolved commit instead of
+the npm version. Reuse checks that recorded commit and the canonical prefix,
+and verifies that the selected executable reports usable identity. Package
+installs additionally require the executable's version to match the requested
+version. `--force` requests reinstallation even when those checks pass.
+Dry-run reports the identity verification it would perform without invoking the
+installed CLI. It also asks no questions (it prints each one it would ask) and
+reports a conflicting `build` that wins in a fresh shell, as a real install does.
+
+Rollback is best-effort, not atomic: on `npm install` failure the installer
+attempts to reinstall the previous manifest target. If rollback fails, the
+previous manifest is preserved at `~/.build/install.json.bak`.
+
+If `npm install` succeeds but post-install verification fails (`build doctor`,
+`build provider list`, or `--strict` gating), the package remains installed
+unless selected-prefix identity integrity failed (that path is still part of
+the install mutation and triggers best-effort package/PATH rollback). The
+installer does not write a success manifest after that failed readiness gate.
+It logs readiness warnings unless `--strict` is set; fix configuration and
+re-run `build doctor` or `build init quickstart` without reinstalling.
+
+## Verifying the Install
+
+Follow [Verify the installation](#verify-the-installation) for executable and
+source identity, then [Set up a provider](#set-up-a-provider) for a real
+invocation. These checks cover different things; `build doctor` neither
+initializes the project nor proves an untried provider can execute.
+
+## Uninstalling
+
+```bash
+npx --yes @ebrindley/build-install -- --uninstall
+```
+
+This uninstalls the main npm package, removes only blocks guarded by
+`# >>> build >>>` and `# <<< build <<<` from supported shell profiles, and
+preserves Build user configuration and data. To remove that global data
+as well, explicitly add `--purge`. Purge removes `~/.build`, a relocated
+`BUILD_HOME`, `BUILD_DATA_DIR` or `BUILD_CONFIG_DIR` (only when Build-named;
+broader directories and anything resolving to your home directory are left
+alone, with a warning), the `build` directories under the XDG data, config and state
+roots (set or default), and on macOS `~/Library/Application Support/Build`
+(sandbox profiles), and it unregisters git worktrees stored there from the
+repositories they belong to. A directory is removed only if it holds files
+Build writes (`install.json`, `build.config.jsonc`, `user-preferences.json`,
+`machine-id`, `processes.json`, `telemetry`, or `sandbox-profiles`, directly or
+in its `config`, `data` or `state` subfolder); any other directory, such as a
+SwiftPM `.build` folder, is left in place with a message naming it. Because those directories can contain provider
+credentials, `.env` files, extensions, configuration, and telemetry, purge lists
+them and asks for confirmation; add installer flag `--yes` only for intentional
+automation. Before asking, purge counts the Build run and session worktrees
+stored there and names any with uncommitted or untracked changes, which are lost:
+
+```bash
+npx --yes @ebrindley/build-install -- --uninstall --purge
+```
+
+Project-local `.build-project/` directories are not removed. The bundled `install.sh`
+also accepts `--uninstall` and `--uninstall --purge` directly.
+
+If the bootstrap package is unavailable, uninstall the package directly with
+`npm uninstall -g @ebrindley/build`; remove only the guarded PATH block
+manually if an earlier installer added it.
+
+A plain `npm uninstall -g @ebrindley/build` removes only the package. npm runs
+no uninstall steps for it, so these stay on disk:
+
+- `~/.build`: user configuration, provider settings, project data, state and
+  telemetry (about 13 MB in one observed install).
+- Preserved run worktrees, which live in Build's per-project data directory
+  (under `~/.build` in the observed Linux install) unless `BUILD_WORKTREE_BASE`
+  points elsewhere. They stay registered in the repository they were created
+  from, together with their `build/*` branches.
+- The `/.build-project/...` lines Build added to each repository's
+  `.git/info/exclude`, and each repository's own `.build-project/` directory.
+
+To keep any run result you still want, apply or copy it out first (for example
+`build run apply <taskId>`). Then, in each repository where you used Build,
+run `build cleanup worktrees` before uninstalling. It previews by default;
+`--execute` removes the eligible worktrees. It keeps worktrees that are dirty or
+newer than the retention age (`--show-preserved` lists the dirty ones), so
+review the preview rather than assuming everything goes. `cleanup worktrees`
+leaves branches, `~/.build` and the exclude lines alone; remove those yourself
+(`build cleanup branches` covers the local `build/*` branches) if you want
+them gone. This does not promise a complete removal.
+
+## Troubleshooting
+
+### `Command not found: build`
+
+The npm global bin is not on PATH. Re-run the installer interactively so it
+can offer to update your shell rc, or add it manually:
+
+```bash
+echo 'export PATH="'"$(npm config get prefix)"'/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### `build` runs the wrong tool
+
+An unrelated npm package named `build` (a linter/formatter installer, last
+published 2021) also claims the `build` binary. If both are installed
+globally, whichever was installed last owns the command. Check with
+`build --version` (this package reports a Build CLI version) and remove the
+other tool with `npm uninstall -g build` if you do not use it.
+
+### `Permission denied` during `npm install`
+
+Do not use sudo. Activate Node 24 or 26 first. If you are not using nvm and its npm
+prefix is still not writable, configure a persistent user-owned prefix:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+If you use nvm, activate Node 24 or 26 first and use nvm's writable prefix instead of
+setting `prefix` in `.npmrc`; persistent custom prefixes conflict with nvm.
+
+Or pass `--install-dir <dir>` to the installer.
+
+### `@ebrindley/build@latest` Cannot Be Resolved
+
+The npm registry is unreachable or the requested version has not been
+published. The installer never silently falls back to a git ref —
+`npm install -g
+git+...` against an unbuilt ref produces a broken `build` shim, so the only
+safe paths are:
+
+1. Retry after registry access recovers or select an existing published version.
+2. For unreleased code, follow [Contributor / Git Source](#contributor--git-source).
+
+### `npx @ebrindley/build-install` Reports `No matching version found`
+
+Bootstrap versions up to 1.42.1-rc17 declare Node 24 in `engines`, so npm on
+another Node skips them and reports a missing version instead of the Node
+requirement. Check `node --version`, activate Node 24 (`nvm use 24`), and
+rerun. Later bootstrap versions resolve on Node 14.13.1 and later and print
+the supported Node majors themselves.
+
+### Git Auth Failure
+
+For a private repository, the script download and source fetch are separate
+requests. If `gh api` succeeds but Git cannot resolve/fetch the ref, follow
+[Private GitHub access](#private-github-access). In a fresh HOME, configure
+Git's helper as well as making gh credentials available. A package-only
+install from public npm does not need GitHub authentication.
+
+### `better-sqlite3` Load Error
+
+better-sqlite3 ships prebuilt binaries and needs no install script, so it works
+under npm 12's default of blocking dependency install scripts. If it fails to
+load, confirm Node 24 or 26 is active and reinstall:
+
+```bash
+npm install -g @ebrindley/build
+# or reinstall via the pinned official installer, or as advanced recovery:
+npm uninstall -g @ebrindley/build
+npm install -g @ebrindley/build --force
+```
+
+## Release Verification
+
+Release automation validates the package before and after candidate publishing:
+
+- `npm run verify:dist` (built artifact + `package.json#files` contract)
+- `npm run test:installer`
+- `npm run release:pack-smoke` (tarball manifest + temp-prefix install smoke)
+- `npm run release:artifacts`
+- `npm publish <tarball> --access public --tag rc` for `-rcN` versions through npm trusted publishing
+- exact-version registry install and CLI identity canary
+- draft GitHub release with the npm tarball, `SHA256SUMS`, release manifest,
+  and generated Homebrew formula
+- promotion of both packages to npm `latest` and of the GitHub release to Latest
+
+At a release-candidate checkpoint, tag the reviewed merge commit as
+`v1.42.0-rcN`. The workflow publishes that immutable version to `rc`, verifies
+it from the registry, and only then moves npm `latest` and publishes the GitHub
+release as Latest. Increment `rcN` for fixes. Ordinary commits
+do not publish npm packages. A Git-source install of `main` does pick up new
+commits without a release tag.
+The first package creation is a one-time local, 2FA-authenticated bootstrap;
+subsequent releases use the trusted-publisher entry for this repository and
+workflow. Provenance can be re-enabled after the source repository is public.
+For local release and operator checks, see [scripts/OPERATOR.md](https://github.com/ebrindley/build/blob/main/scripts/OPERATOR.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ed Brindley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.