@quireco/cli 0.0.3 → 0.0.5

package/README.md

@@ -30,10 +30,11 @@ node dist/quire.mjs --help
 
 ## Workspace target (`quire env`)
 
-`quire env` manages the `.quire/environment.json` file that tells Quire what application to investigate. Configure the target once, then `investigate` will pick it up automatically:
+`quire env` manages the workspace target that tells Quire what application to investigate. Configure the default target once, then `investigate` will pick it up automatically:
 
 ```bash
-quire env init --web --base-url http://localhost:3000     # scaffold a web target
+quire env init --web                                      # prompt for a web target
+quire env init --web --base-url http://localhost:3000     # non-interactive web target
 quire env init --mobile --ios                              # scaffold a mobile target
 quire env                                                  # print the resolved target
 quire env --json                                           # machine-readable form
@@ -43,6 +44,14 @@ quire env set kind=mobile platform=android                 # switch web → mobi
 quire env unset device
 ```
 
+Named environments live under `.quire/environments/<name>.json` and are selected with `--env`:
+
+```bash
+quire env init --web --env local
+quire env init --web --env prod --base-url https://app.example.com
+quire "Verify checkout" --env prod
+```
+
 `set` accepts one or more `key=value` pairs and validates the result against the schema before writing. Valid keys depend on `kind`:
 
 - **Web**: `baseUrl`
@@ -66,7 +75,21 @@ Target reachability runs by default: web environments are probed with a HEAD req
 
 ## Investigations
 
-The primary interface is text-in, durable-run-handle-out. `investigate` starts a background run and returns immediately so coding agents do not need to keep a subprocess open for long investigations:
+The primary interface is text-in investigation. For humans, `quire "..."` starts an investigation and attaches to the live run log:
+
+```bash
+quire "Reproduce the checkout crash"
+quire ask "Verify the login page loads"
+quire investigate "Reproduce the checkout crash"
+```
+
+Use `--detach` to start the run in the background and print run-control commands without attaching:
+
+```bash
+quire investigate "Reproduce the checkout crash" --detach
+```
+
+Coding agents and scripts should use `--json`. JSON mode returns a durable run handle immediately, never prompts, and keeps stdout machine-readable:
 
 ```bash
 quire investigate "Reproduce the checkout crash" --json
@@ -77,25 +100,42 @@ quire report <run-id> --wait --json
 `investigate` carries a deliberately small flag surface — everything that describes the target (platform, provider, device, app id, etc.) lives in `.quire/environment.json` via `quire env`. The run-level flags are:
 
 - `--stdin` reads plain-text investigation context from stdin. If a positional prompt is also present, stdin is treated as additional context.
-- `--json` reserves stdout for the started run handle JSON only.
-- `--watch` attaches to the live run log after starting the investigation. Ctrl-C detaches.
+- `--json` reserves stdout for the started run handle JSON only and uses automation-safe fail-fast behavior.
+- `--detach` starts the run without attaching to the live log.
+- `--watch` attaches to the live run log after starting the investigation. Human mode watches by default; this is mainly useful with `--json`. Ctrl-C detaches.
 - `--headed` shows the browser window for web targets.
 - `--url <url>` overrides the configured web `baseUrl` for one run.
-- `--no-sync` keeps an authenticated run local instead of uploading it to the Quire web app. Default behavior syncs evidence-tier artifacts.
+- `--env <name>` uses `.quire/environments/<name>.json` instead of the default `.quire/environment.json`.
 
 Top-level shortcuts mirror the most common run subcommands:
 
 ```bash
 quire watch <run-id>          # alias for `quire runs watch`
 quire report <run-id>         # alias for `quire runs report`
+quire handoff <run-id>        # alias for `quire runs handoff`
 ```
 
-Less common run operations stay under the canonical `runs` namespace: `quire runs status|cancel|list|sync ...`.
+Less common run operations stay under the canonical `runs` namespace: `quire runs status|cancel|list ...`.
 
-Each run writes `metadata.json`, `report.json`, and raw `emit-report.json` under `~/.quire/runs/<workspace-key>/<run-id>/` by default. Set `QUIRE_RUNS_DIR` to override the run-artifact root.
+Each run writes `metadata.json`, `report.json`, `handoff.md`, and raw `emit-report.json` under `~/.quire/runs/<workspace-key>/<run-id>/` by default. Set `QUIRE_RUNS_DIR` to override the run-artifact root.
+
+`report.json` is the structured source of truth. The stable top-level fields include:
+
+- `triage`, `summary`, `confidence`, and `likelyCause`
+- `evidence[]` with optional run-local artifact paths
+- `reproductionSteps[]` and `journeysTried[]`
+- `environment.notes[]` and `environment.blockers[]`
+- `codeReferences[]` with likely edit targets, optional symbols/lines, rationale, and confidence
+- `verification.commands[]` and `verification.manualSteps[]` with expected outcomes
+- `recommendedActions[]` and `suspectedFiles[]` for backwards-compatible summaries
+
+Use `quire runs report <run-id> --wait --json` when another agent needs the full structured payload.
+Use `quire runs handoff <run-id> --wait` when a human or coding agent needs a compact markdown brief with summary, evidence, likely source files, verification commands, and a ready-to-use next prompt.
 
 Local investigations run the Pi agent loop on your machine. Quire prefers local Pi/OpenAI Codex provider auth when it is configured, then falls back to Quire Credits through Quire's authenticated broker. Quire-owned provider auth is read from `~/.quire/model-auth.json` by default, with compatibility fallback to Pi's existing auth file. Set `QUIRE_MODEL_AUTH_PATH` to override the Quire-owned model auth file. `quire login` associates local runs with your Quire account for identity, wallet access, run upload, and future hosted workflows; personal model-provider auth remains a separate local-provider concern.
 
+The investigation runtime defaults to GPT-5.5 with medium thinking effort for both local ChatGPT/Codex auth and Quire Credits brokered through Cloudflare AI Gateway.
+
 Use `quire connect chatgpt` when you want Quire to connect ChatGPT/Codex subscription auth without using the Pi CLI first:
 
 ```bash