From fc80ea88dfb7bde43e89db0f341c99d7b53c1a7c Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com> Date: Tue, 6 Oct 2026 13:34:22 +0800 Subject: [PATCH] docs: correct CLI examples and documentation checks (#655) --- AGENTS.md | 2 +- README.md | 10 ++++++---- docs/testing.md | 5 ++--- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a87e23b27..b73238f19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ REA is a layered ESM TypeScript application. Dependencies flow inward from pure - `npm run check:changed`: run cached static checks and source tests affected since the branch merge base (default `origin/main`). - `npm run check:fast`: run cached typecheck and lint checks. - `npm run check:pr`: opt into the complete local deterministic gate and generated-document checks for broad changes; CI owns full coverage. Routine iterations need focused tests and relevant checks, not the whole gate each time. -- `npm run docs:check`: check committed generated documents; `npm run docs:api:cached` separately renders API HTML when needed. +- `npm run docs:check`: check committed generated documents; `npm run docs:generate` regenerates them. - For provider-dependent changes, see [docs/testing.md](docs/testing.md) and run the matching real-provider verification. - Keep each verification lane's prerequisites limited to the claim it checks. Use host-native fixtures for host/provider acceptance; put optional cross-target formats and their external toolchains in a separate lane. Preflight required commands and report the missing dependency and lane clearly. diff --git a/README.md b/README.md index e66ebbd95..f6e66930e 100644 --- a/README.md +++ b/README.md @@ -382,7 +382,7 @@ relationships, event activity, IPC, process identity, or Electron roles. See [Node and Electron runtime observation](docs/javascript-runtime-observation.md) for the exact coverage. -Exact package, tool-family, provider, setup-client, schema, and CLI facts are generated from source in [`docs/product-catalog.json`](docs/product-catalog.json). PR CI verifies this catalog, narrative documentation, generated schemas, and a clean TypeDoc render. +Exact package, tool-family, provider, setup-client, schema, and CLI facts are generated from source in [`docs/product-catalog.json`](docs/product-catalog.json). PR CI verifies this catalog, narrative documentation, and generated schemas. ## Roadmap @@ -532,7 +532,9 @@ The session also reports active work and cleanup status. If a caller times out, | `1` | The operation could not complete, for example because of invalid input, host permission denial, cancellation, or timeout. Structured output reports the reason when available. | | `128 + N` | The process ended from signal `N`, where the shell or runtime preserves the conventional signal-derived status. | -`setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human` +`setup --dry-run` returns status `planned` and exits `0`. A setup result with +status `cancelled` also exits `0`. +`setup` returns `1` for `needs_confirmation` or `needs_human` because configuration is not ready; rerun it after approval or remediation. `doctor` returns `1` when required checks for its readiness scope are unhealthy. Unavailable optional provider prerequisites remain visible as informational @@ -544,7 +546,7 @@ cannot hide its failure: ```bash set -o pipefail -rea inventory-artifact ./app.asar --json | jq . > inventory.json +rea inspect-artifact ./app.asar --json | jq . > inspection.json ``` ## Current Hopper provider @@ -651,7 +653,7 @@ Any agent that can run a local MCP server can use the manual configuration. Setu ## Development -See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution checks, and [docs/testing.md](docs/testing.md) for test scopes and real-tool verification. PR CI publishes generated API documentation as the `api-docs` artifact. +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution checks, and [docs/testing.md](docs/testing.md) for test scopes and real-tool verification. `npm run docs:check` checks committed generated documents; `npm run docs:generate` regenerates them. `npm run verify:agent` evaluates native, JavaScript, managed, and browser investigation tasks through a real local Codex CLI. Its report covers tool selection, repeated calls, token use, completion quality, and handling of permissions and unknowns. diff --git a/docs/testing.md b/docs/testing.md index b5d8a81b1..28518fc65 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -182,7 +182,7 @@ behavior, and complete CI evidence before merging. | `npm run test:watch:all` | Changed tests from every project; builds at startup, so rebuild after production edits before relying on compiled tests | | `npm run check:changed` | Cached typecheck/lint and branch-related source feedback | | `npm run check:pr` | Opt-in complete local deterministic gate and generated-file checks | -| `npm run docs:check` | Committed generated-document freshness, without API HTML rendering | +| `npm run docs:check` | Committed generated-document freshness | For example: @@ -229,8 +229,7 @@ process-global, and other boundary projects retain per-file isolation. `npm test`, `npm run docs:check`, and `npm run docs:generate` share repository-local locks and fail fast when the same class of command is already running. The `npm test` build is inside that lock. `check:pr` runs its test task -before starting generated-document validation. TypeDoc rendering is a separate -command and CI step. +before starting generated-document validation. Vitest and Node persistent compile caches are deliberately not enabled by default. To evaluate repeated local runs, opt in for both cold and warm