@redue/cli 0.1.0-alpha.21 → 0.1.0-alpha.23

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.1.0-alpha.23 — 2026-10-26
+
+One command to set up REDUE with Claude Code, and one to undo it.
+
+- **`redue setup claude`** runs `init` (when there is no
+  `redue.config.json`), connects Claude Code, starts the observer, waits for
+  it to index the project, and records each check that can qualify once. It
+  asks once (`--yes` for no prompts), prints every file it writes, and a
+  second run changes nothing. It stops before writing when dependencies are
+  not installed or nothing can be set up.
+- **`redue remove`** undoes exactly what setup created: the integration (or
+  only this machine's hooks), the observer state, the local ignore line, and
+  the config if it is unchanged since setup wrote it. Anything that existed
+  before setup stays. Setup notes what it created in the clone's Git
+  directory, never in a committed file.
+- **Hooks find REDUE.** The Claude Code hooks name plain `redue` only when
+  the `redue` that your shell and a login shell find is this install;
+  otherwise they name this install's Node and entry by absolute path, so a
+  Claude Code started from an IDE or with a shorter PATH still runs it.
+  Checks the hook runs for the agent follow the same rule.
+- `init` keeps a typecheck that runs TypeScript 7's `tsc` (or `tsgo` from
+  `@typescript/native-preview`) recording-only and says why. The pnpm and
+  Yarn TypeScript recipes refuse TypeScript 7 with a clear reason instead
+  of an error from inside the compiler API.
+- The README is rewritten around a 5-minute quickstart, what REDUE covers
+  today (census qualifiers) and what it won't do.
+- Known limits, found by the stranger test: a Vitest run writes under
+  `node_modules/.vite`, which makes a direct TypeScript typecheck STALE until
+  it runs again; an installed file with a second hard link (esbuild's install
+  makes one) keeps the test check UNVERIFIED.
+
+- Contributors: the census can run every recipe (`--all-recipes`) and
+  counts direct TypeScript checks; its unrecorded-program check no longer
+  flags Yarn's temporary `node` wrapper; `eval/stranger.mjs` runs fresh
+  Claude Code sessions that set REDUE up from the README alone.
+
+## 0.1.0-alpha.22 — 2026-10-25
+
+A correctness fix for recorded runs. Earlier alphas could report CURRENT for
+a script that replaced itself with another program.
+
+- **Fixed: a script that replaced itself with another program could be
+  CURRENT.** Node's `process.execve` (Node 22.15 and later) swaps a process
+  for another program under the same PID. The recorder did not see it, so
+  that program ran unseen. TypeScript 7's `tsc` does this to start its
+  native compiler, so alphas 19 to 21 could report a TypeScript 7 typecheck
+  as CURRENT while REDUE saw none of what the compiler did. The general
+  recipe and the direct test recipe now judge the new program like any
+  program a run starts: TypeScript 7's `tsc` makes the run UNVERIFIED and
+  names it. Support for TypeScript 7 is planned.
+- Runs that use Node's bindings with file, network or program access
+  (`process.binding('fs')`, `'spawn_sync'` and others), or run Node with
+  `--expose-internals`, are UNVERIFIED: the recorder cannot follow them.
+- Direct test recipe: a shell a test starts is read by its command, as in the
+  general recipe. One that runs another program before it becomes Node makes
+  the run UNVERIFIED.
+- General recipe, on Linux: pnpm 12 writes a file with no name in
+  `node_modules` when it rewrites its workspace state, which left the first
+  run after an install UNVERIFIED. That file now counts as the run's output
+  when the pnpm executable ran and no file has its name. Known limit: another
+  program's file with no name there, during such a run, is taken as pnpm's.
+- UNVERIFIED reasons for an input that changed during a run name up to five
+  files and a count of the rest.
+
+- Contributors: the census traces each run on Linux and flags programs the
+  recorder missed.
+
 ## 0.1.0-alpha.21 — 2026-10-25
 
 `init` finds more typecheck scripts and no longer stops in large monorepos.

package/README.md

@@ -1,229 +1,146 @@
 # REDUE
 
-Maintainer notice: alpha.4 withdraws automatic npm-launcher applicability.
-Npm commands still execute and record historical outcomes, but remain UNVERIFIED.
-[Why this changed and how to upgrade without deleting receipts](docs/user/npm-launcher-notice.md).
-Alpha.2 users should also review the [receipt correction](docs/user/receipt-selection-notice.md).
+**Know which checks still hold. Redo what's due.**
 
-**Know what still holds. Redo what's due.**
+You or your coding agent ran the typecheck, the linter or the tests. Then the
+code changed, or a new agent session started with no memory of it. REDUE
+records each check's result with the exact inputs it ran on, and tells you and
+your agent whether that result still applies to the code you have now, so a
+check that still holds is not run again and one that is stale is.
 
-You ran the checks. Then the code changed—or a new coding agent started with no
-conversation history. Which results can you still use?
+## Quickstart (about 5 minutes)
 
-REDUE keeps persistent verification state for your codebase so developers and
-coding agents can see which previous checks still apply to the code they have now.
-It records evidence, not proofs of correctness.
-
-For a qualified direct-compiler or supported Yarn/pnpm check (ordinary npm scripts are recording-only):
-
-```text
-$ redue status --sync
-✓ typecheck  CURRENT / PASS
-? test  UNVERIFIED / PASS
-  Recording-only: test runtime, transforms and cache inputs need review
-
-# Later, after a relevant edit:
-$ redue explain typecheck
-typecheck: STALE / PASS
-src/main.ts changed
-Relevant inputs changed:
-  src/main.ts
-Due again when verification is needed: redue run "typecheck"
-```
-
-Agent A verifies and exits. Agent B starts fresh. The receipt is still there;
-REDUE checks whether it still applies. Unrelated documentation edits can preserve
-it; relevant source edits make it stale. [Run the reproducible demo](docs/contributor/demo.md).
-
-## Install the alpha
-
-The opt-in pilot uses **0.1.0-alpha.18**. Follow the
-[fixed-version pilot guide](docs/user/pilot.md) for supported projects, setup,
-updates and voluntary feedback. No external usage results are claimed yet.
-
-
-REDUE is published on npm as `@redue/cli`. The installed command is `redue`.
+You need macOS or Linux, Node 22 or 24, Git, Claude Code, and a JavaScript or
+TypeScript project with its dependencies installed (`npm install`,
+`pnpm install` or `yarn`). On Linux, also Python 3.
 
 ```sh
 npm install --global @redue/cli@alpha
+cd your-project
+redue setup claude
 ```
 
-To test a source candidate, run `npm ci` and `npm pack --json`, then install the
-reported tarball filename with `npm install --global ./<filename>`.
-
-Use a Node installation you own; REDUE does not need administrator privileges.
-If a global prefix is not writable, use a user-owned `--prefix` or run the
-installed CLI with Node. [Installation and removal](docs/user/getting-started.md)
-includes PowerShell and isolated-prefix instructions.
-
-Inside an existing, trusted Git project with dependencies already installed:
-
-```sh
-cd my-project
-redue init
-redue start
-redue run typecheck  # use a check name printed by init
-redue status
-```
+`setup` shows what it will do and asks once (`--yes` skips the question). It
+stops before writing anything if the dependencies are not installed. It:
 
-`init` discovers existing scripts, explains which can qualify and which are
-recording-only, and writes a small `redue.config.json`. It never runs your checks
-or changes your package manager, source, scripts, or dependencies. Commit the
-reviewed project config; local evidence stays outside the checkout.
+- finds your typecheck, lint and test scripts and writes `redue.config.json`
+  (it never changes your scripts, source or dependencies). Checks REDUE can
+  only record, not reuse, are listed as recording-only;
+- connects Claude Code: a short section in `CLAUDE.md`, a skill, and two hooks
+  in `.claude/settings.local.json`;
+- starts REDUE's file observer, waits while it indexes the project (a minute
+  or more in a large one), then runs each check that can qualify once, so
+  there is a first result to reuse;
+- prints every file it writes. Running it again changes nothing.
 
-Start with ordinary `status`. When it cannot establish caller context, use
-`redue status --sync` if that is worthwhile—or just rerun an inexpensive check.
-**Synchronization can cost more than rerunning a cheap check, particularly on
-Windows.** REDUE does not choose or execute that tradeoff for you.
+Then start a new Claude Code session in the project and work as usual. When
+the agent is about to rerun a check whose last pass still applies, the hook
+skips it and tells the agent why. After an edit, the hook runs the check
+through REDUE so the new result is recorded.
 
-`init` tries the strict recipes first: the [direct compiler recipe](docs/user/direct-typescript.md)
-for npm typechecks, the pnpm and Yarn TypeScript recipes, and the
-[direct test recipe](docs/user/tests-direct.md). A root typecheck or lint
-script none of them takes can use the [general recipe](docs/user/node-script.md),
-which runs the script through the package manager and records every Node
-process; a script that starts another program (git, esbuild, turbo) stays
-UNVERIFIED and the reason names it. Test scripts use the direct test recipe
-(Vitest, Jest); other test scripts stay recording-only.
+To look yourself:
 
-## Connect your agent (experimental)
+```text
+$ redue status --sync
+✓ typecheck  CURRENT / PASS
+✓ lint  CURRENT / PASS
 
-```sh
-redue agent setup codex --dry-run
-redue agent setup codex --apply  # or claude
-redue agent doctor
+# after editing src/main.ts
+$ redue explain typecheck
+typecheck: STALE / PASS
+src/main.ts changed
+Due again when verification is needed: redue run "typecheck"
 ```
 
-Start a fresh agent session and give it an ordinary task. Project-local guidance
-teaches it to inspect evidence before deciding whether verification needs repeating.
-Setup is explicit, reversible, and does not change tool permissions or run checks.
-[Activation, removal, and generic-agent guidance](docs/user/agents.md).
-
-The experimental claim is **opt-in project-local agent activation and direct TypeScript
-evidence, with fresh-session reuse demonstrated in the tested Codex/macOS
-configuration and measured for Claude Code below**. Cross-host reuse is not
-tested. This is experimental guidance, not guaranteed agent compliance, general
-sandbox compatibility, or a promise of time savings.
-
-### Measured with Claude Code
-
-Four public TypeScript projects, four tasks each, three sessions per task with
-and without REDUE: 96 headless Claude Code sessions (Sonnet 5.5, CI Linux
-runner, alpha.12 code, October 2026). Plain `tsc --noEmit` takes 10–19 s on
-these projects. Medians per task, summed over the four projects:
-
-| Task | Session time, without → with REDUE | Input tokens | Typechecks skipped |
-|---|---|---|---|
-| Docs edit, then "make sure it still typechecks" | 97 → 45 s | 169k → 162k | 12 of 12 |
-| "Does it still typecheck?" after a pull | 74 → 22 s | 117k → 89k | 12 of 12 |
-| Source change, typecheck, then a docs edit | 141 → 112 s | 210k → 200k | 9 of 12 |
-| Source change with tests | 152 → 151 s | 269k → 234k | 0 of 12 |
-| **All tasks** | **464 → 330 s** | **765k → 685k** | 33 |
-
-- **Correctness:** every typecheck REDUE skipped was checked afterwards with
-  plain tsc on the exact tree it was skipped on. All 33 agreed, and all 96
-  final trees passed plain tsc and the task checks in both arms.
-- **Cost:** API cost was the same ($0.65 without, $0.66 with). One-time setup
-  per checkout was 3–5 s, plus one recorded typecheck; the CLAUDE.md section
-  REDUE adds is about 60 tokens.
-- **How:** each session gets a fresh clone at a pinned commit; the REDUE arm
-  first runs `redue init`, `agent setup claude`, `start` and one
-  `redue run typecheck`, standing for an earlier session's passing check.
-  The harness, tasks and raw results are in [`eval/`](eval/README.md).
-- **Limits:** four projects and three runs per cell show direction, not a
-  general rate. Savings come only when an earlier pass still applies: tasks
-  that change source code save nothing, and on one project the docs edit came
-  after source edits that made the result STALE, so nothing was skipped. The
-  projects were chosen because they qualify for the direct TypeScript recipe;
-  of 38 screened projects, 19 qualified at alpha.12 and 22 at alpha.13. Times are agent session
-  time only, on one runner type.
-
-### Unit tests, measured with Claude Code
-
-Three public projects (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio
-with Jest 29), four tasks each, three sessions per task with and without REDUE:
-72 headless Claude Code sessions (Sonnet 5.5, CI Linux runner, alpha.14 code,
-October 2026), using the opt-in [direct test recipe](docs/user/tests-direct.md).
-Medians per task, summed over the three projects:
-
-| Task | Session time, without → with REDUE | Input tokens | Test runs skipped |
-|---|---|---|---|
-| Docs edit, then "make sure the unit tests still pass" | 95 → 41 s | 131k → 121k | 9 of 9 |
-| "Do the unit tests still pass?" after a pull | 80 → 22 s | 62k → 63k | 9 of 9 |
-| Source change, tests, then a docs edit | 171 → 111 s | 224k → 213k | 3 of 9 |
-| Source change with tests | 169 → 120 s | 172k → 164k | 0 of 9 |
-| **All tasks** | **515 → 295 s** | **589k → 559k** | 21 |
-
-- **Correctness:** every skipped test run was rerun plainly three times on the
-  exact tree it was skipped on; all 21 passed every time. All 72 final trees
-  passed the tests and the task checks in both arms.
-- **Limits:** one run of three projects shows direction, not a rate. The
-  source-change task skipped nothing; its time difference is session variance.
-  In two mixed-task sessions the agent left out its final test run on its own
-  after a README-only edit, without asking REDUE, and said so; the eval report
-  lists such sessions. Since alpha.15 the agent instructions ask agents to run
-  the check and leave skipping to REDUE; in a 12-session rerun of that task,
-  no agent left it out. Cost was the same ($0.54 without, $0.56 with).
+`--sync` checks the files and your environment before it answers; this is
+what the agent asks. Plain `redue status` is a fast cached answer and can say
+UNVERIFIED ("cannot confirm your execution context") where `--sync` would say
+CURRENT.
+
+To undo everything setup did: `redue remove`.
+
+## What it covers today
+
+In a census of 120 active public TypeScript repositories (October 2026, REDUE
+at commit c9034e5, just after 0.1.0-alpha.22), 89 installed cleanly. A check
+counts when two recorded runs on the same code both came out CURRENT on the
+same inputs. 31 repositories had at least one such check:
+
+| Check | Repositories | How |
+|---|---|---|
+| Typecheck | 22 | 16 by running the project's script with every Node process recorded ([general recipe](docs/user/node-script.md)); 6 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)) |
+| Lint | 18 | general recipe |
+| Tests | 2 | Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
+
+Everything else stays UNVERIFIED, with a reason you can read in
+`redue explain`. The usual ones: a script starts a program REDUE cannot see
+into (esbuild, turbo, nx, oxlint's tsgolint, TypeScript 7's native compiler),
+the project uses Bun, or a test suite writes into its own inputs. Two you may
+meet right after setup: a Vitest run writes its results under
+`node_modules/.vite`, which the direct TypeScript recipe counts as an
+installed input, so the typecheck turns STALE until it runs again; and an
+installed file with a second hard link (esbuild's install makes one) keeps
+the test check UNVERIFIED.
+[Supported projects](docs/user/supported-projects.md) has the details.
+
+## Measured with Claude Code
+
+Headless Claude Code sessions (Sonnet 5.5, CI Linux runner) on the same tasks
+with and without REDUE, three sessions per task. Session time, medians per
+task summed over the projects:
+
+- **Typecheck** (twilio-node, semiotic, Ultra-Card, SwitchHosts; four tasks;
+  96 sessions; 0.1.0-alpha.12 code): 464 s without, 330 s with. REDUE skipped
+  33 typechecks. Each was checked afterwards with plain `tsc` on the exact tree
+  it was skipped on, and all 33 agreed.
+- **Unit tests** (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio-node
+  with Jest 29; four tasks; 72 sessions; 0.1.0-alpha.14 code): 515 s without,
+  295 s with. REDUE skipped 21 test runs. Each was rerun plainly three times on
+  the exact tree, and all passed every time.
+
+API cost was the same in both arms. The savings come only when an earlier
+pass still applies: a task that changes source code saves nothing. A handful
+of projects and three runs per task show direction, not a general rate. The
+harness, tasks and raw results are in [`eval/`](eval/README.md).
+
+## What REDUE won't do
+
+- **Prove your code is correct.** CURRENT means the inputs of the recorded
+  run are unchanged, not that the code works. A failure stays a failure.
+- **Run checks for you.** Nothing runs in the background; checks run when you
+  or the agent run them.
+- **Trust what it cannot see.** A program it cannot account for, a file it
+  does not observe, or a gap in observation makes the result UNVERIFIED and
+  says why. It never turns that into CURRENT by guessing.
+- **Support yet:** TypeScript 7's native compiler, Bun, per-package checks in
+  large monorepos, results shared across machines, and the general recipe on
+  Windows (Windows has the strict recipes only).
 
 ## What the states mean
 
-| State | Meaning | Normal next step |
+| State | Meaning | Next step |
 | --- | --- | --- |
-| CURRENT | The recorded result applies to the declared inputs. | Reuse a passing result; do not rerun merely for freshness. |
-| STALE | Relevant inputs changed since the recorded result. | Rerun when verification is needed. |
-| UNVERIFIED | Applicability is unknown: no receipt, incomplete coverage, pending observation, or missing context. | Read the reason; synchronize if worthwhile, or run the check. |
-| FAILED | The invocation failed. Its applicability is tracked separately. | Keep the failure visible; it is not green evidence. |
-
-A historical PASS remains PASS when stale or unverified. A historical failure
-never becomes a successful check. CURRENT does not mean every product behavior
-has been verified.
-
-## Supported alpha path
-
-- macOS, Linux, and Windows on supported local filesystems; Node 22+.
-- Linux also requires Python 3 for observation. No WSL or Git Bash needed on Windows.
-- npm, pinned Yarn `node-modules`, and pinned pnpm 12 isolated/hoisted layouts.
-- Automatic qualification for supported Yarn/pnpm TypeScript invocations; ordinary npm
-  launcher checks remain recording-only. Explicitly select the
-  [direct local compiler recipe](docs/user/direct-typescript.md) for the reviewed
-  npm/TypeScript boundary. Workspace
-  boundaries follow the files actually consumed, including built declarations.
-- Opt-in [direct test recipe](docs/user/tests-direct.md) for Vitest 4/5 and
-  Jest 29 in single-package npm projects on macOS and Linux.
-- Other test/lint/build and arbitrary commands can record results while
-  their applicability remains unqualified.
-
-The [supported-project boundary](docs/user/supported-projects.md) is deliberately
-narrow. A script named `test` is not automatically a complete test contract.
-
-## Alpha limitations
-
-- REDUE records evidence; it does not prove correctness.
-- Direct commands outside `redue run` do not create receipts.
-- Some tests, lints, and builds remain UNVERIFIED/PASS because their input contract is incomplete.
-- Synchronized applicability has nontrivial cost and can lose to an inexpensive rerun.
-- Unsupported/exotic install layouts and filesystems remain conservative; they do not become green through guesses.
-- No cloud/team synchronization, IDE extension, or automatic background check execution.
-- Alpha configuration and APIs may evolve. Neither cached nor synchronized status is an atomic snapshot against concurrent edits.
-
-## Humans, shells, and agents
+| CURRENT | The recorded result applies to the code as it is now. | Reuse a pass; no need to rerun. |
+| STALE | An input changed since the recorded result. | Rerun when you need the answer. |
+| UNVERIFIED | REDUE cannot tell: no result yet, an input it cannot see, or observation not ready. | Read the reason; rerun if it matters. |
+| FAILED | The last run failed: the check ran and reported a failure, or could not run. | Fix and rerun. |
+
+## Without Claude Code, or step by step
 
 ```sh
-redue explain typecheck          # synchronized explanation; may run read-only probes
-redue status --json              # conservative cached data
-redue status --sync --json       # caller-aware decision
-redue status --short             # small cached indicator; never synchronizes
-redue stop                      # retains historical receipts
-redue remove-state              # removes only this config's owned local state
+redue init          # write redue.config.json from your scripts
+redue start         # start the file observer
+redue run typecheck # run a check through REDUE and record the result
+redue status --sync # what still holds
 ```
 
-Agents should use [the documented JSON interface](docs/user/json.md), not parse
-terminal prose. [The canonical agent loop](docs/user/agents.md) keeps the
-sync-versus-rerun choice explicit. [Shell usage](docs/user/shell.md) does not put
-synchronized work in a prompt.
+Codex is supported too (`redue agent setup codex --apply`); see
+[agents](docs/user/agents.md). Agents should read
+[the JSON interface](docs/user/json.md), not the terminal text.
 
-[User docs](docs/README.md) · [Contributing](CONTRIBUTING.md) ·
-[Architecture](docs/contributor/architecture.md) · [Acceptance evidence](docs/acceptance/README.md)
+[Getting started](docs/user/getting-started.md) · [User docs](docs/README.md) ·
+[Contributing](CONTRIBUTING.md) · [Architecture](docs/contributor/architecture.md)
 
 ## License
 
-REDUE is licensed under [Apache-2.0](LICENSE). Dependencies retain their own licenses.
+REDUE is licensed under [Apache-2.0](LICENSE). Dependencies keep their own licenses.

package/bin/redue.mjs

@@ -28,6 +28,9 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
+  setup claude [--yes] Set up REDUE and Claude Code in this project in one step:
+                       init, agent setup claude, start, one recorded run per check
+  remove [--yes]       Undo setup: integration, observer state, and the config setup created
   init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script]
                        Discover existing scripts; optionally select one workspace/check
   agent setup codex|claude [--dry-run|--apply] [--json]
@@ -58,7 +61,18 @@ if(args.length===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
   await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
 }
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
+// Internal: the entry this command runs, so setup and the hook can tell
+// whether the `redue` on PATH (a link, a package manager's shim, a wrapper)
+// is this install.
+if(args.length===1&&args[0]==='--entry'){console.log(fs.realpathSync(fileURLToPath(import.meta.url)));process.exit(0);}
 if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);await exit(0);}
+if(args[0]==='setup'||args[0]==='remove'){
+  // Loaded on demand; setup works before a config exists.
+  const {setupCommand}=await import('../src/setup.mjs');
+  try{await setupCommand(args,{entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  await exit(0);
+}
 let configFile=null,stateOverride=null;
 for(let i=0;i<args.length;){
   if(args[i]==='--config'||args[i]==='--state-dir'){
@@ -124,7 +138,7 @@ if(command==='init'){
     checks:discovery.checks.map(({config:check,level,reason})=>({name:check.name,
       script:check.script||null,command:check.command||null,
       workspace:check.workspace||null,level,reason})),config:configFile,
-    written:willWrite,existing:configured};
+    written:willWrite,existing:configured,writable:!configured&&!unsupported&&discovery.checks.length>0};
   if(!json) {
     console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
       `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);

package/docs/user/agents.md

@@ -74,10 +74,18 @@ observer when a session starts (below); otherwise use `redue start`.
 
 ## Claude Code typecheck hook
 
-`redue agent setup claude --apply` also adds a PreToolUse hook and a
-SessionStart hook to `.claude/settings.local.json`. Both run
-`redue agent hook claude`, which needs a local REDUE install, so they are
-per-developer; keep that file out of commits. Other settings in the file are kept,
+`redue agent setup claude --apply` (and `redue setup claude`) also adds a
+PreToolUse hook and a SessionStart hook to `.claude/settings.local.json`.
+Both run `redue agent hook claude`, which needs a local REDUE install, so
+they are per-developer; keep that file out of commits. Setup names REDUE
+plainly only when the `redue` that both your shell and a login shell find on
+PATH is the install running setup. Otherwise the hooks name this install's
+Node and entry by absolute path, so a Claude Code started from an IDE, a
+desktop app or another shell still runs the right REDUE; run setup again
+after moving or upgrading Node. `redue agent doctor` reports a hook whose
+paths no longer exist. When the hook runs a check through REDUE for the
+agent, it likewise writes plain `redue run` only if its own PATH finds this
+install, else the absolute form. Other settings in the file are kept,
 but the file is rewritten as 2-space JSON. `.claude/settings.json` is not touched.
 `redue agent remove claude --apply` removes only the entries REDUE added.
 

package/docs/user/direct-typescript.md

@@ -7,7 +7,9 @@ not mean npm or npm lifecycle scripts completed.
 For a supported single-package npm project with a typecheck script of `tsc`
 runs (see [script forms](#script-forms)) or no typecheck script and a root
 `tsconfig.json`, installed dependencies, Node 22/24 and TypeScript 5.x or 6.0
-(see [compiler identity](#compiler-identity)):
+(see [compiler identity](#compiler-identity)). TypeScript 7 is a native
+compiler this recipe cannot run: `init` refuses it
+(`direct-typescript-version-unsupported`):
 
 ```sh
 redue init --recipe typescript-direct --check typecheck --dry-run

package/docs/user/getting-started.md

@@ -67,7 +67,26 @@ the package alone does not update project instructions.
 
 ## First project
 
-From the project root:
+With Claude Code, one command does the steps below and connects the agent:
+
+```sh
+redue setup claude          # asks once; --yes for no prompts
+```
+
+It runs `init` when the project has no `redue.config.json`, `agent setup
+claude`, and `start`, then records each check that can qualify once, unless
+it is already CURRENT. It prints every file it writes, and running it again
+changes nothing that is already set up. When `.claude/settings.local.json`
+is not ignored by Git, it adds it to `.git/info/exclude`; it refuses when
+that file is committed. What setup created is noted in the clone's Git
+directory (`.git/redue-setup-<id>.json`, never committed). `redue remove`
+undoes exactly that: the integration (or only this machine's hooks, when the
+integration was already in the project), the observer and its state
+(receipts included), the local ignore line, and the config if setup wrote it
+and it has not been edited since. A config or observer state that existed
+before setup stays. `remove` asks before it deletes; Enter means no.
+
+Step by step, from the project root:
 
 ```sh
 redue init --dry-run

package/docs/user/node-script.md

@@ -69,12 +69,16 @@ anywhere in it.
 
 Two installed files are rewritten by tools during a run. pnpm rewrites
 `node_modules/.pnpm-workspace-state-v1.json` at the first run after an
-install, through a temporary `node_modules/.tmpXXXXXX` file. vue-tsc writes
+install, through a temporary `node_modules/.tmpXXXXXX` file, and on Linux
+writes a file with no name there (`O_TMPFILE`), whose writes the file
+watcher reports as `node_modules/#NUMBER`. vue-tsc writes
 `node_modules/.vue-global-types/*.d.ts` before it reads them. These files stay
 inputs. When they are the only files a run changed, and the run wrote them,
 the result is kept with the files as the run left them. A recorded process
 counts as writing a file it wrote; for pnpm's files, the pnpm executable must
-have run. A later change to them makes the result STALE.
+have run. A `#NUMBER` event counts only directly in the root `node_modules`,
+on Linux, when no file has that name. A later change to them makes the
+result STALE.
 
 It does not mean a rerun would give the same result: a test that depends on
 the time or on randomness can pass now and fail later on the same inputs.
@@ -107,6 +111,13 @@ one REDUE can account for:
   content;
 - `ps -A -o ppid,pid`, which pnpm loaded into Corepack runs.
 
+A process that replaces itself with another program through
+`process.execve` (TypeScript 7's `tsc` does this to start its native
+compiler) is judged the same way as a program it starts. `init` reads
+TypeScript 7's launchers (`tsc` from `typescript@7`, `tsgo` from
+`@typescript/native-preview`) as that native compiler and keeps such a script
+recording-only.
+
 Anything else makes the result UNVERIFIED and names the program: `git`,
 `sleep`, `find`, and native programs from installed packages such as esbuild,
 turbo, tsgo, tsgolint and biome, whose reads, writes and network use REDUE
@@ -142,11 +153,19 @@ inputs.
   run (pnpm 12 does this) can be reported by the file watcher as an event on
   the root itself, an observation gap that makes the run UNVERIFIED. Linux
   reports the file, which is not an input.
+- On Linux, any program's file with no name in the root `node_modules`,
+  written during a run that started the pnpm executable, is taken as pnpm's.
+  If that program gives the file a real name (any name, `node_modules`
+  included) and then writes through the open file, REDUE misses those
+  writes. A real file named `node_modules/#NUMBER` that is created and
+  removed within such a run is treated the same way. Outside a pnpm run,
+  these writes leave the run UNVERIFIED.
 - The pnpm executable and the pnpm launchers' helpers are trusted as
   toolchain: what they read is not checked.
 - Code that copies the environment and reads the copy, and native code that
-  reads files or variables (native addons such as Rust-based resolvers), is
-  not seen.
+  reads files or variables or starts programs (native addons such as
+  Rust-based resolvers), is not seen. Neither are files opened by
+  `node:sqlite` or preopened for `node:wasi`.
 - A project whose `.npmrc` sets `node-options` stays UNVERIFIED: npm replaces
   `NODE_OPTIONS` with it, which drops REDUE's recorder.
 - A script that runs a build first (`npm run build && tsc --noEmit`) usually

package/docs/user/supported-projects.md

@@ -83,7 +83,11 @@ entries stay inputs: an import can still reach an excluded file); a file the
 program reads outside them keeps the check recording-only. This avoids pnpm's task-run bookkeeping
 writes during `pnpm run`; it does not alter the project's script. Test, lint,
 build, and ambiguous TypeScript scripts still execute through `pnpm run`; root
-typecheck and lint ones can use the [general recipe](node-script.md). The generated `@typescript-bin:WORKSPACE` token resolves
+typecheck and lint ones can use the [general recipe](node-script.md). The pnpm
+and Yarn TypeScript recipes read TypeScript's compiler API, which TypeScript 7
+does not ship: with TypeScript 7 installed they refuse and say so. The
+general recipe runs such a script, but TypeScript 7's native compiler is a
+program REDUE does not record, so the result is UNVERIFIED. The generated `@typescript-bin:WORKSPACE` token resolves
 the local compiler when the check runs; it is not an absolute machine path.
 
 The pnpm contract indexes consumed installed package contents inside the

package/docs/user/tests-direct.md

@@ -80,7 +80,14 @@ kept but marked UNVERIFIED, with the reason, when the run:
 - connected to anything other than loopback or a local socket, or asked DNS
   about a name other than localhost;
 - started a process that did not load the recorder: a shell, a binary, or a
-  Node process with its own environment;
+  Node process with its own environment. A process that replaces itself with
+  another program (`process.execve`) counts as starting it, and it must
+  become a recorded Node process. A shell is read by its command, as the
+  [general recipe](node-script.md#programs) reads it: one that runs another
+  program before it becomes Node counts too;
+- used one of Node's bindings with file, network or program access
+  (`process.binding('fs')`, `'spawn_sync'` and others), or ran Node with
+  `--expose-internals`: the recorder cannot follow those;
 - had an installed file with another hard link, other than a link into the
   pnpm store the install recorded in `node_modules/.modules.yaml` (pnpm's
   default on Linux). A change through a link elsewhere, such as Yarn's