@navels/neal 0.1.0 → 0.3.0

package/README.md

@@ -1,39 +1,45 @@
 # neal
 
+**neal** — from *anneal*: repeated, controlled adjustment toward a more
+stable result.
+
 [![CI](https://github.com/navels/neal/actions/workflows/ci.yml/badge.svg)](https://github.com/navels/neal/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@navels/neal.svg)](https://www.npmjs.com/package/@navels/neal)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> **A source-first, multi-agent coding loop.** Separate **planner**, **coder**, and **reviewer** roles — each on the provider and model you choose — drive scoped, reviewed, crash-safe changes to your repository.
+> **A plan-driven, multi-agent coding loop.** Separate **planner**, **coder**, and **reviewer** roles, each on the provider and model you choose, work together to implement your plan.
+
+![neal execution flow](docs/assets/neal-execution-flow.png)
+
+neal is a local planner/coder/reviewer loop for your repo. You write a plan, and neal's planner/reviewer loop turns it into a human-reviewable execution plan with an execution shape, manageable scopes, and high-level implementation detail grounded in the current repository. neal then runs each scope with your configured coder and reviewer roles. After every scope is accepted, a final review pass checks the total set of changes against the entire plan. Run artifacts are recorded under `.neal/` so interrupted work can resume.
 
-![neal driving a planner/coder/reviewer run](https://raw.githubusercontent.com/navels/neal/main/assets/neal-demo.gif)
+Two choices explain the design:
 
-neal is a source-first local planner/coder/reviewer loop for your repo. You write a plan; neal refines it with your configured planner role, runs each scope with your configured coder role, commits the result, and hands the diff to your configured reviewer role before moving on. When every scope is accepted, a final review pass checks the whole plan, and run artifacts stay under `.neal/` so interrupted work can resume.
+- **The coder and reviewer run on different vendors.** The review is genuinely adversarial: a second model with its own blind spots checks the first, instead of one model grading its own work.
+- **Each scope starts the coder from a fresh context.** A long plan doesn't drift the way a single agent does as its context fills up.
 
 ### What makes it interesting
 
-- **Roles, not one monolithic agent.** Planner, coder, and reviewer are independent, separately configurable roles — mix vendors and models per role (e.g. Codex codes, Claude reviews).
-- **The reviewer is read-only** — declared at provider registration and enforced mechanically in each adapter (OS sandbox for Codex, SDK tool allowlist for Claude, a neal-owned jailed toolset for OpenRouter models), pinned by a conformance test — never just prompt-deep. See [SECURITY.md](SECURITY.md) and [docs/providers.md](docs/providers.md).
-- **`neal compat`** — a built-in harness that qualifies any OpenAI-compatible / OpenRouter model across all three roles and emits a dated PASS/FAIL whitelist. See [docs/compatible-models.md](docs/compatible-models.md).
-- **Crash-safe and resumable** — every run's state and artifacts live under `.neal/`; `neal resume` continues an interrupted run.
-- **Bounded autonomous recovery** — neal resolves a class of reviewer/coder deadlocks itself, and escalates genuine blockers.
+- **Roles, not one monolithic agent.** Planner, coder, and reviewer are independent, separately configurable roles. Mix vendors and models per role (e.g. Codex codes, Claude reviews).
+- **The reviewer is read-only.** Declared at provider registration and enforced mechanically in each adapter (OS sandbox for Codex, SDK tool allowlist for Claude, a neal-owned jailed toolset for OpenRouter models). See [SECURITY.md](SECURITY.md) and [docs/providers.md](docs/providers.md).
+- **`neal compat`.** A built-in harness that qualifies any OpenAI-compatible / OpenRouter model across all three roles and emits a dated PASS/FAIL whitelist. See [docs/compatible-models.md](docs/compatible-models.md).
+- **Crash-safe and resumable.** Every run's state and artifacts live under `.neal/`. `neal resume` continues an interrupted run.
+- **Bounded autonomous recovery.** neal resolves a class of reviewer/coder deadlocks itself, and escalates genuine blockers.
+- **Scopes can split themselves.** When a scope turns out bigger than expected, the coder splits it into a derived sub-plan instead of forcing a bad implementation into one commit. See [docs/plan-format.md](docs/plan-format.md).
 
 For how the pieces fit together, see the [architecture overview](docs/architecture.md).
-Wondering how this differs from Claude Code, Aider, or OpenHands? See
-[docs/comparison.md](docs/comparison.md).
 
 **Contents:** [Quickstart](#quickstart) ·
 [Why neal exists](#why-neal-exists) ·
-[neal is built with neal](#neal-is-built-with-neal) ·
 [Installation](#installation) ·
-[Provider Setup](#provider-setup) ·
-[Command Tour](#command-tour) ·
+[Provider setup](#provider-setup) ·
+[Command tour](#command-tour) ·
 [Commands](#commands) ·
-[Exit Codes](#command-exit-codes) ·
+[Exit codes](#command-exit-codes) ·
 [Configuration](#configuration) ·
 [Artifacts](#artifacts-and-storage) ·
-[Plan Shape](#plan-shape) ·
-[Safety Notes](#safety-notes)
+[Plan shape](#plan-shape) ·
+[Safety notes](#safety-notes)
 
 ## Quickstart
 
@@ -43,85 +49,57 @@ neal setup          # pick providers for the coder and reviewer roles
 neal check          # verify config and provider readiness
 ```
 
-The cheapest way to try neal is a single OpenRouter API key — no Codex or
-Claude subscription required: run `neal setup --provider generic-agentic
---all-roles`, set `OPENAI_COMPATIBLE_API_KEY`, and pick a model from the
-[qualified-model whitelist](docs/compatible-models.md). The flagship
-configuration — Codex writes, Claude reviews — uses those two locally
-authenticated CLIs instead; see [Provider Setup](#provider-setup).
+No Claude or Codex subscription? Pick a qualified model slug from the
+[compatibility whitelist](docs/compatible-models.md) and use the OpenRouter
+provider (see [Provider setup](#provider-setup)).
 
-From a Git repository with at least one commit, write a minimal plan and run
-it:
+Describe a real feature in plain language and write it to a file (e.g., `PLAN.md`):
 
 ```md
-# Add a project description
+Add a "Sign in with Google" option to the login page using OAuth 2.0.
+Store the resulting session the same way the existing email/password login does.
+```
 
-## Execution Shape
+Then run neal from your repository root:
 
-executionShape: one_shot
+```bash
+neal run <path-to-PLAN.md>
+```
 
-## Objective
+Note: I usually keep plan docs in a .gitignore-ed directory in my repo but ymmv.
 
-Add a one-line project description to the top of README.md and keep the
-existing content unchanged.
-```
+Want to read the refined plan before neal executes it? Run the two steps
+separately instead:
 
 ```bash
-neal run PLAN.md
+neal plan <path-to-PLAN.md>
+# review/update the refined plan, then:
+neal execute <path-to-PLAN.md>
 ```
 
-neal refines the plan through the planner/reviewer loop, executes each scope
-with a fresh-context coder, has the reviewer judge every diff before moving
-on, and persists run state under `.neal/` — interrupt it any time and
-`neal resume` continues where it stopped. Plan shapes, queues, and loops:
-[docs/plan-format.md](docs/plan-format.md). If something misbehaves:
-[docs/troubleshooting.md](docs/troubleshooting.md).
-
 ## Why neal exists
 
-neal grew out of a large frontend upgrade (Ember 3.28 to Ember 5) where the agent would drift over time from its initial instructions, which led to me wanting to break up the work into smaller chunks and reset the agent context before each chunk. I also wanted to incorporate my typical manual workflow of having Claude review Codex's work, copy/pasting findings and responses until both agents were satisfied with the result, before reviewing myself. I settled on this flow for neal:
+neal grew out of a large frontend upgrade (Ember 3.28 to Ember 5) where the agent would drift over time from its initial instructions, which led to me wanting to break up the work into smaller chunks and reset the agent context before each chunk. I also wanted to incorporate my manual workflow of having Claude review Codex's work, copy/pasting findings and responses until both agents were satisfied with the result, before reviewing myself. I settled on this flow for neal:
 
 - start with a plan of what work needs to be done and how to do it
-- neal sends this through the planner/reviewer loop to ensure it is broken into manageable chunks (aka scopes) and formatted for execution by neal
-- each scope is run through the coder/reviewer loop with the coder starting with a fresh context
+- neal sends this through the planner/reviewer loop to give it an execution shape, define manageable scopes, and flesh out the implementation approach
+- each scope is run through the coder/reviewer loop with the coder starting with a fresh context and the reviewer keeping its context from scope to scope
 - when the reviewer is satisfied, neal moves on to the next scope with the previous scope committed
 - after all scopes are complete, the entire set of changes is run through the coder/reviewer loop a final time
 - if a scope is found to be too large, the coder can split it into a sub-plan
-- if the coder is blocked on something, it can consult the reviewer for assistance
+- if the coder is blocked on something, it can consult the reviewer model for assistance
 - if neal exits for any reason, `neal resume` will attempt to continue, prompting for direction if the coder was blocked
 - run artifacts and state are recorded in `.neal/`
 
-![neal execution flow](docs/assets/neal-execution-flow.png)
-
-The name comes from `anneal`: repeated controlled adjustment toward a more stable result.
-
-## neal is built with neal
-
-neal's development is its own primary proof. The blocked-handling redesign in
-this release — replacing an ad-hoc support loop with the unified, budgeted
-blocked adjudicator — was planned, implemented, and reviewed by neal driving
-itself: Codex wrote each scope from a fresh context, Claude reviewed every
-diff, and the run artifacts under `.neal/` were the working record. Much of
-the code and documentation in this repository was written by coding agents
-under human direction; the architecture, the judgment calls, and the final
-review are human.
-
-The public repository begins at a single squashed commit because the
-pre-release history carried private working context; it is preserved
-privately. From v0.1.0 forward, development happens in the open — including
-runs where neal maintains neal.
-
 ## Installation
 
 ```bash
 npm install -g @navels/neal
 ```
 
-neal requires Node.js >= 22.13 and drives your configured provider CLIs/SDKs
-(OpenAI Codex, Anthropic Claude, or any OpenAI-compatible / OpenRouter model) —
-see [Provider Setup](#provider-setup). On Windows, run neal from WSL2 with the
-target repository on the Linux filesystem; direct PowerShell or cmd.exe
-operation is not a supported launch path.
+neal requires Node.js >= 24.18.0 and drives your configured provider CLIs/SDKs
+(OpenAI Codex, Anthropic Claude, or any OpenAI-compatible / OpenRouter model).
+See [Provider setup](#provider-setup).
 
 ### Run from source / contribute
 
@@ -132,44 +110,94 @@ corepack enable && pnpm install && pnpm start -- help
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor setup, the development
 link, verification commands, CI gates, and canonical doc references.
 
-## Provider Setup
+## Provider setup
 
-neal delegates planning, coding, and reviewing to provider-owned local runtimes, selected by provider id in the `agent.coder.provider` and `agent.reviewer.provider` config keys. The planner inherits the coder provider/model unless `agent.planner` is configured explicitly. Each provider still owns its credentials, account state, model availability, permissions, quotas, and rate limits.
+neal uses separate providers for the planner, coder, and reviewer roles. `neal
+setup` writes explicit coder and reviewer defaults to `~/.neal/config.yml`.
 
-| Provider id | Roles it serves | What you need | Docs |
-| --- | --- | --- | --- |
-| `openai-codex` | planner, coder, reviewer | Local OpenAI Codex runtime, authenticated through its own provider-owned setup | [docs/providers.md](docs/providers.md) |
-| `anthropic-claude` | planner, coder, reviewer | Local Anthropic Claude runtime, authenticated through its own provider-owned setup | [docs/providers.md](docs/providers.md) |
-| `openai-compatible` | reviewer only (API-only: no repository tools — neal inlines diff/artifact context — no session resume, no `effort`) | Any OpenAI-compatible Chat Completions endpoint (DeepSeek, OpenRouter, vLLM, and similar) via the `providers.openai_compatible` config block; env fallbacks `OPENAI_COMPATIBLE_BASE_URL`, `OPENAI_COMPATIBLE_API_KEY`, `OPENAI_COMPATIBLE_MODEL` | [docs/providers.md](docs/providers.md#openai-compatible-endpoints) |
-| `generic-agentic` | coder (and the inherited planner); reviewer through a read-only toolset | The same `providers.openai_compatible` block plus a strong tool-calling model | [docs/providers.md](docs/providers.md#generic-agentic-writer), [docs/compat.md](docs/compat.md) |
+A typical config uses Codex for coding and Claude for review:
 
-For `generic-agentic`, neal owns the agentic loop and supplies its own file/search/shell tools, so the endpoint only needs reliable tool calling; its reviewer inspects the repository directly through read-only tools instead of judging inlined context — prefer it over `openai-compatible` for reviewer duty when the model calls tools reliably. It never persists provider sessions (`neal resume` restarts the interrupted scope from scratch in a fresh session) and runs with the same trust level as the other writer providers — its coder-role `run` tool is unsandboxed shell. Use paid tool-calling model slugs for coder duty; `:free` pools are reviewer-only. Before trusting a generic-agentic model with real work, qualify it with `neal compat` (see [docs/compat.md](docs/compat.md)) to confirm it can drive the full loop.
+```yaml
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: anthropic-claude
+    model: null
+```
+
+`model: null` lets the provider choose its default model. The planner can also be configured
+but otherwise inherits from the coder config.
+
+| Provider id | Setup |
+| --- | --- |
+| `openai-codex` | Complete the normal Codex local setup/login, or use your `OPENAI_API_KEY`. |
+| `anthropic-claude` | Complete the normal Claude local setup/login, or use your `ANTHROPIC_API_KEY`. |
+| `openai-compatible` | Connect an OpenAI-compatible Chat Completions API such as OpenRouter, DeepSeek, Ollama, or vLLM. |
 
-Run setup once before first writer-run use:
+### OpenRouter and other OpenAI-compatible APIs
+
+Use `openai-compatible` to run models through OpenRouter or another API that
+implements OpenAI-compatible Chat Completions. It's separate from
+`openai-codex` and doesn't use the Codex CLI or login.
+
+For OpenRouter, export your API key:
+
+```bash
+export OPENROUTER_API_KEY=...
+```
+
+Then add the endpoint to `~/.neal/config.yml`:
+
+```yaml
+providers:
+  openai_compatible:
+    base_url: https://openrouter.ai/api/v1
+    api_key_env: OPENROUTER_API_KEY
+```
+
+For another compatible API, change the URL and key variable. See
+[docs/providers.md](docs/providers.md) for environment-only configuration and
+local endpoints.
+
+Run setup once:
 
 ```bash
 neal setup
 ```
 
-`neal setup` detects local runtime availability for built-in providers without making live provider calls, asks for coder and reviewer defaults, and writes explicit `agent.coder` and `agent.reviewer` provider/model settings to `~/.neal/config.yml`. The planner inherits coder by default; interactive setup asks before writing an explicit planner override. To script the same provider for every role:
+`neal setup` detects local runtimes and configured OpenAI-compatible settings,
+but it doesn't authenticate or send prompts. Choose `openai-compatible` for
+each role you want to run through OpenRouter, then enter an OpenRouter model
+slug such as `deepseek/deepseek-v3.2`.
+
+To script the same provider for every role:
 
 ```bash
 neal setup --provider anthropic-claude --all-roles
 ```
 
-When a model is omitted, setup writes `model: null` so the provider chooses its default model. Existing effective provider settings are not overwritten unless you confirm interactively or pass `--force`.
-
-Authenticate or configure each provider through its normal provider-owned local setup before running provider-backed workflows such as `neal plan`, `neal execute`, `neal run`, or `neal resume`. Neal does not collect or store provider credentials. Provider contract details are in [docs/providers.md](docs/providers.md). External provider adapters are future work.
+Existing effective provider settings are not overwritten unless you confirm
+interactively or pass `--force`.
 
-After setup, verify local config and provider readiness:
+Then verify the config and live provider access:
 
 ```bash
 neal check
 ```
 
-After the config passes, `neal check` prints the effective planner/coder/reviewer roles and prompts before sending one small prompt to each configured role for live connectivity verification. In non-interactive shells, it validates config and reports that live provider verification was skipped. Common setup and auth failures, with their exact messages and fixes, are collected in [docs/troubleshooting.md](docs/troubleshooting.md).
+`neal check` prints the effective planner/coder/reviewer choices, then prompts
+before sending one small live request to each configured role. In non-interactive
+shells, it only validates config and reports that live verification was skipped.
 
-## Command Tour
+Before using an `openai-compatible` model for real work, run `neal compat` (see
+[docs/compat.md](docs/compat.md)). Free or heavily rate-limited model pools
+usually fail as coders and are unreliable reviewers. Provider details are in
+[docs/providers.md](docs/providers.md), and common setup/auth failures are in
+[docs/troubleshooting.md](docs/troubleshooting.md).
+
+## Command tour
 
 Writer commands require a Git repository with an existing `HEAD` commit before
 provider execution. Create and commit the repository's initial baseline before
@@ -199,13 +227,7 @@ neal execute PLAN.md --unattended
 neal run --unattended tmp/A.md tmp/B.md
 ```
 
-Try the dependency-free in-repo example without provider calls:
-
-```bash
-pnpm --dir examples/issue-triage-js test
-```
-
-To run the same example through Neal after configuring providers:
+To run an example through neal after configuring providers:
 
 ```bash
 neal setup
@@ -231,7 +253,9 @@ Give guidance only when `neal status` or `neal resume` says the selected run is
 neal resume --run <run-id> --message "Keep the change bounded to the failing test and rerun the required validation gate."
 ```
 
-Review already-committed work:
+`neal review` is a separate, plan-free workflow for already-committed work. The
+coder proposes findings, the reviewer judges them, and neal rejects any
+worktree changes made during the review:
 
 ```bash
 neal review --last 3
@@ -248,73 +272,91 @@ neal status --all
 neal status --json --all
 ```
 
-## Automation Contract
+## Automation contract
 
 neal keeps a stable machine-facing contract for driving it from scripts, CI, and benchmark harnesses: writer exit codes, the `neal status --json` classification schema, patch-submission eligibility, and harness timeout and trace-publishing guidance. See [docs/automation.md](docs/automation.md).
 
 ## Commands
 
 ```bash
+# Setup
 neal setup
+neal check
+neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|openai-compatible:<slug>] [--json]
+
+# Plan execution
+neal run [--no-squash] [--unattended] <plan.md> [more-plans...]
 neal plan <plan.md> [--unattended]
 neal execute <plan.md> [--no-squash] [--unattended]
-neal run [--no-squash] [--unattended] <plan.md> [more-plans...]
 neal resume [--run <run-id>] [--message "..."]
+
+# Plan-free review
 neal review [message] (--last <n> | --since <base>)
-neal squash [plan.md]
-neal check
-neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|generic-agentic:<slug>] [--json]
+
+# Inspection and maintenance
 neal status [--json] [--run <run-id>]
 neal status [--json] --all
+neal squash [plan.md]
+
+# CLI information
 neal version
 neal help
 neal --help
 neal -h
 ```
 
-`neal plan` revises the target plan file in place and stores the original-plan backup at `.neal/runs/<run-id>/PLAN_ORIGINAL.md`.
+### Setup
 
-`neal execute` runs an already-ready plan. It requires a Git repository with at least one commit and no dirty work outside the selected plan document, and can edit files and create commits. When the selected plan document is repo-local, nonignored, and changed, neal may include it in the run's final tree through ordinary Git staging. Ignored, missing, non-file, or outside-repository plan documents are recorded as metadata only and are not force-added. Completed execute runs squash run-owned commits by default without confirmation; pass `--no-squash` to leave the individual commits in place.
+`neal setup` detects available providers and writes coder, reviewer, and optional
+planner choices to `~/.neal/config.yml`. `neal check` validates that config and
+can make a small live request to each configured role.
 
-`neal run` refines each plan through the planning loop, then executes the accepted plan. It requires a Git repository with at least one commit and uses the same clean-worktree admission as `neal execute`: dirty work outside the selected plan document blocks writer-run start and queue continuation. Queue items run serially. The queue stops at the first blocked, failed, paused, or operator-attention run. Execution children use the same selected-plan-document handling as `neal execute`: eligible repo-local nonignored plan documents may land in the final run tree, while ignored or outside-repository plans remain metadata-only. Execution children squash completed run-owned commits by default; pass `--no-squash` to preserve per-scope commits.
+`neal compat` is a full-loop smoke test for an `openai-compatible` model, not a
+skill benchmark. See [docs/compat.md](docs/compat.md) for the test contract and
+[docs/compatible-models.md](docs/compatible-models.md) for the current results.
 
-`neal resume` continues the selected writer run when it is mechanically resumable, including ordinary failed, paused, and stale-running states. With no `--run`, neal uses the current local run pointer. If the run is waiting for operator guidance, `neal resume` and `neal status` explain the blocker and print the exact `neal resume --run <run-id> --message "..."` command. `--message` is reserved for that waiting-guidance state.
+### Plan execution
 
-If a coder scope reaches expected human work that Neal cannot perform itself, the run can wait in `waiting_for_manual_gate`. `neal status` shows the gate title, reason, run-local `GATE-<id>.md` instructions file, last failed check if any, and the resume command. `neal resume --run <run-id>` runs the gate's configured noninteractive command checks before provider execution; failed checks keep the gate open, and passing checks clear the gate and resume the same coder scope. Manual gates do not use `neal resume --message`.
+`neal run` is the normal workflow. It refines each plan, executes it, and runs
+multiple plan arguments in order. Use `neal plan` and `neal execute` separately
+when you want to inspect or edit the refined plan before execution.
 
-### Unattended Mode
+Writer commands require a Git repository with an existing commit. `neal execute`
+and `neal run` can edit files and create commits, then squash their completed
+work by default. Pass `--no-squash` to keep the per-scope commits.
 
-`--unattended` (on `neal plan`, `neal execute`, and `neal run`) runs Neal
-headlessly — CI, cron, or a benchmark harness — when no operator is available:
-eligible blocks auto-resume for a small bounded number of turns with a fixed
-conservative guidance message, and the operator review gates fail cleanly and
-terminally (exit code `3`, produced artifacts left unsubmitted) instead of
-waiting for `neal resume --message`; verification, authorization, and the
-squash/grading paths are never weakened. The resolved value is persisted on run
-state, so a later `neal resume` and the `neal run` plan→execute hand-off keep
-the same behavior without re-passing the flag. The squash preference
-(`--no-squash`) is likewise persisted on run state across resume. See
-[config.yml](config.yml) for the `agent.unattended` config key (default
-`false`; the flag overrides it) and [docs/state-machine.md](docs/state-machine.md)
-for the operator-block and gate states.
+`neal resume` continues the current run or a run selected with `--run`. If neal
+needs guidance or manual work, `neal resume` and `neal status` explain what is
+needed and print the command to continue.
 
-`neal review` never mutates your repository: candidate findings are drafted on the coder provider and judged by the read-only reviewer, and neal verifies after every provider call that the worktree and neal's own run state are byte-unchanged, failing the review otherwise. It uses neal's built-in adversarial review posture by default; the optional positional message is additive context. The selector is resolved when the command starts, and neal reviews commits ending at the current checkout `HEAD` for `--last` or `--since`. Dirty worktrees are allowed because the selected committed range is the review target. Accepted findings are printed to the terminal and written under `.neal/reviews/<review-id>/`.
+`--unattended` runs `neal plan`, `neal execute`, or `neal run` without waiting
+for an operator. See [docs/state-machine.md](docs/state-machine.md) for unattended
+blocks, manual gates, and resume behavior, and [docs/plan-format.md](docs/plan-format.md)
+for execution shapes and selected-plan handling.
 
-`neal squash` squashes run-owned commits for a completed plan. With no argument, it selects the latest completed execute-mode run with readable run-local state and uses that run's recorded plan doc. With a plan argument, it selects the latest completed execute-mode run for that plan. It preserves later commits added after the selected neal run by replaying them on top of the replacement squash commit. It previews the selected run, commit range, later commits to preserve, plan-document disposition, commit-message source, and generated semantic commit message, then requires interactive TTY confirmation before rewriting history. The replacement commit is signed when Git signing is configured for commits. Squash result artifacts keep Neal provenance separately from the Git commit message, including the run id, selected and normalized plan paths, plan-document disposition, replacement-tree inclusion, commit-message source, and commit-message subject.
+### Plan-free review
 
-`neal setup` configures explicit coder and reviewer provider defaults for fresh writer runs, with an optional planner override. It reports local runtime availability, writes `~/.neal/config.yml` by default, preserves unrelated user config, and recommends provider-owned authentication followed by `neal check` after writing.
+`neal review` has the coder propose findings and the reviewer judge them against
+already-committed work. Use `--last` or `--since` to choose the commit range and
+an optional message to focus the review. The drafting coder still has coder
+privileges, so neal checks the worktree after every provider call and fails if
+anything changed outside the review artifacts. This is useful for a coordinated
+multi-model review of a PR.
 
-`neal check` validates the effective config, reports the effective planner, coder, and reviewer provider/model choices, then prompts before making live provider connectivity calls. When the resolved **coder or reviewer** role uses a non-native (generic-agentic / openai-compatible) provider, it prints a one-line pointer to `neal compat`; native adapters (`openai-codex`/`anthropic-claude`) do not. (The planner inherits the coder provider by default, so the coder check already covers the common case; an explicitly configured non-native planner alongside native coder/reviewer is not separately flagged.)
+### Inspection and maintenance
 
-`neal compat` is a **compatibility smoke test, not a skill benchmark**: it answers whether an OpenAI-compatible model can drive neal's loop at all as a coder, reviewer, or planner. It reuses `neal check`'s structured pre-filter, then drives the candidate through complete neal runs against bundled trivial fixtures (`examples/compat/`) in throwaway git copies (it never mutates a committed fixture), and emits a binary PASS/FAIL matrix per (model, role) with a structural failure mode for each FAIL. `--model <slug>` runs the slug on the `generic-agentic` provider in the candidate role, and `--reference <id>` names a native provider (`openai-codex` default, or `anthropic-claude`) for the non-candidate roles so a FAIL is attributable to the candidate; `--role` defaults to `all`; `--json` prints a stable machine-readable matrix. It is fully self-contained — the only prerequisites are the neal repo and an API key — forces unattended mode so a model is never penalized for a resumable halt, and exits non-zero on an overall FAIL. See [docs/compat.md](docs/compat.md) for the PASS definition, failure-mode taxonomy, and `--json` schema, and [docs/compatible-models.md](docs/compatible-models.md) for the verified-model whitelist.
+`neal status` shows the current run, or all runs with `--all`. Its `--json`
+forms are the stable automation interface.
 
-`neal status` prints a human-readable summary by default. `neal status --all` lists writer runs from `.neal/runs/*/RUN_STATE.json`. `neal status --json` and `neal status --json --all` are the stable automation contracts. Runs waiting on manual gates report `effectiveStatus: "waiting_for_manual_gate"` and include a nullable `manualGate` summary with the gate instructions path and resume command.
+`neal squash` rewrites a completed run into one commit. It previews the change
+and requires interactive confirmation before rewriting history.
 
-`neal version` prints the package version.
+### CLI information
 
-`neal help`, `neal --help`, and `neal -h` print the supported usage surface, including the package version.
+`neal version` prints the package version. `neal help`, `neal --help`, and
+`neal -h` print the supported command surface.
 
-## Command Exit Codes
+## Command exit codes
 
 The writer commands `neal plan`, `neal execute`, `neal run`, and `neal resume`
 use this shell contract:
@@ -322,27 +364,27 @@ use this shell contract:
 - `0`: completed writer run, completed `neal run` queue, or resume selection
   that was already done.
 - `1`: invalid CLI usage, missing setup or configuration, pre-run Git/worktree
-  precondition failure, or another thrown error before Neal has a writer result.
+  precondition failure, or another thrown error before neal has a writer result.
 - `2`: controlled incomplete state: blocked, waiting for operator guidance,
   waiting for a manual gate, paused, already running under a live lock, or
   manual-gate resume checks still failing.
-- `3`: failed writer run or failed `neal run` queue after Neal has run
+- `3`: failed writer run or failed `neal run` queue after neal has run
   state/result evidence.
 
 Use `neal status --json` for the stable detailed automation interface. `neal
 status` exits `0` when it successfully reports status, even if the reported run
 is blocked, paused, waiting for guidance, waiting for a manual gate, or failed.
 
-## Terminal Output
+## Terminal output
 
 neal prints narrative-focused progress by default. The default stream says what the loop is doing at a human level, while raw provider detail, command output, session handles, and reviewer context are kept out of the normal terminal view.
 
 Interactive TTY writer runs accept live keys:
 
-- `q`: stop after the current scope
 - `v`: switch between narrative and low-level detail views
+- `q`: stop after the current scope during execution (`neal execute` or the execution portion of `neal run`)
 
-The read-only long-running `neal review` command also supports the `v` detail toggle. Toggling views is process-local terminal state only; provider prompts, run state, resume behavior, artifacts, and command semantics stay unchanged.
+The read-only long-running `neal review` command also supports the `v` detail toggle. Toggling views is process-local terminal state only. Provider prompts, run state, resume behavior, artifacts, and command semantics stay unchanged.
 
 Low-level detail is still persisted for debugging. Inspect `.neal/runs/<run-id>/stderr.log` and `.neal/runs/<run-id>/events.ndjson` for writer runs, or the corresponding review artifact directory for read-only review loops.
 
@@ -350,65 +392,15 @@ Low-level detail is still persisted for debugging. Inspect `.neal/runs/<run-id>/
 
 Config precedence is:
 
-1. repo `config.yml`
+1. repo `neal.yml`
 2. `~/.neal/config.yml`
 3. built-in defaults
 
-Fresh writer-run commands require explicit `agent.coder.provider` and `agent.reviewer.provider` settings from either user or repo config. The built-in defaults remain for compatibility paths, but they are not enough to start new plan, execute, run, or check workflows. If either role is missing, neal reports the missing config key. Use `neal setup` for first-time provider/model defaults; edit YAML manually only when you need precise control.
+Fresh writer-run commands require explicit `agent.coder.provider` and `agent.reviewer.provider` settings from either user or repo config. If either role is missing, neal reports the missing config key. Use `neal setup` for first-time provider/model defaults. Edit YAML manually when you need precise control.
 
-The checked-in [config.yml](config.yml) is a commented template. Machine-local overrides usually belong in `~/.neal/config.yml`.
-
-Manual writer-provider config shape:
-
-```yaml
-agent:
-  coder:
-    provider: openai-codex
-    model: null
-  reviewer:
-    provider: anthropic-claude
-    model: null
-```
+This repository has a commented template [neal.yml](neal.yml).
 
-In that simple config, the effective planner role inherits the coder provider
-and model:
-
-```yaml
-agent:
-  planner:
-    provider: openai-codex
-    model: null
-  coder:
-    provider: openai-codex
-    model: null
-  reviewer:
-    provider: anthropic-claude
-    model: null
-```
-
-`model: null` means "let the provider choose its default model." You can keep other settings, such as `neal.notify_bin`, in the same file. neal currently ships built-in writer-run adapters for OpenAI Codex and Anthropic Claude, plus two adapters for OpenAI-compatible Chat Completions endpoints: the reviewer-only `openai-compatible` adapter and the `generic-agentic` writer adapter, which runs the coder role through a neal-owned agentic loop and tool set and the reviewer role through a read-only subset of those tools. See [docs/providers.md](docs/providers.md) for the provider contract, capability checks, telemetry/error mapping, and testing checklist.
-
-The reviewer role can target an OpenAI-compatible endpoint with a `providers.openai_compatible` block (DeepSeek shown; config first, environment fallbacks `OPENAI_COMPATIBLE_BASE_URL`, `OPENAI_COMPATIBLE_API_KEY`, and `OPENAI_COMPATIBLE_MODEL`):
-
-```yaml
-providers:
-  openai_compatible:
-    base_url: https://api.deepseek.com
-    api_key_env: DEEPSEEK_API_KEY
-    default_model: deepseek-chat
-
-agent:
-  coder:
-    provider: openai-codex
-    model: null
-  reviewer:
-    provider: openai-compatible
-    model: deepseek-chat
-```
-
-`openai-compatible` is reviewer/structured-advisor only: coder or planner selection fails the capability check, it has no repository tool access (neal inlines diff and artifact context into reviewer prompts, so the reviewer cannot independently run verification), no session resume, and no `effort` support. Behavior, model quality, and rate limits vary by upstream provider.
-
-Advanced configs can override the planner independently:
+You can configure the planner independently:
 
 ```yaml
 agent:
@@ -426,13 +418,11 @@ agent:
 Each role also accepts an optional `effort` reasoning-depth override. Omitting it
 or setting `effort: null` keeps the provider default. Supported values are
 `minimal, low, medium, high, xhigh` for `openai-codex` and
-`low, medium, high, xhigh, max` for `anthropic-claude`; an unsupported value is
-rejected before a run starts. Planner effort inheritance mirrors planner model
-inheritance: the planner inherits the coder effort only when
-`agent.planner.provider` is not configured explicitly and `agent.planner.effort`
-is omitted. When `agent.planner.provider` is set explicitly, an omitted
-`agent.planner.effort` resolves to the provider default (`null`), so set
-`agent.planner.effort` explicitly to override it.
+`low, medium, high, xhigh, max` for `anthropic-claude`. An unsupported value is
+rejected before a run starts. `openai-compatible` doesn't currently support an
+effort override. Some compatible endpoints expose reasoning controls, but the
+accepted values and behavior vary by endpoint and model, so neal leaves them at
+the upstream default.
 
 ```yaml
 agent:
@@ -446,7 +436,7 @@ agent:
     effort: xhigh
 ```
 
-### Custom Guidance
+### Custom guidance
 
 neal supports additive guidance files for local preferences alongside the built-in protocol prompts:
 
@@ -454,13 +444,17 @@ neal supports additive guidance files for local preferences alongside the built-
 - `~/.neal/guidance/reviewer.md`
 - `~/.neal/guidance/planner.md`
 
-Set `NEAL_GUIDANCE_DIR=/path/to/guidance` to load those same `coder.md`, `reviewer.md`, and `planner.md` files from another directory. neal records applied guidance roles, selected paths, and byte counts in run artifacts; guidance contents stay out of terminal output.
+Set `NEAL_GUIDANCE_DIR=/path/to/guidance` to load those same `coder.md`, `reviewer.md`, and `planner.md` files from another directory. neal records applied guidance roles, selected paths, and byte counts in run artifacts. Guidance contents stay out of terminal output.
 
-## Artifacts And Storage
+## Artifacts and storage
 
 Writer run artifacts live under `.neal/runs/<run-id>/`, including the original-plan backup at `.neal/runs/<run-id>/PLAN_ORIGINAL.md` and reviewer scratch space under `.neal/runs/<run-id>/scratch/`. Queue artifacts live under `.neal/queues/<queue-id>/`. Review findings artifacts live under `.neal/reviews/<review-id>/`.
 
-Reviewer scratch is for temporary verification artifacts, copied tests, scratch builds, logs, and modified throwaway files. Root-level scratch directories such as `build_review/` are still ordinary project-tree dirtiness and must be cleaned up by the operator or committed through the normal accepted-scope flow.
+The run-local scratch directory is reserved for reviewer verification artifacts.
+Current built-in reviewer prompts are read-only and do not use it. Root-level
+scratch directories such as `build_review/` are still ordinary project-tree
+dirtiness and must be cleaned up by the operator or committed through the normal
+accepted-scope flow.
 
 Project-local `.neal/` is the source of truth for runs, queues, reviews, progress, and audit history. Keep `.neal/` ignored by Git. It may contain prompts, diffs, command output, local paths, provider responses, reviewer scratch files, copied tests, build logs, and project-specific context. Use `neal status --all` to discover run IDs, and use `--run <run-id>` to select a run for `resume` or `status`.
 
@@ -468,17 +462,16 @@ For what may (and may not) be published from a run as public automation or bench
 
 The storage layout, artifact classifications, run pointers, and retention guidance are documented in [docs/storage.md](docs/storage.md). Persisted run and queue state boundaries are documented in [docs/state-machine.md](docs/state-machine.md).
 
-## Known Limitations
+## Known limitations
 
-- Writer providers currently run with broad local permissions. See [docs/providers.md](docs/providers.md) and Safety Notes for the current provider permission boundaries.
-- neal stores project-local artifacts under `.neal/`. Those artifacts may contain prompts, diffs, command output, paths, provider responses, and local context; see [docs/storage.md](docs/storage.md) for artifact retention and privacy details.
-- External provider plugins are future work.
-- Provider accounts and authentication come from local provider SDK/CLI sessions.
+- Writer providers currently run with broad local permissions. See [docs/providers.md](docs/providers.md) and Safety notes for the current provider permission boundaries.
+- neal stores project-local artifacts under `.neal/`. Those artifacts may contain prompts, diffs, command output, paths, provider responses, and local context. See [docs/storage.md](docs/storage.md) for artifact retention and privacy details.
 
-## Plan Shape
+## Plan shape
 
 Every executable neal plan must declare exactly one execution shape in a literal `## Execution Shape` section.
-The full executable-plan format reference is [docs/plan-format.md](docs/plan-format.md).
+The full executable-plan format reference is [docs/plan-format.md](docs/plan-format.md). In practice you can just
+let neal format your plan into this shape.
 
 Use `executionShape: one_shot` when the full task can be implemented, reviewed, and verified as one bounded scope:
 
@@ -510,18 +503,22 @@ executionShape: multi_scope
 
 Use `executionShape: multi_scope_unknown` when the work repeats one bounded recurring slice at a time, but the total number of slices is intentionally unknown until a stop rule becomes true.
 
-## Safety Notes
+## Safety notes
 
 Writer commands can edit files and create commits in the target repository. Run neal in a disposable checkout, branch, worktree, container, or VM when the repository or provider credentials are sensitive.
 
-Current writer providers run with broad local permissions. The OpenAI Codex provider is configured with `approvalPolicy: never` and `sandboxMode: danger-full-access`; the Claude provider uses `permissionMode: bypassPermissions`. Treat planner and coder providers as capable of modifying the checkout unless you have added external sandboxing. The reviewer role is read-only — OS-sandboxed for the Codex reviewer, and enforced at the SDK/tool-wiring level for the others, so outside Codex the guarantee is only as strong as the adapter. Reviewers can also read files outside the repository unless the adapter jails reads (only `generic-agentic` does); see [SECURITY.md](SECURITY.md).
+Current writer providers run with broad local permissions. The OpenAI Codex provider is configured with `approvalPolicy: never` and `sandboxMode: danger-full-access`. The Claude provider uses `permissionMode: bypassPermissions`. Treat planner and coder providers as capable of modifying the checkout unless you have added external sandboxing. The reviewer role is read-only: OS-sandboxed for the Codex reviewer, and enforced at the SDK/tool-wiring level for the others, so outside Codex the guarantee is only as strong as the adapter. Reviewers can also read files outside the repository unless the adapter jails reads (only `openai-compatible` does). See [SECURITY.md](SECURITY.md).
 
-`neal execute` and `neal run` can create commits and rewrite run-owned commits into a final squash commit by default. Squashed commit messages are semantic summaries of the implemented project change; plan provenance is kept in Neal artifacts instead of commit subjects, bullets, or trailers. Repo-local nonignored selected plan documents may be included in the run's final tree when they changed. Ignored, missing, non-file, or outside-repository plan documents are metadata-only and are not force-added. `neal squash` rewrites history for plan-owned commits after printing a preview and receiving interactive confirmation. Neal rejects finalization and squash attempts that would include files matching `.gitignore` rules, even if those files were force-added.
+`neal execute` and `neal run` can create commits and rewrite run-owned commits into a final squash commit by default. Squashed commit messages are semantic summaries of the implemented project change. Plan provenance is kept in neal artifacts instead of commit subjects, bullets, or trailers. Repo-local nonignored selected plan documents may be included in the run's final tree when they changed. Ignored, missing, non-file, or outside-repository plan documents are metadata-only and are not force-added. `neal squash` rewrites history for plan-owned commits after printing a preview and receiving interactive confirmation. neal rejects finalization and squash attempts that would include files matching `.gitignore` rules, even if those files were force-added.
 
-Read-only commands are intentionally narrower: `neal status` and `neal review` skip the writer lock. `neal review` writes only review artifacts under `.neal/reviews/`.
+Read-only commands are intentionally narrower: `neal status` and `neal review` skip the writer lock. `neal review` owns only the review artifacts under `.neal/reviews/` and fails if a provider changes anything else. It does not clean up a provider's worktree changes.
 
-Roles carry very different privilege: the coder role (and the inherited planner) executes shell commands and writes files with your privileges in the working directory, while the reviewer role is structurally read-only, enforced per provider adapter. Running an unknown or untrusted model in the coder role — for example via `neal compat` against an arbitrary OpenAI-compatible / OpenRouter slug — grants that model coder-level shell access, so run untrusted models inside a container or disposable sandbox. See [SECURITY.md](SECURITY.md) for the full trust model and how to report a suspected vulnerability.
+Roles carry very different privilege: the coder role (and the inherited planner) executes shell commands and writes files with your privileges in the working directory, while the reviewer role is structurally read-only, enforced per provider adapter. Running an unknown or untrusted model in the coder role (for example via `neal compat` against an arbitrary OpenAI-compatible / OpenRouter slug) grants that model coder-level shell access, so run untrusted models inside a container or disposable sandbox. See [SECURITY.md](SECURITY.md) for the full trust model and how to report a suspected vulnerability.
 
 ## Notifications
 
-Notifications are opt-in. If `neal.notify_bin` is configured, neal runs that command with the notification text for `blocked`, `complete`, `done`, and `retry`. With no configured path, notifications stay disabled.
+Notifications are opt-in. If `neal.notify_bin` is configured, neal runs that command with one notification-text argument for `blocked`, `complete`, `done`, and `retry`. Messages start with `[neal] <planName>:` followed by the reason or status. Blocked and interactive-recovery retry messages append `| consultant advice (read-only): triage <category>; suggested directive: <directive>` when consultant advice is available.
+
+`NEAL_NOTIFY_BIN` overrides the configured command. Set it to another path to use that command, or set it to an empty value to disable notifications for the process. Notification command failures never fail or change the result of a run.
+
+`neal check` reports the resolved notification command and, in an interactive terminal, can send a test notification after confirmation.