# Install Probe

- Fetch pages only when a step names them, in one call, as raw text (a web-fetch tool summarises):
  `curl -fsSL -w '\n(end of %{url_effective})\n\n' "https://research.prbe.ai/{<pages>}.md"`. Never
  fetch one twice; any other page you need (credential.md, big-history.md, …): fetch it then.
- Spell every command `npx -y probe-research …`, never bare `probe` (not even `--help` or
  `--version`).
- Act on each result's `reason` (table below), never its exit code.
- To check this computer's state without changing it, run
  `npx -y probe-research status --json --refresh`; `sign-in` signs in.
- Ask each question with your question tool (AskUserQuestion in Claude Code, request_user_input in
  Codex), else numbered, and wait for its answer.
- Give an option a description only where the page writes one; never one that repeats its label.
  Pass labels and descriptions to the question tool as written; numbered, each line is "label: description".
- Never add notes of your own about the install (errors, retries, files you changed); one plain
  sentence only if the person must act.
- Windows: say "Probe runs on macOS and Linux for now." and stop.
- If a sandbox blocks the network, home-folder writes or a command, ask the person to allow
  them outside it.
- When a step can't finish (`incomplete` or a menu action that answered `ok: false`, after
  `npx -y probe-research repair --json` and one more try; or a reason the table says to stop on),
  say "If this keeps failing, run `npx -y probe-research wizard` in a terminal." `ok: true` with
  `complete: false` is no failure: show its unfinished lines once and go on.
- To remove Probe, follow uninstall.md.

## 1. Check this computer

Run `npx -y probe-research sign-in --json --if-needed`. If `setup.state` is `done`, or `partial`
without `signed_out`, fetch and follow already-set-up.md instead. Also if it is `unknown` and its `why` lists only `credential_unchecked` (the account check
went unanswered): never sign in. Otherwise it ran step 2's `sign-in --json` already.

## 2. Sign in

`npx -y probe-research sign-in --json` opens a browser tab. Show the person each `say` line as it
comes. Then run `npx -y probe-research sign-in --wait --json` with a 5-minute timeout, and wait until it finishes before going on, even if it moved to the background; repeat until `ok`.
Each run waits about 100 s, then answers `waiting_for_approval`; approved while Probe still installs, it
answers at once.
Say if its `account` changed. Keep its `attempt`. The Probe account is separate from the person's
login to you and its email: never compare them.

## 3. Setup

Ask "Full or Runs only?" (question tool):

- **Full**: Full agent toolset: automatically tracks experiment lineage and agent context, so your
  agent knows what your team already tried.
- **Runs only (SDK)**: Only track run metrics with our SDK; drop-in replacement for W&B, MLflow, etc.

Full: fetch `{full,past-work,wandb,example,finish}`, follow full.md. Runs only: fetch
`{runs-only,example,finish}`, follow runs-only.md.

## Reasons

| `reason` | Do |
|---|---|
| `waiting_for_approval`, `downloading`, `run_again`, `uninstall_running`, `updating` | Show its `say` line; run it again. |
| `setup_busy` | Retry every 30 s; after 10 minutes tell the person. |
| `daemon_chat`, `chat_not_on` | An older Probe: run it again once, then as a step that can't finish. |
| `directed_required` | Ask the person first (question tool), saying what stops; add `--directed` only on a yes. |
| `other_session` | Another chat's switch moves only from that chat. |
| `sandboxed` | Run it again outside your sandbox (your tool asks the person). |
| `onboarding_required` | Send the person its link. Not success. |
| `env_credential`, `server_override` | Follow credential.md. |
| `sign_in_expired` | Sign in again (step 2). |
| `account_changed` | Tell the person; sign in again only if asked. |
| `no_service`, `service_lost` | Run `npx -y probe-research repair --json`, then retry. |
| `incomplete_settings` | Say its `message` (in an install, after finish.md's ending); go on. |
| `agent_not_set_up`, `hosted_agent`, `incomplete` | Show its line and stop. |