# Probe Research — for agents

You are an agent. **Probe Research** records a team's ML work so people and agents can find it later: projects, experiments, runs, metrics, files, notes and the coding-agent sessions behind them. This page is your front door: how to get your user set up end to end, what to ask them, and what never to ask.

Hosts: API `https://api.research.prbe.ai` · dashboard `https://research.prbe.ai` · hosted MCP `https://mcp.research.prbe.ai/mcp`.

## The journey

1. **Sign the user up or in** — follow [auth.md](https://www.useprobe.ai/auth.md). The user's only browser step: open your link, sign in with Google, type your 6-digit code.
2. **Onboard them in chat** if they are new (your scope is `account:onboard`): see [Onboarding](#onboarding).
3. **Install Probe on their machine** if you run on it, for the coding agents they pick: see [Install](#install). One more click for the user.
4. **Work**: read and write research through the REST API, the MCP server or the `probe` CLI.

Check before acting: `GET /v1/me` with your token says who you act as, which team, and your scopes.

## Onboarding

When the claim returns `scope: "account:onboard"`, the user has a Probe account but no team. Set it up WITH them: ask, don't decide for them. Call these endpoints with your access token (`Authorization: Bearer <access_token>`). They change the account only while you hold `account:onboard`, which ends when you finish onboarding (step 6); an agent connected by a user who already has a team never gets it.

```http
GET https://api.research.prbe.ai/agent/onboarding
```

Returns their email, `team` (null for now), `pending_invites`, `onboarding_complete`, and `steps`: one entry per onboarding step with how you cover it (`api`, `browser_link`, `cli_install`). Then:

1. **Team.** If `pending_invites` is not empty, ask whether to join one:
   `POST /agent/onboarding/invites/{id}/accept`.
   Otherwise ask what to call their team (and a short lowercase slug, e.g. `acme-lab`):
   `POST /agent/onboarding/team` `{"display_name": "Acme Lab", "slug": "acme-lab"}`. A `409` with a `suggestion` means the slug is taken: offer the suggestion.
   If the user joins a team some other way (in the browser), you are not connected to it: register again (auth.md Step 3) and have them approve you for that team.
2. **Upgrade your token.** Joining or creating a team binds you to it. Exchange your `identity_assertion` again ([auth.md Step 6](https://www.useprobe.ai/auth.md)): the new token adds `research:read research:write research:delete`.
3. **Workspace.** Ask what to call their first workspace: `POST /v1/workspaces` `{"slug": "…", "name": "…"}`.
4. **Teammates.** Ask whether to invite anyone (team owners and admins only): `POST /agent/onboarding/invites` `{"email": "…"}`, once per person. They join as members and get an email; admins are made on the website.
5. **Integrations.** W&B, GitHub and other sources need secrets or an app install. Send the user to `https://research.prbe.ai/integrations`. Never ask for a key in chat.
6. **Finish.** `POST /agent/onboarding/complete`. This ends your `account:onboard` access; your next token carries only the research scopes. From then on the user manages the team (invites, roles) at `https://research.prbe.ai/team`. The response names the next step: the install.

## Install

If you run on the user's machine, install Probe there for the coding agents they choose. This sets up the `probe` CLI, the MCP server, research-tracking skills and, if the user agrees, session capture.

1. **List the coding agents.** Changes nothing and needs no sign-in:

   ```bash
   npx probe-research status --json
   ```

   `agents` has one entry for every coding agent Probe supports (Claude Code, Codex, pi and Kimi Code today). `installed: true` means it is on this machine; `configured: true` means Probe is already set up for it.

2. **Ask the user which to set up.** Show them the installed ones and say which are already set up. Don't choose for them.

3. **Install their picks**, one `--agent` per pick, using each entry's `agent` value:

   ```bash
   npx probe-research install --agent claude_code --agent pi --yes
   ```

It prints an approval link. Pass it to the user: they are already signed in, so it is one click, and that page is where they agree to stream this machine's coding sessions to their team. Ask before choosing capture on their behalf: `--no-capture` skips it.

The installer needs onboarding finished first; otherwise it stops and points at the website.

## Working with Probe

- **REST API** — `https://api.research.prbe.ai/v1/...` with `Authorization: Bearer <access_token>`. Projects (`/v1/projects`), experiments (a project with `kind: "experiment"`), runs, metrics, files, notes and search (`POST /v1/search`).
- **MCP** — `https://mcp.research.prbe.ai/mcp` with the same bearer: read-only search and reads.
- **CLI** — after the install, `probe` (run `probe --help`). The CLI signs in with its own keys.

Refresh your access token before it expires (1 hour) by exchanging your identity assertion again. If anything answers `invalid_grant`, the user revoked you or left the team: start over at auth.md Step 3.

## Ask the user / never ask

Ask: their sign-in email, the team name and slug, whether to join a pending invite, the workspace name, whom to invite, whether to turn on session capture, and before any delete or public share.

Never ask: passwords, API keys, W&B keys or any other secret — send them a browser link instead, because chats can be recorded. Never type the 6-digit code into the page yourself. Keep your own Probe credentials in one private file (see [auth.md](https://www.useprobe.ai/auth.md) Step 3) and never print them.

## Help

- Sign-in protocol: [auth.md](https://www.useprobe.ai/auth.md)
- Privacy: https://www.useprobe.ai/privacy/
- Contact: support@prbe.ai