@quireco/cli 0.0.6 → 0.0.9

package/README.md

@@ -28,40 +28,44 @@ vp pack
 node dist/quire.mjs --help
 ```
 
-## Workspace target (`quire env`)
+## Project runbook
 
-`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:
+Project-specific target guidance lives in `.quire/runbook.md`. The runbook is a committed Markdown file for deployments, local URLs, mobile app IDs, verification commands, safety rules, setup scripts, test accounts, and runner requirements. Quire does not pre-classify every run as web, mobile, or code before the agent starts; it gives the agent the runbook path, caller context, runtime capabilities, and request so the agent can resolve the target or report the smallest missing context.
 
-```bash
-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
+Create or refresh the runbook with:
 
-quire env set platform=ios provider=local appId=com.example.app
-quire env set kind=mobile platform=android                 # switch web → mobile
-quire env unset device
+```bash
+quire setup
 ```
 
-Named environments live under `.quire/environments/<name>.json` and are selected with `--env`:
+A typical runbook includes sections like:
 
-```bash
-quire env init --web --env local
-quire env init --web --env prod --base-url https://app.example.com
-quire "Verify checkout" --env prod
-```
+```markdown
+# Quire runbook
 
-`set` accepts one or more `key=value` pairs and validates the result against the schema before writing. Valid keys depend on `kind`:
+## How to choose a target
 
-- **Web**: `baseUrl`
-- **Mobile**: `platform` (`ios`/`android`), `provider`, `device`, `appiumUrl`, `url`, `appId`, `appPath`
+If the user says prod, use the production deployment in read-only mode.
+If the user asks for local verification, use the provided URL or `$QUIRE_WEB_URL`.
+Do not guess ports or app IDs.
 
-Setting `kind=mobile` (or `kind=web`) switches the union shape and drops incompatible fields. Use `quire env init --force` to start over from a stub.
+## Deployments
+
+### dev
+
+URL: https://dev.example.com
+Safe for test accounts.
+
+## Verification procedures
+
+Run `vp check` for static checks and `vp test` for unit tests.
+```
+
+The removed `quire env` command now prints a migration message that points to `.quire/runbook.md`.
 
 ## Doctor
 
-`quire doctor` diagnoses the current setup before you start an investigation. It checks identity (auth + model broker), workspace (`.quire/environment.json` + target reachability), and run state (runs root writable, no stuck runs):
+`quire doctor` diagnoses the current setup before you start an investigation. It checks identity (auth + model broker), workspace runbook state, and run state (runs root writable, no stuck runs):
 
 ```bash
 quire doctor                # human-readable report, grouped by section
@@ -69,9 +73,7 @@ quire doctor --json         # structured report for agents/CI
 quire doctor --strict       # exit non-zero on warnings as well as failures
 ```
 
-Each check has a stable `id` (e.g. `auth.present`, `target.web.reachable`, `target.mobile.device`) so coding agents can act on specific failures without parsing prose. Failing checks include a `fix.command` you can run to resolve them. Exit code is `0` when all checks pass (or only warnings in non-strict mode) and `1` otherwise.
-
-Target reachability runs by default: web environments are probed with a HEAD request, iOS local environments check `xcrun simctl list devices booted`, Android local checks `adb devices`, and Appium providers ping `/status`.
+Each check has a stable `id` (e.g. `auth.present`, `auth.valid`, `runbook.present`, `runbook.readable`, `runs.rootWritable`) so coding agents can act on specific failures without parsing prose. Failing checks include a `fix.command` you can run to resolve them. Exit code is `0` when all checks pass (or only warnings in non-strict mode) and `1` otherwise.
 
 ## Investigations
 
@@ -93,58 +95,55 @@ Coding agents and scripts should use `--json`. JSON mode returns a durable run h
 
 ```bash
 quire investigate "Reproduce the checkout crash" --json
-cat issue.md | quire investigate --stdin --json
-quire report <run-id> --wait --json
+cat issue.md | quire investigate --json
+quire status <run-id> --json
+quire watch <run-id>
 ```
 
 Continue a previous session when the first run needs more context or a retry:
 
 ```bash
 quire continue <run-id> "Use the seeded buyer account and retry checkout"
-printf 'Fixture account: buyer@example.com\n' | quire continue <run-id> --stdin --json
+printf 'Fixture account: buyer@example.com\n' | quire continue <run-id> --json
 ```
 
-`continue` starts a new linked run, forks the prior Pi session when available, and injects the previous report, handoff, evidence summary, and new caller context. The original run remains immutable.
+`continue` starts a new linked run, forks the prior harness-native session when available, and injects the previous transcript, handoff, evidence summary, and new caller context. The original run remains immutable.
 
-`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:
+`investigate` carries a deliberately small flag surface. Target context belongs in the prompt, `--url`, `$QUIRE_WEB_URL`, and `.quire/runbook.md`. Piped stdin is read automatically when stdin is a pipe or redirected file. If a positional prompt is also present, the prompt steers the piped context. 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 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.
-- `--env <name>` uses `.quire/environments/<name>.json` instead of the default `.quire/environment.json`.
+- `--headed` shows the browser window when browser automation is used.
+- `--url <url>` provides an explicit caller-context URL for one run. It does not force the run to be a web target; the agent still resolves what the URL means from the request and runbook.
 
-Top-level shortcuts mirror the most common run subcommands:
+The top-level prompt form and the explicit investigate command are equivalent:
 
 ```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`
+quire "Verify checkout before I approve this PR"
+quire investigate "Verify checkout before I approve this PR"
 ```
 
-Less common run operations stay under the canonical `runs` namespace: `quire runs status|cancel|list ...`.
+Run lifecycle operations are top-level verbs: `quire status <run-id>`, `quire watch <run-id>`, `quire cancel <run-id>`, and `quire sync <run-id>`. The plural `quire runs` command lists recent runs.
 
-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.
-Runs also store a local Pi session under the run directory so `quire continue` can resume prior context without syncing raw prompts, completions, or provider credentials.
+Each run writes a small artifact contract under `~/.local/share/quire/runs/<workspace-key>/<run-id>/` by default:
 
-`report.json` is the structured source of truth. The stable top-level fields include:
+```text
+run/
+  status.json
+  progress.jsonl
+  handoff.md
+  evidence/
+  .harness-sessions/
+    <session-id>.jsonl
+```
 
-- `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
+Set `QUIRE_RUNS_DIR` to override the run-artifact root. `status.json` is Quire-owned operational state: lifecycle status, run metadata, request metadata, sync state, harness-session pointers, and final handoff/result JSON. `progress.jsonl` is the user-visible narrated timeline that powers `quire watch` and synced case events. `handoff.md` is the durable user-facing output. `evidence/` contains artifacts referenced by the progress stream or handoff. Harness-native transcripts live in hidden `.harness-sessions/` files and are referenced from `status.json`; they are private implementation state, not the public Quire run ledger.
 
-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 local GitHub Copilot auth, then Quire Credits through Quire's authenticated broker. Quire-owned provider auth is read from `~/.local/share/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.
 
-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 local ChatGPT/Codex auth, local GitHub Copilot auth, and Quire Credits brokered through Cloudflare AI Gateway.
 
-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.
+Authenticated runs fetch remote Quire run add-ons at startup. Run add-ons can include an Agent Skills-compatible skill pack, a Quire MCP gateway configured in the web app, and non-authoritative team or user guidance. The CLI-owned run instructions, safety contract, progress protocol, and handoff protocol remain authoritative. Quire includes the `agent-browser` skill by default, then layers dashboard-uploaded skills on top. The CLI downloads skill ZIPs only when the server hash changes, verifies them, unpacks them under `~/.local/share/quire/skill-packs/`, and attaches the unpacked root to Pi through native `additionalSkillPaths` so skills follow Pi's normal progressive-disclosure behavior. If an MCP gateway is present, the CLI exposes it as the Pi custom tool `quire_mcp_call`; tool execution is brokered through the authenticated Quire API and is limited to safe allowlisted tools. Run metadata records run-instruction ids/hashes, run add-on ids/hashes, skill pack id/hash/source, and MCP gateway id/hash/tool metadata, not raw prompts, raw skill instructions, resource files, provider credentials, or API tokens.
 
 Use `quire connect chatgpt` when you want Quire to connect ChatGPT/Codex subscription auth without using the Pi CLI first:
 
@@ -155,6 +154,14 @@ 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.
 
+Use `quire connect copilot` when you want Quire to connect GitHub Copilot subscription auth. Pass `--github-enterprise <url-or-domain>` for GitHub Enterprise, or omit it for the interactive prompt and press Enter for github.com.
+
+```bash
+quire connect copilot
+quire connect copilot --github-enterprise company.ghe.com
+quire connect copilot --github-enterprise company.ghe.com --json
+```
+
 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:
@@ -189,7 +196,7 @@ Use `quire whoami --json` to check the authenticated account and hosted model-so
         "modelId": "gpt-4.1-mini",
         "status": "succeeded",
         "totalTokens": 13,
-        "runId": "run_123",
+        "runId": "run_9x4mdq7p2h8kc6nv4apz",
         "createdAt": "2026-05-18T06:00:00.000Z"
       }
     ]
@@ -198,26 +205,3 @@ Use `quire whoami --json` to check the authenticated account and hosted model-so
 ```
 
 The hosted status is a redacted summary from Quire's server-side model-source API. It does not include provider credentials, sealed envelopes, raw tokens, prompts, or completions. Local `quire investigate` can use local Pi/OpenAI auth when configured; Quire Credits and hosted/Slack-triggered execution use Quire-managed billing.
-
-Example web environment (write with `quire env init --web` and edit via `quire env set`):
-
-```json
-{
-  "version": 1,
-  "app": { "kind": "web", "baseUrl": "http://localhost:3000" }
-}
-```
-
-Example mobile environment:
-
-```json
-{
-  "version": 1,
-  "app": {
-    "kind": "mobile",
-    "platform": "ios",
-    "provider": "local",
-    "appId": "com.example.app"
-  }
-}
-```