@runfile/cli 0.47.0 → 1.0.1

package/README.md

@@ -1,835 +1,807 @@
 # Runfile
 
-[Quick start](#quick-start) · [Why Runfile?](#why-runfile) · [Features](#what-makes-it-different) · [VS Code](#vs-code-extension) · [Platforms](#platform-support) · [Docs](.github/DOCS.md)
+[Quick start](#quick-start) · [Examples](#what-a-runfile-looks-like) · [Language](#the-language) · [Properties](#properties) · [Commands](#commands) · [Editors](#editor-support)
 
-**One JSON file. One binary. Every OS. Every shell.**
+**One directory. One binary. Every OS.**
 
-A modern command runner that replaces Makefiles, shell scripts, and `npm run` — without the platform headaches.
+A command runner that replaces Makefiles, shell scripts and `npm run` — without the platform headaches.
 
 ```bash
-$ run dev --port=4000
-```
-
-```jsonc
-{
-  "$schema": "https://github.com/JoaaoVerona/runfile/releases/latest/download/v0.schema.json",
-  "targets": {
-    "dev": {
-      "description": "Starts the dev server",
-      "commands": "vite",
-      "env": { "PORT": "{{ ARG.port ? '3000' }}" }
-    },
-    "build": {
-      "description": "Type-checks and builds in parallel",
-      "commands": [
-        "@type-check",
-        "vite build",
-        {
-          "if": "{{ RUN.os == 'windows' && FLAG.wsl }}",
-          "then": "wsl --shell-type login -- vite build"
-        }
-      ],
-      "envFiles": [".env", ".env.{{ ARG.env ? 'development' }}"],
-      "parallel": true
-    },
-    "type-check": {
-      "description": "Type-checks source code",
-      "commands": "tsc --noEmit"
-    }
-  }
-}
+run dev --port=4000
 ```
 
----
+Your project's tasks live in a `runfiles/` directory, **one target per file**:
 
-## Quick start
+```
+runfiles/
+  _shared.run          settings every target here inherits
+  dev.run              → run dev
+  build.run            → run build
+  check.run            → run check
+  api/deploy.run       → run api:deploy
+web/runfiles/build.run → run web:build
+```
+
+A target is a file, its name is its path, and its first comment block is its description. There is no central
+file to merge, so two people adding a task never conflict.
 
-**1. Install:**
+```sh
+# runfiles/dev.run
+# Start the dev server
 
-npm:
+.env-file = ".env.local"
+.env.PORT = ARG.port ? "3000"
+
+$ vite
+```
 
 ```bash
-npm install -g @runfile/cli
+$ run :list
+  build    Type-check and build
+  check    Non-mutating gate
+  dev      Start the dev server
 ```
 
-Linux / macOS:
+## Quick start
 
 ```bash
 curl -fsSL https://github.com/JoaaoVerona/runfile/releases/latest/download/install.sh | sh
+run :init             # creates runfiles/ with an example
+run :list             # every target, with descriptions
+run <target> --help   # what one target does, and what it reads
+```
+
+```bash
+run build --env=prod      # an argument for the target
+run --dry-run build       # print what would run, without running it
+run :completions install bash   # tab-completion (or zsh, fish, powershell)
 ```
 
-Windows (via PowerShell):
+Runner flags go **before** the target name; everything after it belongs to the target. `run build --dry-run`
+passes `--dry-run` to `build` as `FLAG.dry-run` and runs it for real — so the position is the whole meaning.
+`run` warns when a target is handed a flag it never reads, which is what catches that.
+
+In CI, the setup action installs `run` and puts it on PATH, so every step after it is a target name:
 
-```powershell
-iwr https://github.com/JoaaoVerona/runfile/releases/latest/download/install.ps1 | iex
+```yaml
+- name: Setup Runfile
+  uses: JoaaoVerona/runfile/.github/actions/setup@v1
+
+- run: run check
+- run: run test
 ```
 
-**2. Generate a starter `Runfile.json`** in your project root:
+`@v1` is the major alias, moved to each release as it ships — so a fix arrives without editing every
+workflow, and a new major never arrives unannounced. Pin `@v1.0.0` instead to hold one exact version.
 
-```bash
-$ run :init
+## What a runfile looks like
+
+These are complete files. Nothing is elided.
+
+### One command that works on three operating systems
+
+`match` on `RUN.os` instead of shipping three scripts and a wrapper.
+
+```sh
+# runfiles/setup/system.run
+# Install the OS-level build prerequisites
+
+match RUN.os
+	case "linux"
+		$ sudo apt-get update
+		$ sudo apt-get install -y build-essential libssl-dev pkg-config
+	case "mac"
+		$ xcode-select --install || true
+		$ brew install openssl pkg-config
+	default
+		print("No system setup for {{ RUN.os }} — see docs/prerequisites.md")
+end
 ```
 
-**3. List and run targets:**
+### A gate that names the file that failed
 
-```bash
-$ run :list
-$ run build
-$ run test --release
-$ run dev --port=4000
+The loop is the language's, so a failure reports the one command that broke rather than the whole script.
+
+```sh
+# runfiles/check.run
+# Non-mutating gate: every compose file is valid
+
+for compose in glob("**/docker-compose.yml")
+	$ docker compose -f {{ compose }} config -q
+end
+
+print("check: every docker-compose.yml is valid")
 ```
 
-**4. Add tab completion** (optional):
+```
+[runfile] error: `docker compose -f observability/loki/docker-compose.yml config -q` exited with status 1
+```
 
-```bash
-$ run :completions install bash # or zsh, fish, powershell
+### Waiting for something to come up
+
+`retry` replaces the `until … do sleep … done` loop, and counts the attempts for you.
+
+```sh
+# runfiles/db/wait.run
+# Block until Postgres answers, then load the seed data
+
+retry 120 every 1
+	$ docker exec db pg_isready -U app -h 127.0.0.1
+else
+	error("the database never became ready")
+end
+
+$ docker exec -i db psql -U app < seed.sql
 ```
 
-**5. Keep it up to date:**
+### Doing several things at once
 
-```bash
-$ run :update                     # update to the latest release in place
-$ run :update --version v0.19.0   # or pin a specific release tag
+`.parallel` on a `for` fans out its iterations, and labels every line so you can tell them apart.
+
+It is block-scoped, so **where it sits is what it covers**: inside the loop it parallelises the iterations and
+nothing else, and at the top of the file it would cover every command in the target.
+
+```sh
+# runfiles/pull.run
+# Pull every service image
+
+for compose in glob("**/docker-compose.yml")
+	.parallel
+	.ignore-errors
+
+	$ docker compose -f {{ compose }} pull
+end
+```
+
+```
+[docker] api      Pulling
+[docker] web      Pulling
+[docker] postgres Pull complete
 ```
 
-`:update` re-runs the install script for your platform, replacing the binary where it already lives. npm-managed
-installs are handled too: on Linux/macOS `:update` runs `npm install -g @runfile/cli@latest` for you; on Windows it
-prints that command to run from a fresh shell (npm can't overwrite the running `run.exe` there).
+### JSON without the backslashes
 
----
+`json … end` is a block of JSON as a value. An interpolation inside becomes **one JSON value** — quoted and
+escaped if it is a string, an array if it is a list — so nothing is escaped by hand.
 
-## VS Code extension
+```sh
+# runfiles/bucket/policy.run
+# Apply the storage policy to a bucket
 
-Every release ships a VS Code extension that puts your targets in the editor — no `tasks.json` to generate or keep
-in sync. It runs `run :generate task-descriptors` and turns the result into real VS Code tasks plus a
-**Runfile → Targets** sidebar, complete with namespace folders and a **Globals** bucket for machine-wide targets.
+let bucket = one_of(ARG.bucket, "app-uploads", "app-backups")
 
-**Install** — download `runfile-vscode-<version>.vsix` from the
-[latest release](https://github.com/JoaaoVerona/runfile/releases/latest), then:
+let policy = json
+	{
+		"Version": "2012-10-17",
+		"Statement": [
+			{
+				"Effect": "Allow",
+				"Action": [
+					"s3:PutObject",
+					"s3:GetObject"
+				],
+				"Resource": {{ concat("arn:aws:s3:::", bucket, "/*") }},
+				"MaxKeys": {{ number(ARG.limit ? "1000") }}
+			}
+		]
+	}
+end
 
-```bash
-code --install-extension runfile-vscode-<version>.vsix
-```
-
-(or, in VS Code: **Extensions → … → Install from VSIX…**)
-
-Targets then show up in **Terminal → Run Task…** and in the Runfile sidebar. Every task is invoked with
-`--stdin-args`, so targets that need input prompt for it right in the task terminal. Nothing is written to your
-repository.
-
-The source lives in [`editors/vscode`](editors/vscode) — see its [README](editors/vscode/README.md) for settings,
-commands, and how the sidebar groups targets.
-
----
-
-## Why Runfile?
-
-Other runners assume one platform and one shell. Runfile assumes **none**.
-
-Sorted from where Runfile is most differentiated to where it lags behind.
-
-| Feature                                                             | Runfile | Make | Just | Taskfile |
-|---------------------------------------------------------------------|:-------:|:----:|:----:|:--------:|
-| Encrypted env vars, built-in (AES-256-GCM)                          |    ✅    |  ❌   |  ❌   |    ❌     |
-| MCP server (AI agent integration)                                   |    ✅    |  ❌   |  ❌   |    ❌     |
-| `when:` blocks for success/failure/always cleanup                   |    ✅    |  ❌   |  ❌   |    ❌     |
-| Inline OS / shell / cwd / paths / debug branching via `{{ RUN.* }}` |    ✅    |  ❌   |  ❌   |    ❌     |
-| Detached background execution                                       |    ✅    |  ❌   |  ❌   |    ❌     |
-| IDE task generation (VS Code / Zed / JetBrains)                     |    ✅    |  ❌   |  ❌   |    ❌     |
-| Migrate from `package.json` / `Makefile`                            |    ✅    |  ❌   |  ❌   |    ❌     |
-| Force-kill process tree on SIGINT (GUI apps)                        |    ✅    |  ❌   |  ❌   |    ❌     |
-| Stdio log tailers (`extendStdio`)                                   |    ✅    |  ❌   |  ❌   |    ❌     |
-| First-class PowerShell / cmd.exe                                    |    ✅    |  ❌   |  ✅   |    ❌     |
-| Fish shell support                                                  |    ✅    |  ❌   |  ✅   |    ❌     |
-| Per-target shell override                                           |    ✅    |  ❌   |  ✅   |    ❌     |
-| Strict parsing (typos are errors)                                   |    ✅    |  ❌   |  ✅   |    ❌     |
-| Argument substitution with chained fallbacks                        |    ✅    |  ❌   |  ✅   |    ❌     |
-| JSON Schema autocomplete in editors                                 |    ✅    |  ❌   |  ❌   |    ✅     |
-| Watch mode, built-in                                                |    ✅    |  ❌   |  ❌   |    ✅     |
-| Output grouping / prefixing in parallel mode                        |    ✅    |  ❌   |  ❌   |    ✅     |
-| Native Windows (no WSL / msys2 needed)                              |    ✅    |  ❌   |  ✅   |    ✅     |
-| Shell completions                                                   |    ✅    |  ❌   |  ✅   |    ✅     |
-| Private / internal targets (`_name`)                                |    ✅    |  ❌   |  ✅   |    ✅     |
-| Built-in string functions (upper, replace, trim, regex, base64, …)  |    ✅    |  ❌   |  ✅   |    ✅     |
-| Parallel execution                                                  |    ✅    |  ✅   |  ❌   |    ✅     |
-| Single static binary                                                |    ✅    |  ✅   |  ✅   |    ✅     |
-| Pattern rules (`%.o: %.c`)                                          |    ❌    |  ✅   |  ❌   |    ❌     |
-| Preconditions / status checks                                       |    ❌    |  ❌   |  ❌   |    ✅     |
-| Incremental builds (sources / timestamps / checksums)               |    ❌    |  ✅   |  ❌   |    ✅     |
-
----
-
-## What makes it different
-
-#### Cross-shell, not just cross-platform
-
-Auto-detects the shell, or pin one per target. The same Runfile works for a teammate using `bash` on Linux and another
-using PowerShell on Windows.
-
-```jsonc
-{
-  "targets": {
-    "ps":   { "commands": ["Write-Host 'hi'"], "forceShell": "powershell" },
-    "bash": { "commands": ["echo $BASH_VERSION"], "forceShell": "bash" }
-  }
-}
+run _aws -- s3api put-bucket-policy --bucket {{ bucket }} --policy {{ policy }}
 ```
 
-#### Encrypted env vars, baked in
+`run :format` lays the block out, and a missing brace is underlined in your editor as you type — not reported
+by the far end an hour later.
 
-AES-256-GCM secrets you can commit to git. Auto-decrypted at runtime, never written to disk in plaintext. No external
-tool, no wrapper.
+### Any language you have installed
 
-```bash
-$ run :env init .env.production
-$ run :env set .env.production DB_PASS "s3cr3t"   # auto-encrypted
-$ run :env set .env.production DB_PASS            # omit value → read from stdin (no shell history, no escaping)
+`exec <command>` runs that command with the block as its **stdin**, so a target can be a Python script, a Node
+script, a SQL file — whatever is already on the machine. The body is that command's language, not this one.
+
+```sh
+# runfiles/i18n/check.run
+# Check that every translation catalogue has the same keys as the reference
+
+.env.LOCALES = "src/locales"
+
+exec python3
+	import json, os, pathlib, sys
+
+	files = sorted(pathlib.Path(os.environ["LOCALES"]).glob("*.json"))
+	catalogues = {f.stem: set(json.loads(f.read_text())) for f in files}
+	reference = catalogues.pop("en")
+
+	for name, keys in catalogues.items():
+		missing = reference - keys
+		if missing:
+			sys.exit(f"{name}: missing {', '.join(sorted(missing))}")
+
+	print(f"i18n: {len(files)} catalogues agree on {len(reference)} keys")
+end
 ```
 
-```bash
-RUNFILE_ENCRYPTION_PUBLIC_KEY=9f86d081...
-DB_PASS=encrypted:BASE64_CIPHERTEXT...
+```sh
+# runfiles/deps/list.run
+# Print the first few runtime dependencies
+
+.env.LIMIT = ARG.limit ? "10"
+
+exec node
+	const { readFileSync } = require("node:fs")
+
+	const pkg = JSON.parse(readFileSync("package.json", "utf8"))
+	const deps = Object.keys(pkg.dependencies ?? {})
+
+	for (const name of deps.slice(0, Number(process.env.LIMIT))) {
+		console.log(`  ${name}`)
+	}
+end
 ```
 
-You can also use Runfile as a drop-in `dotenvx`/`dotenv` replacement to inject env vars (encrypted or plaintext) into
-any command — no Runfile needed:
+```sh
+# runfiles/db/report.run
+# Row counts for the tables that matter
 
-```bash
-$ run :env inject .env -- node app.js                     # one file
-$ run :env inject .env .env.local -- pnpm dev             # multiple files, last wins; parent env always wins
-$ run :env inject .env.production -- ./deploy.sh          # encrypted values auto-decrypted
+exec psql --quiet {{ ENV.DATABASE_URL }}
+	select 'accounts' as table, count(*) from accounts
+	union all
+	select 'orders', count(*) from orders
+	order by 1;
+end
 ```
 
-In CI, the file path can be supplied via `RUNFILE_ENV_FILE_TARGET` (set automatically by the
-[setup action's `env-file-source` input](.github/actions/setup/action.yml) for open-source
-repos that keep their encrypted `.env` in a GitHub secret):
+In value position it captures what the command printed, so another language can answer a question this one
+then acts on:
 
-```bash
-$ run :env inject -- node app.js                          # uses $RUNFILE_ENV_FILE_TARGET
+```sh
+# runfiles/coverage/gate.run
+# Fail if line coverage dropped below the floor
+
+let percent = exec python3
+	import pathlib, re
+
+	text = pathlib.Path("lcov.info").read_text()
+	hit = len(re.findall(r"^DA:\d+,[1-9]", text, re.M))
+	total = len(re.findall(r"^DA:", text, re.M))
+
+	print(round(100 * hit / total))
+end
+
+if number(percent) < 85
+	error("coverage is {{ percent }}%, below the 85% floor")
+end
 ```
 
-#### Powerful argument substitution
+One thing to know: the body **is** the command's stdin, so a script cannot also read data from stdin — give it
+what it needs through `.env`, a file, or the command's own arguments.
+
+An interpolation inside the body arrives **as itself**, unquoted, when the command is not a shell — shell
+quoting is the wrong quoting for anybody else's language, so quote it the way that language wants. A shell
+body still self-quotes, and `$ cp {{ src }} {{ dst }}` is as safe as it ever was.
 
-Positional, named, flags, env vars, and runtime context (`{{ RUN.os }}` / `{{ RUN.arch }}` / `{{ RUN.shell }}` /
-`{{ RUN.cwd }}` / `{{ RUN.file }}` / `{{ RUN.parent }}`) — with chained fallbacks and required values. The
-`{{ ... }}` syntax avoids collisions with shell `$(...)` command substitution.
+### Secrets that never touch the disk
 
-The source prefixes are `{{ ARG.<name> }}` (named arg), `{{ ENV.<name> }}`, `{{ FLAG.<name> }}`,
-`{{ VAR.<name> }}`, and `{{ RUN.<key> }}`. Bare `{{ ARGS }}` expands to **all** positional arguments.
+```sh
+# runfiles/deploy.run
+# Deploy to production
 
-```jsonc
-"PORT": "{{ ARG.port ? ENV.PORT ? '3000' }}",
-"OPTS": "{{ FLAG.release ? '--release' : }} {{ FLAG.verbose ? '-v' : }}",
-"CARGO_TARGET_DIR": "target-{{ RUN.os }}",
-// Inline OS/shell branches — the boolean DSL goes inside a single `{{ ... }}` block:
-{ "if": "{{ RUN.os == 'windows' }}", "then": ["del /S /Q build"], "else": ["rm -rf build"] },
-// User-supplied flags branch through `{{ FLAG.x }}` (resolves to "true" / "false"):
-{ "if": "{{ FLAG.debug }}", "then": ["./tool --verbose"], "else": ["./tool"] },
-// workingDirectory is a free-form path (defaults to {{ RUN.parent }}):
-"workingDirectory": "{{ ARG.workdir ? RUN.cwd }}"
+.env-file = ".env.production"
+.env.GOOGLE_APPLICATION_CREDENTIALS = temp_file(base64_decode(ENV.SERVICE_ACCOUNT_B64), "json")
+
+confirm("Deploy to production?")
+$ terraform apply -auto-approve
 ```
 
-Strict format: exactly one space after `{{` and before `}}`, exactly one space around `?` and `:` operators.
-**String literals must be wrapped in single quotes** — `'production'`, not `production`. Source references
-(`ARG.x`, `VAR.x`, etc.) and function calls remain bare. Use `\{{` / `\}}` to emit a literal `{{` / `}}` in
-your output.
+The temp file is deleted when the run ends, however it ends — including a failure half-way, which is exactly
+when a decoded credential must not be left behind.
+
+### A pre-commit hook
 
-#### Boolean conditions inside substitutions
+```sh
+# runfiles/precommit.run
+# Format staged files and re-stage them
 
-A substitution body containing `==`, `!=`, `&&`, `||`, or unary `!` at top level is evaluated as a boolean
-expression — the result is the string `"true"` or `"false"`. This is what powers the new `if`-block syntax,
-but you can use it anywhere:
+let staged = $ git diff --cached --name-only --diff-filter=ACMR -- "*.rs"
+let files = lines(staged)
 
-```jsonc
-"commands": [
-  // Branch on a CLI flag — `if` checks if the substitution resolves to the literal "true":
-  { "if": "{{ ARG.env == 'production' }}",
-    "then": ["./deploy-prod.sh"],
-    "else": ["./deploy-staging.sh"] },
+if length(files) > 0
+	$ rustfmt {{ files }}
+	$ git add {{ files }}
+end
+```
 
-  // Compose AND/OR/NOT freely:
-  { "if": "{{ ARG.env != 'development' && ARG.env != 'production' }}",
-    "then": ["./deploy-staging.sh"] },
+`files` is a list, so `{{ files }}` becomes one argument per file — spaces in names and all.
 
-  // Invert any boolean-returning value with unary `!` — including the
-  // comparison helpers (`less_than`, `is_number`, …) and `contains` etc.:
-  { "if": "{{ !is_number(ARG.port) }}",
-    "then": ["echo 'port must be a number' && exit 1"] },
+### Re-running on change
 
-  // FLAG.x works as a bare boolean inside DSL — no `== 'true'` needed:
-  { "if": "{{ RUN.os == 'windows' && FLAG.wsl }}",
-    "then": "wsl --shell-type login -- vite build" },
+```sh
+# runfiles/watch.run
+# Recompile whenever a source file changes
 
-  // Inline in a command — useful for passing booleans to other tools:
-  "my-command --resolve {{ ARG.env == 'production' }}"
-]
+.watch = "src/**/*.rs"
+.watch = "!src/generated/**"
+
+run build
 ```
 
-**Strict boolean rule.** Any value used as a bare boolean — both inside the DSL Truthy check (e.g. `&& FLAG.x`,
-`!ARG.y`) and as the entire `if` condition — must resolve to exactly one of:
-
-- `"true"` → truthy (the `then` branch runs / left arm of `&&` continues)
-- `"false"` → falsy
-- `""` (empty) → falsy
-
-Anything else (`"True"`, `"1"`, `"yes"`, `"hello"`, etc.) errors out with a clear message pointing you toward
-the explicit comparison form. So `if: "{{ ARG.x }}"` and `{{ ARG.x && ... }}` only work when `ARG.x` is
-exactly `"true"` / `"false"` / empty — for any other check, use a comparison: `{{ ARG.x == 'yes' }}`.
-
-Comparisons (`==` / `!=`) operate on raw strings — *those* don't have the boolean restriction, so
-`{{ ARG.env == 'staging' }}` works for any value of `ARG.env`.
-
-#### Functions: transform values inline
-
-Wrap any source or chain expression in a function call. Functions resolve at substitution time, can be nested,
-and work as full substitution bodies *or* as chain segments:
-
-```jsonc
-"commands": [
-  // Built-ins:
-  //   case      : to_upper, to_lower, capitalize
-  //   trim      : trim, trim_start, trim_end
-  //   inspect   : length, starts_with, ends_with, contains, substring
-  //   transform : escape, repeat, replace_all, remove_all
-  //   regex     : regex_replace, regex_remove, regex_matches, regex_capture, regex_capture_all
-  //   build     : concat, join
-  //   split     : nth, first, last, count_parts
-  //   path      : basename, dirname, extname, stem, join_path
-  //   math      : add, subtract, multiply, divide, modulo, power, min, max, abs, round, floor, ceil
-  //   compare   : less_than, less_than_or_equal, greater_than, greater_than_or_equal, is_number
-  //   validate  : one_of
-  //   encoding  : base64_encode, base64_decode, url_encode, url_decode
-  //   hashing   : sha256, md5
-  //   ids/time  : uuid, now
-  //   files     : read_file, write_file, file_exists, temp_file, temp_dir
-  //   json      : json_get, json_set
-  //   control   : try, error
-  //   shell     : shell_quote, capture
-  //   variables : define
-  //   cwd       : set_cwd
-  "echo deploying-{{ to_upper(ARG.env) }}",
-  "curl -H \"X-Auth: {{ base64_encode(ENV.TOKEN) }}\" ...",
-  "echo {{ concat('hello-', ARG.name, '-2026') }}",
-  "echo {{ join(' AND ', 'flag-1', 'flag-2', ARG.extra) }}",
-  // Tokenise-and-rejoin-style transforms via replace_all:
-  "go test {{ replace_all(ARG.flags, ' ', ' -tag=') }}",
-  // Strip every match of a regex (here: collapse whitespace runs to a single space):
-  "echo {{ regex_replace(ARG.text, '\\s+', ' ') }}",
-  // Pull a capture group out of the first regex match — no `(?s)^.*X(...)X.*$`
-  // greedy-replace trick needed. Group 0 is the whole match; group N is the
-  // N-th `(...)`. Out-of-bounds returns "" (same convention as `nth`).
-  "echo version={{ regex_capture(read_file('app/build.gradle.kts'), 'versionName = \"([^\"]+)\"', '1') }}",
-  // Pull group N out of EVERY match and join with a separator (the "all" variant
-  // of regex_capture). Here: every quoted dependency name, comma-separated.
-  "echo deps={{ regex_capture_all(read_file('deps.txt'), 'name = \"([^\"]+)\"', '1', ',') }}",
-  // Split-by-separator scalar accessors — string in, string out, no list type:
-  // basename idiom (last segment after `/`); empty string when input ends in `/`.
-  "echo basename={{ last(ARG.path, '/') }}",
-  // Pull out the N-th comma-separated field; out-of-bounds returns "".
-  "echo target={{ nth(ARG.csv, ',', '1') }}",
-  // Pair `count_parts` with `nth` to bound-check before indexing:
-  // "if": "{{ count_parts(ARG.csv, ',') == '3' }}"
-  // Boolean-returning helpers are valid DSL `Truthy` values — use them in `if`:
-  // "if": "{{ starts_with(ARG.path, '/usr') }}"
-  // "if": "{{ regex_matches(ARG.tag, '^v[0-9]+\\.[0-9]+$') }}"
-
-  // Safely inline arbitrary content (newlines, quotes, JSON) as a CLI arg —
-  // `shell_quote` picks the right quoting for the active shell:
-  "some-tool --json {{ shell_quote(base64_decode(ENV.SECRET_BASE64)) }}",
-
-  // Slurp shell-command stdout straight into a substitution. `capture` runs
-  // the command through the platform's default shell (sh / cmd) and trims
-  // the trailing newline. Results are memoized per-target so the same
-  // capture in multiple commands runs once. `--dry-run` substitutes a
-  // readable placeholder instead of spawning the shell.
-  "echo built-at={{ capture('date -u +%Y-%m-%dT%H:%M:%SZ') }}",
-  "{{ define(sha, capture('git rev-parse HEAD')) }}",
-
-  // Arithmetic — variadic (2+ args), coerces strings to numbers, errors on
-  // non-numeric input. The result is formatted as an integer when whole and
-  // as a decimal otherwise (so `add('5', '3')` → "8", `add('5', '1.1')` →
-  // "6.1"). Divide-by-zero errors out.
-  "echo next-build={{ add(VAR.versionCode, '1') }}",
-  "echo half={{ divide(VAR.total, '2') }}",
-  // …plus modulo, power, min, max, abs, round, floor, ceil:
-  "echo shard={{ modulo(ARG.id, '8') }} clamped={{ max('0', min('100', ARG.pct)) }}",
-
-  // Path helpers (std::path semantics). basename/dirname/extname/stem/join_path:
-  "echo name={{ basename(ARG.file) }} ext={{ extname(ARG.file) }}",
-  "cp {{ ARG.file }} {{ join_path(ARG.outdir, basename(ARG.file)) }}",
-
-  // Substring (char-indexed; 3rd arg = length, optional → to end). Short SHA:
-  "echo short={{ substring(capture('git rev-parse HEAD'), '0', '7') }}",
-
-  // Current UTC time. Formats: unix-timestamp, unix-millis, iso, iso-date,
-  // iso-time, rfc3339, year/month/day/hour/minute/second.
-  "echo built-at={{ now('iso') }} tag=build-{{ now('unix-timestamp') }}",
-
-  // UUID (v4-shaped) for unique temp / cache names. `--dry-run` → `<uuid>`.
-  "echo tmp=/tmp/job-{{ uuid() }}",
-
-  // URL percent-encode / decode (space → %20; symmetric round-trip):
-  "curl 'https://api/search?q={{ url_encode(ARG.query) }}'",
-
-  // Numeric comparisons — coerce both args to numbers (same rules as the
-  // arithmetic family, so non-numeric input errors) and return "true"/"false",
-  // so they work as DSL `Truthy` values in `if` conditions:
-  // "if": "{{ greater_than(VAR.count, '50') }}"
-  // "if": "{{ less_than_or_equal(ARG.retries, '3') }}"
-  // `is_number` tests whether a value parses as a (finite) number — it returns
-  // "false" instead of erroring on non-numeric input:
-  // "if": "{{ is_number(ARG.port) }}"
-
-  // Validate a value against a fixed allow-list. Returns the value on
-  // match; lists every valid option in the error on mismatch. Collapses
-  // the four-case `match { major: define(part, 'major'), ... }` boilerplate.
-  "{{ define(part, one_of(ARGS, 'major', 'minor', 'patch', 'build')) }}",
-
-  // Cache keys / content fingerprints. `sha256` for security-sensitive use,
-  // `md5` for cheap fingerprinting (NOT cryptographically secure).
-  "echo cache-key={{ sha256(read_file('package-lock.json')) }}",
-
-  // Branch on file presence without forking a shell. `file_exists` returns
-  // the literal "true" / "false", so it doubles as a DSL truthy value.
-  // "if": "{{ file_exists('.env.local') }}"
-
-  // Read a file inline — relative paths anchor to the Runfile directory.
-  // Use `try(...)` to recover from missing files.
-  "echo version={{ try(read_file('VERSION')) ? '0.0.0-dev' }}",
-
-  // Write a file straight from a substitution — pairs with `read_file` for
-  // read-modify-write pipelines (version bumps, config edits, …). Returns
-  // an empty string, so a line containing only this call is dropped silently
-  // (same convention as `define`). Goes through Rust's `std::fs::write`, so
-  // it sidesteps the shell entirely — safe for large content, content with
-  // quotes, embedded newlines, anything that would break a
-  // `printf > file`-style redirect on Windows. `--dry-run` skips the write.
-  "{{ write_file('build.gradle.kts', regex_replace(read_file('build.gradle.kts'), 'versionCode = [0-9]+', 'versionCode = 43')) }}",
-
-  // Create a temp file / dir in the OS temp directory, auto-deleted when the
-  // CLI exits. `temp_file([content], [extension])` writes `content` (if given)
-  // and appends `.<extension>` (leading dot optional); `temp_dir()` makes an
-  // empty directory (removed recursively). `--dry-run` → `<temp_file>` /
-  // `<temp_dir>` placeholders, nothing created. Capture the path once with
-  // `define` and reuse it:
-  "{{ define(cfg, temp_file('{\"env\":\"prod\"}', 'json')) }}",
-  "tool --config {{ VAR.cfg }}",
-  "{{ define(work, temp_dir()) }}",
-  "git clone --depth 1 $REPO {{ VAR.work }} && build {{ VAR.work }}",
-
-  // Pull values out of arbitrary JSON without `jq` (works on every shell):
-  "echo db_host={{ json_get(read_file('config.json'), 'database.host') }}",
-
-  // Modify a JSON document in place (returns the new compact JSON):
-  "echo {{ json_set('{\"port\":3000}', 'env', 'production') }}",
-
-  // `try(expr)` swallows inner errors. Standalone returns "" on failure;
-  // chained, the next segment runs as a fallback.
-  "echo {{ try(base64_decode(ARG.maybe_b64)) ? ARG.maybe_b64 }}",
-
-  // `error('message')` fails the current command on purpose: prints the
-  // message to stderr and marks the step failed — but the failure flows
-  // through the normal walker, so `when: failure` / `when: always` steps
-  // still run and `ignoreErrors` still suppresses it. Great for guard clauses:
-  // { "if": "{{ ARG.env == 'prod' }}", "then": ["{{ error('refusing to deploy to prod from a laptop') }}"] }
-
-  // Nested:
-  "echo {{ to_upper(to_lower(ARG.x)) }}",
-
-  // As a chain fallback:
-  "echo host={{ ARG.host ? to_lower(ENV.HOST) }}",
-
-  // Capture a value with `define(...)` and read it later via `VAR.<name>`:
-  "{{ define(sdk, ENV.SDK ? '/opt/sdk') }}",
-  "{{ VAR.sdk }}/bin/build",
-  "echo using sdk at {{ VAR.sdk }}",
-
-  // `set_cwd(path)` switches the cwd subsequent commands spawn in — like
-  // shell `cd`, but works on every shell / OS without forking. Relative
-  // paths chain (matching `cd a; cd b` → `a/b`); absolute paths replace.
-  "{{ set_cwd(ARG.subproject ? 'packages/api') }}",
-  "npm install",
-  "npm run build",
-
-  // Single-quoted strings interpolate nested {{ }} substitutions:
-  "{{ define(cmd, 'docker compose -f {{ VAR.compose }} pull') }}",
-  "{{ VAR.cmd }}"
+There is no `--watch` flag: the file already said what it wants, so `run watch` watches.
+
+## The language
+
+Line-oriented, with one rule: **the language is the default, the shell is marked.**
+
+| Line | Meaning |
+| --- | --- |
+| `# text` | A comment. The leading block is the target's description. |
+| `.name = value` | A property. |
+| `$ echo hi` | Hand this line to a shell. |
+| `exec python3` … `end` | Run a command with the block as its stdin. |
+| `json` … `end` | A block of JSON, as one value. |
+| `let x = 1` | Bind a value. `x = 2` rebinds. |
+| `if` / `else` / `end` | Branch. |
+| `for x in list` / `end` | Loop. |
+| `match` / `case` / `default` / `end` | Dispatch on a value. A label is a quoted string: `case "linux"`. |
+| `retry n [every s]` … `end` | Run the block again while it fails, up to `n` times. |
+| `do` … `end` | A block with no condition, so a property can cover a few commands. |
+| `run other-target` | Run another target, in this process. |
+| `print(…)` | Anything else is an expression, evaluated for its effect. |
+
+### Values
+
+Strings, numbers, booleans and lists — **strict, with no coercion.** `"a" + 1` is an error telling you to use
+`concat`. `"1" == 1` is false. `number(ARG.count)` is required before arithmetic. `1 / 2` is `0.5`.
+
+Lists nest as deep as you like, which beats packing several fields into one string and splitting it back out:
+
+```sh
+for volume in [
+	["prometheus-data", "65534:65534"],
+	["kvrocks-data", "999:999"],
 ]
+	$ docker run --rm -v {{ volume[0] }}:/v alpine chown -R {{ volume[1] }} /v
+end
 ```
 
-`define(name, value)` returns an empty string and stores `value` in a run-wide map; a command line that resolves
-to only whitespace (i.e. one consisting solely of a `{{ define(...) }}` call) is silently skipped instead of
-being dispatched to the shell. `define`s in a parent target are visible to `@target` children. The `name` MUST
-be a bareword identifier matching `[A-Za-z_][A-Za-z0-9_-]*` — quotes are NOT allowed on the name.
+`print` writes a line to stdout; `printf` writes exactly what you give it, with `%s`, `%d`, `%f`, `%.Nf` and
+`%%`, and no newline of its own.
 
-#### Declaring variables up front (`vars`)
+Lists are values, and every list function answers with a **new** list, so nothing changes behind another name:
 
-Instead of (or alongside) `define(...)`, you can declare variables directly on a target — or on `globals` to
-apply them to every target — and read them as `{{ VAR.<key> }}`. This mirrors `env`: each value is a `{{ ... }}`
-template resolved **after** the env is built (so it can reference `{{ ENV.* }}`), plus `{{ ARG.* }}`,
-`{{ FLAG.* }}`, `{{ RUN.* }}`, and earlier vars. If a reference has no default and isn't supplied, it errors —
-exactly like everywhere else.
+```sh
+let recent = slice(reverse(sort(tags)), 0, 5)
+let targets = without(RUN.namespaces, "docs")
 
-```jsonc
-{
-  "globals": {
-    "vars": { "appName": "myapp" }      // available to every target
-  },
-  "targets": {
-    "deploy": {
-      "env": { "REGION": "us-east-1" },
-      "vars": {
-        "region": "{{ ENV.REGION }}",     // vars resolve after env
-        "retries": "3",                    // numbers/bools are stringified
-        "tag": "{{ ARG.tag ? 'latest' }}" // chain fallbacks work
-      },
-      "commands": ["echo deploying {{ VAR.appName }} to {{ VAR.region }} as {{ VAR.tag }}"]
-    }
-  }
-}
+for pair in zip(names, owners)
+	$ chown {{ pair[1] }} /srv/{{ pair[0] }}
+end
 ```
 
-Global `vars` are merged into each target's `vars` at parse time (target keys win on conflict). Declared vars are
-**scoped per-target like `env`**: a parent's vars are visible inside an `@target` dependency, but a dependency's
-own declared vars don't leak back to the parent. A runtime `define(...)` of the same name overrides the declared
-value for the rest of the target. Var keys must match `[A-Za-z_][A-Za-z0-9_-]*`.
-
-`set_cwd(path)` is the cwd analog of `define`: returns an empty string and changes the cwd that subsequent shell
-commands in the *current target* spawn in. Behaves like shell `cd`, but works uniformly across every shell / OS
-(no forked process, no `cd` binary needed). Resolution rules:
-
-- **Absolute path** → fully replaces the current override (matches `cd /abs`).
-- **Relative path** → joins onto the existing override, or onto the target's `workingDirectory` if no override
-  has been set yet. So `set_cwd('a'); set_cwd('b')` lands subsequent commands in `<workingDirectory>/a/b`,
-  matching how `cd a; cd b` chains in a shell.
-
-`set_cwd` is **per-target**: each `@target` invocation starts with a clean override (the dispatched target sees
-its own `workingDirectory`, not the caller's `set_cwd` state). Inside `parallel: true` targets each leaf
-captures the override at the moment of its substitution, so siblings don't race on the spawn cwd. Like
-`define`, the side effect is skipped on the redacted-logging pass so log lines don't double-apply it. With
-`sameShell: true`, only the *final* `set_cwd` value applies (everything joins into one shell invocation) — use
-shell `cd` directly between leaves there if you need intermediate cwd changes.
-
-Function args are separated by `, ` (comma + exactly one space).
-
-**Quote semantics inside `{{ ... }}`:**
-
-- **Single quotes (`'...'`) — interpolated string**: surrounding quotes stripped, with any nested `{{ ... }}`
-  resolved through the regular substitution machinery. Use these for almost every literal — they handle the
-  full range of values including embedded substitutions: `concat('a, b', ARG.x)`,
-  `'/var/log/{{ RUN.os }}.log'`, `define(cmd, 'docker -f {{ VAR.compose }} pull')`.
-- **Double quotes (`"..."`) — fully literal value**: the quote characters are part of the value (so `"test"` is
-  the 6-character string `"test"`). No interpolation. Useful when the literal you want to emit really should
-  contain `"` chars.
-- **Plain barewords are rejected** — `{{ ARG.env ? development }}` is a parse-time error. Wrap in quotes.
-
-#### Conditionals and loops, no shell required
-
-Drop `if` / `for` / `match` blocks straight into your `commands` array. Conditions, loops, and value dispatch are
-evaluated by Runfile itself, so the logic works the same on every shell and platform.
-
-```jsonc
-"commands": [
-  { "if": "{{ ARG.env == 'production' }}",
-    "then": ["./deploy-prod.sh"],
-    "else": ["./deploy-staging.sh"] },
-
-  { "match": "{{ ARG.tier ? '1' }}",  // chain default; case "1" runs when --tier missing
-    "cases": {
-      "1": "flutter emulators --launch Tier_1_Android_9",
-      "2": "flutter emulators --launch Tier_2_Android_11",
-      "3": "flutter emulators --launch Tier_3_Android_14",
-      // Case keys wrapped in `/.../` are treated as regex patterns.
-      // Literal cases always win over a regex that would also match.
-      "/^v\\d+$/": "echo version-tag",
-      "/^pr-\\d+$/": "echo preview-build"
-    } },                                // unknown values error out, listing the valid cases
-
-  { "for": "service",
-    "in": ["api", "web", "worker"],
-    "parallel": true,
-    // VAR.<name>_index exposes the 0-based iteration counter.
-    "do": ["echo [{{ VAR.service_index }}] docker build -t {{ VAR.service }} services/{{ VAR.service }}"] },
-
-  { "for": "file",
-    "shell": "git diff --name-only HEAD~1",
-    "do": ["clang-format -i {{ VAR.file }}"] }
-]
+`append`, `prepend`, `concat_lists`, `sort`, `reverse`, `unique`, `slice`, `flatten`, `zip`, `index_of` and
+`without`, beside `first`, `last`, `length` and `join`.
+
+There are 78 built-in functions — strings, lists, regex, paths, JSON, hashes, time, files. Your editor lists
+them all with a description and an example; `run :list` is for targets, and the language server is for the
+language.
+
+### Where values come from
+
+| Source | From |
+| --- | --- |
+| `ARG.name` | `--name=value` |
+| `FLAG.name` | `--name` (a boolean) |
+| `ARGS` | positional arguments, as a list |
+| `ENV.NAME` | the environment |
+| `RUN.os` `RUN.arch` `RUN.cwd` `RUN.file` `RUN.parent` `RUN.namespaces` `RUN.user` | the run itself |
+
+`a ? b` means "`a`, or `b` if `a` is not there", and chains:
+
+```sh
+let port = ARG.port ? ENV.PORT ? "3000"
 ```
 
-#### Call other targets inline with `@target`
+Arguments are `--key=value`. Writing `--key value` gives you a flag and a positional, because nothing declares
+which names take values — and if you meant an argument, the error says so.
+
+**A flag a target cannot read is an error**, not a typo you find out about later. `run` knows exactly what a
+target reads by walking its parsed tree, so `--forse` stops the run and points at `--help`:
 
-Any command string starting with `@` invokes another target. Forward args with `{{ ARGS }}` or pass anything explicit.
-Each invocation runs (no dedup), inherits the parent's env, and works inside `if` / `for` blocks. Parallel parents
-fan out target calls onto worker threads.
+```bash
+$ run deploy --help
+run deploy [--env=<value>] --token=<value> [--force]
 
-Prefix with `@?target` to mark the call **optional**: if the (substituted) target doesn't exist, it's silently
-skipped instead of erroring. Useful with `for in: "namespaces"` when the dispatched target isn't defined in every
-namespace.
+  Deploy to an environment.
 
-```jsonc
-"commands": [
-  "@lint",
-  "@test --coverage",
-  "@build {{ ARGS }}",
-  { "if": "{{ RUN.os == 'windows' }}", "then": "@deploy-win", "else": "@deploy-unix" },
-  { "for": "ns", "in": "namespaces", "do": "@?{{ VAR.ns }}:adb-forward" } // skip namespaces without the target
-]
+Arguments
+  --env=<value>                 defaults to staging
+  --token=<value>               required
+  --force                       off unless passed
+
+Environment
+  DEPLOY_KEY                    required
 ```
 
-#### Readable parallel output
-
-When commands run in parallel (`"parallel": true` on a target or `for` block), each branch's stdout/stderr is
-line-buffered, prefixed with a colored bracketed label identifying the branch, and stripped of cursor-control
-escapes — so progress-bar redraws (`docker compose pull`, `cargo build`, etc.) become chronological append-only
-lines instead of corrupting each other's output. The label shows the full resolved `@target` invocation
-(`[@dev --port 5000]`) for target-call branches; for shell branches it shows the first *meaningful* part of the
-command, skipping setup like `cd`, `export` and `FOO=bar` assignments — so
-`cd ../battle-tanks-api && run api` is labelled `[run api]`, not `[cd /Users/jo]`. Labels are also guaranteed
-unique within a batch: two branches that would otherwise share a label are widened until they differ, then
-distinguished by the directory they `cd` into (`[battle-tanks-api]` vs `[battle-tanks]`), and finally by an
-ordinal suffix (`[npm run dev #1]`). They're padded to a common width so the brackets line up, and each gets one
-of six cycling colors so adjacent branches stay distinct.
-SGR colors flow through unchanged. The prefix propagates through `@target` invocations too,
-so monorepo fan-outs like `{ "for": "ns", "in": "namespaces", "do": "@{{ VAR.ns }}:dev" }` tag every nested shell
-with its branch identity. Set `RUNFILE_NO_LINE_PREFIX=1` to opt out and inherit raw stdio.
-
-```text
-[runfile] (1/3) [parallel] docker compose pull api
-[runfile] (2/3) [parallel] docker compose pull web
-[runfile] (3/3) [parallel] docker compose pull worker
-[1] Pulling api ... 50%
-[2] Pulling web ... 30%
-[3] Pulling worker ... 100%
-[1] Pulling api ... 100%
-[2] Pulling web ... 100%
-```
-
-#### Cleanup on failure / always with `when:` blocks
-
-Wrap any commands in a `when:` block to run them only after a failure, or always — interleaved with the rest of
-`commands`, no separate `before`/`after` arrays.
-
-```jsonc
-"commands": [
-  "./run-tests.sh",                                          // failure flips state
-  "./report.sh",                                             // skipped on failure (default when:success)
-  { "when": "failure", "commands": ["./post-failure.sh"] },  // runs only after a failure
-  { "when": "always",  "commands": ["@cleanup"] }            // runs every time
-]
+Nothing is declared for that — a `?` chain is what makes a value optional, and the literal it ends in is the
+default. `run --stdin-args deploy` asks for the same list, in the same order, **before anything runs**.
+
+Everything after a bare `--` is passed through untouched, flags included. That is how a wrapper forwards a
+command line it does not understand:
+
+```sh
+# runfiles/aws.run
+# The AWS CLI, in a container
+
+$ docker run --rm amazon/aws-cli {{ ARGS }}
 ```
 
-**Ctrl+C runs your cleanup too.** Pressing Ctrl+C stops the running command and skips everything still pending,
-but `when: failure` and `when: always` blocks still execute before Runfile exits (with code `130`) — so a
-container, a lock file, or a dev server started earlier gets torn down instead of leaked. The interrupt is not
-suppressible by `ignoreErrors` (that forgives a failed command, not a user asking to stop), it stops `for` loops
-from starting further iterations, and it reaches every target on the stack: an interrupted `@target` dependency
-runs its own cleanup, then its caller runs the caller's. Cleanup blocks are exempt from the abort, so their own
-steps — including a `@teardown` they delegate to — run in full. Press Ctrl+C **again** to quit immediately if a
-cleanup block is itself slow or stuck.
+```bash
+run aws -- s3api list-buckets --output json
+```
 
-#### Single-shell mode with `sameShell`
+### Interpolation quotes itself
 
-By default each step runs in its own shell process, so `cd`, exported variables, and other shell state don't carry
-over between steps. Set `"sameShell": true` to join every step into a single shell invocation — state changes
-persist for free.
+`{{ … }}` in a shell line becomes **exactly one argument** — or, for a list, one argument per item. So this is
+safe with any file name, spaces and quotes included:
 
-```jsonc
-{
-  "deploy": {
-    "sameShell": true,
-    "commands": ["cd ci-scripts/", "./ci-deploy.sh"]
-  }
-}
+```sh
+$ cp {{ ARG.src }} {{ ARG.dest }}
 ```
 
-Steps are joined with `&&` so the run stops at the first failure (or `;` / `&` when `ignoreErrors: true`). `if`,
-`for`, and `match` blocks are evaluated by Runfile and their chosen branches flow into the same joined invocation.
-`@target` calls inside the body are rejected — they have their own shell context and can't share state with the
-parent. `sameShell` also composes with `detach: true` (joined command spawns as one detached process) and is
-available on `globals` for project-wide defaults.
+**Never wrap an interpolation in shell quotes.** There is no `shell_quote` function because there is nothing
+left to quote: the substitution already did it. The same rule holds one layer up inside a `json` block, where
+an interpolation becomes one JSON value.
 
-#### Watch mode, built in
+### Asking whether a command worked
 
-Add a `watch` array to any target. No flags, no extra tooling.
+A `$` run may stand as a condition or as a `match` subject. The condition is true when the command exits 0;
+the cases are exit codes. Neither stops the target — a non-zero exit is the answer, not a failure.
 
-```jsonc
-"watch": ["src/**/*.rs", "!target/**"]
+```sh
+if $ command -v docker
+	$ docker info
+else
+	error("docker is not on PATH")
+end
+
+match $ curl -fsS https://example.com
+	case "0"
+		print("up")
+	case "22"
+		error("the endpoint answered 4xx or 5xx")
+	default
+		error("could not reach it")
+end
 ```
 
-#### Editor integrations
+`code_of($ cmd)` is the same status as a number, for when you want to keep it — and `code_of(run other)`
+scores another **target** the same way. That is how one target runs both halves of a check and gives a single
+verdict at the end, instead of stopping at the first thing that failed:
 
-Generate native tasks for **VS Code**, **Zed**, and **JetBrains** IDEs from your Runfile:
+```sh
+# runfiles/coverage.run
+# Coverage for both halves, with one verdict
 
-```bash
-$ run :generate vscode-tasks
-$ run :generate zed-tasks
-$ run :generate jetbrains-run-configurations
+let rust = code_of(run coverage:rust)
+let web = code_of(run web:coverage)
+
+run _verdict --name=Rust --code={{ rust }}
+run _verdict --name=Web --code={{ web }}
+
+if rust != 0 || web != 0
+	exit(1)
+end
 ```
 
-Each writes its editor's config to disk (`.vscode/tasks.json`, `.zed/tasks.json`, `.run/*.run.xml`),
-merging with any existing file. By default only the local Runfile's own targets are generated; two
-independent flags widen the set:
+A dispatched target is scored the way `run` itself would exit: `exit(3)` is 3, any other failure is 1, and the
+error is printed where it happened. An interrupt, or answering no to a `confirm()`, is not a status — that
+stops the caller too.
 
-- `--include-namespaces` also generates entries for targets pulled in via `includes` — namespaced
-  targets carry their `namespace:` prefixes, exactly as `run :list` shows them (e.g. `run api:build`).
-- `--include-globals` also generates entries for the global user-level Runfiles registered with
-  `run :config global-files` — the same ones `run :list` folds in. Handy when an editor integration
-  should offer your machine-wide targets (e.g. `run c`, `run backup-git`) alongside a project's own.
+### Capturing output
 
-##### Building your own integration: `task-descriptors`
+```sh
+let branch = $ git rev-parse --abbrev-ref HEAD
 
-For tooling that builds its **own** editor integration (like the
-[Runfile VS Code extension](editors/vscode) shipped with this repo), there's an editor-agnostic
-alternative that always prints to stdout and never touches disk:
+if branch != "main"
+	error("release from main, not {{ branch }}")
+end
+```
 
-```bash
-$ run :generate task-descriptors
-```
-
-It always resolves `includes` and merges registered global files (no `--include-*` flags), and emits
-a stable JSON document describing every runnable target grouped by its source file, with per-target
-provenance so a client can bucket local vs. included vs. global targets itself:
-
-```jsonc
-{
-  "formatVersion": 1,
-  "sources": [
-    {
-      "filePath": "/abs/path/Runfile.json",
-      "kind": "local",              // "local" | "included" | "global"
-      "onlyInDirectories": ["~/w"], // only on globals restricted to certain dirs
-      "targets": [
-        {
-          "name": "api:build",      // full canonical invocation name
-          "namespace": "api",       // omitted for un-namespaced targets
-          "description": "Build the API"
-        }
-      ]
-    }
-  ]
-}
+A `$` capture runs to the end of its line, so it can only be a call's **last** argument, and the `)` has to be
+the last character of the line:
+
+```sh
+let files = lines($ git diff --cached --name-only)
+
+for f in lines($ git ls-files '*.sh')
+	$ shellcheck {{ f }}
+end
 ```
 
-`onlyInDirectories` appears only on a `global` source that declared
-[`globals.onlyInDirectories`](.github/DOCS.md#onlyindirectories) — meaning it merged in only because the
-current directory is inside one of those paths. Such a source is registered machine-wide but scoped in
-practice, so clients are expected to treat it as project-local rather than truly global.
-
-Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
-`metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
-(strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
-editor extensions and CI scripts can stash arbitrary tooling-specific fields here.
-
-Every file Runfile writes honors your project's [**`.editorconfig`**](https://editorconfig.org): the
-output is formatted to match the settings that apply to each written path — the editor files above
-(`.vscode/tasks.json`, `.zed/tasks.json`, `.run/*.run.xml`) as well as the `Runfile.json` produced by
-`:init` and `:convert`. `indent_style` / `indent_size` / `tab_width` drive indentation, `end_of_line`
-sets the newline sequence, `insert_final_newline` and `trim_trailing_whitespace` are applied, and
-`charset = utf-8-bom` prepends a BOM. When no `.editorconfig` applies, the previous defaults are kept.
-
-#### Preparation targets (like `npm prepare`, but enforced)
-
-Most projects have a one-time setup step — install git hooks, pull dependencies, generate config.
-It's easy to forget, and easy to fall behind when it changes. Point `globals.prepare` at a target and
-Runfile makes it a precondition for **every** target in the file:
-
-```jsonc
-{
-  "globals": { "prepare": "@setup" },
-  "targets": {
-    "setup": { "commands": ["git config core.hooksPath .githooks", "npm ci"] },
-    "build": { "commands": ["npm run build"] },
-    "test":  { "commands": ["npm test"], "prepare": "@setup-tests" },
-    "setup-tests": { "commands": ["./scripts/seed-test-db.sh"] }
-  }
-}
+`code_of($ cmd)` and `code_of(run other)` are the same shape: run it and take the status, ignoring how it went
+— which is what `|| true` was doing.
+
+### Blocks that are not shell
+
+`$ line` is shorthand for a one-line `exec` with the default shell. Name any other command and the block
+becomes its stdin — see [Any language you have installed](#any-language-you-have-installed).
+
+```sh
+exec python3
+	import json, sys
+
+	print(json.dumps({"ok": True}))
+end
 ```
 
-Run anything before setup has run and you get a clear stop, not a confusing failure:
+### Stopping early
 
-```console
-$ run build
-Error: target "build" requires preparation steps that haven't been completed:
-  • run setup    (never run)
+`exit()` ends the run with a status; `error("…")` fails with a message; `confirm("…")` asks, and stops if the
+answer is no. Nothing catches any of them: not a `?` fallback, not `.ignore-errors`. A target may forgive a
+command that failed, but being told to stop is not that.
+
+`confirm` is a function rather than a property, so the question can depend on what is about to happen — and is
+skipped by `-y`, in CI, and under `--dry-run`, where there is nothing to approve.
+
+A line that is only a value — `exit`, `abc`, `35` — is a parse error, since it computes something and throws
+it away. Most often it is a call with the parentheses left off, and the message says so.
+
+## Properties
+
+Set at the top of the file, or inside a block where marked.
+
+| Property | Effect | In a block? |
+| --- | --- | :-: |
+| `.shell` | Which shell `$` lines use. | ✅ |
+| `.env.NAME` | Set an environment variable. | ✅ |
+| `.workdir` | Where commands run. | ✅ |
+| `.parallel` | Run this block's commands at once. On a `for`, its iterations. | ✅ |
+| `.ignore-errors` | Keep going when a command fails. | ✅ |
+| `.logging` | Announce each command on stderr before it runs. Off unless set. | ✅ |
+| `.env-file` | Load a `.env` file (encrypted values are decrypted in memory). Appends. | ✅ |
+| `.add-path` | Prepend a directory to `PATH`. Appends. | ✅ |
+| `.watch` | Re-run when matching files change. A `!` prefix excludes. | |
+| `.alias` | Another name for this target. | |
+| `.detach` | Start the commands and do not wait. | |
+| `.only-in-directories` | For the machine-wide directory: only offer these targets inside these directories. | |
+
+`.env-file` and `.add-path` **append**, so a block adds to what it inherited rather than replacing it, and a
+block's file can be named by something the body worked out — which a header property cannot do, because it
+resolves before any statement runs:
+
+```sh
+# runfiles/deploy.run
+# Deploy to an environment
+
+let env = one_of(first(ARGS), "staging", "production")
+
+if env == "production"
+	.env-file = ".env.production"
+	.add-path = "vendor/prod-tools"
+
+	confirm("Deploy to production?")
+end
+
+$ terraform apply -auto-approve
 ```
 
-Once you `run setup`, Runfile records a hash of its commands (following `@target` calls, so nested
-setups count too). Future runs pass silently — **until those commands change**, at which point the
-requirement re-triggers and everyone is prompted to re-run it. A target's own `prepare` is *additive*
-on top of the global one, so `run test` above requires both `setup` and `setup-tests`.
+**A target whose file name starts with `_` is hidden** from `run :list`, from completion and from generated
+editor tasks — and still runs when something calls it. That is the whole of it; there is no property to
+disagree with the name.
 
-Preparation is a developer-machine concern, so the gate is **skipped automatically in CI** (detected
-via `CI`, `GITHUB_ACTIONS`, and friends). Set `RUNFILE_SKIP_PREPARE=1` to bypass it manually.
+```
+runfiles/_aws.run       → run _aws     (a helper other targets call)
+runfiles/deploy.run     → run deploy
+```
 
-#### Migrate in seconds
+`do … end` is a block with no condition — somewhere for a property to go when it should cover a few commands
+and not the whole target:
 
-```bash
-$ run :convert package-json   # turns package.json scripts into targets
-$ run :convert makefile       # turns Makefile recipes into targets
+```sh
+# runfiles/setup.run
+# One-time per clone: hooks, then the web dependencies
+
+$ git config core.hooksPath .githooks
+
+do
+	.workdir = "web"
+
+	$ pnpm install
+	$ pnpm exec playwright install chromium
+end
 ```
 
-#### Plus
+That is what replaced writing `cd web &&` on every line, which the shell would have needed once per command.
 
-Parallel & detached execution · file includes with optional namespacing for monorepos
-(`pnpm --recursive --parallel`-style aggregation) · cycle detection · global Runfiles · path aliases ·
-confirmation prompts · `--dry-run` · `--stdin-args` (interactive prompting for missing inputs) · `--timings` ·
-force-kill on SIGINT (works for GUI apps like Unity) · stdio tailers · shell completions · MCP server.
+`_shared.run` holds properties — and `let` bindings — that every target in its directory inherits. A nested
+one layers over the directory above it, so `runfiles/api/_shared.run` adds to `runfiles/_shared.run`.
 
----
+```sh
+# runfiles/_shared.run
+# Settings every target here inherits
 
-## Platform Support
+.add-path = "node_modules/.bin"
+.env.CARGO_TERM_COLOR = "always"
 
-| Platform              | Status    |
-|-----------------------|-----------|
-| Linux (x86-64)        | Supported |
-| Linux (ARM64)         | Supported |
-| macOS (Apple Silicon) | Supported |
-| macOS (Intel)         | Supported |
-| Windows 10            | Supported |
-| Windows 11            | Supported |
-| Windows Server        | Supported |
+let image = "ghcr.io/example/builder:v2"
+```
 
-Single static binary. No runtime, no interpreter, no package manager.
+## How targets are found
 
----
+`run` walks **up** from the working directory for the nearest `runfiles/`, then **down** one level for
+subprojects. A nested directory becomes a namespace:
 
-## Documentation
+```
+runfiles/build.run          → run build
+web/runfiles/build.run      → run web:build
+runfiles/api/deploy.run     → run api:deploy
+```
 
-The full reference — every property, every flag, every subcommand — lives in [DOCS.md](.github/DOCS.md).
+Inside a subproject, `run build` means *that* subproject's `build` — so a file reads the same wherever you
+invoke `run` from.
 
-- [CLI usage and subcommands](.github/DOCS.md#cli-usage)
-- [Runfile.json reference](.github/DOCS.md#runfilejson-reference)
-- [Arguments and substitution](.github/DOCS.md#arguments-and-substitution)
-- [Encrypted environment variables](.github/DOCS.md#encrypted-environment-variables)
-- [Internal targets](.github/DOCS.md#internal-targets)
-- [`when:` blocks](.github/DOCS.md#when-guarded-blocks-when)
-- [Watch mode](.github/DOCS.md#watch-mode)
-- [Editor integration](.github/DOCS.md#editor-integration)
+`$HOME/.runfiles/` holds machine-wide targets, available in every project. If you would rather see the
+directory than hide it, `$HOME/runfiles/` and `$HOME/Runfiles/` are read too — but only one of the three may
+hold anything.
 
----
+Everything relative — `.env-file`, `.add-path`, `glob`, `read_file`, `{{ RUN.parent }}`, the working directory
+— resolves against **the parent of `runfiles/`**. One anchor, one rule.
 
-## Development
+## Setup targets
+
+Name a target `setup` and every other target in its directory refuses to run until it has:
 
-```bash
-run setup          # one-time per clone: activates the committed git hooks (.githooks/)
-run build          # debug build
-run check          # non-mutating gate: fmt --check + clippy (deny warnings) + cargo check
-run lint           # auto-format + clippy
-run test           # full workspace test suite
 ```
+$ run build
+error: `setup` has never been run
+
+    run setup
+```
+
+It re-triggers when `setup.run` itself changes, so a new dependency is not silently missed. `--dry-run` is
+exempt, CI is exempt, and `RUNFILE_SKIP_PREPARE=1` bypasses it.
+
+## Commands
+
+| Command | |
+| --- | --- |
+| `run <target> [args…]` | Run a target |
+| `run :list` | List every target (`--names`, `--json` for tooling) |
+| `run :init` | Create `runfiles/` with an example |
+| `run :format [path…]` | Format runfiles in place (`--check`, `--stdout`) |
+| `run :env <sub>` | Manage `.env` files: `init`, `get`, `set`, `encrypt`, `decrypt`, `rotate`, `inject`, `secret-keys` |
+| `run :completions <command> <shell>` | `install`, `uninstall` or `output` a completion script for `bash`, `zsh`, `fish` or `powershell` |
+| `run :generate <editor>` | Task files for `zed`, `jetbrains` or `vscode`, merged into what is there |
+| `run :update` | Update the binary |
 
-The VS Code extension in [`editors/vscode`](editors/vscode) has its own targets, namespaced under `vscode:`:
+| Flag | |
+| --- | --- |
+| `-y`, `--yes` | Skip confirmation prompts |
+| `--stdin-args` | Prompt for every input the target reads, before it runs |
+| `--dry-run` | Print what would run, without running it |
+| `--dir <path>` | Start discovery somewhere else |
+| `-h`, `--help` | Show the help for `run` or any of its commands |
+| `-v`, `--version` | Print the version |
+
+Flags belong **before** the target name; everything after it is passed to the target.
+
+`run :format` has no settings: one shape, everywhere. It reindents with tabs, spaces expressions, places blank
+lines, lays out `json` blocks, and leaves the three things that are not the language's to touch — strings, the
+text after `$ `, and `exec` bodies — exactly as written. It refuses a file that does not parse, and checks that
+its own output still means the same thing before writing it. `--check` reports what would change and exits 1,
+which is what a CI step wants.
+
+## Encrypted environment variables
+
+Values in a `.env` file can be encrypted individually, so the file stays readable and diffable:
+
+```
+DATABASE_URL=encrypted:AAAA...
+PUBLIC_HOST=example.com
+```
 
 ```bash
-run vscode:deps      # one-time: pnpm install (required before the targets below)
-run vscode:compile   # type-check + compile to editors/vscode/out
-run vscode:watch     # recompile on change
-run vscode:package   # build the .vsix
-run vscode:install   # package + install into VS Code
+run :env init .env.production          # create, with a fresh key
+run :env set .env.production KEY value # encrypts on write
+run :env get .env.production KEY       # decrypts on read
+run :env rotate .env.production        # re-encrypt under a new key
 ```
 
----
+Keys live in the OS credential store — Keychain, Credential Manager, or Secret Service with a keyutils
+fallback. In CI, pass them as `RUNFILE_PRIVATE_KEYS` (newline-separated) and no credential store is involved.
+
+Decryption happens in memory; secrets never reach disk. The credential store is only touched when something
+actually decrypts, so a locked keyring never gets in the way of an unrelated target.
+
+## Editor support
+
+`runfile-lsp` ships beside `run` and gives you diagnostics, completion, formatting, go-to-definition and
+documentation on hover — from the same parser `run` itself uses, so your editor never disagrees with what will
+actually happen.
+
+Hover anything: a function shows its signature, what it does and a worked example; a property adds whether it
+may sit inside a block; `$`, `exec`, `run`, `retry`, `match` and the rest explain the line form itself.
+
+Ctrl+click a `run <target>` to open that target's file, or a variable to jump to where it was bound — including
+into the `_shared.run` above it, which is the one definition you cannot find by reading the file in front of
+you.
+
+It also hands `$` lines and shell `exec` bodies to [shellcheck](https://www.shellcheck.net) when it is
+installed, mapping findings back to the lines you wrote.
+
+**VS Code** — install the `.vsix` from the [latest release](https://github.com/JoaaoVerona/runfile/releases).
+You get a Run button on every target, a task provider, a sidebar tree, and shell lines coloured exactly as the
+same command in a `.sh` file. Set `"editor.formatOnSave": true` and saving formats.
+
+**JetBrains IDEs** read the same grammar: *Settings → Editor → TextMate Bundles*, add the `editors/vscode`
+directory from a checkout.
+
+**Zed, Neovim and Helix** use the tree-sitter grammar in `editors/tree-sitter`, with highlight queries
+included. For Neovim with nvim-treesitter:
+
+```lua
+require("nvim-treesitter.parsers").get_parser_configs().runfile = {
+  install_info = {
+    url = "https://github.com/JoaaoVerona/runfile",
+    location = "editors/tree-sitter",
+    files = { "src/parser.c", "src/scanner.c" },
+  },
+  filetype = "runfile",
+}
+vim.filetype.add({ extension = { run = "runfile" } })
+```
+
+`run :generate zed` writes every target into `.zed/tasks.json`, and `run :generate jetbrains` into
+`.idea/runConfigurations/`; both leave entries you wrote yourself alone and replace only their own.
+
+## Why a language
+
+The alternative is a config format plus an escape hatch into shell, and every version of that ends up encoding
+control flow in JSON or YAML — or giving up and shipping shell scripts that only run on one platform.
+
+A small language means `if`, `for` and `match` read as themselves; values have types, so `"a" + 1` is a mistake
+rather than `"a1"`; and interpolation can be safe by construction, because the language knows a string is one
+argument.
+
+Shell is still there. It is just marked.
+
+## How it compares
+
+| | Runfile | Make | Just | Taskfile |
+| --- | :-: | :-: | :-: | :-: |
+| One target per file, so a shared task file never conflicts | ✅ | ❌ | ❌ | ❌ |
+| Encrypted env vars, built-in (AES-256-GCM) | ✅ | ❌ | ❌ | ❌ |
+| Inline OS / shell / cwd branching via `RUN.*` | ✅ | ❌ | ❌ | ❌ |
+| Editor diagnostics from the runner's own parser | ✅ | ❌ | ❌ | ❌ |
+| Hover documentation for every function, property and line form | ✅ | ❌ | ❌ | ❌ |
+| One canonical format, in the CLI and on save | ✅ | ❌ | ❌ | ❌ |
+| IDE task generation (VS Code / Zed / JetBrains) | ✅ | ❌ | ❌ | ❌ |
+| Per-target shell override | ✅ | ❌ | ✅ | ❌ |
+| Any interpreter for a block (`exec python3`) | ✅ | ❌ | ✅ | ❌ |
+| Strict parsing (typos are errors) | ✅ | ❌ | ✅ | ❌ |
+| `--help` for one target, built from its own comments | ✅ | ❌ | ✅ | ❌ |
+| Argument substitution with chained fallbacks | ✅ | ❌ | ✅ | ❌ |
+| Watch mode, built-in | ✅ | ❌ | ❌ | ✅ |
+| Shell completions | ✅ | ❌ | ✅ | ✅ |
+| Hidden targets | ✅ | ❌ | ✅ | ✅ |
+| Built-in functions (strings, regex, paths, JSON, hashes, time) | ✅ | ❌ | ✅ | ✅ |
+| Parallel execution | ✅ | ✅ | ❌ | ✅ |
+| Single static binary | ✅ | ✅ | ✅ | ✅ |
+| Native Windows binary (`$` lines use Git Bash) | ✅ | ❌ | ✅ | ✅ |
+| Output prefixing in parallel mode | ✅ | ❌ | ❌ | ✅ |
+| First-class PowerShell / cmd.exe | ❌ | ❌ | ✅ | ❌ |
+| Pattern rules (`%.o: %.c`) | ❌ | ✅ | ❌ | ❌ |
+| Preconditions / status checks | ❌ | ❌ | ❌ | ✅ |
+| Incremental builds (sources / timestamps / checksums) | ❌ | ✅ | ❌ | ✅ |
+
+## Platform support
+
+| | |
+| --- | --- |
+| Linux | x86-64, arm64 |
+| macOS | Intel, Apple Silicon |
+| Windows | x86-64, arm64 |
+
+`$` lines use bash where it exists, Git Bash on Windows, and `sh` otherwise — so one file works everywhere. Set
+`.shell` to pin something else.
 
 ## License