@quireco/cli 0.0.2 → 0.0.4

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,63 @@ 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`, `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:
 
-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.
+- `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
+quire connect chatgpt
+quire connect chatgpt --no-open
+```
+
+This starts Pi's OpenAI Codex OAuth flow and writes Pi-compatible credentials to Quire's local model-auth store. Existing Pi users do not need this step because Quire still reads Pi's existing auth file as a fallback.
+
+Web investigations use the `agent-browser` package bundled with `@quireco/cli`; a separate global `agent-browser` install is not required. A usable Chrome/Chromium installation is still required for local browser automation unless the run uses an external browser provider or explicit executable path.
+
+Remote agents can use an environment-scoped API token instead of browser login:
+
+```bash
+export QUIRE_API_TOKEN=qk_...
+quire whoami --json
+quire investigate "Verify this PR" --json
+```
+
+API tokens are created in the web app under Settings → API Tokens. The CLI sends them with `X-Quire-API-Key`, uses `QUIRE_API_URL` when pointing at a non-production Quire app, and syncs runs under the token's environment name so Cursor Cloud, Codex, and CI activity can be grouped separately from direct human sessions.
+
 ## Hosted Model-Source Status
 
 Use `quire whoami --json` to check the authenticated account and hosted model-source status before relying on remote Quire Credits behavior:

package/dist/{chunk-e9Ob2GDo.mjs → chunk-Vs_PY4HZ.mjs}

@@ -6,7 +6,17 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -21,6 +31,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
+var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
-export { __require as n, __toESM as r, __commonJSMin as t };
+export { __toCommonJS as a, __require as i, __esmMin as n, __toESM as o, __exportAll as r, __commonJSMin as t };