From 1e0c75699f9614d7958de0f2fd2013dc74ea661b Mon Sep 17 00:00:00 2001
From: Jakub Dzikowski <jakub.t.dzikowski@gmail.com>
Date: Wed, 13 May 2026 13:28:24 +0200
Subject: [PATCH 1/5] =?UTF-8?q?chore:=20release=200.9.4=20=E2=80=94=20vers?=
 =?UTF-8?q?ion=20bump=20and=20changelog?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Jakub Dzikowski <jakub.t.dzikowski@gmail.com>
---
 .jaiph/docs_parity.jh   | 138 ++++++++++++++++++++--------------------
 CHANGELOG.md            |  39 ++++++++++--
 README.md               |   2 +-
 docs/cli.md             |   2 +-
 docs/index.html         |   6 +-
 docs/install            |   6 +-
 docs/setup.md           |   4 +-
 package-lock.json       |   4 +-
 package.json            |   2 +-
 src/cli/commands/use.ts |   2 +-
 src/cli/index.ts        |   2 +-
 11 files changed, 119 insertions(+), 88 deletions(-)

diff --git a/.jaiph/docs_parity.jh b/.jaiph/docs_parity.jh
index 10209f1c..bfec7344 100755
--- a/.jaiph/docs_parity.jh
+++ b/.jaiph/docs_parity.jh
@@ -1,29 +1,29 @@
 #!/usr/bin/env jaiph
 
 const role = """
-    You are an expert technical writer for this project.
-    1. You are fluent in Markdown and can read TypeScript code and Bash
-    2. You write for a developer audience, focusing on clarity and practical
-       examples.
-    3. You are concise, specific, and value dense
-    4. Write so that a new developer to this codebase can understand your
-       writing, but don't assume your audience are experts in the topic/area you
-       are writing about.
-    5. You are good in formulating generic context and describing the problem
-       starting from the generic part, leaving the specific details for the
-       last step, once the audience is aware of the generic context and the
-       problem.
-    6. You write problem explanation and goals in a human approachable way,
-       while keeping details dense in separate sections, so both human and AI
-    7. Source code and docs/architecture.md are the single source of truth. You don't
-       trust the existing documentation blindly.
+  You are an expert technical writer for this project.
+  1. You are fluent in Markdown and can read TypeScript code and Bash
+  2. You write for a developer audience, focusing on clarity and practical
+     examples.
+  3. You are concise, specific, and value dense
+  4. Write so that a new developer to this codebase can understand your
+     writing, but don't assume your audience are experts in the topic/area you
+     are writing about.
+  5. You are good in formulating generic context and describing the problem
+     starting from the generic part, leaving the specific details for the
+     last step, once the audience is aware of the generic context and the
+     problem.
+  6. You write problem explanation and goals in a human approachable way,
+     while keeping details dense in separate sections, so both human and AI
+  7. Source code and docs/architecture.md are the single source of truth. You don't
+     trust the existing documentation blindly.
 """
 
 script assert_newline_paths_are_files = ```
-while IFS= read -r f; do
-  [ -z "$f" ] && continue
-  test -f "$f" || return 1
-done <<< "$1"
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    test -f "$f" || return 1
+  done <<< "$1"
 ```
 
 rule docs_files_present(list) {
@@ -31,20 +31,20 @@ rule docs_files_present(list) {
 }
 
 script assert_worktree_clean_for_docs = ```
-local current_changed_files
-current_changed_files="$(
-  {
-    git diff --name-only --cached
-    git diff --name-only
-    git ls-files --others --exclude-standard
-  } | sort -u
-)"
-if [ -n "$current_changed_files" ]; then
-  echo "Refusing to run docs parity workflow on a dirty worktree." >&2
-  echo "Please commit, stash, or discard these files first:" >&2
-  echo "$current_changed_files" >&2
-  return 1
-fi
+  local current_changed_files
+  current_changed_files="$(
+    {
+      git diff --name-only --cached
+      git diff --name-only
+      git ls-files --others --exclude-standard
+    } | sort -u
+  )"
+  if [ -n "$current_changed_files" ]; then
+    echo "Refusing to run docs parity workflow on a dirty worktree." >&2
+    echo "Please commit, stash, or discard these files first:" >&2
+    echo "$current_changed_files" >&2
+    return 1
+  fi
 ```
 
 rule worktree_is_clean() {
@@ -52,23 +52,23 @@ rule worktree_is_clean() {
 }
 
 script assert_only_allowed_changed = ```
-local allowed="$1"
-local after_changed_files
-after_changed_files="$(
-  {
-    git diff --name-only --cached
-    git diff --name-only
-    git ls-files --others --exclude-standard
-  } | sort -u
-)"
-while IFS= read -r changed_file; do
-  [ -z "$changed_file" ] && continue
-  if [[ $'\n'"$allowed"$'\n' == *$'\n'"$changed_file"$'\n'* ]]; then
-    continue
-  fi
-  echo "Unexpected file changed by docs prompt: $changed_file" >&2
-  return 1
-done <<< "$after_changed_files"
+  local allowed="$1"
+  local after_changed_files
+  after_changed_files="$(
+    {
+      git diff --name-only --cached
+      git diff --name-only
+      git ls-files --others --exclude-standard
+    } | sort -u
+  )"
+  while IFS= read -r changed_file; do
+    [ -z "$changed_file" ] && continue
+    if [[ $'\n'"$allowed"$'\n' == *$'\n'"$changed_file"$'\n'* ]]; then
+      continue
+    fi
+    echo "Unexpected file changed by docs prompt: $changed_file" >&2
+    return 1
+  done <<< "$after_changed_files"
 ```
 
 rule only_expected_docs_changed_after_prompt(allowed) {
@@ -80,26 +80,26 @@ script first_line_str = `printf '%s\n' "$1" | head -n 1`
 script rest_lines_str = `printf '%s\n' "$1" | tail -n +2`
 
 script list_docs_md_paths = ```
-local out=""
-local f
-for f in docs/*.md; do
-  out="${out:+$out
-}$f"
-done
-printf '%s\n' "$out"
+  local out=""
+  local f
+  for f in docs/*.md; do
+    out="${out:+$out
+  }$f"
+  done
+  printf '%s\n' "$out"
 ```
 
 script build_allowed_paths_block = ```
-local out="README.md
-docs/index.html
-docs/_layouts/docs.html
-src/cli/shared/usage.ts"
-local f
-for f in docs/*.md; do
-  out="$out
-$f"
-done
-printf '%s\n' "$out"
+  local out="README.md
+  docs/index.html
+  docs/_layouts/docs.html
+  src/cli/shared/usage.ts"
+  local f
+  for f in docs/*.md; do
+    out="$out
+  $f"
+  done
+  printf '%s\n' "$out"
 ```
 
 script join_newline_args = `printf '%s\n' "$@"`
@@ -124,7 +124,7 @@ workflow update_from_task(taskDesc) {
     The task description is:
     ${taskDesc}
     </task>
-"""
+  """
 }
 
 workflow docs_page(path) {
diff --git a/CHANGELOG.md b/CHANGELOG.md
index add83fb6..4e7987e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,15 +1,46 @@
 # Unreleased
 
-- **Cleanup — remove `JAIPH_TEST_MODE` event suppression from production runtime code:** `RuntimeEventEmitter.emitStep` / `emitLog` no longer read `this.env.JAIPH_TEST_MODE` to decide whether to write `__JAIPH_EVENT__` lines to stderr. A construction-time `suppressLiveEvents?: boolean` option replaces the per-call env check: `NodeWorkflowRuntime` accepts it in its options and forwards it to `RuntimeEventEmitter`. `node-test-runner.ts` passes `suppressLiveEvents: true` when constructing the in-process runtime for `test_run_workflow` steps so `node --test` reporter output stays clean. `JAIPH_TEST_MODE: "1"` is still set in the test runner's env — but only for `prompt.ts`'s mock-mode selection, not event emission. No other production caller constructs `NodeWorkflowRuntime` directly, so the spawned `node-workflow-runner.js` child defaults to `suppressLiveEvents: false` and live events stream to stderr exactly as before. Durable `appendRunSummaryLine` writes to `run_summary.jsonl` are unchanged in either mode. Existing in-process unit tests under `node-workflow-runtime.artifacts.test.ts` pass the new option through their `NodeWorkflowRuntime` constructions.
+# 0.9.4
+
+## Summary
 
+Maintenance and simplification:
+- **Breaking:** Inbox dispatch is sequential only (parallel config/env removed). Stricter grammar: multiline `config` blocks only; no one-line braced workflows; no semicolon-separated statements in workflow/rule bodies.
+- **Runtime:** Single-line shell steps run in the Node runtime (`sh -c`); script capture only on success; async `run` + `recover` return propagation fixed; mock prompts use JSON arm dispatch and an in-memory response queue; inbox artifact files are written only when a route consumes the channel.
+- **CLI / install:** Failure footers use the **last** failed step in `run_summary.jsonl`; curl install ships `package.json` so stable installs resolve the correct default Docker image tag.
+- **Language:** RHS bare identifiers and bare dotted identifiers are treated as interpolation sugar where applicable.
+- **Library:** `artifacts.save(paths)` in single-argument form (path or newline-separated list); `git format-patch` workflows use `--stdout` so patch bytes are captured.
+- **Repo:** `node-workflow-runtime` split into arg-parser, event-emitter, and mock modules; test directories consolidated under `integration/`, `test-fixtures/`, `test-infra/`; `JAIPH_TEST_MODE` no longer suppresses stderr events in runtime code (constructor option instead).
+- **Docs / DX:** Agent-proxy design note; explicit parse error for `test` blocks outside `*.test.jh`; architecture/inbox corrections; getting-started shortened.
+
+## All changes
+
+- **Breaking — Language:** Inline one-line `config { k = v }` is removed — only the multiline `config {\n  … \n}` form parses (matches documented grammar). The formatter no longer emits compact inline `config`, which would be invalid input. Examples such as `examples/async.jh` were migrated.
+- **Breaking — Language:** Single-line `workflow name() { stmt }` braced form removed; workflow and rule bodies require one statement per line as in the grammar.
+- **Breaking — Language:** Semicolons no longer separate statements in workflow/rule bodies (`splitStatementsOnSemicolons` remains for `match` arms). Multiple statements on one line joined by `;` must be split across lines.
+- **Breaking — Inbox dispatch is always sequential** — The optional parallel inbox mode is removed: there is no `run.inbox_parallel` config key, no `JAIPH_INBOX_PARALLEL` environment variable (it is ignored), and no `JAIPH_INBOX_PARALLEL_LOCKED` shim. Route targets for a queued message always run **one after another** in declaration order on the `channel` line, inside `NodeWorkflowRuntime`’s `drainWorkflowQueue`. Using `run.inbox_parallel = …` in a `config { … }` block is `E_PARSE: unknown config key: run.inbox_parallel`. Docs and E2E now match sequential-only semantics; unit tests cover the unknown key and parity of dispatch event order with and without the old env var set. E2E harness clears inherited `JAIPH_*` noise so CI stays reliable in polluted agent environments.
+- **Language / Runtime:** Single-line shell steps execute via `sh -c` with script working-directory semantics in the Node workflow runtime (replacing the removed bash-era path for these steps). `validateReferences` and related checks were extended for `send` arrow targets, managed `run` on bare names, and dotted references.
+- **Fix — Interpolation:** RHS values treat bare identifiers and bare dotted identifiers as `${…}` interpolation sugar where the grammar allows, so dotted env-style names behave consistently with other binding references.
+- **Fix — Runtime return capture:** `executeScript` / `executeShLine` / `executeMockShellBody` return captured stdout only when the subprocess exits with status 0 (failed commands no longer leak stdout as a workflow return value).
+- **Fix — Async recover:** `run … recover(e) { … }` now propagates `recoverReturn` through the implicit async join site (parity with synchronous `ensure` / catch semantics).
+- **Language:** Reject `return 0`, `return $?`, and bare integer `return N` in workflows/rules with a clear diagnostic instead of emitting a useless shell line.
+- **Runtime — Mock prompts:** Mock arms are passed structurally as JSON via `JAIPH_MOCK_PROMPT_ARMS_JSON` with in-process dispatch in `mock.ts` (no bash dispatcher). Sequential mock responses use `JAIPH_MOCK_RESPONSES_JSON` and an in-memory queue (`consumeNextMockResponse`), removing per-step file churn.
+- **Runtime — Inbox files:** Inbox files under the run directory are written only when a route consumes the channel (no “audit-only” files for unrouted sends).
+- **Fix — Mock shell:** `executeMockShellBody` uses `bash -c` instead of a tempfile indirection; removes an ESM/`require` shadowing bug in the mock shell path.
+- **Library:** `jaiphlang/artifacts` exposes a single `save(paths)` workflow: one filesystem path or a newline-separated list; destination relpaths are derived per source (leading `./` stripped; absolute sources use `basename` only). The bundled engineer workflow uses `git.commit` plus `git format-patch` with `--stdout` / `HEAD` so the patch **contents** are saved (without `--stdout`, `format-patch` only printed the filename on stdout).
+- **Parser / UX:** A `test { … }` block in a file whose name does not end in `.test.jh` now fails with `E_PARSE` explaining that test blocks belong in `*.test.jh` (instead of falling through to a generic unsupported-statement error).
+- **Repo — Compiler/runtime cleanup:** Removed a large amount of dead bash-era kernel code and legacy parse rejects; consolidated import parsers and config-key handling; stricter top-level dispatch in `parser.ts`. `.jaiph/git.jh` moves to `jaiphlang/git` with `import "jaiphlang/git" as git`. Collapsed duplicate parser/runtime paths from the audit series (`B1`, `B10`, `B11`, etc.).
+- **Repo — AST clarity (no source keyword changes):** AST field names now align with keywords: the single-shot branch is `step.catch`, the repair-and-retry loop body is `step.recover`. TypeScript uses `catchDef` where `catch` is reserved. Workflow source still uses `run foo() recover(e) { … }` and `run foo() catch(e) { … }`.
+- **Fix — Runtime config seed:** Restore `cpSync` seeding of Claude config into the workspace fallback when only session env is unwritable (auth preservation).
+- **Docs:** Add `design/2026-05-12-agent-proxy.md` (Phantom Token / credential proxy design for sandboxed agents). Update `architecture.md` (drop stale `run-step-exec` / `seq-alloc` references). Update `inbox.md` (remove unused dispatch env vars; document inbox files only when consumed). Shorten `getting-started` overview.
+- **Tests / QA:** E2E and txtar fixtures for `import script` (shell/Python, capture, missing file); extended parse/validate error fixtures; QA scripts (`read_txtar_*`) point at `test-fixtures/compiler-txtar/`.
+- **Repo:** `AUDIT_PROGRESS.md` removed (remaining items tracked in `QUEUE.md`). `Gemfile.lock` records `ffi` platform gems for arm64-darwin and x86_64-linux where needed.
+- **Cleanup — remove `JAIPH_TEST_MODE` event suppression from production runtime code:** `RuntimeEventEmitter.emitStep` / `emitLog` no longer read `this.env.JAIPH_TEST_MODE` to decide whether to write `__JAIPH_EVENT__` lines to stderr. A construction-time `suppressLiveEvents?: boolean` option replaces the per-call env check: `NodeWorkflowRuntime` accepts it in its options and forwards it to `RuntimeEventEmitter`. `node-test-runner.ts` passes `suppressLiveEvents: true` when constructing the in-process runtime for `test_run_workflow` steps so `node --test` reporter output stays clean. `JAIPH_TEST_MODE: "1"` is still set in the test runner's env — but only for `prompt.ts`'s mock-mode selection, not event emission. No other production caller constructs `NodeWorkflowRuntime` directly, so the spawned `node-workflow-runner.js` child defaults to `suppressLiveEvents: false` and live events stream to stderr exactly as before. Durable `appendRunSummaryLine` writes to `run_summary.jsonl` are unchanged in either mode. Existing in-process unit tests under `node-workflow-runtime.artifacts.test.ts` pass the new option through their `NodeWorkflowRuntime` constructions.
 - **Repo — `node-workflow-runtime.ts` split:** The 1915-LoC `src/runtime/kernel/node-workflow-runtime.ts` god file is split into the orchestrator plus three focused sibling modules under `src/runtime/kernel/`. No behavior changes — pure relocation; existing tests pass unchanged (helpers re-imported from their new location where needed).
   - **`runtime-arg-parser.ts`** — every stateless free helper that used to live above the `NodeWorkflowRuntime` class (`interpolate`, `parseInlineCaptureCall`, `commaArgsToInterpolated`, `parseArgsRaw`, `parseInlineScriptAt`, `parseManagedArgAt`, `parseArgTokens`, `stripOuterQuotes`, `parsePromptSchema`, `sanitizeName`, `nowIso`), the `BARE_IDENT_RE` / `MAX_EMBED` / `MAX_RECURSION_DEPTH` constants, and the `ParsedArgToken` / `PromptSchemaField` types. Direct unit tests added in `runtime-arg-parser.test.ts`.
   - **`runtime-event-emitter.ts`** — `RuntimeEventEmitter` owns `emitWorkflow`, `emitStep`, `emitPromptStepStart`, `emitPromptStepEnd`, `emitPromptEvent`, `emitLog`, plus the monotonic step and prompt sequence counters. Constructed with `{ runId, runDir, env, getFrameStack, getAsyncIndices }`. No more direct `process.stderr.write(__JAIPH_EVENT__ …)` scattered through the runtime.
   - **`runtime-mock.ts`** — `executeMockBodyDef` and `executeMockShellBody` move here as exported functions taking `{ ref, args, env, cwd, executeStepsBack }` (the last is a callback so steps-kind mocks dispatch back into the runtime). The `require("node:child_process")` call that shadowed ESM imports inside `executeMockShellBody` is gone — replaced by a top-of-file `import`.
   - The orchestrator (`node-workflow-runtime.ts`) keeps the `NodeWorkflowRuntime` class, workflow/step orchestration (`runDefault`, `runNamedWorkflow`, `executeSteps`, `executeStep`, `runRecoverBody`, `runPromptStep`, frame and scope management), async-handle bookkeeping (`getAsyncIndices`, `getFrameStack`), and heartbeat (`startHeartbeat`, `stopHeartbeat`, `writeHeartbeat`). Dependency direction is one-way (orchestrator → helpers/emitter/mock); no circular imports.
-
-- **Breaking — Inbox dispatch is always sequential** — The optional parallel inbox mode is removed: there is no `run.inbox_parallel` config key, no `JAIPH_INBOX_PARALLEL` environment variable (it is ignored), and no `JAIPH_INBOX_PARALLEL_LOCKED` shim. Route targets for a queued message always run **one after another** in declaration order on the `channel` line, inside `NodeWorkflowRuntime`’s `drainWorkflowQueue`. Using `run.inbox_parallel = …` in a `config { … }` block is `E_PARSE: unknown config key: run.inbox_parallel`. Docs and E2E now match sequential-only semantics; unit tests cover the unknown key and parity of dispatch event order with and without the old env var set.
-
 - **Fix — CLI failure footer:** `Output of failed step` and the footer `out:` / `err:` paths now resolve from the **last** non-zero `STEP_END` in `run_summary.jsonl` (append order), not the first. The first failure line could be a recovered `catch`/`ensure` attempt, a stray record, or unrelated noise; the last failure matches the terminal step (the one the progress tree marks as failed). **`src/cli/shared/errors.test.ts`** covers multiple non-zero `STEP_END` lines.
 - **Fix — Docker default image tag:** `curl` / `docs/install` copied only `dist/src` into `~/.local/bin/.jaiph`, so the CLI could not read `package.json` and defaulted the sandbox image to `ghcr.io/jaiphlang/jaiph-runtime:nightly` even for stable installs. The installer now copies `package.json` beside `src/`, and `resolveDefaultDockerImageTag` checks both the installer layout and the npm `dist/src/runtime` layout.
 - **Repo — Test directory consolidation:** Consolidated the five-way test directory split (`src/**/*.test.ts`, `test/`, `tests/`, `compiler-tests/`, `golden-ast/`) into three test "places" plus two clearly named support directories. File moves:
diff --git a/README.md b/README.md
index a5bed42c..c113e01e 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ Or install from npm:
 npm install -g jaiph
 ```
 
-Verify: `jaiph --version`. Switch versions: `jaiph use nightly` or `jaiph use 0.9.3`.
+Verify: `jaiph --version`. Switch versions: `jaiph use nightly` or `jaiph use 0.9.4`.
 
 ## Example
 
diff --git a/docs/cli.md b/docs/cli.md
index ddd7c6a0..a5258692 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -393,7 +393,7 @@ jaiph use <version|nightly>
 
 ```bash
 jaiph use nightly
-jaiph use 0.9.3
+jaiph use 0.9.4
 ```
 
 ## File extension
diff --git a/docs/index.html b/docs/index.html
index 8670e2d1..96a0985e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -77,7 +77,7 @@ <h2>Try it out!</h2>
 
                 <div class="code-tab-panel is-active" data-panel="try-run-sample">
                     <pre><code class="language-bash static-highlight"><span class="code-line">curl -fsSL https://jaiph.org/run | bash -s '</span><span class="code-line"><span class="ralph-keyword">workflow</span> <span class="ralph-definition">default</span>() {</span><span class="code-line">  <span class="ralph-keyword">const</span> <span class="ralph-variable">response</span> <span class="ralph-operator">=</span> <span class="ralph-keyword">prompt</span> <span class="ralph-string">"Say: Hello, I am [model name]!"</span></span><span class="code-line">  <span class="ralph-keyword">log</span> response</span><span class="code-line">}'</span></code></pre>
-                    <p class="small">Installs Jaiph <strong>v0.9.3</strong> to <strong>~/.local/bin</strong> (if not
+                    <p class="small">Installs Jaiph <strong>v0.9.4</strong> to <strong>~/.local/bin</strong> (if not
                         already
                         installed), and runs the sample workflow with <a href="https://cursor.com/docs/cli/installation"
                             target="_blank" rel="noopener noreferrer">Cursor CLI</a> agent backend (the default one).
@@ -89,14 +89,14 @@ <h2>Try it out!</h2>
                 <div class="code-tab-panel" data-panel="try-init-project">
                     <p class="small">Run the script below from the project directory:</p>
                     <pre><code class="language-bash">curl -fsSL https://jaiph.org/init | bash</code></pre>
-                    <p class="small">Installs Jaiph <strong>v0.9.3</strong> to <strong>~/.local/bin</strong> (if not
+                    <p class="small">Installs Jaiph <strong>v0.9.4</strong> to <strong>~/.local/bin</strong> (if not
                         already installed), and runs <code>jaiph init</code> to initialize the Jaiph workspace in the
                         current directory.</p>
                 </div>
 
                 <div class="code-tab-panel" data-panel="try-install-only">
                     <pre><code class="language-bash">curl -fsSL https://jaiph.org/install | bash</code></pre>
-                    <p class="small">The installer will install the version <strong>0.9.3</strong> of Jaiph to
+                    <p class="small">The installer will install the version <strong>0.9.4</strong> of Jaiph to
                         <strong>~/.local/bin</strong>. To switch versions, use <code>jaiph use nightly</code>
                         or <code>jaiph use &lt;version&gt;</code> to switch.
                     </p>
diff --git a/docs/install b/docs/install
index a6be8c1a..8c43b126 100755
--- a/docs/install
+++ b/docs/install
@@ -55,11 +55,11 @@ elif [ -n "${1+x}" ] && [ -d "${1}" ] && [ -f "${1}/package.json" ]; then
   JAIPH_REPO_URL="${REPO_URL}"
 fi
 REPO_URL="${REPO_URL:-${JAIPH_REPO_URL:-https://github.com/jaiphlang/jaiph.git}}"
-# Version/ref: first argument only when not a local path, or JAIPH_REPO_REF env, or default tag v0.9.3.
+# Version/ref: first argument only when not a local path, or JAIPH_REPO_REF env, or default tag v0.9.4.
 if [ -n "${JAIPH_FROM_LOCAL}" ]; then
-  REPO_REF="${JAIPH_REPO_REF:-v0.9.3}"
+  REPO_REF="${JAIPH_REPO_REF:-v0.9.4}"
 else
-  REPO_REF="${1:-${JAIPH_REPO_REF:-v0.9.3}}"
+  REPO_REF="${1:-${JAIPH_REPO_REF:-v0.9.4}}"
 fi
 BIN_DIR="${JAIPH_BIN_DIR:-$HOME/.local/bin}"
 LIB_DIR="${JAIPH_LIB_DIR:-${BIN_DIR}/.jaiph}"
diff --git a/docs/setup.md b/docs/setup.md
index 2a382b74..0eefa22a 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -31,11 +31,11 @@ jaiph --version
 
 If the command is not found, ensure `~/.local/bin` (installer) or the npm global bin directory is in your `PATH`.
 
-Switch versions at any time (re-runs the install script with a Git ref: `nightly` or `v<version>` such as `v0.9.3` when you pass `0.9.3`):
+Switch versions at any time (re-runs the install script with a Git ref: `nightly` or `v<version>` such as `v0.9.4` when you pass `0.9.4`):
 
 ```bash
 jaiph use nightly
-jaiph use 0.9.3
+jaiph use 0.9.4
 ```
 
 The default install command is `curl -fsSL https://jaiph.org/install | bash`. Override it with `JAIPH_INSTALL_COMMAND` if you need a fork, air-gapped bundle, or local script.
diff --git a/package-lock.json b/package-lock.json
index 2dbbe150..393fb652 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "jaiph",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "jaiph",
-      "version": "0.9.3",
+      "version": "0.9.4",
       "bin": {
         "jaiph": "dist/src/cli.js"
       },
diff --git a/package.json b/package.json
index def844bd..bd08315e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "jaiph",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "jaiph compiler/transpiler",
   "repository": {
     "type": "git",
diff --git a/src/cli/commands/use.ts b/src/cli/commands/use.ts
index b1440327..f575fad4 100644
--- a/src/cli/commands/use.ts
+++ b/src/cli/commands/use.ts
@@ -14,7 +14,7 @@ function toInstallRef(version: string): string | undefined {
 export function runUse(rest: string[]): number {
   const version = rest[0];
   if (!version) {
-    process.stderr.write("jaiph use requires a version (e.g. 0.9.3) or 'nightly'\n");
+    process.stderr.write("jaiph use requires a version (e.g. 0.9.4) or 'nightly'\n");
     return 1;
   }
   const ref = toInstallRef(version);
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 2270770a..3248529e 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -16,7 +16,7 @@ export async function main(argv: string[]): Promise<number> {
     return 0;
   }
   if (cmd === "--version" || cmd === "-v") {
-    process.stdout.write("jaiph 0.9.3\n");
+    process.stdout.write("jaiph 0.9.4\n");
     return 0;
   }
   try {

From 64f6dbc576c9b5a51a6cd87bc8ff685804527041 Mon Sep 17 00:00:00 2001
From: Jakub Dzikowski <jakub.t.dzikowski@gmail.com>
Date: Wed, 13 May 2026 14:55:23 +0200
Subject: [PATCH 2/5] =?UTF-8?q?feat:=20for=20=E2=80=A6=20in=20=E2=80=A6=20?=
 =?UTF-8?q?iteration=20over=20newline-delimited=20strings?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add parse, validate, emit, and runtime support for `for <id> in <id> { … }`
in workflows and rules. Split helper normalizes CRLF and drops a trailing
empty segment after a final newline. Add string-lines unit tests and E2E 135.

Document the change under # Unreleased in CHANGELOG.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CHANGELOG.md                                |  3 +
 e2e/test_all.sh                             |  1 +
 e2e/tests/135_for_string_lines.sh           | 99 +++++++++++++++++++++
 src/format/emit.ts                          |  7 ++
 src/parse/core.ts                           |  2 +-
 src/parse/workflow-brace.ts                 | 21 +++++
 src/runtime/kernel/node-workflow-runtime.ts | 17 ++++
 src/runtime/string-lines.test.ts            | 25 ++++++
 src/runtime/string-lines.ts                 | 13 +++
 src/transpile/emit-script.ts                |  4 +
 src/transpile/validate.ts                   | 66 +++++++++++---
 src/types.ts                                |  8 ++
 12 files changed, 254 insertions(+), 12 deletions(-)
 create mode 100644 e2e/tests/135_for_string_lines.sh
 create mode 100644 src/runtime/string-lines.test.ts
 create mode 100644 src/runtime/string-lines.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4e7987e8..be0622c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,8 @@
 # Unreleased
 
+- **Language:** `for <id> in <id> { … }` in workflows and rules iterates newline-delimited lines of a string binding. Newlines normalize `\r\n` to `\n`; a single trailing empty segment from a final newline is omitted. Lines are not trimmed and empty interior lines are still iterated unless the body skips them (e.g. `if line != "" { … }`). Documented in `docs/language.md`.
+- **Tests / QA:** Unit tests for string line splitting (`src/runtime/string-lines.test.ts`); E2E `e2e/tests/135_for_string_lines.sh`.
+
 # 0.9.4
 
 ## Summary
diff --git a/e2e/test_all.sh b/e2e/test_all.sh
index 114c6a7a..d99eb90e 100755
--- a/e2e/test_all.sh
+++ b/e2e/test_all.sh
@@ -88,6 +88,7 @@ TEST_SCRIPTS=(
   "e2e/tests/132_return_log_inline_script.sh"
   "e2e/tests/133_return_bare_identifier.sh"
   "e2e/tests/134_script_imports.sh"
+  "e2e/tests/135_for_string_lines.sh"
 )
 
 PASS_COUNT=0
diff --git a/e2e/tests/135_for_string_lines.sh b/e2e/tests/135_for_string_lines.sh
new file mode 100644
index 00000000..8f5f262a
--- /dev/null
+++ b/e2e/tests/135_for_string_lines.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "${ROOT_DIR}/e2e/lib/common.sh"
+trap e2e::cleanup EXIT
+
+e2e::prepare_test_env "for_string_lines"
+TEST_DIR="${JAIPH_E2E_TEST_DIR}"
+
+e2e::section "for line in string iterates lines"
+
+e2e::file "for_lines.jh" <<'EOF'
+workflow default() {
+  const paths = """
+docs/a.md
+docs/b.md
+"""
+  for path in paths {
+    log "${path}"
+  }
+  log "done"
+}
+EOF
+
+out="$(e2e::run "for_lines.jh")"
+grep -q "docs/a.md" <<<"${out}" || {
+  echo "${out}" >&2
+  exit 1
+}
+grep -q "docs/b.md" <<<"${out}" || {
+  echo "${out}" >&2
+  exit 1
+}
+grep -q "done" <<<"${out}" || {
+  echo "${out}" >&2
+  exit 1
+}
+e2e::pass "for … in … runs body per line"
+
+e2e::section "for line in string skips only trailing empty segment"
+
+e2e::file "for_lines_trim_nl.jh" <<'EOF'
+workflow default() {
+  const paths = """
+one
+two
+"""
+  for line in paths {
+    log ">>${line}<<"
+  }
+}
+EOF
+
+out2="$(e2e::run "for_lines_trim_nl.jh")"
+grep -q ">>one<<" <<<"${out2}" || exit 1
+grep -q ">>two<<" <<<"${out2}" || exit 1
+# No third empty iteration from final newline
+if grep -q '>><<' <<<"${out2}"; then
+  echo "unexpected empty line iteration:${out2}" >&2
+  exit 1
+fi
+e2e::pass "final newline does not yield empty line"
+
+e2e::section "for … in … with empty line in middle"
+
+e2e::file "for_lines_interior_blank.jh" <<'EOF'
+workflow default() {
+  const paths = """
+x
+
+y
+"""
+  for line in paths {
+    if line == "" {
+      log "(empty)"
+    }
+    if line != "" {
+      log "${line}"
+    }
+  }
+}
+EOF
+
+out3="$(e2e::run "for_lines_interior_blank.jh")"
+grep -q "ℹ x" <<<"${out3}" || {
+  echo "${out3}" >&2
+  exit 1
+}
+grep -q "ℹ (empty)" <<<"${out3}" || {
+  echo "${out3}" >&2
+  exit 1
+}
+grep -q "ℹ y" <<<"${out3}" || {
+  echo "${out3}" >&2
+  exit 1
+}
+e2e::pass "interior empty line is still iterated"
diff --git a/src/format/emit.ts b/src/format/emit.ts
index bbc70329..f1315f22 100644
--- a/src/format/emit.ts
+++ b/src/format/emit.ts
@@ -731,6 +731,13 @@ function emitStep(step: WorkflowStepDef, pad: string, currentIndent: string): st
       lines.push(`${ci}}`);
       break;
     }
+
+    case "for_lines": {
+      lines.push(`${ci}for ${step.iterVar} in ${step.sourceVar} {`);
+      lines.push(...emitSteps(step.body, pad, ci + pad));
+      lines.push(`${ci}}`);
+      break;
+    }
   }
 
   return lines;
diff --git a/src/parse/core.ts b/src/parse/core.ts
index c131c794..0cac7c10 100644
--- a/src/parse/core.ts
+++ b/src/parse/core.ts
@@ -92,7 +92,7 @@ const JAIPH_KEYWORDS = new Set([
   "run", "ensure", "prompt", "return", "fail", "log", "logerr",
   "if", "else", "not", "const", "match", "import", "export",
   "workflow", "rule", "script", "channel", "config", "catch", "async",
-  "returns", "send", "true", "false",
+  "returns", "send", "true", "false", "for", "in",
 ]);
 
 /** Check if a token is a bare identifier (valid identifier, not a keyword). */
diff --git a/src/parse/workflow-brace.ts b/src/parse/workflow-brace.ts
index cb12675f..485d1c10 100644
--- a/src/parse/workflow-brace.ts
+++ b/src/parse/workflow-brace.ts
@@ -160,6 +160,27 @@ export function parseBlockStatement(
     );
   }
 
+  // for <iter> in <string-var> { ... }
+  const forHead = inner.match(/^for\s+([A-Za-z_][A-Za-z0-9_]*)\s+in\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{\s*$/);
+  if (forHead) {
+    const iterVar = forHead[1];
+    const sourceVar = forHead[2];
+    const forLoc = { line: innerNo, col: innerRaw.indexOf("for") + 1 };
+    const { steps: body, nextIdx } = parseBraceBlockBody(filePath, lines, idx + 1, innerNo, opts);
+    return {
+      step: { type: "for_lines", iterVar, sourceVar, body, loc: forLoc },
+      nextIdx,
+    };
+  }
+  if (/^for\s/.test(inner)) {
+    fail(
+      filePath,
+      'invalid for syntax; expected: for <identifier> in <identifier> { ... }',
+      innerNo,
+      innerRaw.indexOf("for") + 1,
+    );
+  }
+
   const constMatch = inner.match(/^const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/s);
   if (constMatch) {
     const name = constMatch[1];
diff --git a/src/runtime/kernel/node-workflow-runtime.ts b/src/runtime/kernel/node-workflow-runtime.ts
index 97ff655e..d6c91545 100644
--- a/src/runtime/kernel/node-workflow-runtime.ts
+++ b/src/runtime/kernel/node-workflow-runtime.ts
@@ -31,6 +31,7 @@ import {
 } from "./runtime-arg-parser";
 import { RuntimeEventEmitter, type Frame } from "./runtime-event-emitter";
 import { executeMockBodyDef, type MockBodyDef, type StepResult } from "./runtime-mock";
+import { linesOfDelimitedString } from "../string-lines";
 
 export type { MockBodyDef } from "./runtime-mock";
 
@@ -866,6 +867,22 @@ export class NodeWorkflowRuntime {
         }
         continue;
       }
+      if (step.type === "for_lines") {
+        const raw =
+          scope.vars.get(step.sourceVar) ??
+          scope.env?.[step.sourceVar] ??
+          "";
+        for (const line of linesOfDelimitedString(raw)) {
+          scope.vars.set(step.iterVar, line);
+          const bodyResult = await this.executeSteps(scope, step.body, io);
+          if (bodyResult.status !== 0 || bodyResult.returnValue !== undefined) {
+            return this.mergeStepResult(accOut, accErr, bodyResult);
+          }
+          accOut += bodyResult.output;
+          accErr += bodyResult.error;
+        }
+        continue;
+      }
       if (step.type === "match") {
         const matchResult = await this.evaluateMatch(scope, step.expr);
         if (!matchResult.ok) return this.mergeStepResult(accOut, accErr, matchResult.result);
diff --git a/src/runtime/string-lines.test.ts b/src/runtime/string-lines.test.ts
new file mode 100644
index 00000000..e4b6dd44
--- /dev/null
+++ b/src/runtime/string-lines.test.ts
@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { linesOfDelimitedString } from "./string-lines";
+
+test("linesOfDelimitedString: empty", () => {
+  assert.deepEqual(linesOfDelimitedString(""), []);
+});
+
+test("linesOfDelimitedString: no trailing newline", () => {
+  assert.deepEqual(linesOfDelimitedString("a"), ["a"]);
+  assert.deepEqual(linesOfDelimitedString("a\nb"), ["a", "b"]);
+});
+
+test("linesOfDelimitedString: trailing newline drops empty last segment", () => {
+  assert.deepEqual(linesOfDelimitedString("a\n"), ["a"]);
+  assert.deepEqual(linesOfDelimitedString("a\nb\n"), ["a", "b"]);
+});
+
+test("linesOfDelimitedString: normalizes CRLF", () => {
+  assert.deepEqual(linesOfDelimitedString("a\r\nb"), ["a", "b"]);
+});
+
+test("linesOfDelimitedString: preserves empty interior lines", () => {
+  assert.deepEqual(linesOfDelimitedString("a\n\nb"), ["a", "", "b"]);
+});
diff --git a/src/runtime/string-lines.ts b/src/runtime/string-lines.ts
new file mode 100644
index 00000000..ae097ccc
--- /dev/null
+++ b/src/runtime/string-lines.ts
@@ -0,0 +1,13 @@
+/**
+ * Lines of a newline-delimited string for `for x in str`.
+ * Normalizes `\r\n` to `\n`. If the string ends with a final newline, the
+ * trailing empty segment is not yielded (so `"a\nb\n"` → `["a", "b"]`).
+ */
+export function linesOfDelimitedString(s: string): string[] {
+  const normalized = s.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  if (lines.length && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines;
+}
diff --git a/src/transpile/emit-script.ts b/src/transpile/emit-script.ts
index ca8c9185..5ccf8675 100644
--- a/src/transpile/emit-script.ts
+++ b/src/transpile/emit-script.ts
@@ -91,6 +91,10 @@ function collectInlineScripts(
     } else if ((s.type === "ensure" || s.type === "run") && s.catch) {
       const recoverSteps = "single" in s.catch ? [s.catch.single] : s.catch.block;
       collectInlineScripts(recoverSteps, seen, out);
+    } else if (s.type === "if") {
+      collectInlineScripts(s.body, seen, out);
+    } else if (s.type === "for_lines") {
+      collectInlineScripts(s.body, seen, out);
     }
   }
 }
diff --git a/src/transpile/validate.ts b/src/transpile/validate.ts
index b537a683..30627918 100644
--- a/src/transpile/validate.ts
+++ b/src/transpile/validate.ts
@@ -206,6 +206,10 @@ function collectKnownVars(steps: WorkflowStepDef[], envDecls?: { name: string }[
       if (s.type === "if") {
         walk(s.body);
       }
+      if (s.type === "for_lines") {
+        vars.add(s.iterVar);
+        walk(s.body);
+      }
     }
   };
   walk(steps);
@@ -227,8 +231,8 @@ function validateImmutableBindings(
     bound.set(p, { kind: "parameter", line: declLoc.line });
   }
 
-  const check = (name: string, kind: string, loc: { line: number; col: number }): void => {
-    const prev = bound.get(name);
+  const check = (name: string, kind: string, loc: { line: number; col: number }, b: Map<string, { kind: string; line: number }>): void => {
+    const prev = b.get(name);
     if (prev) {
       throw jaiphError(
         filePath,
@@ -247,33 +251,47 @@ function validateImmutableBindings(
         `cannot rebind immutable name "${name}"; already bound as script in this module`,
       );
     }
-    bound.set(name, { kind, line: loc.line });
+    b.set(name, { kind, line: loc.line });
   };
 
-  const walk = (ss: WorkflowStepDef[]): void => {
+  const walk = (ss: WorkflowStepDef[], b: Map<string, { kind: string; line: number }>): void => {
     for (const s of ss) {
       if (s.type === "const") {
-        check(s.name, "const", s.loc);
+        check(s.name, "const", s.loc, b);
       }
       if (s.type === "ensure" && s.captureName) {
-        check(s.captureName, "capture", s.ref.loc);
+        check(s.captureName, "capture", s.ref.loc, b);
       }
       if (s.type === "run" && s.captureName) {
-        check(s.captureName, "capture", s.workflow.loc);
+        check(s.captureName, "capture", s.workflow.loc, b);
       }
       if ((s.type === "prompt" || s.type === "run_inline_script") && s.captureName) {
-        check(s.captureName, "capture", s.loc);
+        check(s.captureName, "capture", s.loc, b);
       }
       if ((s.type === "ensure" || s.type === "run") && s.catch) {
         const recoverSteps = "single" in s.catch ? [s.catch.single] : s.catch.block;
-        walk(recoverSteps);
+        walk(recoverSteps, b);
       }
       if (s.type === "if") {
-        walk(s.body);
+        walk(s.body, b);
+      }
+      if (s.type === "for_lines") {
+        if (b.has(s.iterVar)) {
+          throw jaiphError(
+            filePath,
+            s.loc.line,
+            s.loc.col,
+            "E_VALIDATE",
+            `for loop iterator "${s.iterVar}" conflicts with an existing binding`,
+          );
+        }
+        const inner = new Map(b);
+        inner.set(s.iterVar, { kind: "loop_iterator", line: s.loc.line });
+        walk(s.body, inner);
       }
     }
   };
-  walk(steps);
+  walk(steps, bound);
 }
 
 /** Count the number of call arguments from a space-separated args string (respects quotes). */
@@ -882,6 +900,19 @@ export function validateReferences(ast: jaiphModule, ctx: ValidateContext): void
         for (const bodyStep of s.body) validateRuleStep(bodyStep);
         return;
       }
+      if (s.type === "for_lines") {
+        if (!ruleKnownVars.has(s.sourceVar)) {
+          throw jaiphError(
+            ast.filePath,
+            s.loc.line,
+            s.loc.col,
+            "E_VALIDATE",
+            `for ... in <name>: "${s.sourceVar}" is not a known variable in this scope`,
+          );
+        }
+        for (const bodyStep of s.body) validateRuleStep(bodyStep);
+        return;
+      }
       if (s.type === "run_inline_script") {
         return;
       }
@@ -1270,6 +1301,19 @@ export function validateReferences(ast: jaiphModule, ctx: ValidateContext): void
         for (const bodyStep of s.body) validateStep(bodyStep, recoverBindings);
         return;
       }
+      if (s.type === "for_lines") {
+        if (!wfKnownVars.has(s.sourceVar)) {
+          throw jaiphError(
+            ast.filePath,
+            s.loc.line,
+            s.loc.col,
+            "E_VALIDATE",
+            `for ... in <name>: "${s.sourceVar}" is not a known variable in this scope`,
+          );
+        }
+        for (const bodyStep of s.body) validateStep(bodyStep, recoverBindings);
+        return;
+      }
       if (s.type === "run_inline_script") {
         return;
       }
diff --git a/src/types.ts b/src/types.ts
index ae4b4d98..61e6abff 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -252,6 +252,14 @@ export type WorkflowStepDef =
       body: WorkflowStepDef[];
       loc: SourceLoc;
     }
+  | {
+      /** `for line in paths { ... }` — iterate lines of a string variable (newline-delimited). */
+      type: "for_lines";
+      iterVar: string;
+      sourceVar: string;
+      body: WorkflowStepDef[];
+      loc: SourceLoc;
+    }
   | {
       /** Preserved intentional blank line between steps (formatter only). */
       type: "blank_line";

From 91d40868cc929371b105948cc90857ea229a7c1d Mon Sep 17 00:00:00 2001
From: Jakub Dzikowski <jakub.t.dzikowski@gmail.com>
Date: Wed, 13 May 2026 14:55:25 +0200
Subject: [PATCH 3/5] docs: document for-line iteration; use it in docs_parity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add language.md subsection for `for … in …`. Queue follow-up on optional
trim/skip-empty sugar. Replace head/tail recursion in .jaiph/docs_parity.jh
with a loop over the docs path list.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .jaiph/docs_parity.jh | 53 +++++++++++++------------------------------
 QUEUE.md              | 17 ++++++++++++++
 docs/language.md      | 36 ++++++++++++++++++++++++-----
 3 files changed, 63 insertions(+), 43 deletions(-)

diff --git a/.jaiph/docs_parity.jh b/.jaiph/docs_parity.jh
index bfec7344..30bf62cc 100755
--- a/.jaiph/docs_parity.jh
+++ b/.jaiph/docs_parity.jh
@@ -21,6 +21,8 @@ const role = """
 
 script assert_newline_paths_are_files = ```
   while IFS= read -r f; do
+    f="${f#"${f%%[![:space:]]*}"}"
+    f="${f%"${f##*[![:space:]]}"}"
     [ -z "$f" ] && continue
     test -f "$f" || return 1
   done <<< "$1"
@@ -75,35 +77,27 @@ rule only_expected_docs_changed_after_prompt(allowed) {
   run assert_only_allowed_changed(allowed)
 }
 
-script first_line_str = `printf '%s\n' "$1" | head -n 1`
-
-script rest_lines_str = `printf '%s\n' "$1" | tail -n +2`
-
 script list_docs_md_paths = ```
-  local out=""
-  local f
+  local out="" f
   for f in docs/*.md; do
-    out="${out:+$out
-  }$f"
+    if [ -z "$out" ]; then
+      out="$f"
+    else
+      out="$out"$'\n'"$f"
+    fi
   done
   printf '%s\n' "$out"
 ```
 
 script build_allowed_paths_block = ```
-  local out="README.md
-  docs/index.html
-  docs/_layouts/docs.html
-  src/cli/shared/usage.ts"
-  local f
+  local out f
+  out="$(printf '%s\n' README.md docs/index.html docs/_layouts/docs.html src/cli/shared/usage.ts)"
   for f in docs/*.md; do
-    out="$out
-  $f"
+    out="$out"$'\n'"$f"
   done
   printf '%s\n' "$out"
 ```
 
-script join_newline_args = `printf '%s\n' "$@"`
-
 workflow update_from_task(taskDesc) {
   prompt """
     <role>
@@ -206,31 +200,16 @@ workflow docs_overview(docPaths) {
 """
 }
 
-workflow process_docs_md_recursive(file, remaining) {
-  run docs_page(file)
-  if remaining == "" {
-    return
-  }
-  const next = run first_line_str(remaining)
-  const rest = run rest_lines_str(remaining)
-  run process_docs_md_recursive(next, rest)
-}
-
-workflow maybe_process_docs_md(first_doc, rest_docs) {
-  if first_doc == "" {
-    return
-  }
-  run process_docs_md_recursive(first_doc, rest_docs)
-}
-
 workflow default() {
   ensure worktree_is_clean()
   const allowed_list = run build_allowed_paths_block()
   ensure docs_files_present(allowed_list)
   const docs_md_list = run list_docs_md_paths()
-  const first_doc = run first_line_str(docs_md_list)
-  const rest_docs = run rest_lines_str(docs_md_list)
-  run maybe_process_docs_md(first_doc, rest_docs)
+  for path in docs_md_list {
+    if path != "" {
+      run docs_page(path)
+    }
+  }
   run docs_overview(docs_md_list)
   ensure only_expected_docs_changed_after_prompt(allowed_list)
 }
diff --git a/QUEUE.md b/QUEUE.md
index 72264987..e077f988 100644
--- a/QUEUE.md
+++ b/QUEUE.md
@@ -48,3 +48,20 @@ When starting workflows (e.g. `jaiph run` / first step), users observe a 2–4 s
 * `npm test` passes.
 
 ***
+
+## `for … in …` — optional built-in trim / skip-empty #dev-ready
+
+**Goal**
+Evaluate optional sugar (keywords, modifiers, or a small stdlib helper) for trimming each iterated line or skipping empty lines, if authors repeatedly need shell-style normalization beyond an explicit `if line != "" { … }`.
+
+**Scope**
+
+* Baseline behavior and splitting rules are documented in `docs/language.md`.
+* If a language change is chosen, add tests and note migration for workflows that would adopt it.
+
+**Acceptance criteria**
+
+* Decision recorded in `docs/language.md` (new subsection or changelog in that doc).
+* `npm test` passes.
+
+***
diff --git a/docs/language.md b/docs/language.md
index 9fae1d15..228ed583 100644
--- a/docs/language.md
+++ b/docs/language.md
@@ -164,7 +164,7 @@ Routes (`->`) declare which workflows receive messages sent to the channel. See
 
 ### Config
 
-Optional block setting agent and run options. Allowed at module level and inside individual workflow bodies.
+Optional `config { … }` block. At **module** level it may set `agent.*`, `run.*`, `runtime.*`, and `module.*` keys (see `src/parse/metadata.ts`). A **workflow** may contain **at most one** nested `config { … }`, it must appear **before** the first step, and only **`agent.*`** and **`run.*`** are allowed there — `runtime.*` and `module.*` are rejected with `E_PARSE`.
 
 ```jaiph
 config {
@@ -182,6 +182,8 @@ See [Configuration](configuration.md) for all available keys and precedence rule
 
 Named sequences of orchestration steps. Workflows can call other workflows, scripts, prompts, and channels. Parentheses are required on definitions, even when parameterless.
 
+`jaiph run` only executes the workflow named **`default`** in the entry `.jh` file (the runner’s argv hard-codes that name today). Other workflows are reachable from steps inside the module or its imports. See the `jaiph run` sequence in [Architecture](architecture.md).
+
 ```jaiph
 workflow default() {
   ensure check_deps()
@@ -198,6 +200,14 @@ workflow deploy(env, version) {
 
 Workflows support all step types: `run`, `ensure`, `prompt`, `const`, `log`, `logerr`, `fail`, `return`, `send`, `match`, `if`, `run async`, `catch`, and `recover`.
 
+#### Inline shell lines (workflows only)
+
+Any workflow body line that does **not** parse as a managed Jaiph step is treated as **inline shell**: the text is Jaiph-interpolated, then executed with `sh -c` in the workspace (same working-directory rules as `run` on scripts — see [Script isolation](#script-isolation)). Prefer a top-level `script` and `run name()` for non-trivial shell.
+
+The compiler still inspects shell lines (for example a first word that names a local script or workflow must be written as a managed `run`/`ensure` step, not as bare shell). **`wait`** is not a step — using it is a parse error (`"wait" has been removed from the language`).
+
+**Rules cannot** contain inline shell; unstructured shell there fails validation (`inline shell steps are forbidden in rules; use explicit script blocks`).
+
 ### Rules
 
 Named blocks of structured validation steps. Rules are called with `ensure` and are meant for checks and gates.
@@ -214,7 +224,9 @@ rule gate(path) {
 }
 ```
 
-Rules are more restricted than workflows: the compiler rejects `prompt`, `send`, and `run async` in rule bodies, and `run` may only target **scripts** (never workflows or other rules via `run` — use `ensure` for rules). Those restrictions are **static** (see `validateReferences` in `src/transpile/validate.ts`). At runtime, `run` inside a rule still launches a normal managed script subprocess with the same **environment model** as workflow scripts (see [Script isolation](#script-isolation)); scripts can perform side effects — the language simply keeps orchestration-heavy steps out of rules.
+Rules are more restricted than workflows: the compiler rejects `prompt`, `send`, and `run async` in rule bodies, and `run` may only target **scripts** (never workflows or other rules via `run` — use `ensure` for rules). Rule bodies also reject `const … = prompt`. Those restrictions are **static** (see `validateReferences` in `src/transpile/validate.ts`). At runtime, `run` inside a rule still launches a normal managed script subprocess with the same **environment model** as workflow scripts (see [Script isolation](#script-isolation)); scripts can perform side effects — the language simply keeps orchestration-heavy steps out of rules.
+
+`catch` and **`recover`** on **`run`** are allowed in rules the same as in workflows. **`recover` never attaches to `ensure`** — only `run` steps support `recover`.
 
 ### Scripts
 
@@ -423,7 +435,7 @@ workflow default() {
 **Constraints:**
 - `recover` requires exactly one binding: `recover(name)`. Bare `recover` without bindings is a parse error.
 - All call arguments must appear inside parentheses **before** `recover`.
-- `recover` is available on `run` steps in workflows only (not `ensure`). `recover` also works with `run async` — see [`run async`](#run-async--concurrent-execution-with-handles).
+- `recover` is only valid on **`run`** steps (`ensure` supports `catch`, not `recover`). It is allowed in both workflow and rule bodies. `recover` also works with `run async` — see [`run async`](#run-async--concurrent-execution-with-handles).
 - `recover` and `catch` are mutually exclusive on the same step — use one or the other.
 
 ### `prompt` — Agent Interaction
@@ -666,6 +678,20 @@ workflow default(env) {
 ```
 
 
+### `for` — Iterate lines of a string
+
+```jaiph
+for line in paths_blob {
+  if line != "" {
+    run process_one(line)
+  }
+}
+```
+
+`for <identifier> in <identifier> { … }` splits the **string value** of the right-hand variable on newlines (`\r\n` is normalized to `\n`). If the string ends with a final newline, the trailing empty segment is **not** iterated (so `"a\nb\n"` yields two lines, not three). **Interior** empty lines are still yielded as empty strings. There is **no** automatic trimming of whitespace; use an `if` guard, `match`, or a script when you need to skip blanks or strip indentation.
+
+The iterator name must not conflict with an existing parameter, `const`, or capture in the same scope. After the loop completes, the iterator variable remains set to the last line visited (same shared scope as other workflow bindings).
+
 ## Inline Scripts
 
 Embed a shell command directly in a step without a named `script` definition. Single backticks for one-liners, triple backticks for multiline.
@@ -719,9 +745,7 @@ If the inline capture fails, the enclosing step fails. Nested inline captures ar
 
 **Emitted script files** do not embed module `const` values or other Jaiph “shims” — the transpiler writes the authored body plus a shebang (see `emitScriptsForModule` / `emit-script.ts`). Anything a script needs from the module must be passed as **positional arguments** (`$1`, `$2`, …), read from paths under `JAIPH_WORKSPACE`, or live in shared script sources (`import script`).
 
-**Subprocess environment (`NodeWorkflowRuntime`):** When the AST interpreter runs `run` / inline scripts, it spawns the emitted executable with the **current workflow scope environment** — a copy of the runner’s `process.env` merged with Jaiph-populated keys (`JAIPH_SCRIPTS`, `JAIPH_WORKSPACE`, `JAIPH_RUN_DIR`, `JAIPH_ARTIFACTS_DIR`, prompt-related `JAIPH_AGENT_*` variables when set, and values derived from `config { … }` via metadata). It is **not** reset to a tiny fixed allowlist; anything visible to the workflow runner is visible to child scripts unless your deployment strips the parent environment.
-
-The kernel helper `run-step-exec.ts` still uses a **minimal** env (`PATH`, `HOME`, `TERM`, `USER`, `JAIPH_SCRIPTS`, `JAIPH_WORKSPACE`) for its own **internal** `spawnSync` script-capture paths — that is not the same code path as ordinary `NodeWorkflowRuntime` `spawn()` for user `script` steps.
+**Subprocess environment (`NodeWorkflowRuntime`):** Managed **script** steps (`run` on a named script, script import, or inline `` `…` `` / fenced body), and **workflow inline shell** lines, all use the same **`scope.env`**: the runner’s `process.env` as adjusted by Jaiph (for example `JAIPH_SCRIPTS`, `JAIPH_WORKSPACE`, `JAIPH_RUN_DIR`, `JAIPH_ARTIFACTS_DIR`, prompt-related `JAIPH_AGENT_*` when set, and keys derived from `config { … }`). It is **not** reset to a small fixed allowlist; anything visible to the workflow runner is visible to child processes unless your deployment strips the parent environment.
 
 **Interpolation rules by body form:**
 

From d9922da8d760da84f9ee342833ecb52c4ee50b7e Mon Sep 17 00:00:00 2001
From: Jakub Dzikowski <jakub.t.dzikowski@gmail.com>
Date: Wed, 13 May 2026 14:56:57 +0200
Subject: [PATCH 4/5] docs: refresh site pages, README, and jaiph compile help

Update documentation across docs/* (architecture, CLI, grammar, inbox,
libraries, sandboxing, hooks, testing, and related pages). Align README
and static site snippets where needed. Clarify `jaiph compile` in
CLI usage and compile command help: validateReferences / import closure
only, without script emission or the workflow runner.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                   |   9 +++
 docs/_layouts/docs.html     |   1 +
 docs/architecture.md        |  36 +++++-----
 docs/artifacts.md           |  23 +++---
 docs/cli.md                 |  42 ++++++-----
 docs/configuration.md       |  11 +--
 docs/contributing.md        |  19 +++--
 docs/getting-started.md     |  10 +--
 docs/grammar.md             |  85 +++++++++++-----------
 docs/hooks.md               | 102 ++++++++++++++-------------
 docs/inbox.md               | 137 +++++++++++++++++-------------------
 docs/index.html             |   9 ++-
 docs/jaiph-skill.md         |  20 +++---
 docs/libraries.md           |  71 ++++++++++++++-----
 docs/sandboxing.md          |  36 +++++-----
 docs/setup.md               |  71 +++++++++++++------
 docs/spec-async-handles.md  |  65 ++++++++++-------
 docs/testing.md             |  19 +++--
 src/cli/commands/compile.ts |   6 +-
 src/cli/shared/usage.ts     |   3 +-
 20 files changed, 449 insertions(+), 326 deletions(-)

diff --git a/README.md b/README.md
index c113e01e..d4aceaa2 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,15 @@
 > [!WARNING]
 > Jaiph is still in an early stage. Expect breaking changes.
 
+## Features
+
+- **Workflows** — Compose `prompt`, `run`, `ensure`, channel sends, conditionals, `run async` with implicit join, `catch`, and repair-and-retry `recover`.
+- **Rules and scripts** — Rules stay structured (no raw shell lines); **`script`** steps run bash or polyglot code as subprocesses.
+- **Agents** — Backends include Cursor, Claude, Codex (HTTP), or a custom `agent.command`.
+- **Testing** — `*.test.jh` files run in-process (`jaiph test`) with mocks and `expect_*` assertions ([Testing](docs/testing.md)).
+- **Safety and inspectability** — Docker-backed sandbox for **`jaiph run`** (env-controlled; see [Sandboxing](docs/sandboxing.md)); live **`__JAIPH_EVENT__`** on stderr and durable **`.jaiph/runs/`** artifacts ([Architecture](docs/architecture.md)).
+- **Tooling** — `jaiph compile`, `jaiph format`, `jaiph install` / `.jaiph/libs/`, and optional `hooks.json` ([CLI](docs/cli.md), [Hooks](docs/hooks.md)).
+
 ## Core components
 
 - **CLI** (`src/cli`) — `jaiph run` / `test` / `compile` / `format` / `init` / `install` / `use`; prepares scripts, spawns the workflow runner (or in-process test runner), parses `__JAIPH_EVENT__` on stderr, runs hooks on `jaiph run` only.
diff --git a/docs/_layouts/docs.html b/docs/_layouts/docs.html
index e0d98280..bb4f5fd2 100644
--- a/docs/_layouts/docs.html
+++ b/docs/_layouts/docs.html
@@ -52,6 +52,7 @@
                 <li><a href="{{ '/cli' | relative_url }}"{% if page.permalink == '/cli' %} class="docs-nav-active" aria-current="page"{% endif %}>CLI</a></li>
                 <li><a href="{{ '/configuration' | relative_url }}"{% if page.permalink == '/configuration' %} class="docs-nav-active" aria-current="page"{% endif %}>Configuration</a></li>
                 <li><a href="{{ '/testing' | relative_url }}"{% if page.permalink == '/testing' %} class="docs-nav-active" aria-current="page"{% endif %}>Testing</a></li>
+                <li><a href="{{ '/spec-async-handles' | relative_url }}"{% if page.permalink == '/spec-async-handles' %} class="docs-nav-active" aria-current="page"{% endif %}>Async handles</a></li>
                 <li><a href="{{ '/inbox' | relative_url }}"{% if page.permalink == '/inbox' %} class="docs-nav-active" aria-current="page"{% endif %}>Inbox</a></li>
                 <li><a href="{{ '/hooks' | relative_url }}"{% if page.permalink == '/hooks' %} class="docs-nav-active" aria-current="page"{% endif %}>Hooks</a></li>
                 <li><a href="{{ '/sandboxing' | relative_url }}"{% if page.permalink == '/sandboxing' %} class="docs-nav-active" aria-current="page"{% endif %}>Sandboxing</a></li>
diff --git a/docs/architecture.md b/docs/architecture.md
index 8b8a9e2d..fa2f7b73 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -9,7 +9,7 @@ redirect_from:
 
 Jaiph is a workflow system with a **TypeScript CLI** and a **JavaScript kernel** (`src/runtime/kernel/`) that interprets the workflow AST in process — there is no separate “workflow shell” emitted for execution.
 
-This page describes **how Jaiph is built**: repository layout of major subsystems, **core components**, compile and run pipelines, and **runtime contracts** (events, artifacts on disk, distribution). It is the map of the implementation.
+This page describes **how Jaiph is built**: repository layout of major subsystems, **core components**, compile and run pipelines, and **runtime contracts** (events, artifacts on disk, distribution). It is the map of the implementation. For workflow syntax and semantics, see the [Language](language.md) guide; this document stays on implementation boundaries.
 
 For **how to contribute** — branches, test layers, E2E assertion policy, and bash harness details — see [Contributing](contributing.md). For the `*.test.jh` **language** and test blocks, see [Testing](testing.md).
 
@@ -18,7 +18,7 @@ For **how to contribute** — branches, test layers, E2E assertion policy, and b
 Workflow authors write `.jh` / `.test.jh` modules. The toolchain turns those files into **validated** modules plus **extracted script files**, then the **same AST interpreter** runs workflows whether you use local `jaiph run`, Docker, or `jaiph test`.
 
 1. Parse source into AST (the CLI parses once up front for `jaiph run` metadata such as `runtime` config; `buildRuntimeGraph` and transpilation use the same parser on disk contents).
-2. **Compile-time** validation (`validateReferences`, invoked from **`emitScriptsForModule`** / **`buildScripts()`**) runs before script extraction, not inside `buildRuntimeGraph()` (the graph loader only parses modules and follows imports). The **`jaiph compile`** command runs the same validation over files or directories without executing workflows (see `src/cli/commands/compile.ts`).
+2. **Compile-time** validation (`validateReferences`, invoked from **`emitScriptsForModule`** / **`buildScripts()`**) runs before script extraction, not inside `buildRuntimeGraph()` (the graph loader only parses modules and follows imports). The **`jaiph compile`** command runs **`validateReferences` only**: it parses each module in the computed import closure and **does not** run **`buildScriptFiles`** or **`buildScripts`**, and never spawns the runner (`src/cli/commands/compile.ts`). For a **directory** argument it discovers `*.jh` via `walkjhFiles`, which **skips** `*.test.jh`; to validate a test module, pass that file explicitly. Imported modules in the closure are still validated recursively either way.
 3. **CLI** (`dist/src/cli.js` via npm, or a **Bun-compiled** `dist/jaiph` binary) prepares script executables (scripts-only), then spawns a **detached child** that loads **`node-workflow-runner.js`**. That child calls `buildRuntimeGraph()` and runs **`NodeWorkflowRuntime`**. The child’s interpreter is **`process.execPath`** of the CLI process (Node when you run `node dist/src/cli.js`, the standalone Bun binary when you run `dist/jaiph`). Script steps execute as managed subprocesses; prompt, inbox I/O, and event/summary emission are handled by the kernel under `src/runtime/kernel/`.
 4. Stream live events to the CLI and persist durable run artifacts.
 
@@ -27,7 +27,7 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
 ## Core components
 
 - **CLI (`src/cli`)**
-  - Entry point (`run`, `test`, `compile`, `init`, `install`, `use`, `format`).
+  - Entry point (`run`, `test`, `compile`, `init`, `install`, `use`, `format`). Paths ending in `.jh` / `.test.jh` are also accepted as implicit commands (see `src/cli/index.ts`).
   - **Workflow launch** is owned in TypeScript (`src/runtime/kernel/workflow-launch.ts` + `src/cli/run/lifecycle.ts`): spawns **`node-workflow-runner.js`** with `process.execPath`, which calls `buildRuntimeGraph()` then `NodeWorkflowRuntime`. `setupRunSignalHandlers` accepts an optional `onSignalCleanup` callback for Docker sandbox teardown on SIGINT/SIGTERM.
   - Parses runtime events and renders progress; dispatches hooks.
 
@@ -39,10 +39,10 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
   - Shared compile-time schema (`jaiphModule`, step defs, test defs, hook payload types).
 
 - **Validator (`src/transpile/validate.ts`)**
-  - Resolves imports and symbol references; emits deterministic compile-time errors. Import resolution (`resolveImportPath` in `resolve.ts`) checks relative paths first, then falls back to project-scoped libraries under `<workspace>/.jaiph/libs/` — the workspace root is threaded through all compilation call sites. Export visibility is enforced by `validateRef` in `validate-ref-resolution.ts`: if an imported module declares any `export`, only exported names are reachable through the import alias.
+  - Resolves imports and symbol references; emits deterministic compile-time errors. Import resolution (`resolveImportPath` in `transpile/resolve.ts`) checks relative paths first, then falls back to project-scoped libraries under `<workspace>/.jaiph/libs/` — the workspace root is threaded through all compilation call sites. Export visibility is enforced by `validateRef` in `validate-ref-resolution.ts`: if an imported module declares any `export`, only exported names are reachable through the import alias.
 
 - **Transpiler (`src/transpiler.ts`, `src/transpile/*`)**
-  - **`emitScriptsForModule`** parses, runs **`validateReferences`**, and **`buildScriptFiles`** — the only compile path for `jaiph run` / `jaiph test` — **persists only atomic `script` files** under `scripts/`. Inline scripts (`` run `body`(args) ``) are also emitted as `scripts/__inline_<hash>` with deterministic hash-based names. There is no workflow-level bash emission.
+  - **`emitScriptsForModule`** parses, runs **`validateReferences`**, and **`buildScriptFiles`** — the only compile path for `jaiph run` / `jaiph test` — **persists only atomic `script` files** under `scripts/`. **`buildScripts()`** can also take a **directory** of non-test `*.jh` modules (`transpile/build.ts` uses `walkjhFiles`); the **`jaiph run`** and **`jaiph test`** commands always pass a **single entry file** (`.jh` or `*.test.jh`). Inline scripts (`` run `body`(args) ``) are also emitted as `scripts/__inline_<hash>` with deterministic hash-based names. There is no workflow-level bash emission.
 
 - **Node Workflow Runtime (`src/runtime/kernel/node-workflow-runtime.ts`)**
   - `NodeWorkflowRuntime` interprets the AST directly: walks workflow steps, manages scope/variables, delegates prompt and script execution to kernel helpers, handles channels/inbox/dispatch, owns the frame stack and heartbeat, and writes run artifacts.
@@ -50,13 +50,13 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
     - **`runtime-arg-parser.ts`** — stateless interpolation and call-argument parsing (`interpolate`, `parseInlineCaptureCall`, `commaArgsToInterpolated`, `parseArgsRaw`, `parseInlineScriptAt`, `parseManagedArgAt`, `parseArgTokens`, `stripOuterQuotes`, `parsePromptSchema`, `sanitizeName`, `nowIso`) plus shared constants and the `ParsedArgToken` / `PromptSchemaField` types. Direct unit tests live in `runtime-arg-parser.test.ts`.
     - **`runtime-event-emitter.ts`** — `RuntimeEventEmitter` owns the `__JAIPH_EVENT__` stderr stream and `run_summary.jsonl` writes for workflow/step/prompt/log events, plus the monotonic step and prompt sequence counters. Constructed with `{ runId, runDir, env, getFrameStack, getAsyncIndices, suppressLiveEvents? }`; the runtime delegates all event emission to it. The optional `suppressLiveEvents` flag (forwarded from `NodeWorkflowRuntime`'s `suppressLiveEvents` option) skips the live stderr write while leaving the durable `run_summary.jsonl` append intact — used by in-process callers like the test runner that share stderr with `node --test` reporter output. The CLI's spawned `node-workflow-runner` child does not set it, so production runs stream events to stderr as before.
     - **`runtime-mock.ts`** — `executeMockBodyDef` and `executeMockShellBody` for `*.test.jh` workflow/rule/script mocks. Shell-kind mocks run `bash -c`; steps-kind mocks dispatch back into the runtime via an `executeStepsBack` callback so the body runs against the full step interpreter.
-  - `buildRuntimeGraph()` (`graph.ts`) loads reachable modules with **`parsejaiph` only** (import closure); it does **not** run `validateReferences`. Cross-module refs are resolved from that graph at runtime.
+  - `buildRuntimeGraph()` (`graph.ts`) loads reachable modules with **`parsejaiph` only** (import closure); it does **not** run `validateReferences`. Cross-module refs are resolved from that graph at runtime. For **`script import`** declarations, `buildRuntimeGraph()` injects synthetic `ScriptDef` stubs (`graph.ts`) so reference resolution matches the validated compile path without re-reading external script bodies at graph-build time.
 
 - **Node Test Runner (`src/runtime/kernel/node-test-runner.ts`)**
   - Executes `*.test.jh` test blocks using `NodeWorkflowRuntime` with mock support (mock prompts, mock workflow/rule/script bodies). Pure Node harness — no Bash test transpilation.
 
 - **JS kernel (`src/runtime/kernel/`)**
-  - Prompt execution (`prompt.ts`), streaming parse (`stream-parser.ts`), schema (`schema.ts`), mocks (`mock.ts`), **`emit.ts`** (live `__JAIPH_EVENT__` + `run_summary.jsonl`), **`workflow-launch.ts`** (spawn contract). Script subprocesses are launched directly from `NodeWorkflowRuntime`.
+  - Prompt execution (`prompt.ts`), streaming parse (`stream-parser.ts`), schema (`schema.ts`), mocks (`mock.ts`), **`emit.ts`** (durable **`run_summary.jsonl`** helpers — `appendRunSummaryLine`, `formatUtcTimestamp` — consumed by `RuntimeEventEmitter`), **`workflow-launch.ts`** (spawn contract). **`RuntimeEventEmitter`** (`runtime-event-emitter.ts`) owns live **`__JAIPH_EVENT__`** lines on stderr and coordinates summary writes plus step/prompt sequence counters. Script subprocesses are launched directly from `NodeWorkflowRuntime`.
 
 - **Formatter (`src/format/emit.ts`)**
   - `jaiph format` rewrites `.jh` / `.test.jh` files into canonical style. Pure AST→text emitter; no side-effects beyond file writes.
@@ -73,7 +73,7 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
 - Manage channels (`send`, routes, queue drain) through kernel logic.
 - Emit step/log events; persist run logs and summary timeline.
 - Prompt steps and managed script subprocesses: Node kernel owns execution, events, and control flow.
-- Execute test blocks with mock support (`NodeTestRunner`).
+- Execute test blocks with mock support (`runTestFile()` in `node-test-runner.ts`).
 
 ### CLI responsibilities
 
@@ -99,19 +99,19 @@ The runtime persists step captures and the event timeline under a UTC-dated hier
   <YYYY-MM-DD>/                       # UTC date (see NodeWorkflowRuntime)
     <HH-MM-SS>-<source-basename>/       # UTC time + JAIPH_SOURCE_FILE or entry basename
       000001-module__step.out          # stdout capture per step (6-digit seq prefix)
-      000001-module__step.err          # stderr capture (when non-empty)
+      000001-module__step.err          # stderr capture (may be empty)
       artifacts/                       # user-published files (JAIPH_ARTIFACTS_DIR); created at run start
-      inbox/                           # inbox message files (when channels are used)
+      inbox/                           # audit copies of routed channel payloads (optional)
       heartbeat                        # liveness: epoch ms, refreshed about every 10s
       return_value.txt                 # when `jaiph run` default workflow returns a value (success only)
       run_summary.jsonl                # durable event timeline
 ```
 
-Step sequence numbers are monotonic and unique per run: `NodeWorkflowRuntime` allocates them in memory when opening each step’s capture files (`%06d-<safe_name>.out|.err`). There is no `.seq` file in the run directory.
+Step sequence numbers are monotonic and unique per run: `RuntimeEventEmitter` allocates them in memory (`allocStepSeq`) when opening each step’s capture files (`%06d-<safe_name>.out|.err`). There is no `.seq` file in the run directory.
 
 ## Channels and hooks in context
 
-Channels are validated at compile time (`validateReferences` / send RHS rules) and executed via in-memory queue and dispatch in the Node runtime; durable inbox files under the run directory are for audit and reporting. See [Inbox & Dispatch](inbox.md). Hooks are CLI-only: they load from `hooks.json` and run as shell commands with JSON on stdin, driven by the same `__JAIPH_EVENT__` stream as the progress UI — see [Hooks](hooks.md).
+Channels are validated at compile time (`validateReferences` / send RHS rules) and executed via in-memory queue and dispatch in the Node runtime; durable **`inbox/`** files under the run directory appear only for **routed** sends (audit — see [Inbox & Dispatch](inbox.md)). Hooks are CLI-only: they load from `hooks.json` and run as shell commands with JSON on stdin, driven by the same `__JAIPH_EVENT__` stream as the progress UI — see [Hooks](hooks.md).
 
 ## Test runner integration (`*.test.jh` in the kernel)
 
@@ -122,7 +122,7 @@ Authoring rules, fixtures, and mock syntax for `*.test.jh` are documented in [Te
 
 ## CLI progress reporting pipeline
 
-Static tree from AST (`progress.ts`); runtime events (`events.ts`, `stderr-handler.ts`); emitter (`emitter.ts`); display (`display.ts`, `progress.ts`). Async branch numbering (subscript ₁₂₃… prefixes) is driven by `async_indices` on step and log events — the runtime propagates a chain of 1-based branch indices through `AsyncLocalStorage`, and the stderr handler renders them at the appropriate indent level. `const` steps whose value is a `match_expr` are walked for nested `run`/`ensure` arms; matched targets appear as child items in the step tree (e.g. `▸ script safe_name` under the `const` row).
+The progress UI combines a **static** step tree derived from the workflow AST (`cli/run/progress.ts`) with **live** updates from the runtime event stream. Event wiring: `events.ts` and `stderr-handler.ts` parse `__JAIPH_EVENT__` lines; `emitter.ts` bridges into the renderer. Line-oriented formatting (`formatStartLine`, `formatHeartbeatLine`, `formatCompletedLine`) lives primarily in `display.ts`, which shares some display helpers with `progress.ts`. Async branch numbering (subscript ₁₂₃… prefixes) is driven by `async_indices` on step and log events — the runtime propagates a chain of 1-based branch indices through `AsyncLocalStorage`, and the stderr handler renders them at the appropriate indent level. `const` steps whose value is a `match_expr` are walked for nested `run`/`ensure` arms; matched targets appear as child items in the step tree (e.g. `▸ script safe_name` under the `const` row).
 
 ## Distribution: Node vs Bun standalone
 
@@ -147,7 +147,7 @@ flowchart TD
     CLI -->|jaiph run| BS1[buildScripts]
     BS1 --> Transpile
 
-    CLI -->|jaiph test| BS2[buildScripts workspace]
+    CLI -->|jaiph test| BS2[buildScripts(entry .test.jh)]
     BS2 --> Transpile
     BS2 --> TR[Node Test Runner in-process]
 
@@ -166,7 +166,7 @@ flowchart TD
     TR --> RT
 
     RT -->|script steps| SCRIPT[Managed script subprocesses]
-    RT -->|prompt steps| KERNEL[JS kernel: prompt / emit / inbox / stream / schema / mock]
+    RT -->|prompt steps| KERNEL[Kernel libs: prompt, events, inbox, stream, schema, mock]
 
     RT -->|live events| EV["__JAIPH_EVENT__ stderr only"]
     EV --> CLI
@@ -226,7 +226,7 @@ sequenceDiagram
     participant User
     participant CLI as CLI jaiph test
     participant Parser as parsejaiph
-    participant Prep as buildScripts workspace
+    participant Prep as buildScripts(test file)
     participant TestRunner as runTestFile / runTestBlock
     participant Graph as buildRuntimeGraph
     participant Runtime as NodeWorkflowRuntime
@@ -235,7 +235,7 @@ sequenceDiagram
     User->>CLI: jaiph test flow.test.jh
     CLI->>Parser: parse test file
     Parser-->>CLI: jaiphModule + tests[] blocks
-    CLI->>Prep: buildScripts(workspace) workspace .jh only
+    CLI->>Prep: buildScripts(test path, tmp) import closure
     Prep-->>CLI: scriptsDir
     CLI->>TestRunner: runTestFile(test path workspace scriptsDir blocks)
     TestRunner->>Graph: buildRuntimeGraph(test file) once per file
@@ -256,7 +256,7 @@ sequenceDiagram
 ## Summary
 
 - `.jh` / `*.test.jh` share parser/AST; **compile-time** validation runs in **`emitScriptsForModule`** during **`buildScripts`**. **`buildRuntimeGraph`** loads modules with **parse-only** imports.
-- **`jaiph compile`** walks the same import closures as a normal compile check, runs **`validateReferences`** on each module, and exits — no **`buildScriptFiles`** emission, no **`buildScripts`**, no runner spawn.
+- **`jaiph compile`** walks import closures **`validateReferences` only**, and exits — no **`buildScriptFiles`** emission, no **`buildScripts`**, no runner spawn. Directory discovery omits **`*.test.jh`** unless you pass a test file explicitly.
 - **Node-only runtime:** all execution — local `jaiph run`, Docker `jaiph run`, and `jaiph test` — goes through `NodeWorkflowRuntime`. Docker containers run `node-workflow-runner` with the compiled JS tree and scripts mounted, using the same semantics as local execution.
 - **CLI** owns launch, observation, hooks, and runtime preparation (`buildScripts`). Workflow execution runs in **`NodeWorkflowRuntime`**, with **script steps** as managed subprocesses.
 - No workflow-level `.sh` files or `jaiph_stdlib.sh` are produced or required.
diff --git a/docs/artifacts.md b/docs/artifacts.md
index 23ecab86..af9d6e50 100644
--- a/docs/artifacts.md
+++ b/docs/artifacts.md
@@ -9,7 +9,7 @@ redirect_from:
 
 Workflow and test runners need two kinds of output: **what humans see right now** (progress, status) and **what is left behind** after the process exits (replay, diffs, CI reports). Jaiph keeps those separate: the **live** channel is `__JAIPH_EVENT__` JSON lines on the child process’s **stderr**; the **durable** side is a tree of files under the project workspace so you can inspect, diff, and archive a run after it finishes.
 
-When you run a workflow, or `jaiph test` executes workflows inside test blocks, the **Node** workflow runtime materializes that durable tree. By default it lives at `<workspace>/.jaiph/runs/`; you can point it elsewhere with `run.logs_dir` / `JAIPH_RUNS_DIR` (see [Configuration — Run keys](configuration.md#run-keys)). The layout below is what `NodeWorkflowRuntime` writes.
+When you run a workflow, or `jaiph test` executes workflows inside test blocks, **`NodeWorkflowRuntime`** materializes that durable tree. By default it lives at `<workspace>/.jaiph/runs/`; you can point it elsewhere with `run.logs_dir` / `JAIPH_RUNS_DIR` (see [Configuration — Run keys](configuration.md#run-keys)). The layout below matches what `NodeWorkflowRuntime` creates at startup (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) for where this fits in the overall pipeline). In Docker mode, paths inside recorded events may use container prefixes (`/jaiph/run/…`); the CLI maps them to host paths when reporting failures — see [Sandboxing — Path remapping](sandboxing.md#path-remapping).
 
 ## Run directory layout
 
@@ -20,24 +20,29 @@ The runtime uses a UTC-dated hierarchy. Each run gets its own folder: UTC date,
   <YYYY-MM-DD>/                       # UTC date (see NodeWorkflowRuntime)
     <HH-MM-SS>-<source-basename>/       # UTC time + basename (see above)
       000001-module__step.out          # stdout capture per step (6-digit seq prefix)
-      000001-module__step.err          # stderr capture (when non-empty)
+      000001-module__step.err          # stderr capture (may be empty)
       artifacts/                       # user-published files (`jaiphlang/artifacts`); `JAIPH_ARTIFACTS_DIR`
-      inbox/                           # inbox message files (when channels are used)
+      inbox/                           # audit copies of routed channel payloads (optional)
       heartbeat                        # liveness: epoch ms, refreshed about every 10s
       return_value.txt                 # present if `default` workflow exited 0 and returned a value
       run_summary.jsonl                # durable event timeline (JSON Lines)
 ```
 
-Sequence numbers in those filenames are **monotonic and unique** per run: a single in-memory counter in `NodeWorkflowRuntime` increments for each step capture. The separate `seq-alloc` helper is a **file-backed** allocator for tooling; ordinary runs do not use a `.seq` file in the run directory. For the full system picture, see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) and [Architecture — Contracts](architecture.md#contracts) (`__JAIPH_EVENT__` on stderr is the live path).
+Sequence numbers in those filenames are **monotonic and unique** per run. `RuntimeEventEmitter` owns a single in-memory counter (`allocStepSeq`) that advances whenever a step needs paired capture files — managed steps (`script`, nested `workflow` / `rule`, single-line `shell`, and similar) and `prompt` steps that write transcripts all draw from the same sequence. There is **no** `.seq` file in the run directory. For the live vs durable split, see [Architecture — Contracts](architecture.md#contracts): `__JAIPH_EVENT__` on stderr is the streaming path; `run_summary.jsonl` is the durable timeline.
 
 ## What each artifact is for
 
-- **`*.out` / `*.err`** — Per-step capture files for managed work (script subprocesses, nested workflows, rules, and prompt steps). **Stdout** is written to a `.out` file as the step runs; a **`.err` file appears when stderr is non-empty** (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout)). The live CLI stream is still separate: see [Architecture — Contracts](architecture.md#contracts).
-- **`run_summary.jsonl`** — JSON Lines timeline mirroring what also goes to `__JAIPH_EVENT__` (where enabled): workflow boundaries, step start/end, log lines, inbox-related events. The file is created at runtime startup and lines are appended as the run progresses.
-- **`inbox/`** — When you use channels, copies of message payloads can appear here for inspection (see [Inbox & Dispatch](inbox.md)).
+- **`*.out` / `*.err`** — Paired capture files for steps that record subprocess or prompt I/O. The runtime creates both paths at **`STEP_START`**. For **managed** steps (extracted scripts, nested workflows/rules, single-line `shell`, and similar), stdout/stderr are **streamed** into the files during execution, then **rewritten** with the final aggregated strings at step end — so a long-running step’s `.out` can be tailed while it runs (see [CLI — Run artifacts and live output](cli.md#run-artifacts-and-live-output)). **Prompt** steps stream the model transcript into `.out`; `.err` is only overwritten when stderr from the backend is non-empty (otherwise the placeholder file stays zero-length). **Errors and CLI progress** still use the live `__JAIPH_EVENT__` stream on stderr; these files are the on-disk record.
+
+- **`run_summary.jsonl`** — Append-only JSON Lines timeline: workflow boundaries, step start/end, `LOG` / `LOGERR`, prompt lifecycle, inbox events, and the same step payload fields as the live stream. It is **truncated to empty at runtime startup**, then each event appends a line via `appendRunSummaryLine` as execution proceeds. **Note:** the in-process test runner can set `suppressLiveEvents`, which **stops** `__JAIPH_EVENT__` lines from going to stderr while **`run_summary.jsonl` keeps updating** (see [Architecture — Core components](architecture.md#core-components), `RuntimeEventEmitter`).
+
+- **`inbox/`** — When channels are used, **routed** `send` steps may persist a copy of the payload here (`NNN-<channel>.txt`) for audit. Files are created **only if** the send resolves to a context that has dispatch routes for that channel (no file for unrouted sends — see `NodeWorkflowRuntime` send handling and [Inbox & Dispatch](inbox.md)). Delivery stays in-memory; this directory is not a mailbox API.
+
 - **`heartbeat`** — Best-effort file containing a wall-clock millisecond timestamp, rewritten on a timer (~10s). Liveness for external watchdogs; not required for normal CLI use.
-- **`return_value.txt`** — Written after a successful `default` workflow when the workflow returns a value (including empty string, which yields a zero-length file so it is distinct from “no return”). Other entry paths (e.g. `test_run_workflow`) are not required to create this file.
-- **`artifacts/`** — The runtime creates this directory in the run folder before execution and sets `JAIPH_ARTIFACTS_DIR` to it (along with `JAIPH_RUN_DIR`, `JAIPH_RUN_ID`, and `JAIPH_RUN_SUMMARY_FILE`). User code typically writes here via the `jaiphlang/artifacts` library (`artifacts.save`). In Docker mode this directory is under the **host-writable** run mount (`/jaiph/run/...` in the container), not the read-only workspace overlay. See [Libraries — `jaiphlang/artifacts`](libraries.md#jaiphlangartifacts--publishing-files-out-of-the-sandbox) and [Sandboxing](sandboxing.md).
+
+- **`return_value.txt`** — Written after a successful **`default`** workflow when `executeWorkflow` reports a defined `returnValue` (including `""`, which produces a zero-length file — distinct from “no file / no return”). **`runNamedWorkflow`** (used by `test_run_workflow` and similar) does not write this file by that path.
+
+- **`artifacts/`** — Created before steps run. The runtime sets **`JAIPH_ARTIFACTS_DIR`**, **`JAIPH_RUN_DIR`**, **`JAIPH_RUN_SUMMARY_FILE`**, and **`JAIPH_RUN_ID`** (a new UUID when `JAIPH_RUN_ID` was not already set in the environment). User workflows usually publish into this directory through **`jaiphlang/artifacts`** (`artifacts.save`). In Docker mode it sits under the **host-writable** run mount (`/jaiph/run/...` inside the container), not the read-only workspace overlay. See [Libraries — `jaiphlang/artifacts`](libraries.md#jaiphlangartifacts--publishing-files-out-of-the-sandbox) and [Sandboxing](sandboxing.md).
 
 ## Keeping runs out of git
 
diff --git a/docs/cli.md b/docs/cli.md
index a5258692..7b633af9 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,15 +9,17 @@ redirect_from:
 
 Jaiph is a workflow system: authors write `.jh` modules, and a **TypeScript CLI** prepares scripts, launches a **Node workflow runtime**, and surfaces progress while the **JavaScript kernel** executes the AST in process (no separate workflow shell). The CLI is what you install as the `jaiph` binary — it is the boundary between your terminal or CI and the interpreter.
 
-This page lists **commands**, important **flags**, and **environment variables**. It focuses on how the tool behaves, not on the language itself. For syntax and step semantics, see [Grammar](grammar.md). For repository layout, pipelines, and contracts (`__JAIPH_EVENT__`, artifacts, Docker vs local), see [Architecture](architecture.md).
+This page lists **commands**, important **flags**, and **environment variables**. It focuses on how the tool behaves, not on the language itself. For semantics and the overall language model, see [Language](language.md). For concrete syntax rules (imports, orchestration strings, managed calls, …), see [Grammar](grammar.md). For repository layout, pipelines, and contracts (`__JAIPH_EVENT__`, artifacts, Docker vs local), see [Architecture](architecture.md).
 
 **Commands:** `run`, `test`, `compile`, `format`, `init`, `install`, `use`.
 
-**Global options:** `-h` / `--help` and `-v` / `--version` are recognized only as the **first token after `jaiph`** (e.g. `jaiph --help`). They are not treated as global flags after a subcommand or a file path (`jaiph run --help` is **not** usage — use `jaiph --help`, or `jaiph compile -h` for compile-specific usage).
+**Global options:** `-h` / `--help` and `-v` / `--version` are recognized only as the **first token after `jaiph`** (e.g. `jaiph --help`). They are not treated as global flags after a subcommand or a file path (`jaiph run --help` is **not** usage — use `jaiph --help`, or **`jaiph compile -h`** / **`jaiph compile --help`** for compile-specific usage — the `compile` command parses `-h` / `--help` after the subcommand). Running **`jaiph`** with no arguments prints the same overview and exits **0**.
 
 ## File shorthand
 
-If the first argument is an existing file, Jaiph routes it automatically based on the extension. Files ending in **`*.test.jh`** are run as tests (same as `jaiph test <file>`). Other files ending in **`*.jh`** are run as workflows (same as `jaiph run <file>`). The `*.test.jh` check happens first, so test files are never mistaken for workflows.
+If the **first argument after `jaiph`** is an **existing path** (resolved relative to the current working directory), Jaiph routes it automatically based on the extension. Files ending in **`*.test.jh`** are run as tests (same as `jaiph test <file>`). Other paths ending in **`.jh`** are run as workflows (same as `jaiph run <file>`). The `*.test.jh` check happens first, so test modules are never mistaken for workflows.
+
+Additional positional tokens after a **workflow** shorthand are forwarded to **`workflow default`**, matching `jaiph run`. Tokens after a **test** shorthand are accepted but **ignored** (same as `jaiph test <file>` with extra arguments).
 
 ```bash
 # Workflow shorthand
@@ -45,7 +47,7 @@ Any path ending in `.jh` is accepted (including `*.test.jh`, since the extension
 **Flags:**
 
 - **`--target <dir>`** — keep emitted script files and run metadata under `<dir>` instead of a temp directory (useful for debugging).
-- **`--raw`** — skip the banner, live progress tree, hooks, and CLI failure footer. The workflow runner child uses **inherited stdio** so `__JAIPH_EVENT__` JSON lines go to **stderr** unchanged. The **host** CLI relies on this for Docker-backed runs (the container invokes `jaiph run --raw` so the host parses events from Docker’s stderr); you can also use it when embedding Jaiph in another tool. See [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
+- **`--raw`** — skip the banner, live progress tree, hooks, and CLI failure footer. The workflow runner child uses **inherited stdio** so `__JAIPH_EVENT__` JSON lines go to **stderr** unchanged. The **host** CLI relies on this for Docker-backed runs (the container invokes `jaiph run --raw` so the host parses events from Docker’s stderr); you can also use it when embedding Jaiph in another tool. There is no PASS/FAIL line, **`return_value.txt` is not printed to stdout**, and the process exit code alone reflects success or failure. See [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
 - **`--`** — end of Jaiph flags; remaining args are passed to `workflow default` (e.g. `jaiph run file.jh -- --verbose`).
 
 **Examples:**
@@ -73,7 +75,7 @@ workflow default() {
 }
 ```
 
-Workflow and rule bodies contain structured Jaiph steps only — use `run` to call a `script` for shell execution. In bash-bearing contexts (mainly `script` bodies, and restricted `const` / send RHS forms), `$(...)` and the first command word are validated: they must not invoke Jaiph rules, workflows, or scripts, contain inbox send (`<-`), or use `run` / `ensure` as shell commands (`E_VALIDATE`). See [Grammar — Managed calls vs command substitution](grammar.md#managed-calls-vs-command-substitution).
+**Rule** bodies are **managed steps only** — no raw shell lines; use `run` to a `script` for shell execution. **Workflow** bodies may include **inline shell** lines that do not parse as a Jaiph step (the compiler still validates them); for anything non-trivial, prefer a top-level `script` and `run`. In bash-bearing contexts (mainly `script` bodies, and restricted `const` / send RHS forms), `$(...)` and the first command word are validated: they must not invoke Jaiph rules, workflows, or scripts, contain inbox send (`<-`), or use `run` / `ensure` as shell commands (`E_VALIDATE`). See [Grammar — Language concepts](grammar.md#language-concepts) and [Grammar — Managed calls vs command substitution](grammar.md#managed-calls-vs-command-substitution).
 
 For `const` in those bodies, a reference plus arguments on the RHS must be written as `const name = run ref([args...])` (or `ensure` for rule capture), not as `const name = ref([args...])` — the latter is `E_PARSE` with text that explains the fix.
 
@@ -107,6 +109,8 @@ The root PASS/FAIL summary uses the format `✓ PASS workflow default (0.2s)`. C
 
 **TTY mode:** one extra line at the bottom shows the running workflow and elapsed time: `▸ RUNNING workflow <name> (X.Xs)` — updated in place every second. When the run completes, it is replaced by the final PASS/FAIL line.
 
+**Successful exit:** when the default workflow exits **0**, the CLI prints `✓ PASS workflow default (...)` plus elapsed time (see above). If the workflow **returns** a value, the runtime writes `return_value.txt` under the run directory; the CLI prints that value on stdout **after** the PASS line, separated by a blank line (host paths are unchanged; Docker runs remap container paths when reading the file). See [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout).
+
 **Non-TTY mode** (CI, pipes, log capture): no RUNNING line and no in-place updates. Step start (▸) and completion (✓/✗) lines still print as they occur. Long-running steps additionally print **heartbeat** lines to avoid looking like a hang:
 
 - Format: `· <kind> <name> (running <N>s)` — entire line dim/gray (plain text with `NO_COLOR`).
@@ -272,16 +276,16 @@ Parse modules and run **`validateReferences`** (the same compile-time checks as
 jaiph compile [--json] [--workspace <dir>] <file.jh | directory> ...
 ```
 
-At least one path is required.
+At least one path is required. **`jaiph compile -h`** or **`jaiph compile --help`** prints command-specific usage and exits **0**.
 
 **File arguments** — Each `*.jh` file is expanded to its **transitive import closure**; every module in the union is parsed and validated once.
 
-**Directory arguments** — The tree is scanned for `*.jh` files whose basename is **not** `*.test.jh`; each such file is treated as an entrypoint and its closure merged into the same validation set. To validate a test module’s graph explicitly, pass that **`*.test.jh` file** as a path (directories never pick up `*.test.jh` as roots).
+**Directory arguments** — The tree is scanned for `*.jh` files whose basename is **not** `*.test.jh` (same rule as `walkjhFiles` in the transpiler: files like `foo.test.jh` are skipped). Each non-test `*.jh` under the tree is treated as an entrypoint and its closure merged into the same validation set. To validate a test module’s graph explicitly, pass that **`*.test.jh` file** as a path (directories never pick up `*.test.jh` as roots).
 
 **Flags:**
 
 - **`--json`** — On success, print `[]` to stdout. On failure, print one JSON **array** of objects `{ "file", "line", "col", "code", "message" }` to stdout and exit **1** (non-JSON errors use a synthetic `E_COMPILE` object when the message is not in `file:line:col CODE …` form).
-- **`--workspace <dir>`** — Override the workspace root used for **library import resolution** (`<workspace>/.jaiph/libs/`, etc.) for all derived paths. When omitted, the workspace is auto-detected per file the same way as `jaiph run`.
+- **`--workspace <dir>`** — Override the workspace root used for **library import resolution** (`<workspace>/.jaiph/libs/`, etc.) for **all** modules reached from the given paths. When omitted, the workspace is **auto-detected** from each path’s location (`detectWorkspaceRoot` — same algorithm as `jaiph run`, starting from the file’s directory or from a directory argument).
 
 ## `jaiph format`
 
@@ -327,22 +331,22 @@ Creates:
 
 - `.jaiph/.gitignore` — lists `runs` and `tmp`. If the file already exists and does not match this exact list, `jaiph init` exits with a non-zero status.
 - `.jaiph/bootstrap.jh` — canonical bootstrap workflow; made executable. The template uses a triple-quoted multiline prompt body (`prompt """ ... """`) so the generated file parses and compiles as valid Jaiph. It asks the agent to scaffold workflows under `.jaiph/` and ends by logging a summary (`WHAT CHANGED` + `WHY`). Docker sandboxing uses the default `ghcr.io/jaiphlang/jaiph-runtime` image unless you set `runtime.docker_image` or `JAIPH_DOCKER_IMAGE`.
-- `.jaiph/SKILL.md` — copied from the skill file bundled with your Jaiph installation (or from `JAIPH_SKILL_PATH` when set). If no skill file is found, this file is not written and a note is printed.
+- `.jaiph/SKILL.md` — copied from the skill file bundled with your Jaiph installation. If **`JAIPH_SKILL_PATH`** is set, that path is used **only when it exists on disk**; otherwise the CLI searches known install-relative locations and `docs/jaiph-skill.md` from the current directory. If no file is found, `SKILL.md` is not written and a note is printed.
 
 ## `jaiph install`
 
-Install project-scoped libraries. Libraries are git repos cloned into `.jaiph/libs/<name>/` under the workspace root. A lockfile (`.jaiph/libs.lock`) tracks installed libraries for reproducible setups.
+Install project-scoped libraries. Libraries are git repos cloned into `.jaiph/libs/<name>/` under the **workspace root**. The workspace is determined from the **current working directory** (`detectWorkspaceRoot(process.cwd())` — walk upward until `.jaiph` or `.git`, with the same temp-directory guards as `jaiph run`). A lockfile (`.jaiph/libs.lock`) under that root tracks installed libraries for reproducible setups.
 
 ```bash
 jaiph install [--force] <repo-url[@version]> ...
 jaiph install [--force]
 ```
 
-**With arguments** — clone each repo into `.jaiph/libs/<name>/` (shallow: `--depth 1`) and upsert the entry in `.jaiph/libs.lock`. The library name is derived from the URL: last path segment, stripped of `.git` suffix (e.g. `github.com/you/queue-lib.git` → `queue-lib`). Version pinning uses `@<tag-or-branch>` after the URL.
+**With arguments** — clone each repo into `.jaiph/libs/<name>/` (shallow: `--depth 1`) and upsert the entry in `.jaiph/libs.lock`. The library name is derived from the URL: last path segment, stripped of `.git` suffix (e.g. `github.com/you/queue-lib.git` → `queue-lib`). Version pinning is usually written as **`https://…/name.git@<tag-or-branch>`**; other URL shapes with a trailing **`@ref`** are also accepted when the parser can split URL and version unambiguously.
 
-**Without arguments** — restore all libraries from `.jaiph/libs.lock`. Useful after cloning a project or in CI.
+**Without arguments** — restore all libraries from `.jaiph/libs.lock`. Useful after cloning a project or in CI. If the lockfile exists but lists **no** libraries, the command prints `No libs in lockfile.` and exits **0**.
 
-If `.jaiph/libs/<name>/` already exists, the library is skipped. Use `--force` to delete and re-clone.
+If `.jaiph/libs/<name>/` already exists, the library is skipped. Use **`--force`** (anywhere in the argument list) to delete and re-clone.
 
 **Lockfile format** (`.jaiph/libs.lock`):
 
@@ -408,14 +412,16 @@ These variables apply to `jaiph run` and workflow execution. Variables marked **
 
 **Internal variables:**
 
-- `JAIPH_META_FILE` — path to the metadata file the CLI writes under the build output directory; the workflow runner reads it after exit. Set by the launcher on the child process; `resolveRuntimeEnv` removes any inherited value from the parent.
-- `JAIPH_RUN_DIR`, `JAIPH_RUN_ID`, `JAIPH_RUN_SUMMARY_FILE` — `JAIPH_RUN_ID` is generated by the host CLI as a UUID per `jaiph run` invocation and forwarded to the runtime (and into the Docker container when sandboxed). The runtime uses this value as the workflow run identifier; if unset, the runtime generates its own UUID. `JAIPH_RUN_DIR` and `JAIPH_RUN_SUMMARY_FILE` are set by `NodeWorkflowRuntime` to the run directory and `run_summary.jsonl` path.
-- `JAIPH_SOURCE_FILE` — set automatically by the CLI to the entry file basename. Used to name run directories.
+- `JAIPH_META_FILE` — path to the run metadata file (under the CLI’s build output directory for that invocation). Set on the **detached workflow child** only; the parent strips any inherited value so leftover exports do not collide. The runner writes `run_dir=` / `summary_file=` lines for the host to read after exit.
+- `JAIPH_SOURCE_ABS` — absolute path to the entry `.jh` file; set by the CLI for **`jaiph run`** before spawn. Required by the runner (local and Docker).
+- `JAIPH_SCRIPTS` — directory containing emitted **`script`** files for this run; set after **`buildScripts()`**. Any **`JAIPH_SCRIPTS`** exported in the parent shell is cleared before launch so nested toolchains do not point at the wrong tree.
+- `JAIPH_RUN_DIR`, `JAIPH_RUN_ID`, `JAIPH_RUN_SUMMARY_FILE` — for a normal (**non-raw**) **`jaiph run`**, the host generates **`JAIPH_RUN_ID`** once per invocation (UUID), passes it through to the detached child (and into Docker when sandboxed), and Docker failure-path discovery can match summaries by this id. The runtime uses **`JAIPH_RUN_ID`** as the stable run identifier; if it is absent, the runtime may assign its own UUID. **`JAIPH_RUN_DIR`** and **`JAIPH_RUN_SUMMARY_FILE`** are set inside the runner once the UTC run directory exists.
+- `JAIPH_SOURCE_FILE` — set automatically by the CLI to the entry file **basename**. Used to name run directories (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout)).
 
 **Workspace and run paths:**
 
 - `JAIPH_WORKSPACE` — workspace root, set by the CLI. Detected by walking up from the entry `.jh` file's directory until `.jaiph` or `.git` is found. Guards in `detectWorkspaceRoot` skip misleading markers under shared system temp directories (`/tmp`, `/var/tmp`, macOS `/var/folders/.../T/...`) and nested `.jaiph/tmp` trees. In Docker sandbox mode the runtime remaps it inside the container (see [Sandboxing](sandboxing.md)).
-- `JAIPH_RUNS_DIR` — root directory for run logs (default: `.jaiph/runs` under workspace).
+- `JAIPH_RUNS_DIR` — root directory for run logs. If unset in the environment, the CLI merges the entry module **`config`** field **`run.logs_dir`** (when present) into the spawned process environment; otherwise the default layout is `.jaiph/runs` under the workspace. Exporting **`JAIPH_RUNS_DIR` yourself locks that choice: in-file **`run.logs_dir`** cannot override an environment-provided value.
 
 **Agent and prompt configuration:**
 
@@ -461,4 +467,4 @@ For overlay vs copy workspace mode, mounts, and stderr wiring, see [Sandboxing](
 
 ### `jaiph init`
 
-- `JAIPH_SKILL_PATH` — path to the skill markdown copied to `.jaiph/SKILL.md` when running `jaiph init`.
+- `JAIPH_SKILL_PATH` — absolute or relative path to the skill markdown copied to `.jaiph/SKILL.md` when running `jaiph init`. The file **must exist**; otherwise this variable is ignored and the default search runs.
diff --git a/docs/configuration.md b/docs/configuration.md
index 85dbf640..88d04b51 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -11,7 +11,7 @@ When you need the same workflow sources to behave differently on different machi
 
 All execution is interpreted by the Node workflow runtime (`NodeWorkflowRuntime`): the AST, managed scripts, prompts, channels, inbox, and `.jaiph/runs` artifacts (see [Architecture](architecture.md)). Configuration only adjusts that stack; it does not change the workflow language or the compile graph.
 
-`jaiph compile` and `buildScripts()` use the same parser, so **unknown `config` keys and wrong value types** fail with deterministic parse errors. Runtime graph loading is parse-only; **compile-time** validation of references runs in the transpile path, not in `buildRuntimeGraph()` (see [Architecture — Summary](architecture.md#summary)).
+`jaiph compile` parses each module in the import closure (same grammar as `buildScripts()`), so **unknown `config` keys and wrong value types** produce the same parse errors as a normal build. `jaiph compile` then runs **`validateReferences` only** — it does not emit scripts or spawn the runner (see [Architecture](architecture.md#summary)). Runtime graph loading is parse-only; **compile-time** reference validation runs in the transpile path, not in `buildRuntimeGraph()`.
 
 **Source of truth:** When this document and the implementation disagree, treat the source code as authoritative.
 
@@ -27,6 +27,8 @@ For **agent and run keys**, the full precedence chain is:
 
 > **environment > workflow-level config > module-level config > defaults**
 
+`run.recover_limit` is an exception: only **module-level** values affect `run … recover` (see [Run keys](#run-keys)).
+
 For **`runtime.*` (image, network, timeout)**, the CLI merges at **`jaiph run` launch** — not inside `NodeWorkflowRuntime` — in the order **`JAIPH_DOCKER_*` environment > in-file `runtime.*` > defaults** (and separately: Docker on/off is env-only, see above and [Precedence in detail](#precedence-in-detail)). `runtime.*` cannot appear in workflow-level `config` blocks.
 
 ## In-file config blocks
@@ -98,7 +100,8 @@ workflow default() {
 
 - At most one per workflow; it must be the first non-comment construct in the body. A duplicate is `E_PARSE`: `duplicate config block inside workflow (only one allowed per workflow)`.
 - Only **`agent.*` and `run.*` keys** are allowed. Any `runtime.*` or `module.*` key is `E_PARSE`.
-- Workflow-level values apply to all steps in that workflow, including `ensure`d rules and scripts called from it. When the workflow finishes, the previous environment is restored.
+- Workflow-level values apply to all steps in that workflow, including `ensure`d rules and scripts called from it, for **`agent.*`** and **`run.logs_dir`** / **`run.debug`** (merged when the workflow or cross-module `ensure` runs). **`run.recover_limit` is different:** the retry limit for `run … recover` comes only from the **module-level** `config` of the **`.jh` file that owns the current scope** when the step runs; a workflow-level `run.recover_limit` assignment is valid syntax but does **not** change recover behavior today.
+- When the workflow finishes, the previous environment is restored.
 
 **Sibling isolation:** Each workflow gets its own clone of the parent environment. Sibling workflows never see each other's config — even when they execute sequentially. If workflow `alpha` sets `agent.backend = "claude"` and workflow `beta` only sets `agent.default_model = "beta-model"`, `beta` still sees the module-level backend (e.g. `"cursor"`), not `alpha`'s.
 
@@ -134,7 +137,7 @@ These control runtime behavior unrelated to the agent.
 |-----|------|---------|--------------|-------------|
 | `run.logs_dir` | string | `.jaiph/runs` | `JAIPH_RUNS_DIR` | Step log directory. Relative paths are joined with the workspace root; absolute paths are used as-is. |
 | `run.debug` | boolean | `false` | `JAIPH_DEBUG` | Enables debug tracing for the run. |
-| `run.recover_limit` | integer | `10` | _(no env override)_ | Maximum number of retry attempts for `run … recover` loops before the step fails. See [Language — `recover`](language.md#recover--repair-and-retry-loop). |
+| `run.recover_limit` | integer | `10` | _(no env override)_ | Maximum attempts for `run … recover` loops before the step fails (see [Language — `recover`](language.md#recover--repair-and-retry-loop)). Effective value comes **only** from the **module-level** `config` block of the **`.jh` file that owns the current scope** (the file containing the workflow or rule that executes the step). Workflow-level `run.recover_limit` does not apply. |
 
 ### Module keys
 
@@ -343,4 +346,4 @@ The runtime also sets `JAIPH_ARTIFACTS_DIR` — the absolute path to the writabl
 
 ## Created by `jaiph init`
 
-`jaiph init` creates `.jaiph/bootstrap.jh` and writes `.jaiph/SKILL.md` from the skill file bundled with your installation (see `JAIPH_SKILL_PATH` in the CLI reference). It does not add a separate config file — use `config { ... }` in your workflow sources.
+`jaiph init` creates `.jaiph/bootstrap.jh`, writes `.jaiph/SKILL.md` from the skill file bundled with your installation (see `JAIPH_SKILL_PATH` in the [CLI](cli.md) reference), and ensures `.jaiph/.gitignore` matches the canonical template (lists `runs` and `tmp` under `.jaiph/`). It does not add a separate config file — use `config { ... }` in your workflow sources.
diff --git a/docs/contributing.md b/docs/contributing.md
index a53f3fac..355b511a 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -7,7 +7,9 @@ redirect_from:
 
 # Contributing to Jaiph
 
-A shared workflow needs shared expectations: which branch to target, how to build from a clone, and what evidence a change should carry. **This page is that contract for Jaiph** — branching, local install, code and testing philosophy, the layered test stack (TypeScript, txtar, goldens, bash E2E), and what CI enforces. It does **not** teach the language; for that, use [Getting Started](getting-started.md) (documentation map), [Setup](setup.md) (install and workspace), and [Grammar](grammar.md). For **how the implementation is structured** (components, compile and run pipelines, `buildRuntimeGraph` vs validation, runtime contracts, artifact paths), use [Architecture](architecture.md) as the source of truth.
+Open source only works when expectations match reality: where to land changes, how to reproduce CI locally, and how to prove behavior with the right test layer. **This page is that contract** — branching, install-from-clone, engineering conventions, the test stack (TypeScript, txtar, golden AST, bash E2E), and what GitHub Actions run on each push.
+
+**Related documentation:** [Getting Started](getting-started.md) (map), [Language](language.md) (patterns), [Setup](setup.md), and [Grammar](grammar.md). **Implementation boundaries** (pipelines, `buildRuntimeGraph` vs `validateReferences`, runtime contracts, artifact layout) are spelled out in [Architecture](architecture.md); if this page disagrees with that file, **Architecture wins**.
 
 ## Branching and pull requests
 
@@ -105,7 +107,7 @@ Jaiph uses several test layers. Each layer catches a different class of bug. Use
 
 ### Key principles
 
-1. **Compile-time validation vs graph loading.** `buildScripts` / `emitScriptsForModule` run **`validateReferences`** before any script files are written. **`buildRuntimeGraph()`** only parses modules and follows imports — it does **not** re-run that validation. Lock compile errors in the compiler/validator tests; the runtime graph is the wrong layer for that (see [Architecture — Transpiler / Node workflow runtime](architecture.md#core-components)).
+1. **Compile-time validation vs graph loading.** `buildScripts` / `emitScriptsForModule` run **`validateReferences`** before any script files are written. **`buildRuntimeGraph()`** only parses modules and follows imports — it does **not** re-run that validation. Lock compile errors in the compiler/validator tests; the runtime graph is the wrong layer for that (see [Architecture — Core components](architecture.md#core-components)). **`jaiph compile`** runs **`validateReferences` only** (no **`buildScripts`**, no runner); cover it with txtar/acceptance/E2E such as `e2e/tests/109_compile_command.sh`, not by expecting the full transpile path — see [Architecture — System overview](architecture.md#system-overview).
 2. **Tests are behavior contracts.** E2E tests and acceptance tests define what the product does. Default approach: change production code to satisfy tests, not the other way around.
 3. **Modify existing tests only with a strong reason:** intentional product behavior change, incorrect test expectation, or removal of an obsolete feature. Any such change should be minimal and paired with a clear rationale.
 4. **Golden tests are the compiler's safety net.** After transpiler changes, run `npm test`. Failures in `src/transpile/compiler-golden.test.ts` usually mean updating an explicit expected string or fixture in that file — there is no separate dump script; align expectations with intentional emitter changes and re-run `npm test`. **Golden AST tests** (`test-fixtures/golden-ast/`) complement this by locking in the parse tree shape — if those fail, regenerate with `UPDATE_GOLDEN=1 npm run test:golden-ast` and review the diff.
@@ -167,14 +169,16 @@ The project uses GitHub Actions (`.github/workflows/ci.yml`). The workflow defin
 |-----|--------|---------|
 | **ShellCheck** | `ubuntu-latest` | Runs `shellcheck` on `runtime/overlay-run.sh` to lint the standalone shell script shipped in the npm package. |
 | **Compiler and unit tests** | `ubuntu-latest` | `npm test` (TypeScript unit + acceptance + golden tests), plus a `curl` check that the public install URL responds and a git-tag verification on `main`. |
-| **E2E install and CLI workflow** | Matrix: **`ubuntu-latest` twice** + **`macos-latest`** | `npm run test:e2e` — full build-and-run E2E suite. In **CI**, the **docker** matrix leg builds `jaiph-ci-runtime:local` from `runtime/Dockerfile` and sets **`JAIPH_DOCKER_IMAGE`** so the job does not pull the public GHCR image during the run. **Ubuntu — docker:** `JAIPH_UNSAFE` unset (container sandbox). **Ubuntu / macOS — host:** `JAIPH_UNSAFE=true` (no Docker; macOS does not run the docker leg). On a **developer machine**, with `JAIPH_UNSAFE` unset, the CLI still resolves the default image (typically `ghcr.io/jaiphlang/jaiph-runtime`) for Docker-backed runs — see `src/runtime/docker.ts` and [Architecture](architecture.md). |
+| **E2E** | Matrix: **`ubuntu-latest` twice** + **`macos-latest`** | Job id `e2e`; in the Actions UI each leg appears as **`E2E (<os>, <label>)`**. Runs `npm run test:e2e`. In **CI**, the **`docker`** leg builds `jaiph-ci-runtime:local` from `runtime/Dockerfile` and sets **`JAIPH_DOCKER_IMAGE`** so tests do not pull the public GHCR image during the run. **`docker` leg:** `JAIPH_UNSAFE` unset (container sandbox). **`host` legs (Ubuntu + macOS):** `JAIPH_UNSAFE=true` (no Docker; macOS does not run a docker leg). On a **developer machine**, with `JAIPH_UNSAFE` unset, the CLI still resolves the default image (typically `ghcr.io/jaiphlang/jaiph-runtime`) for Docker-backed runs — see `src/runtime/docker.ts` and [Architecture](architecture.md). |
 | **Getting started (local)** | `ubuntu-latest` | Serves the Jekyll site from `docs/` on `127.0.0.1:4000`, smoke-checks key routes with `curl`, builds the same local runtime image as E2E for any Docker-backed sample paths, installs Playwright (Chromium), and runs `npx playwright test` for landing-page samples. The Playwright step builds Jaiph, checks sample source against `examples/*.jh`, and runs deterministic samples through the CLI. No runtime dependency on `jaiph.org` for the site content. |
 | **E2E install and CLI workflow (windows-latest + wsl)** | `windows-latest` | Provisions or selects a WSL distro, installs Node inside it, and runs `npm run test:e2e` under WSL with **`JAIPH_UNSAFE=true`**. |
 | **Publish Docker runtime image** | `ubuntu-latest` | *Conditional (see above).* Multi-arch push to GHCR. |
 
-### npm publish on tag (trusted publishing)
+### Version tags and npm
+
+Pushing a **`v*`** ref does **not** run any npm publish step from this repository: the automation checked in under **`.github/workflows/`** is **`ci.yml`** (push CI) and **`nightly-engineer.yml`** (optional manual engineer run) — **neither publishes to npm**. The same tag pattern **does** satisfy the `if:` on the **`docker-publish`** job in **`ci.yml`**, which pushes `ghcr.io/jaiphlang/jaiph-runtime` after the other CI jobs succeed.
 
-Pushing a version tag (`v*`) triggers `.github/workflows/release.yml`, which publishes to npm using **trusted publishing** (OIDC). No classic `NPM_TOKEN` secret is stored in the repo. After a successful publish, a smoke job installs `jaiph` globally and verifies `--version` and `--help` match expectations. The npm package must have trusted publishing enabled for the `jaiphlang/jaiph` repo and `release.yml` workflow on npmjs.com.
+If you are preparing a release that includes the **npm** package, coordinate version bumps, registry publish, and smoke checks with the maintainers — that flow is intentionally outside this repo’s workflows.
 
 ### Local docs site (Jekyll)
 
@@ -265,7 +269,7 @@ EOF
 # When — build and run
 hello_out="$(e2e::run "hello.jh")"
 
-# Then — assert on CLI tree output
+# Then — assert on CLI tree output (include workflow return value when default() returns one)
 e2e::expect_stdout "${hello_out}" <<'EOF'
 
 Jaiph: Running hello.jh
@@ -274,6 +278,8 @@ workflow default
   ▸ script hello_impl
   ✓ script hello_impl (<time>)
 ✓ PASS workflow default (<time>)
+
+hello-jh
 EOF
 
 # Then — assert on run artifacts
@@ -337,6 +343,7 @@ After a workflow runs, its step outputs are written as sequenced artifact files
 |--------|-------------|
 | `e2e::assert_contains "$actual" "$needle" "label"` | Assert that `actual` contains `needle`. |
 | `e2e::assert_equals "$actual" "$expected" "label"` | Assert exact string equality. |
+| `e2e::assert_output_equals "$actual" "$expected" "label"` | Like **`assert_equals`**, but runs both strings through **`e2e::normalize_output`** first (ANSI, `<time>`, async line ordering — same normalization as **`expect_stdout`**). |
 | `e2e::assert_file_exists "path" "label"` | Assert that a file exists at `path`. |
 | `e2e::assert_file_executable "path" "label"` | Assert that a file exists and is executable. |
 | `e2e::pass "label"` | Print a `[PASS]` line. |
diff --git a/docs/getting-started.md b/docs/getting-started.md
index b1620d34..7c1288be 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -11,7 +11,9 @@ redirect_from:
 
 **Jaiph** is a workflow system for building agent-style pipelines. You write `.jh` sources (and optional `*.test.jh` test modules) that combine **prompts**, **rules**, **scripts**, and **workflows**.
 
-This page is a **map**: it does not teach syntax end-to-end; it points to install steps, language references, and runtime behavior. For how the tool fits together, see [Architecture](architecture.md).
+The **TypeScript CLI** validates modules, extracts **`script`** bodies to disk, and launches a **Node workflow runtime** that interprets the AST in process (no separate workflow shell). Local `jaiph run`, Docker-backed runs, and `jaiph test` all use that same interpreter stack; only the launch path and observability differ. For boundaries, contracts, and pipelines, see [Architecture](architecture.md).
+
+This page is a **map**: it does not teach syntax end-to-end; it points to install steps, language references, and runtime behavior.
 
 ## Setup
 
@@ -28,16 +30,16 @@ This page is a **map**: it does not teach syntax end-to-end; it points to instal
 
 ## Runtime
 
-- **[CLI](cli.md)** — `jaiph run`, `test`, `compile`, `format`, `init`, `install`, `use`, flags, and environment variables.
+- **[CLI](cli.md)** — `jaiph run`, `test`, `compile`, `format`, `init`, `install`, `use`, flags, environment variables, and [file-path shorthand](cli.md#file-shorthand) for existing `.jh` / `*.test.jh` files. **`jaiph compile`** walks the import closure and runs **`validateReferences` only** — no script emission or runner (see [Architecture — Summary](architecture.md#summary)).
 - **[Configuration](configuration.md)** — `config { }` blocks, agent backends, logging, and runtime options (including env overrides).
 - **[Runtime artifacts](artifacts.md)** — What Jaiph writes under `.jaiph/runs/` (per-step logs, JSONL timeline, inbox files) versus live progress on stderr.
 - **[Hooks](hooks.md)** — Project or user `hooks.json` to run shell commands on workflow and step lifecycle events.
-- **[Sandboxing](sandboxing.md)** — Optional Docker-backed workflow isolation (beta; opt-in through `runtime.*` keys in module `config` and environment—see [Configuration](configuration.md)).
+- **[Sandboxing](sandboxing.md)** — Docker-backed isolation for `jaiph run` only (beta; **on by default**; use **`JAIPH_DOCKER_ENABLED`** or **`JAIPH_UNSAFE`** to force on/off — workflow `config` cannot toggle the container). Image, network, and timeout come from **`runtime.*`** and **`JAIPH_DOCKER_*`** env overrides (see [Configuration](configuration.md)). There is no `jaiph run --docker` flag.
 
 ## Other
 
 - **[VS Code extension](https://marketplace.visualstudio.com/items?itemName=jaiph.jaiph-syntax-vscode)** — Syntax highlighting, formatting, and compile feedback in the editor.
 - **[Architecture](architecture.md)** — How the CLI, parser, transpiler, Node runtime, and contracts fit together; aimed at contributors and deep dives.
 - **[Contributing](contributing.md)** — Clone-and-build workflow, branch strategy, test layers, and how to propose changes.
-- **[Agent Skill](https://raw.githubusercontent.com/jaiphlang/jaiph/refs/heads/main/docs/jaiph-skill.md)** — Short, opinionated defaults for AI assistants authoring and running Jaiph in a repo.
+- **[Agent Skill](jaiph-skill.md)** — Short, opinionated defaults for AI assistants authoring and running Jaiph in a repo.
 - **[Examples](https://github.com/jaiphlang/jaiph/tree/main/examples)** — Runnable samples (async, inbox, testing, recovery) alongside the main tree.
diff --git a/docs/grammar.md b/docs/grammar.md
index c4c1f140..6dbc902d 100644
--- a/docs/grammar.md
+++ b/docs/grammar.md
@@ -7,7 +7,7 @@ redirect_from:
 
 # Jaiph Grammar
 
-Jaiph source files (`.jh`) combine a small orchestration language with shell execution. **Workflows** and **rules** express Jaiph steps — sequencing, failure handling (`catch`), value branching (`match`), prompts, channels. **Scripts** contain Bash (or another interpreter via shebang) and run as isolated subprocesses. The runtime interprets the AST directly; only script bodies are emitted as executable files. This page is the language reference. For system boundaries and event contracts, see [Architecture](architecture.md).
+Jaiph source files (`.jh`) combine a small orchestration language with shell execution. **Workflows** and **rules** express Jaiph steps — sequencing, failure handling (`catch`), value branching (`match` / `if`), prompts, channels. **Scripts** contain Bash (or another interpreter via shebang) and run as isolated subprocesses. The runtime interprets the AST directly; only script bodies are emitted as executable files. This page is the **lexical and grammatical** reference (tables, edge cases, EBNF). For a narrative tour of the same primitives, see [Language](language.md). For system boundaries and event contracts, see [Architecture](architecture.md).
 
 **Scope:** Lexical rules, syntax, and runtime semantics for normal modules (`.jh`). Test files (`*.test.jh`) are described in [Testing](testing.md). CLI and configuration are covered in [CLI](cli.md) and [Configuration](configuration.md).
 
@@ -42,17 +42,17 @@ The compiler enforces these boundaries at every call site. Using a script where
 
 ## Language Concepts
 
-Jaiph enforces a strict boundary between orchestration and execution. Workflows and rules contain only Jaiph steps. Bash lives in `script` bodies.
+Jaiph enforces a strict boundary between **managed** steps (interpreted by the runtime) and **shell task code**. Prefer top-level `script` definitions (or inline `run` scripts) for multi-line bash. **Workflow** bodies may also contain free-form **inline shell** lines; **rule** bodies must not — unstructured shell there is rejected at validation.
 
-- **Workflows** — Named sequences of Jaiph steps: `ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox `send` (`channel <- …`), `match`, `if`, `run async`, `ensure … catch`, `run … catch`, and `run … recover`. Any line that is not a recognized step is a parse error — extract bash to a `script` and call it with `run`.
+- **Workflows** — Named sequences of steps. **Managed** Jaiph steps include `ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox `send` (`channel <- …`), `match`, `if`, `run async`, `ensure … catch`, `run … catch`, and `run … recover`. A line that does **not** parse as one of those becomes an **inline shell** step (bash text stored as a `shell` AST node). The compiler still validates shell lines (for example a bare name that refers to a local script or workflow must be written as `run name()`, not as a shell line). For non-trivial bash, prefer a top-level `script` and `run name()`.
 
-- **Rules** — Named blocks of structured Jaiph steps: `ensure` (other rules), `run` (scripts only — not workflows), `const`, `match`, `if`, `fail`, `log`/`logerr`, `return "…"`, `ensure … catch`, `run … catch`, and `run … recover`. Rules cannot use `prompt`, inbox `send` (or channel routing), or `run async`.
+- **Rules** — Named blocks of the same **managed** step forms as workflows, with restrictions: `ensure` (other rules), `run` (scripts only — not workflows), `const`, `match`, `if`, `fail`, `log`/`logerr`, `return`, `ensure … catch`, `run … catch`, and `run … recover`. Rules cannot use `prompt`, `const … = prompt`, inbox `send`, or `run async`. **Raw shell lines are not allowed** in rules: if a line parses as unstructured shell, validation fails with `E_VALIDATE` (`inline shell steps are forbidden in rules; use explicit script blocks`).
 
-- **Scripts** — Top-level `script` definitions emitted as separate executable files under the workspace `scripts/` directory. Called from workflows or rules with `run`. Bodies are opaque to the compiler — the parser does not check Jaiph keywords inside them. Use `echo`/`printf` for data output and `return N`/`return $?` for exit status. Jaiph interpolation (`${...}`) is forbidden in script bodies — use `$1`, `$2` positional arguments instead. Polyglot support: a fence lang tag (`` ```<tag> ``) maps to `#!/usr/bin/env <tag>` — any tag is valid (no hardcoded allowlist). Alternatively, a manual `#!` shebang as the first line of the body selects the interpreter; if both a fence tag and a `#!` first line are present, it is an error. Without either, `#!/usr/bin/env bash` is used. For trivial one-off commands, **inline scripts** (`` run `body`(args) `` or `` run ```lang...body...```(args) ``) let you embed a script body directly in a step without a named definition — see [`run` — Inline Scripts](#inline-scripts).
+- **Scripts** — Top-level `script` definitions emitted as separate executable files under the workspace `scripts/` directory. Called from workflows or rules with `run`. Bodies are opaque to the compiler — the parser does not check Jaiph keywords inside them. Use `echo`/`printf` for data output and `return N`/`return $?` for exit status. In **single-line backtick** script bodies, Jaiph `${…}` interpolation is **forbidden** (use `$1`, `$2`, … from the orchestration layer). In **fenced** (`\`\`\`…\`\`\``) script bodies, `${…}` is passed through to the shell. Polyglot support: a fence lang tag (`` ```<tag> ``) maps to `#!/usr/bin/env <tag>` — any tag is valid (no hardcoded allowlist). Alternatively, a manual `#!` shebang as the first line of the body selects the interpreter; if both a fence tag and a `#!` first line are present, it is an error. Without either, `#!/usr/bin/env bash` is used. For trivial one-off commands, **inline scripts** (`` run `body`(args) `` or `` run ```lang...body...```(args) ``) let you embed a script body directly in a step without a named definition — see [`run` — Inline Scripts](#inline-scripts).
 
 - **Channels** — Named message queues declared at top level with `channel name`. Optionally declare inline routes with `channel name -> workflow` or `channel name -> wf1, wf2`. Workflows send messages with `<-`. See [Inbox & Dispatch](inbox.md).
 
-- **Config** — Optional block setting agent and run options. Allowed at module level and inside individual workflow bodies. See [Configuration](configuration.md).
+- **Config** — Optional `config { … }` block. At **module** level, keys may include `agent.*`, `run.*`, `runtime.*`, and `module.*` (see `src/parse/metadata.ts`). A **workflow** may contain at most one nested `config { … }`, it must appear before steps, and only `agent.*` and `run.*` are allowed there (`runtime.*` / `module.*` yield `E_PARSE`). See [Configuration](configuration.md).
 
 ## Imports and Exports
 
@@ -149,10 +149,14 @@ workflow default() { … }               # no params — () required
 rule gate(path) { … }                 # one named param
 workflow implement(task, role) { … }  # two named params
 script setup = `echo ok`               # correct (single-line backtick)
-script setup = ```                     # correct (fenced block)
-echo ok
 ```
+
+Multiline script bodies use triple-backtick fences (shown in HTML so nested fences render correctly):
+
+<pre><code>script setup = ```
+echo ok
 ```
+</code></pre>
 
 ## Call Arguments and Named Parameters
 
@@ -268,7 +272,7 @@ Inline scripts embed a shell command directly in a workflow or rule step without
 ```jaiph
 workflow default() {
   run `echo hello`()
-  x = run `echo captured`()
+  const x = run `echo captured`()
   const y = run `date +%s`()
   log "got: ${x}, time: ${y}"
 }
@@ -298,14 +302,16 @@ print(f"args: {sys.argv[1:]}")
 
 Both body forms work with capture:
 
-```jaiph
-x = run `echo captured`()
-const y = run ```
+<pre><code>workflow default() {
+  const x = run `echo captured`()
+  const y = run ```
 date +%s
 ```()
-```
+  log "got: ${x} at ${y}"
+}
+</code></pre>
 
-**Deterministic naming:** Inline script bodies are emitted as executable files under `scripts/` with names of the form `__inline_<hash>` (12-character SHA-256 prefix of body + shebang). The same body and shebang always produce the same artifact name across runs.
+**Deterministic naming:** Inline script bodies are emitted as executable files under `scripts/` with names of the form `__inline_<hash>` where `<hash>` is the first **12** hex digits of the SHA-256 digest of `shebang + "\n" + body` when a shebang is present, or of the body alone when it is not (`src/inline-script-name.ts`). The same body and shebang always produce the same artifact name across runs.
 
 **Isolation:** Inline scripts run with the same subprocess isolation as named scripts — no parent scope variables are visible. Only positional arguments and essential Jaiph variables (`JAIPH_SCRIPTS`, `JAIPH_WORKSPACE`) are inherited.
 
@@ -469,7 +475,7 @@ A double-quoted string on one line. `${...}` interpolation works inside the quot
 
 ```jaiph
 prompt "Review the following code for security issues"
-answer = prompt "Summarize the report"
+const answer = prompt "Summarize the report"
 ```
 
 If a `"` string has no closing quote on the same line, the parser rejects it — multiline prompt text must use a triple-quoted block (`prompt """..."""`).
@@ -481,7 +487,7 @@ A bare identifier after `prompt` uses the string value of an existing binding (e
 ```jaiph
 const text = "Analyze this code for security issues"
 prompt text
-result = prompt text returns "{ type: string, risk: string }"
+const result = prompt text returns "{ type: string, risk: string }"
 ```
 
 **3. Triple-quoted block (multiline)**
@@ -495,10 +501,10 @@ Analyze the following: ${input}
 """
 ```
 
-All three forms work in capture and `const` capture positions:
+Capture uses **`const` only** — `name = prompt …` is rejected by the parser (use `const name = prompt …`).
 
 ```jaiph
-answer = prompt "Summarize the report"
+const answer = prompt "Summarize the report"
 const x = prompt myVar
 const y = prompt """
 Analyze this input in detail.
@@ -508,15 +514,15 @@ Analyze this input in detail.
 **Typed prompt (returns schema):** Ask the agent for structured JSON output. `returns "…"` may follow a single-line string or identifier body on the same line, or appear on the **line after** the closing `"""` of a triple-quoted block.
 
 ```jaiph
-result = prompt "Analyze this code" returns "{ type: string, risk: string }"
-result = prompt text returns "{ type: string, risk: string }"
+const result = prompt "Analyze this code" returns "{ type: string, risk: string }"
+const typed = prompt text returns "{ type: string, risk: string }"
 ```
 
 For a **triple-quoted** prompt, either put `returns "…"` on the line **immediately after** the closing `"""`, or on the **same line** as the closing delimiter: `""" returns "{ … }"` (nothing else may follow the schema string on that line).
 
-When `returns` is present, capture is required. The schema is flat only — allowed types are `string`, `number`, `boolean`. The runtime validates the response: it searches for valid JSON (last non-empty line, fenced code blocks, standalone `{…}`, embedded JSON). On success, the capture variable holds the raw JSON string and each field is accessible via **dot notation** — `${result.type}`, `${result.risk}`. On failure, the step fails with a parse, missing-field, or type error.
+When `returns` is present, **capture is required** — write `const name = prompt … returns "…"`. Uncaptured `prompt … returns` fails at compile time with `E_PARSE` (`validatePromptStepReturns` in `src/transpile/validate-prompt-schema.ts`).
 
-**String values in orchestration:** Bindings in workflows and rules are **strings** end-to-end (including capture, `return`, and `${…}` interpolation). For typed prompts, schema types only constrain the **parsed JSON** from the agent: after validation, each field is coerced with string conversion for storage. For example, `returns "{ n: number }"` with `{"n":42}` stores `42` as the **text** `"42"` in `${x.n}`, not a numeric type. The same applies to `boolean`. Bare `return x.field` in a workflow is sugar for `return "${x.field}"`.
+The schema is flat only — allowed types are `string`, `number`, `boolean` (`E_SCHEMA` if invalid). The runtime validates the response: it searches for valid JSON (last non-empty line, fenced code blocks, standalone `{…}`, embedded JSON). On success, the capture variable holds the raw JSON string and each field is accessible via **dot notation** — `${result.type}`, `${result.risk}`. On failure, the step fails with a parse, missing-field, or type error. Bindings in workflows and rules are **strings** end-to-end (including capture, `return`, and `${…}` interpolation). For typed prompts, schema types only constrain the **parsed JSON** from the agent: after validation, each field is coerced with string conversion for storage. For example, `returns "{ n: number }"` with `{"n":42}` stores `42` as the **text** `"42"` in `${x.n}`, not a numeric type. The same applies to `boolean`. Bare `return x.field` in a workflow is sugar for `return "${x.field}"`.
 
 **Dot notation validation:** The compiler validates `${var.field}` references at compile time. If `var` is not a typed prompt capture, the compiler reports an error. If `field` is not defined in the `returns` schema, the error lists available fields.
 
@@ -756,13 +762,12 @@ script setup_env = `export BASE_DIR=$(pwd) && mkdir -p "$BASE_DIR/output" && ech
 
 ### Bash Scripts (fenced block)
 
-```jaiph
-script setup_env = ```
+<pre><code>script setup_env = ```
 export BASE_DIR=$(pwd)
 mkdir -p "$BASE_DIR/output"
 echo "Environment initialized"
 ```
-```
+</code></pre>
 
 Script bodies are opaque bash — the compiler does not parse them as Jaiph steps. For bash scripts, the emitter applies only lightweight transforms: `return` normalization, `local`/`export`/`readonly` spacing, and import alias resolution.
 
@@ -777,19 +782,17 @@ Script bodies are opaque bash — the compiler does not parse them as Jaiph step
 
 Use a fence lang tag (`` ```<tag> ``) to select an interpreter without writing a shebang line. The tag maps directly to a shebang: `` ```<tag> `` becomes `#!/usr/bin/env <tag>`. Any tag is valid — there is no hardcoded allowlist.
 
-```jaiph
-script analyze = ```python3
+<pre><code>script analyze = ```python3
 import sys
 print(f"Analyzing {sys.argv[1]}")
 ```
-```
+</code></pre>
 
-```jaiph
-script transform = ```node
+<pre><code>script transform = ```node
 const data = process.argv[2];
 console.log(JSON.stringify({ result: data }));
 ```
-```
+</code></pre>
 
 Examples of tag-to-shebang mapping:
 
@@ -810,12 +813,11 @@ Combining a fence lang tag with a manual `#!` shebang in the body is an error 
 
 If no fence tag is present, the user may provide a manual `#!` shebang as the first line of the body:
 
-```jaiph
-script run_lua = ```
+<pre><code>script run_lua = ```
 #!/usr/bin/env lua
 print("hello from lua")
 ```
-```
+</code></pre>
 
 Non-bash scripts skip Jaiph keyword validation and emit the body verbatim.
 
@@ -893,12 +895,13 @@ Key rules:
 
 ## EBNF (Practical Form)
 
-Informal symbols: `string` = quoted string; `call_ref` = `REF "(" [args] ")"` — parentheses are always required (each argument may be a quoted string, `${var}`, or a **bare identifier** — see [Call Arguments](#call-arguments-and-positional-parameters)); `double_quoted_string` = single-line double-quoted string supporting `\$`, `\"`, `\\`, `` \` `` escapes and `${identifier}` / `${run …}` / `${ensure …}` interpolation; `triple_quoted_block` = multiline string delimited by `"""` on opening and closing lines, supporting the same interpolation; `prompt_body` = single-line double-quoted string | bare `IDENT` (reference to an existing binding) | triple-quoted block (`""" … """`).
+Informal symbols: `string` = quoted string; `call_ref` = `REF "(" [args] ")"` — parentheses are always required (each argument may be a quoted string, `${var}`, or a **bare identifier** — see [Call Arguments](#call-arguments-and-named-parameters)); `double_quoted_string` = single-line double-quoted string supporting `\$`, `\"`, `\\`, `` \` `` escapes and `${identifier}` / `${run …}` / `${ensure …}` interpolation; `triple_quoted_block` = multiline string delimited by `"""` on opening and closing lines, supporting the same interpolation; `prompt_body` = single-line double-quoted string | bare `IDENT` (reference to an existing binding) | triple-quoted block (`""" … """`).
 
 ```ebnf
 file            = { top_level } ;
 
 top_level       = config_block | import_stmt | import_script_stmt | channel_decl | env_decl | rule_decl | script_decl | workflow_decl ;
+ (* env_decl is written `const` in source; parsed into `envDecls` / module constants in `src/parser.ts`. *)
 
 config_block    = "config" "{" { config_line } "}" ;
 config_line     = config_key "=" config_value ;
@@ -922,8 +925,8 @@ env_value       = double_quoted_string | triple_quoted_block | bare_value ;
 
 rule_decl       = [ "export" ] "rule" IDENT [ "(" param_list ")" ] "{" { rule_body_step } "}" ;
 rule_body_step  = comment_line | workflow_step ;
-  (* validation rejects prompt, send, const…=prompt, run async,
-     and run targets that are not scripts *)
+  (* Parsed with the same statement dispatcher as workflows, but validation rejects
+     shell, prompt, send, const … = prompt, run async, and run targets that are not scripts. *)
 
 script_decl     = "script" IDENT "=" script_rhs ;
 script_rhs      = backtick_script_body | fenced_script_block ;
@@ -939,12 +942,13 @@ workflow_config = config_block ;
   (* optional per-workflow override; must appear before steps;
      only agent.* and run.* keys allowed; runtime.* and module.* yield E_PARSE *)
 
-workflow_step   = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stmt | run_async_stmt | prompt_stmt | prompt_capture_stmt
+workflow_step   = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stmt | run_async_stmt | prompt_stmt
                 | const_decl_step | return_stmt
                 | fail_stmt | log_stmt | logerr_stmt | send_stmt
                 | match_stmt | if_stmt | comment_line ;
   (* route declarations (-> workflow) belong at the top level in channel_decl,
      not inside workflow bodies; a -> inside a body is E_PARSE *)
+  (* Any line that does not match the managed forms above becomes a shell step in workflows. *)
 
 const_decl_step = "const" IDENT "=" const_rhs ;
 const_rhs       = double_quoted_string | triple_quoted_block | bash_value_expr
@@ -955,7 +959,6 @@ const_rhs       = double_quoted_string | triple_quoted_block | bash_value_expr
 
 fail_stmt       = "fail" ( double_quoted_string | triple_quoted_block ) ;
 run_async_stmt  = "run" "async" call_ref [ "recover" recover_bindings recover_body ] [ "catch" catch_bindings catch_body ] ;
-run_async_capture = "const" IDENT "=" "run" "async" call_ref ;
 return_stmt     = "return" return_value ;
 return_value    = double_quoted_string | triple_quoted_block | "$" IDENT | "${" IDENT "}"
                 | IDENT
@@ -1004,7 +1007,7 @@ catch_bindings  = "(" IDENT ")" ;  (* failure payload *)
 catch_body      = single_workflow_stmt | "{" { workflow_step } "}" ;
 recover_bindings = "(" IDENT ")" ;  (* failure payload — same as catch *)
 recover_body    = single_workflow_stmt | "{" { workflow_step } "}" ;
-single_workflow_stmt = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stmt | prompt_stmt | prompt_capture_stmt
+single_workflow_stmt = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stmt | prompt_stmt
                 | const_decl_step
                 | return_stmt | fail_stmt | log_stmt | logerr_stmt
                 | send_stmt ;
@@ -1014,7 +1017,7 @@ single_workflow_stmt = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stm
 
 After parsing, the compiler validates references and config (`src/transpile/validate.ts`). Error codes:
 
-- **E_PARSE:** Invalid syntax — duplicate config, invalid keys/values, `$(…)` or `${var:-fallback}` in orchestration strings, `${...}` interpolation in script bodies, `prompt … returns` without capture, bare `ref(args)` in const RHS (use `run`/`ensure`/`prompt`), `local` at top level, unrecognized workflow/rule line, invalid send RHS, arguments after `catch`, bare `catch` with no recovery step, nested inline captures, shell redirection after `run`/`ensure`, invalid parameter names (non-identifier, duplicate, or reserved keyword), or missing `{` on definition line.
+- **E_PARSE:** Invalid syntax — duplicate config, invalid keys/values, `$(…)` or `${var:-fallback}` in orchestration strings, `${...}` interpolation in **single-line backtick** script bodies, `prompt … returns` without `const` capture, `name = prompt …` / assignment captures without `const` for `run`/`ensure`, bare `ref(args)` in const RHS (use `run`/`ensure`/`prompt`), `local` at top level, unrecognized workflow/rule line, invalid send RHS, arguments after `catch`, bare `catch` with no recovery step, nested inline captures, shell redirection after `run`/`ensure`, invalid parameter names (non-identifier, duplicate, or reserved keyword), or missing `{` on definition line.
 - **E_SCHEMA:** Invalid `returns` schema — empty, non-flat, unsupported type (only `string`, `number`, `boolean`).
 - **E_VALIDATE:** Reference errors — unknown rule/workflow, duplicate alias, `ensure` on non-rule, `run` on rule, `run` to workflow inside rule, `run async` in rule, forbidden Jaiph usage inside `$(…)`, dot notation on non-prompt variable or invalid field name, bare identifier argument referencing an unknown variable, `${identifier}` in strings referencing an unknown variable, standalone `"${identifier}"` in call arguments (use bare identifier instead), arity mismatch (call-site argument count differs from callee's declared parameter count), **bare nested managed calls** — `run foo(bar())` or `run foo(rule_bar())` without explicit `run`/`ensure` keyword, **bare nested inline script calls** — `run foo(\`echo aaa\`())` without explicit `run`, **type crossing** — `prompt` with a script name (`scripts are not promptable`), `run` with a string const (`strings are not executable`), `const x = scriptName` (`scripts are not values`), `${scriptName}` interpolation (`scripts cannot be interpolated`).
 - **E_IMPORT_NOT_FOUND:** Import target file does not exist.
diff --git a/docs/hooks.md b/docs/hooks.md
index cf497b7f..cf5990c9 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -5,15 +5,19 @@ redirect_from:
   - /hooks.md
 ---
 
-# Jaiph Hooks
+# Hooks
 
-Workflows often need **side effects** — notifications, structured logging, CI integration — but that logic does not belong in `.jh` sources. **Hooks** solve this: they are optional shell commands the CLI runs at fixed points in the run lifecycle, configured in a single `hooks.json` file rather than scattered across workflows.
+Many workflows trigger **integrations** you do not want to hard-code in `.jh` sources: notifications, structured logging, CI callbacks. **Hooks** are optional shell commands the CLI runs at fixed lifecycle points. Configuration lives in `hooks.json` (global or per-project), so side effects stay out of workflow modules and can be shared across runs.
 
-Under the hood, `jaiph run` follows a predictable path: prepare scripts, spawn the workflow runner (locally or in Docker), stream **`__JAIPH_EVENT__`** JSON lines from the runner’s stderr, then print PASS/FAIL. Hooks tap into that path. The CLI parses the same stderr events that drive the progress tree and builds a JSON payload for each hook command. Hooks live entirely in the **CLI** (they are not executed by `NodeWorkflowRuntime`); channels and inbox dispatch are runtime concerns. See [Architecture — Runtime vs CLI responsibilities](architecture.md#runtime-vs-cli-responsibilities) and [Architecture — Channels and hooks in context](architecture.md#channels-and-hooks-in-context).
+Hooks are **CLI-only**: they are *not* part of `NodeWorkflowRuntime`. The same **`__JAIPH_EVENT__`** JSON lines on stderr that drive the progress tree are parsed in the CLI; hook commands receive a JSON snapshot of each event on stdin. Channels and inbox behavior remain runtime concerns. See [Architecture — Runtime vs CLI responsibilities](architecture.md#runtime-vs-cli-responsibilities) and [Architecture — Channels and hooks in context](architecture.md#channels-and-hooks-in-context). The live event contract is summarized under [Architecture — Contracts](architecture.md#contracts).
 
-Hooks run only for normal **`jaiph run`** (including the `jaiph <file.jh>` shorthand). They are **not** triggered by `jaiph test`, `jaiph init`, `jaiph compile`, or other commands. **`jaiph run --raw`** also skips hooks (along with the banner, progress tree, and failure footer); that path exists so another process can consume stderr unchanged — for example the host CLI when Docker runs `jaiph run --raw` inside the container. See the **`--raw`** bullet under [CLI — `jaiph run`](cli.md#jaiph-run).
+## When hooks run
 
-For local runs, hooks use the same machine as the workflow. For **Docker-backed** runs, hook commands still execute on the **host** CLI process (not inside the container); see [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
+Hooks run only for normal **`jaiph run`**, including the shorthand **`jaiph <file.jh>`** (same code path as `jaiph run`). The entry file must be a **non-test** `.jh` file (`src/cli/index.ts` routes `*.test.jh` to `jaiph test` instead).
+
+Hooks do **not** run for `jaiph test`, `jaiph init`, `jaiph compile`, `jaiph format`, or other commands. **`jaiph run --raw`** skips hooks (and the banner, progress tree, and failure footer) so stderr stays a clean `__JAIPH_EVENT__` stream—used when the host CLI wraps Docker or another embedding. See [CLI — `jaiph run`](cli.md#jaiph-run).
+
+For local runs, hooks use the same machine as the workflow. For **Docker-backed** runs, hook commands still execute on the **host** CLI process, not inside the container. See [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
 
 ## Config locations
 
@@ -22,18 +26,17 @@ For local runs, hooks use the same machine as the workflow. For **Docker-backed*
 | Global | `~/.jaiph/hooks.json` |
 | Project-local | `<workspace>/.jaiph/hooks.json` |
 
-Both files are optional. `<workspace>` is resolved using the same rules as `JAIPH_WORKSPACE` for `jaiph run`: walk up from the entry `.jh` file’s directory, with guards for temp directories and nested sandboxes. Full rules: [CLI — Environment variables](cli.md#environment-variables).
+Both files are optional. `<workspace>` is resolved the same way as `JAIPH_WORKSPACE` for `jaiph run`: walk up from the entry `.jh` file’s directory, with guards for temp directories and nested sandboxes. Full rules: [CLI — Environment variables](cli.md#environment-variables).
 
-Configuration uses **per-event override** precedence: if the project file lists at least one non-empty command for an event, those commands run and the global ones for that event are ignored. Lists are not merged. If neither file defines an event, nothing runs for it.
+**Precedence (per event):** If the project file defines at least one non-empty command for an event, only those commands run and global commands for that event are ignored. Lists are not merged. If the project file omits an event or only has empty/invalid entries for it, global commands apply for that event. Unsupported keys in the JSON object are ignored (see [Schema](#schema)).
 
 ## Schema
 
 Each file must be a single JSON **object** at the root (not an array) mapping **event names** to **arrays of shell commands**:
 
-- Keys must be supported event names (see [Supported events](#supported-events)). Unknown keys are ignored.
-- Values must be arrays. A non-array value for a known key is treated as absent for that event.
-- Array elements must be non-empty strings (one shell command each). Empty strings and non-string elements are skipped. An array of only empty strings is normalized away, so that event falls back to the other config file per [Precedence](#precedence).
-- Commands for an event are all spawned without waiting for the previous hook to finish; spawn order follows the array order (see [Behavior](#behavior)).
+- Keys must be supported event names (see [Supported events](#supported-events)).
+- Values must be arrays. A non-array value for a known key is skipped for that event.
+- Elements must be non-empty strings (one shell command each). Empty strings and non-string elements are skipped. If every element is skipped, that event is not defined in the normalized config, so the other file’s commands can apply (see [Precedence](#precedence)).
 
 ```json
 {
@@ -44,58 +47,58 @@ Each file must be a single JSON **object** at the root (not an array) mapping **
 }
 ```
 
-An empty array (or omitting the key) means “no commands from this file for this event,” so resolution falls back to global hooks when the project file does not override that event (see [Precedence](#precedence)).
+An empty array normalizes to “no commands from this file for this event,” so resolution falls back to the other config file when the project file does not override that event.
 
 ## Supported events
 
 | Event | When it fires |
 |-------|---------------|
-| `workflow_start` | After **`buildScripts`** completes (parse, **`validateReferences`**, script extraction to `scripts/`) and **before** the runner subprocess is spawned. Does not fire if compilation fails. |
-| `workflow_end` | After the runner subprocess exits (any status), **before** the CLI prints PASS/FAIL. |
-| `step_start` | When the CLI observes a step-start event on the runner's stderr stream. |
-| `step_end` | When the CLI observes a step-end event on that stream. |
+| `workflow_start` | After **`buildScripts`** completes (parse, **`validateReferences`**, script extraction to `scripts/`) on the CLI host, and **before** the workflow runner subprocess is spawned. Does not fire if compilation fails earlier. Emitted via `emitter.emit` in `src/cli/commands/run.ts` after subscribers are registered. |
+| `workflow_end` | After the runner exits (any status) and stderr has been drained, in **`reportResult`**—**before** the CLI prints PASS/FAIL. |
+| `step_start` | When the CLI parses a `STEP_START` line on the runner’s stderr (same stream as the progress tree). Includes nested steps; the root `workflow default` step still emits `STEP_START` even though the TTY view skips drawing that start row (`registerTTYSubscriber` in `src/cli/run/stderr-handler.ts`). |
+| `step_end` | When the CLI parses a matching `STEP_END` line on that stream. |
 
-Step kinds correspond to the runtime step types: `workflow`, `rule`, `script`, and `prompt`. Step hooks are driven by the same `__JAIPH_EVENT__` stderr stream as the progress tree; see [CLI — Run progress and tree output](cli.md#run-progress-and-tree-output).
+Step `kind` values come from the runtime event payload (`workflow`, `rule`, `script`, `prompt`). See [CLI — Run progress and tree output](cli.md#run-progress-and-tree-output).
 
 ## Precedence
 
-Resolution happens **per event**, independently:
+Resolution is **per event**, independently:
 
-- Project file has `workflow_end` with at least one non-empty command — only those commands run; global `workflow_end` is ignored.
-- Project file omits `workflow_end` or uses an empty array — global `workflow_end` commands run (if any).
-- Overriding `step_end` in the project file has no effect on how `workflow_start` is resolved.
+- Project `workflow_end` with at least one usable command — only those run; global `workflow_end` is ignored.
+- Project omits `workflow_end` or supplies `[]` / only skipped commands — global `workflow_end` runs (if any).
+- Changing `step_end` in the project file does not affect how `workflow_start` is resolved.
 
-There is no explicit “disable” mechanism. Omitting an event or using `[]` means “fall back to global.” To suppress a global hook for one project, override that event with a no-op: `"workflow_end": ["true"]`.
+There is no explicit “disable hooks” flag. To silence a global hook for one project, override that event with a no-op, e.g. `"workflow_end": ["true"]`.
 
 ## Payload
 
-Each command receives a single JSON object on **stdin** (UTF-8). Parse it with `jq`, `python3 -c`, or any tool you prefer. Stdin can only be read once — if your command needs the payload more than once, capture it in a variable first (see [Examples](#examples)).
+Each command receives one JSON object on **stdin** (UTF-8). Parse with `jq`, `python3 -c`, or your tool of choice. Stdin can only be read once per process; buffer it in a variable if you need the payload multiple times (see [Examples](#examples)).
 
 ### Fields
 
 | Field | Present in | Description |
 |-------|------------|-------------|
-| `event` | all | Event name: `workflow_start`, `workflow_end`, `step_start`, or `step_end`. |
-| `workflow_id` | all | Runtime run id (`run_id` from step events on the stderr stream). Empty on `workflow_start`. For `workflow_end`, the CLI reuses the first non-empty `run_id` it saw on a step event (empty if the runner never emitted one). `step_start` / `step_end` pass through the `run_id` from each event (usually the same value once the run is underway). |
-| `timestamp` | all | ISO 8601 timestamp (from the CLI or runtime event). |
-| `run_path` | all | Absolute path to the `.jh` file being run. |
+| `event` | all | `workflow_start`, `workflow_end`, `step_start`, or `step_end`. |
+| `workflow_id` | all | Runtime `run_id` from each `STEP_*` line. Empty on `workflow_start`. For `workflow_end`, the CLI reuses the first non-empty `run_id` it buffered while parsing stderr (`workflowRunId` in `RunState`, `src/cli/run/stderr-handler.ts`); it stays empty if the runner never emitted one. `step_start` / `step_end` echo the `run_id` from that event. |
+| `timestamp` | all | ISO 8601 string. For `step_*`, the event’s `ts` when non-empty; otherwise the CLI synthesizes one at hook time. `workflow_start` and `workflow_end` timestamps come from the CLI when those hooks fire. |
+| `run_path` | all | Absolute path to the `.jh` entry file. |
 | `workspace` | all | Workspace root directory (same rules as [Config locations](#config-locations)). |
-| `step_id` | `step_*` | Step id used for progress and log paths. Usually the runtime’s `id`; if empty, the CLI synthesizes a stable `legacy:…` id so starts and ends match. |
+| `step_id` | `step_*` | Step id for progress and captures; from the event’s `id`, or a synthesized `legacy:…` value when the runtime left `id` empty so starts and ends still pair (`resolveEventId` in `src/cli/run/stderr-handler.ts`). |
 | `step_kind` | `step_*` | `workflow`, `rule`, `script`, or `prompt`. |
 | `step_name` | `step_*` | Step name (e.g. `default`, `scan_passes`). |
-| `status` | `*_end` | Exit status: 0 = success, non-zero = failure. For `workflow_end`, non-zero if the subprocess exited non-zero **or** the CLI detected a fatal error on stderr (see [CLI](cli.md)). |
-| `elapsed_ms` | `*_end` | Milliseconds elapsed: total wall time (`workflow_end`) or step duration (`step_end`). |
-| `run_dir` | `workflow_end` | Absolute path to the run’s log directory (from runner metadata). Omitted if metadata is missing. |
-| `summary_file` | `workflow_end` | Absolute path to `run_summary.jsonl` (from runner metadata). See [CLI — Run summary](cli.md#run-summary-jsonl). Omitted if unavailable. |
-| `out_file` | `step_end` | Step stdout log path, if the file was non-empty. Omitted otherwise. |
-| `err_file` | `step_end` | Step stderr log path, if the file was non-empty. Omitted otherwise. |
+| `status` | `*_end` | **Step:** exit status from the `STEP_END` event (0 success, non-zero failure; missing status is treated as `1` in the hook payload). **Workflow:** the CLI’s resolved outcome—**`0` success or `1` failure** (not the raw child exit code): non-zero subprocess exit or `hasFatalRuntimeStderr` yields `1` (`reportResult` in `src/cli/commands/run.ts`). |
+| `elapsed_ms` | `*_end` | **`workflow_end`:** wall-clock ms from when the CLI recorded `startedAt` (inside the main `try` after the output dir exists—so **after** module metadata is read and the scratch/target directory is created, and **including** banner, **`buildScripts`**, the full runner lifetime, and stderr drain) until the hook runs. **`step_end`:** duration from the `STEP_END` event, or `0` if missing. |
+| `run_dir` | `workflow_end` | Absolute run log directory from runner metadata (or Docker discovery). Omitted if unavailable. |
+| `summary_file` | `workflow_end` | Absolute path to `run_summary.jsonl` when metadata provides it. See [CLI — Run summary](cli.md#run-summary-jsonl). |
+| `out_file` | `step_end` | Stdout capture path from the `STEP_END` event. The hook omits this JSON key when the parsed event has an empty `out_file` string (`registerHooksSubscriber` in `src/cli/run/hooks.ts`). Current runtimes normally emit paths for every completed step; files may still be empty. |
+| `err_file` | `step_end` | Stderr capture path; same omission rule as `out_file`. |
 
 ### Payload by event
 
-- **`workflow_start`** — `event`, `workflow_id` (empty), `timestamp`, `run_path`, `workspace`.
-- **`step_start`** — `workflow_id`, `timestamp`, `run_path`, `workspace`, plus `step_id`, `step_kind`, `step_name`.
-- **`step_end`** — same base fields as `step_start`, plus `status`, `elapsed_ms`, and optionally `out_file` / `err_file`.
-- **`workflow_end`** — `event`, `workflow_id`, `status`, `elapsed_ms`, `timestamp`, `run_path`, `workspace`, and optionally `run_dir` / `summary_file`.
+- **`workflow_start`** — `event`, `workflow_id` (empty string), `timestamp`, `run_path`, `workspace`.
+- **`step_start`** — `event`, `workflow_id`, `timestamp`, `run_path`, `workspace`, `step_id`, `step_kind`, `step_name`.
+- **`step_end`** — same base as `step_start`, plus `status`, `elapsed_ms`, and optionally `out_file` / `err_file`.
+- **`workflow_end`** — `event`, `workflow_id`, `status` (0 or 1), `elapsed_ms`, `timestamp`, `run_path`, `workspace`, and optionally `run_dir` / `summary_file`.
 
 Example payload (`step_end`):
 
@@ -111,22 +114,23 @@ Example payload (`step_end`):
   "elapsed_ms": 1500,
   "run_path": "/repo/flows/ci.jh",
   "workspace": "/repo",
-  "out_file": "/repo/.jaiph/runs/.../step.out",
-  "err_file": "/repo/.jaiph/runs/.../step.err"
+  "out_file": "/repo/.jaiph/runs/2026-03-11/12-00-00-ci/000001-ci__step.out",
+  "err_file": "/repo/.jaiph/runs/2026-03-11/12-00-00-ci/000001-ci__step.err"
 }
 ```
 
 ## Behavior
 
 - **Shell:** Each command runs as `sh -c '<command>'` (POSIX `sh` on the **`PATH`** of the `jaiph run` process).
-- **Concurrency:** All commands for a single event are started in sequence without awaiting completion, so they overlap in wall time. Lifecycle order is still respected: `workflow_start`, then step hooks as events arrive, then `workflow_end` before PASS/FAIL.
-- **Best-effort:** Hook failures never change the CLI exit code. Non-zero exits or spawn errors produce a `jaiph hooks: ...` line on stderr; the workflow result is unchanged.
-- **I/O:** Hook stdout is discarded. Hook stderr is forwarded to the CLI’s stderr. The JSON payload is written once to each hook’s stdin (`utf8`); if the process exits before reading stdin, delivery is best-effort and may log an error.
-- **Environment:** Hooks receive a shallow copy of the parent process environment (same keys and values as `jaiph run` at spawn time).
-- **Working directory:** Hooks run with the **current working directory** of the `jaiph run` process (often the directory you launched the CLI from), **not** necessarily the workspace root. To write paths under the project, read the `workspace` field from stdin (see [Examples](#examples)).
-- **Invalid config:** Missing files are silently skipped. If a file exists but fails `JSON.parse` or is not a JSON object, the CLI prints a warning on stderr and ignores that file. Bad per-event values (non-array, empty strings) are skipped without rejecting the rest of the file.
+- **Concurrency:** Every command for one event is spawned in a loop **without** waiting for the previous process to exit, so hook commands for the same event overlap in wall time. Ordering across lifecycle stages is still `workflow_start` → step hooks as lines arrive → `workflow_end` before PASS/FAIL.
+- **Best-effort:** Hook failures never change the CLI exit code. Non-zero exits or spawn errors log `jaiph hooks: …` lines on stderr; the workflow result is unchanged.
+- **I/O:** Hook stdout is discarded. Hook stderr is copied to the CLI’s stderr. The JSON payload is written with `stdin.end(payloadJson, "utf8")` per process; if a hook exits before reading stdin, delivery is best-effort and may log an error.
+- **Environment:** Hooks receive a shallow copy of `process.env` at hook spawn time.
+- **Working directory:** The child’s cwd is **not** reset by the hook runner—it inherits the **`jaiph run` process cwd** (often where you launched the CLI), not necessarily `workspace`. Use the `workspace` field from stdin for project-root paths.
+
+**Invalid or missing config:** Missing files are skipped silently. A file that exists but fails `JSON.parse` or is not a JSON object produces a stderr warning and is ignored. Bad per-event values are skipped without rejecting the rest of the file (`parseHookConfig` in `src/cli/run/hooks.ts`).
 
-Payload shapes for tooling are also declared in TypeScript as **`HookPayload`** / **`HookEventName`** in `src/types.ts`.
+Shape definitions in repo: **`HookPayload`** / **`HookEventName`** in `src/types.ts`.
 
 ## Examples
 
@@ -147,8 +151,8 @@ Payload shapes for tooling are also declared in TypeScript as **`HookPayload`**
 }
 ```
 
-Note that stdin can only be read once per process. The `workflow_end` command stores the payload in `p` so it can pipe it to multiple `jq` invocations. The `step_end` command reads stdin once via a single `jq` call.
+Stdin is one-shot per process. The `workflow_end` command stores the payload in `p` so it can feed multiple `jq` invocations. The `step_end` line reads stdin once inside a single `jq` pipeline.
 
-The `step_end` example writes to a fixed path under `$HOME` so it does not depend on where `jaiph run` was invoked. The `workflow_end` example writes relative to the project using the `workspace` field from the payload.
+The `step_end` example uses `$HOME` so it does not depend on the shell cwd. The `workflow_end` line resolves the log path via the payload’s `workspace` field.
 
 **Project overrides global:** If global defines `workflow_end: ["global-notify.sh"]` and the project defines `workflow_end: ["project-notify.sh"]`, only `project-notify.sh` runs.
diff --git a/docs/inbox.md b/docs/inbox.md
index 7cea5fd9..b81a0eed 100644
--- a/docs/inbox.md
+++ b/docs/inbox.md
@@ -18,19 +18,15 @@ in order.
 **Jaiph’s model** is a small orchestration feature on top of that idea: a
 `channel` is declared with optional `->` routes to **workflow** targets; a send
 uses `<-` to enqueue a string payload. `NodeWorkflowRuntime` keeps the queue
-and route map in memory, writes a matching file under the run for audit, and
+and route map in memory, may persist a routed send to disk for audit, and
 **dispatches** targets when the **entry** workflow’s step list completes (plus
 any implicit `run async` join) — not when a separate `->` “fires”; the `->`
 in source code is **static routing** on the channel line, not a runtime
 operator.
 
-`NodeWorkflowRuntime` attaches an **in-memory** queue and route map to each
-**`WorkflowContext`** (one per `run`/`inbox` nesting level; channel-level
-`->` rows populate the map **only** on the entry context — see
-[Who registers routes and who drains](#who-registers-routes-and-who-drains)). Each send also writes a durable copy to
-`inbox/NNN-<channel>.txt` under the run directory for audit and reporting —
-channel transport is queue-based, not filesystem-driven. There are no directory
-watchers, no polling loops, and no third-party brokers.
+`NodeWorkflowRuntime` attaches an **in-memory** queue (`WorkflowContext.queue`) and route **`Map`** per **`run <workflow>()`**. **`channel … ->`** bindings load into **`routes` only when `inheritCallerMetadataScope` is **`false`** (CLI **`jaiph run`** → **`workflow default`**, programmatic **`runNamedWorkflow`** → the named callee). Nested **`run`** workflows begin with **`routes = new Map()` — see **[Who registers routes and who drains](#who-registers-routes-and-who-drains)**.
+
+On **`send`**, **`inboxSeq`** increments, an **`InboxMsg`** queues on **`targetCtx`**, and **`run_summary.jsonl`** always gains **`INBOX_ENQUEUE`** (channel / sender / sequence metadata only — **[Trigger contract](#trigger-contract)**). **`inbox/NNN-<literal>.txt`** is created only when the runtime marked the send **`routed`** (**`routes.has(step.channel)`** in **`node-workflow-runtime.ts`**). If **every** send stays **`routed === false`**, **`inbox/`** may be omitted. Interpreter queue + drain — **[Architecture — Channels and hooks](architecture.md#channels-and-hooks-in-context)** — no brokers, no **`inotify`**, no polling **`inbox/`**.
 
 ## At a glance
 
@@ -57,13 +53,13 @@ channel name, and sender bound to its declared parameters `message`, `chan`, and
 
 ## Design principles
 
-- **Inbox is an event bus, not a filesystem watcher.** Delivery is driven by an
-  explicit **drain** after the orchestrator workflow's steps finish — no
-  `inotifywait`, no `fswatch`, no polling for new files.
+- **Drain-driven delivery, not a filesystem mailbox.** Messages are drained from an
+  in-memory queue **after each workflow finishes its steps** (including the implicit
+  join for `run async`). `inbox/*.txt` is an optional audit copy for routed sends —
+  routing does **not** read from disk — no `inotifywait`, `fswatch`, or polling loops.
 - **Sequential dispatch.** For each queued message, route targets run **in list
   order** (declaration order on the `channel` line), one completion at a time.
-- **Inbox is scoped per run.** Message files live under that run's **`inbox/`**
-  directory; they are not a separate mailbox outside `.jaiph/runs`.
+- **Inbox is scoped per run.** **`inbox/*.txt`** persists **routed** payloads under that UTC run directory (**[Architecture — Durable artifact layout](architecture.md#durable-artifact-layout)**); there is no repo-wide mailbox outside **`.jaiph/runs`**.
 - **Channels are compile-checked.** Unknown channels, bad route targets, and
   invalid `send` RHS forms are `E_PARSE` / `E_VALIDATE` from
   `validateReferences` in the build path; **`buildRuntimeGraph()`** only parses
@@ -96,13 +92,11 @@ The channel reference is always on the left side of the `<-` operator. Valid
 channel forms:
 
 - local channel: `findings`
-- imported channel: `shared.findings`
+- imported channel: `shared.findings` — checked against the import at compile time; **dispatch** still matches **`routes.has()`** with the **literal** token (see [Module scope](#who-registers-routes-and-who-drains))
+
+The send step resolves the **string** payload from the **RHS**, bumps **`inboxSeq`**, and appends an **`InboxMsg`** to the queue on the workflow context selected by walking **from the sender outward** until **`ctx.routes.has(sendChannel)`** — **`sendChannel`** is the exact text left of **`<-`**. If nothing matches, enqueue on the sender’s context (**`routed === false`**; no **`inbox/*.txt`** row). If a match exists (**`routed === true`**), create **`inbox/`** when needed and write **`NNN-<sendChannel>.txt`** sharing the same **`inbox_seq`** as JSONL.
 
-The send step resolves the message from the **RHS**, writes the payload to the
-next inbox file on disk, and appends to the **in-memory** queue of the workflow
-context selected by the routing rule (innermost matching route on the stack, or
-the sender's own context if none match — see
-[Runtime dispatch](#runtime-dispatch)).
+**`INBOX_ENQUEUE`** is always written (`channel`, **`sender`**, **`inbox_seq`**, **`ts`**, **`run_id`**, **`event_version`**) and **does not** embed the payload body (`node-workflow-runtime.ts`).
 
 Valid RHS forms:
 
@@ -206,30 +200,22 @@ Under the run directory (see [Architecture — Durable artifact layout](architec
   ...
 ```
 
-Each message is a file named `NNN-<channel>.txt` where `NNN` is a zero-padded
-sequence for that run (monotonic on the runtime instance via `inboxSeq`). The
-orchestration queue itself is **in memory**; these files are the durable copy
-of the payload.
+When present, files are **`NNN-<channel>.txt`** (`NNN` = **three**‑digit **`inboxSeq`**,
+same value as **`inbox_seq`** in **`INBOX_ENQUEUE`**). **`inboxSeq`** is shared across
+every `send` in the process for that run, so numbering matches **enqueue order**, not “per channel”.
+Persisted payloads are exactly the **routed** sends — the orchestration queue is always in memory.
 
 ## Runtime dispatch
 
 ### Who registers routes and who drains
 
-Every entered workflow gets a **`WorkflowContext`**: a route map and a message
-queue. **Channel-level route declarations are registered on the entry workflow**
-(the outermost workflow invoked by `jaiph run`). After the workflow's **steps**
-finish (including the implicit join for `run async` branches), the runtime runs
-`drainWorkflowQueue` for that context.
-
-Nested workflows invoked with `run` share a **workflow context stack**. On
-**send**, the runtime looks for a route for that channel starting at the
-**sending workflow** (innermost on the stack) and moving **outward** toward the
-entry workflow. Since channel-level routes are registered only on the entry
-workflow, sends from nested workflows bubble up to the orchestrator for dispatch,
-preserving the expected progress tree nesting. If **no** workflow on the stack
-declares a route, the message is queued on the **sender's** context; when that
-context is drained, there are no targets and the message is **skipped** (see
-[Error semantics](#error-semantics)).
+Every entered workflow gets a **`WorkflowContext`**: `workflowName`, a route **`Map`**,
+and a message queue. **`->` bindings are populated only when the workflow is entered
+with `inheritCallerMetadataScope === false`** — ordinary **`jaiph run`** invokes **`workflow default`** from your **`run` filepath**, and **`runNamedWorkflow`** (tests / embedders) uses the same **`false`** branch for whichever workflow it launches, so **`routes`** mirror **that callee module’s** top-level **`channel ->`** lines—not files you only **`import`**. Each nested **`run child()`** pushes another frame with an **empty** route **`Map`**
+(**`// Only register on the entry workflow`** in **`node-workflow-runtime.ts`**), so **`send`** walks **outward** until **`routes.has(step.channel)`** succeeds (**`step.channel`** token from the **`send`** AST node).
+After **each** workflow body finishes (implicit **`run async` join included), **`drainWorkflowQueue`** runs for **that** frame’s queue and route table **before** the frame pops — nested exits are usually no-ops, while the **`jaiph run`** root drains work that nested sends enqueued onto it.
+
+**Module scope.** `ctx.routes` **keys** are bare names from **`channel <name>`** in the callee module (**`parseChannelLine`**). Imports allow **`lib.topic <-`** (validator proves **`topic`** exists inside **`lib`**) yet **`routes.has("lib.topic")`** is still **false** for default layouts, because registered keys omit the **`alias.`** prefix (**`step.channel`** is compared verbatim). Prefer **`topic <-`** next to **`channel topic -> …`** in the **`inheritCallerMetadataScope === false` module**, or **`jaiph run lib.jh`** when **`lib.jh`'s **`channel`** lines should supply the **`->`** bindings.
 
 ### Dispatch loop
 
@@ -237,12 +223,12 @@ Implementation: `src/runtime/kernel/node-workflow-runtime.ts` — `send` step
 handling and `drainWorkflowQueue`.
 
 1. On workflow entry, push a `WorkflowContext` (route map, empty queue).
-2. For the entry workflow, channel-level route declarations populate the
-   context's route map.
+2. When **`inheritCallerMetadataScope === false`**, copy each **`channel <name> -> …`** from **`graph.modules.get(resolved.filePath)`**’s AST into **`ctx.routes`**; nested **`run`** frames leave **`routes`** empty.
 3. Execute workflow steps top to bottom.
-4. On `<-`: resolve payload, allocate the next sequence id from `inboxSeq`,
-   append `InboxMsg` to the selected context's queue, write
-   `inbox/NNN-<channel>.txt`, and append `INBOX_ENQUEUE` to `run_summary.jsonl`.
+4. On `<-`: resolve payload; bump `inboxSeq` (`NNN` zero-padded to **3** digits);
+   enqueue on the routed context selected by scanning the stack outward; **`if routed`**
+   write `inbox/NNN-<channel>.txt`; always append **`INBOX_ENQUEUE`**
+   (`channel`, `sender`, **`inbox_seq`**, **`ts`**, **`run_id`**, **`event_version`**) to **`run_summary.jsonl`** .
 5. After all steps (and implicit `run async` joins) complete,
    `drainWorkflowQueue`:
    - `while (cursor < queue.length)` — new sends during dispatch append to the
@@ -259,9 +245,8 @@ There is no `E_DISPATCH_DEPTH` / `JAIPH_INBOX_MAX_DISPATCH_DEPTH` check in
 
 ### Implementation notes
 
-- Routes (from channel-level `->` declarations) and the pending queue are
-  **in-memory** on `WorkflowContext`. Message files under `inbox/` are written
-  on send for audit; routing uses the queue.
+- Routes (from channel-level `->` declarations) and the pending queue live **in-memory** on **`WorkflowContext`**.
+  Routing consults **`ctx.routes` + `ctx.queue`**; **`inbox/NNN-….txt`** is written **only when** **`if (routed)`** after enqueue — see **`send`** in **`node-workflow-runtime.ts`**.
 - **Sender identity** is the **current workflow name** from the context that
   performed the send (e.g. `researcher`), stable across modules.
 
@@ -280,9 +265,11 @@ fail-fast on the first non-zero exit).
 - **Undefined channel reference:** validation error `Channel "<name>" is not defined`.
 - **Dispatched workflow exits non-zero:** the owning workflow fails; the first
   failing target stops further targets for that message (fail-fast).
-- **No route for a channel:** the message file and queue entry still exist, but
-  dispatch **skips** that message (silent drop). This is intentional for optional
-  subscribers; use a dedicated workflow if missing handlers should be an error.
+- **No route for a channel:** the **`InboxMsg`** is still queued and **`INBOX_ENQUEUE`**
+  is recorded, but **`inbox/*.txt`** is **not** written and **`drainWorkflowQueue`** has
+  no targets (`routes.get(channel)` empty) → the message is **skipped** with no receivers
+  (silent drop). This is intentional for optional subscribers; declare explicit routes if
+  a missing handler should be an error.
 - **Circular sends:** the in-memory queue can grow without a built-in iteration
   cap in `NodeWorkflowRuntime`. Avoid circular sends that grow the queue without bound.
 
@@ -299,14 +286,16 @@ Routed receivers get three dispatch values bound to their declared parameters:
 Receivers get channel and sender via their declared parameter names —
 no environment-variable plumbing.
 
-- **`run_summary.jsonl`:** `NodeWorkflowRuntime` appends `INBOX_ENQUEUE`,
-  `INBOX_DISPATCH_START`, and `INBOX_DISPATCH_COMPLETE` via
-  `appendRunSummaryLine` (see [CLI — Run summary](cli.md#run-summary-jsonl)).
-  `INBOX_DISPATCH_COMPLETE` includes `elapsed_ms`. For `INBOX_ENQUEUE`
-  from `jaiph run`, the line includes `channel`, `sender`, and
-  `inbox_seq`. When a route consumes the channel, the full message body
-  is also written to `inbox/NNN-<channel>.txt` for audit; sends to
-  unrouted channels stay in the JSONL summary only.
+- **`run_summary.jsonl`:** **`NodeWorkflowRuntime`** appends **`INBOX_ENQUEUE`** on every **`send`**,
+  then **`INBOX_DISPATCH_START`** / **`INBOX_DISPATCH_COMPLETE`** (with **`elapsed_ms`** and **`status`**)
+  per routed-target invocation (`appendRunSummaryLine`).
+
+  **`INBOX_ENQUEUE`** (current **`NodeWorkflowRuntime`**) records **`type`**, **`ts`**, **`run_id`**,
+  **`channel`**, **`sender`**, **`inbox_seq`**, **`event_version`** — **not** the message body.
+
+  Routed sends also get the full payload on disk as **`inbox/NNN-<channel>.txt`**. Tooling must read
+  that file **or** the receiver’s **`STEP_*` / script captures for the full string; unrouted sends
+  have **only** enqueue metadata in JSONL (plus whatever you log around the **`send`**).
 - **Calling a receiver with explicit args:** the CLI’s `jaiph run` only starts
   the file’s `default` workflow; extra CLI arguments are passed to `default`
   (see [CLI — `jaiph run`](cli.md#jaiph-run)). There is no `jaiph run
@@ -317,13 +306,9 @@ no environment-variable plumbing.
 
 ## Progress tree integration
 
-- Channel-level route declarations appear as nodes in the progress tree where
-  the static tree is derived from the AST.
-- Dispatched workflows appear like other `run` steps, with dispatch values
-  shown as named parameters (e.g.
-  `workflow analyst (message="…", chan="findings", sender="scanner")`). The Node runtime does
-  not add a separate `dispatched` flag to `STEP_START`/`STEP_END` payloads
-  for inbox routing.
+- Channel‑level **`channel … ->`** declarations surface in the CLI’s **static** step-tree
+  view (derived from the module AST alongside concrete steps).
+- Dispatched workflows render like other **`run`** steps (same shape as `workflow analyst (message="…", chan="findings", sender="scanner")` in **`e2e/tests/91_inbox_dispatch.sh`**). Live **`STEP_START` / `STEP_END`** payloads from **`NodeWorkflowRuntime`** do **not** add inbox-specific **`dispatched` metadata** (**`events.ts`** still tolerates **`dispatched: true`** for forward compatibility).
 - Dispatched step output follows the same artifact rules as other managed steps.
   Use `log` inside the receiver to surface lines in the tree. The runtime
   embeds stdout in `STEP_END` (`out_content`) with the same JSON escaping
@@ -333,16 +318,24 @@ no environment-variable plumbing.
 
 ### Example output
 
-Illustrative progress tree for a pipeline where `researcher` sends on
-`findings`, `analyst` sends on `report`, and `default` routes both channels:
+Shape aligns with **`e2e/tests/91_inbox_dispatch.sh`** (**`display_inbox.jh`**): `scanner` sends on **`findings`**, **`analyst`** sends on **`report`**, **`default`** routes both:
 
 ```
 workflow default
-  ▸ workflow researcher
-  ✓ workflow researcher (0s)
-  ▸ workflow analyst (message="Found 3 issues in auth module", chan="findings", sender="researcher")
-  ✓ workflow analyst (0s)
+  ▸ workflow scanner
+  ·   ▸ script emit_findings
+  ·   ✓ script emit_findings (<time>)
+  ✓ workflow scanner (<time>)
+  ▸ workflow analyst (message="Found 3 issues in auth module", chan="findings", sender="scanner")
+  ·   ▸ script emit_summary (1="Found 3 issues in auth module")
+  ·   ✓ script emit_summary (<time>)
+  ✓ workflow analyst (<time>)
   ▸ workflow reviewer (message="Summary: Found 3 issues in auth ...", chan="report", sender="analyst")
-  ✓ workflow reviewer (0s)
-✓ PASS workflow default (0.1s)
+  ·   ▸ script print_reviewed (1="Summary: Found 3 issues in auth ...")
+  ·   ✓ script print_reviewed (<time>)
+  ✓ workflow reviewer (<time>)
+
+✓ PASS workflow default (<time>)
 ```
+
+A smaller hand-written module with the same routing idea lives at **`examples/agent_inbox.jh`**.
diff --git a/docs/index.html b/docs/index.html
index 96a0985e..2a2e5b2b 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -566,9 +566,12 @@ <h3>Jaiph workflows</h3>
                         &middot;
                         <code>script name = `cmd`</code> &middot; <code>script name = ```[lang] ... ```</code>
                     </dt>
-                    <dd><code>rule</code> is for reusable checks (Jaiph structured steps; used with
-                        <code>ensure</code>),
-                        <code>workflow</code> orchestrates Jaiph steps only, and <code>script</code> holds bash (or any
+                    <dd><code>rule</code> bodies use Jaiph structured steps only (with <code>ensure</code>) &mdash;
+                        raw shell lines are rejected; use <code>script</code> and <code>run</code> for bash.
+                        <code>workflow</code> mixes managed steps with optional <strong>inline shell</strong> lines when
+                        they do not parse as Jaiph keywords (prefer <code>script</code> + <code>run</code> for
+                        non-trivial shell). See <a href="grammar#language-concepts">Grammar — Language concepts</a>.
+                        <code>script</code> holds bash (or any
                         language via a fence lang tag like <code>```node</code>, <code>```python3</code>, or a custom
                         shebang) invoked with <code>run</code>. Rules and workflows <strong>require parentheses</strong>
                         on every definition &mdash; even when parameterless (e.g.
diff --git a/docs/jaiph-skill.md b/docs/jaiph-skill.md
index a92166d6..92e5d45d 100644
--- a/docs/jaiph-skill.md
+++ b/docs/jaiph-skill.md
@@ -13,7 +13,7 @@ redirect_from:
 
 This page is an **agent skill**: it tells an AI assistant how to **author** Jaiph workflows (`.jh` files) and what a sensible `.jaiph/` layout looks like. It is not a full language specification — use [Getting started](getting-started.md) as the documentation map, [Grammar](grammar.md) for syntax and validation details, [Configuration](configuration.md) for `config` keys, [Inbox & Dispatch](inbox.md) for channels, and [Sandboxing](sandboxing.md) for rule design vs optional Docker isolation.
 
-**Jaiph** is a small language for agentic workflows: **orchestration** (rules, prompts, managed calls) and **shell in `script` definitions**. The **Node workflow runtime** (`NodeWorkflowRuntime`) interprets the parsed AST in process — there is no separate transpiled workflow shell on the execution path ([Architecture](architecture.md)). Before `jaiph run` or `jaiph test`, **`buildScripts()`** takes a single **entry** `.jh` path (the workflow file, or the `*.test.jh` file for tests), runs **compile-time validation** (`validateReferences` inside **`emitScriptsForModule`**), and writes extracted **`script`** files under `scripts/` for that module and every file reachable from it via transitive **`import`** — not the whole workspace unless those files are imported. **`jaiph compile`** runs the same validation without emitting scripts or executing workflows. The runner’s **`buildRuntimeGraph()`** then loads the graph with **parse-only** imports (it does not re-run `validateReferences`).
+**Jaiph** is a small language for agentic workflows: **orchestration** (rules, prompts, managed calls) and **shell in `script` definitions**. The **Node workflow runtime** (`NodeWorkflowRuntime`) interprets the parsed AST in process — there is no separate transpiled workflow shell on the execution path ([Architecture](architecture.md)). Before `jaiph run` or `jaiph test`, **`buildScripts()`** takes a single **entry** `.jh` path (the workflow file, or the `*.test.jh` file for tests), runs **compile-time validation** (`validateReferences` inside **`emitScriptsForModule`**), and writes extracted **`script`** files under `scripts/` for that module and every file reachable from it via transitive **`import`** — not the whole workspace unless those files are imported. **`jaiph compile`** runs the same **`validateReferences`** checks by parsing each module in the computed closure **without** **`buildScripts`**, script emission, or the runner ([Architecture](architecture.md)). The runner’s **`buildRuntimeGraph()`** then loads the graph with **parse-only** imports (it does not re-run `validateReferences`).
 
 **Contracts (CLI vs runtime):** **Live:** `__JAIPH_EVENT__` JSON lines on **stderr only** (CLI progress and **hooks** — hooks are **CLI-only**, driven by that stream). **Durable:** `.jaiph/runs/...` and **`run_summary.jsonl`**. Channels are enforced at compile time and executed in the runtime (in-memory queue + inbox files under the run dir); they are not hooks.
 
@@ -25,8 +25,8 @@ The **JS kernel** (`src/runtime/kernel/`) handles **prompt** execution, **manage
 
 **Concepts:**
 
-- **Rules** — Structured checks: `ensure` (other **rules** only), `run` (**scripts** only — not workflows), `const`, `match`, `if`, `fail`, `log`/`logerr`, `return "…"` / `return run script()` / `return ensure rule()`, `ensure … catch`, `run … catch`. No raw shell lines, `prompt`, inbox send/route, or `run async`. Under `jaiph run`, rule bodies are executed **in-process** by the Node runtime; when a rule runs a **script**, that script is a normal managed subprocess (same as scripts from workflows) — see [Sandboxing](sandboxing.md).
-- **Workflows** — Named sequences of **Jaiph-only** steps: `ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox **send** (`channel_ref <- …`), `match`, `if`, `run async`, `ensure … catch`, `run … catch`, `run … recover`. Route declarations (`->`) belong at the top level on `channel` declarations, **not** inside workflow bodies — a `->` inside a body is a parse error. Unrecognized lines are errors — put bash in **`script`** definitions and call with `run`.
+- **Rules** — Structured checks: `ensure` (other **rules** only), `run` (**scripts** only — not workflows), `const`, `match`, `if`, `fail`, `log`/`logerr`, `return "…"` / `return run script()` / `return ensure rule()`, `ensure … catch`, `run … catch`, `run … recover`. No raw shell lines, `prompt`, inbox send/route, or `run async`. Under `jaiph run`, rule bodies are executed **in-process** by the Node runtime; when a rule runs a **script**, that script is a normal managed subprocess (same as scripts from workflows) — see [Sandboxing](sandboxing.md).
+- **Workflows** — Named sequences of **managed** Jaiph steps (`ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox **send**, `match`, `if`, `run async`, `ensure`/`run` with `catch` or `recover`, …) plus optional **inline shell** lines: a line that does not parse as a managed step is treated as bash stored in a `shell` AST node (validated like other shell text). Prefer top-level **`script`** definitions and `run` for multi-line or reusable shell. Route declarations (`->`) belong on top-level `channel` lines, never inside a workflow body (a `->` in a body is `E_PARSE`).
 - **Scripts** — Top-level **`script`** definitions are **bash (or shebang interpreter) source**, not Jaiph orchestration. Defined with `` script name = `body` `` (single-line backtick) or `` script name = ```[lang] ... ``` `` (fenced block). Double-quoted string bodies (`script name = "body"`) and bare identifier bodies (`script name = varName`) are **removed** — both produce parse errors with guidance to use backtick delimiters. The compiler treats all script bodies as **opaque text**: it does not parse lines as Jaiph steps, reject keywords, strip quotes, or validate cross-script calls. This means embedded `node -e` heredocs, inline Python, `const` assignments in JS, and any other valid shell construct compile without interference. Jaiph interpolation (`${...}`) is **forbidden** in **single-line backtick** script bodies — use `$1`, `$2` positional arguments to pass data from orchestration to scripts. In **fenced** (triple-backtick) blocks, `${...}` is passed through to the shell as standard parameter expansion (`${VAR}`, `${VAR:-default}`, etc.). A single-backtick body containing a newline is a hard parse error — use a fenced block for multi-line scripts. Use `return N` / `return $?` for exit status and **stdout** (`echo` / `printf`) for string data to callers. From a **workflow** or **rule**, call with **`run fn()`**. Can be exported (`export script name = ...`) for use by importing modules. Cannot be used with `ensure`, are not valid inbox route targets, and must not be invoked through `$(...)` or as a bare shell step. **Polyglot scripts:** use a fence lang tag (`` ```<tag> ``) to select an interpreter — the tag maps directly to `#!/usr/bin/env <tag>`. Any tag is valid (no hardcoded allowlist). For example: `` ```node ``, `` ```python3 ``, `` ```ruby ``, `` ```lua ``. Alternatively, if no fence tag is present, the first non-empty body line may start with `#!` (e.g. `#!/usr/bin/env lua`), which becomes the script's shebang and the body is emitted verbatim (you cannot combine a fence tag with a manual shebang — that is an error). Without either, `#!/usr/bin/env bash` is used and the emitter applies only lightweight bash-specific transforms (`return` normalization, `local`/`export`/`readonly` spacing, import alias resolution). Scripts are extracted to a `scripts/` directory under the run output tree (`jaiph run --target <dir>` sets that tree; without `--target` the CLI uses a temporary directory) and executed via **`JAIPH_SCRIPTS`**. **Inline scripts:** For trivial one-off commands, use `` run `body`(args) `` or `` run ```lang...body...```(args) `` directly in a workflow or rule step instead of declaring a named `script` definition. The body (single backtick for one-liners or triple backtick for multi-line) comes before the parentheses; optional comma-separated arguments go inside the parentheses: `` run `echo $1`("hello") ``. Fenced blocks support lang tags for polyglot inline scripts: `` run ```python3 ... ```() ``. Capture forms: `` const x = run `echo val`() `` and `` const x = run ```...```() ``. The old `run script() "body"` form is **removed** — use the backtick forms instead. Inline scripts use deterministic hash-based artifact names (`__inline_<hash>`) and run with the same isolation as named scripts. `run async` with inline scripts is not supported.
 - **Channels** — Top-level `channel <name> [-> workflow, ...]` declarations with optional inline routing; **send** uses `channel_ref <- …`. Routes are declared on the channel declaration, not inside workflow bodies (see [Inbox & Dispatch](inbox.md)). Channel names share the per-module namespace with rules, workflows, scripts, and module-scoped `local` / `const` variables.
 
@@ -38,12 +38,12 @@ Step semantics (`ensure`, `run`, `prompt`, `catch`, `recover`, `match`, `if`, `l
 
 ## Safe delivery loop (any repository)
 
-Use this loop whenever you add or change Jaiph workflows so failures surface before work is handed back:
+Use this loop whenever you add or change Jaiph workflows so failures surface before work is handed back. When the repo defines a **`workflow default` entrypoint** (often `.jaiph/main.jh`) that wires preflight → implementation → verification, use **`jaiph run`** on that file for end-to-end delivery after the narrower checks below pass.
 
 1. **Preflight** — Run the project’s readiness checks if they exist (often `jaiph run .jaiph/readiness.jh` or a named preflight workflow). When the repo ships native tests (`*.test.jh`), run `jaiph test` before large edits when practical.
 2. **Implement** — Edit `.jh` modules using only constructs described in [Grammar](grammar.md); keep managed-call rules (`ensure` for rules, `run` for workflows and scripts); keep bash inside **`script`** bodies only (no raw shell in workflow/rule bodies).
 3. **Format** — Run `jaiph format <file.jh ...>` on all authored or modified `.jh` files before committing. This normalizes whitespace, indentation, and top-level ordering (imports, config, and channels hoisted to the top; everything else kept in source order). Use `jaiph format --check <file.jh ...>` to verify formatting without writing (non-zero exit on drift — useful in CI).
-4. **Compile check** — Run `jaiph compile <file-or-dir>` on the paths you touched (or `jaiph compile --json …` in automation). Same reference checks as before a run, without executing workflows or writing `scripts/` ([Architecture](architecture.md)).
+4. **Compile check** — Run `jaiph compile <file-or-dir>` on the paths you touched (or `jaiph compile --json …` in automation). Same `validateReferences` checks as before a run, without executing workflows or writing `scripts/` ([Architecture](architecture.md)). With a **directory** argument, only non-test `*.jh` files are used as entrypoints (`*.test.jh` is skipped); pass a test file path explicitly to validate it.
 5. **Verify** — Run `jaiph test` (whole workspace or a focused path) and any verification workflow the repo defines (commonly `jaiph run .jaiph/verification.jh`). Fix failures you introduce.
 6. **Inspect (optional)** — Browse `.jaiph/runs` directly when you need raw step logs or `run_summary.jsonl` instead of only the terminal tree.
 
@@ -73,7 +73,7 @@ Use this guide when generating or updating `.jaiph/*.jh` workflows for a reposit
 
 When this skill conflicts with the compiler or runtime, follow the implementation. For language rules and validation codes, [Grammar](grammar.md) is the detailed reference. Published docs: [jaiph.org](https://jaiph.org).
 
-`jaiph init` writes this skill to `.jaiph/SKILL.md` when the installed Jaiph bundle includes a skill file (or when `JAIPH_SKILL_PATH` points at a markdown file). If that step is skipped, set `JAIPH_SKILL_PATH` to this file (or `docs/jaiph-skill.md` in a checkout) and run `jaiph init` again — see [CLI Reference](cli.md).
+`jaiph init` writes this skill to `.jaiph/SKILL.md` when the installer resolves a skill file: if **`JAIPH_SKILL_PATH`** is set, it is used **only when that path exists on disk**; otherwise the CLI searches install-relative locations and `docs/jaiph-skill.md` from the current working directory ([CLI Reference](cli.md)). If no file is found, init skips `SKILL.md` — set **`JAIPH_SKILL_PATH`** to an existing markdown file (for example `docs/jaiph-skill.md` in a checkout) and run `jaiph init` again.
 
 Ignore any outdated Markdown that contradicts the above.
 
@@ -93,11 +93,11 @@ Prefer composable modules over one large file.
 ## Language Rules You Must Respect
 
 - **Imports:** `import "path.jh" as alias`. Path must be double-quoted. Path is relative to the importing file first; if no file is found and the path contains `/`, the resolver falls back to project-scoped libraries under `<workspace>/.jaiph/libs/` (e.g. `import "queue-lib/queue" as queue` resolves to `.jaiph/libs/queue-lib/queue.jh`). If the path has no extension, the compiler appends `.jh`. Install libraries with `jaiph install <url[@version]>`. **Script imports:** `import script "./helper.py" as helper` imports an external script file and binds it as a local script symbol — callable with `run helper(args)` exactly like an inline `script` definition. The path resolves relative to the importing file. Shebangs in the imported file are preserved. Missing targets fail with `E_IMPORT_NOT_FOUND`.
-- **Definitions:** `channel name` (inbox endpoint); `rule name() { ... }` or `rule name(params) { ... }`, `workflow name() { ... }` or `workflow name(params) { ... }`, `` script name = `body` `` or `` script name = ```[lang] ... ``` ``. **Parentheses are required on all rule and workflow definitions** — even when parameterless (e.g. `workflow default() { ... }`, `rule check() { ... }`). Omitting `()` before `{` is a parse error with a fix hint. Named parameters go inside the parentheses — e.g. `workflow implement(task, role) { ... }`, `rule gate(path) { ... }`. At runtime, named params are the only way to access arguments. The compiler validates call-site arity when the callee declares params. Named scripts require a name at the definition site; for anonymous one-off commands use inline scripts: `` run `echo ok`() `` or `` run ```...```(args) ``. Optional `export` before `rule`, `workflow`, or `script` marks it as public (see [Grammar](grammar.md)). Optional `config { ... }` at the top of a file sets agent, run, and runtime options. An optional `config { ... }` block can also appear inside a `workflow { ... }` body (before any steps) to override module-level settings for that workflow only — only `agent.*` and `run.*` keys are allowed; `runtime.*` yields `E_PARSE` (see [Configuration](configuration.md#workflow-level-config)). Config values can be quoted strings, booleans (`true`/`false`), bare integers, or bracket-delimited arrays of strings (see [Grammar](grammar.md) and [Configuration](configuration.md)).
+- **Definitions:** `channel name` (inbox endpoint); `rule name() { ... }` or `rule name(params) { ... }`, `workflow name() { ... }` or `workflow name(params) { ... }`, `` script name = `body` `` or `` script name = ```[lang] ... ``` ``. **Parentheses are required on all rule and workflow definitions** — even when parameterless (e.g. `workflow default() { ... }`, `rule check() { ... }`). Omitting `()` before `{` is a parse error with a fix hint. Named parameters go inside the parentheses — e.g. `workflow implement(task, role) { ... }`, `rule gate(path) { ... }`. At runtime, named params are the only way to access arguments. The compiler validates call-site arity when the callee declares params. Named scripts require a name at the definition site; for anonymous one-off commands use inline scripts: `` run `echo ok`() `` or `` run ```...```(args) ``. Optional `export` before `rule`, `workflow`, or `script` marks it as public (see [Grammar](grammar.md)). Optional `config { ... }` at the top of a file sets agent, run, and runtime options. An optional `config { ... }` block can also appear inside a `workflow { ... }` body (before any steps) to override module-level settings for that workflow only — only `agent.*` and `run.*` keys are allowed; `runtime.*` and `module.*` yield `E_PARSE` (see [Configuration](configuration.md#workflow-level-config)). Config values can be quoted strings, booleans (`true`/`false`), bare integers, or bracket-delimited arrays of strings (see [Grammar](grammar.md) and [Configuration](configuration.md)).
 - **Module-scoped variables:** `local name = value` or `const name = value` (same value forms). Prefer **`const`** for new files. Values can be single-line `"..."` strings, triple-quoted `"""..."""` multiline strings, or bare tokens. A double-quoted string that spans multiple lines is rejected — use `"""..."""` instead. Accessible as `${name}` inside orchestration strings in the same module. Names share the unified namespace with channels, rules, workflows, and scripts — duplicates are `E_PARSE`. Not exportable; module-scoped only.
 - **Steps:**
-  - **ensure** — `ensure ref` or `ensure ref([args...])` runs a rule (local or `alias.rule_name`). **Parentheses are optional when passing zero arguments** — `ensure check` is equivalent to `ensure check()`. When arguments are present, parentheses are required with comma-separated expressions. **Bare identifier arguments** are supported and preferred: `ensure check(status)` is equivalent to `ensure check("${status}")` — the identifier must reference a known variable (`const`, capture, or named parameter); unknown names fail with `E_VALIDATE`. **Standalone `"${identifier}"` in call arguments is rejected** — use the bare form instead. Optionally `ensure ref([args]) catch (<name>) <body>` or `ensure ref([args]) catch (<name>, <attempt>) <body>`: the recovery body runs **once** on failure (like a catch clause). There is no retry loop — for retries, use explicit recursion. The first binding (e.g. `failure`) receives the full merged stdout+stderr from the failed rule execution, including output from nested scripts and rules. The optional second binding (e.g. `attempt`) receives the attempt number (always `"1"`). Full output still lives in step **`.out` / `.err`** artifacts. If the failure binding is empty for your rule, persist diagnostics before prompting or assert non-empty. Works in both workflows and rules.
-  - **run** — `run ref` or `run ref([args...])` runs a workflow or script (local or `alias.name`). **Parentheses are optional when passing zero arguments** — `run setup` is equivalent to `run setup()`. When arguments are present, parentheses are required with comma-separated expressions. **`run` does not forward args by default** — pass named params explicitly (e.g. `run wf(task)`, `run util_fn(name)`). **Bare identifier arguments** are supported and preferred: `run greet(name)` is equivalent to `run greet("${name}")` — the identifier must reference a known variable (`const`, capture, or named parameter); unknown names fail with `E_VALIDATE`. **Standalone `"${identifier}"` in call arguments is rejected** — use the bare form instead (e.g. `run greet(name)` not `run greet("${name}")`). Quoted strings with additional text around the interpolation (e.g. `"prefix_${name}"`) are still allowed. Jaiph keywords cannot be used as bare identifiers. **Nested managed calls in arguments** are supported with explicit keywords: `run foo(run bar())`, `run foo(ensure check())`, `run foo(run \`echo ok\`())`. Bare call-like forms in arguments (`run foo(bar())`, `run foo(\`echo ok\`())`) are rejected — add the `run` or `ensure` keyword. Optionally `run ref([args]) catch (<name>) <body>`: the recovery body runs **once** on failure (same semantics as `ensure … catch`). Works in both workflows and rules. Optionally `run ref([args]) recover (<name>) <body>`: repair-and-retry loop — on failure, binds error output, runs the repair body, and retries the target. Loop stops on success or when `run.recover_limit` (default 10) is exhausted. `recover` and `catch` are mutually exclusive on the same step. Workflows only. Also supports **inline scripts**: `` run `body`(args) `` or `` run ```lang...body...```(args) `` — see Scripts section above.
+  - **ensure** — `ensure ref()` or `ensure ref(args…)` runs a rule (local or `alias.rule_name`). **Parentheses are required on every call site**, including zero-argument calls (`ensure check()`, not bare `ensure check`). Arguments are comma-separated inside `()`. **Bare identifier arguments** are supported and preferred (when valid): `ensure check(status)` is equivalent to `ensure check("${status}")` — the identifier must reference a known variable (`const`, capture, or named parameter); unknown names fail with `E_VALIDATE`. **Standalone `"${identifier}"` in call arguments is rejected** — use the bare form instead. Quoted strings with extra text (e.g. `"prefix_${name}"`) stay valid. Jaiph keywords cannot be used as bare identifiers. Optionally `ensure ref(…) catch (<name>) <body>`: the recovery body runs **once** on failure (no built-in retry on `ensure` — use `run … recover` for loops). The binding receives merged stdout+stderr from the failed rule. Full output also lives in **`.out` / `.err`** artifacts. Works in workflows and rules.
+  - **run** — `run ref()` or `run ref(args…)` runs a workflow or script (local or `alias.name`). Same **required `()` on every call site** as `ensure`, including zero args (`run setup()`). In a **workflow**, the target may be another workflow or a script; in a **rule**, the target must be a **script** only (`E_VALIDATE` if you name a workflow). **`run` does not forward CLI positional args implicitly** — the entry workflow binds them into named params and must pass values explicitly into callees. **Bare identifier arguments** follow the same rules as `ensure` when applicable. **Nested managed calls inside argument lists must use keywords:** `run foo(run bar())`, `run foo(ensure check())`; bare `run foo(bar())`/`run foo(\`...\`())` forms are rejected. Optionally `catch (<name>)` (runs once on failure, mutually exclusive with `recover`) or `recover (<name>)` (repair-and-retry up to **`run.recover_limit`**, module-level only). **`catch` / `recover` on `run`** are allowed in workflows and rules (rules: callee must remain a script). Also **inline scripts**: `` run `body`(args) `` or `` run ```lang...body...```(args) `` — see Scripts above.
   - **log** — `log "message"` writes the expanded message to **stdout** and emits a **`LOG`** event; the CLI shows it in the progress tree at the current depth. Double-quoted string; `${identifier}` interpolation works at runtime. For multiline messages, use triple quotes: `log """..."""`. **Bare identifier form:** `log foo` (no quotes) expands to `log "${foo}"` — the variable's value is logged. Works with `const`, capture, and named parameters. **Inline capture interpolation** is also supported: `${run ref([args])}` and `${ensure ref([args])}` execute a managed call and inline the result (e.g. `log "Got: ${run greet()}"`). Nested inline captures are rejected. **`LOG`** events and `run_summary.jsonl` store the **same** message string (JSON-escaped for the payload). No spinner, no timing — a static annotation. See [CLI Reference](cli.md) for tree formatting. Useful for marking workflow phases (e.g. `log "Starting analysis phase"`).
   - **logerr** — `logerr "message"` is identical to `log` except the message goes to **stderr** and the event type is **`LOGERR`**. In the progress tree, `logerr` lines use a red `!` instead of the dim `ℹ` used by `log`. Same quoting, interpolation, bare identifier, and triple-quote rules as `log` (e.g. `logerr err_msg`, `logerr """..."""`).
   - **Send** — After `<-`, use a **double-quoted literal**, **triple-quoted block** (`channel <- """..."""`), **`${var}`**, or **`run ref([args])`**. An explicit RHS is always required — bare `channel <-` (without a value) is invalid. Raw shell on the RHS is rejected — use `const x = run helper()` then `channel <- "${x}"`, or `channel <- run fmt_fn()`. Combining capture and send (`name = channel <- …`) is `E_PARSE`. See [Inbox & Dispatch](inbox.md).
@@ -157,7 +157,7 @@ const ts = run `date +%s`()
 Conventions:
 
 - `jaiph run <file.jh>` executes `workflow default` in that file. The file must define a `workflow default` (the runtime checks for it and exits with an error if missing).
-- Inside a workflow, `run` targets a workflow or script (local or `alias.name`), not a raw shell command. Call scripts with `run`, never `fn args` or `$(fn ...)`.
+- Inside a workflow, reach other workflows/scripts with **`run ref()`**. Free-form bash can appear as **inline shell** lines when the grammar allows; prefer **`script`** + **`run`** for anything non-trivial. Never use `fn args` or `$(fn …)` as a substitute for **`run`**.
 - Inside a rule, use `ensure` for **rules** and `run` for **scripts only** — not `prompt`, `send`, or `run async`.
 - Treat rules as non-mutating checks; perform filesystem or agent mutations in **workflows**. Script steps from rules use the same managed subprocess path as workflows. Details: [Sandboxing](sandboxing.md).
 - **Parallelism:** `run async ref([args...])` for managed async with implicit join. For concurrent **bash**, use `&` and the shell builtin `wait` inside a **`script`** and call it with `run`. Do not call Jaiph internals from background subprocesses unless you understand how isolation and logging interact with the runtime.
diff --git a/docs/libraries.md b/docs/libraries.md
index 2f6d2bb8..5b81f5f0 100644
--- a/docs/libraries.md
+++ b/docs/libraries.md
@@ -7,35 +7,45 @@ redirect_from:
 
 # Libraries
 
-When workflows grow, you want to **reuse** modules: shared rules, script wrappers, and small “standard library” flows. Jaiph does not publish those as a global install path; instead, each **workspace** can hold **project-scoped libraries** under `<workspace>/.jaiph/libs/`. The compiler resolves `import` paths against that tree (after normal relative resolution), and the CLI can **clone** git repositories into that folder and record them in a lockfile. This matches the import story in [Architecture](architecture.md#core-components) (validator + `resolveImportPath` with workspace root).
+Workflow systems usually want **shared modules**: reusable rules, scripts, and small packaged workflows. Jaiph does not ship a global library path on the machine. Instead, everything is **scoped to a workspace**: first-party and third-party modules live under disk paths that the compiler resolves from your entry file and **workspace root**.
+
+This page covers **project-scoped libraries** under `<workspace>/.jaiph/libs/`, how `import` resolves into that tree, how **`jaiph install`** populates it from git, and the first-party **`jaiphlang/`** helpers maintained in this repository. For validator behavior and `resolveImportPath`, see [Architecture — Core components](architecture.md#core-components). For exact grammar and export rules, see [Grammar — Imports and Exports](grammar.md#imports-and-exports).
 
 ## How imports resolve
 
-1. **Relative to the current file** — the same as for local modules (`import "./foo"`, `import "../lib/util"`).
-2. **Library paths** — if the import string contains a `/` and the relative path does not exist, the compiler tries  
+Resolution is implemented in `resolveImportPath` (`src/transpile/resolve.ts`). Order:
+
+1. **Relative to the importing file** — `import "./foo"`, `import "../lib/util"` (`.jh` appended when the path omits the extension).
+2. **Library fallback** — only if step 1 did not find an existing file **and** the import string contains `/`. The path is split at the first `/` into `<lib-name>` and `<rest>`, then the compiler looks for  
    `<workspace>/.jaiph/libs/<lib-name>/<rest>.jh`  
-   (see `resolveImportPath` in the transpiler; the **workspace root** is required everywhere imports are checked).
+   (with the same `.jh` defaulting rule as above).
+
+The **workspace root** threaded into **`validateReferences`** / **`emitScriptsForModule`** is whatever root the invoking command computed — for example **`jaiph run`** passes `detectWorkspaceRoot(dirname(entry.jh))`, while **`jaiph install`** uses `detectWorkspaceRoot(process.cwd())`. Detection walks upward from that starting path until `.jaiph` or `.git` (with the temp-directory guards summarized in [CLI — `jaiph install`](cli.md#jaiph-install)). **`jaiph compile`** applies the same resolver over each module’s import closure without emitting scripts (see [Architecture](architecture.md)).
+
+The first segment of a library import is the directory name under `.jaiph/libs/` (for example `queue-lib` in `import "queue-lib/queue"`). If a module declares any `export`, only exported names are visible through the alias — same rule as local modules ([Grammar — Imports and Exports](grammar.md#imports-and-exports)).
 
-The library name is the first path segment (e.g. `queue-lib` in `import "queue-lib/queue"`). A module that declares `export` names only exposes those names to importers, as described in [Grammar — Imports and Exports](grammar.md#imports-and-exports).
+**Limitation:** `import script "…"` paths resolve **only** relative to the importing file; there is no library fallback for script imports ([Grammar](grammar.md#imports-and-exports)).
 
 ## Installing third-party libraries
 
 ```bash
-# Install a library (shallow git clone into .jaiph/libs/<name>/)
+# Clone into .jaiph/libs/<name>/ (shallow git clone) and update the lockfile
 jaiph install https://github.com/you/queue-lib.git
 
-# Install a specific tag or branch (ref must follow the .git in the URL)
+# Pin a branch or tag (typical HTTPS shape: …/.git@ref)
 jaiph install https://github.com/you/queue-lib.git@v1.0
 
-# Restore all libraries from the lockfile (e.g. after git clone)
+# Restore all libraries from the lockfile (e.g. after git clone or in CI)
 jaiph install
 ```
 
-`jaiph install` writes `.jaiph/libs.lock`. Commit the lockfile; add `.jaiph/libs/` to `.gitignore` if you do not want vendored clones in git. Use `--force` to replace an existing clone (see [CLI — `jaiph install`](cli.md#jaiph-install) for details).
+`jaiph install` writes `.jaiph/libs.lock` under the workspace root. Commit the lockfile; add `.jaiph/libs/` to `.gitignore` if you do not want vendored clones in version control. If `.jaiph/libs/<name>/` already exists, the clone is skipped unless you pass **`--force`** (see [CLI — `jaiph install`](cli.md#jaiph-install) for URL/`@ref` parsing and lockfile JSON).
+
+The clone directory name is derived from the URL (last path segment, `.git` stripped), so imports use that segment as `<lib-name>`.
 
 ## Example: `import` from a clone under `.jaiph/libs/`
 
-`jaiph install` creates `queue-lib/…` on disk, so a path like `queue-lib/queue` resolves the same as any other library layout. The exported names are defined by that repository; here is a self-contained example using the documented **`jaiphlang/queue`** API (after you have `.jaiph/libs/jaiphlang/` in the workspace).
+After `jaiph install`, paths like `queue-lib/queue` resolve like any other library layout. Exported names come from that repository. Below assumes `.jaiph/libs/jaiphlang/` exists (copy from this repo or install your own package named `jaiphlang`).
 
 ```jaiph
 import "jaiphlang/queue" as q
@@ -49,30 +59,38 @@ workflow default() {
 
 ## The `jaiphlang/` standard libraries
 
-The `jaiphlang/` prefix is a **naming convention** for first-party helper modules (queue, artifacts, …). They are not bundled inside the npm `jaiph` package; the canonical source lives in the [jaiph repository](https://github.com/jaiphlang/jaiph) under `.jaiph/libs/jaiphlang/`. Copy that directory into your own workspace as `.jaiph/libs/jaiphlang/` (or track it in git) so `import "jaiphlang/..."` resolves. They use the same `import` / `export workflow` (and `export rule`) pattern as any other library.
+The `jaiphlang/` prefix is a **naming convention** for first-party helper modules shipped **in this repository** under `.jaiph/libs/jaiphlang/`. They are not bundled inside the npm `jaiph` package. Copy that directory into your workspace as `.jaiph/libs/jaiphlang/` (or track it in git) so `import "jaiphlang/…"` resolves. They use the same `import` / `export workflow` / `export rule` pattern as any other library.
 
 ### `jaiphlang/queue` — `QUEUE.md` task queue
 
-Manages a markdown task file **`QUEUE.md`** at `${JAIPH_WORKSPACE:-.}` (see `queue.jh` and `queue.py`). Task sections use `##` headers; optional tags are `#hashtags` on the header line (e.g. `## My task #dev-ready`).
+Manages a markdown task file **`QUEUE.md`** at `${JAIPH_WORKSPACE:-.}` (`queue.jh` + `queue.py`). Sections use `##` headers; tags are `#hashtags` on the header line (e.g. `## My task #dev-ready`). **`python3`** must be available on `PATH` when steps run the imported `queue.py` script.
 
 | Export | Kind | Description |
 |--------|------|-------------|
 | `get_first_task()` | workflow | Returns the first task block (header + body). |
-| `next_task(tag)` | workflow | Returns the first task whose header has the given tag. |
-| `get_task_by_header(header)` | workflow | Returns a task by title (tags stripped for matching). |
-| `get_all_task_headers()` | workflow | Newline-separated task titles (no `##` prefix). |
+| `next_task(tag)` | workflow | Returns the first task whose header carries the given tag (tag name without `#`). |
+| `get_task_by_header(header)` | workflow | Returns a task by title; tags stripped for matching. |
+| `get_all_task_headers()` | workflow | Newline-separated task titles (no `##` prefix); all tasks, no tag filter at the Jaiph layer. |
 | `mark_task_dev_ready(header)` | workflow | Adds `#dev-ready` to the matching header. |
 | `remove_completed_task(header)` | workflow | Removes the task with that title. |
 | `set_task_description_from_file(header, bodyPath)` | workflow | Replaces body text from a UTF-8 file; header unchanged. |
 | `has_tasks()` | rule | Passes if the queue has at least one task. |
-| `task_is_dev_ready(task)` | rule | Passes if the task text has `#dev-ready` on the header. |
+| `task_is_dev_ready(task)` | rule | Passes if the task text has `#dev-ready` on the header line. |
 | `all_dev_ready()` | rule | Passes if every task has `#dev-ready`. |
 
-The module also defines a `default` workflow for **direct CLI** use (arguments are forwarded to the Python helper). For example: `jaiph .jaiph/libs/jaiphlang/queue.jh headers`.
+The module also defines a `default` workflow for **direct CLI** use (arguments pass through to the Python helper). Examples:
+
+```bash
+jaiph .jaiph/libs/jaiphlang/queue.jh headers
+jaiph .jaiph/libs/jaiphlang/queue.jh get dev-ready
+jaiph .jaiph/libs/jaiphlang/queue.jh json
+```
+
+The Python helper’s `headers` command accepts an optional tag when invoked directly; the exported Jaiph workflow `get_all_task_headers()` does not take parameters and always lists every title.
 
 ### `jaiphlang/artifacts` — publishing files out of the sandbox
 
-Copies files from the **workspace** (or sandbox overlay) into the run’s `artifacts/` tree so they remain on the host after a Docker run or process exit. The kernel sets `JAIPH_ARTIFACTS_DIR` to the writable directory for the current run. See [Architecture](architecture.md#durable-artifact-layout) and [Sandboxing](sandboxing.md) for how that interacts with the read-only workspace in Docker.
+Copies files from the **workspace** (or sandbox overlay) into the run’s `artifacts/` tree so they remain on the host after Docker teardown or process exit. The runtime sets **`JAIPH_ARTIFACTS_DIR`** to the writable directory for the current run. See [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) and [Sandboxing](sandboxing.md) for the read-only workspace contract in Docker.
 
 ```jaiph
 import "jaiphlang/artifacts" as artifacts
@@ -94,4 +112,19 @@ workflow default() {
 
 | Workflow | Description |
 |----------|-------------|
-| `save(paths)` | `paths` is a single file path or a **newline-separated** list of file paths. Each file is copied to `${JAIPH_ARTIFACTS_DIR}/…` using the same relative path (`./` prefix stripped; absolute sources use `basename` only). Returns the absolute destination path(s), one per line, in order. Fails if the list is empty or any file is missing. |
+| `save(paths)` | `paths` is a single file path or a **newline-separated** list of file paths. Blank lines are ignored. Each file is copied to `${JAIPH_ARTIFACTS_DIR}/…` preserving relative layout (`./` stripped; absolute sources use `basename` only). Returns absolute destination path(s), one per line, in order. Exits with failure if the list is empty after trimming, any path is missing, or `JAIPH_ARTIFACTS_DIR` is unset. |
+
+### `jaiphlang/git` — git hygiene helpers and an example commit flow
+
+Small **exported rules** around `git status` / `git rev-parse`, plus **`commit(task)`** / **`default(task)`** workflows that drive an agent-backed prompt to stage and commit changes and write a patch file. This module is **opinionated** (Cursor agent defaults in a `config` block); read `.jaiph/libs/jaiphlang/git.jh` before reusing or trimming it.
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `in_git_repo()` | rule | Passes when `git rev-parse --is-inside-work-tree` succeeds (after marking the workspace as a safe directory). |
+| `branch_clean()` | rule | Passes when `git status --porcelain` is empty. |
+| `has_changes()` | rule | Passes when there are porcelain changes (fails on a clean tree). |
+| `is_clean()` | rule | Ensures `in_git_repo()` and `branch_clean()`. |
+| `commit(task)` | workflow | Ensures repo + changes, runs a structured `prompt`, writes `git format-patch` output to a `.patch` path, returns that path. |
+| `default(task)` | workflow | Delegates to `commit(task)`. |
+
+Use these as patterns for your own libraries: thin `script` wrappers, composable `rule`s, and workflows that call them.
diff --git a/docs/sandboxing.md b/docs/sandboxing.md
index 1e56ebfb..da4a9e92 100644
--- a/docs/sandboxing.md
+++ b/docs/sandboxing.md
@@ -9,7 +9,7 @@ redirect_from:
 
 Workflows orchestrate **managed scripts** and other steps on the machine where `jaiph run` executes. That power is useful for builds and agents, but it also means a script can read files, call the network, and run arbitrary programs unless you constrain it. Jaiph addresses that at two layers: **language rules** (what may appear in a rule body) and **Docker-backed isolation** for `jaiph run` (on by default via env; see [Enabling Docker](#enabling-docker)). You can rely on rules alone, turn Docker off for host execution, or combine both.
 
-At a high level, the **CLI** chooses local vs Docker launch; the **Node workflow runtime** (`NodeWorkflowRuntime` in `src/runtime/kernel/`) interprets the same AST either way. See [Architecture](architecture.md) for how compile validation, the runner child, and durable artifacts fit together.
+At a high level, the **CLI** chooses local vs Docker launch (see `src/runtime/docker.ts`); the **Node workflow runtime** (`NodeWorkflowRuntime` in `src/runtime/kernel/`) interprets the same AST either way. See [Architecture](architecture.md) for how compile validation, the runner child, and durable artifacts fit together.
 
 Both local and Docker runs stream `__JAIPH_EVENT__` on **stderr** only; [Hooks](hooks.md) always run on the **host** CLI and read that stream, even when the workflow runs in a container. For `config` syntax, allowed keys, and merge rules, see [Configuration](configuration.md). For the full step-type matrix, see [Grammar](grammar.md).
 
@@ -19,9 +19,9 @@ Rules restrict which step types are allowed in their body — enforced at **comp
 
 Disallowed in rules: **raw shell lines** (every line must be a recognized Jaiph step — use a `script` and `run`), `prompt`, inbox **`send`** / routing, and **`run async`**. See the grammar page for the authoritative list and examples.
 
-The runtime executes rules by walking the AST in-process (`NodeWorkflowRuntime.executeRule`). There is no per-rule OS sandbox -- no mount namespace, no automatic read-only filesystem. When a rule runs a script step, that script executes as a normal managed subprocess with full access to paths the process user can reach. Treat rules as non-mutating checks by convention; perform intentional filesystem changes in workflows, not rules.
+The runtime executes rules by walking the rule body in-process (same interpreter as workflows; see `executeRule` in `src/runtime/kernel/node-workflow-runtime.ts`). There is no per-rule OS sandbox — no mount namespace, no automatic read-only filesystem. When a rule runs a script step, that script executes as a normal managed subprocess with full access to paths the process user can reach. Treat rules as non-mutating checks by convention; perform intentional filesystem changes in workflows, not rules.
 
-`jaiph test` executes tests in-process with `NodeTestRunner` and does not use Docker or a separate rule sandbox.
+`jaiph test` executes tests in-process via `runTestFile()` (`src/runtime/kernel/node-test-runner.ts`) and does not use Docker or a separate rule sandbox.
 
 ## Threat model
 
@@ -29,7 +29,7 @@ Docker sandboxing is designed to contain damage from untrusted or semi-trusted w
 
 **What Docker protects against:**
 
-- **Filesystem access** -- Scripts inside the container cannot read or write arbitrary host paths. The container's `/jaiph/workspace` is either an in-container fuse-overlayfs union over a read-only bind of the host workspace (overlay mode, writes land in a tmpfs upper layer and are discarded on exit) or a host-side clone of the workspace mounted read-write (copy mode, the clone is removed on exit). Only the run-artifacts directory (`/jaiph/run`) persists writes back to the host workspace.
+- **Filesystem access** -- Scripts inside the container cannot read or write arbitrary host paths. The container's `/jaiph/workspace` is either an in-container `fuse-overlayfs` merge over a read-only bind of the host workspace (overlay mode; writes go to the overlay upper/work dirs under `/tmp` inside the container and are discarded on exit) or a host-side clone of the workspace mounted read-write (copy mode; the clone is removed on exit unless kept for debugging). Only the run-artifacts directory (`/jaiph/run`) persists writes back to the host workspace.
 - **Process isolation** -- Container processes cannot see or signal host processes. Every sandboxed container uses `--cap-drop ALL` plus `--security-opt no-new-privileges`. **Overlay mode** (Linux) adds capabilities required for `fuse-overlayfs` and for dropping privileges after mount: `SYS_ADMIN`, `SETUID`, `SETGID`, `CHOWN`, and `DAC_READ_SEARCH` (see `buildDockerArgs` in `src/runtime/docker.ts`). **Copy mode** does not add capabilities. The overlay entrypoint (`runtime/overlay-run.sh`) starts as the container user `0:0` so it can mount, then normally **`exec`s `jaiph run` as the host UID/GID** via `setpriv` when `JAIPH_HOST_UID` / `JAIPH_HOST_GID` are set; copy mode uses `--user <host_uid>:<host_gid>` directly. macOS Docker Desktop does not use Linux `--user` overrides (UID mapping is handled by the VM).
 - **Credential leakage** -- Environment variable forwarding uses an explicit allowlist: only `JAIPH_*` (except `JAIPH_DOCKER_*`), `ANTHROPIC_*`, `CLAUDE_*`, and `CURSOR_*` cross the container boundary. Everything else is dropped.
 - **Mount safety** -- The host root filesystem (`/`), Docker socket (`/var/run/docker.sock`, `/run/docker.sock`), and OS internals (`/proc`, `/sys`, `/dev`) cannot be mounted into the container. Attempting to do so produces `E_VALIDATE_MOUNT`.
@@ -51,14 +51,16 @@ Docker applies to `jaiph run` only (not `jaiph test`). Enablement is **environme
 
 The container's `/jaiph/workspace` always *looks* writable to scripts but never mutates the host checkout. The CLI picks one of two sandbox primitives at launch time:
 
-- **Overlay mode** (selected when `/dev/fuse` exists on the host -- typically Linux). The host workspace is bind-mounted read-only at `/jaiph/workspace-ro`. The runtime entrypoint (`overlay-run.sh`) sets up `fuse-overlayfs` with that read-only bind as the lower layer and a tmpfs as the upper layer, merged at `/jaiph/workspace`. Writes go to the tmpfs and are discarded on container exit. Requires `/dev/fuse` in the container and the extra Linux capabilities described under [Process isolation](#threat-model) (not only `SYS_ADMIN`).
-- **Copy mode** (selected when `/dev/fuse` is missing -- typically macOS Docker Desktop, or when forced via `JAIPH_DOCKER_NO_OVERLAY=1`). Before launching the container, the CLI clones the host workspace (excluding `.jaiph/runs`) into a fresh `<runs-root>/.sandbox-<id>/` directory, then bind-mounts that clone read-write at `/jaiph/workspace`. On macOS the clone uses `cp -cR` (APFS clonefile, near-zero cost); on other platforms it falls back to `cp -pR` and emits a one-line stderr warning. The clone is removed on exit unless `JAIPH_DOCKER_KEEP_SANDBOX=1` is set. No `SYS_ADMIN`, no `/dev/fuse`, no in-container overlay script.
+- **Overlay mode** (selected when `/dev/fuse` exists on the host — typically Linux). The host workspace is bind-mounted read-only at `/jaiph/workspace-ro`. The runtime entrypoint (`runtime/overlay-run.sh`, copied into the container read-only) runs `fuse-overlayfs` with that read-only tree as the lower layer and **writable upper/work directories under `/tmp`** inside the container, merged at `/jaiph/workspace`. Writes stay in the container filesystem and are discarded when the container exits. Requires `/dev/fuse` in the container and the extra Linux capabilities described under [Process isolation](#threat-model) (not only `SYS_ADMIN`).
+- **Copy mode** (selected when `/dev/fuse` is missing — typically macOS Docker Desktop, or when forced via `JAIPH_DOCKER_NO_OVERLAY=1` or `JAIPH_DOCKER_NO_OVERLAY=true`). Before launching the container, the CLI clones the host workspace (see below) into a fresh `<runs-root>/.sandbox-<id>/` directory, then bind-mounts that clone read-write at `/jaiph/workspace`. On macOS the clone uses `cp -cR` (APFS clonefile, near-zero cost) when the filesystem supports it; otherwise it falls back to `cp -pR` and emits a one-line stderr warning. The clone is removed on exit unless `JAIPH_DOCKER_KEEP_SANDBOX` is `1` or `true`. No `SYS_ADMIN`, no `/dev/fuse`, no in-container overlay script.
+
+The clone copies each top-level entry of the workspace; under `.jaiph` it copies everything except the `runs` tree (run logs live under the separate `/jaiph/run` mount). **`.git` is not stripped** — workflows that call `git` see the same history as on the host, at the cost of a larger copy in copy mode on Linux.
 
 In both modes, run artifacts are written to a separate rw mount at `/jaiph/run` (outside the workspace sandbox) so they persist to the host.
 
 ### Enabling Docker
 
-**Turning Docker on or off** uses environment variables only — workflow files cannot enable or disable the container (see [Enabling Docker](#enabling-docker)). **Image, network, and timeout** still come from module `config` and env overrides as in [Configuration keys](#configuration-keys). The idea is that skipping the container always requires an explicit host choice (`JAIPH_UNSAFE` / `JAIPH_DOCKER_ENABLED`), not a change committed to a `.jh` file alone.
+**Turning Docker on or off** uses environment variables only — a `.jh` workflow file cannot enable or disable the container by itself. **Image, network, and timeout** still come from module `config` and env overrides as in [Configuration keys](#configuration-keys). The idea is that skipping the container always requires an explicit host choice (`JAIPH_UNSAFE` / `JAIPH_DOCKER_ENABLED`), not something you can turn on from committed workflow source alone.
 
 Docker is **on by default** for both local development and CI. To run on the host without a sandbox, set `JAIPH_UNSAFE=true`. To control Docker enablement explicitly, set `JAIPH_DOCKER_ENABLED`.
 
@@ -79,7 +81,7 @@ If Docker is enabled but `docker info` fails, the run exits with `E_DOCKER_NOT_F
 
 ### Configuration keys
 
-**Docker on/off** is **not** a `runtime.*` key — only `JAIPH_DOCKER_ENABLED` / `JAIPH_UNSAFE` control that (see [Enabling Docker](#enabling-docker)). The keys below live under `runtime.*` in **module-level** `config` only. They are merged as **`JAIPH_DOCKER_*` environment variables > module `runtime.*` > defaults** (`resolveDockerConfig` in `src/runtime/docker.ts`).
+**Docker on/off** is **not** a `runtime.*` key — only `JAIPH_DOCKER_ENABLED` / `JAIPH_UNSAFE` control that (see [Enabling Docker](#enabling-docker)). The keys below live under `runtime.*` in **module-level** `config` only. For **image**, **network**, and **timeout**, the merge is **`JAIPH_DOCKER_*` environment variables > module `runtime.*` > defaults** (`resolveDockerConfig` in `src/runtime/docker.ts`). Docker on/off does not use `runtime.*`; it follows [Enabling Docker](#enabling-docker) only.
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
@@ -114,7 +116,7 @@ Overlay mode:
 ```
 /jaiph/
   workspace-ro/       # read-only bind mount of host workspace (overlay lower layer)
-  workspace/          # fuse-overlayfs merged view (reads from -ro, writes to tmpfs)
+  workspace/          # fuse-overlayfs merged view (reads from -ro; writes to upper/work under /tmp in the container)
     *.jh              # source files
     .jaiph/           # project config
   run/                # writable bind mount for this run's artifacts (host runs root)
@@ -150,15 +152,15 @@ On **Linux**, if the host UID/GID cannot be determined (`process.getuid()` / `pr
 
 **Events** -- The container's jaiph runs in `--raw` mode: it spawns the runtime with inherited stdio, so `__JAIPH_EVENT__` JSON flows directly to the container's stderr. The host CLI reads Docker's stderr pipe and renders the progress tree. stdout carries plain script output. `STEP_END` events embed `out_content` (and `err_content` on failure) so consumers do not need host paths to step artifact files.
 
-**Sandbox primitive (overlay vs. copy)** -- Selected at launch time. If `/dev/fuse` exists on the host, the CLI uses **overlay mode**: the `overlay-run.sh` wrapper (shipped as `runtime/overlay-run.sh`, written to a temp file and mounted read-only) sets up `fuse-overlayfs` with the ro bind mount (`/jaiph/workspace-ro`) as the lower layer and a tmpfs as the upper layer, merged at `/jaiph/workspace`. All workspace writes go to the tmpfs and are discarded on container exit. On Linux hosts, the overlay container is also launched with `--security-opt apparmor=unconfined` because the default Docker AppArmor profile (active on Ubuntu 22.04+, GitHub Actions runners, and similar) denies fuse mounts even when `SYS_ADMIN` and `/dev/fuse` are present. If `fuse-overlayfs` is missing from the image or the mount still fails at runtime, the entrypoint exits with `E_DOCKER_OVERLAY` -- there is no in-container fallback. Set `JAIPH_DOCKER_NO_OVERLAY=1` on the host to opt into copy mode instead. Custom images used in overlay mode must ensure `/jaiph/workspace` is mountable by root (the official image keeps this path root-owned).
+**Sandbox primitive (overlay vs. copy)** -- Selected at launch time. If `/dev/fuse` exists on the host, the CLI uses **overlay mode**: the `overlay-run.sh` wrapper (shipped as `runtime/overlay-run.sh`, written to a temp file and mounted read-only) runs `fuse-overlayfs` with the ro bind mount (`/jaiph/workspace-ro`) as the lower layer and **writable upper/work directories under `/tmp`** (`overlay-run.sh` uses `/tmp/overlay-upper` and `/tmp/overlay-work`), merged at `/jaiph/workspace`. Workspace writes stay in the container and are discarded on container exit. On Linux hosts, the overlay container is also launched with `--security-opt apparmor=unconfined` because the default Docker AppArmor profile (active on Ubuntu 22.04+, GitHub Actions runners, and similar) denies fuse mounts even when `SYS_ADMIN` and `/dev/fuse` are present. If `fuse-overlayfs` is missing from the image or the mount still fails at runtime, the entrypoint exits with `E_DOCKER_OVERLAY` — there is no in-container fallback. Set `JAIPH_DOCKER_NO_OVERLAY=1` (or `true`) on the host to opt into copy mode instead. Custom images used in overlay mode must ensure `/jaiph/workspace` is mountable by root (the official image keeps this path root-owned).
 
-If `/dev/fuse` is missing on the host, the CLI uses **copy mode**: before launching the container it clones the workspace into `<runs-root>/.sandbox-<id>/` (excluding `.jaiph/runs`) using `cp -cR` on macOS (APFS clonefile, O(1) per file) or `cp -pR` elsewhere (a real copy; a single stderr warning is printed when the fast path is unavailable). The clone is bind-mounted rw at `/jaiph/workspace`. After the container exits — whether normally, via signal (SIGINT/SIGTERM), or due to an uncaught error — the clone is removed unless `JAIPH_DOCKER_KEEP_SANDBOX=1` is set, in which case the path is left in place for debugging.
+If `/dev/fuse` is missing on the host, the CLI uses **copy mode**: before launching the container it clones the workspace into `<runs-root>/.sandbox-<id>/` using `cp -cR` on macOS when clonefile works (otherwise `cp -pR` and a one-time stderr warning), or `cp -pR` on other platforms. The clone is bind-mounted rw at `/jaiph/workspace`. After the container exits — whether normally, via signal (SIGINT/SIGTERM), or due to an uncaught error — the clone is removed unless `JAIPH_DOCKER_KEEP_SANDBOX` is `1` or `true`, in which case the path is left in place for debugging.
 
 **Run artifacts** -- The host CLI mounts the resolved host runs root at `/jaiph/run:rw` inside the container. By default this is `.jaiph/runs` under the workspace; a relative `JAIPH_RUNS_DIR` is resolved under the workspace; an absolute `JAIPH_RUNS_DIR` must stay within the workspace or the run fails with `E_DOCKER_RUNS_DIR`. `JAIPH_RUNS_DIR` is set to `/jaiph/run` inside the container, so the runtime writes artifacts directly into the requested host path.
 
-**Path remapping** {#path-remapping} -- Inside the container, the runtime records artifact paths relative to `/jaiph/run` (e.g. `/jaiph/run/2026-04-21/07-55-32-say_hello.jh/000003-script__validate_name.err`). These container-internal paths do not exist on the host. After the container exits, the host CLI remaps every container path that starts with `/jaiph/run/` to the corresponding path under the bind-mounted host runs directory (the `sandboxRunDir`). This ensures the failure footer (`Logs:`, `Summary:`, `out:`, `err:`) printed to stderr shows valid **host** paths that can be opened directly. The `run_summary.jsonl` file also records container-internal `out_file` / `err_file` values; the CLI applies the same remapping when reading these fields to locate artifact content for the "Output of failed step" excerpt. When the container meta file is inaccessible from the host (which is typical in Docker mode), the CLI discovers the run directory by scanning the bind-mounted runs directory for a `run_summary.jsonl` whose `WORKFLOW_START` event matches the expected `JAIPH_RUN_ID`. This run-id stamping ensures that concurrent `jaiph run` invocations sharing the same `JAIPH_RUNS_DIR` each report their own run directory, not a sibling's. The net effect is that Docker and no-sandbox runs produce identical failure footers — same structure, same host-resolvable paths, same step output excerpt.
+**Path remapping** {#path-remapping} -- Inside the container, the runtime records artifact paths relative to `/jaiph/run` (e.g. `/jaiph/run/2026-04-21/07-55-32-say_hello.jh/000003-script__validate_name.err`). These container-internal paths do not exist on the host. After the container exits, the host CLI remaps every container path that starts with `/jaiph/run/` to the corresponding path under the bind-mounted host runs directory (the `sandboxRunDir`). This ensures the failure footer (`Logs:`, `Summary:`, `out:`, `err:`) printed to stderr shows valid **host** paths that can be opened directly. The `run_summary.jsonl` file also records container-internal `out_file` / `err_file` values; the CLI applies the same remapping when reading these fields to locate artifact content for the "Output of failed step" excerpt. When the container meta file is inaccessible from the host (which is typical in Docker mode), the CLI discovers the run directory by scanning the bind-mounted runs directory for a `run_summary.jsonl` whose first line is a `WORKFLOW_START` event with `run_id` equal to the expected run id (the same value as `JAIPH_RUN_ID` on the host). This ties concurrent `jaiph run` invocations sharing the same runs root to distinct run directories. The net effect is that Docker and no-sandbox runs produce identical failure footers — same structure, same host-resolvable paths, same step output excerpt.
 
-**Workspace immutability contract** -- Docker runs cannot directly modify the host workspace. In overlay mode the host checkout is bind-mounted read-only and writes land in a tmpfs upper layer that is discarded on container exit. In copy mode the container writes to a separate host-side clone of the workspace (`<runs-root>/.sandbox-<id>/`), which is removed on container exit unless explicitly kept for debugging. In both modes the only persistence channel from a Docker run to the host is the run-artifacts directory (`/jaiph/run` → host `.jaiph/runs`). Non-Docker (local) runs are unaffected by this contract.
+**Workspace immutability contract** -- Docker runs cannot directly modify the host workspace. In overlay mode the host checkout is bind-mounted read-only and writes land in the overlay upper layer (under `/tmp` inside the container) and are discarded on container exit. In copy mode the container writes to a separate host-side clone of the workspace (`<runs-root>/.sandbox-<id>/`), which is removed on container exit unless explicitly kept for debugging. In both modes the only persistence channel from a Docker run to the host is the run-artifacts directory (`/jaiph/run` → host `.jaiph/runs`). Non-Docker (local) runs are unaffected by this contract.
 
 **Workspace patch export** -- To capture workspace changes as a patch, run `git diff` (or your own exporter) inside the workflow, write the result to a file under the workspace, then call `artifacts.save(local_path)` so the patch lands in the run’s `artifacts/` tree on the host. Callers choose when and what to record. The published GHCR runtime image includes `git` if you use it from a script step. See [Libraries — `jaiphlang/artifacts`](libraries.md#jaiphlangartifacts--publishing-files-out-of-the-sandbox).
 
@@ -170,7 +172,7 @@ If `/dev/fuse` is missing on the host, the CLI uses **copy mode**: before launch
 
 ### Failure modes
 
-Docker-related errors use `E_DOCKER_*` codes for programmatic detection:
+The table below lists Docker run failures and the codes emitted in logs or error output. Most are `E_DOCKER_*`; **`E_TIMEOUT`** and **`E_VALIDATE_MOUNT`** appear here because they surface during container runs or mount validation, not inside the interpreter.
 
 | Error code | Trigger | Behavior |
 |------------|---------|----------|
@@ -178,12 +180,12 @@ Docker-related errors use `E_DOCKER_*` codes for programmatic detection:
 | `E_DOCKER_PULL` | `docker pull` fails (network error, image not found, auth failure) | Run exits. Check registry access and image name. |
 | `E_DOCKER_NO_JAIPH` | Selected image does not contain a `jaiph` CLI | Run exits with guidance to use the official image or install jaiph. |
 | `E_DOCKER_RUNS_DIR` | Absolute `JAIPH_RUNS_DIR` points outside the workspace | Run exits. Use a relative path or an absolute path within the workspace. |
-| `E_DOCKER_OVERLAY` | Overlay mode selected but `fuse-overlayfs` is missing from the image or the mount fails inside the container | Container exits with code 78. Use the official runtime image, install `fuse-overlayfs` in your custom image, or set `JAIPH_DOCKER_NO_OVERLAY=1` on the host to switch to copy mode. The CLI already passes `--security-opt apparmor=unconfined` on Linux to defeat the default AppArmor fuse-deny; remaining failures usually mean the host kernel itself blocks fuse mounts (rootless docker without the right user-namespace setup, locked-down kernel, etc.). |
-| `E_DOCKER_TIMEOUT` | `JAIPH_DOCKER_TIMEOUT` or `runtime.docker_timeout_seconds` is not a valid non-negative integer | Run exits before container launch. Value must be a non-negative integer; `0` disables the timeout. |
+| `E_DOCKER_OVERLAY` | Overlay mode selected but `fuse-overlayfs` is missing from the image or the mount fails inside the container | Container exits with code 78. Use the official runtime image, install `fuse-overlayfs` in your custom image, or set `JAIPH_DOCKER_NO_OVERLAY=1` (or `true`) on the host to switch to copy mode. The CLI already passes `--security-opt apparmor=unconfined` on Linux to defeat the default AppArmor fuse-deny; remaining failures usually mean the host kernel itself blocks fuse mounts (rootless docker without the right user-namespace setup, locked-down kernel, etc.). |
+| `E_DOCKER_TIMEOUT` | `JAIPH_DOCKER_TIMEOUT` is empty, non-numeric, negative, or has trailing junk; or `runtime.docker_timeout_seconds` is negative in the parsed module | Run exits before container launch. A valid value is a non-negative integer; `0` disables the timeout. |
 | `E_DOCKER_UID` | Linux host UID/GID detection failed (`process.getuid` and `id -u` both unavailable) | Run exits before container launch. Ensures the container never silently runs as root. Applies to both copy and overlay modes. |
 | `E_DOCKER_SANDBOX_COPY` | Copy mode failed to clone the host workspace (`cp` returned non-zero) | Run exits before container launch. Inspect the path printed in the error. |
 | `E_VALIDATE_MOUNT` | Mount targets a denied host path (`/`, `/proc`, docker socket, etc.) | Run exits before container launch. |
-| `E_TIMEOUT` | Container exceeds `runtime.docker_timeout_seconds` seconds | Container receives SIGTERM, then SIGKILL after 5s grace period. |
+| `E_TIMEOUT` | Container runs longer than the effective Docker timeout seconds (`JAIPH_DOCKER_TIMEOUT` or `runtime.docker_timeout_seconds` after merge; see [Configuration keys](#configuration-keys)) | Container receives SIGTERM, then SIGKILL after 5s grace period. |
 
 All failures are deterministic and produce non-zero exit codes. There is no silent fallback from Docker to local execution.
 
diff --git a/docs/setup.md b/docs/setup.md
index 0eefa22a..addd69de 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -7,9 +7,20 @@ redirect_from:
 
 # Setup
 
-This page is about **getting the Jaiph CLI on your machine** and **turning a directory into a Jaiph-friendly workspace**: install paths, a one-liner “try it” flow, how `jaiph run` wires arguments into workflows, formatting and artifacts, and what `jaiph init` drops into `.jaiph/`.
+## Overview
 
-For how the CLI, transpiler, and Node runtime fit together (including `JAIPH_WORKSPACE` and the detached runner), see [Architecture](architecture.md).
+Jaiph ships as a **CLI** backed by Node: it parses `.jh` sources, emits extracted **`script`** files, and starts a **Node workflow runtime** that interprets workflows in process (same stack for local runs, Docker, and tests — see [Architecture](architecture.md)). This page focuses on **installing that CLI**, **running your first workflow**, **project layout**, and **`jaiph init`** — not syntax or internals.
+
+Goals you should leave with:
+
+1. **The Jaiph CLI** on your `PATH`.
+2. A mental model for **workspace root** (`JAIPH_WORKSPACE`), **run artifacts**, and optional **`.jaiph/`** scaffolding.
+3. Pointers to **format**, **tests**, **libraries**, and deeper docs.
+
+### Prerequisites
+
+- **Node.js** — required to run `jaiph` itself (installer runs `npm` + `npm run build`).
+- **`bash`** — required on the machine if your workflows use **`script`** steps that execute shell bodies (see [Architecture — Distribution](architecture.md)): the runtime runs those as subprocesses using the host shell you configure.
 
 ## Install
 
@@ -17,28 +28,30 @@ For how the CLI, transpiler, and Node runtime fit together (including `JAIPH_WOR
 curl -fsSL https://jaiph.org/install | bash
 ```
 
-This installs Jaiph to `~/.local/bin`. Alternatively, install from npm:
+This installs a small wrapper **`jaiph`** under `~/.local/bin` plus a **`~/.local/bin/.jaiph/`** tree (CLI sources and **`jaiph-skill.md`** beside `src/`). Alternatively:
 
 ```bash
 npm install -g jaiph
 ```
 
-Verify with:
+The published npm package may **not** include `docs/jaiph-skill.md` next to the CLI the way the curl layout does — if **`jaiph init`** does not write `.jaiph/SKILL.md`, point **`JAIPH_SKILL_PATH`** at a skill file (for example clone [Agent Skill source](jaiph-skill.md) or the repo `docs/jaiph-skill.md`).
+
+Verify:
 
 ```bash
 jaiph --version
 ```
 
-If the command is not found, ensure `~/.local/bin` (installer) or the npm global bin directory is in your `PATH`.
+If the command is not found, ensure `~/.local/bin` (installer) or the npm global bin directory is on your **`PATH`** (the **`docs/run`** helper prepends `$HOME/.local/bin` automatically after installing).
 
-Switch versions at any time (re-runs the install script with a Git ref: `nightly` or `v<version>` such as `v0.9.4` when you pass `0.9.4`):
+Switch versions anytime: **`jaiph use`** re-runs your install command (default: `curl … /install | bash`) with **`JAIPH_REPO_REF`** set to **`nightly`** or to **`v`** plus the version you pass (for example **`0.9.4`** → **`v0.9.4`**).
 
 ```bash
 jaiph use nightly
-jaiph use 0.9.4
+jaiph use 0.9.4    # reinstalls tag v0.9.4
 ```
 
-The default install command is `curl -fsSL https://jaiph.org/install | bash`. Override it with `JAIPH_INSTALL_COMMAND` if you need a fork, air-gapped bundle, or local script.
+Default install invocation is `curl -fsSL https://jaiph.org/install | bash`; override **`JAIPH_INSTALL_COMMAND`** when you need a fork, offline bundle, or local script (**`docs/install-from-local.sh`** wraps `docs/install` with a repo path).
 
 ## Quick try
 
@@ -52,13 +65,13 @@ workflow default() {
 }'
 ```
 
-The script installs Jaiph automatically if it is not already on your `PATH`. Requires `node` and `curl`. For local docs or CI without hitting production URLs, the same script honors `JAIPH_SITE` (see header comments in the repo’s [`docs/run`](https://github.com/jaiphlang/jaiph/blob/main/docs/run) file).
+The script installs Jaiph if it is missing, then runs the workflow in a fresh temp directory that includes a **`.jaiph`** marker (so Docker sandboxes only mount that tree — see comments in the repo’s [`docs/run`](https://github.com/jaiphlang/jaiph/blob/main/docs/run)). Requires **`node`** and **`curl`**. For local docs or CI without production URLs, set **`JAIPH_SITE`** (documented in the same file).
 
 For more runnable samples (inbox, async, testing, ensure/catch), see the [`examples/`](https://github.com/jaiphlang/jaiph/tree/main/examples) directory.
 
 ## Running a workflow
 
-Jaiph workflows are `.jh` files. `jaiph run` loads a single file as the entry module and requires a workflow named **`default`** (`workflow default(...) { ... }`). Run it directly (executable file with a `#!/usr/bin/env jaiph` shebang) or through the CLI:
+Jaiph workflows live in **`.jh`** files ( **`*.test.jh`** suites use **`jaiph test`** instead — see [Testing](testing.md)). **`jaiph run`** loads a **single entry file** and runs the workflow named **`default`** (`workflow default(...) { ... }`). Use a **shebang** (`#!/usr/bin/env jaiph`) or the CLI — if the first argument is an existing **`.jh`** path, **`*.test.jh`** routes to **`jaiph test`** and other **`.jh`** files to **`jaiph run`** (see [CLI — file shorthand](cli.md#file-shorthand)).
 
 ```bash
 ./path/to/main.jh "feature request or task"
@@ -66,23 +79,35 @@ Jaiph workflows are `.jh` files. `jaiph run` loads a single file as the entry mo
 jaiph run ./path/to/main.jh "feature request or task"
 ```
 
-Arguments after the `.jh` path are bound **by position** to the named parameters of `workflow default` (for example `workflow default(task)` → `${task}` in the body; see [Language — Parameters and arguments](language.md#parameters-and-arguments)). The CLI sets `JAIPH_WORKSPACE` to the detected workspace root (walk upward from the directory containing the entry `.jh` file, looking for `.jaiph` / `.git` markers; see [Architecture](architecture.md)); managed **script** steps receive `$1`, `$2`, … only for arguments passed at the corresponding `run` step, not automatically from the CLI unless the workflow forwards them (see [Language — `run`](language.md#run--execute-a-workflow-or-script)).
+Arguments after the `.jh` path are bound **by position** to the named parameters of `workflow default` (for example `workflow default(task)` → `${task}` in the body; see [Language — Parameters and arguments](language.md#parameters-and-arguments)).
+
+### Workspace root
+
+The CLI sets **`JAIPH_WORKSPACE`** to a **workspace root** before it spawns the workflow runner. For **`jaiph run`**, detection starts at the **directory containing the entry `.jh` file** and walks **upward** until it finds **`.jaiph`** or **`.git`**, with guards for shared temp trees (see `detectWorkspaceRoot` in `src/cli/shared/paths.ts`). If no marker is found before the filesystem root, the **starting directory** (the entry file’s directory) is used as the workspace. That root is what import resolution and **`.jaiph/libs/`** are scoped to (see [Libraries](libraries.md)).
+
+Managed **script** steps receive **`$1`**, **`$2`**, … only for arguments passed at the corresponding **`run`** step in the workflow — not automatically from the CLI unless the workflow forwards them (see [Language — `run`](language.md#run--execute-a-workflow-or-script)).
 
 ### Run artifacts
 
-Each run writes durable files under `.jaiph/runs/`. See [Runtime artifacts](artifacts.md) for the directory layout, per-step logs, the JSONL timeline, and inbox files.
+Each run writes durable files under **`.jaiph/runs/`**. See [Runtime artifacts](artifacts.md) for layout, per-step logs, the JSONL timeline, and inbox files.
 
 ### Formatting
 
-Enforce consistent style across `.jh` files:
+Enforce consistent style across `.jh` / `*.test.jh` files (paths must end in **`.jh`**):
 
 ```bash
 jaiph format flow.jh           # rewrite in place
-jaiph format --check *.jh      # CI-safe: exits 1 when changes needed; *.test.jh matches too (suffix .jh)
+jaiph format --check flow.jh tests/flow.test.jh   # CI-safe: exits 1 when changes needed
 jaiph format --indent 4 flow.jh
 ```
 
-See [CLI — `jaiph format`](cli.md#jaiph-format) for all options.
+Use your shell’s globbing if you pass multiple files (for example `jaiph format --check *.jh` when your shell expands the pattern). See [CLI — `jaiph format`](cli.md#jaiph-format).
+
+### Validate, test, and libraries (next steps)
+
+- **`jaiph compile`** — validates the import closure (**`validateReferences` only**); no script emission or runner. See [Architecture — Summary](architecture.md#summary) and [CLI](cli.md).
+- **`jaiph test`** — runs **`*.test.jh`** blocks in-process with mocks. See [Testing](testing.md).
+- **`jaiph install`** — fetches reusable modules into **`.jaiph/libs/`**. See [Libraries](libraries.md).
 
 ## Workspace setup
 
@@ -93,13 +118,13 @@ jaiph init              # current directory (default)
 jaiph init path/to/repo # explicit workspace root
 ```
 
-This creates a `.jaiph/` directory under the chosen root with:
+This creates **`.jaiph/`** under the chosen root with:
 
-- `.jaiph/.gitignore` — ignores ephemeral `runs/` and `tmp/` under `.jaiph/` (workflows and libraries stay tracked)
-- `.jaiph/bootstrap.jh` — an interactive workflow that asks an agent to scaffold recommended workflows for your project. The generated template uses a triple-quoted multiline prompt (`prompt """ ... """`) and logs the bootstrap summary (`log` of the prompt result).
-- `.jaiph/SKILL.md` — copied from the skill file resolved at init time: if `JAIPH_SKILL_PATH` points at an existing file, that wins; otherwise the CLI searches paths next to the installed package and typical checkout layouts (including `./docs/jaiph-skill.md` when your cwd is the repo root). If none is found, init skips the file and tells you to set `JAIPH_SKILL_PATH` and run again.
+- **`.jaiph/.gitignore`** — ignores ephemeral **`runs/`** and **`tmp/`** under **`.jaiph/`** (workflows and libraries stay tracked).
+- **`.jaiph/bootstrap.jh`** — an executable workflow with a triple-quoted multiline **`prompt`** and **`log`** of the result; it points the agent at **`.jaiph/SKILL.md`**.
+- **`.jaiph/SKILL.md`** — copied only when **`resolveInstalledSkillPath()`** finds **`jaiph-skill.md`**; see **`src/cli/shared/paths.ts`** (**`JAIPH_SKILL_PATH`** first when that file exists, then **`jaiph-skill.md`** next to the shipped **`src/`** tree — the curl installer keeps that under **`~/.local/bin/.jaiph/`** by default — then **`docs/jaiph-skill.md`** as a sibling of that **`src/`** parent, then **`docs/jaiph-skill.md`** under **`process.cwd()`**). If nothing resolves, **`jaiph init`** skips the file and tells you to set **`JAIPH_SKILL_PATH`** and run again.
 
-Run the bootstrap workflow to get started:
+Run the bootstrap workflow:
 
 ```bash
 ./.jaiph/bootstrap.jh
@@ -107,4 +132,8 @@ Run the bootstrap workflow to get started:
 
 ### Workspace convention
 
-By convention, keep Jaiph workflow files in `<project_root>/.jaiph/` so workspace-root detection and agent setup stay predictable. The CLI exports `JAIPH_WORKSPACE` to that detected root when it launches the workflow runner (same root the validator uses for `.jaiph/libs/` imports). Reusable `.jh` modules installed with `jaiph install` live under `.jaiph/libs/` (see [Libraries](libraries.md)). Optional Docker sandboxes use a separate mount contract; see [Sandboxing](sandboxing.md) for how `jaiph run` selects container vs host execution.
+By convention, keep Jaiph workflow files under **`<project_root>/.jaiph/`** so workspace-root detection and agent setup stay predictable. The runtime sees **`JAIPH_WORKSPACE`** as that detected root (same root the validator uses for **`.jaiph/libs/`** imports). Optional Docker sandboxes use a separate mount contract; see [Sandboxing](sandboxing.md) for how **`jaiph run`** selects container vs host execution.
+
+### Building from source
+
+Contributors typically clone the repo, run **`npm install`** and **`npm run build`**, and invoke **`node dist/src/cli.js`** (or build the standalone Bun binary per [Contributing](contributing.md)). That path is separate from the curl/npm end-user install above.
diff --git a/docs/spec-async-handles.md b/docs/spec-async-handles.md
index 905f9482..f22a7dbe 100644
--- a/docs/spec-async-handles.md
+++ b/docs/spec-async-handles.md
@@ -9,15 +9,15 @@ redirect_from:
 
 ## Context
 
-Pipelines often wait on work that could overlap: several scripts or workflows are independent, and the author wants the **main sequence** to move on while that work runs. A generic way to do that in Jaiph is **`run async`**: start the callee in parallel, get a value you can read later, and let the runtime guarantee nothing is left dangling when the current **step list** returns.
+Concurrent work is a common orchestration problem: independent steps could run in parallel while the main line of the workflow keeps going, as long as completion and errors are accounted for before the surrounding scope finishes.
 
-**This page** is the value model: what `Handle<T>` means, when it becomes a real string, and how `recover` / `catch` and progress reporting interact. Syntax and step forms live in the [Language — `run async`](language.md#run-async--concurrent-execution-with-handles) and [Grammar — `run async`](grammar.md#run-async--concurrent-execution-with-handles) sections. For system layout (AST interpreter, events, `async_indices` on the CLI), see [Architecture](architecture.md).
+Jaiph addresses that with **`run async`**: the runtime starts a normal `run` target in the background, exposes the in-flight result as a **handle**, and **joins** every handle created in the current step list when that list ends—so nothing is left dangling. This page is about that **value model** (when a handle becomes a real string, how failures propagate, and how events look on the wire). Syntax lives in [Language — `run async`](language.md#run-async--concurrent-execution-with-handles) and [Grammar — `run async`](grammar.md#run-async--concurrent-execution-with-handles). For where this fits in the interpreter, events, and CLI progress, see [Architecture](architecture.md).
 
-**Implementation fact:** The behavior is implemented in **`NodeWorkflowRuntime`** — a handle is a tracked in-flight `run` result, joined at the [step list boundary](#implicit-join) that registered it. That is the same in-process runtime as in [Architecture — System overview](architecture.md#system-overview); there is no second execution engine for async work.
+**Implementation:** All of this runs in **`NodeWorkflowRuntime`** (`src/runtime/kernel/node-workflow-runtime.ts`)—the same AST interpreter described in [Architecture — System overview](architecture.md#system-overview). A handle is bookkeeping on an in-flight **`run`**; it is joined at the [`executeSteps`](#implicit-join) scope that registered it.
 
 ## Overview
 
-`run async ref(args)` schedules the same **`run` target** (workflow or script) **without blocking** the current step list. The expression’s value is a **handle**—conceptually `Handle<T>` where `T` is what a synchronous `run` would have produced (return value of a workflow, or trimmed stdout of a script). The handle is materialized in the variable map as an **opaque** string; the first **non-passthrough** use that needs the real value **awaits** the in-flight work and then **replaces** the variable with the resolved string for later reads.
+`run async ref(args)` schedules the same **`run` target** (workflow or script) **without blocking** the current step list. The value is a **handle**—conceptually `Handle<T>` where `T` is what a synchronous `run` would have produced (workflow **`return`**, or trimmed script stdout). In the runtime variable map the handle is stored as an opaque string token (`__JAIPH_HANDLE__…`); the first **non-passthrough** use that needs the real value **awaits** the scheduled work, then **replaces** that binding with the resolved string (or clears it on failure—see [Resolution](#resolution)).
 
 ## Handle creation
 
@@ -39,36 +39,45 @@ A handle resolves to the `run` result: workflow **`return`**, or **trimmed scrip
 
 ### Reads that force resolution
 
+The runtime scans for `${name}` (and related interpolation) in the places below. **Call arguments:** the parser rewrites **bare identifier** arguments such as `run downstream(h)` into `${h}` form for execution, so handles are resolved there too—same behavior as an explicit quoted interpolation in that position (see [Grammar — Call-site arguments](grammar.md#call-site-arguments) and [Language — `run`](language.md#run--execute-a-workflow-or-script)).
+
 | Access pattern | Example | Forces resolution? |
 | --- | --- | --- |
-| String / template interpolation (including `log` / `fail` / `return` messages) | `log "result: ${h}"` | Yes |
-| `run` (or `ensure`) argument strings that use `${var}` | `run downstream("${h}")` | Yes — handles in `${…}` are resolved when args are built |
-| `if` subject | `if h == "ok" { ... }` | Yes — subject is read after handle handling |
+| String / template interpolation (`log`, `logerr`, `fail`, `return`, `const … = "…"`, shell one-liners, and other orchestration strings using `interpolate`) | `log "result: ${h}"` | Yes |
+| Arguments to `run` / `ensure` (bare identifiers compile to `${name}`; quoted args with `${…}` use the same resolution path) | `run downstream(h)` or `run downstream("pref_${h}")` | Yes |
+| Prompt body (string, identifier, or triple-quoted) before the model call | `prompt "ctx: ${h}"` | Yes |
+| `if` subject variable | `if h == "ok" { ... }` | Yes — subject is resolved when it is still a handle token |
 | `match` subject | `match h { ... }` | Yes |
-| Send with a `${var}` payload (or a quoted string containing it) | `findings <- ${h}` | Yes — `${name}` in the RHS is scanned to resolve handles (`findings` is the channel name) |
+| Literal or `var` send RHS that contains `${…}` | `findings <- "${h}"` or `findings <- ${h}` (see send forms in [Inbox](inbox.md)) | Yes — `${name}` tokens in the payload are scanned |
 
-**Send RHS:** use `${var}` in the `channel <- …` payload (or a quoted string containing `${var}`). Resolution follows the same `${...}`-based path as in other steps; a bare shell-style `$name` in the `var` RHS is not a substitute for `${name}` in the current runtime.
+**Send RHS:** For the `var`-style RHS, use `${name}`; a bare `$name` is not treated as a handle reference in the Node runtime.
 
 ### Passthrough (does not force resolution)
 
-Only the **binding step** that starts the async work is non-blocking:
+Only the step that **starts** the async work avoids waiting on the result:
 
 | Access pattern | Example | Forces resolution? |
 | --- | --- | --- |
-| Initial handle capture | `const h = run async foo()` | No — stores the handle token; the `run async` has already been scheduled |
+| `const` binding from `run async` | `const h = run async foo()` | No — stores the handle token; work is already scheduled |
+| Bare `run async` (no capture variable) | `run async bar()` | No read of a value here; the handle still [joins](#implicit-join) at scope end |
+
+Any later use that needs a real string—including the first `${h}` inside a `const` RHS, or passing `h` as a bare `run` argument—forces resolution. There is no separate “copy handle without reading” statement; aliasing is done by passing the name through steps that eventually interpolate or join.
 
-Every later use of `h` that goes through the **read** paths in the table above (or any place the runtime must treat `h` as a real string) forces resolution, including the first `${h}` in a `const`, `log`, or `return` string.
+If resolution fails (non-zero underlying `run`), the step or join fails with the same error shape as a synchronous `run`; the bound variable is cleared to an empty string in the scope where resolution ran.
 
-After resolution, the variable **holds the string value**; further reads are ordinary string reads (no re-`run`).
+After a **successful** resolution, the variable holds the result string; further reads are ordinary string reads.
 
 ## Implicit join
 
-When the **step list** you are in finishes, the runtime **awaits every `run async` handle** that was still registered in that list’s scope. That is the “implicit join”: it is tied to the **`executeSteps` scope** for that block, not only to the outer name of a workflow. For example, handles created only inside an `if` (or a similar inner body) are joined at the end of that **inner** list, before the next line after the `if` runs. Entry workflows [drain the inbox](inbox.md#who-registers-routes-and-who-drains) when their step list ends (and after that join).
+When the **step list** you are in finishes, the runtime **awaits every `run async` handle** created in that **`executeSteps`** invocation (see `localHandleIds` in `node-workflow-runtime.ts`). That is the “implicit join”: it is per **block**, not merely per workflow name—for example, handles created only inside an `if` body are joined at the end of that **inner** list, before control continues after the `if`.
+
+For an **entry** workflow, **inbox dispatch** runs only **after** `executeSteps` returns successfully: the runtime finishes the step list and the implicit join first, then drains the channel queue ([Inbox — drain timing](inbox.md#who-registers-routes-and-who-drains), [Architecture — channels](architecture.md#channels-and-hooks-in-context)).
 
 - If all joined work succeeds, the outer step list continues or the workflow **returns** normally.
-- If any handle finishes with a **non-zero** `run` status, the block fails (or join reports an aggregate error) with a message that references the `run async` **ref** string(s) involved.
+- If any joined handle ends with a **non-zero** status, the scope fails; several failures are aggregated in one error. Messages refer to the **`run async`** target ref string(s). Handles that were **never read** still participate in this join.
+- If an async branch ends with a **`return`** from a `catch`/`recover` body (the same `recoverReturn` path as synchronous `run`/`ensure`), the join can propagate that **workflow return value** to the parent—mirroring non-async recovery.
 
-This matches the pre-handle model where all async work was effectively awaited before the workflow could complete, but allows overlapping steps **until** a read or a scope boundary forces ordering.
+This preserves the older “all async work settled before the workflow could complete” guarantee, while still allowing overlap **until** an explicit read or a scope boundary forces ordering.
 
 ## `recover` and `catch`
 
@@ -86,7 +95,7 @@ const b1 = run async foo() recover(err) {
 1. The async path runs `foo()`.
 2. If `foo()` succeeds, the handle resolves to that success value.
 3. If it fails, `err` is the merged **stdout+stderr** of the failure, and the `recover` body runs.
-4. If the `recover` body **succeeds** (status 0 and no `return` from the repair), `foo()` is run again.
+4. If the `recover` body finishes with status 0 **and** does not use `return` to short-circuit the branch, `foo()` is run again. A `return …` from inside the repair body stops the loop and becomes the async branch’s result.
 5. Steps 3–4 repeat until `foo()` succeeds or the [recover limit](#retry-limit) is exhausted; then the handle result reflects the final **failure** (or last attempt), like synchronous `recover`.
 
 ### `catch` (single-shot, surface keyword `catch`)
@@ -99,18 +108,22 @@ run async foo() catch(err) {
 }
 ```
 
-The `catch` keyword is the user-facing name; the same failure-binding pattern applies as for synchronous `run … catch` (see [Language — `catch`](language.md#catch--failure-recovery) and the `run … catch` section in [Grammar](grammar.md)).
+The `catch` keyword is the user-facing name; the failure payload is the merged **stdout + stderr** text, as in synchronous `run … catch`. If the catch body succeeds without returning, the async branch is treated as **success** for join and handle resolution (status 0)—the original failure is not rethrown. A `return` from the catch body can supply a return value via the same **`recoverReturn`** path as synchronous recovery. See [Language — `catch`](language.md#catch--failure-recovery) and [Grammar](grammar.md).
 
 ### Retry limit
 
-- **Default limit:** **10** when the module’s metadata does not set `run.recover_limit`.
-- **Config:** **`run.recover_limit = N` in the file’s top-level `config { }`**. The runtime currently reads this from the **module** (the `.jh` file’s `config` block), not from a per-workflow `config` nested inside a workflow body.
+Limits apply to the **retry loop** in `recover` (including `run async … recover`).
+
+- **Default:** **10** attempts when `run.recover_limit` is unset.
+- **Config:** top-level `config { run.recover_limit = N }` in the **`.jh` file whose workflow is currently executing** the `run async` / `recover` step—that is the runtime’s `scope.filePath` for that step list, **not** necessarily the CLI entry file when you are deep in a nested `run`. Per-workflow nested `config { }` blocks are not read for this knob.
 
 ## Progress and events
 
-Async work uses the same **subscripted branch** model as before: each nested or concurrent `run async` level has a 1-based index chain (`async_indices` on step/log events; see [Architecture — CLI progress reporting pipeline](architecture.md#cli-progress-reporting-pipeline)). The CLI’s progress tree indents and labels those branches; resolving a handle does not add a separate “resolution” event beyond the branch’s own step/log events.
+Concurrent `run async` branches are tagged with a chain of **1-based indices** stored on `STEP_START`, `STEP_END`, `LOG`, and `LOGERR` events as `async_indices`; the CLI prints them as subscript prefixes on the live stream (see [Architecture — CLI progress reporting pipeline](architecture.md#cli-progress-reporting-pipeline)). Indexing uses `AsyncLocalStorage` in the runtime so nested async work gets a deeper chain. Resolving a handle does not emit a separate event—the branch’s own step/log events are the timeline.
+
+In **`jaiph test`**, the runner sets `suppressLiveEvents: true` on the in-process runtime (see [Architecture](architecture.md) — *Test runner integration*), which silences **`__JAIPH_EVENT__`** on stderr only; durable `run_summary.jsonl` (and handle semantics) behave like `jaiph run`.
 
-A PTY-based E2E test exercises TTY output for two concurrent async branches: `e2e/tests/131_tty_async_progress.sh` (summary in [Testing — PTY-based TTY tests](testing.md#pty-based-tty-tests)).
+PTY E2E coverage for interleaved async progress: `e2e/tests/131_tty_async_progress.sh` ([Testing — PTY-based TTY tests](testing.md#pty-based-tty-tests)).
 
 ## Constraints
 
@@ -122,7 +135,9 @@ A PTY-based E2E test exercises TTY output for two concurrent async branches: `e2
 
 ### Relationship to the rest of the system
 
-- **Local / Docker / tests** — the same [Node workflow runtime](architecture.md#core-components) runs `run async` everywhere; Docker and `jaiph test` do not use a different handle implementation.
-- **Script extraction** is unchanged: only script **bodies** are materialized for `JAIPH_SCRIPTS`; `run async` remains orchestration, not a new artifact type (see [Architecture](architecture.md#emit-artifacts)).
+- **Local / Docker / `jaiph test`** share the same [`NodeWorkflowRuntime`](architecture.md#core-components) code path; sandboxing changes **where** the process runs, not how handles are implemented.
+- **`buildScripts` / `JAIPH_SCRIPTS`** only materialize **`script`** bodies; `run async` does not add new on-disk artifacts ([Architecture — Emit artifacts](architecture.md#emit-artifacts)).
+
+Integration-style checks for handles and recovery live in `integration/sample-build/recover-handle.test.ts` (e.g. implicit join, passing handles into `run`, `run async … recover`).
 
-If this spec and `src/runtime/kernel/node-workflow-runtime.ts` disagree, the source is authoritative; keep [Grammar](grammar.md#run-async--concurrent-execution-with-handles) and [Language](language.md#run-async--concurrent-execution-with-handles) aligned when you change behavior.
+If this spec disagrees with **`src/runtime/kernel/node-workflow-runtime.ts`**, trust the source and update [Grammar — `run async`](grammar.md#run-async--concurrent-execution-with-handles) and [Language — `run async`](language.md#run-async--concurrent-execution-with-handles) accordingly.
diff --git a/docs/testing.md b/docs/testing.md
index 3d7aa366..87b5cd82 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -37,7 +37,9 @@ jaiph test ./e2e/workflow_greeting.test.jh
 jaiph ./e2e/workflow_greeting.test.jh
 ```
 
-**Discovery:** `jaiph test` walks the given directory recursively, or the workspace root when no path is passed. The workspace root is found by walking up from the current directory until a `.jaiph` or `.git` directory exists; if neither is found, the current directory is used.
+`jaiph path.test.jh` without the `test` subcommand is only accepted when that path resolves to an existing file (`src/cli/index.ts`); otherwise the CLI treats the token as an unknown command.
+
+**Discovery:** With no path argument, Jaiph scans the detected workspace root recursively; with a directory, it scans that tree. Only `*.test.jh` files are collected: the name must end in `.jh` and the stem must end with `.test` (see `walkTestFiles` in `src/transpile/build.ts`). The workspace root—for locating imports and setting `JAIPH_WORKSPACE`—is from `detectWorkspaceRoot` in `src/cli/shared/paths.ts`: walk upward from a starting directory (the current working directory, the directory you passed, or the parent of a single test file) until `.jaiph` or `.git` is found, subject to a few guards for shared temp directories and nested `.jaiph/tmp` layouts; if nothing matches, the resolved starting directory is used as the root.
 
 If no `*.test.jh` files are found, the command prints an error and exits with status 1. A file must contain at least one `test` block; otherwise the CLI reports a parse error. Passing a plain `*.jh` file that is not named `*.test.jh` is rejected — use `jaiph run` for those.
 
@@ -199,7 +201,7 @@ When a workflow uses typed prompts (`returns "{ ... }"`), mock text must be a si
 
 ## Pass/fail reporting
 
-Each test block runs in isolation. Assertions, shell errors, or a workflow exiting non-zero (without `allow_failure`) mark that case as failed.
+Each test block runs in isolation. Failed assertions, harness/runtime errors while executing the block, or a workflow exiting non-zero (without `allow_failure`) mark that case as failed.
 
 The runner output looks like:
 
@@ -236,9 +238,10 @@ For each workflow run inside a test block, the harness builds the runtime enviro
 | `JAIPH_WORKSPACE` | Project root (from `detectWorkspaceRoot`) |
 | `JAIPH_RUNS_DIR` | Per test block, `…/tmp/jaiph-test-block-*/.jaiph/runs` (ephemeral) |
 | `JAIPH_SCRIPTS` | Directory containing extracted `script` files from `buildScripts` (temp) |
-| `JAIPH_MOCK_RESPONSES_FILE` or `JAIPH_MOCK_DISPATCH_SCRIPT` | Set by the runner when using inline or block `mock prompt` (do not set manually) |
+| `JAIPH_MOCK_RESPONSES_JSON` | JSON array of strings: sequential inline `mock prompt "…"` / `mock prompt <const>` responses (only when no `mock prompt { … }` block exists in that case) |
+| `JAIPH_MOCK_PROMPT_ARMS_JSON` | JSON payload for pattern-based `mock prompt { … }` arms (in-process dispatch in `mock.ts` / `prompt.ts`; mutually exclusive with the responses queue for that run) |
 
-You do not set `JAIPH_TEST_MODE` yourself; the harness manages it. Its only purpose is to route prompt steps to the mock dispatcher in `prompt.ts`. It no longer controls `__JAIPH_EVENT__` stderr suppression — the test runner now passes `suppressLiveEvents: true` directly to the in-process `NodeWorkflowRuntime` constructor so test reporter output stays clean. Durable `run_summary.jsonl` writes are unaffected; production runs (`jaiph run` via the spawned `node-workflow-runner` child) do not set the flag and stream events to stderr as before.
+You do not set mock variables or `JAIPH_TEST_MODE` yourself; the harness sets them for each `run …` step that starts an in-process `NodeWorkflowRuntime`. `JAIPH_TEST_MODE` routes prompt steps to the mock path in `prompt.ts`. Suppression of live `__JAIPH_EVENT__` lines on stderr is controlled by `suppressLiveEvents: true` on that runtime (see [Architecture — Test runner integration](architecture.md#test-runner-integration-testjh-in-the-kernel)), not by `JAIPH_TEST_MODE`; durable `run_summary.jsonl` writes still append. Production `jaiph run` uses a spawned `node-workflow-runner` child without `suppressLiveEvents`, so live events keep streaming to stderr there.
 
 ## Organizing tests
 
@@ -278,6 +281,7 @@ workflow default() {
 --- input.jh
 workflow default() {
   log "hello"
+
 ```
 
 ### Format rules
@@ -318,11 +322,11 @@ Test cases are organized by error type and single-vs-multi-module:
 | File | Cases | What it covers |
 |------|-------|----------------|
 | `test-fixtures/compiler-txtar/valid.txt` | 119 | Success cases — source compiles without error (single-module) |
-| `test-fixtures/compiler-txtar/parse-errors.txt` | 274 | `E_PARSE` error cases — syntax and grammar violations |
-| `test-fixtures/compiler-txtar/validate-errors.txt` | 88 | `E_VALIDATE`, `E_IMPORT_NOT_FOUND`, `E_SCHEMA` error cases (single-module) |
+| `test-fixtures/compiler-txtar/parse-errors.txt` | 282 | `E_PARSE` error cases — syntax and grammar violations |
+| `test-fixtures/compiler-txtar/validate-errors.txt` | 92 | `E_VALIDATE`, `E_IMPORT_NOT_FOUND`, `E_SCHEMA` error cases (single-module) |
 | `test-fixtures/compiler-txtar/validate-errors-multi-module.txt` | 20 | Validation errors requiring imports (multi-file) |
 
-(Counts are one `# @expect` per test case; re-count after large fixture changes.)
+(Counts are lines matching `# @expect` in each `.txt` file; the runner also registers separate `node:test` meta-tests in `compiler-test-runner.ts`. Re-count after large fixture changes.)
 
 The initial cases were extracted from TypeScript test files across `src/parse/*.test.ts` and `src/transpile/*.test.ts`. Additional cases were written directly as txtar fixtures to cover compiler error paths that had no prior test coverage. Only tests that verify "source in, pass/fail out" qualify — tests that check AST structure or internal APIs remain in TypeScript.
 
@@ -413,4 +417,5 @@ The project includes a Playwright-based test (`e2e/playwright/landing-page.spec.
 - **Do not combine** `mock prompt { … }` with queue-style `mock prompt "…"` / `mock prompt <const>` in the same test block; when a block is present, queued entries are ignored.
 - **Capture** without a successful non-empty `return` concatenates all step `*.out` files in the run directory (sorted by filename), then falls back to the runtime’s aggregated output string.
 - **`expect_*` right-hand side** is either a double-quoted literal or a test `const` name — not an arbitrary expression.
+- **`expectContain` / `expectEqual` / `expectNotContain` (camelCase)** are rejected; use `expect_contain`, `expect_equal`, `expect_not_contain`.
 - **Extra CLI arguments** after the path (`jaiph test <path> [extra...]`) are accepted but ignored (reserved for future use).
diff --git a/src/cli/commands/compile.ts b/src/cli/commands/compile.ts
index 2db9c525..a375bfaa 100644
--- a/src/cli/commands/compile.ts
+++ b/src/cli/commands/compile.ts
@@ -42,8 +42,10 @@ function makeValidateContext(workspaceRoot?: string): ValidateContext {
 function printUsage(): void {
   process.stderr.write(
     "Usage: jaiph compile [--json] [--workspace <dir>] <file.jh | directory> ...\n\n" +
-      "Parse and validate modules (same checks as before `jaiph run`) without executing workflows.\n" +
-      "With a directory, all non-test *.jh files are used as entrypoints; each file’s import closure is validated.\n\n" +
+      "Parse import closures and run validateReferences only (same compile-time checks as before jaiph run).\n" +
+      "Does not emit scripts/, does not run buildRuntimeGraph, does not spawn the workflow runner.\n" +
+      "With a directory, all non-test *.jh files are used as entrypoints; each file's import closure is validated.\n" +
+      "Pass *.test.jh explicitly to validate a test module.\n\n" +
       "  --json       Print one JSON array of diagnostics to stdout (empty on success).\n" +
       "  --workspace  Override workspace root for import resolution for all paths.\n",
   );
diff --git a/src/cli/shared/usage.ts b/src/cli/shared/usage.ts
index 19630d50..8826de00 100644
--- a/src/cli/shared/usage.ts
+++ b/src/cli/shared/usage.ts
@@ -36,7 +36,8 @@ export function printUsage(): void {
       "  --indent <n>    spaces per indent level (default: 2)",
       "",
       "jaiph compile:",
-      "  Parse and validate (same as pre-run checks) without executing workflows. Useful for editors.",
+      "  Parse import closures and validateReferences only (same compile-time checks as before jaiph run;",
+      "  no scripts/ emission, no buildRuntimeGraph, no runner). Useful for editors and CI.",
       "  --json          stdout: JSON array of { file, line, col, code, message } (empty array if ok).",
       "  --workspace <dir>  workspace root for import resolution (default: auto-detect per file).",
       "",

From dadbe636208564abca53b870dde82d9775c34aac Mon Sep 17 00:00:00 2001
From: Jakub Dzikowski <jakub.t.dzikowski@gmail.com>
Date: Wed, 13 May 2026 17:25:24 +0200
Subject: [PATCH 5/5] docs: refresh pages, Jekyll Gemfile for Ruby 4, CLI
 tweaks

- Add base64/bigdecimal to docs Gemfile; update Gemfile.lock for Homebrew Ruby
- Update documentation across grammar, hooks, language, testing, etc.
- README and QUEUE updates; minor test command and usage output fixes

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 QUEUE.md                   | 17 -------
 README.md                  | 13 +++++-
 docs/Gemfile               |  3 ++
 docs/Gemfile.lock          |  4 ++
 docs/architecture.md       | 36 +++++++++------
 docs/artifacts.md          | 20 ++++----
 docs/cli.md                | 24 ++++++----
 docs/configuration.md      | 27 +++++++----
 docs/contributing.md       | 37 ++++++++-------
 docs/getting-started.md    | 20 ++++----
 docs/grammar.md            | 95 ++++++++++++++++++++++++++++++--------
 docs/hooks.md              | 54 ++++++++++------------
 docs/inbox.md              | 67 +++++++++++++++++----------
 docs/jaiph-skill.md        | 24 +++++++---
 docs/language.md           | 32 ++++++++-----
 docs/libraries.md          | 86 +++++++++++++++++++---------------
 docs/sandboxing.md         | 14 +++---
 docs/setup.md              | 20 ++++----
 docs/spec-async-handles.md | 80 +++++++++++++++++++++-----------
 docs/testing.md            | 49 ++++++++++++--------
 src/cli/commands/test.ts   |  4 +-
 src/cli/shared/usage.ts    |  1 +
 22 files changed, 450 insertions(+), 277 deletions(-)

diff --git a/QUEUE.md b/QUEUE.md
index e077f988..72264987 100644
--- a/QUEUE.md
+++ b/QUEUE.md
@@ -48,20 +48,3 @@ When starting workflows (e.g. `jaiph run` / first step), users observe a 2–4 s
 * `npm test` passes.
 
 ***
-
-## `for … in …` — optional built-in trim / skip-empty #dev-ready
-
-**Goal**
-Evaluate optional sugar (keywords, modifiers, or a small stdlib helper) for trimming each iterated line or skipping empty lines, if authors repeatedly need shell-style normalization beyond an explicit `if line != "" { … }`.
-
-**Scope**
-
-* Baseline behavior and splitting rules are documented in `docs/language.md`.
-* If a language change is chosen, add tests and note migration for workflows that would adopt it.
-
-**Acceptance criteria**
-
-* Decision recorded in `docs/language.md` (new subsection or changelog in that doc).
-* `npm test` passes.
-
-***
diff --git a/README.md b/README.md
index d4aceaa2..baeb4b2c 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # ![Jaiph](docs/logo.png)
 
-[jaiph.org](https://jaiph.org) · [Getting Started](docs/getting-started.md) ([jaiph.org/getting-started](https://jaiph.org/getting-started)) · [Setup](docs/setup.md) · [Libraries](docs/libraries.md) · [Grammar](docs/grammar.md) · [CLI](docs/cli.md) · [Configuration](docs/configuration.md) · [Testing](docs/testing.md) · [Hooks](docs/hooks.md) · [Inbox & Dispatch](docs/inbox.md) · [Sandboxing](docs/sandboxing.md) · [Runtime artifacts](docs/artifacts.md) · [Async Handles](docs/spec-async-handles.md) · [Architecture](docs/architecture.md) · [Contributing](docs/contributing.md)
+[jaiph.org](https://jaiph.org) · [Getting Started](docs/getting-started.md) ([jaiph.org/getting-started](https://jaiph.org/getting-started)) · [Setup](docs/setup.md) · [Libraries](docs/libraries.md) · [Language](docs/language.md) · [Grammar](docs/grammar.md) · [CLI](docs/cli.md) · [Configuration](docs/configuration.md) · [Testing](docs/testing.md) · [Hooks](docs/hooks.md) · [Inbox & Dispatch](docs/inbox.md) · [Sandboxing](docs/sandboxing.md) · [Runtime artifacts](docs/artifacts.md) · [Async Handles](docs/spec-async-handles.md) · [Architecture](docs/architecture.md) · [Contributing](docs/contributing.md)
 
 ---
 
@@ -64,6 +64,17 @@ npm install -g jaiph
 
 Verify: `jaiph --version`. Switch versions: `jaiph use nightly` or `jaiph use 0.9.4`.
 
+Initialize a project (optional): `jaiph init` writes `.jaiph/` with bootstrap workflow, gitignore entries for runs/tmp, and **`SKILL.md`** when the CLI resolves a skill file on disk (`JAIPH_SKILL_PATH`, install-relative `jaiph-skill.md`, or `docs/jaiph-skill.md` under cwd — see [Setup](docs/setup.md)). Canonical skill text for agents: `https://raw.githubusercontent.com/jaiphlang/jaiph/refs/heads/main/docs/jaiph-skill.md`.
+
+## Usage
+
+- Run the default workflow: `jaiph run path/to/main.jh [args...]` or `./main.jh [args...]` with a `#!/usr/bin/env jaiph` shebang.
+- Run tests: `jaiph test` (workspace), `jaiph test ./dir`, or `jaiph test path.test.jh`.
+- Validate without executing: `jaiph compile …` (same `validateReferences` checks as before `jaiph run`; no `scripts/` emission — see [Architecture](docs/architecture.md)).
+- Format sources: `jaiph format …` / `jaiph format --check …`.
+
+Full flags and environment variables: [CLI reference](docs/cli.md). Doc map: [Getting Started](docs/getting-started.md).
+
 ## Example
 
 ```jaiph
diff --git a/docs/Gemfile b/docs/Gemfile
index d5d2130d..983cec24 100644
--- a/docs/Gemfile
+++ b/docs/Gemfile
@@ -1,4 +1,7 @@
 source "https://rubygems.org"
+# Ruby 4.0+ bundles some stdlib as gems; Jekyll 3 / Liquid / safe_yaml still require them.
+gem "base64"
+gem "bigdecimal"
 gem "jekyll", "~> 3.9"
 gem "kramdown-parser-gfm"
 gem "jekyll-relative-links"
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
index 0301b67c..ad1195ae 100644
--- a/docs/Gemfile.lock
+++ b/docs/Gemfile.lock
@@ -3,6 +3,8 @@ GEM
   specs:
     addressable (2.8.9)
       public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
     colorator (1.1.0)
     concurrent-ruby (1.3.6)
     csv (3.3.5)
@@ -72,6 +74,8 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  base64
+  bigdecimal
   jekyll (~> 3.9)
   jekyll-redirect-from
   jekyll-relative-links
diff --git a/docs/architecture.md b/docs/architecture.md
index fa2f7b73..55e9ff50 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -11,6 +11,8 @@ Jaiph is a workflow system with a **TypeScript CLI** and a **JavaScript kernel**
 
 This page describes **how Jaiph is built**: repository layout of major subsystems, **core components**, compile and run pipelines, and **runtime contracts** (events, artifacts on disk, distribution). It is the map of the implementation. For workflow syntax and semantics, see the [Language](language.md) guide; this document stays on implementation boundaries.
 
+**Why this split:** the transpiler turns each `script` block (and inline script bodies) into real files under `scripts/` with a stable layout and `JAIPH_SCRIPTS`, while **`NodeWorkflowRuntime` always executes from the AST** (`buildRuntimeGraph`). That separation keeps bash entrypoints predictable for subprocesses without duplicating workflow logic in a second language.
+
 For **how to contribute** — branches, test layers, E2E assertion policy, and bash harness details — see [Contributing](contributing.md). For the `*.test.jh` **language** and test blocks, see [Testing](testing.md).
 
 ## System overview
@@ -18,18 +20,20 @@ For **how to contribute** — branches, test layers, E2E assertion policy, and b
 Workflow authors write `.jh` / `.test.jh` modules. The toolchain turns those files into **validated** modules plus **extracted script files**, then the **same AST interpreter** runs workflows whether you use local `jaiph run`, Docker, or `jaiph test`.
 
 1. Parse source into AST (the CLI parses once up front for `jaiph run` metadata such as `runtime` config; `buildRuntimeGraph` and transpilation use the same parser on disk contents).
-2. **Compile-time** validation (`validateReferences`, invoked from **`emitScriptsForModule`** / **`buildScripts()`**) runs before script extraction, not inside `buildRuntimeGraph()` (the graph loader only parses modules and follows imports). The **`jaiph compile`** command runs **`validateReferences` only**: it parses each module in the computed import closure and **does not** run **`buildScriptFiles`** or **`buildScripts`**, and never spawns the runner (`src/cli/commands/compile.ts`). For a **directory** argument it discovers `*.jh` via `walkjhFiles`, which **skips** `*.test.jh`; to validate a test module, pass that file explicitly. Imported modules in the closure are still validated recursively either way.
+2. **Compile-time** validation (`validateReferences`, invoked from **`emitScriptsForModule`** / **`buildScripts()`**) runs before script extraction, not inside `buildRuntimeGraph()` (the graph loader only parses modules and follows imports). The **`jaiph compile`** command walks the same import closure but runs **`validateReferences` only**: it parses each reachable module on disk and **does not** emit **`scripts/`** (no **`buildScriptFiles`** / **`buildScripts`**), **does not** invoke **`buildRuntimeGraph()`**, and never spawns the workflow runner (`src/cli/commands/compile.ts`). For a **directory** argument it discovers `*.jh` via `walkjhFiles`, which **skips** `*.test.jh`; to validate a test module, pass that file explicitly. Imported modules in the closure are still validated recursively either way.
 3. **CLI** (`dist/src/cli.js` via npm, or a **Bun-compiled** `dist/jaiph` binary) prepares script executables (scripts-only), then spawns a **detached child** that loads **`node-workflow-runner.js`**. That child calls `buildRuntimeGraph()` and runs **`NodeWorkflowRuntime`**. The child’s interpreter is **`process.execPath`** of the CLI process (Node when you run `node dist/src/cli.js`, the standalone Bun binary when you run `dist/jaiph`). Script steps execute as managed subprocesses; prompt, inbox I/O, and event/summary emission are handled by the kernel under `src/runtime/kernel/`.
 4. Stream live events to the CLI and persist durable run artifacts.
 
+Interactive **`jaiph run`** parses **`__JAIPH_EVENT__`** lines from the runner’s stderr, renders the progress tree, and runs hooks. **`jaiph run --raw`** skips that shell: the child uses inherited stdio so events still land on stderr unchanged — used when embedding Jaiph or when the host wraps a container (see [CLI — `jaiph run`](cli.md#jaiph-run) and [Sandboxing — Docker container isolation](sandboxing.md#docker-container-isolation)).
+
 All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`** — uses the **Node workflow runtime** (AST interpreter). Docker containers run the same `node-workflow-runner` process with the compiled JS source tree and scripts mounted read-only.
 
 ## Core components
 
-- **CLI (`src/cli`)**
+- **CLI (`src/cli`, invoked via compiled `src/cli.ts` → `dist/src/cli.js`)**
   - Entry point (`run`, `test`, `compile`, `init`, `install`, `use`, `format`). Paths ending in `.jh` / `.test.jh` are also accepted as implicit commands (see `src/cli/index.ts`).
-  - **Workflow launch** is owned in TypeScript (`src/runtime/kernel/workflow-launch.ts` + `src/cli/run/lifecycle.ts`): spawns **`node-workflow-runner.js`** with `process.execPath`, which calls `buildRuntimeGraph()` then `NodeWorkflowRuntime`. `setupRunSignalHandlers` accepts an optional `onSignalCleanup` callback for Docker sandbox teardown on SIGINT/SIGTERM.
-  - Parses runtime events and renders progress; dispatches hooks.
+  - **Workflow launch** is owned in TypeScript (`src/runtime/kernel/workflow-launch.ts` + `src/cli/run/lifecycle.ts`): spawns **`node-workflow-runner.js`** with `process.execPath`, which calls `buildRuntimeGraph()` then `NodeWorkflowRuntime`. The **`jaiph run`** path always launches the **`default`** workflow via argv wired in `workflow-launch.ts` (`node-workflow-runner` calls `runDefault`). `setupRunSignalHandlers` accepts an optional `onSignalCleanup` callback for Docker sandbox teardown on SIGINT/SIGTERM.
+  - Parses runtime events and renders progress (except `--raw`); dispatches hooks.
 
 - **Parser (`src/parser.ts`, `src/parse/*`)**
   - Converts `.jh`/`.test.jh` into `jaiphModule` AST.
@@ -42,13 +46,13 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
   - Resolves imports and symbol references; emits deterministic compile-time errors. Import resolution (`resolveImportPath` in `transpile/resolve.ts`) checks relative paths first, then falls back to project-scoped libraries under `<workspace>/.jaiph/libs/` — the workspace root is threaded through all compilation call sites. Export visibility is enforced by `validateRef` in `validate-ref-resolution.ts`: if an imported module declares any `export`, only exported names are reachable through the import alias.
 
 - **Transpiler (`src/transpiler.ts`, `src/transpile/*`)**
-  - **`emitScriptsForModule`** parses, runs **`validateReferences`**, and **`buildScriptFiles`** — the only compile path for `jaiph run` / `jaiph test` — **persists only atomic `script` files** under `scripts/`. **`buildScripts()`** can also take a **directory** of non-test `*.jh` modules (`transpile/build.ts` uses `walkjhFiles`); the **`jaiph run`** and **`jaiph test`** commands always pass a **single entry file** (`.jh` or `*.test.jh`). Inline scripts (`` run `body`(args) ``) are also emitted as `scripts/__inline_<hash>` with deterministic hash-based names. There is no workflow-level bash emission.
+  - **`emitScriptsForModule`** parses, runs **`validateReferences`**, and **`buildScriptFiles`** — the only compile path for `jaiph run` / `jaiph test` — **persists only atomic `script` files** under `scripts/`. **`buildScripts()`** can also take a **directory** of non-test `*.jh` modules (`src/transpile/build.ts` uses `walkjhFiles`); the **`jaiph run`** and **`jaiph test`** commands always pass a **single entry file** (`.jh` or `*.test.jh`). Inline scripts (`` run `body`(args) ``) are also emitted as `scripts/__inline_<hash>` with deterministic hash-based names (`inlineScriptName` in `src/inline-script-name.ts`). There is no workflow-level bash emission.
 
 - **Node Workflow Runtime (`src/runtime/kernel/node-workflow-runtime.ts`)**
   - `NodeWorkflowRuntime` interprets the AST directly: walks workflow steps, manages scope/variables, delegates prompt and script execution to kernel helpers, handles channels/inbox/dispatch, owns the frame stack and heartbeat, and writes run artifacts.
   - Three sibling modules under `src/runtime/kernel/` carry concerns that used to live inline in the runtime file. Dependency direction is one-way (orchestrator → helpers/emitter/mock); no circular imports back.
     - **`runtime-arg-parser.ts`** — stateless interpolation and call-argument parsing (`interpolate`, `parseInlineCaptureCall`, `commaArgsToInterpolated`, `parseArgsRaw`, `parseInlineScriptAt`, `parseManagedArgAt`, `parseArgTokens`, `stripOuterQuotes`, `parsePromptSchema`, `sanitizeName`, `nowIso`) plus shared constants and the `ParsedArgToken` / `PromptSchemaField` types. Direct unit tests live in `runtime-arg-parser.test.ts`.
-    - **`runtime-event-emitter.ts`** — `RuntimeEventEmitter` owns the `__JAIPH_EVENT__` stderr stream and `run_summary.jsonl` writes for workflow/step/prompt/log events, plus the monotonic step and prompt sequence counters. Constructed with `{ runId, runDir, env, getFrameStack, getAsyncIndices, suppressLiveEvents? }`; the runtime delegates all event emission to it. The optional `suppressLiveEvents` flag (forwarded from `NodeWorkflowRuntime`'s `suppressLiveEvents` option) skips the live stderr write while leaving the durable `run_summary.jsonl` append intact — used by in-process callers like the test runner that share stderr with `node --test` reporter output. The CLI's spawned `node-workflow-runner` child does not set it, so production runs stream events to stderr as before.
+    - **`runtime-event-emitter.ts`** — `RuntimeEventEmitter` owns **`__JAIPH_EVENT__`** writes on stderr (step/log traffic when not suppressed), **`run_summary.jsonl`** appends for the wider timeline (including workflow/prompt records that are summary-first), plus step/prompt sequence counters. Constructed with `{ runId, runDir, env, getFrameStack, getAsyncIndices, suppressLiveEvents? }`; the runtime delegates structured emission to it. The optional `suppressLiveEvents` flag (forwarded from `NodeWorkflowRuntime`'s `suppressLiveEvents` option) skips the live stderr **`__JAIPH_EVENT__`** lines while **`appendRunSummaryLine`** keeps updating **`run_summary.jsonl`** — used by in-process callers like the test runner that share stderr with `node --test` reporter output. The CLI's spawned `node-workflow-runner` child does not set it, so production runs stream events to stderr as before.
     - **`runtime-mock.ts`** — `executeMockBodyDef` and `executeMockShellBody` for `*.test.jh` workflow/rule/script mocks. Shell-kind mocks run `bash -c`; steps-kind mocks dispatch back into the runtime via an `executeStepsBack` callback so the body runs against the full step interpreter.
   - `buildRuntimeGraph()` (`graph.ts`) loads reachable modules with **`parsejaiph` only** (import closure); it does **not** run `validateReferences`. Cross-module refs are resolved from that graph at runtime. For **`script import`** declarations, `buildRuntimeGraph()` injects synthetic `ScriptDef` stubs (`graph.ts`) so reference resolution matches the validated compile path without re-reading external script bodies at graph-build time.
 
@@ -56,7 +60,7 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
   - Executes `*.test.jh` test blocks using `NodeWorkflowRuntime` with mock support (mock prompts, mock workflow/rule/script bodies). Pure Node harness — no Bash test transpilation.
 
 - **JS kernel (`src/runtime/kernel/`)**
-  - Prompt execution (`prompt.ts`), streaming parse (`stream-parser.ts`), schema (`schema.ts`), mocks (`mock.ts`), **`emit.ts`** (durable **`run_summary.jsonl`** helpers — `appendRunSummaryLine`, `formatUtcTimestamp` — consumed by `RuntimeEventEmitter`), **`workflow-launch.ts`** (spawn contract). **`RuntimeEventEmitter`** (`runtime-event-emitter.ts`) owns live **`__JAIPH_EVENT__`** lines on stderr and coordinates summary writes plus step/prompt sequence counters. Script subprocesses are launched directly from `NodeWorkflowRuntime`.
+  - Prompt execution (`prompt.ts`), streaming parse (`stream-parser.ts`), schema (`schema.ts`), **`mock.ts`** (sequential prompt responses / mock-arm dispatch from test env JSON), **`runtime-mock.ts`** (mock workflow/rule/script **bodies** for `*.test.jh`), **`emit.ts`** (durable **`run_summary.jsonl`** helpers — `appendRunSummaryLine`, `formatUtcTimestamp` — consumed by `RuntimeEventEmitter`), **`workflow-launch.ts`** (spawn contract). **`RuntimeEventEmitter`** (`runtime-event-emitter.ts`) owns live **`__JAIPH_EVENT__`** lines on stderr and coordinates summary writes plus step/prompt sequence counters. Script subprocesses are launched directly from `NodeWorkflowRuntime`.
 
 - **Formatter (`src/format/emit.ts`)**
   - `jaiph format` rewrites `.jh` / `.test.jh` files into canonical style. Pure AST→text emitter; no side-effects beyond file writes.
@@ -79,11 +83,11 @@ All orchestration — local `jaiph run`, `jaiph test`, and **Docker `jaiph run`*
 
 - Parse, validate, and launch workflows/tests.
 - Own **process spawn** for `jaiph run` (detached workflow runner process group for signal propagation).
-- Parse live runtime events; render terminal progress; trigger hooks.
+- Parse live runtime events; render terminal progress; trigger hooks — skipped in **`jaiph run --raw`** (child stdio inherited; see [CLI](cli.md#jaiph-run)).
 
 ## Contracts
 
-- **Live contract (runtime -> CLI):** `__JAIPH_EVENT__` JSON lines on **stderr only** — the single event channel for all modes (local and Docker). The CLI listens on stderr exclusively; stdout carries only plain script output.
+- **Live contract (runtime → observing process):** `__JAIPH_EVENT__` JSON lines on **stderr only** — the structured event channel. Hooks and the interactive CLI consume that stream; see [Hooks](hooks.md).
 - **Durable contract:** `.jaiph/runs/...` + `run_summary.jsonl` (layout below).
 
 Channel transport remains file/queue based in runtime inbox logic.
@@ -115,14 +119,15 @@ Channels are validated at compile time (`validateReferences` / send RHS rules) a
 
 ## Test runner integration (`*.test.jh` in the kernel)
 
-**How** `jaiph test` wires into the same stack as `jaiph run`: `*.test.jh` files are parsed in the CLI; `runTestFile()` drives blocks in-process. **`buildRuntimeGraph(testFile)`** is called **once per `runTestFile` invocation** and the resulting graph is reused across all blocks and `test_run_workflow` steps (the import closure is constant for a given test file within a single process run). Each `test_run_workflow` step resolves mocks against that cached graph, then constructs `NodeWorkflowRuntime` with `mockBodies` / mock prompt env, passing **`suppressLiveEvents: true`** so the in-process runtime's `__JAIPH_EVENT__` stderr writes are skipped (durable `run_summary.jsonl` writes are unaffected). Without this flag, every workflow event would print to the test process's stderr and swamp `node --test` reporter output. Mock prompts, workflows, rules, and scripts are supported through the runtime's mock infrastructure.
+**How** `jaiph test` wires into the same stack as `jaiph run`: `*.test.jh` files are parsed in the CLI; `runTestFile()` drives blocks in-process. **`buildRuntimeGraph(testFile)`** is called **once per `runTestFile` invocation** and the resulting graph is reused across all blocks and `test_run_workflow` steps (the import closure is constant for a given test file within a single process run). Each `test_run_workflow` step resolves mocks against that cached graph, then constructs `NodeWorkflowRuntime` with `mockBodies` / mock prompt env, passing **`suppressLiveEvents: true`** so **`RuntimeEventEmitter`** skips writing **`__JAIPH_EVENT__`** lines to **stderr** while still appending **`run_summary.jsonl`** for that run. Without this flag, every workflow event would print to the test process's stderr and swamp `node --test` reporter output. Mock prompts, workflows, rules, and scripts are supported through the runtime's mock infrastructure.
+
 Before that, the CLI prepares script executables via **`buildScripts(testFileAbs, tmpDir, workspaceRoot)`** — the same **`buildScripts`** helper as `jaiph run`, with the **test file as the entrypoint**. That walks the test module and its **import closure** (transitive `import` edges), runs **`validateReferences`** / **`emitScriptsForModule`** per reachable file, and writes `scripts/` so imported workflows have paths under `JAIPH_SCRIPTS`. Unrelated `*.jh` files elsewhere in the repo are not compiled unless imported.
 
 Authoring rules, fixtures, and mock syntax for `*.test.jh` are documented in [Testing](testing.md), not here.
 
 ## CLI progress reporting pipeline
 
-The progress UI combines a **static** step tree derived from the workflow AST (`cli/run/progress.ts`) with **live** updates from the runtime event stream. Event wiring: `events.ts` and `stderr-handler.ts` parse `__JAIPH_EVENT__` lines; `emitter.ts` bridges into the renderer. Line-oriented formatting (`formatStartLine`, `formatHeartbeatLine`, `formatCompletedLine`) lives primarily in `display.ts`, which shares some display helpers with `progress.ts`. Async branch numbering (subscript ₁₂₃… prefixes) is driven by `async_indices` on step and log events — the runtime propagates a chain of 1-based branch indices through `AsyncLocalStorage`, and the stderr handler renders them at the appropriate indent level. `const` steps whose value is a `match_expr` are walked for nested `run`/`ensure` arms; matched targets appear as child items in the step tree (e.g. `▸ script safe_name` under the `const` row).
+The progress UI combines a **static** step tree derived from the workflow AST (`src/cli/run/progress.ts`) with **live** updates from the runtime event stream. Event wiring: `src/cli/run/events.ts` and `src/cli/run/stderr-handler.ts` parse `__JAIPH_EVENT__` lines; `src/cli/run/emitter.ts` bridges into the renderer. Line-oriented formatting (`formatStartLine`, `formatHeartbeatLine`, `formatCompletedLine`) lives primarily in `src/cli/run/display.ts`, which shares some display helpers with `progress.ts`. Async branch numbering (subscript ₁₂₃… prefixes) is driven by `async_indices` on step and log events — the runtime propagates a chain of 1-based branch indices through `AsyncLocalStorage`, and the stderr handler renders them at the appropriate indent level. `const` steps whose value is a `match_expr` are walked for nested `run`/`ensure` arms; matched targets appear as child items in the step tree (e.g. `▸ script safe_name` under the `const` row). This pipeline does not apply to **`jaiph run --raw`**.
 
 ## Distribution: Node vs Bun standalone
 
@@ -182,6 +187,8 @@ flowchart TD
 
 ## Sequence diagram: regular flow (`*.jh`)
 
+Interactive **`jaiph run`** (no **`--raw`**): banner, progress tree, hooks, and PASS/FAIL footer.
+
 ```mermaid
 sequenceDiagram
     participant User
@@ -219,6 +226,8 @@ sequenceDiagram
     CLI-->>User: PASS/FAIL
 ```
 
+**Docker:** the inner container command is **`jaiph run --raw …`** (see [Sandboxing](sandboxing.md#docker-container-isolation)): no banner or progress UI inside the container; **`__JAIPH_EVENT__`** lines still appear on stderr for the host CLI to parse.
+
 ## Sequence diagram: `jaiph test` flow
 
 ```mermaid
@@ -256,8 +265,9 @@ sequenceDiagram
 ## Summary
 
 - `.jh` / `*.test.jh` share parser/AST; **compile-time** validation runs in **`emitScriptsForModule`** during **`buildScripts`**. **`buildRuntimeGraph`** loads modules with **parse-only** imports.
-- **`jaiph compile`** walks import closures **`validateReferences` only**, and exits — no **`buildScriptFiles`** emission, no **`buildScripts`**, no runner spawn. Directory discovery omits **`*.test.jh`** unless you pass a test file explicitly.
+- **`jaiph compile`** walks import closures with **`validateReferences` only**, and exits — no **`scripts/`** emission (**no **`buildScriptFiles`** / **`buildScripts`**), no **`buildRuntimeGraph()`**, no runner spawn. Directory discovery omits **`*.test.jh`** unless you pass a test file explicitly.
 - **Node-only runtime:** all execution — local `jaiph run`, Docker `jaiph run`, and `jaiph test` — goes through `NodeWorkflowRuntime`. Docker containers run `node-workflow-runner` with the compiled JS tree and scripts mounted, using the same semantics as local execution.
-- **CLI** owns launch, observation, hooks, and runtime preparation (`buildScripts`). Workflow execution runs in **`NodeWorkflowRuntime`**, with **script steps** as managed subprocesses.
+- **CLI** owns launch, observation, hooks (except **`jaiph run --raw`**), and runtime preparation (`buildScripts`). **`jaiph run --raw`** still emits **`__JAIPH_EVENT__`** on stderr from the runtime; the CLI does not attach the interactive progress/hooks pipeline. **`jaiph test`** passes **`suppressLiveEvents: true`** into **`NodeWorkflowRuntime`** so **`RuntimeEventEmitter`** skips writing those live stderr lines while **`run_summary.jsonl`** still records workflow traffic where the emitter appends it.
+- Workflow execution runs in **`NodeWorkflowRuntime`**, with **script steps** as managed subprocesses.
 - No workflow-level `.sh` files or `jaiph_stdlib.sh` are produced or required.
 - Contracts: `__JAIPH_EVENT__`, `.jaiph/runs`, `run_summary.jsonl`, hook payloads.
diff --git a/docs/artifacts.md b/docs/artifacts.md
index af9d6e50..397bff1a 100644
--- a/docs/artifacts.md
+++ b/docs/artifacts.md
@@ -7,13 +7,15 @@ redirect_from:
 
 # Runtime artifacts
 
-Workflow and test runners need two kinds of output: **what humans see right now** (progress, status) and **what is left behind** after the process exits (replay, diffs, CI reports). Jaiph keeps those separate: the **live** channel is `__JAIPH_EVENT__` JSON lines on the child process’s **stderr**; the **durable** side is a tree of files under the project workspace so you can inspect, diff, and archive a run after it finishes.
+Long-running orchestration tools usually split **telemetry you watch while something runs** from **evidence you keep after it stops**. The first answers “what is happening now?”; the second answers “what happened, in enough detail to debug or audit later?” Jaiph does the same.
 
-When you run a workflow, or `jaiph test` executes workflows inside test blocks, **`NodeWorkflowRuntime`** materializes that durable tree. By default it lives at `<workspace>/.jaiph/runs/`; you can point it elsewhere with `run.logs_dir` / `JAIPH_RUNS_DIR` (see [Configuration — Run keys](configuration.md#run-keys)). The layout below matches what `NodeWorkflowRuntime` creates at startup (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) for where this fits in the overall pipeline). In Docker mode, paths inside recorded events may use container prefixes (`/jaiph/run/…`); the CLI maps them to host paths when reporting failures — see [Sandboxing — Path remapping](sandboxing.md#path-remapping).
+For Jaiph, **live** observation is the `__JAIPH_EVENT__` JSON line protocol on the workflow runner’s **stderr** (what the interactive CLI and [Hooks](hooks.md) consume). **Durable** observation is a directory tree on disk: step captures, an append-only summary timeline, optional inbox copies, and a writable `artifacts/` folder for anything workflows publish explicitly.
+
+When you run a workflow, or `jaiph test` executes workflows inside test blocks, **`NodeWorkflowRuntime`** materializes that durable tree. **`jaiph run`** defaults to `<workspace>/.jaiph/runs/`; override with `run.logs_dir` or **`JAIPH_RUNS_DIR`** (see [Configuration — Run keys](configuration.md#run-keys)). The test runner uses its own ephemeral runs root under **`JAIPH_RUNS_DIR`** so normal workspace runs are not overwritten — see [Configuration — Testing with `jaiph test`](configuration.md#testing-with-jaiph-test). The layout below matches what the runtime creates in the constructor (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout)). In Docker mode, paths inside recorded events may use container prefixes (`/jaiph/run/…`); the CLI maps them to host paths when reporting failures — see [Sandboxing — Path remapping](sandboxing.md#path-remapping).
 
 ## Run directory layout
 
-The runtime uses a UTC-dated hierarchy. Each run gets its own folder: UTC date, then UTC time plus a basename derived from `JAIPH_SOURCE_FILE` when set, otherwise the entry module’s file basename.
+The runtime uses a UTC-dated hierarchy. Each run gets its own folder: UTC date, then UTC time plus a **basename** used only for naming (not a path): **`JAIPH_SOURCE_FILE`** when set in the environment (the CLI and `node-workflow-runner` set this to the entry file basename), otherwise `basename(graph.entryFile)` from the parsed graph.
 
 ```
 .jaiph/runs/
@@ -24,25 +26,25 @@ The runtime uses a UTC-dated hierarchy. Each run gets its own folder: UTC date,
       artifacts/                       # user-published files (`jaiphlang/artifacts`); `JAIPH_ARTIFACTS_DIR`
       inbox/                           # audit copies of routed channel payloads (optional)
       heartbeat                        # liveness: epoch ms, refreshed about every 10s
-      return_value.txt                 # present if `default` workflow exited 0 and returned a value
+      return_value.txt                 # `runDefault` only: status 0 and `returnValue` defined (may be "")
       run_summary.jsonl                # durable event timeline (JSON Lines)
 ```
 
-Sequence numbers in those filenames are **monotonic and unique** per run. `RuntimeEventEmitter` owns a single in-memory counter (`allocStepSeq`) that advances whenever a step needs paired capture files — managed steps (`script`, nested `workflow` / `rule`, single-line `shell`, and similar) and `prompt` steps that write transcripts all draw from the same sequence. There is **no** `.seq` file in the run directory. For the live vs durable split, see [Architecture — Contracts](architecture.md#contracts): `__JAIPH_EVENT__` on stderr is the streaming path; `run_summary.jsonl` is the durable timeline.
+Sequence numbers in those filenames are **monotonic and unique** per run. `RuntimeEventEmitter` owns a single in-memory counter (`allocStepSeq`) that advances whenever a step allocates paired capture files: **`executeManagedStep`** (nested **`workflow`** / **`rule`**, **`script`** references, inline scripts, and **`shell`** lines run via `sh -c`) plus **`prompt`** steps (which call `allocStepSeq` inside `emitPromptStepStart`). Ordinary **`log`**, **`logerr`**, **`fail`**, **`send`**, and most **`const`** bindings do **not** open new numbered `.out`/`.err` pairs — they still emit **`LOG`/`LOGERR`** or **`INBOX_ENQUEUE`** records (and related lines) into **`run_summary.jsonl`** where applicable. There is **no** `.seq` file in the run directory. For the live vs durable split, see [Architecture — Contracts](architecture.md#contracts): `__JAIPH_EVENT__` on stderr is the streaming path; `run_summary.jsonl` is the durable timeline.
 
 ## What each artifact is for
 
 - **`*.out` / `*.err`** — Paired capture files for steps that record subprocess or prompt I/O. The runtime creates both paths at **`STEP_START`**. For **managed** steps (extracted scripts, nested workflows/rules, single-line `shell`, and similar), stdout/stderr are **streamed** into the files during execution, then **rewritten** with the final aggregated strings at step end — so a long-running step’s `.out` can be tailed while it runs (see [CLI — Run artifacts and live output](cli.md#run-artifacts-and-live-output)). **Prompt** steps stream the model transcript into `.out`; `.err` is only overwritten when stderr from the backend is non-empty (otherwise the placeholder file stays zero-length). **Errors and CLI progress** still use the live `__JAIPH_EVENT__` stream on stderr; these files are the on-disk record.
 
-- **`run_summary.jsonl`** — Append-only JSON Lines timeline: workflow boundaries, step start/end, `LOG` / `LOGERR`, prompt lifecycle, inbox events, and the same step payload fields as the live stream. It is **truncated to empty at runtime startup**, then each event appends a line via `appendRunSummaryLine` as execution proceeds. **Note:** the in-process test runner can set `suppressLiveEvents`, which **stops** `__JAIPH_EVENT__` lines from going to stderr while **`run_summary.jsonl` keeps updating** (see [Architecture — Core components](architecture.md#core-components), `RuntimeEventEmitter`).
+- **`run_summary.jsonl`** — Append-only JSON Lines timeline: workflow boundaries, step start/end, `LOG` / `LOGERR`, prompt lifecycle, inbox events, and the same step payload fields as the live stream. It is **truncated to empty at runtime startup**, then each event appends a line via `appendRunSummaryLine` as execution proceeds. The in-process test runner can set `suppressLiveEvents`, which **stops** `__JAIPH_EVENT__` lines from going to stderr while **`run_summary.jsonl` keeps updating** (see [Architecture — Core components](architecture.md#core-components), `RuntimeEventEmitter`).
 
-- **`inbox/`** — When channels are used, **routed** `send` steps may persist a copy of the payload here (`NNN-<channel>.txt`) for audit. Files are created **only if** the send resolves to a context that has dispatch routes for that channel (no file for unrouted sends — see `NodeWorkflowRuntime` send handling and [Inbox & Dispatch](inbox.md)). Delivery stays in-memory; this directory is not a mailbox API.
+- **`inbox/`** — When channels are used, a **`send`** may persist a copy of the payload here (`NNN-<channel>.txt`) for audit. The runtime walks ancestor workflow contexts and writes a file **only when it finds a matching route for that channel** on the stack (same condition as “routed” dispatch — see [Inbox & Dispatch](inbox.md)); unrouted sends enqueue without creating `inbox/` files. Delivery stays in-memory; this directory is not a mailbox API.
 
 - **`heartbeat`** — Best-effort file containing a wall-clock millisecond timestamp, rewritten on a timer (~10s). Liveness for external watchdogs; not required for normal CLI use.
 
-- **`return_value.txt`** — Written after a successful **`default`** workflow when `executeWorkflow` reports a defined `returnValue` (including `""`, which produces a zero-length file — distinct from “no file / no return”). **`runNamedWorkflow`** (used by `test_run_workflow` and similar) does not write this file by that path.
+- **`return_value.txt`** — Written only from **`runDefault`** (the normal **`jaiph run`** entry path) when the top-level workflow finishes with **exit status 0** and the aggregated result has **`returnValue !== undefined`** (empty string is allowed and produces a zero-byte file; **`undefined`** means the file is omitted — typically “fell off the end” of the workflow without a **`return`**). **`runNamedWorkflow`** (`test_run_workflow`, nested named runs, etc.) returns the value to the caller but does **not** write this file.
 
-- **`artifacts/`** — Created before steps run. The runtime sets **`JAIPH_ARTIFACTS_DIR`**, **`JAIPH_RUN_DIR`**, **`JAIPH_RUN_SUMMARY_FILE`**, and **`JAIPH_RUN_ID`** (a new UUID when `JAIPH_RUN_ID` was not already set in the environment). User workflows usually publish into this directory through **`jaiphlang/artifacts`** (`artifacts.save`). In Docker mode it sits under the **host-writable** run mount (`/jaiph/run/...` inside the container), not the read-only workspace overlay. See [Libraries — `jaiphlang/artifacts`](libraries.md#jaiphlangartifacts--publishing-files-out-of-the-sandbox) and [Sandboxing](sandboxing.md).
+- **`artifacts/`** — Created in the constructor together with the empty **`run_summary.jsonl`** (truncated file). The runtime sets **`JAIPH_ARTIFACTS_DIR`**, **`JAIPH_RUN_DIR`**, **`JAIPH_RUN_SUMMARY_FILE`**, and **`JAIPH_RUN_ID`**: if **`JAIPH_RUN_ID`** is already set in the incoming environment it is preserved; otherwise a new UUID is generated. User workflows usually publish into **`artifacts/`** through **`jaiphlang/artifacts`** (`artifacts.save`). In Docker mode it sits under the **host-writable** run mount (`/jaiph/run/...` inside the container), not the read-only workspace overlay. See [Libraries — `jaiphlang/artifacts`](libraries.md#jaiphlangartifacts--publishing-files-out-of-the-sandbox) and [Sandboxing](sandboxing.md).
 
 ## Keeping runs out of git
 
diff --git a/docs/cli.md b/docs/cli.md
index 7b633af9..b956872f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,15 +9,19 @@ redirect_from:
 
 Jaiph is a workflow system: authors write `.jh` modules, and a **TypeScript CLI** prepares scripts, launches a **Node workflow runtime**, and surfaces progress while the **JavaScript kernel** executes the AST in process (no separate workflow shell). The CLI is what you install as the `jaiph` binary — it is the boundary between your terminal or CI and the interpreter.
 
+At a high level, the CLI does four things: **compile** script bodies from your module graph (`buildScripts`), **spawn** the detached workflow runner (`node-workflow-runner`) for `jaiph run`, **observe** `__JAIPH_EVENT__` lines on stderr to render progress and drive hooks (unless `--raw`), and **leave** durable artifacts under `.jaiph/runs`. `jaiph test` reuses the same compilation step and runtime kernel but executes test blocks in-process with mocks — see [Architecture](architecture.md) for the full pipeline.
+
 This page lists **commands**, important **flags**, and **environment variables**. It focuses on how the tool behaves, not on the language itself. For semantics and the overall language model, see [Language](language.md). For concrete syntax rules (imports, orchestration strings, managed calls, …), see [Grammar](grammar.md). For repository layout, pipelines, and contracts (`__JAIPH_EVENT__`, artifacts, Docker vs local), see [Architecture](architecture.md).
 
 **Commands:** `run`, `test`, `compile`, `format`, `init`, `install`, `use`.
 
 **Global options:** `-h` / `--help` and `-v` / `--version` are recognized only as the **first token after `jaiph`** (e.g. `jaiph --help`). They are not treated as global flags after a subcommand or a file path (`jaiph run --help` is **not** usage — use `jaiph --help`, or **`jaiph compile -h`** / **`jaiph compile --help`** for compile-specific usage — the `compile` command parses `-h` / `--help` after the subcommand). Running **`jaiph`** with no arguments prints the same overview and exits **0**.
 
+Any other unknown first token prints `Unknown command: …`, repeats the overview, and exits **1**.
+
 ## File shorthand
 
-If the **first argument after `jaiph`** is an **existing path** (resolved relative to the current working directory), Jaiph routes it automatically based on the extension. Files ending in **`*.test.jh`** are run as tests (same as `jaiph test <file>`). Other paths ending in **`.jh`** are run as workflows (same as `jaiph run <file>`). The `*.test.jh` check happens first, so test modules are never mistaken for workflows.
+If the **first argument after `jaiph`** is an **existing path** (resolved relative to the current working directory), Jaiph routes it automatically based on the extension. Files ending in **`*.test.jh`** are run as tests (same as `jaiph test <file>`). Other paths ending in **`.jh`** are run as workflows (same as `jaiph run <file>`). The `*.test.jh` check happens first, so test modules are never mistaken for workflows. Paths that do not exist fall through to normal command parsing (e.g. you cannot rely on shorthand for a not-yet-created file).
 
 Additional positional tokens after a **workflow** shorthand are forwarded to **`workflow default`**, matching `jaiph run`. Tokens after a **test** shorthand are accepted but **ignored** (same as `jaiph test <file>` with extra arguments).
 
@@ -47,7 +51,7 @@ Any path ending in `.jh` is accepted (including `*.test.jh`, since the extension
 **Flags:**
 
 - **`--target <dir>`** — keep emitted script files and run metadata under `<dir>` instead of a temp directory (useful for debugging).
-- **`--raw`** — skip the banner, live progress tree, hooks, and CLI failure footer. The workflow runner child uses **inherited stdio** so `__JAIPH_EVENT__` JSON lines go to **stderr** unchanged. The **host** CLI relies on this for Docker-backed runs (the container invokes `jaiph run --raw` so the host parses events from Docker’s stderr); you can also use it when embedding Jaiph in another tool. There is no PASS/FAIL line, **`return_value.txt` is not printed to stdout**, and the process exit code alone reflects success or failure. See [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
+- **`--raw`** — skip the banner, live progress tree, hooks, and CLI failure footer. The workflow runner child uses **inherited stdio** so `__JAIPH_EVENT__` JSON lines go to **stderr** unchanged. When **Docker sandboxing** is used, the **host** runs interactive `jaiph run` and the **container** runs `jaiph run --raw …` so the host can parse events from the container’s stderr ([Architecture](architecture.md), [Sandboxing](sandboxing.md)). **Important:** if you invoke `jaiph run --raw` yourself on the host, the CLI takes a separate code path that **never starts Docker** — workflow execution runs locally in that process even when `JAIPH_DOCKER_ENABLED=true`. Use `--raw` for embedding or piping; use interactive `jaiph run` (no `--raw`) when you want the CLI to apply sandbox env rules. There is no PASS/FAIL line, **`return_value.txt` is not printed to stdout**, and the process exit code alone reflects success or failure. See [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
 - **`--`** — end of Jaiph flags; remaining args are passed to `workflow default` (e.g. `jaiph run file.jh -- --verbose`).
 
 **Examples:**
@@ -173,7 +177,7 @@ In Docker mode, artifact paths recorded by the container use container-internal
 
 ### Run artifacts and live output
 
-Each run directory is `<JAIPH_RUNS_DIR>/<YYYY-MM-DD>/<HH-MM-SS>-<source>/`, where date and time are UTC and `<source>` is `JAIPH_SOURCE_FILE` if set, otherwise the entry file basename. Each step gets sequenced capture files: `000001-module__rule.out` for stdout, and `000002-module__workflow.err` for stderr **when that stream is non-empty** (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout)).
+Each run directory is `<JAIPH_RUNS_DIR>/<YYYY-MM-DD>/<HH-MM-SS>-<source>/`, where date and time are UTC and `<source>` is `JAIPH_SOURCE_FILE` if set, otherwise the entry file basename. Steps that allocate captures open **paired** `NNNNNN-<safe_name>.out` and `.err` files at **`STEP_START`** (see [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) and [Runtime artifacts — What each artifact is for](artifacts.md#what-each-artifact-is-for)).
 
 Step **stdout** artifacts are written **incrementally during execution**, so you can tail a running step's output in real time:
 
@@ -185,7 +189,7 @@ jaiph run ./flows/deploy.jh
 tail -f .jaiph/runs/2026-03-22/14-30-00-deploy.jh/000003-deploy__run_migrations.out
 ```
 
-If a stream stays empty for a step, the runtime may omit that artifact file. Any empty capture files are cleaned up at step end.
+Which steps get numbered `.out`/`.err` pairs, how prompts differ from managed scripts, and when empty files are removed are spelled out in [Runtime artifacts](artifacts.md); the durable timeline either way is **`run_summary.jsonl`**.
 
 ### Run summary (`run_summary.jsonl`) {#run-summary-jsonl}
 
@@ -251,9 +255,9 @@ The test runner uses the same Node workflow runtime as `jaiph run`. For each tes
 
 **Usage:**
 
-- `jaiph test` — discover and run all `*.test.jh` under the workspace root. The workspace root is found by walking up from the current directory until a directory with `.jaiph` or `.git` is found; if neither exists, the current directory is used.
-- `jaiph test <dir>` — run all `*.test.jh` files recursively under the given directory.
-- `jaiph test <file.test.jh>` — run a single test file.
+- `jaiph test` — discover and run all `*.test.jh` under the workspace root. The workspace root is found by walking up from the **current working directory** until a directory with `.jaiph` or `.git` is found; if neither exists, the current directory is used (same `detectWorkspaceRoot` algorithm as `jaiph run` / `jaiph install`).
+- `jaiph test <dir>` — run all `*.test.jh` files recursively under the given directory. Workspace root for script compilation is detected by walking up from **that directory** (resolved), not necessarily from your shell cwd.
+- `jaiph test <file.test.jh>` — run a single test file; workspace root is detected from the test file’s directory.
 
 With no arguments, or with a directory that contains no test files, the command exits with status **1** and prints an error.
 
@@ -312,7 +316,7 @@ One or more file paths are required (each path must end with `.jh`, e.g. `flow.j
 # Rewrite files in place
 jaiph format flow.jh utils.jh
 
-# Check formatting in CI (non-zero exit on drift)
+# Check formatting in CI (non-zero exit on drift); ensure globs expand to real paths
 jaiph format --check src/**/*.jh
 
 # Use 4-space indentation
@@ -331,7 +335,7 @@ Creates:
 
 - `.jaiph/.gitignore` — lists `runs` and `tmp`. If the file already exists and does not match this exact list, `jaiph init` exits with a non-zero status.
 - `.jaiph/bootstrap.jh` — canonical bootstrap workflow; made executable. The template uses a triple-quoted multiline prompt body (`prompt """ ... """`) so the generated file parses and compiles as valid Jaiph. It asks the agent to scaffold workflows under `.jaiph/` and ends by logging a summary (`WHAT CHANGED` + `WHY`). Docker sandboxing uses the default `ghcr.io/jaiphlang/jaiph-runtime` image unless you set `runtime.docker_image` or `JAIPH_DOCKER_IMAGE`.
-- `.jaiph/SKILL.md` — copied from the skill file bundled with your Jaiph installation. If **`JAIPH_SKILL_PATH`** is set, that path is used **only when it exists on disk**; otherwise the CLI searches known install-relative locations and `docs/jaiph-skill.md` from the current directory. If no file is found, `SKILL.md` is not written and a note is printed.
+- `.jaiph/SKILL.md` — copied when the CLI can resolve a skill markdown file: if **`JAIPH_SKILL_PATH`** is set **and** that path exists, it wins; otherwise the CLI tries install-relative paths (`jaiph-skill.md` beside the packaged tree, then `docs/jaiph-skill.md` beside the package), then **`docs/jaiph-skill.md` under the current working directory**. If none of these exist, `SKILL.md` is not written and a note is printed.
 
 ## `jaiph install`
 
@@ -467,4 +471,4 @@ For overlay vs copy workspace mode, mounts, and stderr wiring, see [Sandboxing](
 
 ### `jaiph init`
 
-- `JAIPH_SKILL_PATH` — absolute or relative path to the skill markdown copied to `.jaiph/SKILL.md` when running `jaiph init`. The file **must exist**; otherwise this variable is ignored and the default search runs.
+- `JAIPH_SKILL_PATH` — path to the skill markdown copied to `.jaiph/SKILL.md` when running `jaiph init`. The file **must exist** at this path; otherwise the variable is ignored and the CLI falls back to the same install-relative and `docs/jaiph-skill.md` (cwd) search described under [`jaiph init`](#jaiph-init).
diff --git a/docs/configuration.md b/docs/configuration.md
index 88d04b51..e433b8f7 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -11,7 +11,7 @@ When you need the same workflow sources to behave differently on different machi
 
 All execution is interpreted by the Node workflow runtime (`NodeWorkflowRuntime`): the AST, managed scripts, prompts, channels, inbox, and `.jaiph/runs` artifacts (see [Architecture](architecture.md)). Configuration only adjusts that stack; it does not change the workflow language or the compile graph.
 
-`jaiph compile` parses each module in the import closure (same grammar as `buildScripts()`), so **unknown `config` keys and wrong value types** produce the same parse errors as a normal build. `jaiph compile` then runs **`validateReferences` only** — it does not emit scripts or spawn the runner (see [Architecture](architecture.md#summary)). Runtime graph loading is parse-only; **compile-time** reference validation runs in the transpile path, not in `buildRuntimeGraph()`.
+`jaiph compile` parses each module in the import closure (same grammar as `emitScriptsForModule`), so **unknown `config` keys and wrong value types** surface as the same parse diagnostics as before `jaiph run`. With a **directory** argument it treats every non-test **`*.jh`** file in that directory as its own entrypoint (see `walkjhFiles` — `*.test.jh` is skipped unless you pass a test file explicitly) and validates each entry’s transitive imports. **`validateReferences` only** — no `scripts/` emission, no `buildRuntimeGraph()`, no runner spawn (see [Architecture](architecture.md#summary)). Runtime graph loading is parse-only; **compile-time** reference validation runs in the transpile path, not in `buildRuntimeGraph()`.
 
 **Source of truth:** When this document and the implementation disagree, treat the source code as authoritative.
 
@@ -29,7 +29,7 @@ For **agent and run keys**, the full precedence chain is:
 
 `run.recover_limit` is an exception: only **module-level** values affect `run … recover` (see [Run keys](#run-keys)).
 
-For **`runtime.*` (image, network, timeout)**, the CLI merges at **`jaiph run` launch** — not inside `NodeWorkflowRuntime` — in the order **`JAIPH_DOCKER_*` environment > in-file `runtime.*` > defaults** (and separately: Docker on/off is env-only, see above and [Precedence in detail](#precedence-in-detail)). `runtime.*` cannot appear in workflow-level `config` blocks.
+For **`runtime.*` (image, network, timeout)**, the host CLI merges them when it **may spawn Docker** (`resolveDockerConfig` in `src/runtime/docker.ts`) — not inside `NodeWorkflowRuntime`. Precedence is **`JAIPH_DOCKER_*` environment > module-level `runtime.*` > defaults** (Docker on/off remains env-only, see above and [Precedence in detail](#precedence-in-detail)). A **host** invocation of **`jaiph run --raw`** skips that driver entirely and always runs the workflow runner **locally** (no container); **`runtime.*` is unused on that path**. Sandboxed workflows still run `jaiph run --raw …` **inside** the container. `runtime.*` cannot appear in workflow-level `config` blocks.
 
 ## In-file config blocks
 
@@ -166,10 +166,12 @@ workflow default() {
 
 ### Runtime keys (Docker sandbox — beta)
 
-These configure Docker sandboxing. Unlike agent and run keys, runtime keys are resolved by the `jaiph run` CLI at launch — not by the workflow runtime. They can only appear in **module-level** config blocks (not workflow-level).
+These configure Docker sandboxing. Unlike agent and run keys, they are read when the CLI considers a **Docker launch** for interactive **`jaiph run`** (`src/cli/commands/run.ts` → `spawnExec`). They never affect **`NodeWorkflowRuntime`** directly. They can only appear in **module-level** config blocks (not workflow-level).
 
 > Docker sandboxing is in **beta**. See [Sandboxing](sandboxing.md) for mounts, workspace layout, env forwarding, path remapping, and container behavior.
 
+> **Host `--raw`:** If you run **`jaiph run --raw`** yourself on the host, the CLI does not enter the Docker branch; image/network/timeout merge is irrelevant for that invocation. Embedding and container flows use **`--raw` inside** the sandbox where the CLI has already picked the image — see [Architecture](architecture.md#sequence-diagram-regular-flow-jh).
+
 | Key | Type | Default | Env variable | Description |
 |-----|------|---------|--------------|-------------|
 | `runtime.docker_image` | string | `ghcr.io/jaiphlang/jaiph-runtime:<version>` | `JAIPH_DOCKER_IMAGE` | Image name. Must already contain `jaiph`. When unset, uses the official GHCR image tag matching the installed jaiph version. For a custom image, build and push (or tag locally), then set this key or `JAIPH_DOCKER_IMAGE`. |
@@ -187,7 +189,7 @@ For **agent and run keys**, resolution order (highest wins):
 3. **Module-level `config`** — applies to workflows that don't define their own block.
 4. **Built-in defaults.**
 
-For **Docker enablement**, the `jaiph run` driver uses **`JAIPH_DOCKER_ENABLED` env > unsafe default rule** (env only; `runtime.docker_enabled` is no longer supported). The default rule enables Docker unless `JAIPH_UNSAFE=true` is set; `CI=true` no longer disables Docker (see [Sandboxing — Enabling Docker](sandboxing.md#enabling-docker)). For other `runtime.*` keys (image, network, timeout), the merge is **`JAIPH_DOCKER_*` env > module-level `runtime.*` > defaults**. Workflow-level config cannot set runtime keys.
+For **Docker enablement** on **interactive** **`jaiph run`** (no `--raw` on the host), the CLI uses **`JAIPH_DOCKER_ENABLED` env > unsafe default rule** (env only; `runtime.docker_enabled` is no longer supported). The default rule enables Docker unless `JAIPH_UNSAFE=true` is set; `CI=true` no longer disables Docker (see [Sandboxing — Enabling Docker](sandboxing.md#enabling-docker)). **Host** **`jaiph run --raw`** never consults this branch. For other `runtime.*` keys (image, network, timeout), the merge is **`JAIPH_DOCKER_*` env > module-level `runtime.*` > defaults** whenever Docker launch is considered. Workflow-level config cannot set runtime keys.
 
 ### Locked variables
 
@@ -227,7 +229,9 @@ Backend-specific flags come from `agent.cursor_flags` / `agent.claude_flags` (or
 
 ### Custom agent commands
 
-When `agent.command` points to an executable other than `cursor-agent`, Jaiph treats it as a **custom agent command**. This lets you use any shell script, Python wrapper, or CLI tool as a prompt backend — no need to implement the `stream-json` protocol.
+Only the **cursor** backend consults **`agent.command`**. For **`claude`** and **`codex`**, Jaiph always invokes the Claude CLI or the Codex HTTP path (`prompt.ts`), regardless of `agent.command`.
+
+When **`agent.backend` is `cursor`** (the default) and `agent.command`’s basename is anything other than `cursor-agent`, Jaiph treats it as a **custom agent command**. That lets you use a shell script, Python wrapper, or other CLI as a prompt backend — no need to implement the `stream-json` protocol.
 
 **How it works:**
 
@@ -292,15 +296,15 @@ When a `prompt` step runs, Jaiph resolves the effective model using this order:
 
 `agent.default_model` applies to **cursor**, **claude**, and **codex**. For the **Claude** backend, when `agent.default_model` is set and `agent.claude_flags` does not already contain `--model`, Jaiph passes `--model <value>` to the Claude CLI automatically. If both are set, the value in `agent.claude_flags` takes precedence (it is appended last).
 
-**Diagnostics.** Every prompt step records the resolved model in `PROMPT_START` and `PROMPT_END` events in `run_summary.jsonl`:
+**Diagnostics.** Every prompt step records model metadata in **`PROMPT_START`** and **`PROMPT_END`** in **`run_summary.jsonl`** (`model`, `model_reason`):
 
 ```jsonl
 {"type":"PROMPT_START","backend":"cursor","model":"gpt-4","model_reason":"explicit",...}
 ```
 
-The `model_reason` field is one of: `explicit` (from `agent.default_model`), `flags` (extracted from backend flags), or `backend-default` (no model configured — the backend picks its own). Inspect these events directly in the run summary file.
+`model_reason` is one of: **`explicit`** (non-empty **`agent.default_model` / `JAIPH_AGENT_MODEL`**), **`flags`** (`--model` taken from **`agent.cursor_flags`** or **`agent.claude_flags`**), or **`backend-default`** (no resolved model string — Cursor/Claude binaries choose their own; **codex** also reports this when no model is configured, **even though** the HTTP client defaults to **`gpt-4o`**, so the **`model`** field may be omitted there). Inspect these events directly in the summary file.
 
-**No-model troubleshooting.** If the backend rejects the auto-selected default, set `agent.default_model` explicitly or pass `--model <name>` in the backend-specific flags.
+**No-model troubleshooting.** If the backend rejects the auto-selected default, set **`agent.default_model`** (all backends). For **cursor** and **claude** you can also pass **`--model <name>`** in **`agent.cursor_flags`** / **`agent.claude_flags`**; **codex** has no flag channel — use **`agent.default_model`** or env **`JAIPH_AGENT_MODEL`** only.
 
 ## Testing with `jaiph test`
 
@@ -330,6 +334,13 @@ Quick reference for all in-file keys and their environment variable equivalents:
 | `module.version` | _(no env override)_ |
 | `module.description` | _(no env override)_ |
 
+There is **no in-file key** for the Codex HTTP endpoint or API key. Use environment only:
+
+| Purpose | Environment variable |
+|---------|----------------------|
+| OpenAI-compatible API key (required for **codex**) | `OPENAI_API_KEY` |
+| OpenAI-compatible chat-completions URL override | `JAIPH_CODEX_API_URL` |
+
 ## Inspecting effective config at runtime
 
 Inside workflows, rules, and scripts, agent and run settings are visible as `JAIPH_*` environment variables. In orchestration strings, `${IDENTIFIER}` resolves from workflow variables first, then from the process environment.
diff --git a/docs/contributing.md b/docs/contributing.md
index 355b511a..fbbd1422 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -7,9 +7,11 @@ redirect_from:
 
 # Contributing to Jaiph
 
-Open source only works when expectations match reality: where to land changes, how to reproduce CI locally, and how to prove behavior with the right test layer. **This page is that contract** — branching, install-from-clone, engineering conventions, the test stack (TypeScript, txtar, golden AST, bash E2E), and what GitHub Actions run on each push.
+Contributor docs answer a narrow question: **where changes belong**, **how to run the same checks CI runs**, and **which test layer** should encode a behavior change.
 
-**Related documentation:** [Getting Started](getting-started.md) (map), [Language](language.md) (patterns), [Setup](setup.md), and [Grammar](grammar.md). **Implementation boundaries** (pipelines, `buildRuntimeGraph` vs `validateReferences`, runtime contracts, artifact layout) are spelled out in [Architecture](architecture.md); if this page disagrees with that file, **Architecture wins**.
+At a high level, Jaiph is built as described in [Architecture](architecture.md) — transpile path (`emitScriptsForModule`, `buildScripts`), parse-only **`buildRuntimeGraph()`**, **`jaiph compile`** (validate-only), **`NodeWorkflowRuntime`**, artifact layout, and Docker helper contracts. Treat that page as authoritative for pipelines and boundaries; if anything here diverges from it or from the implementation, prefer **architecture + source**.
+
+For workflow syntax, library usage, tooling setup, and grammar details, see [Language](language.md), [Setup](setup.md), [Grammar](grammar.md), and the overview in [Getting Started](getting-started.md).
 
 ## Branching and pull requests
 
@@ -41,7 +43,7 @@ The script installs from local source (including uncommitted changes) and places
 
 For day-to-day work on the compiler and CLI you usually stay inside the clone: install dev dependencies once, then build and run tests from npm scripts.
 
-**Prerequisites:** Node.js and npm (the installer also expects `git` and `bash`). End-to-end tests are written in bash and are run by `e2e/test_all.sh`.
+**Prerequisites:** Node.js **20.x** and npm (same **`setup-node`** version as `.github/workflows/ci.yml`). The installers also expect `git` and `bash`. End-to-end tests are written in bash and are run by `e2e/test_all.sh`.
 
 **Typical commands** (from the repo root):
 
@@ -49,14 +51,14 @@ For day-to-day work on the compiler and CLI you usually stay inside the clone: i
 |---------|----------------|
 | `npm install` | Installs TypeScript and types (dev dependencies). |
 | `npm run build` | Runs `tsc`, then copies **`src/runtime`** → **`dist/src/runtime`** (kernel JS for the compiled CLI) and **`runtime/overlay-run.sh`** → **`dist/src/runtime/overlay-run.sh`** (Docker overlay entrypoint). |
-| `npm run build:standalone` | `npm run build`, then copies **`dist/src/runtime`** → **`dist/runtime`** and runs **`bun build --compile`** on `src/cli.ts` → **`dist/jaiph`**. Requires [Bun](https://bun.sh). Ship the **`dist/`** tree (binary plus the runtime directory) for a self-contained layout. |
+| `npm run build:standalone` | `npm run build`, then copies **`dist/src/runtime`** → **`dist/runtime`** and runs **`bun build --compile ./src/cli.ts --outfile ./dist/jaiph`**. Requires [Bun](https://bun.sh). Ship **`dist/jaiph`** beside **`dist/runtime`** ([Architecture — Distribution](architecture.md#distribution-node-vs-bun-standalone)). |
 | `npm test` | **`npm run clean`**, then **`npm run build`**, then the Node.js test runner with **`JAIPH_UNSAFE=true`**, **`NODE_OPTIONS`** including **`--enable-source-maps`** and a large heap limit, on every file under `dist/integration/` matching `*.test.js`, every file under `dist/src/` matching `*.test.js` or `*.acceptance.test.js` (via `find`), `dist/test-infra/compiler-test-runner.js` (txtar compiler tests), and `dist/test-infra/golden-ast-runner.js` (golden AST tests). |
 | `npm run test:compiler` | **`npm run build`**, then **`node --test`** on `dist/test-infra/compiler-test-runner.js` — runs txtar-based compiler test fixtures from `test-fixtures/compiler-txtar/`. |
 | `npm run test:golden-ast` | **`npm run build`**, then **`node --test`** on `dist/test-infra/golden-ast-runner.js` — runs golden AST tests from `test-fixtures/golden-ast/`. Use `UPDATE_GOLDEN=1 npm run test:golden-ast` to regenerate goldens after intentional parser changes. |
-| `npm run test:acceptance:compiler` | **`npm run build`**, then **`node --test`** on only `dist/src/**/*.acceptance.test.js` — compiler acceptance tests without the full unit suite or E2E. |
+| `npm run test:acceptance:compiler` | **`npm run build`**, then **`node --test`** with only `*.acceptance.test.js` files under **`dist/src/`** (same `find … -name '*.acceptance.test.js'` fragment as **`package.json`**) — compiler acceptance tests without the full unit suite or E2E. |
 | `npm run test:acceptance:runtime` | **`bash ./e2e/test_all.sh`** only — same E2E driver as below **without** an implicit rebuild; ensure `dist/` is up to date before running. |
 | `npm run test:acceptance` | **`npm run test:acceptance:compiler`** then **`npm run test:acceptance:runtime`**. |
-| `npm run test:e2e` | **`npm run build`**, then **`bash ./e2e/test_all.sh`**. Prefer this when you want a fresh `dist/` before E2E. By default this exercises the **Docker** sandbox when `JAIPH_UNSAFE` is unset. For a faster host-only run (no container), use **`JAIPH_UNSAFE=true npm run test:e2e`**. |
+| `npm run test:e2e` | **`npm run build`**, then **`bash ./e2e/test_all.sh`**. Prefer this when you want a fresh `dist/` before E2E. **`e2e::prepare_shared_context`** in `e2e/lib/common.sh` exports **`JAIPH_DOCKER_ENABLED=false`** after clearing most **`JAIPH_*`** variables, so typical tests run on the **host**; Docker coverage lives in scripts that set **`JAIPH_DOCKER_ENABLED=true`** — see [E2E testing](#e2e-testing) and **`resolveDockerConfig`** in `src/runtime/docker.ts` / [Architecture — Core components](architecture.md#core-components). |
 | `npm run test:samples` | **`npx playwright test`** — Playwright suite for the docs landing page (`e2e/playwright/`). Uses `http://127.0.0.1:4000` (see `playwright.config.ts`); starts Jekyll via `webServer` or reuses one already on that port. Requires Playwright (`npx playwright install chromium` once). |
 | `npm run test:ci` | `npm test` followed by `npm run test:e2e` — useful before pushing when you want the full local picture. |
 
@@ -108,11 +110,12 @@ Jaiph uses several test layers. Each layer catches a different class of bug. Use
 ### Key principles
 
 1. **Compile-time validation vs graph loading.** `buildScripts` / `emitScriptsForModule` run **`validateReferences`** before any script files are written. **`buildRuntimeGraph()`** only parses modules and follows imports — it does **not** re-run that validation. Lock compile errors in the compiler/validator tests; the runtime graph is the wrong layer for that (see [Architecture — Core components](architecture.md#core-components)). **`jaiph compile`** runs **`validateReferences` only** (no **`buildScripts`**, no runner); cover it with txtar/acceptance/E2E such as `e2e/tests/109_compile_command.sh`, not by expecting the full transpile path — see [Architecture — System overview](architecture.md#system-overview).
-2. **Tests are behavior contracts.** E2E tests and acceptance tests define what the product does. Default approach: change production code to satisfy tests, not the other way around.
-3. **Modify existing tests only with a strong reason:** intentional product behavior change, incorrect test expectation, or removal of an obsolete feature. Any such change should be minimal and paired with a clear rationale.
-4. **Golden tests are the compiler's safety net.** After transpiler changes, run `npm test`. Failures in `src/transpile/compiler-golden.test.ts` usually mean updating an explicit expected string or fixture in that file — there is no separate dump script; align expectations with intentional emitter changes and re-run `npm test`. **Golden AST tests** (`test-fixtures/golden-ast/`) complement this by locking in the parse tree shape — if those fail, regenerate with `UPDATE_GOLDEN=1 npm run test:golden-ast` and review the diff.
-5. **E2E tests assert two things independently:** what the user sees (CLI tree output via `e2e::expect_stdout`) and what the runtime persists (artifact files via `e2e::expect_out`, `e2e::expect_file`). A bug could break one without the other.
-6. **Prefer the narrowest test layer.** A pure function bug should be caught by a unit test, not an E2E test. E2E tests are expensive to run and hard to debug — reserve them for integration-level behavior.
+2. **`jaiph test` vs live events.** **`jaiph test`** reuses **`NodeWorkflowRuntime`** with **`suppressLiveEvents: true`** so **`__JAIPH_EVENT__`** lines are **not** written to stderr alongside **`node --test`** output while **`run_summary.jsonl`** and other artifact paths stay consistent where the harness writes them ([Architecture — Test runner integration](architecture.md#test-runner-integration-testjh-in-the-kernel)).
+3. **Tests are behavior contracts.** E2E tests and acceptance tests define what the product does. Default approach: change production code to satisfy tests, not the other way around.
+4. **Modify existing tests only with a strong reason:** intentional product behavior change, incorrect test expectation, or removal of an obsolete feature. Any such change should be minimal and paired with a clear rationale.
+5. **Golden tests are the compiler's safety net.** After transpiler changes, run `npm test`. Failures in `src/transpile/compiler-golden.test.ts` usually mean updating an explicit expected string or fixture in that file — there is no separate dump script; align expectations with intentional emitter changes and re-run `npm test`. **Golden AST tests** (`test-fixtures/golden-ast/`) complement this by locking in the parse tree shape — if those fail, regenerate with `UPDATE_GOLDEN=1 npm run test:golden-ast` and review the diff.
+6. **E2E tests assert two things independently:** what the user sees (CLI tree output via `e2e::expect_stdout`) and what the runtime persists (artifact files via `e2e::expect_out`, `e2e::expect_file`). A bug could break one without the other.
+7. **Prefer the narrowest test layer.** A pure function bug should be caught by a unit test, not an E2E test. E2E tests are expensive to run and hard to debug — reserve them for integration-level behavior.
 
 ### TypeScript test layout
 
@@ -169,7 +172,7 @@ The project uses GitHub Actions (`.github/workflows/ci.yml`). The workflow defin
 |-----|--------|---------|
 | **ShellCheck** | `ubuntu-latest` | Runs `shellcheck` on `runtime/overlay-run.sh` to lint the standalone shell script shipped in the npm package. |
 | **Compiler and unit tests** | `ubuntu-latest` | `npm test` (TypeScript unit + acceptance + golden tests), plus a `curl` check that the public install URL responds and a git-tag verification on `main`. |
-| **E2E** | Matrix: **`ubuntu-latest` twice** + **`macos-latest`** | Job id `e2e`; in the Actions UI each leg appears as **`E2E (<os>, <label>)`**. Runs `npm run test:e2e`. In **CI**, the **`docker`** leg builds `jaiph-ci-runtime:local` from `runtime/Dockerfile` and sets **`JAIPH_DOCKER_IMAGE`** so tests do not pull the public GHCR image during the run. **`docker` leg:** `JAIPH_UNSAFE` unset (container sandbox). **`host` legs (Ubuntu + macOS):** `JAIPH_UNSAFE=true` (no Docker; macOS does not run a docker leg). On a **developer machine**, with `JAIPH_UNSAFE` unset, the CLI still resolves the default image (typically `ghcr.io/jaiphlang/jaiph-runtime`) for Docker-backed runs — see `src/runtime/docker.ts` and [Architecture](architecture.md). |
+| **E2E** | Matrix: **`ubuntu-latest` twice** + **`macos-latest`** | Job id `e2e`; in the Actions UI each leg appears as **`E2E (<os>, <label>)`**. Runs `npm run test:e2e`. The **`docker`** Ubuntu leg builds **`jaiph-ci-runtime:local`** from **`runtime/Dockerfile`** and exports **`JAIPH_DOCKER_IMAGE=jaiph-ci-runtime:local`** so scripts that set **`JAIPH_DOCKER_ENABLED=true`** do not pull **`ghcr.io/…`** during the job. **`JAIPH_UNSAFE`** is unset on that leg and set to **`true`** on Ubuntu **host** plus **macOS** — unlike manual **`jaiph run`** (see **`resolveDockerConfig`** / [Sandboxing](sandboxing.md)), that matrix choice does **not** mean “everything runs in Docker”: **`e2e/lib/common.sh`** sets **`JAIPH_DOCKER_ENABLED=false`** by default, so only scripts that explicitly re-enable Docker hit the sandbox. Container-only assertions on non-Linux runners use **`e2e::skip`** or availability guards. Implementation: **`src/runtime/docker.ts`**; overview: [Architecture — Core components](architecture.md#core-components). |
 | **Getting started (local)** | `ubuntu-latest` | Serves the Jekyll site from `docs/` on `127.0.0.1:4000`, smoke-checks key routes with `curl`, builds the same local runtime image as E2E for any Docker-backed sample paths, installs Playwright (Chromium), and runs `npx playwright test` for landing-page samples. The Playwright step builds Jaiph, checks sample source against `examples/*.jh`, and runs deterministic samples through the CLI. No runtime dependency on `jaiph.org` for the site content. |
 | **E2E install and CLI workflow (windows-latest + wsl)** | `windows-latest` | Provisions or selects a WSL distro, installs Node inside it, and runs `npm run test:e2e` under WSL with **`JAIPH_UNSAFE=true`**. |
 | **Publish Docker runtime image** | `ubuntu-latest` | *Conditional (see above).* Multi-arch push to GHCR. |
@@ -203,7 +206,7 @@ After the Jekyll smoke-check, the CI job also verifies that code samples shown o
 The test does two things:
 
 1. **Source parity** — extracts each sample's source code from the DOM (`[data-sample-source]` elements inside `[data-sample]` tab panels) and compares it byte-for-byte against the corresponding file in `examples/` (identified by `data-sample-file`).
-2. **Output verification** — for deterministic samples (currently `say_hello.jh` failure path and `agent_inbox.jh`), runs the workflow via `node dist/src/cli.js run` and asserts that key output lines match what the page displays (`[data-sample-output]` blocks), after normalizing ANSI codes, timestamps, and trailing whitespace.
+2. **Output verification** — for each **`[data-sample-output]`** block whose sample/output key is **not** listed in **`SKIP_OUTPUT`** (`e2e/playwright/landing-page.spec.ts`), the test parses the **`➜`** command line, runs it against the temp copy of the page source (the executable **`.jh`** from **`examples/`** named by **`data-sample-file`**, with **`say_hello.test.jh`** also copying companion **`say_hello.jh`**), and compares normalized CLI output to the block. Normalization mirrors **`e2e::normalize_output`** (ANSI, durations, `<agent-command>` / `<script-path>`, log/summary/out/err path lines collapsed to `<path>`, spacing before **`✓ PASS`**). Entries in **`SKIP_OUTPUT`** mark nondeterministic model or agent-backed tabs (e.g. **`say-hello` / success**, **`async` / run**, **`recover-loop` / run**).
 
 To run locally:
 
@@ -213,11 +216,11 @@ npm run test:samples
 
 If a Jekyll server is already running on **`http://127.0.0.1:4000`**, Playwright reuses it (`reuseExistingServer` in `playwright.config.ts`). Otherwise it starts one.
 
-Samples that require live agent backends (e.g. `async.jh`, `recover_loop.jh`) are verified for source parity only — output verification is limited to fully deterministic workflows.
+Samples whose rendered output embeds nondeterministic model or agent transcripts skip output comparison per-tab via **`SKIP_OUTPUT`** in **`e2e/playwright/landing-page.spec.ts`** (see [Landing-page sample verification](#landing-page-sample-verification-playwright)); those tabs still participate in DOM **source parity**.
 
 ## E2E testing
 
-The E2E test suite (`e2e/tests/*.sh`) exercises the full build-and-run pipeline from the outside: compile a workflow, run it, and assert on both the CLI tree output and the run artifact files (`.out`, `.err`) written to `.jaiph/runs/`.
+The E2E test suite (`e2e/tests/*.sh`) drives the toolchain from outside the TypeScript harness: **`e2e::prepare_test_env`** (via **`prepare_shared_context`** in **`e2e/lib/common.sh`**) prepends a **`jaiph` shim** to **`PATH`** (preferring **`dist/src/cli.js`** when built), sanitizes stray **`JAIPH_*`** vars, wires **`JAIPH_REPO_URL`** to the cloned tree, exports **`JAIPH_DOCKER_ENABLED=false`** by default, then each script invokes **`jaiph run`**; Docker-specific assertions set **`JAIPH_DOCKER_ENABLED=true`** and expect **`JAIPH_DOCKER_IMAGE`** (for example **`jaiph-ci-runtime:local`** on the CI **`e2e`** **docker** matrix leg). Scripts assert on both the CLI tree (**`e2e::expect_stdout`**) and **`*.out` / `.err`** / **`run_summary.jsonl`** under **`.jaiph/runs/`** — see also [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout).
 
 Some scripts are **contract** tests: they validate persisted machine-readable output (for example `e2e/tests/88_run_summary_event_contract.sh` and `run_summary.jsonl`) in addition to or instead of golden CLI trees.
 
@@ -236,7 +239,7 @@ E2E tests are the outermost **behavior contracts** for the CLI and runtime. Each
 - **Unbounded or variable-length logs** — e.g. `run_summary.jsonl` with platform-dependent event counts, or live step output where line count varies.
 - **Platform-dependent text** — e.g. OS-specific error messages, paths that differ across CI environments.
 
-**Normalization:** `e2e::normalize_output` (in `e2e/lib/common.sh`) strips ANSI codes, replaces timing values with `<time>`, normalizes some CLI-specific strings (`<agent-command>`, `<script-path>`), and **sorts** a class of async progress lines (UTF-8 subscript markers) so strict equality stays stable when parallel branches finish in different orders. This keeps full-equality heredocs usable across machines.
+**Normalization:** `e2e::normalize_output` (in `e2e/lib/common.sh`) strips ANSI codes, replaces timing values with `<time>`, normalizes **`__inline_<hash>`** script names to **`__inline_<id>`**, swaps some CLI-specific strings (`<agent-command>`, `<script-path>`), and **sorts** a class of async progress lines (UTF-8 subscript markers) so strict equality stays stable when parallel branches finish in different orders. This keeps full-equality heredocs usable across machines.
 
 **Where files land on disk** (directory tree, sequence prefixes): [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout). Runtime testing with `*.test.jh` is covered in [Testing](testing.md). The `run_summary.jsonl` event contract is exercised in `e2e/tests/88_run_summary_event_contract.sh`.
 
@@ -266,7 +269,7 @@ workflow default() {
 }
 EOF
 
-# When — build and run
+# When — run workflow (`jaiph` transpiles and executes inside the shim)
 hello_out="$(e2e::run "hello.jh")"
 
 # Then — assert on CLI tree output (include workflow return value when default() returns one)
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 7c1288be..ca2ea49a 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -9,16 +9,18 @@ redirect_from:
 
 ## Overview
 
-**Jaiph** is a workflow system for building agent-style pipelines. You write `.jh` sources (and optional `*.test.jh` test modules) that combine **prompts**, **rules**, **scripts**, and **workflows**.
+**Jaiph** is a workflow language and toolchain for combining **prompts**, **rules**, **scripts**, and **workflows** — the usual building blocks for agent-style pipelines, automation, and review flows.
 
-The **TypeScript CLI** validates modules, extracts **`script`** bodies to disk, and launches a **Node workflow runtime** that interprets the AST in process (no separate workflow shell). Local `jaiph run`, Docker-backed runs, and `jaiph test` all use that same interpreter stack; only the launch path and observability differ. For boundaries, contracts, and pipelines, see [Architecture](architecture.md).
+You work in a workspace: author `.jh` modules and optional `*.test.jh` tests; the toolchain validates them, emits each `script` body under `scripts/` (and deterministic paths for inline scripts), then runs a Node workflow runtime that interprets the workflow AST in process. Orchestration stays in that interpreter — there is no separate “workflow shell” and no workflow-wide bash emitter; script steps are normal executables spawned as subprocesses. That matches how the CLI and kernel are wired; see [Architecture](architecture.md).
 
-This page is a **map**: it does not teach syntax end-to-end; it points to install steps, language references, and runtime behavior.
+The CLI (`run`, `test`, `compile`, `format`, `init`, `install`, `use`, and [file shorthand](cli.md#file-shorthand)) is what you install. `jaiph run` always starts the entry file’s `workflow default` ([CLI — `jaiph run`](cli.md#jaiph-run)). Local `jaiph run`, Docker-backed `jaiph run`, and `jaiph test` share that AST interpreter stack; sandboxing (Docker vs host) and how `__JAIPH_EVENT__` is shown differ by command and flags ([Architecture — Runtime vs CLI responsibilities](architecture.md#runtime-vs-cli-responsibilities)).
+
+This page is a map: it does not teach syntax end-to-end. Use the sections below for install steps, language reference, contracts, and runtime behavior.
 
 ## Setup
 
 - **[Setup and installation](setup.md)** — Install the CLI, run a one-liner sample without cloning, execute workflows, format sources, and initialize a project with `.jaiph/` and workspace conventions.
-- **[Libraries](libraries.md)** — Install git-based `.jh` modules under `.jaiph/libs/`, pin versions with a lockfile, and import them with the `library-name/module` path form.
+- **[Libraries](libraries.md)** — Install git-based `.jh` modules under `.jaiph/libs/`, pin versions with a lockfile, and import them with paths like **`"lib-name/rest"`** (first segment is the folder under `.jaiph/libs/`).
 
 ## Language
 
@@ -30,16 +32,16 @@ This page is a **map**: it does not teach syntax end-to-end; it points to instal
 
 ## Runtime
 
-- **[CLI](cli.md)** — `jaiph run`, `test`, `compile`, `format`, `init`, `install`, `use`, flags, environment variables, and [file-path shorthand](cli.md#file-shorthand) for existing `.jh` / `*.test.jh` files. **`jaiph compile`** walks the import closure and runs **`validateReferences` only** — no script emission or runner (see [Architecture — Summary](architecture.md#summary)).
+- **[CLI](cli.md)** — `jaiph run`, `test`, `compile`, `format`, `init`, `install`, `use`, flags, environment variables, and [file-path shorthand](cli.md#file-shorthand) for existing `.jh` / `*.test.jh` files. **`jaiph compile`** walks the import closure and runs **`validateReferences` only** — no **`scripts/`** emission, no **`buildRuntimeGraph()`**, no runner ([Architecture — Summary](architecture.md#summary); directory discovery skips **`*.test.jh`** unless you pass a test file explicitly).
 - **[Configuration](configuration.md)** — `config { }` blocks, agent backends, logging, and runtime options (including env overrides).
-- **[Runtime artifacts](artifacts.md)** — What Jaiph writes under `.jaiph/runs/` (per-step logs, JSONL timeline, inbox files) versus live progress on stderr.
-- **[Hooks](hooks.md)** — Project or user `hooks.json` to run shell commands on workflow and step lifecycle events.
-- **[Sandboxing](sandboxing.md)** — Docker-backed isolation for `jaiph run` only (beta; **on by default**; use **`JAIPH_DOCKER_ENABLED`** or **`JAIPH_UNSAFE`** to force on/off — workflow `config` cannot toggle the container). Image, network, and timeout come from **`runtime.*`** and **`JAIPH_DOCKER_*`** env overrides (see [Configuration](configuration.md)). There is no `jaiph run --docker` flag.
+- **[Runtime artifacts](artifacts.md)** — What Jaiph writes under `.jaiph/runs/` (per-step captures, **`run_summary.jsonl`**, optional **`inbox/`** files) versus live **`__JAIPH_EVENT__`** lines on stderr for progress and hooks.
+- **[Hooks](hooks.md)** — Project or user `hooks.json` to run shell commands on workflow and step lifecycle events (hooks run on the **host** CLI even when the workflow runs in Docker).
+- **[Sandboxing](sandboxing.md)** — Docker-backed isolation for **`jaiph run` only** (beta; **on by default** when **`JAIPH_DOCKER_ENABLED`** is unset and **`JAIPH_UNSAFE`** is not **`true`**). Enablement is **environment-only** — use **`JAIPH_DOCKER_ENABLED`** and **`JAIPH_UNSAFE`** as described in [Enabling Docker](sandboxing.md#enabling-docker); workflow **`config` cannot turn Docker on or off**. There is no **`jaiph run --docker`** flag. Image, network, and timeout still come from **`runtime.*`** and **`JAIPH_DOCKER_*`** where applicable ([Configuration](configuration.md)). **`jaiph test`** does not use Docker ([Architecture — Test runner integration](architecture.md#test-runner-integration-testjh-in-the-kernel)).
 
 ## Other
 
 - **[VS Code extension](https://marketplace.visualstudio.com/items?itemName=jaiph.jaiph-syntax-vscode)** — Syntax highlighting, formatting, and compile feedback in the editor.
 - **[Architecture](architecture.md)** — How the CLI, parser, transpiler, Node runtime, and contracts fit together; aimed at contributors and deep dives.
 - **[Contributing](contributing.md)** — Clone-and-build workflow, branch strategy, test layers, and how to propose changes.
-- **[Agent Skill](jaiph-skill.md)** — Short, opinionated defaults for AI assistants authoring and running Jaiph in a repo.
+- **[Agent Skill](jaiph-skill.md)** — Short, opinionated defaults for AI assistants authoring and running Jaiph in a repo (same content as the canonical raw URL: `https://raw.githubusercontent.com/jaiphlang/jaiph/refs/heads/main/docs/jaiph-skill.md`).
 - **[Examples](https://github.com/jaiphlang/jaiph/tree/main/examples)** — Runnable samples (async, inbox, testing, recovery) alongside the main tree.
diff --git a/docs/grammar.md b/docs/grammar.md
index 6dbc902d..36c95ff8 100644
--- a/docs/grammar.md
+++ b/docs/grammar.md
@@ -13,7 +13,17 @@ Jaiph source files (`.jh`) combine a small orchestration language with shell exe
 
 **Source of truth:** When this document and the compiler disagree, treat the implementation as authoritative.
 
-**Compile vs. graph load:** The rules below are checked during **transpile-time validation** (`validateReferences` on each module) when the CLI runs `buildScripts` / `emitScriptsForModule` (and when you run `jaiph compile`). The runtime’s `buildRuntimeGraph` path **parses** imports only — it does not re-run that validation, though the runtime still enforces invariants and resolves references from the loaded graph. See [Architecture](architecture.md).
+**Compile vs. graph load:** Reference and channel rules are checked during **transpile-time validation** (`validateReferences` on each reachable module) when the CLI runs **`buildScripts`** / **`emitScriptsForModule`** (before any script files are written). The same validation alone runs for **`jaiph compile`** — no `scripts/` emission and no runtime graph build ([Architecture](architecture.md)). The runtime’s **`buildRuntimeGraph`** path **parses** the import closure only; it does not re-run **`validateReferences`**, though execution still resolves symbols from the loaded graph and enforces runtime invariants.
+
+## Overview
+
+This guide answers three questions for workflow authors:
+
+1. **What can appear in a `.jh` file?** — Top-level imports, config, channels, module `const` bindings, scripts, rules, and workflows; execution constructs (`run`, `ensure`, `prompt`, control flow, channels) live in workflow and rule bodies with different restrictions.
+2. **Where is it enforced?** — The parser (`src/parser.ts`, `src/parse/*`) builds the AST; **`validateReferences`** (`src/transpile/validate.ts`) rejects invalid references, arity, and disallowed constructs before **`emitScriptsForModule`** extracts **`script`** bodies to `scripts/`. The **Node workflow runtime** interprets everything else from the AST ([Architecture](architecture.md)).
+3. **How do scripts relate to Jaiph?** — Only **`script`** definitions and inline **`run \`…\`()` / `run ```…```()`** bodies become executable files under `scripts/`; they run as child processes while workflows and rules stay in the interpreter.
+
+The sections below go from **values and declarations** through **steps**, **scripts**, **interpolation**, then **formal notes** (lexical, EBNF, validation catalog).
 
 ## Types
 
@@ -44,9 +54,9 @@ The compiler enforces these boundaries at every call site. Using a script where
 
 Jaiph enforces a strict boundary between **managed** steps (interpreted by the runtime) and **shell task code**. Prefer top-level `script` definitions (or inline `run` scripts) for multi-line bash. **Workflow** bodies may also contain free-form **inline shell** lines; **rule** bodies must not — unstructured shell there is rejected at validation.
 
-- **Workflows** — Named sequences of steps. **Managed** Jaiph steps include `ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox `send` (`channel <- …`), `match`, `if`, `run async`, `ensure … catch`, `run … catch`, and `run … recover`. A line that does **not** parse as one of those becomes an **inline shell** step (bash text stored as a `shell` AST node). The compiler still validates shell lines (for example a bare name that refers to a local script or workflow must be written as `run name()`, not as a shell line). For non-trivial bash, prefer a top-level `script` and `run name()`.
+- **Workflows** — Named sequences of steps. **Managed** Jaiph steps include `ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox `send` (`channel <- …`), `match`, `if`, `for … in … { … }` (line iteration over a string variable), `run async`, `ensure … catch`, `run … catch`, and `run … recover`. A line that does **not** parse as one of those becomes an **inline shell** step (bash text stored as a `shell` AST node). The compiler still validates shell lines (for example a bare name that refers to a local script or workflow must be written as `run name()`, not as a shell line). For non-trivial bash, prefer a top-level `script` and `run name()`.
 
-- **Rules** — Named blocks of the same **managed** step forms as workflows, with restrictions: `ensure` (other rules), `run` (scripts only — not workflows), `const`, `match`, `if`, `fail`, `log`/`logerr`, `return`, `ensure … catch`, `run … catch`, and `run … recover`. Rules cannot use `prompt`, `const … = prompt`, inbox `send`, or `run async`. **Raw shell lines are not allowed** in rules: if a line parses as unstructured shell, validation fails with `E_VALIDATE` (`inline shell steps are forbidden in rules; use explicit script blocks`).
+- **Rules** — Named blocks of the same **managed** step forms as workflows, with restrictions: `ensure` (other rules), `run` (scripts only — not workflows), `const`, `match`, `if`, `for … in … { … }`, `fail`, `log`/`logerr`, `return`, `ensure … catch`, `run … catch`, and `run … recover`. Rules cannot use `prompt`, `const … = prompt`, inbox `send`, or `run async`. **Raw shell lines are not allowed** in rules: if a line parses as unstructured shell, validation fails with `E_VALIDATE` (`inline shell steps are forbidden in rules; use explicit script blocks`).
 
 - **Scripts** — Top-level `script` definitions emitted as separate executable files under the workspace `scripts/` directory. Called from workflows or rules with `run`. Bodies are opaque to the compiler — the parser does not check Jaiph keywords inside them. Use `echo`/`printf` for data output and `return N`/`return $?` for exit status. In **single-line backtick** script bodies, Jaiph `${…}` interpolation is **forbidden** (use `$1`, `$2`, … from the orchestration layer). In **fenced** (`\`\`\`…\`\`\``) script bodies, `${…}` is passed through to the shell. Polyglot support: a fence lang tag (`` ```<tag> ``) maps to `#!/usr/bin/env <tag>` — any tag is valid (no hardcoded allowlist). Alternatively, a manual `#!` shebang as the first line of the body selects the interpreter; if both a fence tag and a `#!` first line are present, it is an error. Without either, `#!/usr/bin/env bash` is used. For trivial one-off commands, **inline scripts** (`` run `body`(args) `` or `` run ```lang...body...```(args) ``) let you embed a script body directly in a step without a named definition — see [`run` — Inline Scripts](#inline-scripts).
 
@@ -313,7 +323,7 @@ date +%s
 
 **Deterministic naming:** Inline script bodies are emitted as executable files under `scripts/` with names of the form `__inline_<hash>` where `<hash>` is the first **12** hex digits of the SHA-256 digest of `shebang + "\n" + body` when a shebang is present, or of the body alone when it is not (`src/inline-script-name.ts`). The same body and shebang always produce the same artifact name across runs.
 
-**Isolation:** Inline scripts run with the same subprocess isolation as named scripts — no parent scope variables are visible. Only positional arguments and essential Jaiph variables (`JAIPH_SCRIPTS`, `JAIPH_WORKSPACE`) are inherited.
+**Isolation:** Inline scripts use the same subprocess mechanism as named scripts: the child inherits the **workflow runner’s environment** (`process.env` passed into `NodeWorkflowRuntime`), including host variables and Jaiph-related keys set by the CLI and layered config — not a freshly emptied environment. **Orchestration bindings** (`const`, parameters, captures) are **not** exported into that environment automatically; pass values as **`$1`, `$2`, …** or rely on variables already exported by the host.
 
 **Restrictions:**
 - `run async` with inline scripts is not supported — inline scripts cannot be used with `run async`.
@@ -577,7 +587,9 @@ channel alerts -> handle_alert
 channel events -> handler_a, handler_b
 ```
 
-When a message arrives on the channel, the runtime calls each target workflow, binding the three dispatch values (message, channel, sender) to whatever parameter names the target declares. Route targets must declare exactly 3 parameters. Multiple targets dispatch sequentially. Routes are stored on `ChannelDef`, not on workflow definitions or steps. See [Inbox & Dispatch](inbox.md).
+When a routed message is **drained**, the runtime calls each target workflow, binding the three dispatch values (message, channel, sender) to whatever parameter names the target declares. Route targets must declare exactly 3 parameters. Multiple targets dispatch sequentially. Routes are stored on `ChannelDef`, not on workflow definitions or steps. See [Inbox & Dispatch](inbox.md).
+
+**Enqueue vs. dispatch:** `send` appends to an in-memory queue during workflow execution. After that workflow’s steps finish successfully, the runtime **drains** the queue and runs route targets. Sends from **nested** workflows bubble to the **nearest ancestor** workflow context that has routes for that channel (so dispatch stays aligned with the orchestrator workflow — see `NodeWorkflowRuntime`).
 
 A `->` route declaration inside a workflow body is a **parse error** with guidance to move it to the top-level `channel` declaration.
 
@@ -613,6 +625,44 @@ fail """
 
 Aborts the workflow or rule with a message on stderr and non-zero exit. Accepts a single-line `"..."` string or a triple-quoted `"""..."""` multiline block.
 
+### `if` — conditional block
+
+Runs a nested block when a string variable compares equal (or not equal) to a literal, or matches (or does not match) a regex.
+
+```jaiph
+if status == "ok" {
+  log "healthy"
+}
+
+if message =~ /ERROR/ {
+  logerr "matched error pattern"
+}
+```
+
+- **Subject:** bare identifier naming an in-scope variable (`const`, capture, or parameter). If the value is an async **handle**, it is resolved before the test (same resolution rules as other reads).
+- **Operators:** `==` and `!=` take a **double-quoted string** operand; `=~` and `!~` take a **`/regex/`** operand. Mixing operator and operand kinds is a parse error.
+
+Allowed in workflows and rules. Nested steps inside the block follow the same constraints as the surrounding workflow or rule body.
+
+### `for … in …` — iterate lines of a string
+
+```jaiph
+const paths = """
+docs/a.md
+docs/b.md
+"""
+
+for path in paths {
+  log "${path}"
+}
+```
+
+**Syntax:** `for <iterVar> in <sourceVar> { … }` — both names are bare identifiers. `<sourceVar>` must already hold a string; the runtime splits it on newlines (normalizes `\r\n` to `\n`). If the string ends with a final newline, the **trailing empty segment is dropped** — so `"a\nb\n"` yields two iterations (`a`, `b`), not a third empty line (see `linesOfDelimitedString` in `src/runtime/string-lines.ts`).
+
+Inside the body, `<iterVar>` is bound to each line for every iteration. Iterator names participate in the same immutable-binding rules as `const` in that scope.
+
+Allowed in workflows and rules.
+
 ### `return`
 
 ```jaiph
@@ -823,13 +873,9 @@ Non-bash scripts skip Jaiph keyword validation and emit the body verbatim.
 
 ### Script Isolation
 
-Scripts run in a clean process environment (`env -i`). Only these variables are inherited:
-
-- System: `PATH`, `HOME`, `TERM`, `USER`
-- Jaiph: `JAIPH_SCRIPTS`, `JAIPH_WORKSPACE`
-- Positional arguments (`$1`, `$2`, …)
+Managed **script** steps (`run` to a named script, inline script, or `import script`) are spawned with the **same environment object** the workflow runner uses for that scope (`scope.env`): effectively the runner’s `process.env` as augmented by Jaiph (`JAIPH_WORKSPACE`, `JAIPH_SCRIPTS`, run/agent metadata from config, run-directory variables set during execution, etc.). This is **not** an `env -i`-style wipe — inherited host variables remain available unless overwritten.
 
-Module-scoped `const` variables are **not** visible. Pass data as positional arguments, duplicate small bash inline, or use `import script` for shared helpers.
+Module-scoped **`const`** values live only in the interpreter’s variable map — they are **not** automatically exported into script environments. Pass data as **`$1`, `$2`, …**, read Jaiph-provided env vars, or export from the host before starting `jaiph run`.
 
 ## String Interpolation {#string-interpolation}
 
@@ -901,7 +947,8 @@ Informal symbols: `string` = quoted string; `call_ref` = `REF "(" [args] ")"` 
 file            = { top_level } ;
 
 top_level       = config_block | import_stmt | import_script_stmt | channel_decl | env_decl | rule_decl | script_decl | workflow_decl ;
- (* env_decl is written `const` in source; parsed into `envDecls` / module constants in `src/parser.ts`. *)
+ (* env_decl is written `const` in source; parsed into `envDecls` / module constants in `src/parser.ts`.
+    Test modules (`*.test.jh`) may also contain `test` blocks — see `parseTestBlock` / [Testing](testing.md). *)
 
 config_block    = "config" "{" { config_line } "}" ;
 config_line     = config_key "=" config_value ;
@@ -945,10 +992,11 @@ workflow_config = config_block ;
 workflow_step   = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stmt | run_async_stmt | prompt_stmt
                 | const_decl_step | return_stmt
                 | fail_stmt | log_stmt | logerr_stmt | send_stmt
-                | match_stmt | if_stmt | comment_line ;
-  (* route declarations (-> workflow) belong at the top level in channel_decl,
-     not inside workflow bodies; a -> inside a body is E_PARSE *)
-  (* Any line that does not match the managed forms above becomes a shell step in workflows. *)
+                | match_stmt | if_stmt | for_lines_stmt | comment_line ;
+  (* Route declarations (-> workflow) belong at top level in channel_decl, not inside workflow bodies
+     (-> inside a body is E_PARSE). Any line that does not match the managed forms above becomes a
+     shell step in workflows (rules forbid shell — validated separately). *)
+for_lines_stmt  = "for" IDENT "in" IDENT "{" { workflow_step } "}" ;
 
 const_decl_step = "const" IDENT "=" const_rhs ;
 const_rhs       = double_quoted_string | triple_quoted_block | bash_value_expr
@@ -958,7 +1006,10 @@ const_rhs       = double_quoted_string | triple_quoted_block | bash_value_expr
                 | "match" IDENT "{" { match_arm } "}" ;
 
 fail_stmt       = "fail" ( double_quoted_string | triple_quoted_block ) ;
-run_async_stmt  = "run" "async" call_ref [ "recover" recover_bindings recover_body ] [ "catch" catch_bindings catch_body ] ;
+run_async_stmt  = "run" "async" call_ref [ recover_suffix | catch_suffix ] ;
+recover_suffix  = "recover" recover_bindings recover_body ;
+catch_suffix    = "catch" catch_bindings catch_body ;
+  (* recover and catch are mutually exclusive on a given run async — parser/runtime treat only one as active *)
 return_stmt     = "return" return_value ;
 return_value    = double_quoted_string | triple_quoted_block | "$" IDENT | "${" IDENT "}"
                 | IDENT
@@ -1011,6 +1062,9 @@ single_workflow_stmt = ensure_stmt | run_stmt | run_catch_stmt | run_recover_stm
                 | const_decl_step
                 | return_stmt | fail_stmt | log_stmt | logerr_stmt
                 | send_stmt ;
+  (* Actual catch/recover bodies use parseCatchStatement in src/parse/steps.ts: a richer subset
+     than this sketch, including inline shell text for workflow recovery blocks — rule bodies still
+     reject unstructured shell via validateRuleStep. *)
 ```
 
 ## Validation Rules
@@ -1034,23 +1088,24 @@ Validation rules:
 8. Shell redirection (`>`, `|`, `&`) after `run`/`ensure` is rejected — use a script.
 9. **Type crossing:** `string` and `script` are non-interchangeable primitive types (see [Types](#types)). `prompt` rejects script names; `run` rejects string consts; assigning a script to a `const` or interpolating a script name with `${…}` is rejected. Each crossing produces an actionable `E_VALIDATE` message.
 10. **Explicit nested managed calls:** Bare call-like forms in argument position (`run foo(bar())`, `run foo(rule_bar())`) are rejected — add the missing `run` or `ensure` keyword. Bare inline script calls in arguments (`run foo(\`echo aaa\`())`) are also rejected — add `run`. Valid forms: `run foo(run bar())`, `run foo(ensure rule_bar())`, `run foo(run \`echo aaa\`())`.
+11. **`for iter in source`:** `source` must name a variable already in scope (`const`, capture, or parameter) — unknown names are `E_VALIDATE`.
 
 ## Build Artifacts {#build-artifacts}
 
 `jaiph run` and `jaiph test` do **not** transpile workflows to shell. The CLI calls `buildScripts()`, which emits only per-`script` executable files under `scripts/`. Workflows, rules, prompts, channels, and control flow are interpreted by `NodeWorkflowRuntime` from the AST.
 
-Each `script name = …` becomes `scripts/<name>` with `chmod +x`: shebang (from fence lang tag, manual `#!`, or default `#!/usr/bin/env bash`) plus the body. Inline scripts (`` run `body`(args) `` or `` run ```lang...body...```(args) ``) are emitted as `scripts/__inline_<hash>` with deterministic hash-based names. At runtime, script steps run these files with a minimal environment.
+Each `script name = …` becomes `scripts/<name>` with `chmod +x`: shebang (from fence lang tag, manual `#!`, or default `#!/usr/bin/env bash`) plus the body. Inline scripts (`` run `body`(args) `` or `` run ```lang...body...```(args) ``) are emitted as `scripts/__inline_<hash>` with deterministic hash-based names. At runtime, script subprocesses inherit the **workflow runner environment** (host `process.env` plus Jaiph variables — see [Script Isolation](#script-isolation)), not an emptied shell environment.
 
 ## Runtime Execution
 
 At runtime, the Node workflow runtime interprets the AST directly:
 
 - **Config:** Precedence chain: environment → workflow-level → module-level → defaults.
-- **Script isolation:** Managed subprocesses with only essential variables. Module-scoped variables not visible.
+- **Script subprocess environment:** Script steps receive the same **`scope.env`** as the interpreter (runner `process.env` plus Jaiph metadata and run paths). Module **`const`** bindings are **not** auto-exported — pass values via arguments or host exports.
 - **Prompt + schema:** JSON extraction and schema validation via the JS kernel. Exit codes: 0=ok, 1=parse error, 2=missing field, 3=type mismatch.
 - **ensure/run … catch:** On failure, the recovery body runs **once**. There is no retry loop. Requires explicit bindings: `catch (failure) { … }`. The binding gets the merged stdout+stderr from the failed execution.
 - **run … recover:** Repair-and-retry loop. On failure, the binding gets merged stdout+stderr, the repair body runs, and the target is retried. Loop stops on success or when `run.recover_limit` (default 10) is exhausted. Requires explicit bindings: `recover(err) { … }`.
 - **Recursion safety:** There is a hard recursion depth limit of 256. Exceeding it produces a runtime error.
 - **Assignment capture:** Rules and workflows use explicit `return "…"`. Scripts use stdout.
 - **`run async`:** Returns a `Handle<T>` value. Handle-based concurrency with implicit resolution on first non-passthrough read and implicit join of unresolved handles at workflow exit. `recover` and `catch` composition supported. Failures aggregated at join.
-- **Channels:** Messages enqueued via `send`, dispatched to route targets at workflow end. Each target must declare exactly 3 parameters; the runtime binds message, channel, and sender to the declared names.
+- **Channels:** `send` enqueues messages on the active workflow context; after that workflow’s steps complete successfully, the runtime drains the queue and invokes route targets. A send from a nested workflow targets the **nearest ancestor** context that defines routes for that channel. Each route target must declare exactly 3 parameters; the runtime binds message, channel, and sender to the declared names.
diff --git a/docs/hooks.md b/docs/hooks.md
index cf5990c9..82fe6adc 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -7,19 +7,19 @@ redirect_from:
 
 # Hooks
 
-Many workflows trigger **integrations** you do not want to hard-code in `.jh` sources: notifications, structured logging, CI callbacks. **Hooks** are optional shell commands the CLI runs at fixed lifecycle points. Configuration lives in `hooks.json` (global or per-project), so side effects stay out of workflow modules and can be shared across runs.
+Workflow automation often needs **side effects** outside the workflow itself: notifications, structured logging, webhooks, or CI integration. Hard-coding those into `.jh` makes modules noisy and hard to reuse. **Hooks** are a separate mechanism: optional shell commands the **CLI** runs at fixed workflow/step lifecycle points. You declare them in `hooks.json` (global or per-project); they are not part of the Jaiph language and do not run inside `NodeWorkflowRuntime`.
 
-Hooks are **CLI-only**: they are *not* part of `NodeWorkflowRuntime`. The same **`__JAIPH_EVENT__`** JSON lines on stderr that drive the progress tree are parsed in the CLI; hook commands receive a JSON snapshot of each event on stdin. Channels and inbox behavior remain runtime concerns. See [Architecture — Runtime vs CLI responsibilities](architecture.md#runtime-vs-cli-responsibilities) and [Architecture — Channels and hooks in context](architecture.md#channels-and-hooks-in-context). The live event contract is summarized under [Architecture — Contracts](architecture.md#contracts).
+The CLI parses the same **`__JAIPH_EVENT__`** JSON lines on the runner’s **stderr** that drive the progress tree. For each supported lifecycle event, it forwards a JSON **snapshot** to your commands on **stdin**. Channels, inbox files, and dispatch stay in the runtime — hooks only observe the stream and act on the host. See [Architecture — Runtime vs CLI responsibilities](architecture.md#runtime-vs-cli-responsibilities), [Architecture — Channels and hooks in context](architecture.md#channels-and-hooks-in-context), and [Architecture — Contracts](architecture.md#contracts).
 
 ## When hooks run
 
-Hooks run only for normal **`jaiph run`**, including the shorthand **`jaiph <file.jh>`** (same code path as `jaiph run`). The entry file must be a **non-test** `.jh` file (`src/cli/index.ts` routes `*.test.jh` to `jaiph test` instead).
+Hooks run only for interactive **`jaiph run`** (including the shorthand **`jaiph <file.jh>`**, which uses the same `runWorkflow` path as **`jaiph run`**). The entry file must be a **non-test** `.jh` file (`src/cli/index.ts` routes `*.test.jh` to `jaiph test`).
 
-Hooks do **not** run for `jaiph test`, `jaiph init`, `jaiph compile`, `jaiph format`, or other commands. **`jaiph run --raw`** skips hooks (and the banner, progress tree, and failure footer) so stderr stays a clean `__JAIPH_EVENT__` stream—used when the host CLI wraps Docker or another embedding. See [CLI — `jaiph run`](cli.md#jaiph-run).
+Hooks do **not** run for `jaiph test`, `jaiph compile`, `jaiph format`, `jaiph init`, `jaiph install`, `jaiph use`, or other commands. **`jaiph run --raw`** skips hooks (and the banner, progress tree, and failure footer) so stderr stays a clean `__JAIPH_EVENT__` stream — used when embedding Jaiph or when the host wraps a container. See [CLI — `jaiph run`](cli.md#jaiph-run).
 
 For local runs, hooks use the same machine as the workflow. For **Docker-backed** runs, hook commands still execute on the **host** CLI process, not inside the container. See [Sandboxing — Runtime behavior](sandboxing.md#runtime-behavior).
 
-## Config locations
+## Config locations and precedence
 
 | Scope | Path |
 |-------|------|
@@ -28,7 +28,11 @@ For local runs, hooks use the same machine as the workflow. For **Docker-backed*
 
 Both files are optional. `<workspace>` is resolved the same way as `JAIPH_WORKSPACE` for `jaiph run`: walk up from the entry `.jh` file’s directory, with guards for temp directories and nested sandboxes. Full rules: [CLI — Environment variables](cli.md#environment-variables).
 
-**Precedence (per event):** If the project file defines at least one non-empty command for an event, only those commands run and global commands for that event are ignored. Lists are not merged. If the project file omits an event or only has empty/invalid entries for it, global commands apply for that event. Unsupported keys in the JSON object are ignored (see [Schema](#schema)).
+**Precedence is per event:** if the project file defines at least one non-empty command for an event, **only** those commands run and global commands for that event are ignored (lists are not merged). If the project file omits an event or only has empty / skipped entries for it, global commands apply for that event. Changing `step_end` in the project file does not affect how `workflow_start` is resolved.
+
+Unsupported keys in the JSON object are ignored — `parseHookConfig` in `src/cli/run/hooks.ts` only reads the four supported event names.
+
+There is no explicit “disable hooks” flag. To silence a global hook for one project, override that event with a no-op, e.g. `"workflow_end": ["true"]`.
 
 ## Schema
 
@@ -36,7 +40,7 @@ Each file must be a single JSON **object** at the root (not an array) mapping **
 
 - Keys must be supported event names (see [Supported events](#supported-events)).
 - Values must be arrays. A non-array value for a known key is skipped for that event.
-- Elements must be non-empty strings (one shell command each). Empty strings and non-string elements are skipped. If every element is skipped, that event is not defined in the normalized config, so the other file’s commands can apply (see [Precedence](#precedence)).
+- Elements must be non-empty strings (one shell command each). Empty strings and non-string elements are skipped. If every element is skipped, that event is not defined in the normalized config, so the other file’s commands can apply (see [Config locations and precedence](#config-locations-and-precedence)).
 
 ```json
 {
@@ -53,23 +57,13 @@ An empty array normalizes to “no commands from this file for this event,” so
 
 | Event | When it fires |
 |-------|---------------|
-| `workflow_start` | After **`buildScripts`** completes (parse, **`validateReferences`**, script extraction to `scripts/`) on the CLI host, and **before** the workflow runner subprocess is spawned. Does not fire if compilation fails earlier. Emitted via `emitter.emit` in `src/cli/commands/run.ts` after subscribers are registered. |
-| `workflow_end` | After the runner exits (any status) and stderr has been drained, in **`reportResult`**—**before** the CLI prints PASS/FAIL. |
-| `step_start` | When the CLI parses a `STEP_START` line on the runner’s stderr (same stream as the progress tree). Includes nested steps; the root `workflow default` step still emits `STEP_START` even though the TTY view skips drawing that start row (`registerTTYSubscriber` in `src/cli/run/stderr-handler.ts`). |
-| `step_end` | When the CLI parses a matching `STEP_END` line on that stream. |
+| `workflow_start` | After **`buildScripts`** completes (parse, **`validateReferences`**, script extraction to `scripts/`) on the CLI host, and **before** the workflow runner subprocess is spawned. The interactive **banner** has already been printed (and, when Docker sandboxing is enabled, **`prepareImage`** has already run) — see `runWorkflow` in `src/cli/commands/run.ts`. Does not fire if compilation fails earlier (`buildScripts` throws before `emitter.emit("workflow_start", …)`). |
+| `workflow_end` | At the start of **`reportResult`** in `src/cli/commands/run.ts`: after the runner exits (any status) and stderr has been drained, **before** the CLI prints PASS/FAIL. |
+| `step_start` | When the CLI parses a `STEP_START` **`__JAIPH_EVENT__`** line on the runner’s stderr (same stream as the progress tree). Includes nested steps. The root **`workflow default`** step still emits `STEP_START`; the TTY subscriber skips **drawing** that start row (`data.isRoot` in `registerTTYSubscriber`, `src/cli/run/stderr-handler.ts`). |
+| `step_end` | When the CLI parses a matching `STEP_END` line on that stream. The TTY subscriber also skips drawing the root step’s completion row (`data.isRoot`). |
 
 Step `kind` values come from the runtime event payload (`workflow`, `rule`, `script`, `prompt`). See [CLI — Run progress and tree output](cli.md#run-progress-and-tree-output).
 
-## Precedence
-
-Resolution is **per event**, independently:
-
-- Project `workflow_end` with at least one usable command — only those run; global `workflow_end` is ignored.
-- Project omits `workflow_end` or supplies `[]` / only skipped commands — global `workflow_end` runs (if any).
-- Changing `step_end` in the project file does not affect how `workflow_start` is resolved.
-
-There is no explicit “disable hooks” flag. To silence a global hook for one project, override that event with a no-op, e.g. `"workflow_end": ["true"]`.
-
 ## Payload
 
 Each command receives one JSON object on **stdin** (UTF-8). Parse with `jq`, `python3 -c`, or your tool of choice. Stdin can only be read once per process; buffer it in a variable if you need the payload multiple times (see [Examples](#examples)).
@@ -82,12 +76,12 @@ Each command receives one JSON object on **stdin** (UTF-8). Parse with `jq`, `py
 | `workflow_id` | all | Runtime `run_id` from each `STEP_*` line. Empty on `workflow_start`. For `workflow_end`, the CLI reuses the first non-empty `run_id` it buffered while parsing stderr (`workflowRunId` in `RunState`, `src/cli/run/stderr-handler.ts`); it stays empty if the runner never emitted one. `step_start` / `step_end` echo the `run_id` from that event. |
 | `timestamp` | all | ISO 8601 string. For `step_*`, the event’s `ts` when non-empty; otherwise the CLI synthesizes one at hook time. `workflow_start` and `workflow_end` timestamps come from the CLI when those hooks fire. |
 | `run_path` | all | Absolute path to the `.jh` entry file. |
-| `workspace` | all | Workspace root directory (same rules as [Config locations](#config-locations)). |
-| `step_id` | `step_*` | Step id for progress and captures; from the event’s `id`, or a synthesized `legacy:…` value when the runtime left `id` empty so starts and ends still pair (`resolveEventId` in `src/cli/run/stderr-handler.ts`). |
+| `workspace` | all | Workspace root directory (same rules as [Config locations](#config-locations-and-precedence)). |
+| `step_id` | `step_*` | Step id for progress and captures; from the event’s `id`, or a synthesized `legacy:<n>:<func>` value when the runtime left `id` empty so starts and ends still pair (`resolveEventId` in `src/cli/run/stderr-handler.ts`). |
 | `step_kind` | `step_*` | `workflow`, `rule`, `script`, or `prompt`. |
 | `step_name` | `step_*` | Step name (e.g. `default`, `scan_passes`). |
-| `status` | `*_end` | **Step:** exit status from the `STEP_END` event (0 success, non-zero failure; missing status is treated as `1` in the hook payload). **Workflow:** the CLI’s resolved outcome—**`0` success or `1` failure** (not the raw child exit code): non-zero subprocess exit or `hasFatalRuntimeStderr` yields `1` (`reportResult` in `src/cli/commands/run.ts`). |
-| `elapsed_ms` | `*_end` | **`workflow_end`:** wall-clock ms from when the CLI recorded `startedAt` (inside the main `try` after the output dir exists—so **after** module metadata is read and the scratch/target directory is created, and **including** banner, **`buildScripts`**, the full runner lifetime, and stderr drain) until the hook runs. **`step_end`:** duration from the `STEP_END` event, or `0` if missing. |
+| `status` | `*_end` | **Step:** exit status from the `STEP_END` event (0 success, non-zero failure; missing / null status becomes `1` in the hook payload via `?? 1`). **Workflow:** the CLI’s resolved outcome — **`0` success or `1` failure** (not the raw child exit code): non-zero subprocess exit or `hasFatalRuntimeStderr` yields `1` (`reportResult` in `src/cli/commands/run.ts`). |
+| `elapsed_ms` | `*_end` | **`workflow_end`:** wall-clock ms from when the CLI recorded `startedAt` (start of the main `try` in `runWorkflow`, after the scratch/target directory exists — so **after** module metadata is read and `outDir` exists, and **including** banner, **`buildScripts`**, the full runner lifetime, and stderr drain) until the hook runs. **`step_end`:** duration from the `STEP_END` event, or `0` if missing. |
 | `run_dir` | `workflow_end` | Absolute run log directory from runner metadata (or Docker discovery). Omitted if unavailable. |
 | `summary_file` | `workflow_end` | Absolute path to `run_summary.jsonl` when metadata provides it. See [CLI — Run summary](cli.md#run-summary-jsonl). |
 | `out_file` | `step_end` | Stdout capture path from the `STEP_END` event. The hook omits this JSON key when the parsed event has an empty `out_file` string (`registerHooksSubscriber` in `src/cli/run/hooks.ts`). Current runtimes normally emit paths for every completed step; files may still be empty. |
@@ -119,22 +113,22 @@ Example payload (`step_end`):
 }
 ```
 
+Shape definitions in repo: **`HookPayload`** / **`HookEventName`** in `src/types.ts`.
+
 ## Behavior
 
 - **Shell:** Each command runs as `sh -c '<command>'` (POSIX `sh` on the **`PATH`** of the `jaiph run` process).
-- **Concurrency:** Every command for one event is spawned in a loop **without** waiting for the previous process to exit, so hook commands for the same event overlap in wall time. Ordering across lifecycle stages is still `workflow_start` → step hooks as lines arrive → `workflow_end` before PASS/FAIL.
+- **Concurrency:** Every command for one event is spawned in a loop **without** waiting for the previous process to exit, so hook commands for the same event overlap in wall time. The CLI also **does not wait** for hook processes between lifecycle stages: a `workflow_end` hook may start while `step_end` hooks spawned earlier are still running. Causal order is only **when spawns happen**: `workflow_start` → step hooks as stderr lines are processed → `workflow_end` before PASS/FAIL.
 - **Best-effort:** Hook failures never change the CLI exit code. Non-zero exits or spawn errors log `jaiph hooks: …` lines on stderr; the workflow result is unchanged.
 - **I/O:** Hook stdout is discarded. Hook stderr is copied to the CLI’s stderr. The JSON payload is written with `stdin.end(payloadJson, "utf8")` per process; if a hook exits before reading stdin, delivery is best-effort and may log an error.
 - **Environment:** Hooks receive a shallow copy of `process.env` at hook spawn time.
-- **Working directory:** The child’s cwd is **not** reset by the hook runner—it inherits the **`jaiph run` process cwd** (often where you launched the CLI), not necessarily `workspace`. Use the `workspace` field from stdin for project-root paths.
+- **Working directory:** The child’s cwd is **not** reset by the hook runner — it inherits the **`jaiph run` process cwd** (often where you launched the CLI), not necessarily `workspace`. Use the `workspace` field from stdin for project-root paths.
 
 **Invalid or missing config:** Missing files are skipped silently. A file that exists but fails `JSON.parse` or is not a JSON object produces a stderr warning and is ignored. Bad per-event values are skipped without rejecting the rest of the file (`parseHookConfig` in `src/cli/run/hooks.ts`).
 
-Shape definitions in repo: **`HookPayload`** / **`HookEventName`** in `src/types.ts`.
-
 ## Examples
 
-**Global `~/.jaiph/hooks.json` — POST the workflow-end payload to an HTTP endpoint:**
+**Global `~/.jaiph/hooks.json` — POST the workflow-end payload to an HTTP endpoint** (replace the URL with yours):
 
 ```json
 {
diff --git a/docs/inbox.md b/docs/inbox.md
index b81a0eed..6875d5eb 100644
--- a/docs/inbox.md
+++ b/docs/inbox.md
@@ -9,24 +9,27 @@ redirect_from:
 
 ## Overview
 
-Pipelines often split work across **workflows** that hand off a payload: one
-stage produces output, a later stage reacts to it. A generic way to do that
-without a separate broker is an **in-module channel**: a named queue the
-runtime can drain after a caller finishes its steps, driving receiver workflows
-in order.
-
-**Jaiph’s model** is a small orchestration feature on top of that idea: a
-`channel` is declared with optional `->` routes to **workflow** targets; a send
-uses `<-` to enqueue a string payload. `NodeWorkflowRuntime` keeps the queue
-and route map in memory, may persist a routed send to disk for audit, and
-**dispatches** targets when the **entry** workflow’s step list completes (plus
-any implicit `run async` join) — not when a separate `->` “fires”; the `->`
-in source code is **static routing** on the channel line, not a runtime
-operator.
-
-`NodeWorkflowRuntime` attaches an **in-memory** queue (`WorkflowContext.queue`) and route **`Map`** per **`run <workflow>()`**. **`channel … ->`** bindings load into **`routes` only when `inheritCallerMetadataScope` is **`false`** (CLI **`jaiph run`** → **`workflow default`**, programmatic **`runNamedWorkflow`** → the named callee). Nested **`run`** workflows begin with **`routes = new Map()` — see **[Who registers routes and who drains](#who-registers-routes-and-who-drains)**.
-
-On **`send`**, **`inboxSeq`** increments, an **`InboxMsg`** queues on **`targetCtx`**, and **`run_summary.jsonl`** always gains **`INBOX_ENQUEUE`** (channel / sender / sequence metadata only — **[Trigger contract](#trigger-contract)**). **`inbox/NNN-<literal>.txt`** is created only when the runtime marked the send **`routed`** (**`routes.has(step.channel)`** in **`node-workflow-runtime.ts`**). If **every** send stays **`routed === false`**, **`inbox/`** may be omitted. Interpreter queue + drain — **[Architecture — Channels and hooks](architecture.md#channels-and-hooks-in-context)** — no brokers, no **`inotify`**, no polling **`inbox/`**.
+Many pipelines split work across stages: one part of the system produces a
+payload and another reacts later. Without standing up a message broker, a
+common pattern is an **in-process queue**: producers enqueue messages, and the
+runtime drains that queue at predictable boundaries so receivers run in order.
+
+**Jaiph’s channels** follow that pattern at workflow granularity. You declare a
+`channel` at module scope, optionally list workflow targets after `->`, and use
+`<-` inside a workflow to enqueue a **string** payload. Routing on the
+`channel … ->` line is **static** (parsed into the AST); nothing “fires” at
+parse time. Delivery happens later: after a workflow’s steps finish — including
+waiting out any **`run async`** handles joined at workflow exit — the runtime
+drains that workflow frame’s queue and **`run`s** each route target in order.
+
+Under the hood, `NodeWorkflowRuntime` keeps queues and route maps **in memory**
+(see [Architecture — Channels and hooks in context](architecture.md#channels-and-hooks-in-context)).
+**`run_summary.jsonl`** records **`INBOX_ENQUEUE`** on every send (metadata only;
+see [Trigger contract](#trigger-contract)). **`inbox/NNN-<channel>.txt`** files
+are optional **audit** copies of the payload for **routed** sends only; routing
+does not read them back — no filesystem watchers or inbox polling. Which stack
+frame owns routes, and how sends bubble to an ancestor frame, is spelled out in
+[Who registers routes and who drains](#who-registers-routes-and-who-drains).
 
 ## At a glance
 
@@ -58,7 +61,10 @@ channel name, and sender bound to its declared parameters `message`, `chan`, and
   join for `run async`). `inbox/*.txt` is an optional audit copy for routed sends —
   routing does **not** read from disk — no `inotifywait`, `fswatch`, or polling loops.
 - **Sequential dispatch.** For each queued message, route targets run **in list
-  order** (declaration order on the `channel` line), one completion at a time.
+  order** (declaration order on the `channel` line), strictly **one after
+  another**. Older Jaiph releases exposed parallel inbox dispatch via config /
+  environment variables; that mode is **removed** — `run.inbox_parallel` is an
+  unknown config key and **`JAIPH_INBOX_PARALLEL` has no effect** on ordering.
 - **Inbox is scoped per run.** **`inbox/*.txt`** persists **routed** payloads under that UTC run directory (**[Architecture — Durable artifact layout](architecture.md#durable-artifact-layout)**); there is no repo-wide mailbox outside **`.jaiph/runs`**.
 - **Channels are compile-checked.** Unknown channels, bad route targets, and
   invalid `send` RHS forms are `E_PARSE` / `E_VALIDATE` from
@@ -171,6 +177,13 @@ Route declarations are static routing rules stored on `ChannelDef`, not on
 workflow definitions or steps. The compiler validates that all target workflow
 references exist and declare exactly 3 parameters.
 
+A **`channel <name>`** line **without** **`->`** still defines **`name`** for **`send`**
+validation, but the runtime **never** adds **`name`** to **`ctx.routes`** — only
+channels with **at least one** **`->`** target populate the route map
+(**`node-workflow-runtime.ts`** skips bare channels when building **`routes`**).
+Sends on those names therefore behave like **unrouted** sends (no **`inbox/*.txt`**),
+and **`drainWorkflowQueue`** has nothing to **`run`** for them.
+
 A `->` route inside a workflow body is a **parse error** with guidance:
 `route declarations belong at the top level: channel <name> -> <targets>`.
 
@@ -210,12 +223,16 @@ Persisted payloads are exactly the **routed** sends — the orchestration queue
 ### Who registers routes and who drains
 
 Every entered workflow gets a **`WorkflowContext`**: `workflowName`, a route **`Map`**,
-and a message queue. **`->` bindings are populated only when the workflow is entered
-with `inheritCallerMetadataScope === false`** — ordinary **`jaiph run`** invokes **`workflow default`** from your **`run` filepath**, and **`runNamedWorkflow`** (tests / embedders) uses the same **`false`** branch for whichever workflow it launches, so **`routes`** mirror **that callee module’s** top-level **`channel ->`** lines—not files you only **`import`**. Each nested **`run child()`** pushes another frame with an **empty** route **`Map`**
-(**`// Only register on the entry workflow`** in **`node-workflow-runtime.ts`**), so **`send`** walks **outward** until **`routes.has(step.channel)`** succeeds (**`step.channel`** token from the **`send`** AST node).
+and a message queue. **`->` bindings are populated only on “entry” workflows:**
+the interpreter passes **`inheritCallerMetadataScope === false`** for **`jaiph run`’s
+`default`**, for **`runNamedWorkflow`** (used by **`jaiph test`**’s
+**`test_run_workflow`**), and for any other path that starts a workflow the same
+way — so **`routes`** mirror **that callee module’s** top-level **`channel ->`** lines,
+not modules you only **`import`**. Each nested **`run child()`** passes **`inheritCallerMetadataScope === true`**, which keeps **`routes`** as an **empty** **`Map`**
+(see **`node-workflow-runtime.ts`** — routes register only when **not** inheriting the caller metadata scope), so **`send`** walks **up the workflow stack** until **`routes.has(step.channel)`** succeeds (**`step.channel`** is the exact AST token left of **`<-`**).
 After **each** workflow body finishes (implicit **`run async` join included), **`drainWorkflowQueue`** runs for **that** frame’s queue and route table **before** the frame pops — nested exits are usually no-ops, while the **`jaiph run`** root drains work that nested sends enqueued onto it.
 
-**Module scope.** `ctx.routes` **keys** are bare names from **`channel <name>`** in the callee module (**`parseChannelLine`**). Imports allow **`lib.topic <-`** (validator proves **`topic`** exists inside **`lib`**) yet **`routes.has("lib.topic")`** is still **false** for default layouts, because registered keys omit the **`alias.`** prefix (**`step.channel`** is compared verbatim). Prefer **`topic <-`** next to **`channel topic -> …`** in the **`inheritCallerMetadataScope === false` module**, or **`jaiph run lib.jh`** when **`lib.jh`'s **`channel`** lines should supply the **`->`** bindings.
+**Module scope.** `ctx.routes` **keys** are bare names from **`channel <name>`** in the callee module (**`parseChannelLine`**). Imports allow **`lib.topic <-`** (validator proves **`topic`** exists inside **`lib`**) yet **`routes.has("lib.topic")`** is still **false** for default layouts, because registered keys omit the **`alias.`** prefix (**`step.channel`** is compared verbatim). Prefer **`topic <-`** next to **`channel topic -> …`** in the **entry module** (the workflow started by **`jaiph run`** or **`runNamedWorkflow`**), or **`jaiph run lib.jh`** when **`lib.jh`'s **`channel`** lines should supply the **`->`** bindings.
 
 ### Dispatch loop
 
@@ -228,7 +245,7 @@ handling and `drainWorkflowQueue`.
 4. On `<-`: resolve payload; bump `inboxSeq` (`NNN` zero-padded to **3** digits);
    enqueue on the routed context selected by scanning the stack outward; **`if routed`**
    write `inbox/NNN-<channel>.txt`; always append **`INBOX_ENQUEUE`**
-   (`channel`, `sender`, **`inbox_seq`**, **`ts`**, **`run_id`**, **`event_version`**) to **`run_summary.jsonl`** .
+   (`channel`, `sender`, **`inbox_seq`**, **`ts`**, **`run_id`**, **`event_version`**) to **`run_summary.jsonl`**.
 5. After all steps (and implicit `run async` joins) complete,
    `drainWorkflowQueue`:
    - `while (cursor < queue.length)` — new sends during dispatch append to the
@@ -318,7 +335,7 @@ no environment-variable plumbing.
 
 ### Example output
 
-Shape aligns with **`e2e/tests/91_inbox_dispatch.sh`** (**`display_inbox.jh`**): `scanner` sends on **`findings`**, **`analyst`** sends on **`report`**, **`default`** routes both:
+The shape matches the **`display_inbox.jh`** fixture inline in the same test file (search for **`display_inbox.jh`** in **`e2e/tests/91_inbox_dispatch.sh`**): `scanner` sends on **`findings`**, **`analyst`** sends on **`report`**, **`default`** routes both:
 
 ```
 workflow default
diff --git a/docs/jaiph-skill.md b/docs/jaiph-skill.md
index 92e5d45d..81ee9346 100644
--- a/docs/jaiph-skill.md
+++ b/docs/jaiph-skill.md
@@ -19,18 +19,18 @@ This page is an **agent skill**: it tells an AI assistant how to **author** Jaip
 
 The **JS kernel** (`src/runtime/kernel/`) handles **prompt** execution, **managed script subprocesses**, **inbox** queues and dispatch, and **event/summary emission**. **Rule** bodies run in-process; user **`script`** bodies run as separate OS processes (bash by default, polyglot via fence lang tags like `` ```node ``, `` ```python3 `` or a leading `#!` shebang in the body).
 
-**Test lane:** `jaiph test` runs **`*.test.jh`** in-process (`node-test-runner.ts`): for each file it calls **`buildScripts(testFile, …)`** (same helper as `jaiph run`, with the **test file as the entry** so its import closure is validated and scripts are emitted), then **`buildRuntimeGraph(testFile)` once per file**, mocks, and assertions — same `NodeWorkflowRuntime` as `jaiph run`.
+**Test lane:** `jaiph test` runs **`*.test.jh`** in-process (`node-test-runner.ts`): for each file it calls **`buildScripts(testFile, …)`** (same helper as `jaiph run`, with the **test file as the entry** so its import closure is validated and scripts are emitted), then **`buildRuntimeGraph(testFile)` once per file**, mocks, and assertions — same `NodeWorkflowRuntime` as `jaiph run`. The runtime enables **`suppressLiveEvents`** for those workflow runs so **`__JAIPH_EVENT__`** lines are not written to **stderr** (keeping `node --test` output readable); **`run_summary.jsonl`** under the run directory is still updated where the emitter records workflow traffic ([Architecture](architecture.md)).
 
 **After `jaiph init`**, a repository gets `.jaiph/bootstrap.jh` (a triple-quoted prompt that tells the agent to read `.jaiph/SKILL.md`) and a copy of this file. The bootstrap prompt asks the agent to scaffold workflows under `.jaiph/` and to end with a clear `WHAT CHANGED` + `WHY` summary. The expected outcome is a **minimal workflow set** for safe feature work: preflight checks, an implementation workflow, verification, and a `workflow default` entrypoint that wires them together (with an optional human-or-agent “review” step when you use a task queue). Docker-backed runs use the official `ghcr.io/jaiphlang/jaiph-runtime` image by default; see [Sandboxing](sandboxing.md) to override with `runtime.docker_image` or `JAIPH_DOCKER_IMAGE`.
 
 **Concepts:**
 
-- **Rules** — Structured checks: `ensure` (other **rules** only), `run` (**scripts** only — not workflows), `const`, `match`, `if`, `fail`, `log`/`logerr`, `return "…"` / `return run script()` / `return ensure rule()`, `ensure … catch`, `run … catch`, `run … recover`. No raw shell lines, `prompt`, inbox send/route, or `run async`. Under `jaiph run`, rule bodies are executed **in-process** by the Node runtime; when a rule runs a **script**, that script is a normal managed subprocess (same as scripts from workflows) — see [Sandboxing](sandboxing.md).
-- **Workflows** — Named sequences of **managed** Jaiph steps (`ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox **send**, `match`, `if`, `run async`, `ensure`/`run` with `catch` or `recover`, …) plus optional **inline shell** lines: a line that does not parse as a managed step is treated as bash stored in a `shell` AST node (validated like other shell text). Prefer top-level **`script`** definitions and `run` for multi-line or reusable shell. Route declarations (`->`) belong on top-level `channel` lines, never inside a workflow body (a `->` in a body is `E_PARSE`).
+- **Rules** — Structured checks: `ensure` (other **rules** only), `run` (**scripts** only — not workflows), `const`, `match`, `if`, `for … in …` (line iteration over a string binding), `fail`, `log`/`logerr`, `return "…"` / `return run script()` / `return ensure rule()`, `ensure … catch`, `run … catch`, `run … recover`. No raw shell lines, `prompt`, inbox send/route, or `run async`. Under `jaiph run`, rule bodies are executed **in-process** by the Node runtime; when a rule runs a **script**, that script is a normal managed subprocess (same as scripts from workflows) — see [Sandboxing](sandboxing.md).
+- **Workflows** — Named sequences of **managed** Jaiph steps (`ensure`, `run`, `prompt`, `const`, `fail`, `return`, `log`/`logerr`, inbox **send**, `match`, `if`, `for … in …`, `run async`, `ensure`/`run` with `catch` or `recover`, …) plus optional **inline shell** lines: a line that does not parse as a managed step is treated as bash stored in a `shell` AST node (validated like other shell text). Prefer top-level **`script`** definitions and `run` for multi-line or reusable shell. Route declarations (`->`) belong on top-level `channel` lines, never inside a workflow body (a `->` in a body is `E_PARSE`).
 - **Scripts** — Top-level **`script`** definitions are **bash (or shebang interpreter) source**, not Jaiph orchestration. Defined with `` script name = `body` `` (single-line backtick) or `` script name = ```[lang] ... ``` `` (fenced block). Double-quoted string bodies (`script name = "body"`) and bare identifier bodies (`script name = varName`) are **removed** — both produce parse errors with guidance to use backtick delimiters. The compiler treats all script bodies as **opaque text**: it does not parse lines as Jaiph steps, reject keywords, strip quotes, or validate cross-script calls. This means embedded `node -e` heredocs, inline Python, `const` assignments in JS, and any other valid shell construct compile without interference. Jaiph interpolation (`${...}`) is **forbidden** in **single-line backtick** script bodies — use `$1`, `$2` positional arguments to pass data from orchestration to scripts. In **fenced** (triple-backtick) blocks, `${...}` is passed through to the shell as standard parameter expansion (`${VAR}`, `${VAR:-default}`, etc.). A single-backtick body containing a newline is a hard parse error — use a fenced block for multi-line scripts. Use `return N` / `return $?` for exit status and **stdout** (`echo` / `printf`) for string data to callers. From a **workflow** or **rule**, call with **`run fn()`**. Can be exported (`export script name = ...`) for use by importing modules. Cannot be used with `ensure`, are not valid inbox route targets, and must not be invoked through `$(...)` or as a bare shell step. **Polyglot scripts:** use a fence lang tag (`` ```<tag> ``) to select an interpreter — the tag maps directly to `#!/usr/bin/env <tag>`. Any tag is valid (no hardcoded allowlist). For example: `` ```node ``, `` ```python3 ``, `` ```ruby ``, `` ```lua ``. Alternatively, if no fence tag is present, the first non-empty body line may start with `#!` (e.g. `#!/usr/bin/env lua`), which becomes the script's shebang and the body is emitted verbatim (you cannot combine a fence tag with a manual shebang — that is an error). Without either, `#!/usr/bin/env bash` is used and the emitter applies only lightweight bash-specific transforms (`return` normalization, `local`/`export`/`readonly` spacing, import alias resolution). Scripts are extracted to a `scripts/` directory under the run output tree (`jaiph run --target <dir>` sets that tree; without `--target` the CLI uses a temporary directory) and executed via **`JAIPH_SCRIPTS`**. **Inline scripts:** For trivial one-off commands, use `` run `body`(args) `` or `` run ```lang...body...```(args) `` directly in a workflow or rule step instead of declaring a named `script` definition. The body (single backtick for one-liners or triple backtick for multi-line) comes before the parentheses; optional comma-separated arguments go inside the parentheses: `` run `echo $1`("hello") ``. Fenced blocks support lang tags for polyglot inline scripts: `` run ```python3 ... ```() ``. Capture forms: `` const x = run `echo val`() `` and `` const x = run ```...```() ``. The old `run script() "body"` form is **removed** — use the backtick forms instead. Inline scripts use deterministic hash-based artifact names (`__inline_<hash>`) and run with the same isolation as named scripts. `run async` with inline scripts is not supported.
 - **Channels** — Top-level `channel <name> [-> workflow, ...]` declarations with optional inline routing; **send** uses `channel_ref <- …`. Routes are declared on the channel declaration, not inside workflow bodies (see [Inbox & Dispatch](inbox.md)). Channel names share the per-module namespace with rules, workflows, scripts, and module-scoped `local` / `const` variables.
 
-Step semantics (`ensure`, `run`, `prompt`, `catch`, `recover`, `match`, `if`, `log`, `fail`, `return`, `send`, `run async`) are detailed in the **Steps** section below.
+Step semantics (`ensure`, `run`, `prompt`, `catch`, `recover`, `match`, `if`, `for`, `log`, `fail`, `return`, `send`, `run async`) are detailed in the **Steps** section below.
 
 **Audience:** Agents that produce or edit `.jh` files.
 
@@ -41,7 +41,7 @@ Step semantics (`ensure`, `run`, `prompt`, `catch`, `recover`, `match`, `if`, `l
 Use this loop whenever you add or change Jaiph workflows so failures surface before work is handed back. When the repo defines a **`workflow default` entrypoint** (often `.jaiph/main.jh`) that wires preflight → implementation → verification, use **`jaiph run`** on that file for end-to-end delivery after the narrower checks below pass.
 
 1. **Preflight** — Run the project’s readiness checks if they exist (often `jaiph run .jaiph/readiness.jh` or a named preflight workflow). When the repo ships native tests (`*.test.jh`), run `jaiph test` before large edits when practical.
-2. **Implement** — Edit `.jh` modules using only constructs described in [Grammar](grammar.md); keep managed-call rules (`ensure` for rules, `run` for workflows and scripts); keep bash inside **`script`** bodies only (no raw shell in workflow/rule bodies).
+2. **Implement** — Edit `.jh` modules using only constructs described in [Grammar](grammar.md); keep managed-call rules (`ensure` for rules, `run` for workflows and scripts); put multi-line or reusable bash in **`script`** definitions (rules **never** allow raw shell lines — use `run` to a script; workflows may use optional inline shell where the grammar allows, but prefer `script` + `run` for anything non-trivial — see [Grammar — Language concepts](grammar.md#language-concepts)).
 3. **Format** — Run `jaiph format <file.jh ...>` on all authored or modified `.jh` files before committing. This normalizes whitespace, indentation, and top-level ordering (imports, config, and channels hoisted to the top; everything else kept in source order). Use `jaiph format --check <file.jh ...>` to verify formatting without writing (non-zero exit on drift — useful in CI).
 4. **Compile check** — Run `jaiph compile <file-or-dir>` on the paths you touched (or `jaiph compile --json …` in automation). Same `validateReferences` checks as before a run, without executing workflows or writing `scripts/` ([Architecture](architecture.md)). With a **directory** argument, only non-test `*.jh` files are used as entrypoints (`*.test.jh` is skipped); pass a test file path explicitly to validate it.
 5. **Verify** — Run `jaiph test` (whole workspace or a focused path) and any verification workflow the repo defines (commonly `jaiph run .jaiph/verification.jh`). Fix failures you introduce.
@@ -97,7 +97,7 @@ Prefer composable modules over one large file.
 - **Module-scoped variables:** `local name = value` or `const name = value` (same value forms). Prefer **`const`** for new files. Values can be single-line `"..."` strings, triple-quoted `"""..."""` multiline strings, or bare tokens. A double-quoted string that spans multiple lines is rejected — use `"""..."""` instead. Accessible as `${name}` inside orchestration strings in the same module. Names share the unified namespace with channels, rules, workflows, and scripts — duplicates are `E_PARSE`. Not exportable; module-scoped only.
 - **Steps:**
   - **ensure** — `ensure ref()` or `ensure ref(args…)` runs a rule (local or `alias.rule_name`). **Parentheses are required on every call site**, including zero-argument calls (`ensure check()`, not bare `ensure check`). Arguments are comma-separated inside `()`. **Bare identifier arguments** are supported and preferred (when valid): `ensure check(status)` is equivalent to `ensure check("${status}")` — the identifier must reference a known variable (`const`, capture, or named parameter); unknown names fail with `E_VALIDATE`. **Standalone `"${identifier}"` in call arguments is rejected** — use the bare form instead. Quoted strings with extra text (e.g. `"prefix_${name}"`) stay valid. Jaiph keywords cannot be used as bare identifiers. Optionally `ensure ref(…) catch (<name>) <body>`: the recovery body runs **once** on failure (no built-in retry on `ensure` — use `run … recover` for loops). The binding receives merged stdout+stderr from the failed rule. Full output also lives in **`.out` / `.err`** artifacts. Works in workflows and rules.
-  - **run** — `run ref()` or `run ref(args…)` runs a workflow or script (local or `alias.name`). Same **required `()` on every call site** as `ensure`, including zero args (`run setup()`). In a **workflow**, the target may be another workflow or a script; in a **rule**, the target must be a **script** only (`E_VALIDATE` if you name a workflow). **`run` does not forward CLI positional args implicitly** — the entry workflow binds them into named params and must pass values explicitly into callees. **Bare identifier arguments** follow the same rules as `ensure` when applicable. **Nested managed calls inside argument lists must use keywords:** `run foo(run bar())`, `run foo(ensure check())`; bare `run foo(bar())`/`run foo(\`...\`())` forms are rejected. Optionally `catch (<name>)` (runs once on failure, mutually exclusive with `recover`) or `recover (<name>)` (repair-and-retry up to **`run.recover_limit`**, module-level only). **`catch` / `recover` on `run`** are allowed in workflows and rules (rules: callee must remain a script). Also **inline scripts**: `` run `body`(args) `` or `` run ```lang...body...```(args) `` — see Scripts above.
+  - **run** — `run ref()` or `run ref(args…)` runs a workflow or script (local or `alias.name`). Same **required `()` on every call site** as `ensure`, including zero args (`run setup()`). In a **workflow**, the target may be another workflow or a script; in a **rule**, the target must be a **script** only (`E_VALIDATE` if you name a workflow). **`run` does not forward CLI positional args implicitly** — the entry workflow binds them into named params and must pass values explicitly into callees. **Bare identifier arguments** follow the same rules as `ensure` when applicable. **Nested managed calls inside argument lists must use keywords:** `run foo(run bar())`, `run foo(ensure check())`; bare `run foo(bar())`/`run foo(\`...\`())` forms are rejected. Optionally `catch (<name>)` (runs once on failure, mutually exclusive with `recover`) or `recover (<name>)` (repair-and-retry loop; attempt cap is **`run.recover_limit`** from the **file’s top-level** `config { … }`, default **10** — the runtime does not apply this setting from a workflow’s inner `config` block). **`catch` / `recover` on `run`** are allowed in workflows and rules (rules: callee must remain a script). Also **inline scripts**: `` run `body`(args) `` or `` run ```lang...body...```(args) `` — see Scripts above.
   - **log** — `log "message"` writes the expanded message to **stdout** and emits a **`LOG`** event; the CLI shows it in the progress tree at the current depth. Double-quoted string; `${identifier}` interpolation works at runtime. For multiline messages, use triple quotes: `log """..."""`. **Bare identifier form:** `log foo` (no quotes) expands to `log "${foo}"` — the variable's value is logged. Works with `const`, capture, and named parameters. **Inline capture interpolation** is also supported: `${run ref([args])}` and `${ensure ref([args])}` execute a managed call and inline the result (e.g. `log "Got: ${run greet()}"`). Nested inline captures are rejected. **`LOG`** events and `run_summary.jsonl` store the **same** message string (JSON-escaped for the payload). No spinner, no timing — a static annotation. See [CLI Reference](cli.md) for tree formatting. Useful for marking workflow phases (e.g. `log "Starting analysis phase"`).
   - **logerr** — `logerr "message"` is identical to `log` except the message goes to **stderr** and the event type is **`LOGERR`**. In the progress tree, `logerr` lines use a red `!` instead of the dim `ℹ` used by `log`. Same quoting, interpolation, bare identifier, and triple-quote rules as `log` (e.g. `logerr err_msg`, `logerr """..."""`).
   - **Send** — After `<-`, use a **double-quoted literal**, **triple-quoted block** (`channel <- """..."""`), **`${var}`**, or **`run ref([args])`**. An explicit RHS is always required — bare `channel <-` (without a value) is invalid. Raw shell on the RHS is rejected — use `const x = run helper()` then `channel <- "${x}"`, or `channel <- run fmt_fn()`. Combining capture and send (`name = channel <- …`) is `E_PARSE`. See [Inbox & Dispatch](inbox.md).
@@ -108,6 +108,7 @@ Prefer composable modules over one large file.
   - **run async** — `run async ref([args...])` starts a workflow or script concurrently and returns a **`Handle<T>`**. Capture is supported: `const h = run async ref()`. The handle resolves on first non-passthrough read (string interpolation, passing as arg to `run`, comparison, conditional, match subject). Passthrough (initial capture, re-assignment) does not force resolution. Unresolved handles are implicitly joined at workflow exit. `recover` (retry loop) and `catch` (single-shot) composition work with `run async`: `run async foo() recover(err) { … }`. Workflows only — rejected in rules.
   - **match** — `match var { "literal" => …, /regex/ => …, _ => … }` pattern-matches on a string value. The subject is always a bare identifier (no `$` or `${}`). Arms are tested top-to-bottom; the first match wins. Patterns: double-quoted string literal (exact match), `/regex/` (regex match), or `_` (wildcard — exactly one required). Usable as a statement, as an expression (`const x = match var { … }`), or with `return` (`return match var { … }`). Using `$var` or `${var}` as the match subject is a parse error. Allowed in both workflows and rules. See [Grammar](grammar.md#match).
   - **if** — `if var == "value" { … }` or `if var =~ /pattern/ { … }`. Subject is a bare identifier. Operators: `==` (exact string equality), `!=` (inequality), `=~` (regex match), `!~` (regex non-match). Operand is a `"string"` for `==`/`!=` or `/regex/` for `=~`/`!~`. Body is a brace block of valid workflow/rule steps. No `else` branch — use `match` for exhaustive value branching. `if` is a statement (no value production; cannot use with `const` or `return`). Allowed in both workflows and rules.
+  - **for** — `for iterVar in sourceVar { … }` runs the body once per **line** of the string bound to `sourceVar` (newline-separated text, e.g. from `const`/`prompt`/`run` capture). Each iteration binds `iterVar` to one line (trimming rules match the runtime’s line split — a trailing empty line after a final newline is not an extra iteration). Allowed in workflows and rules. See [Grammar](grammar.md) for the formal production.
 - **Prompts:** Three body forms: (1) **single-line string** `prompt "..."` — double-quoted, single line only; (2) **identifier** `prompt myVar` — uses the value of an existing binding; (3) **triple-quoted block** `prompt """ ... """` — for multiline text, opening `"""` on the same line as `prompt`. Triple backticks (`` ``` ``) in prompt context are rejected with guidance — they are reserved for scripts. Multiline double-quoted strings are rejected — use a triple-quoted block instead. All forms support `${identifier}` interpolation (`${varName}`, `${paramName}`). **Inline capture interpolation** is also supported: `${run ref([args])}` and `${ensure ref([args])}` inside the prompt string or triple-quoted body (e.g. `prompt "Fix: ${ensure get_diagnostics()}"`). Nested inline captures are rejected. Bare `$varName` is not valid in orchestration strings. `$(...)` and `${var:-fallback}` are rejected. Capture: `const name = prompt "..."`, `const x = prompt myVar`, `const y = prompt """ ... """`. Optional **typed prompt:** `const name = prompt "..." returns "{ field: type, ... }"` or `const name = prompt myVar returns "..."` (flat schema; types `string`, `number`, `boolean`) validates the agent's JSON and sets `${name}` plus per-field variables accessible via **dot notation** — `${name.field}`. Dot notation is validated at compile time: the variable must be a typed prompt capture and the field must exist in the schema. **Orchestration bindings are strings:** typed fields are coerced with `String()` after JSON validation, so e.g. a numeric field is still the text `"42"` in scope. See [Grammar](grammar.md).
 
 **Quick reference examples:**
@@ -140,6 +141,15 @@ if mode =~ /^debug/ {
   log "Debug mode enabled"
 }
 
+# for — iterate over lines of a string variable
+const paths = """
+docs/a.md
+docs/b.md
+"""
+for path in paths {
+  log "${path}"
+}
+
 # typed prompt — structured JSON with dot-notation field access
 const result = prompt "Analyze this code" returns "{ type: string, risk: string }"
 log "Type: ${result.type}, Risk: ${result.risk}"
@@ -185,6 +195,7 @@ Test files use the `*.test.jh` suffix and contain `test "name" { ... }` blocks.
 **Available mocks:**
 
 - `mock prompt "fixed response"` — queues a fixed response for the next `prompt` call (multiple queue in order).
+- `mock prompt responseVar` — uses the string already bound as `responseVar` (e.g. a `const` earlier in the block) as the next response.
 - `mock prompt { /pattern/ => "response", _ => "default" }` — content-based dispatch.
 - `mock workflow alias.name() { return "stubbed" }` — replaces a workflow body.
 - `mock rule alias.name() { return "ok" }` — replaces a rule body.
@@ -235,6 +246,7 @@ Include a compile check and, when the repository has native tests (`*.test.jh`),
 ```bash
 jaiph format .jaiph/*.jh
 jaiph compile .jaiph
+# Omit the next line when the repo has no *.test.jh files (workspace discovery exits 1 with "no *.test.jh files found").
 jaiph test
 jaiph run .jaiph/main.jh "implement feature X"
 # Or run verification only:
diff --git a/docs/language.md b/docs/language.md
index 228ed583..8d6c789d 100644
--- a/docs/language.md
+++ b/docs/language.md
@@ -9,7 +9,7 @@ redirect_from:
 
 Workflow systems usually need two layers: a **host language** that sequences work, handles failures, and talks to tools, and **task code** (shell, Python, and so on) that does the mechanical steps. Jaiph’s `.jh` modules are that host layer: they wire prompts, scripts, validation **rules**, and **channels** into pipelines you can run from the CLI or CI.
 
-Under the hood, the **TypeScript CLI** parses modules, runs **`validateReferences`** while emitting script files (`emitScriptsForModule` / `buildScripts`), then starts a **Node workflow runtime** that walks the same AST in process — there is no separate workflow shell. The runtime’s `buildRuntimeGraph` pass loads imports with the parser only; compile-time checks live in the transpile path, not in the graph loader. For repository layout, event contracts, and diagrams, see [Architecture](architecture.md).
+Under the hood, the **TypeScript CLI** parses modules, runs **`validateReferences`** while emitting script files (`emitScriptsForModule` / `buildScripts`), then starts a **Node workflow runtime** that walks the same AST in process — there is no separate workflow shell. The **`jaiph compile`** command walks the same import closure with **`validateReferences`** only — it **does not** emit `scripts/`, **invoke** **`buildRuntimeGraph`**, or spawn the workflow runner (`src/cli/commands/compile.ts`). The runtime’s **`buildRuntimeGraph`** pass loads imports with the parser only; compile-time checks live in the transpile path, not in the graph loader. For repository layout, event contracts, and diagrams, see [Architecture](architecture.md).
 
 This page is the practical reference for language primitives — syntax, steps, and runtime behavior at the author’s eye level. For lexical/syntax tables and edge-case grammar, see [Grammar](grammar.md). Test files (`*.test.jh`) are a dialect documented in [Testing](testing.md).
 
@@ -148,7 +148,9 @@ world
 """
 ```
 
-Values can be double-quoted strings (single-line), triple-quoted strings (multiline `"""..."""`), or bare tokens. Declaration order matters — `${name}` only expands variables already bound above. Module constants are **not** passed to script subprocesses; use arguments or shared libraries instead.
+Values can be double-quoted strings (single-line), triple-quoted strings (multiline `"""..."""`), or a **bare** right-hand side: everything after `=` on that line becomes the stored string verbatim (including tokens that look like numbers, for example `const N = 42` keeps **`"42"`** as text for `${N}` — there is no separate numeric type).
+
+Declaration order matters — `${name}` only expands variables already bound above. Module constants are **not** passed to script subprocesses; use arguments or shared libraries instead.
 
 ### Channels
 
@@ -164,7 +166,7 @@ Routes (`->`) declare which workflows receive messages sent to the channel. See
 
 ### Config
 
-Optional `config { … }` block. At **module** level it may set `agent.*`, `run.*`, `runtime.*`, and `module.*` keys (see `src/parse/metadata.ts`). A **workflow** may contain **at most one** nested `config { … }`, it must appear **before** the first step, and only **`agent.*`** and **`run.*`** are allowed there — `runtime.*` and `module.*` are rejected with `E_PARSE`.
+Optional `config { … }` block. At **module** level only the keys allowed in **`src/parse/metadata.ts`** are accepted (`agent.*`, `run.*`, `runtime.*`, `module.*` — each assignment is validated for type). For example **`agent.backend`** must be **`cursor`**, **`claude`**, or **`codex`**. A **workflow** may contain **at most one** nested `config { … }`, it must appear **before** the first step, and only **`agent.*`** and **`run.*`** are allowed there — `runtime.*` and `module.*` are rejected with `E_PARSE`.
 
 ```jaiph
 config {
@@ -174,7 +176,7 @@ config {
 }
 ```
 
-See [Configuration](configuration.md) for all available keys and precedence rules.
+See [Configuration](configuration.md) for key semantics and precedence rules.
 
 ## Definitions
 
@@ -224,7 +226,7 @@ rule gate(path) {
 }
 ```
 
-Rules are more restricted than workflows: the compiler rejects `prompt`, `send`, and `run async` in rule bodies, and `run` may only target **scripts** (never workflows or other rules via `run` — use `ensure` for rules). Rule bodies also reject `const … = prompt`. Those restrictions are **static** (see `validateReferences` in `src/transpile/validate.ts`). At runtime, `run` inside a rule still launches a normal managed script subprocess with the same **environment model** as workflow scripts (see [Script isolation](#script-isolation)); scripts can perform side effects — the language simply keeps orchestration-heavy steps out of rules.
+Rules are more restricted than workflows: the compiler rejects `prompt`, `send`, and `run async` in rule bodies, and `run` may only target **scripts** (never workflows or other rules via `run` — use `ensure` for rules). Rule bodies also reject `const … = prompt`. Otherwise rule bodies share the same structured step set as workflows for control flow (**`match`**, **`if`**, **`for … in …`**), captures, logging, **`return`**, and failure handling (**`catch`** / **`recover`** on **`run`**). Those restrictions are **static** (see `validateReferences` in `src/transpile/validate.ts`). At runtime, `run` inside a rule still launches a normal managed script subprocess with the same **environment model** as workflow scripts (see [Script isolation](#script-isolation)); scripts can perform side effects — the language simply keeps orchestration-heavy steps out of rules.
 
 `catch` and **`recover`** on **`run`** are allowed in rules the same as in workflows. **`recover` never attaches to `ensure`** — only `run` steps support `recover`.
 
@@ -320,7 +322,7 @@ run lib.build_project(task)
 const output = run transform()
 ```
 
-**Capture:** For a workflow, captures the explicit `return` value. For a script, captures stdout.
+**Capture:** For a workflow, captures the explicit `return` value. For a script or inline script, captures **trimmed** stdout on success (`node-workflow-runtime.ts` treats the emitted stdout string with `.trim()` when producing the capture value).
 
 ### `run async` — Concurrent Execution with Handles
 
@@ -328,7 +330,7 @@ const output = run transform()
 
 ```jaiph
 workflow default() {
-  # Fire-and-forget style (handle created but not captured)
+  # Start work without storing a binding — still tracked until this step list ends
   run async lib.task_a()
 
   # Capture the handle for later use
@@ -339,9 +341,13 @@ workflow default() {
 }
 ```
 
-**Handle resolution:** The handle resolves on first non-passthrough read — string interpolation, passing as argument to `run`, comparison, conditional branching, or match subject. Passthrough operations (initial capture into `const`, re-assignment) do not force resolution.
+**Handle resolution:** The handle resolves on first **non-passthrough** read — string interpolation, passing as a bare argument to `run` / `ensure` (rewritten to use `${name}`), comparison / regex tests in **`if`**, **`match`** on the handle variable, **`prompt`** bodies that mention `${h}`, **`send`** payloads that interpolate `${h}`, and similar paths that scan orchestration strings (full table in [Spec: Async Handles](spec-async-handles.md)).
+
+**Passthrough:** `const h = run async foo()` binds the opaque handle token **without awaiting** `foo()` on that line. A bare `run async foo()` also performs no handle read — it still registers the branch for joining.
 
-**Implicit join:** When a workflow scope exits, the runtime implicitly joins all remaining unresolved handles created in that scope. This is not an error — it preserves backward compatibility with the pre-handle `run async` model.
+**Important:** Workflow **`const`** can use a bare identifier RHS (for example `const copy = h`); that desugars to string interpolation **`"${h}"`** in `parse/const-rhs.ts`, which **does** resolve a handle — unlike the initial async capture alone.
+
+**Implicit join:** When the **`executeSteps`** scope that created handles **finishes** (for example end of an `if` body, **`for`** body, or the outer workflow step list), the runtime awaits **every** `run async` handle registered there — including handles that were never read. Nested blocks join **their** handles before control continues outward. Failures aggregate like a synchronous step failure. This preserves backward compatibility with the pre-handle concurrency model while still allowing overlap until a read or a scope boundary forces ordering ([Spec: Async Handles](spec-async-handles.md#implicit-join)).
 
 **`recover` composition:** `recover` works with `run async` to provide retry-loop semantics on the async branch:
 
@@ -474,7 +480,9 @@ const result = prompt "Analyze this code" returns "{ type: string, risk: string
 log "Type: ${result.type}, Risk: ${result.risk}"
 ```
 
-Schema supports flat fields with types `string`, `number`, `boolean`. Fields are accessible via dot notation (`${result.type}`). The compiler validates field references at compile time.
+The schema is a flat comma-separated `{ field: type, … }` fragment — only `string`, `number`, and `boolean`; no nested objects or union syntax (`validatePromptReturnsSchema` in `src/transpile/validate-prompt-schema.ts`). Fields are exposed as dot accessors (`${result.type}`); the compiler checks those references against the declared fields.
+
+Prompts using `returns` must be captured (`const … = prompt … returns …`). A `returns` prompt without capture is rejected at compile time.
 
 Prompts are not allowed in rules.
 
@@ -760,8 +768,8 @@ Every step produces three outputs: status, value, and logs.
 |---|---|---|---|
 | `ensure rule` | exit code | explicit `return` value | artifacts |
 | `run workflow` | exit code | explicit `return` value | artifacts |
-| `run script` | exit code | stdout | artifacts |
-| `run` inline | exit code | stdout | artifacts |
+| `run script` | exit code | trimmed stdout | artifacts |
+| `run` inline | exit code | trimmed stdout | artifacts |
 | `prompt` | exit code | final assistant answer | artifacts |
 | `log` / `logerr` | always 0 | — | event stream |
 | `fail` | non-zero (abort) | — | stderr |
diff --git a/docs/libraries.md b/docs/libraries.md
index 5b81f5f0..4e65e296 100644
--- a/docs/libraries.md
+++ b/docs/libraries.md
@@ -7,24 +7,38 @@ redirect_from:
 
 # Libraries
 
-Workflow systems usually want **shared modules**: reusable rules, scripts, and small packaged workflows. Jaiph does not ship a global library path on the machine. Instead, everything is **scoped to a workspace**: first-party and third-party modules live under disk paths that the compiler resolves from your entry file and **workspace root**.
+## Why workspaces and `.jaiph/libs`
 
-This page covers **project-scoped libraries** under `<workspace>/.jaiph/libs/`, how `import` resolves into that tree, how **`jaiph install`** populates it from git, and the first-party **`jaiphlang/`** helpers maintained in this repository. For validator behavior and `resolveImportPath`, see [Architecture — Core components](architecture.md#core-components). For exact grammar and export rules, see [Grammar — Imports and Exports](grammar.md#imports-and-exports).
+Workflow authoring usually needs **shared modules**: reusable rules, scripts, and small packaged workflows people can version and reuse across projects.
+
+Jaiph avoids a machine-wide library path: resolution is anchored to a **workspace** (detected directory root; see below). Modules you own live next to your entry `.jh`; **third-party clones** conventionally live under **`<workspace>/.jaiph/libs/<name>/`**, wired up by **`jaiph install`**. Imports that look like **`lib-name/rest/of/path`** attach to those directories when relative resolution misses.
+
+This page covers that layout, **`import`** resolution (**`resolveImportPath`** in `src/transpile/resolve.ts`), **`jaiph install`**, and the first-party **`jaiphlang/`** helpers shipped in **this repo** under `.jaiph/libs/jaiphlang/`. Validator behavior crosses into [Architecture — Core components](architecture.md#core-components). Grammar for import/export syntax lives in [Grammar — Imports and Exports](grammar.md#imports-and-exports).
 
 ## How imports resolve
 
-Resolution is implemented in `resolveImportPath` (`src/transpile/resolve.ts`). Order:
+Resolution runs in **`resolveImportPath`** — order:
+
+1. **Relative to the importing file** — e.g. `import "./foo"`, `import "../lib/util"`. Paths without a `.jh` suffix get **`.jh`** appended automatically.
+2. **Library fallback** — only if step 1’s candidate path **does not exist on disk**, **`workspaceRoot`** is set, **and** the import string **`contains`** a **`/`**. The first `/` splits **`lib-name`** from **`rest`**, then the compiler looks for **`<workspace>/.jaiph/libs/<lib-name>/<rest>.jh`** (same extension defaulting).
+
+Implications:
 
-1. **Relative to the importing file** — `import "./foo"`, `import "../lib/util"` (`.jh` appended when the path omits the extension).
-2. **Library fallback** — only if step 1 did not find an existing file **and** the import string contains `/`. The path is split at the first `/` into `<lib-name>` and `<rest>`, then the compiler looks for  
-   `<workspace>/.jaiph/libs/<lib-name>/<rest>.jh`  
-   (with the same `.jh` defaulting rule as above).
+- **Imports without `/`** — e.g. **`import "submod"`** — only relative-to-file lookup is attempted; there is **no** library fallback under `.jaiph/libs/` even if a matching folder name exists.
+- **`jaiph compile`** runs the same **`validateReferences`** check as **`jaiph run`** but does not emit **`scripts/`** or invoke **`buildRuntimeGraph()`** ([Architecture — Summary](architecture.md#summary)).
 
-The **workspace root** threaded into **`validateReferences`** / **`emitScriptsForModule`** is whatever root the invoking command computed — for example **`jaiph run`** passes `detectWorkspaceRoot(dirname(entry.jh))`, while **`jaiph install`** uses `detectWorkspaceRoot(process.cwd())`. Detection walks upward from that starting path until `.jaiph` or `.git` (with the temp-directory guards summarized in [CLI — `jaiph install`](cli.md#jaiph-install)). **`jaiph compile`** applies the same resolver over each module’s import closure without emitting scripts (see [Architecture](architecture.md)).
+**Workspace root:** whatever the invoking CLI path passes into **`emitScriptsForModule`** / **`validateReferences`**:
 
-The first segment of a library import is the directory name under `.jaiph/libs/` (for example `queue-lib` in `import "queue-lib/queue"`). If a module declares any `export`, only exported names are visible through the alias — same rule as local modules ([Grammar — Imports and Exports](grammar.md#imports-and-exports)).
+- **`jaiph run`** and **`jaiph test`** on an explicit **`*.jh` / `*.test.jh`** file use **`detectWorkspaceRoot(dirname(entry))`** (same predicate for both commands).
+- **`jaiph test`** with **no** file argument discovers tests under **`detectWorkspaceRoot(process.cwd())`** (`src/cli/commands/test.ts`).
+- **`jaiph install`** uses **`detectWorkspaceRoot(process.cwd())`**.
+- **`jaiph compile`** uses **`detectWorkspaceRoot(dirname(file))`** per validated module by default, or **`--workspace <dir>`** to pin one root for the whole command (`src/cli/commands/compile.ts`).
 
-**Limitation:** `import script "…"` paths resolve **only** relative to the importing file; there is no library fallback for script imports ([Grammar](grammar.md#imports-and-exports)).
+Walk-up rules (`.jaiph` / `.git` markers, temp-directory guards) match [CLI — `jaiph install`](cli.md#jaiph-install).
+
+**Export visibility:** if an imported module declares **any** `export`, only those names are valid through the alias; otherwise **every** top-level workflow, rule, and script in that file is reachable ([Architecture — Core components](architecture.md#core-components)). First-party **`jaiphlang/*`** modules typically use explicit `export` lines; **`jaiphlang/git`** is the odd one out (see below).
+
+**Limitation:** **`import script "…"`** paths are validated with **`resolveScriptImportPath`**: **only** relative to the importing file’s directory — **no** workspace library fallback (`src/transpile/validate.ts`).
 
 ## Installing third-party libraries
 
@@ -32,20 +46,20 @@ The first segment of a library import is the directory name under `.jaiph/libs/`
 # Clone into .jaiph/libs/<name>/ (shallow git clone) and update the lockfile
 jaiph install https://github.com/you/queue-lib.git
 
-# Pin a branch or tag (typical HTTPS shape: …/.git@ref)
+# Pin a branch or tag (common shape: …/.git@ref — passed to git clone --branch)
 jaiph install https://github.com/you/queue-lib.git@v1.0
 
 # Restore all libraries from the lockfile (e.g. after git clone or in CI)
 jaiph install
 ```
 
-`jaiph install` writes `.jaiph/libs.lock` under the workspace root. Commit the lockfile; add `.jaiph/libs/` to `.gitignore` if you do not want vendored clones in version control. If `.jaiph/libs/<name>/` already exists, the clone is skipped unless you pass **`--force`** (see [CLI — `jaiph install`](cli.md#jaiph-install) for URL/`@ref` parsing and lockfile JSON).
+`jaiph install` writes **`.jaiph/libs.lock`** under the workspace root. Commit the lockfile; add **`.jaiph/libs/`** to `.gitignore` if you do not want vendored clones in version control. If **`.jaiph/libs/<name>/`** already exists, the clone is skipped unless you pass **`--force`** (URL / `@ref` parsing: [CLI — `jaiph install`](cli.md#jaiph-install)).
 
-The clone directory name is derived from the URL (last path segment, `.git` stripped), so imports use that segment as `<lib-name>`.
+The clone directory name is **`deriveLibName(url)`** (last path segment, **`.git`** stripped), so imports use that segment as **`lib-name`**.
 
 ## Example: `import` from a clone under `.jaiph/libs/`
 
-After `jaiph install`, paths like `queue-lib/queue` resolve like any other library layout. Exported names come from that repository. Below assumes `.jaiph/libs/jaiphlang/` exists (copy from this repo or install your own package named `jaiphlang`).
+After `jaiph install`, paths like **`queue-lib/queue`** resolve like any other library layout. Below assumes **`.jaiph/libs/jaiphlang/`** exists (copy from this repo or install a repo whose root name is **`jaiphlang`**).
 
 ```jaiph
 import "jaiphlang/queue" as q
@@ -59,26 +73,26 @@ workflow default() {
 
 ## The `jaiphlang/` standard libraries
 
-The `jaiphlang/` prefix is a **naming convention** for first-party helper modules shipped **in this repository** under `.jaiph/libs/jaiphlang/`. They are not bundled inside the npm `jaiph` package. Copy that directory into your workspace as `.jaiph/libs/jaiphlang/` (or track it in git) so `import "jaiphlang/…"` resolves. They use the same `import` / `export workflow` / `export rule` pattern as any other library.
+The **`jaiphlang/`** prefix is a **naming convention** for first-party helper modules maintained **in this repository** under **`.jaiph/libs/jaiphlang/`**. They are **not** bundled inside the published npm **`jaiph`** package; copy that tree into your workspace or track it in git so **`import "jaiphlang/…"`** resolves. They use the same **`import` / `export workflow` / `export rule`** pattern as any other library (except **`git`**, see below).
 
 ### `jaiphlang/queue` — `QUEUE.md` task queue
 
-Manages a markdown task file **`QUEUE.md`** at `${JAIPH_WORKSPACE:-.}` (`queue.jh` + `queue.py`). Sections use `##` headers; tags are `#hashtags` on the header line (e.g. `## My task #dev-ready`). **`python3`** must be available on `PATH` when steps run the imported `queue.py` script.
+Manages a markdown task file **`QUEUE.md`** at **`${JAIPH_WORKSPACE:-.}`** (`queue.jh` + `queue.py`). Sections use **`##`** headers; tags are **`#hashtags`** on the header line (e.g. **`## My task #dev-ready`**). **`python3`** must be on **`PATH`** when steps run the imported **`queue.py`** script.
 
-| Export | Kind | Description |
+| Symbol | Kind | Description |
 |--------|------|-------------|
-| `get_first_task()` | workflow | Returns the first task block (header + body). |
+| `get_first_task()` | workflow | Returns the first task block (header + body) via **`queue("get")`**. |
 | `next_task(tag)` | workflow | Returns the first task whose header carries the given tag (tag name without `#`). |
 | `get_task_by_header(header)` | workflow | Returns a task by title; tags stripped for matching. |
-| `get_all_task_headers()` | workflow | Newline-separated task titles (no `##` prefix); all tasks, no tag filter at the Jaiph layer. |
-| `mark_task_dev_ready(header)` | workflow | Adds `#dev-ready` to the matching header. |
+| `get_all_task_headers()` | workflow | Newline-separated task titles (no `##` prefix); calls **`queue("headers")`** with no extra args, so **all** tasks are listed (the Python **`headers`** subcommand accepts an optional tag when run directly from the CLI, but this workflow does not expose that). |
+| `mark_task_dev_ready(header)` | workflow | Adds **`#dev-ready`** to the matching header. |
 | `remove_completed_task(header)` | workflow | Removes the task with that title. |
 | `set_task_description_from_file(header, bodyPath)` | workflow | Replaces body text from a UTF-8 file; header unchanged. |
 | `has_tasks()` | rule | Passes if the queue has at least one task. |
-| `task_is_dev_ready(task)` | rule | Passes if the task text has `#dev-ready` on the header line. |
-| `all_dev_ready()` | rule | Passes if every task has `#dev-ready`. |
+| `task_is_dev_ready(task)` | rule | Passes if the task text has **`#dev-ready`** on the header line. |
+| `all_dev_ready()` | rule | Passes if every task has **`#dev-ready`**. |
 
-The module also defines a `default` workflow for **direct CLI** use (arguments pass through to the Python helper). Examples:
+The module also defines a **`default`** workflow for **direct CLI** use (arguments pass through to the Python helper). Examples:
 
 ```bash
 jaiph .jaiph/libs/jaiphlang/queue.jh headers
@@ -86,11 +100,9 @@ jaiph .jaiph/libs/jaiphlang/queue.jh get dev-ready
 jaiph .jaiph/libs/jaiphlang/queue.jh json
 ```
 
-The Python helper’s `headers` command accepts an optional tag when invoked directly; the exported Jaiph workflow `get_all_task_headers()` does not take parameters and always lists every title.
-
 ### `jaiphlang/artifacts` — publishing files out of the sandbox
 
-Copies files from the **workspace** (or sandbox overlay) into the run’s `artifacts/` tree so they remain on the host after Docker teardown or process exit. The runtime sets **`JAIPH_ARTIFACTS_DIR`** to the writable directory for the current run. See [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) and [Sandboxing](sandboxing.md) for the read-only workspace contract in Docker.
+Copies files from the **workspace** (or sandbox overlay) into the run’s **`artifacts/`** tree so they remain on the host after Docker teardown or process exit. The runtime sets **`JAIPH_ARTIFACTS_DIR`** to the writable directory for the current run. See [Architecture — Durable artifact layout](architecture.md#durable-artifact-layout) and [Sandboxing](sandboxing.md) for the read-only workspace contract in Docker.
 
 ```jaiph
 import "jaiphlang/artifacts" as artifacts
@@ -108,23 +120,25 @@ workflow default() {
 }
 ```
 
-**Exported workflows**
+**Exported workflow**
 
 | Workflow | Description |
 |----------|-------------|
-| `save(paths)` | `paths` is a single file path or a **newline-separated** list of file paths. Blank lines are ignored. Each file is copied to `${JAIPH_ARTIFACTS_DIR}/…` preserving relative layout (`./` stripped; absolute sources use `basename` only). Returns absolute destination path(s), one per line, in order. Exits with failure if the list is empty after trimming, any path is missing, or `JAIPH_ARTIFACTS_DIR` is unset. |
+| `save(paths)` | **`paths`** is a single file path or a **newline-separated** list of file paths. Blank lines are ignored. Each file is copied to **`${JAIPH_ARTIFACTS_DIR}/…`** preserving relative layout (`./` stripped; absolute sources use **`basename`** only). Returns absolute destination path(s), one per line, in order. Exits with failure if the list is empty after trimming, any path is missing, or **`JAIPH_ARTIFACTS_DIR`** is unset. |
 
 ### `jaiphlang/git` — git hygiene helpers and an example commit flow
 
-Small **exported rules** around `git status` / `git rev-parse`, plus **`commit(task)`** / **`default(task)`** workflows that drive an agent-backed prompt to stage and commit changes and write a patch file. This module is **opinionated** (Cursor agent defaults in a `config` block); read `.jaiph/libs/jaiphlang/git.jh` before reusing or trimming it.
+**`git.jh`** defines rules and workflows **without** **`export`** keywords. With **zero** `export` lines, the compiler does **not** hide any top-level names: importers may reference **every** **`rule`** and **`workflow`** in that file. Prefer explicit **`export`** in libraries you publish so only a stable surface is reachable.
+
+The module mixes small rules around **`git status`** / **`git rev-parse`** with **`commit(task)`** / **`default(task)`** workflows that drive a **`prompt`** to stage/commit and write **`git format-patch -1 HEAD --stdout`** to a **`*.patch`** path. This file is **opinionated** (default **`config`** block targets the Cursor agent); read **`.jaiph/libs/jaiphlang/git.jh`** before trimming or reusing.
 
-| Export | Kind | Description |
+| Symbol | Kind | Description |
 |--------|------|-------------|
-| `in_git_repo()` | rule | Passes when `git rev-parse --is-inside-work-tree` succeeds (after marking the workspace as a safe directory). |
-| `branch_clean()` | rule | Passes when `git status --porcelain` is empty. |
+| `in_git_repo()` | rule | Passes when **`git rev-parse --is-inside-work-tree`** succeeds (after marking the workspace as a safe directory). |
+| `branch_clean()` | rule | Passes when **`git status --porcelain`** is empty. |
 | `has_changes()` | rule | Passes when there are porcelain changes (fails on a clean tree). |
-| `is_clean()` | rule | Ensures `in_git_repo()` and `branch_clean()`. |
-| `commit(task)` | workflow | Ensures repo + changes, runs a structured `prompt`, writes `git format-patch` output to a `.patch` path, returns that path. |
-| `default(task)` | workflow | Delegates to `commit(task)`. |
+| `is_clean()` | rule | Passes when **`in_git_repo()`** **and** **`branch_clean()`** both pass (their **`ensure`** calls are inlined in this rule). |
+| `commit(task)` | workflow | Ensures repo + changes, runs **`prompt`**, writes patch file, returns path. |
+| `default(task)` | workflow | Runs **`commit(task)`** (same **`return`**). |
 
-Use these as patterns for your own libraries: thin `script` wrappers, composable `rule`s, and workflows that call them.
+Use **`jaiphlang`** modules as patterns for your own libs: thin **`script`** wrappers, composable **`rule`** constructs, and workflows built on both.
diff --git a/docs/sandboxing.md b/docs/sandboxing.md
index da4a9e92..9b9ba3b5 100644
--- a/docs/sandboxing.md
+++ b/docs/sandboxing.md
@@ -15,7 +15,7 @@ Both local and Docker runs stream `__JAIPH_EVENT__` on **stderr** only; [Hooks](
 
 ## Rules: structured validation, not mutation
 
-Rules restrict which step types are allowed in their body — enforced at **compile time** in `validateReferences` (`src/transpile/validate.ts`), not by an OS sandbox. The permitted set matches [Grammar — Language concepts](grammar.md#language-concepts): `ensure` (other rules only), `run` (**scripts** only — not workflows), `const` (script/`ensure` captures, `match` expressions, or bash RHS — never `prompt`), `match`, `if`, `fail`, `log` / `logerr`, `return` (strings, identifiers, `return run …` / `return ensure …`, and the managed forms the grammar allows), `ensure … catch`, `run … catch`, and `run … recover`. Inline script steps and managed `log`/`logerr` from inline scripts are allowed where the grammar permits them.
+Rules restrict which step types are allowed in their body — enforced at **compile time** in `validateReferences` (`src/transpile/validate.ts`), not by an OS sandbox. The permitted set matches [Grammar — Language concepts](grammar.md#language-concepts): `ensure` (other rules only), `run` (**scripts** only — not workflows), `const` (script/`ensure` captures, `match` expressions, or bash RHS — never `prompt`), `match`, `if`, `for … in … { … }` (line iteration over a string variable), `fail`, `log` / `logerr`, `return` (strings, identifiers, `return run …` / `return ensure …`, and the managed forms the grammar allows), `ensure … catch`, `run … catch`, and `run … recover`. Inline script steps and managed `log`/`logerr` from inline scripts are allowed where the grammar permits them.
 
 Disallowed in rules: **raw shell lines** (every line must be a recognized Jaiph step — use a `script` and `run`), `prompt`, inbox **`send`** / routing, and **`run async`**. See the grammar page for the authoritative list and examples.
 
@@ -47,7 +47,7 @@ Docker sandboxing is designed to contain damage from untrusted or semi-trusted w
 
 > **Beta.** Docker sandboxing is functional but still under active development. Expect rough edges, breaking changes, and incomplete platform coverage. Feedback is welcome at <https://github.com/jaiphlang/jaiph/issues>.
 
-Docker applies to `jaiph run` only (not `jaiph test`). Enablement is **environment-driven** (see [Enabling Docker](#enabling-docker)); there is no `jaiph run --docker` flag — the CLI decides from env before spawn. When Docker is active, the entire workflow (every rule and script step) runs inside a **single** container. The container runs `jaiph run --raw <file>` using the **image’s** installed `jaiph`, not the host binary. The `--raw` flag skips the banner and progress UI in that inner process so `__JAIPH_EVENT__` JSON lines go to **stderr** unchanged for the host CLI to parse.
+Docker applies to `jaiph run` only (not `jaiph test`). Enablement is **environment-driven** (see [Enabling Docker](#enabling-docker)); there is no `jaiph run --docker` flag — the CLI decides from env before spawn. **`jaiph run --raw` on the host never starts Docker:** only interactive `jaiph run` (no `--raw` on the host) consults `JAIPH_DOCKER_ENABLED` / `JAIPH_UNSAFE` and may spawn a container — see [CLI — `jaiph run`](cli.md#jaiph-run). When Docker is active, the entire workflow (every rule and script step) runs inside a **single** container. The container runs `jaiph run --raw <file>` using the **image’s** installed `jaiph`, not the host binary. The `--raw` flag skips the banner and progress UI in that inner process so `__JAIPH_EVENT__` JSON lines go to **stderr** unchanged for the host CLI to parse.
 
 The container's `/jaiph/workspace` always *looks* writable to scripts but never mutates the host checkout. The CLI picks one of two sandbox primitives at launch time:
 
@@ -77,7 +77,7 @@ CI environments (`CI=true`) deliberately exercise the same sandbox path users do
 
 If Docker is enabled but `docker info` fails, the run exits with `E_DOCKER_NOT_FOUND` and suggests setting `JAIPH_UNSAFE=true` as an escape hatch. There is no silent fallback to local execution.
 
-> **Migration note:** `runtime.docker_enabled` in a `.jh` config block is no longer supported and produces a parse error. Use `JAIPH_DOCKER_ENABLED` or `JAIPH_UNSAFE` in the environment instead.
+> **Migration note:** `runtime.docker_enabled` is not an allowed `config` key — the parser rejects it as an unknown key (with the allowed-key list in the error). Use `JAIPH_DOCKER_ENABLED` or `JAIPH_UNSAFE` in the environment instead.
 
 ### Configuration keys
 
@@ -156,9 +156,9 @@ On **Linux**, if the host UID/GID cannot be determined (`process.getuid()` / `pr
 
 If `/dev/fuse` is missing on the host, the CLI uses **copy mode**: before launching the container it clones the workspace into `<runs-root>/.sandbox-<id>/` using `cp -cR` on macOS when clonefile works (otherwise `cp -pR` and a one-time stderr warning), or `cp -pR` on other platforms. The clone is bind-mounted rw at `/jaiph/workspace`. After the container exits — whether normally, via signal (SIGINT/SIGTERM), or due to an uncaught error — the clone is removed unless `JAIPH_DOCKER_KEEP_SANDBOX` is `1` or `true`, in which case the path is left in place for debugging.
 
-**Run artifacts** -- The host CLI mounts the resolved host runs root at `/jaiph/run:rw` inside the container. By default this is `.jaiph/runs` under the workspace; a relative `JAIPH_RUNS_DIR` is resolved under the workspace; an absolute `JAIPH_RUNS_DIR` must stay within the workspace or the run fails with `E_DOCKER_RUNS_DIR`. `JAIPH_RUNS_DIR` is set to `/jaiph/run` inside the container, so the runtime writes artifacts directly into the requested host path.
+**Run artifacts** -- The host CLI mounts the resolved host runs root at `/jaiph/run:rw` inside the container. By default this is `.jaiph/runs` under the workspace; a relative `JAIPH_RUNS_DIR` is resolved under the workspace; an absolute `JAIPH_RUNS_DIR` must stay within the workspace or the run fails with `E_DOCKER_RUNS_DIR`. `JAIPH_RUNS_DIR` is set to `/jaiph/run` inside the container, so the runtime writes artifacts directly into the requested host path. On **Linux** in **overlay** mode, the CLI best-effort `chmod`s that host run directory to mode `0777` before `docker run` so writes still work when the daemon uses user-namespace remapping and the inner workflow runs as a non-root UID.
 
-**Path remapping** {#path-remapping} -- Inside the container, the runtime records artifact paths relative to `/jaiph/run` (e.g. `/jaiph/run/2026-04-21/07-55-32-say_hello.jh/000003-script__validate_name.err`). These container-internal paths do not exist on the host. After the container exits, the host CLI remaps every container path that starts with `/jaiph/run/` to the corresponding path under the bind-mounted host runs directory (the `sandboxRunDir`). This ensures the failure footer (`Logs:`, `Summary:`, `out:`, `err:`) printed to stderr shows valid **host** paths that can be opened directly. The `run_summary.jsonl` file also records container-internal `out_file` / `err_file` values; the CLI applies the same remapping when reading these fields to locate artifact content for the "Output of failed step" excerpt. When the container meta file is inaccessible from the host (which is typical in Docker mode), the CLI discovers the run directory by scanning the bind-mounted runs directory for a `run_summary.jsonl` whose first line is a `WORKFLOW_START` event with `run_id` equal to the expected run id (the same value as `JAIPH_RUN_ID` on the host). This ties concurrent `jaiph run` invocations sharing the same runs root to distinct run directories. The net effect is that Docker and no-sandbox runs produce identical failure footers — same structure, same host-resolvable paths, same step output excerpt.
+**Path remapping** {#path-remapping} -- Inside the container, the runtime records artifact paths relative to `/jaiph/run` (e.g. `/jaiph/run/2026-04-21/07-55-32-say_hello.jh/000003-script__validate_name.err`). These container-internal paths do not exist on the host. After the container exits, the host CLI remaps every container path that starts with `/jaiph/run/` to the corresponding path under the bind-mounted host runs directory (the `sandboxRunDir`). This ensures the failure footer (`Logs:`, `Summary:`, `out:`, `err:`) printed to stderr shows valid **host** paths that can be opened directly. The `run_summary.jsonl` file also records container-internal `out_file` / `err_file` values; the CLI applies the same remapping when reading these fields to locate artifact content for the "Output of failed step" excerpt. When the container meta file is inaccessible from the host (typical in Docker mode), the CLI discovers the run directory by walking UTC date/time subdirectories of the bind-mounted runs root **newest first** until it finds a `run_summary.jsonl` whose first line is a `WORKFLOW_START` event with `run_id` equal to the expected run id (the same value as `JAIPH_RUN_ID` on the host). This stays correct when concurrent `jaiph run` invocations share the same runs root. The net effect is that Docker and no-sandbox runs produce identical failure footers — same structure, same host-resolvable paths, same step output excerpt.
 
 **Workspace immutability contract** -- Docker runs cannot directly modify the host workspace. In overlay mode the host checkout is bind-mounted read-only and writes land in the overlay upper layer (under `/tmp` inside the container) and are discarded on container exit. In copy mode the container writes to a separate host-side clone of the workspace (`<runs-root>/.sandbox-<id>/`), which is removed on container exit unless explicitly kept for debugging. In both modes the only persistence channel from a Docker run to the host is the run-artifacts directory (`/jaiph/run` → host `.jaiph/runs`). Non-Docker (local) runs are unaffected by this contract.
 
@@ -168,7 +168,7 @@ If `/dev/fuse` is missing on the host, the CLI uses **copy mode**: before launch
 
 **Timeout** -- When the effective timeout (from `JAIPH_DOCKER_TIMEOUT` or `runtime.docker_timeout_seconds`, after the merge in [Configuration keys](#configuration-keys)) is greater than zero, the CLI arms a timer on the spawned `docker` child; on overrun it sends `SIGTERM`, then `SIGKILL` after a 5-second grace period. The failure message includes `E_TIMEOUT container execution exceeded timeout`. `0` disables the timer.
 
-**Image pre-pull** -- Image preparation (`prepareImage`) runs **before** the CLI banner so Docker's pull overhead does not interleave with the progress tree. If the image is not present locally, a single `pulling image <name>…` status line is written to stderr, then `docker pull --quiet` runs (Docker's native layer progress is suppressed). Pull failure produces `E_DOCKER_PULL`. After the pull (or if the image was already local), `verifyImageHasJaiph` confirms the image contains `jaiph`. The banner and progress tree only begin after image preparation completes.
+**Image pre-pull** -- Image preparation (`prepareImage`) runs **before** the CLI banner so Docker's pull overhead does not interleave with the progress tree. If the image is not present locally, a `pulling image <name>…` status line is written to stderr, then `docker pull --quiet` runs (Docker's native layer progress is suppressed); on success the CLI writes `pulled` on its own line. Pull failure produces `E_DOCKER_PULL`. After the pull (or if the image was already local), `verifyImageHasJaiph` confirms the image contains `jaiph`. The banner and progress tree only begin after image preparation completes.
 
 ### Failure modes
 
@@ -236,7 +236,7 @@ Environment variable forwarding uses an explicit allowlist; everything else is d
 - `CURSOR_*`
 - `CLAUDE_*`
 
-`JAIPH_WORKSPACE` is overridden to `/jaiph/workspace` and `JAIPH_RUNS_DIR` is overridden to `/jaiph/run`. `JAIPH_RUN_ID` is forwarded into the container so the runtime reuses the host-generated run identifier instead of creating its own — this ties the container's `run_summary.jsonl` back to the host CLI invocation and prevents concurrent-run misidentification during run-directory discovery.
+`JAIPH_WORKSPACE` is overridden to `/jaiph/workspace` and `JAIPH_RUNS_DIR` is overridden to `/jaiph/run`. If `JAIPH_AGENT_TRUSTED_WORKSPACE` points at a path inside the host workspace, it is rewritten to the matching path under `/jaiph/workspace` so agent CLIs see a path that exists in the container; absolute paths outside the workspace are left unchanged. `JAIPH_RUN_ID` is forwarded into the container so the runtime reuses the host-generated run identifier instead of creating its own — this ties the container's `run_summary.jsonl` back to the host CLI invocation and prevents concurrent-run misidentification during run-directory discovery.
 
 This allowlist is enforced in `buildDockerArgs` and cannot be overridden. Any variable not matching the allowlist -- including cloud credentials (`AWS_*`, `GCP_*`, etc.), authentication sockets (`SSH_*`), registry tokens (`NPM_TOKEN`, `GITHUB_TOKEN`, `PYPI_*`, `CARGO_*`), and all other host environment -- is silently dropped. If a workflow needs external credentials inside the container, pass them explicitly through `JAIPH_*`-prefixed variables or use a credential proxy.
 
diff --git a/docs/setup.md b/docs/setup.md
index addd69de..0633f9ea 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -9,7 +9,7 @@ redirect_from:
 
 ## Overview
 
-Jaiph ships as a **CLI** backed by Node: it parses `.jh` sources, emits extracted **`script`** files, and starts a **Node workflow runtime** that interprets workflows in process (same stack for local runs, Docker, and tests — see [Architecture](architecture.md)). This page focuses on **installing that CLI**, **running your first workflow**, **project layout**, and **`jaiph init`** — not syntax or internals.
+Jaiph ships as a **CLI** backed by Node: it parses `.jh` sources, runs compile-time validation during script extraction, emits **`script`** bodies into a **`scripts/`** directory (path in **`JAIPH_SCRIPTS`**), and starts a **Node workflow runtime** that interprets workflow ASTs in process (same stack for local runs, Docker, and tests — see [Architecture — System overview](architecture.md#system-overview)). This page covers **installing the CLI**, **running your first workflow**, **workspace layout**, and **`jaiph init`**, not language syntax or runtime internals.
 
 Goals you should leave with:
 
@@ -19,8 +19,8 @@ Goals you should leave with:
 
 ### Prerequisites
 
-- **Node.js** — required to run `jaiph` itself (installer runs `npm` + `npm run build`).
-- **`bash`** — required on the machine if your workflows use **`script`** steps that execute shell bodies (see [Architecture — Distribution](architecture.md)): the runtime runs those as subprocesses using the host shell you configure.
+- **Node.js** — required to run `jaiph` (the curl installer runs `npm install` and `npm run build` in a checkout).
+- **Shell tooling** — the CLI and workflow runtime are Node-based; **emitted `script` steps** run by spawning the script path so the interpreter comes from each file’s **shebang** (often `#!/usr/bin/env bash` or another interpreter on your `PATH`). **Shell lines inside workflows** (after Jaiph interpolation) run via **`sh -c`**, so a POSIX **`sh`** must exist. See [Architecture — Distribution](architecture.md#distribution-node-vs-bun-standalone).
 
 ## Install
 
@@ -28,13 +28,13 @@ Goals you should leave with:
 curl -fsSL https://jaiph.org/install | bash
 ```
 
-This installs a small wrapper **`jaiph`** under `~/.local/bin` plus a **`~/.local/bin/.jaiph/`** tree (CLI sources and **`jaiph-skill.md`** beside `src/`). Alternatively:
+This installs a small wrapper **`jaiph`** under `~/.local/bin` plus a **`~/.local/bin/.jaiph/`** tree: `src/` (compiled CLI), `package.json`, and **`jaiph-skill.md`** (copied from the repo for `jaiph init`). Alternatively:
 
 ```bash
 npm install -g jaiph
 ```
 
-The published npm package may **not** include `docs/jaiph-skill.md` next to the CLI the way the curl layout does — if **`jaiph init`** does not write `.jaiph/SKILL.md`, point **`JAIPH_SKILL_PATH`** at a skill file (for example clone [Agent Skill source](jaiph-skill.md) or the repo `docs/jaiph-skill.md`).
+The published npm package may **not** include `docs/jaiph-skill.md` next to the CLI the way the curl layout does — if **`jaiph init`** does not write `.jaiph/SKILL.md`, point **`JAIPH_SKILL_PATH`** at a skill file (for example the repo’s `docs/jaiph-skill.md`, or download the canonical raw skill: `https://raw.githubusercontent.com/jaiphlang/jaiph/refs/heads/main/docs/jaiph-skill.md`).
 
 Verify:
 
@@ -44,7 +44,7 @@ jaiph --version
 
 If the command is not found, ensure `~/.local/bin` (installer) or the npm global bin directory is on your **`PATH`** (the **`docs/run`** helper prepends `$HOME/.local/bin` automatically after installing).
 
-Switch versions anytime: **`jaiph use`** re-runs your install command (default: `curl … /install | bash`) with **`JAIPH_REPO_REF`** set to **`nightly`** or to **`v`** plus the version you pass (for example **`0.9.4`** → **`v0.9.4`**).
+Switch versions anytime: **`jaiph use`** runs your install command via **`bash -c`** (default: `curl -fsSL https://jaiph.org/install | bash`) with **`JAIPH_REPO_REF`** set to **`nightly`** or to **`v`** plus the version (for example **`0.9.4`** → **`v0.9.4`**).
 
 ```bash
 jaiph use nightly
@@ -71,7 +71,7 @@ For more runnable samples (inbox, async, testing, ensure/catch), see the [`examp
 
 ## Running a workflow
 
-Jaiph workflows live in **`.jh`** files ( **`*.test.jh`** suites use **`jaiph test`** instead — see [Testing](testing.md)). **`jaiph run`** loads a **single entry file** and runs the workflow named **`default`** (`workflow default(...) { ... }`). Use a **shebang** (`#!/usr/bin/env jaiph`) or the CLI — if the first argument is an existing **`.jh`** path, **`*.test.jh`** routes to **`jaiph test`** and other **`.jh`** files to **`jaiph run`** (see [CLI — file shorthand](cli.md#file-shorthand)).
+Jaiph workflows live in **`.jh`** files (**`*.test.jh`** suites use **`jaiph test`** instead — see [Testing](testing.md)). **`jaiph run`** loads a **single entry file** and runs the workflow named **`default`** (`workflow default(...) { ... }`). Use a **shebang** (`#!/usr/bin/env jaiph`) or the CLI: if the first argument is an existing file path, names ending in **`.test.jh`** dispatch to **`jaiph test`** (this check runs before the generic **`.jh`** rule), and every other **`.jh`** file dispatches to **`jaiph run`** (see [CLI — file shorthand](cli.md#file-shorthand)).
 
 ```bash
 ./path/to/main.jh "feature request or task"
@@ -107,7 +107,7 @@ Use your shell’s globbing if you pass multiple files (for example `jaiph forma
 
 - **`jaiph compile`** — validates the import closure (**`validateReferences` only**); no script emission or runner. See [Architecture — Summary](architecture.md#summary) and [CLI](cli.md).
 - **`jaiph test`** — runs **`*.test.jh`** blocks in-process with mocks. See [Testing](testing.md).
-- **`jaiph install`** — fetches reusable modules into **`.jaiph/libs/`**. See [Libraries](libraries.md).
+- **`jaiph install`** — fetches reusable modules into **`.jaiph/libs/`**; workspace root is detected from your **current working directory** (not the entry-`.jh` rule used by **`jaiph run`**). See [Libraries](libraries.md) and [CLI — `jaiph install`](cli.md#jaiph-install).
 
 ## Workspace setup
 
@@ -121,8 +121,8 @@ jaiph init path/to/repo # explicit workspace root
 This creates **`.jaiph/`** under the chosen root with:
 
 - **`.jaiph/.gitignore`** — ignores ephemeral **`runs/`** and **`tmp/`** under **`.jaiph/`** (workflows and libraries stay tracked).
-- **`.jaiph/bootstrap.jh`** — an executable workflow with a triple-quoted multiline **`prompt`** and **`log`** of the result; it points the agent at **`.jaiph/SKILL.md`**.
-- **`.jaiph/SKILL.md`** — copied only when **`resolveInstalledSkillPath()`** finds **`jaiph-skill.md`**; see **`src/cli/shared/paths.ts`** (**`JAIPH_SKILL_PATH`** first when that file exists, then **`jaiph-skill.md`** next to the shipped **`src/`** tree — the curl installer keeps that under **`~/.local/bin/.jaiph/`** by default — then **`docs/jaiph-skill.md`** as a sibling of that **`src/`** parent, then **`docs/jaiph-skill.md`** under **`process.cwd()`**). If nothing resolves, **`jaiph init`** skips the file and tells you to set **`JAIPH_SKILL_PATH`** and run again.
+- **`.jaiph/bootstrap.jh`** — executable **`workflow default`** whose template uses a triple-quoted multiline **prompt**; it tells the agent to read **`.jaiph/SKILL.md`**, scaffold workflows under **`.jaiph/`**, and end with **WHAT CHANGED** and **WHY**; the workflow **`log`**s the result.
+- **`.jaiph/SKILL.md`** — copied when **`jaiph init`** can resolve a skill markdown file: if **`JAIPH_SKILL_PATH`** is set **and** that path exists, it wins; otherwise the CLI tries install-relative paths (`jaiph-skill.md` beside the packaged tree — curl install: **`~/.local/bin/.jaiph/jaiph-skill.md`** next to **`src/`** — then **`docs/jaiph-skill.md`** beside the package when present), then **`docs/jaiph-skill.md`** under the current working directory. Resolution lives in **`resolveInstalledSkillPath()`** (`src/cli/shared/paths.ts`). If nothing resolves, the skill file is skipped and a message tells you to set **`JAIPH_SKILL_PATH`** and run **`jaiph init`** again. Same rules as [CLI — `jaiph init`](cli.md#jaiph-init).
 
 Run the bootstrap workflow:
 
diff --git a/docs/spec-async-handles.md b/docs/spec-async-handles.md
index f22a7dbe..4d260f60 100644
--- a/docs/spec-async-handles.md
+++ b/docs/spec-async-handles.md
@@ -13,38 +13,48 @@ Concurrent work is a common orchestration problem: independent steps could run i
 
 Jaiph addresses that with **`run async`**: the runtime starts a normal `run` target in the background, exposes the in-flight result as a **handle**, and **joins** every handle created in the current step list when that list ends—so nothing is left dangling. This page is about that **value model** (when a handle becomes a real string, how failures propagate, and how events look on the wire). Syntax lives in [Language — `run async`](language.md#run-async--concurrent-execution-with-handles) and [Grammar — `run async`](grammar.md#run-async--concurrent-execution-with-handles). For where this fits in the interpreter, events, and CLI progress, see [Architecture](architecture.md).
 
-**Implementation:** All of this runs in **`NodeWorkflowRuntime`** (`src/runtime/kernel/node-workflow-runtime.ts`)—the same AST interpreter described in [Architecture — System overview](architecture.md#system-overview). A handle is bookkeeping on an in-flight **`run`**; it is joined at the [`executeSteps`](#implicit-join) scope that registered it.
+**Implementation:** All of this runs in **`NodeWorkflowRuntime`** (`src/runtime/kernel/node-workflow-runtime.ts`)—the same AST interpreter described in [Architecture — System overview](architecture.md#system-overview). A handle is bookkeeping on an in-flight **`run`**; it is joined at the [`executeSteps`](#implicit-join) scope that registered it. **`async_indices`** for events are threaded through **`AsyncLocalStorage`** and emitted via **`RuntimeEventEmitter`** (see [Architecture — Core components](architecture.md#core-components) and [CLI progress reporting pipeline](architecture.md#cli-progress-reporting-pipeline)).
 
 ## Overview
 
-`run async ref(args)` schedules the same **`run` target** (workflow or script) **without blocking** the current step list. The value is a **handle**—conceptually `Handle<T>` where `T` is what a synchronous `run` would have produced (workflow **`return`**, or trimmed script stdout). In the runtime variable map the handle is stored as an opaque string token (`__JAIPH_HANDLE__…`); the first **non-passthrough** use that needs the real value **awaits** the scheduled work, then **replaces** that binding with the resolved string (or clears it on failure—see [Resolution](#resolution)).
+`run async ref(args)` schedules the same **`run` target** (workflow or script) **without blocking** the current step list. The value is a **handle**—conceptually `Handle<T>` where `T` is what a synchronous `run` would have produced (workflow **`return`**, or trimmed script stdout on success). In the runtime variable map the handle is stored as an opaque string token (`__JAIPH_HANDLE__` + numeric id); the first **non-passthrough** use that needs the real value **awaits** the scheduled work, then **replaces** that binding with the resolved string (or clears it on failure—see [Resolution](#resolution)).
 
 ## Handle creation
 
 ```jaiph
+script noop = `echo ok`
+
+workflow bg() {
+  run noop()
+}
+
 workflow default() {
-  const h = run async foo()
-  run async bar()
+  const h = run async bg()
+  run async bg()
 }
 ```
 
-- `const h = run async foo()` — `h` holds a handle. Work for `foo()` starts immediately; later steps can run in parallel.
-- `run async bar()` — a handle is still created and **tracked** for [implicit join](#implicit-join) even if you do not store it in a variable.
+- `const h = run async bg()` — `h` holds a handle. Work for `bg()` starts immediately; later steps can overlap with it.
+- `run async bg()` — a handle is still created and **tracked** for [implicit join](#implicit-join) even if you do not store it in a variable.
 
 This is not “fire and forget” in a scheduler sense: the runtime **registers** every `run async`, captured or not, and still **joins** it when the [scope below](#implicit-join) allows.
 
+**Forms:** Only `run async …` as a statement or as `const name = run async ref(args)` is supported. **`recover` / `catch` blocks attach only to the statement form** (`run async foo() recover …` / `catch …`); `const … = run async …` cannot carry a recovery block (the parser allows only a plain call there—see `const-rhs.ts` / `workflow-brace.ts`).
+
 ## Resolution
 
 A handle resolves to the `run` result: workflow **`return`**, or **trimmed script stdout** on success; on failure, resolution carries the same failure shape as a synchronous `run` (and can fail the block or the join, depending on where resolution happens). Resolution is triggered on the first **non-passthrough** read of the value.
 
+`resolveHandlesInInput` scans for `${name}` substrings (identifier form) and resolves each binding that still holds a handle token; **`${run …}` / `${ensure …}`** **inline captures** run only after that scan (see `interpolateWithCaptures`).
+
 ### Reads that force resolution
 
-The runtime scans for `${name}` (and related interpolation) in the places below. **Call arguments:** the parser rewrites **bare identifier** arguments such as `run downstream(h)` into `${h}` form for execution, so handles are resolved there too—same behavior as an explicit quoted interpolation in that position (see [Grammar — Call-site arguments](grammar.md#call-site-arguments) and [Language — `run`](language.md#run--execute-a-workflow-or-script)).
+The runtime scans for `${name}` in the places below. **Call arguments:** at parse time, bare identifiers in a `run` / `ensure` argument list are rewritten to **`${name}`** (`commaArgsToSpaced` in `src/parse/core.ts`), so they go through the same `resolveHandlesInInput` path as explicit interpolation (see [Grammar — Call-site arguments](grammar.md#call-site-arguments) and [Language — `run`](language.md#run--execute-a-workflow-or-script)).
 
 | Access pattern | Example | Forces resolution? |
 | --- | --- | --- |
-| String / template interpolation (`log`, `logerr`, `fail`, `return`, `const … = "…"`, shell one-liners, and other orchestration strings using `interpolate`) | `log "result: ${h}"` | Yes |
-| Arguments to `run` / `ensure` (bare identifiers compile to `${name}`; quoted args with `${…}` use the same resolution path) | `run downstream(h)` or `run downstream("pref_${h}")` | Yes |
+| String / template interpolation (`log`, `logerr`, `fail`, `return`, `const … = "…"`, shell one-liners, and other orchestration strings using `interpolateWithCaptures`) | `log "result: ${h}"` | Yes |
+| Arguments to `run` / `ensure` (tokens that embed `${…}` or bare identifiers rewritten for the callee) | `run downstream(h)` or `run downstream("pref_${h}")` | Yes |
 | Prompt body (string, identifier, or triple-quoted) before the model call | `prompt "ctx: ${h}"` | Yes |
 | `if` subject variable | `if h == "ok" { ... }` | Yes — subject is resolved when it is still a handle token |
 | `match` subject | `match h { ... }` | Yes |
@@ -52,6 +62,8 @@ The runtime scans for `${name}` (and related interpolation) in the places below.
 
 **Send RHS:** For the `var`-style RHS, use `${name}`; a bare `$name` is not treated as a handle reference in the Node runtime.
 
+**`for_lines`:** The loop source is read as a plain variable value **without** passing through handle resolution. If the source is still a handle token, you get the opaque string (or wrong iteration)—materialize the value first (for example `const text = "${h}"` on an expression RHS, or another step that interpolates the handle) before `for_lines`.
+
 ### Passthrough (does not force resolution)
 
 Only the step that **starts** the async work avoids waiting on the result:
@@ -61,7 +73,7 @@ Only the step that **starts** the async work avoids waiting on the result:
 | `const` binding from `run async` | `const h = run async foo()` | No — stores the handle token; work is already scheduled |
 | Bare `run async` (no capture variable) | `run async bar()` | No read of a value here; the handle still [joins](#implicit-join) at scope end |
 
-Any later use that needs a real string—including the first `${h}` inside a `const` RHS, or passing `h` as a bare `run` argument—forces resolution. There is no separate “copy handle without reading” statement; aliasing is done by passing the name through steps that eventually interpolate or join.
+Any later use that needs a real string—including the first `${h}` inside a `const` RHS, or passing `h` as a `run` / `ensure` argument—forces resolution. There is no separate “copy handle without reading” statement; aliasing is done by passing the name through steps that eventually interpolate or join.
 
 If resolution fails (non-zero underlying `run`), the step or join fails with the same error shape as a synchronous `run`; the bound variable is cleared to an empty string in the scope where resolution ran.
 
@@ -69,34 +81,50 @@ After a **successful** resolution, the variable holds the result string; further
 
 ## Implicit join
 
-When the **step list** you are in finishes, the runtime **awaits every `run async` handle** created in that **`executeSteps`** invocation (see `localHandleIds` in `node-workflow-runtime.ts`). That is the “implicit join”: it is per **block**, not merely per workflow name—for example, handles created only inside an `if` body are joined at the end of that **inner** list, before control continues after the `if`.
+When the **step list** you are in finishes, the runtime **awaits every `run async` handle** created in that **`executeSteps`** invocation (`localHandleIds` in `node-workflow-runtime.ts`). Await happens **in creation order** (sequential `await`), not with a single `Promise.all`. That is the “implicit join”: it is per **block**, not merely per workflow name—for example, handles created only inside an `if` body are joined at the end of that **inner** list, before control continues after the `if`.
 
 For an **entry** workflow, **inbox dispatch** runs only **after** `executeSteps` returns successfully: the runtime finishes the step list and the implicit join first, then drains the channel queue ([Inbox — drain timing](inbox.md#who-registers-routes-and-who-drains), [Architecture — channels](architecture.md#channels-and-hooks-in-context)).
 
 - If all joined work succeeds, the outer step list continues or the workflow **returns** normally.
 - If any joined handle ends with a **non-zero** status, the scope fails; several failures are aggregated in one error. Messages refer to the **`run async`** target ref string(s). Handles that were **never read** still participate in this join.
-- If an async branch ends with a **`return`** from a `catch`/`recover` body (the same `recoverReturn` path as synchronous `run`/`ensure`), the join can propagate that **workflow return value** to the parent—mirroring non-async recovery.
+- If an async branch ends with a **`return`** from a `catch`/`recover` body (the same `recoverReturn` path as synchronous `run`/`ensure`), the join can propagate that **workflow return value** to the parent—mirroring non-async recovery. If multiple branches set `recoverReturn`, the **first** joined branch that does so wins (`returnValue` is only set while still `undefined`).
 
-This preserves the older “all async work settled before the workflow could complete” guarantee, while still allowing overlap **until** an explicit read or a scope boundary forces ordering.
+This preserves the “all async work settled before the workflow could complete” guarantee, while still allowing overlap **until** an explicit read or a scope boundary forces ordering.
 
 ## `recover` and `catch`
 
 ### `recover` (retry loop)
 
-`recover` on `run async` mirrors non-async `recover`: on failure, run the **repair** body, then **retry** the `run` target, up to the [recover limit](#retry-limit). The async branch is scheduled once as a **single** promise; retries happen **inside** that branch.
+`recover` on `run async` mirrors non-async `recover`: after a failing run, the runtime executes the **repair** body, then **re-runs** the `run` target, until success or the [recover limit](#retry-limit) is reached. The async branch is scheduled once as a **single** promise; retries happen **inside** that branch.
 
 ```jaiph
-const b1 = run async foo() recover(err) {
-  log "repairing: ${err}"
-  run fix_it()
+script flaky = `test -f .marker`
+script touch_marker = `touch .marker`
+
+workflow maybe_ok() {
+  run flaky()
+}
+
+workflow repair() {
+  run touch_marker()
+}
+
+workflow default() {
+  run async maybe_ok() recover(err) {
+    log "repairing: ${err}"
+    run repair()
+  }
 }
 ```
 
-1. The async path runs `foo()`.
-2. If `foo()` succeeds, the handle resolves to that success value.
-3. If it fails, `err` is the merged **stdout+stderr** of the failure, and the `recover` body runs.
-4. If the `recover` body finishes with status 0 **and** does not use `return` to short-circuit the branch, `foo()` is run again. A `return …` from inside the repair body stops the loop and becomes the async branch’s result.
-5. Steps 3–4 repeat until `foo()` succeeds or the [recover limit](#retry-limit) is exhausted; then the handle result reflects the final **failure** (or last attempt), like synchronous `recover`.
+Execution inside the promise:
+
+1. Run the target once (`maybe_ok()`).
+2. While the last result is a failure and the repair-cycle count is still within `run.recover_limit`, run the `recover` body with `err` set to the merged **stdout+stderr** of the failure, then **run the target again** unless the repair body failed or used `return` to supply a result.
+3. A `return …` from inside the repair body **stops** the loop and becomes the async branch’s result (no further retries of the original target).
+4. If the limit is exhausted and the target still fails, the handle result is that failure—like synchronous `recover`.
+
+So the repair body runs only **after** a failing attempt, and each allowed cycle is “repair, then retry,” not “retry, then repair” on the first failure.
 
 ### `catch` (single-shot, surface keyword `catch`)
 
@@ -114,14 +142,14 @@ The `catch` keyword is the user-facing name; the failure payload is the merged *
 
 Limits apply to the **retry loop** in `recover` (including `run async … recover`).
 
-- **Default:** **10** attempts when `run.recover_limit` is unset.
-- **Config:** top-level `config { run.recover_limit = N }` in the **`.jh` file whose workflow is currently executing** the `run async` / `recover` step—that is the runtime’s `scope.filePath` for that step list, **not** necessarily the CLI entry file when you are deep in a nested `run`. Per-workflow nested `config { }` blocks are not read for this knob.
+- **Meaning:** `run.recover_limit` (default **10**) is the maximum number of **repair cycles** the runtime will execute after a failure: each cycle runs the `recover` body (when applicable) and then **re-runs** the target. Including the **first** attempt, the target may run **up to `recover_limit + 1` times** before the loop stops and surfaces the last failure.
+- **Config:** top-level `config { run.recover_limit = N }` in the **`.jh` file** whose module metadata is keyed by **`scope.filePath`** for that step list (`resolveRecoverLimit` reads `graph.modules.get(filePath)?.ast.metadata`). That is the file **currently executing** those steps—not necessarily the CLI entry file when you are deep in a nested `run`. Per-workflow nested `config { }` blocks are not read for this knob.
 
 ## Progress and events
 
-Concurrent `run async` branches are tagged with a chain of **1-based indices** stored on `STEP_START`, `STEP_END`, `LOG`, and `LOGERR` events as `async_indices`; the CLI prints them as subscript prefixes on the live stream (see [Architecture — CLI progress reporting pipeline](architecture.md#cli-progress-reporting-pipeline)). Indexing uses `AsyncLocalStorage` in the runtime so nested async work gets a deeper chain. Resolving a handle does not emit a separate event—the branch’s own step/log events are the timeline.
+Concurrent `run async` branches are tagged with a chain of **1-based indices** stored on `STEP_START`, `STEP_END`, `LOG`, and `LOGERR` events as `async_indices`; the CLI prints them as subscript prefixes on the live stream ([Architecture — CLI progress reporting pipeline](architecture.md#cli-progress-reporting-pipeline)). Indexing uses `AsyncLocalStorage` in the runtime so nested async work gets a deeper chain. Resolving a handle does not emit a separate event—the branch’s own step/log events are the timeline.
 
-In **`jaiph test`**, the runner sets `suppressLiveEvents: true` on the in-process runtime (see [Architecture](architecture.md) — *Test runner integration*), which silences **`__JAIPH_EVENT__`** on stderr only; durable `run_summary.jsonl` (and handle semantics) behave like `jaiph run`.
+In **`jaiph test`**, the runner sets `suppressLiveEvents: true` on the in-process runtime ([Architecture — Test runner integration](architecture.md#test-runner-integration-testjh-in-the-kernel)), which silences **`__JAIPH_EVENT__`** on stderr only; durable `run_summary.jsonl` (and handle semantics) behave like `jaiph run`.
 
 PTY E2E coverage for interleaved async progress: `e2e/tests/131_tty_async_progress.sh` ([Testing — PTY-based TTY tests](testing.md#pty-based-tty-tests)).
 
diff --git a/docs/testing.md b/docs/testing.md
index 87b5cd82..106b4b0b 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -7,10 +7,16 @@ redirect_from:
 
 # Testing Jaiph Workflows
 
-Jaiph includes a built-in test harness for workflow testing. Test files (`*.test.jh`) let you mock prompt responses, stub workflows, rules, and scripts, run workflows through the same in-process [Node workflow runtime](architecture.md#core-components) used by `jaiph run` (`NodeWorkflowRuntime`), and assert on captured output — all without calling real LLMs or depending on external state. Unlike `jaiph run`, the test harness does not spawn a separate `node-workflow-runner` process: after `buildScripts`, the CLI runs `runTestFile` from `node-test-runner.ts` in the same process. There is no Docker mode for `jaiph test` (workflows under test always run on the host). The system layout (including **Test runner integration** and the Node test runner) is described in [Architecture](architecture.md).
+**Scope:** this page is about **authoring** `*.test.jh` workflow tests (`jaiph test`) and how those pieces relate to the same [Node workflow runtime](architecture.md#core-components) as `jaiph run`. It also summarizes **repository** test layers (compiler txtar, golden AST, shell E2E) that contributors run in CI.
+
+## Why workflow tests exist
 
 In production, a workflow’s behavior depends on live models, host timing, and local files. A harness fixes inputs (mock prompts, stubbed workflows/scripts), runs the same interpreter the CLI uses for real runs, and checks outputs with small assertions so CI and refactors can catch regressions without external services.
 
+## What Jaiph provides
+
+Jaiph includes a built-in test harness: test files (`*.test.jh`) mock prompt responses, stub workflows, rules, and scripts, execute workflows through `NodeWorkflowRuntime` **in-process**, and assert on captured output — without calling real LLMs or depending on external state. Unlike `jaiph run`, the harness does not spawn `node-workflow-runner`: after `buildScripts`, the CLI calls `runTestFile()` in `src/runtime/kernel/node-test-runner.ts`. There is no Docker mode for `jaiph test`; workflows under test always run on the host. **How** that fits `buildRuntimeGraph`, `suppressLiveEvents`, and artifact writes is in [Architecture — Test runner integration](architecture.md#test-runner-integration-testjh-in-the-kernel).
+
 ## File naming and layout
 
 Test files use the `.test.jh` suffix (for example `workflow_greeting.test.jh`).
@@ -37,9 +43,9 @@ jaiph test ./e2e/workflow_greeting.test.jh
 jaiph ./e2e/workflow_greeting.test.jh
 ```
 
-`jaiph path.test.jh` without the `test` subcommand is only accepted when that path resolves to an existing file (`src/cli/index.ts`); otherwise the CLI treats the token as an unknown command.
+`jaiph path.test.jh` without the `test` subcommand is only accepted when the **first** CLI argument ends with `.test.jh` **and** `path` resolves to an existing file (`src/cli/index.ts`); otherwise the token is treated as an unknown command.
 
-**Discovery:** With no path argument, Jaiph scans the detected workspace root recursively; with a directory, it scans that tree. Only `*.test.jh` files are collected: the name must end in `.jh` and the stem must end with `.test` (see `walkTestFiles` in `src/transpile/build.ts`). The workspace root—for locating imports and setting `JAIPH_WORKSPACE`—is from `detectWorkspaceRoot` in `src/cli/shared/paths.ts`: walk upward from a starting directory (the current working directory, the directory you passed, or the parent of a single test file) until `.jaiph` or `.git` is found, subject to a few guards for shared temp directories and nested `.jaiph/tmp` layouts; if nothing matches, the resolved starting directory is used as the root.
+**Discovery:** With no path argument, Jaiph scans the detected workspace root recursively; with a directory, it scans that tree. Only `*.test.jh` files are collected: the name must end in `.jh` and the stem must end with `.test` (see `walkTestFiles` in `src/transpile/build.ts`). Unlike `walkjhFiles` (used when compiling ordinary `*.jh` trees), test discovery does **not** skip `.jaiph/` subtrees, so stray `*.test.jh` files under `.jaiph/...` would be picked up — keep test modules in normal source locations. The workspace root—for locating imports and setting `JAIPH_WORKSPACE`—is from `detectWorkspaceRoot` in `src/cli/shared/paths.ts`: walk upward from a starting directory (the current working directory, the directory you passed, or the parent of a single test file) until `.jaiph` or `.git` is found, subject to a few guards for shared temp directories and nested `.jaiph/tmp` layouts; if nothing matches, the resolved starting directory is used as the root.
 
 If no `*.test.jh` files are found, the command prints an error and exits with status 1. A file must contain at least one `test` block; otherwise the CLI reports a parse error. Passing a plain `*.jh` file that is not named `*.test.jh` is rejected — use `jaiph run` for those.
 
@@ -58,7 +64,7 @@ test "runs happy path and prints PASS" {
 }
 ```
 
-Inside a test block, steps execute in order. The following step types are available.
+Inside a test block, steps execute in order. **`#` line comments** and **blank lines** are allowed between steps (they are ignored by the runner).
 
 ### Mock prompt (inline)
 
@@ -70,7 +76,7 @@ mock prompt "second response"
 mock prompt myConstName
 ```
 
-Use a **double-quoted string** (escapes: `\"`, `\n`, `\\`) or a bare identifier for a [test `const`](#test-block-constants) defined earlier in the block.
+Use a **double-quoted string** (escapes: `\"`, `\n`, `\\`) or a bare identifier for a [test `const`](#test-block-constants) defined earlier in the block. **Single-quoted** mock text is rejected at parse time — use double quotes.
 
 ### Mock prompt (content-based dispatch)
 
@@ -104,6 +110,8 @@ mock workflow w.greet() {
 }
 ```
 
+**Syntax:** `mock workflow <ref>(<params>) { ... }` — **parentheses are required**, even when there are no parameters (`()`). The legacy form `mock workflow ref {` without `()` is rejected with a fix hint.
+
 The reference format is `<alias>.<workflow>` (preferred) or `<name>` for a workflow defined in the test file itself.
 
 ### Mock rule
@@ -118,7 +126,7 @@ mock rule w.validate() {
 
 ### Mock script
 
-Stubs a module `script` block:
+Stubs a module `script` block. The body is **shell**, like a real `script` step (the runner executes it as a managed shell mock — see `runtime-mock.ts`):
 
 ```jaiph
 mock script w.helper() {
@@ -128,6 +136,8 @@ mock script w.helper() {
 
 Test stubs use `mock script`, not `mock function`; the latter is a parse error with a fix hint.
 
+`mock script` uses the same **`ref() { ... }`** header shape as `mock workflow` / `mock rule`.
+
 ### Workflow run (with capture)
 
 Runs a workflow and captures its output into a variable:
@@ -136,13 +146,13 @@ Runs a workflow and captures its output into a variable:
 const response = run w.default()
 ```
 
-**Capture semantics** match production behavior:
+**Capture semantics** (see `runTestBlock` in `node-test-runner.ts`) pick the first branch that applies:
 
-1. If the workflow exits 0 with a non-empty explicit `return` value, that string is captured.
-2. If the workflow fails (non-zero exit), the runtime error string is captured (when present).
-3. Otherwise, the harness reads all `*.out` files in the run directory sorted by filename, or falls back to the runtime's aggregated output.
+1. **Exit code 0** and a **non-empty** `return` string from the workflow → that return value is captured.
+2. **Non-zero exit** and a non-empty runtime **error** string → the trimmed error string is captured (useful with `allow_failure` when you assert on failure output).
+3. **All other cases** (for example exit 0 with no return text, non-zero without an error string, or empty return) → the harness concatenates every `*.out` step capture in the run directory **in sorted filename order**; if listing or reading those files fails, it falls back to the runtime’s aggregated output string.
 
-The test fails on non-zero exit unless `allow_failure` is specified.
+The test still **fails** on non-zero exit unless `allow_failure` is set; capture content is independent of that check.
 
 **Variants:**
 
@@ -193,7 +203,7 @@ const want = "expected substring"
 expect_contain response want
 ```
 
-Failures print expected vs. actual previews.
+`expect_equal` failures print a short `diff`-style `-` / `+` preview; substring assertions report lengths and the expected fragment.
 
 ## Typed prompts
 
@@ -207,7 +217,7 @@ The runner output looks like:
 
 ```
 testing workflow_greeting.test.jh
-  ▸ runs happy path
+  ▸ runs happy path and prints PASS
   ✓ 0s
   ▸ handles error case
   ✗ expect_contain failed: "response" (42 chars) does not contain "expected" 1s
@@ -220,7 +230,7 @@ When all tests pass: `✓ N test(s) passed`. Exit status is 0 on full success, n
 
 ## How it works
 
-The CLI parses each test file and passes `test "…" { … }` blocks to `runTestFile()` (`src/runtime/kernel/node-test-runner.ts`). That path aligns with the **Test runner integration** description in [Architecture](architecture.md):
+The CLI parses each test file and passes `test "…" { … }` blocks to `runTestFile()` (`src/runtime/kernel/node-test-runner.ts`). That path aligns with [Architecture — Test runner integration](architecture.md#test-runner-integration-testjh-in-the-kernel):
 
 1. **`buildScripts(testFileAbs, tmpDir, workspaceRoot)`** — same helper as `jaiph run`, with the **test file as the entrypoint** (`test.ts` calls it with the absolute path to the `*.test.jh` file). For a file entrypoint, the transpiler walks the test module and every file reachable by transitive **`import`** (see `collectTransitiveJhModules` in `src/transpile/build.ts`); it runs `validateReferences` / `emitScriptsForModule` per file and writes atomic **`script`** files into a temp `scripts/` tree. (If `buildScripts` were ever given a **directory** entrypoint, directory walks skip `*.test.jh` files — that is not how `jaiph test` invokes it.)
 2. **`buildRuntimeGraph(testFileAbs, workspaceRoot)`** — called **once per test file**; the same graph is reused for every `test` block in that file and for every `run` step inside them.
@@ -295,15 +305,15 @@ workflow default() {
 | Directive | Meaning |
 |-----------|---------|
 | `# @expect ok` | Parse + validate succeed with no errors |
-| `# @expect error E_CODE "substring"` | An error is thrown whose message contains both `E_CODE` and `substring` |
+| `# @expect error E_CODE "substring"` | An error is thrown whose message contains both `E_CODE` and `substring` (substring must be **double-quoted** in the fixture — the runner parses that form only) |
 | `# @expect error E_CODE "substring" @L` | Same, and the error must be reported at line `L` (any column) |
 | `# @expect error E_CODE "substring" @L:C` | Same, and the error must be reported at line `L`, column `C` |
 
 ### Single-file vs multi-file tests
 
-- **Single-file:** use `--- input.jh`. The runner compiles `input.jh`.
+- **Single-file:** use `--- input.jh`. The runner parses and validates `input.jh`.
 - **Single test file:** use `--- input.test.jh` for test-specific fixtures.
-- **Multi-file:** use `--- main.jh` as the entry file plus additional `--- lib.jh` etc. The runner compiles `main.jh`.
+- **Multi-file:** use `--- main.jh` as the entry file plus additional `--- lib.jh` etc. The runner parses and validates `main.jh` as the entry.
 
 The entry file is determined by priority: `main.jh` if present, otherwise `input.jh`, otherwise `input.test.jh`, otherwise the first file.
 
@@ -413,9 +423,10 @@ The project includes a Playwright-based test (`e2e/playwright/landing-page.spec.
 
 ## Limitations (v1)
 
-- **Prompt mocks** must be written **inside the test file** (inline `mock prompt "…"`, `mock prompt <const>`, or `mock prompt { … }`) — there are no external mock-config file paths.
+- **Prompt mocks** must be written **inside the test file** (inline `mock prompt "…"`, `mock prompt <const>`, or `mock prompt { … }`) — there are no external mock-config file paths. Inline responses must use **double** quotes (not single quotes).
 - **Do not combine** `mock prompt { … }` with queue-style `mock prompt "…"` / `mock prompt <const>` in the same test block; when a block is present, queued entries are ignored.
-- **Capture** without a successful non-empty `return` concatenates all step `*.out` files in the run directory (sorted by filename), then falls back to the runtime’s aggregated output string.
+- **`mock workflow` / `mock rule` / `mock script`** require `ref()` with parentheses — empty `()` when there are no parameters.
+- **Capture**: only a **non-empty** return value on success bypasses concatenating `*.out` files; exit 0 with an empty return, failures without a runtime error string, and other edge cases use the `*.out` / aggregated-output path described above.
 - **`expect_*` right-hand side** is either a double-quoted literal or a test `const` name — not an arbitrary expression.
 - **`expectContain` / `expectEqual` / `expectNotContain` (camelCase)** are rejected; use `expect_contain`, `expect_equal`, `expect_not_contain`.
 - **Extra CLI arguments** after the path (`jaiph test <path> [extra...]`) are accepted but ignored (reserved for future use).
diff --git a/src/cli/commands/test.ts b/src/cli/commands/test.ts
index 68ffe3f3..340e7c88 100644
--- a/src/cli/commands/test.ts
+++ b/src/cli/commands/test.ts
@@ -65,8 +65,8 @@ export async function runTest(rest: string[]): Promise<number> {
   }
 
   process.stderr.write(
-    "jaiph test requires a *.test.jh file with inline mock prompt steps. Example:\n" +
-      "  test \"...\" { mock prompt \"response\"; response = w.default; expectContain response \"...\"; }\n",
+    "jaiph test requires a *.test.jh file. Example:\n" +
+      "  test \"...\" { mock prompt \"response\"; const r = run w.default(); expect_contain r \"...\"; }\n",
   );
   return 1;
 }
diff --git a/src/cli/shared/usage.ts b/src/cli/shared/usage.ts
index 8826de00..9166228d 100644
--- a/src/cli/shared/usage.ts
+++ b/src/cli/shared/usage.ts
@@ -38,6 +38,7 @@ export function printUsage(): void {
       "jaiph compile:",
       "  Parse import closures and validateReferences only (same compile-time checks as before jaiph run;",
       "  no scripts/ emission, no buildRuntimeGraph, no runner). Useful for editors and CI.",
+      "  -h, --help      show compile command usage (also accepted after jaiph compile)",
       "  --json          stdout: JSON array of { file, line, col, code, message } (empty array if ok).",
       "  --workspace <dir>  workspace root for import resolution (default: auto-detect per file).",
       "",