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

package/docs/user/agents.md

@@ -1,20 +1,29 @@
 # Agent decision policy
 
-Use the CLI; no SDK or bespoke agent integration is required. Add these
-instructions to a session or project only with its owner's permission.
-
-1. Query ordinary `redue status --json` first.
-2. If a check has `freshness: "CURRENT"`, `result: "PASS"`, and
-   `reuse_eligible: true`, reuse it. Do not rerun merely for freshness.
-3. If STALE, run `redue run CHECK` when that verification is needed.
-4. If the historical `result` is FAIL, report it honestly. The human CLI calls
-   this FAILED; applicability is a separate field, never an excuse to call it green.
-5. If UNVERIFIED, inspect its reason. Use `status --sync --json` when establishing
-   applicability is worthwhile, or rerun the underlying check when cheaper/simpler.
-   Use `redue run CHECK` if a new receipt is wanted. Incomplete coverage can remain
-   UNVERIFIED even after success.
-6. Do not assume synchronization is cheaper than execution. There are no universal
-   package-manager or OS thresholds. Inexpensive checks may be cheaper to rerun.
+Use the CLI with explicit project-local activation below, or add this policy to a
+generic agent's instructions with the project owner's permission.
+
+1. If fresh execution is already required, execute it; do not synchronize merely
+   to confirm an irrelevant reuse opportunity. Use `redue run CHECK` when recording
+   the configured check. An explicit npm-script request still requires npm.
+2. For reuse of the explicitly configured direct compiler recipe
+   (`qualification: "npm-typescript-direct-v1"`, direct compiler command; receipt
+   `verification_recipe: "npm-direct-typescript@1"`), query once:
+   `redue --config CONFIG status --sync --json`. Do not infer a recipe from its name.
+   Cached status cannot establish its caller context. In mixed configurations,
+   assess each check's contract separately; this is not a global sync-first policy.
+3. For other/unknown recipes, query ordinary `status --json` first and decide whether
+   synchronization is worthwhile. Ordinary status and `--short` remain cheap inspection.
+4. Reuse only schema 1, healthy observation and the selected check's CURRENT/PASS
+   with `reuse_eligible: true`. Missing eligibility means false. A historical FAIL
+   is never green evidence. Do not rerun eligible evidence merely for freshness.
+5. STALE requires execution when verification is needed. UNVERIFIED requires an
+   honest choice of synchronization, permitted execution or reporting the limitation.
+   Recording-only success can remain UNVERIFIED. A deliberate cheap-check rerun is
+   permitted; there are no universal platform/package-manager timing thresholds.
+6. Use a successful synchronized response for the current decision without repeated
+   sync/explain calls unless edits, context changes or missing information require it.
+   Do not loop until green or use an earlier response after a later query fails.
 
 `redue explain CHECK --json` gives synchronized detail, including a known changed
 input when available. It has the same cost caveat as synchronized status.
@@ -25,8 +34,283 @@ check is not universal product correctness. Report additional uncaptured checks
 separately. Do not infer that an outer invocation's success proves a specific
 check ran or that an upstream cache was hit; inspect `target_provenance`.
 
+Reassess at the decision point after edits or context changes; previous CURRENT is
+not continuing authorization. A status exit code of zero is not proof of CURRENT.
+An empty changed-input list does not prove nothing changed. `run CHECK --json`
+streams check output; use a subsequent status/explain query for structured evidence.
+Explicit fresh-execution requests still require execution.
+
 On a CLI error, unhealthy observation, or unavailable context, do not infer
 CURRENT. Do not delete state or reset receipts to make the output green.
 
 REDUE tells you what evidence exists and whether it still applies. It does not
 promise that establishing applicability is cheaper than every possible check.
+
+## Connect once (experimental)
+
+Alpha.5 and later support opt-in project-local activation and direct
+TypeScript evidence, with fresh-session reuse demonstrated for Codex CLI 0.160.1
+and subsequent 0.162.0 trials on macOS under the documented owner-approved checkout/state/socket route. CLI
+mechanics are tested on macOS/Linux/Windows; model behavior is not claimed for
+every host/platform or sandbox policy. Claude setup/removal mechanics are tested,
+but Claude behavior and cross-host reuse remain untested. Reuse is not guaranteed,
+and the existing subsecond example establishes no meaningful net time saving.
+
+After installing REDUE and running `redue init` in a trusted project:
+
+```sh
+redue agent setup codex --dry-run
+redue agent setup codex --apply
+# Or: redue agent setup claude --apply
+redue agent doctor
+```
+
+Start a fresh agent session in this checkout, then give it your ordinary task.
+Interactive setup shows the changes and asks before applying; noninteractive
+setup requires `--apply`. `--dry-run` never writes. Installing REDUE or running
+`init` does not connect an agent automatically. Setup does not start an observer
+or execute verification. With Claude Code, a SessionStart hook starts the
+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,
+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.
+
+When a session starts, resumes, clears or compacts, the SessionStart hook starts
+this project's observer if none is running. It launches `redue start` in the
+background and returns at once, and prints nothing, so it adds nothing to the
+agent's context. Until the observer's first index is done, checks are
+UNVERIFIED and run as typed. An observer you stopped with `redue stop` starts
+again with the next session; remove the hook to prevent that. Setups from
+alpha.15 or earlier get the hook by running `redue agent setup claude --apply`
+again.
+
+The hook skips an exact rerun of a configured typecheck (a check with
+`kind: "typecheck"` or named `typecheck`) or direct test check. It matches
+these commands, run from the project root:
+
+- `redue run CHECK`, or `redue --config FILE run CHECK` when the config is not
+  `redue.config.json`
+- the check's script through the project's package manager: `npm run SCRIPT`
+  (and `npm test`), `pnpm SCRIPT`, `pnpm run SCRIPT`, `yarn SCRIPT` or
+  `yarn run SCRIPT`. The short form is left out when the script is named like
+  one of the package manager's own commands.
+- the tool the check runs: `npx tsc ARGS` (and `pnpm exec tsc ARGS` with pnpm)
+  for a direct TypeScript check, or the runner's command, alone or after `npx`,
+  for a direct test check
+- the check's `command`, when it has no `@` tokens
+- for a workspace package's check: `pnpm --filter NAME SCRIPT` (also
+  `--filter=NAME`, `-F NAME`, and with `run`), `yarn workspace NAME SCRIPT`, or
+  `npm run SCRIPT -w NAME` (also `--workspace NAME`, `--workspace=NAME` and
+  `npm -w NAME run SCRIPT`). After `cd` into the package's directory, the
+  package-manager script forms and tool forms match that check.
+
+A `turbo run TASK` (or `turbo TASK`, alone or after `npx` or `pnpm exec`) or,
+in a pnpm project, `pnpm -r TASK` (`--recursive`, with or without `run`) that
+runs a checked task in every workspace package is skipped only when every check
+it would run is CURRENT, PASS and `reuse_eligible`. Every package with the
+task's script must have a check. turbo must define the task, with `dependsOn`
+listing at most `^TASK`, no `with`, no `PACKAGE#TASK` entries and no package
+`turbo.json`; `pnpm -r` must not include the workspace root. A root script
+whose text is such a command counts as that command, unless it has pre- or
+post-scripts. In every other case the command runs as typed: turbo caches its
+own results, so the hook never rewrites it. Filters (`--filter`) and nx are not
+matched.
+
+For a typecheck check that runs the compiler, the script's forms act only when
+the script in package.json still has exactly the configured runs: one `tsc`
+run per check with the same arguments, and no pre- or post-script. Otherwise
+the command runs as typed. A script that chains `tsc` runs with `&&` has one
+check per run, `typecheck.1`, `typecheck.2` and so on (see
+[direct TypeScript](direct-typescript.md#script-forms)); each run's own
+`npx tsc ...` form matches its check. The hook skips the script when all its
+runs are CURRENT, PASS and `reuse_eligible`, and otherwise rewrites it to
+`redue run` of the runs that are not, in the script's order, joined by `&&`.
+In a turbo or `pnpm -r` fan-out, a package's script counts only the same way.
+
+Each form may end with `2>&1` and then one `| tail -n N`, `| head -n N`,
+`| tail -N` or `| head -N`. It may also be the first command of a `;` or `&&`
+chain. Nothing else matches. Each form has its own `if` rule, so other Bash
+commands never start the hook. The installed skill lists these exact commands,
+so the agent uses forms the hook recognizes.
+
+On a match, the hook runs `redue status --sync --json`. It waits up to half the
+duration of the check's last completed run, at most 10 seconds, so waiting never
+costs more than half a run. With no completed run it waits 2 seconds. A check
+that takes a few hundred milliseconds is therefore rarely skipped; skipping it
+would save almost nothing, and the hook does not rewrite it to `redue run`
+either. Claude Code's own limit for the hook is 15 seconds.
+It blocks the command only when the check is CURRENT, PASS and
+`reuse_eligible: true`. The message names the check and the receipt's run ID. Every
+other result allows the command: STALE, UNVERIFIED, FAILED, a timeout, an error, or
+a missing `redue`. A command that starts with `REDUE_FORCE=1` always runs. A
+blocked chain runs none of its commands; the message names the rest of the chain
+so the agent can run it on its own.
+
+When the check is not CURRENT but the observer answered for it, the hook rewrites
+the command to `redue run CHECK` and allows it, keeping any `2>&1` and
+`| tail`/`| head` suffix. It adds `--config FILE` when the config is not
+`redue.config.json`. The run is recorded, so the next identical command can be
+skipped. Without a healthy answer (timeout, error, no observer) the command runs
+as typed. Claude Code still applies deny and ask rules to the rewritten command.
+A chain is never rewritten: the rewrite is allowed without a prompt, and that
+would also skip the prompt for the rest of the chain.
+
+Limits:
+
+- The hook judges its own environment, which Claude Code passes to it. The Bash
+  tool can add variables from your shell profile. The hook cannot see those.
+- Commands run from a session that started in a subdirectory, after a `cd`
+  outside the project, or combined with `||`, `&` or other pipes, are not
+  matched. After a `cd` into any other directory than the root or a checked
+  package's, nothing matches.
+- A skip writes nothing. If a typecheck command also emits files, later
+  commands see the files from its last run.
+- Only the Bash tool is covered, not PowerShell.
+- Run setup again after you rename a check or script.
+- The rewrite is allowed without a permission prompt, even where the original
+  command would have prompted.
+
+## Update an existing connection
+
+Installing a newer package does **not** rewrite project instructions. From the
+same project and installation, stop every observer using that installation before
+replacing it. Keep the original config and state selection; do not create a second
+config or delete receipts. Example for a default npm installation/config:
+
+```sh
+redue --config redue.config.json stop
+npm install --global @redue/cli@alpha
+redue --config redue.config.json agent setup codex --dry-run
+redue --config redue.config.json agent setup codex --apply
+redue --config redue.config.json start
+redue --config redue.config.json status --sync --json
+```
+
+Use the **same `--prefix`** as the existing npm installation when it has a custom
+prefix, and invoke its corresponding `redue` binary. Keep your actual config path
+on every command. For Claude, select `claude` in both setup commands. Preserve any
+existing `--state-dir` on lifecycle/status commands; setup does not embed custom
+state locations, so retain the documented generic instruction path if your agent
+workflow needs an explicit custom state. PowerShell may use the existing
+`npm.cmd`/`redue.cmd` shims without changing script policy.
+
+Review the preview before applying. Intact owned content updates; unrelated text
+is preserved. Edited managed content is refused, not overwritten. If refused,
+review/reconcile those edits deliberately; do not remove ownership records to force
+an update. Restart the observer with its original selection even if you postpone
+updating instructions, then start a **fresh agent session** after a successful
+update. Setup creates no verification receipt.
+
+Managed project metadata can itself be an observed input. Prior receipts remain
+historical evidence, but setup may make them STALE or UNVERIFIED. Reassess normally
+and run required checks; an upgrade is not a promise that existing receipts remain
+CURRENT. Do not suppress that invalidation or reset state.
+
+Codex gets a short managed section in project `AGENTS.md` that points to
+`.agents/skills/redue-verification/SKILL.md`. Claude Code gets one in `CLAUDE.md`
+that names the typecheck command the hook matches and says what a skip means,
+plus `.claude/skills/redue-verification/SKILL.md`. The skill holds the reuse
+rules and the exact commands for the selected config. When the hook matches a
+typecheck, the `CLAUDE.md` section does not point to the skill: the hook does
+the work, and the skill is there for agents that look for it. Small
+ownership records in `.redue/agents/` support safe updates/removal. These are
+portable project files, not receipts; review and commit them if the team wants
+this integration. Do not ignore just the ownership records while committing the
+managed files.
+
+Existing instruction text is retained. Review it in the preview: setup cannot
+prove arbitrary natural-language policies are consistent. Conflicts such as a
+root `AGENTS.override.md` or an alternative `.claude/CLAUDE.md` are reported
+instead of silently outranked. Global/managed policies, nested instructions,
+Codex instruction-size limits, skill disabling, and host-specific exclusions
+still apply. Complete the host's ordinary trust/permission prompts yourself;
+REDUE never grants tool permission. Sandboxed hosts may need owner-approved access
+to the checkout, owned state directory and local observer socket. A healthy daemon
+does not establish that the agent can reach it; doctor reports control access
+separately. Do not disable sandbox protections to make this work. Do not use a mode that disables project
+instructions and expect automatic activation.
+
+Control access is not simply file-read permission. The observer can reconcile and
+write its owned index, run the trusted configuration's probes in its own process
+context, reload receipts, and stop. Approve only the intended checkout/state and
+endpoint, accounting for that authority. Doctor sends only a bounded metrics
+request; it does not synchronize or run these probes.
+
+`agent doctor [codex|claude] --json` is read-only. It distinguishes command lookup,
+config resolution, cached observer health, a bounded read-only control-access probe,
+managed-file integrity, detected host
+version, and loading guidance. `behavior_verified: false` is deliberate: intact
+files do not prove the agent followed them. For Claude, doctor reports whether the
+typecheck hook is installed. Doctor neither
+executes checks nor starts observers, reconciles inputs, or installs a host.
+
+Doctor separates missing/unreadable state, a missing or refused endpoint, an
+explicit EPERM/EACCES access denial, and timeout/invalid response. A denial does
+not identify whether OS permissions or host policy caused it. A live PID and
+healthy cached observation do not prove control access. An older cached response
+without receipt-selection validation gets stop/start guidance. Windows command
+shims whose target has not been established are reported as unknown, not a
+proven installation mismatch.
+
+Codex CLI 0.160.1 on macOS can use the approved exact observer-socket route while
+other sockets and direct network access remain denied. Its independent sessions
+receive different proxy values. Ordinary npm invocation is **not** equivalent
+across arbitrary notifier state: REDUE withholds automatic npm-launcher
+reuse. Do not change proxy settings or permissions to get green evidence.
+
+The separate opt-in [direct local compiler recipe](direct-typescript.md) does not
+run npm. Its reviewed compiler implementation does not consume npm/proxy settings;
+a digest preserves their observed provenance without treating them as compiler
+inputs. Other execution context remains strict, and cached status still cannot
+assert caller eligibility. An explicit user request for `npm run typecheck` still
+requires npm execution; direct compiler evidence is not a substitute.
+
+Before model trials, run `redue agent doctor --json` and
+`redue status --sync --json` inside the agent's actual command boundary. The
+contributor helper `test/acceptance/codex-preflight.mjs --config FILE --check CHECK`
+performs the same bounded, read-only decision check and exits 2 when reuse is not
+eligible. It neither executes verification nor grants access; synchronization
+may run configured probes. A successful outside-shell result is insufficient.
+
+Use the same setup command after an upgrade; it updates intact managed
+content idempotently. Changed skill text or a changed managed block causes a
+conflict instead of an overwrite. Review your edits before retrying.
+
+```sh
+redue agent remove codex --dry-run
+redue agent remove codex --apply
+redue agent remove claude --apply
+```
+
+Removal deletes only intact REDUE-owned content for that host. Unrelated text,
+other integrations, project config, receipts and installed dependencies remain.
+User edits outside the managed section survive. Modified managed content is left
+intact with a diagnostic; compare it with a preview and resolve manually. Empty
+parent directories may remain. If the selected config has been deleted, restore
+it or manually remove only the marked REDUE section, that host's skill, and its
+`.redue/agents/HOST.json` ownership record after review. Do not delete an entire
+instruction file containing user content.
+
+## Project identity and generic agents
+
+Commands from nested directories search toward the nearest Git root. If more than
+one configuration applies, select one with `--config FILE`; REDUE refuses to guess.
+The generated skill names its project-relative configuration and gives the exact
+status and run commands for it. External configs or custom machine-local `--state-dir`
+setups should use a reviewed generic instruction instead of committing absolute
+paths. Other worktrees and remote containers have separate local evidence.
+
+For another agent, put a short instruction in its documented project mechanism:
+“Before deciding whether configured verification needs repeating, read REDUE's
+agent policy, identify the selected recipe and use its decision query for the intended config.
+Apply the schema/health/reuse rules.” Supply this document and the
+[JSON contract](json.md) as the detailed policy. Review the agent's actual tool
+trace before calling activation verified. A local npm installation does not install
+REDUE in a remote container; that environment needs its own CLI, checkout,
+dependencies and state. There is no cloud/team receipt synchronization.

package/docs/user/configuration.md

@@ -1,7 +1,7 @@
 # Configuration
 
-Prefer `redue init` over hand-authoring a qualified contract. A typical generated
-npm configuration is concise and portable:
+Prefer `redue init` over hand-authoring a contract. An ordinary generated npm script (recording-only in this candidate)
+configuration is concise and portable:
 
 ```json
 {
@@ -28,6 +28,11 @@ Use `--config FILE` to select an external configuration. `root` is relative to
 that file. Runtime paths, resolved executables, local evidence, and sockets stay
 out of version-controlled configuration.
 
+For the explicit direct compiler choice and generated exact argv, see
+[direct TypeScript](direct-typescript.md). Existing script receipts cannot satisfy it.
+A general check (`"qualification": "node-script-v1"`) has a `script` and no
+`command`; see the [general recipe](node-script.md).
+
 ## Arbitrary commands
 
 An unrecognized ecosystem can still record ordinary execution:
@@ -53,5 +58,26 @@ Advanced explicit contracts may declare `generatedInputs`, `installedInputs`, na
 reviewed escape hatches, not onboarding requirements. A coverage rationale cannot
 override unsupported storage, unresolved links, missing inputs, or observation failure.
 
+A chained typecheck script gets one generated check per `tsc` run, all with
+the script's name (see [script forms](direct-typescript.md#script-forms)). A
+proposed check for a project without a typecheck script has no `script`.
+
+Input patterns are relative to the project root. They cannot name a `.git`
+directory, because REDUE does not observe one; `!.git/**` is fine.
+
 Changing commands, relevant configuration, installed material, or consumed inputs
 invalidates prior applicability. It does not erase historical execution outcomes.
+
+Installed inputs (under `node_modules` or other installed roots) are observed by
+file identity: inode, size, mode, link count, and modification and change times.
+REDUE does not read every installed file, so large installations become ready
+quickly. Any write to an installed file makes dependent checks STALE until they
+run again, even when it restores earlier bytes, reinstalls identical packages
+(`npm ci`), copies the installation, or remounts it under another device. Timestamps tick in milliseconds, so a file
+changed in the last 2 seconds could be rewritten at the same size without a new
+identity; `redue run` waits until such files are 2 seconds old before it records
+a checkpoint, which adds up to 2 seconds right after an install. Source files are
+content-hashed, and the direct TypeScript recipe's probe content-checks every file
+the compiler reads. The 2-second window assumes the filesystem clock matches this
+machine's; on a network or VM-shared mount whose clock runs behind, keep the
+installation on a local disk.

package/docs/user/direct-typescript.md

@@ -0,0 +1,209 @@
+# Explicit local TypeScript verification
+
+This check means: the reviewed local TypeScript compiler completed the configured
+check against declared, observed inputs and relevant execution context. It does
+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)):
+
+```sh
+redue init --recipe typescript-direct --check typecheck --dry-run
+redue init --recipe typescript-direct --check typecheck
+redue start
+redue run typecheck
+redue status --sync
+```
+
+The preview shows the discovered script and recorded direct invocation. Nothing
+executes during init. package.json, environment and dependencies remain unchanged.
+A generated check contains:
+
+```json
+{
+  "name": "typecheck",
+  "script": "typecheck",
+  "kind": "typecheck",
+  "command": ["@node", "@typescript-compiler:.", "--noEmit"],
+  "cwd": ".",
+  "qualification": "npm-typescript-direct-v1",
+  "inputs": ["package.json", "package-lock.json", "tsconfig.json", "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,jsonc}", "!node_modules/**", "!.git/**"]
+}
+```
+
+`script` identifies the reviewed source recipe; `command` is what actually runs:
+the resolved Node executable and local TypeScript implementation, with exact argv
+and no shell. The entry is `lib/_tsc.js` where the package has one (5.7 and
+later), without its outer compile-cache-enabling shim, and `lib/tsc.js`
+otherwise. No compiler is fetched or bundled.
+
+## Compiler identity
+
+The entire installed `node_modules/typescript` must be an official package,
+byte for byte, in one of two ways:
+
+- TypeScript 5.5.2, 5.6.3, 5.9.3, 6.0.2 or 6.0.3: its files match the digest
+  REDUE ships for that release.
+- Any other TypeScript 5.x or 6.0 release: package-lock.json records the
+  registry's `typescript` package at the installed version (no alias, an
+  `https` tarball URL, not a file or git source) with an integrity (sha512,
+  or sha1 where a registry records only sha1), npm's cache holds the tarball
+  under that integrity, and the installed files are exactly the tarball's
+  files. REDUE reads the cache only; it never downloads. The cache is the one
+  npm uses: `npm_config_cache`, else `cache` in the project's `.npmrc`, then
+  the user's, else `~/.npm` (`%LocalAppData%\npm-cache` on Windows); the
+  global npmrc is not read. `npm-shrinkwrap.json` is not read on this path.
+  `npm ci` fills the cache. When the tarball is missing the check stays
+  recording-only with the reason `npm-tarball-uncached`; `npm cache add
+  typescript@VERSION` adds it. The check's compiler identity is then the
+  lockfile integrity, so a lockfile change re-probes.
+
+CI runs the same contract suite against the last release of each minor from
+5.0 to 5.8 that the reviewed releases do not cover. Later minors (6.1 and up)
+wait until CI covers them. TypeScript 7 (the native compiler) is not
+supported.
+
+## Script forms
+
+A typecheck script qualifies when it is one or more `tsc` runs joined by `&&`,
+each with `--noEmit` and only these arguments, in any order: `-p`/`--project`
+with a config file or directory inside the project, `--skipLibCheck`, and
+`--pretty` (optionally `true` or `false`). For example
+`tsc -p tsconfig.app.json --noEmit` or
+`tsc --noEmit && tsc --noEmit -p tsconfig.node.json`. `tsc -b`, `--watch`,
+other options, quotes, variables and other commands keep the script
+recording-only.
+
+A chain gets one check per run, named `typecheck.1`, `typecheck.2` and so on,
+each with the script's name and that run's arguments in its command. Each run
+is checked as its own program against its own config, and is reused only while
+the script still has as many runs as the config has checks for it, one of them
+with exactly those arguments. Adding or removing a run, or a pre- or
+post-script, makes every check of the script not reusable until `init` runs
+again. The script as a whole
+(`npm run typecheck`) is skipped only when its current runs and the configured
+checks correspond one to one and all are CURRENT (see [agents](agents.md)).
+
+With no typecheck script and a root `tsconfig.json`, init proposes a
+`tsc --noEmit` check with no `script` field, unless a script already runs a
+TypeScript checker in another form (`tsc -b`, `vue-tsc`, `svelte-check`,
+`tsgo`, `astro check`, `nuxi typecheck`). package.json is not changed. The
+check is written only when the contract holds; otherwise no typecheck check is
+added. The pnpm contract does the same for each workspace package with a
+`tsconfig.json` and no typecheck script.
+
+Existing configs are never overwritten. To compare choices, use a new project-local
+`--config redue.direct.config.json` with init; this explicitly selects separate
+state. To replace an existing check deliberately, preview JSON, stop its observer,
+review/edit that check's config, and restart using the same config/state. Existing
+npm receipts remain historical; the new command/interpretation needs a fresh run.
+Do not delete receipts. `redue run` always executes the configured command.
+
+## Existing npm configuration: deliberate replacement
+
+First upgrade through the [alpha.4 containment](npm-launcher-notice.md), stopping
+observers before the installation change and restarting with the same config/state.
+The old npm check becomes recording-only; its receipts remain historical.
+To opt into the direct recipe afterward:
+
+1. Stop the observer, install the selected released version into the same prefix,
+   and keep the original `redue.config.json` and any explicit `--state-dir` selection.
+2. Run `redue init --recipe typescript-direct --check typecheck --dry-run --json`
+   using that config selection. Inspect `proposed_config.checks` and the recorded
+   invocation. This does not write anything, even when the config already exists.
+3. In your editor, replace only the intended check object with the reviewed proposed
+   object. Preserve its name, the top-level project configuration, and every other
+   check. Do not replace the whole config with a one-check preview. Keep a local
+   backup outside observed inputs if desired.
+4. Run `redue start` with the same config/state. `redue status --sync --json` must
+   not treat the old npm receipt as eligible compiler evidence.
+5. Run `redue run typecheck`, then `redue status --sync --json`. A qualified success
+   now records the direct compiler recipe with a new run ID. Old npm runs remain
+   immutable history. Other check definitions are unchanged.
+
+Substitute the actual selected check name throughout. Repeating plain `init`
+does **not** migrate an existing config. A deliberately separate `--config` file
+is useful for comparison, but has separate state by design. Do not create one
+accidentally when intending to preserve the original selection.
+
+Pre/post scripts, compound commands, wrappers, environment assignments, workspace
+projects and unsupported compiler versions are not automatically converted.
+Init retains the original script with a reason. Development-mode source-map helpers,
+Node preloads/loaders/compile-cache settings, `TS_ETW_MODULE_PATH` (including empty or case aliases), unsupported compiler plugins, a
+`composite` root tsconfig, a program that uses a referenced project's files,
+outside-root inputs and uncertain observation withhold applicability. Extra custom probes cannot inherit this recipe's context
+exception. Relevant source, declaration, config, membership and installed-content
+changes invalidate or withdraw applicability normally. Installed files are observed
+by identity, so reinstalling identical packages or restoring an installed file's
+bytes also needs one rerun (see [configuration](configuration.md)).
+
+A root tsconfig with `incremental: true` is supported. tsc reads and writes
+its build-info file (`tsBuildInfoFile`, or the default next to the config) on
+each run, so REDUE leaves that file out of the inputs and lets the run write
+only that file and the directories it needs; any other write makes the run
+non-reusable. The result is what your own incremental tsc reports, so it
+trusts TypeScript's build-info cache, which TypeScript discards after a
+compiler or option change. The file must be inside the checkout and named
+`*.tsbuildinfo`, with no glob characters in its path.
+`assumeChangesOnlyAffectDirectDependencies` is refused: with it, the result
+depends on earlier runs. REDUE reads the setting when the observer starts:
+after turning `incremental` on or moving the file, restart the observer;
+status says so until then. On Linux, a run that creates the build-info directory is an
+observation gap, so the first run after that is not reusable.
+
+A root tsconfig may reference other configs (`references`), for example a
+composite `tsconfig.node.json`. Plain `tsc --noEmit` reads those configs but
+does not build them, so REDUE treats them as configuration. If the program
+uses a referenced project's sources or built outputs, the check is not
+qualified.
+
+On macOS and Linux, `redue run` records which files the compiler looked up and
+compares them with what the observer's last probe saw. The probe only builds the
+program. With `declaration: true`, tsc also resolves the project's dependencies
+while it checks declarations, so the run looks up files the probe never did,
+some outside the checkout, and reads those dependencies' `package.json`. The
+receipt keeps the run's answers to those existence, `realpath` and
+`package.json` lookups as run facts. Before every CURRENT answer, status asks
+each one again; a cached `redue status` asks them again when it is read. If any
+now answers differently, the check is STALE and the reason names the path. Any
+other file the run read, or a directory it listed, that the probe never did
+still makes the run non-reusable, as do more than 10,000 run facts. Receipts
+with run facts use a new format, so earlier observers do not reuse them. A
+direct receipt recorded before run facts is UNVERIFIED until the check runs
+again. Windows does not record direct runs, so it has no run facts: there, a
+lookup only declaration checks make is not checked again.
+
+The versioned `npm-direct-typescript@1` interpretation retains relevant Node context
+and identity. Reviewed compiler code does not parse npm settings or proxy variables;
+these remain untouched in the child environment and are recorded only as a digest
+of observed provenance. This is not an environment ignore option for arbitrary
+commands or other providers. No remote service equivalence is claimed. Ordinary
+cached status remains conservative; synchronize deliberately when worth the cost.
+
+Explain/JSON report `verification_recipe: "npm-direct-typescript@1"` for receipts
+recorded with this recipe. Report compiler evidence as compiler evidence. A user's
+explicit request for `npm run typecheck` is not satisfied by this different command.
+
+The injected `NODE_USE_ENV_PROXY=1` setting is admitted only on Node 22.13.0,
+where it is inert; it remains strictly tracked. Other Node versions with this
+setting need review and stay unqualified. REDUE does not alter the setting.
+
+## Node settings
+
+Since alpha.11 the direct recipe accepts these `NODE_*` settings:
+
+- `NODE_OPTIONS`, when every token is one of `--max-old-space-size=<n>`,
+  `--max-semi-space-size=<n>`, `--use-openssl-ca`, `--use-bundled-ca`,
+  `--use-system-ca` or `--dns-result-order=ipv4first|ipv6first|verbatim`.
+  Any other flag, quotes, backslashes or tabs are refused.
+- `NODE_EXTRA_CA_CERTS`.
+- `NODE_PATH`.
+
+`NODE_ENV` set to `production`, `test` or empty was already accepted. Every other non-empty
+`NODE_*` setting withholds applicability. The values are part of the recorded
+execution context: a run under one value is not reusable under another. A
+`--require` in `NODE_OPTIONS` still runs inside REDUE's own process before REDUE
+refuses it. The npm, pnpm and Yarn recipes still refuse `NODE_OPTIONS` and
+`NODE_PATH`.

package/docs/user/getting-started.md

@@ -57,6 +57,14 @@ prefix. Uninstalling the package does not remove local verification evidence;
 `redue remove-state` is a separate, explicit action. Alpha.1 remains available as
 historical software and is superseded for package identity, not a runtime defect.
 
+## Upgrading REDUE
+
+Stop every observer using the installation before upgrading, then restart each
+with the same config/state selection. See [the npm launcher notice](npm-launcher-notice.md)
+for exact commands. Do not remove state or delete receipts. Existing agent connections require a separate
+[preview/apply policy update](agents.md#update-an-existing-connection); installing
+the package alone does not update project instructions.
+
 ## First project
 
 From the project root:
@@ -74,7 +82,10 @@ Use a check actually printed by `init`. For a workspace:
 `redue init --workspace @example/package --check typecheck`.
 Initialization previews detected commands and qualification confidence before writing
 `redue.config.json`. An existing config is never overwritten. No checks are run and
-no dependencies installed. A missing/unsupported boundary is explained.
+no dependencies installed. A missing/unsupported boundary is explained. `init` tries
+the strict recipes first and uses the [general recipe](node-script.md) for a root
+typecheck or lint script none of them takes. Test scripts use the
+[direct test recipe](tests-direct.md).
 
 “Ready to qualify” means REDUE has a supported recipe whose prerequisites will be
 validated. It is not a receipt. “Recording-only” can record PASS/FAIL without claiming
@@ -82,7 +93,9 @@ reusability. Qualification can change when configuration or installation changes
 
 `run` streams normal output and preserves execution environment and cancellation.
 For the narrow pnpm TypeScript contract, `init` explicitly shows the direct installed
-compiler invocation it selects; other scripts run through the package manager.
+compiler invocation it selects, and for npm the
+[local compiler recipe](direct-typescript.md). General checks and other scripts
+run through the package manager. No existing configuration is silently migrated.
 Only use configs and probes from trusted repositories: these execute local code.
 
 `status` is cached and conservative. `status --sync` and `explain` revalidate caller
@@ -125,3 +138,11 @@ all observed roots; its basename must start with `redue-` or legacy `vstate-`.
 For a removed checkout, `redue --state-dir /your/owned/redue-project-state remove-state`
 still works without rebuilding its compiler/configuration. Ownership/active-run conflicts
 are actionable errors, never resolved merely by deleting an old lock.
+
+## Connect an agent explicitly
+
+After initialization, use `redue agent setup codex --dry-run` (or `claude`) to
+review project-local instructions, then repeat with `--apply`. Start a fresh host
+session. `redue agent doctor` checks prerequisites without running verification.
+See [agent activation](agents.md) for loading rules, generic agents, and removal.
+For a fixed build and ordinary development evaluation, use the [opt-in pilot guide](pilot.md).

package/docs/user/json.md

@@ -30,6 +30,8 @@ Stable-enough-for-alpha fields:
 | `result` | Historical `PASS`, `FAIL`, or null. A failed invocation is not green even with CURRENT applicability. |
 | `freshness` | `CURRENT`, `STALE`, or `UNVERIFIED`, independent of result. |
 | `reuse_eligible` | True only for qualified, applicable passing evidence. Never derive permission to reuse from outcome alone. Missing means false. |
+| `run_facts` | Number of lookups outside the discovery certificate that the receipt's run made (direct TypeScript recipe). Status asks each again before answering CURRENT. Absent when there are none. |
+| `probe_deadline_ms` | Top level. How long the full state probes of one decision may take in total: each check's deadline (5 s to 60 s, from earlier probes and runs) times its probe count, summed. Callers wait at least this long plus 10 s for a synchronized answer. |
 | `reason` | Human explanation; not a stable machine enum. Do not parse it to authorize reuse. |
 | `changed_inputs` | Known changed relevant paths when available, possibly only the first difference; empty/missing is not proof of no changes. |
 | `invocation` | Null without a receipt; otherwise run ID, completion `status`, duration, exit code/signal when known. Status distinguishes exited, interrupted, and start/capture failure. |