@redue/cli 0.0.0-stage → 0.1.0-alpha.10

package/docs/user/direct-typescript.md

@@ -0,0 +1,96 @@
+# 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 an existing standalone
+`tsc --noEmit` script, installed dependencies, Node 22/24 and TypeScript 5.5.2/5.6.3/5.9.3:
+
+```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. TypeScript 5.5.2 and 5.6.3 use `lib/tsc.js`; 5.9.3 uses `lib/_tsc.js` directly,
+without its outer compile-cache-enabling shim. No compiler is fetched or bundled.
+The entire installed package must match reviewed official distribution bytes.
+
+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 or
+incremental/composite configuration, 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.
+
+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.

package/docs/user/getting-started.md

@@ -0,0 +1,148 @@
+# Install and use REDUE
+
+Requirements: Git; Node 22 or newer with npm; an existing local JS/TS checkout
+with its dependencies installed. Linux additionally needs `python3`. Supported
+storage is local APFS on macOS, NTFS on Windows, and the documented native Linux
+filesystems. Network/FUSE/overlay mounts are not qualified Linux storage.
+Node 22 and 24 are the release-test matrix; newer majors are not yet acceptance claims.
+
+Install the public alpha:
+
+```sh
+npm install --global @redue/cli@alpha
+redue --version
+```
+
+For an unpublished source candidate, run `npm ci` and `npm pack --json`, then
+install the exact filename reported by npm with `npm install --global ./<filename>`.
+
+These commands also work in PowerShell (use `npm.cmd`/`redue.cmd` when a local
+PowerShell script policy blocks generated `.ps1` shims; do not change policy).
+No build step, custom installer, account, or login service is required. Installing
+npm dependencies uses the registry; normal local observation does not require network.
+
+For a reversible user-owned prefix, POSIX shells:
+
+```sh
+npm install --global --prefix "$HOME/.local/redue-alpha" @redue/cli@alpha
+export PATH="$HOME/.local/redue-alpha/bin:$PATH"
+```
+
+PowerShell:
+
+```powershell
+$reduePrefix = Join-Path $env:LOCALAPPDATA 'redue-alpha-install'
+npm.cmd install --global --prefix $reduePrefix @redue/cli@alpha
+$env:PATH = "$reduePrefix;$env:PATH"
+redue.cmd --help
+```
+
+These PATH changes affect only the current shell. Alternatively invoke the
+installed entry point directly: POSIX `node "$HOME/.local/redue-alpha/lib/node_modules/@redue/cli/bin/redue.mjs"`;
+Windows `node "$reduePrefix/node_modules/@redue/cli/bin/redue.mjs"`.
+
+## Moving from alpha.1
+
+If the personal-scope alpha.1 package is installed, stop the project's observer
+and replace that package before installing the canonical command:
+
+```sh
+redue stop
+npm uninstall --global @msiric/redue
+npm install --global @redue/cli@alpha
+```
+
+Use the same `--prefix` on both npm commands if your installation has a custom
+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:
+
+```sh
+redue init --dry-run
+redue init
+redue start
+redue run typecheck
+redue status
+redue explain typecheck
+```
+
+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. Npm-launcher typechecks are
+recording-only in alpha.4; a passed execution is historical PASS with UNVERIFIED
+applicability, not reusable CURRENT.
+
+“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
+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. Npm scripts remain recording-only;
+use `redue init --recipe typescript-direct --dry-run` to preview a distinct,
+explicit [local compiler recipe](direct-typescript.md). 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
+context and may execute read-only probes. Synchronization can be slower than a cheap
+check, especially on Windows. Choose deliberately. A timeout is UNVERIFIED, not green.
+
+## Lifecycle and removal
+
+`start` starts this config's owned observer, or reports that it is already running.
+If already running, use `status`; do not create a second state directory just to
+start another observer. Startup may report initialization before inputs are ready.
+`stop` stops that observer and retains historical evidence. After restart, observation
+is reconciled before reuse.
+
+```sh
+redue stop
+redue start
+redue remove-state
+npm uninstall --global @redue/cli
+```
+
+For an isolated installation, use the same `--prefix` on uninstall. Remove state
+**before** uninstalling the command. No broad recursive deletion command is needed.
+`remove-state` checks its ownership marker and stops only that observer. It does not
+remove project files, dependencies, another tool's watches, or other REDUE configurations.
+To remove project configuration, inspect and delete `redue.config.json` yourself.
+
+Runtime state is separate from durable project config. Legacy directory spelling is
+retained for compatibility, not copied into your config:
+
+| OS | Default state base |
+| --- | --- |
+| macOS | `~/Library/Application Support/vstate/` |
+| Linux | `$XDG_STATE_HOME/vstate/`, otherwise `~/.local/state/vstate/` |
+| Windows | `%LOCALAPPDATA%/vstate/` |
+
+A checkout/config identity selects a dedicated child directory. Use
+`--state-dir /your/owned/redue-project-state` to choose a dedicated directory outside
+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

@@ -0,0 +1,59 @@
+# Alpha JSON interface (schema 1)
+
+Use `status --json` for cached state, `status --sync --json` for caller-aware
+applicability, and `explain CHECK --json` for selected synchronized detail.
+`detail` remains an alias. Successful reads emit one JSON object, no human prose.
+
+```json
+{
+  "schema": 1,
+  "state": "stale",
+  "current": 0, "stale": 1, "failed": 0, "observed_failed": 0, "unverified": 0,
+  "checks": [{
+    "name": "typecheck",
+    "result": "PASS",
+    "freshness": "STALE",
+    "reason": "src/main.ts changed",
+    "changed_inputs": ["src/main.ts"],
+    "reuse_eligible": false,
+    "invocation": {"runId": "opaque-run-id", "status": "exited", "exitCode": 0, "durationMs": 940}
+  }],
+  "observation": {"healthy": true}
+}
+```
+
+Stable-enough-for-alpha fields:
+
+| Field | Contract |
+| --- | --- |
+| `checks[].name` | Configured check identity. |
+| `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. |
+| `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. |
+| `target_provenance` | Available target evidence. Unknown is not executed or cache-hit. |
+| `observation.healthy` | False means no check is reusable. Additional reason/phase diagnostics may appear. |
+| `state` | Aggregate lowercase current/stale/failed/unverified (and runtime pending states where applicable). Use per-check fields for decisions. |
+
+Counts cover the whole configuration even when `explain CHECK` filters `checks`.
+`failed` counts applicable failures; `observed_failed` preserves historical failures
+regardless of applicability. Fields not listed here are diagnostic and may evolve.
+Ignore unknown fields; reject unknown schema versions. These responses contain local
+paths/check names and must not be uploaded automatically.
+
+`init --json` returns discovery levels (`ready`, `recording`, `unsupported`),
+reasons, workspace ownership, `written`, and `proposed_config`. Ready is not PASS.
+`init --dry-run --json` writes no config and runs no check.
+
+Read commands normally exit 0 even when the evidence is not current. Errors exit
+nonzero; synchronized transport failures may still return conservative JSON.
+Usage/configuration errors go to stderr and are not guaranteed JSON. Never treat
+a failed read as authority from a previously cached answer.
+
+`run CHECK --json` preserves ordinary command stdin/stdout/stderr and appends a
+JSON summary. **Its stdout is not a JSON-only stream.** Query status/details after
+completion for machine-readable evidence. Normal check exit codes are preserved;
+interruption/process-start failures are nonzero. REDUE retains metadata and receipts,
+not arbitrary terminal output. The CLI does not infer tests executed from prose.

package/docs/user/npm-launcher-notice.md

@@ -0,0 +1,42 @@
+# npm launcher applicability correction — alpha.4
+
+Alpha.4 withdraws automatic applicability for npm-backed TypeScript checks using
+`typescript-noemit-v1`. Alpha.3 was demonstrated to admit an npm invocation whose
+update notification consumes unobserved remote responses, cache and time. Those
+inputs can change the outer npm result without changing the tracked project or
+caller identity. The controlled reproduction does not establish a public registry
+malfunction, affected-user count, or compiler completion in the failing npm case.
+
+Npm commands still execute exactly as configured through `redue run CHECK`.
+They still record PASS/FAIL. Previous PASS remains historical PASS; applicability
+is now UNVERIFIED, including after synchronization or a successful new npm run.
+This is a correction to the claimed boundary, not evidence that the code failed.
+Supported Yarn/pnpm and independently reviewed explicit contracts are unchanged.
+
+Until upgraded, do not rely solely on automatic npm CURRENT to skip the npm
+invocation. A different verification recipe requires explicit selection and fresh
+evidence; it cannot reinterpret an old npm receipt. Alpha.4 does not ship the
+experimental npm direct-compiler recipe or agent activation.
+
+## Upgrade without losing history
+
+First stop **every observer using this installation**, using each original config
+and any explicit state directory. Then upgrade that same installation and restart
+each observer with the same selections:
+
+```sh
+redue --config /path/to/project/redue.config.json stop
+npm install --global @redue/cli@0.1.0-alpha.4
+redue --config /path/to/project/redue.config.json start
+redue --config /path/to/project/redue.config.json status --sync
+```
+
+Repeat the stop/start commands for each project. If you originally used
+`--state-dir`, supply the identical directory on every REDUE command. If installed
+with a custom npm `--prefix`, supply the same prefix during installation. On Windows
+use `npm.cmd`/`redue.cmd` if required by existing PowerShell policy; do not change it.
+
+**Do not delete receipts or use `remove-state` as an upgrade step.** An upgraded
+client refuses an obsolete running observer interpretation and asks for stop/start.
+Restart reconciles existing state and preserves immutable historical runs. This
+correction does not silently change your project config or configured command.

package/docs/user/pilot.md

@@ -0,0 +1,142 @@
+# Opt-in development pilot: alpha.10
+
+Use one fixed build for several ordinary development sessions. The owner will
+invite two or three willing testers and approve their projects; nothing is
+collected or uploaded automatically. External usage has **not started**. Earlier
+controlled compiler/agent trials are acceptance evidence, not independent adoption.
+
+## Check the boundary first
+
+Start with a trusted, single-package npm Git checkout, normally installed locked
+dependencies, and an existing standalone `tsc --noEmit` script without pre/post
+scripts. The direct recipe accepts only the official, unchanged TypeScript
+**5.5.2, 5.6.3 or 5.9.3** packages and Node **22 or 24**. No workspaces, named
+tsconfig selection, emitted/incremental/composite builds, custom loaders or
+outside-root inputs are added by this pilot. Do not downgrade or change your
+project to fit; record an unsupported setup as feedback.
+
+Development-mode source-map support, Node preloads/inspectors/compile-cache
+overrides and `TS_ETW_MODULE_PATH` are unsupported. The injected
+`NODE_USE_ENV_PROXY=1` context is reviewed only on Node **22.13.0**; leave the
+environment and security controls intact. See the [full recipe boundary](direct-typescript.md).
+
+CLI/package mechanics are tested on macOS/APFS, native Linux and Windows/NTFS;
+Linux also needs Python 3 and [supported native storage](getting-started.md).
+Actual fresh-session behavior was tested with Codex **0.162.0 on macOS**, Node
+22.13.0 and the approved exact checkout/state/socket access. This is not general
+sandbox compatibility. Claude mechanics are tested; Claude behavior and cross-host
+handoff are **NOT RUN**. The recording shortcut is macOS/direct-recipe only.
+
+## Install and connect explicitly
+
+For a new default npm installation:
+
+```sh
+npm install --global @redue/cli@0.1.0-alpha.10
+redue --version
+cd my-project
+redue --config redue.config.json init --recipe typescript-direct --check typecheck --dry-run
+redue --config redue.config.json init --recipe typescript-direct --check typecheck
+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 agent doctor codex --json
+```
+
+Use the discovered check name. Review both previews before applying. The recorded
+invocation is the resolved local Node/compiler with `--noEmit`, **not npm or its
+lifecycle scripts**. Neither init nor setup executes verification. An existing
+config is never overwritten; use the [deliberate check replacement procedure](direct-typescript.md#existing-npm-configuration-deliberate-replacement)
+without losing other checks or changing config/state identity. For an owned custom
+installation prefix or Windows command shims, use the [installation instructions](getting-started.md).
+
+Run doctor inside the agent's actual command boundary too. A healthy outside-shell
+result does not prove access. The owner must grant only the intended checkout,
+owned state directory and exact observer endpoint through supported host controls.
+The observer can write its index, run trusted configured probes in its own process
+context, reload receipts and stop; endpoint access is more than a file read.
+Do not disable sandboxing, bypass the proxy, or allow all sockets. If access is
+unavailable, record the limitation; an installed skill is not behavioral acceptance.
+See [access and diagnostics](agents.md). Doctor does not run verification or sync.
+
+Complete setup before the first real verification obligation. When that obligation
+arises, record the configured compiler check in the intended execution context:
+
+```sh
+redue --config redue.config.json run typecheck
+redue --config redue.config.json status --sync --json
+```
+
+A successful run may remain **UNVERIFIED**. Reuse needs understood schema, healthy
+observation, CURRENT, PASS and `reuse_eligible: true`; a receipt or exit code alone
+is insufficient. Recovery cannot repair a run's missing start observation. A later
+fully observed run can create new eligible evidence. Do not erase receipts to get green.
+
+Start a fresh agent session after connecting, then work normally. Keep ordinary
+task requests and explicit fresh-verification obligations; an explicit npm-script
+request still requires npm. Let later sessions occur naturally—do not manufacture
+edits, restarts or repeated queries to inflate reuse. Configured compiler evidence
+does not verify tests, npm lifecycle behavior or application correctness.
+
+## Update or leave without losing evidence
+
+Keep the pilot version fixed unless a real defect requires a reviewed update.
+Record any build boundary. Before replacing an installation, stop every observer
+using it; keep the same npm prefix, config and any explicit state selection.
+
+```sh
+redue --config redue.config.json stop
+npm install --global @redue/cli@0.1.0-alpha.10
+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
+```
+
+Package installation alone does not update project instructions. Setup updates
+intact owned content, preserves unrelated text and refuses edited managed content.
+Review conflicts; do not delete ownership records to force an update. Setup metadata
+can invalidate prior applicability; reassess normally and start a fresh agent session.
+Historical receipts remain. See [the complete update procedure](agents.md#update-an-existing-connection).
+
+To disconnect and uninstall, using the same installation prefix when applicable:
+
+```sh
+redue --config redue.config.json agent remove codex --dry-run
+redue --config redue.config.json agent remove codex --apply
+redue --config redue.config.json stop
+npm uninstall --global @redue/cli
+```
+
+This preserves project config and receipts. Do not use `remove-state` for an upgrade
+or pilot exit. Edited managed content is left intact with a conflict for review.
+
+## Voluntary notes, reviewed before sharing
+
+Keep a small local note per real verification obligation, including setup failures
+and abandoned attempts. Use existing local receipts/tool history only when you
+choose; do not enable automatic transcript capture. Suggested fields:
+
+| Field | Record |
+| --- | --- |
+| Context | Build, OS/Node/compiler/host versions, anonymous project/session label |
+| Obligation | What actually needed verification; explicit fresh execution if requested |
+| Decision | Consulted? Agent-visible CURRENT/PASS/eligible, STALE, unsupported or unavailable? |
+| Outcome | Actual reuse with no equivalent execution; wrapped run; execution outside REDUE; or unresolved |
+| Evidence | Local before/after receipt IDs and actual commands, reviewed locally |
+| Cost | Measured setup/restart/query/recording/execution durations, if available |
+| Friction | What failed or confused; why you continued or stopped using REDUE |
+
+A CURRENT query is not automatically a saved run; an inspection needing no
+verification is not an avoided check. Do not infer a counterfactual from a receipt.
+Label estimated avoided compiler cost and its assumptions separately from measured
+time. Include recording, restarts and required reruns. Whole-task time alone does
+not establish causal speedup. The question is whether natural later reuse repays
+the cost of creating and maintaining evidence.
+
+Share only a voluntary owner-reviewed, redacted summary through the
+[existing issue tracker](https://github.com/msiric/redue/issues). Keep private source,
+paths, configuration bodies, credentials, receipts and raw transcripts out of public
+issues. Sensitive correctness/security reports use the repository's private security
+reporting channel. Maintain one short friction list, prioritize correctness first,
+and choose the next development task from observed usage rather than a benchmark target.

package/docs/user/receipt-selection-notice.md

@@ -0,0 +1,60 @@
+# Receipt selection correction in alpha.3
+
+**Known affected release: `@redue/cli@0.1.0-alpha.2`. Fixed in
+`@redue/cli@0.1.0-alpha.3`.** No exploit or affected-user count is established.
+REDUE remains an alpha.
+
+If a wrapper persisted a newer outcome but its observer reload notification
+failed, the observer could continue selecting an older passing receipt. Cached
+and synchronized status could then present that older result as CURRENT and
+eligible for reuse. A separate reproduced write-failure window left a new
+immutable outcome recorded while replacing the selected receipt failed.
+
+Until upgraded, do not rely solely on affected CURRENT output to skip checks.
+Run verification when needed and inspect its actual outcome; a successful status
+command is not proof that the latest execution passed.
+
+## What changes
+
+The observer refreshes REDUE-owned receipt selection before publishing status.
+Clients check that a response represents the current readable selection. Missing,
+unreadable, malformed, incompatible, or replaced selection cannot authorize
+reuse. A new client connecting to an alpha.2 observer returns UNVERIFIED and
+asks for a restart, even when the old response says CURRENT.
+
+A small owned pending-update record also withholds applicability after an
+incomplete receipt write. Successful recording clears only that check's pending
+entry. It does not discard another check's incomplete outcome or automatically
+promote an orphaned journal entry. Inspect the failed run and storage error, fix
+the storage problem, then record that check again. An unreadable/malformed pending
+record requires operator inspection; do not delete receipts to obtain green status.
+
+Historical PASS/FAIL and immutable `runs-v1` files remain intact. Stable applicable
+FAIL remains a failure and is never reuse-eligible. This guard tracks owned
+receipt replacement; it does not replace input-content validation or promise an
+atomic decision against concurrent edits/writes.
+
+## Upgrade and restart
+
+From each initialized project, stop its observer before replacing the installation.
+After all observers for that installation have stopped, upgrade it once, then
+restart each observer with its existing configuration and state selection:
+
+```sh
+redue stop
+npm install --global @redue/cli@0.1.0-alpha.3
+redue --version
+redue start
+redue status --sync --json
+```
+
+Use the same npm `--prefix`, project `--config`, and `--state-dir` you already use,
+if customized. On Windows use `npm.cmd`/`redue.cmd` where required by the existing
+shell policy. Stop all observers belonging to the installation before replacing
+it, then start each with the upgraded binary. For an independently installed
+candidate, its `stop` command can stop the older observer in the same explicitly
+selected owned state. Do not run `remove-state`; receipts need not be deleted.
+
+Restart preserves historical receipts and reconciles inputs. It does not promise
+CURRENT: a newer failure, unstable execution, incomplete contract, changed input,
+or observation uncertainty remains visible under the normal rules.

package/docs/user/shell.md

@@ -0,0 +1,25 @@
+# Shell usage
+
+Run `redue start` once for the project/configuration you want to observe. A shell,
+terminal multiplexer, and agent using that same config share its backend. Closing
+the terminal does not stop the observer. `redue stop` does.
+
+`redue status --short` is the intended small indicator:
+
+```text
+REDUE UNVERIFIED
+```
+
+It reads the cached snapshot, checks its expiry and observer liveness, and never
+synchronizes, traverses installed packages, or runs probes/checks. Like ordinary
+status, it can remain conservative when caller context or installed hardlinks
+need a synchronized read. Do not turn that uncertainty into a green badge.
+
+For an existing async/bounded prompt framework, use `redue status --short` from
+the project root as the segment command and display unavailable on errors or
+timeout. Node startup and configuration parsing still have a cost. REDUE does
+not install a shell hook, edit global shell files, or provide its own prompt
+scheduler. Running it manually is supported in PowerShell and POSIX shells.
+
+Never put `status --sync` or `explain` in a prompt. Use those deliberately when
+you need a decision and synchronization is worth its cost.