# ProtoPeek — setup guide for Claude Code (and other AI coding agents)

You are an AI coding agent. A developer pointed you at this page to set up **ProtoPeek** in
their project. ProtoPeek hosts a self-contained HTML prototype behind a private, time-boxed
link, lets invited reviewers pin comments right on the page, and gives you an agent-shaped
feedback payload to synthesize. Your job: complete the setup below, then tell the user you're
ready and show them the workflow. Work through the steps in order. Be concise with the user.

## What you will set up
- Three slash commands in the project's `.claude/commands/`: `/proto-up`, `/proto-status`,
  `/proto-feedback`.
- Two variables in the project's `.env`: `PROTOPEEK_BASE_URL` and `PROTOPEEK_API_KEY`.

## Step 1 — Make sure the user has an account and an API key
Tell the user to:
1. Create an account (or log in) at https://protopeek.dev/accounts/signup/
2. Open the dashboard at https://protopeek.dev/dashboard/ and copy their API key (it starts with `pp_`).
3. Paste that API key to you here in the chat.

Never ask for their password — you only need the API key. If they already have a key, just
ask them to paste it. Do not proceed to Step 2 until you have a key that starts with `pp_`.

## Step 2 — Configure the project
Create or edit the project's `.env` and add these two lines (make sure `.env` is gitignored):

```
PROTOPEEK_BASE_URL=https://protopeek.dev
PROTOPEEK_API_KEY=<the key the user pasted>
```

Never commit the API key and never print it back to the user.

## Step 3 — Install the three slash commands
Create the directory `.claude/commands/` in the project if it does not exist, then create each
file below with the EXACT content shown (keep the `---` frontmatter). These are curl-based and
read the two `.env` variables from Step 2.

### Save as `.claude/commands/proto-up.md`

````md
---
description: Upload a self-contained HTML prototype to ProtoPeek and print the shareable URL.
argument-hint: <path-to-html> [--name "..."] [--allow domain-or-email] [--expires <hours>] [--update <url-or-uuid>]
allowed-tools: Bash
---

Upload an HTML prototype to ProtoPeek and return a shareable link.

Arguments: `$ARGUMENTS`
- First token is the path to the self-contained `.html` file.
- Optional flags:
  - `--name "..."` — display name (defaults to the file name).
  - `--allow <domain-or-email>` — add an allowlist rule (repeatable; comma-separate values).
  - `--expires <hours>` — link lifetime in hours (default 48).
  - `--update <url-or-uuid>` — publish a NEW VERSION behind the same link (no link churn).

Steps:
1. Load config from the environment or the project `.env`:
   `PROTOPEEK_BASE_URL` (e.g. `http://127.0.0.1:8000`) and `PROTOPEEK_API_KEY`.
   If either is missing, stop and tell the user to set them in `.env`.
2. Parse the path and flags from `$ARGUMENTS`. Split `--allow` values into `domains`
   (no `@`) and `emails` (contains `@`), joined comma-separated.
3. If `--update` is given, extract the trailing UUID from the URL and pass `update_of=<uuid>`.
4. Run curl (multipart):
   ```bash
   curl -s -X POST "$PROTOPEEK_BASE_URL/api/prototypes" \
     -H "X-API-Key: $PROTOPEEK_API_KEY" \
     -F "html=@<path>;type=text/html" \
     -F "name=<name>" \
     -F "domains=<domains>" \
     -F "emails=<emails>" \
     -F "expires_hours=<hours>" \
     -F "update_of=<uuid-if-any>"
   ```
5. Parse the JSON response and print, clearly:
   - the **shareable URL** (`url`),
   - the version number and the expiry time.
   Then remind the user: send the URL to reviewers; run `/proto-status <url>` to poll,
   `/proto-feedback <url>` to pull and synthesize.

Do not echo the API key. If the response is an error, show the status and `detail`.
````

### Save as `.claude/commands/proto-status.md`

````md
---
description: Cheap "is there new feedback?" poll for a ProtoPeek prototype (does not consume the new-since watermark).
argument-hint: <url-or-uuid>
allowed-tools: Bash
---

Check activity on a ProtoPeek prototype WITHOUT advancing its "new since last pull"
watermark — safe to run repeatedly.

Arguments: `$ARGUMENTS` — a share URL or a bare UUID.

Steps:
1. Load `PROTOPEEK_BASE_URL` and `PROTOPEEK_API_KEY` from the environment or `.env`.
2. Extract the UUID (the trailing path segment of a `/p/<uuid>` URL, or the bare value).
3. Run:
   ```bash
   curl -s "$PROTOPEEK_BASE_URL/api/prototypes/<uuid>/status" -H "X-API-Key: $PROTOPEEK_API_KEY"
   ```
4. Report concisely: prototype name + version, whether it's live/expired, and the
   status counts — `distinct_reviewers`, `total_comments`, **`new_since_last_pull`**
   (the load-bearing "worth re-pulling?" signal), and `last_activity`.
   If `new_since_last_pull > 0`, suggest running `/proto-feedback <url>`.

This endpoint is read-only and does not change the watermark; only `/proto-feedback` does.
````

### Save as `.claude/commands/proto-feedback.md`

````md
---
description: Pull ProtoPeek feedback and synthesize it into themes, attributions, conflicts, and a proposed change list.
argument-hint: <url-or-uuid>
allowed-tools: Bash
---

Pull the agent-shaped feedback for a ProtoPeek prototype and **synthesize** it —
do NOT just dump the raw comments.

Arguments: `$ARGUMENTS` — a share URL or a bare UUID.

Steps:
1. Load `PROTOPEEK_BASE_URL` and `PROTOPEEK_API_KEY` from the environment or `.env`.
2. Extract the UUID.
3. Fetch the payload (this advances the "new since last pull" watermark):
   ```bash
   curl -s "$PROTOPEEK_BASE_URL/api/prototypes/<uuid>/feedback" -H "X-API-Key: $PROTOPEEK_API_KEY"
   ```
   The payload has `prototype`, `status`, and `annotations[]` (each with
   `css_selector`, `element_snapshot`, `note`, `type`, `author`, `version`,
   `resolved`, and a `thread[]` of replies).

Then produce a synthesis, not a transcript:
- **Themes** — group annotations by what they're really about (e.g. "pricing clarity",
  "header/nav", "copy tone"). For each theme, attribute: "2 of 3 reviewers flagged …".
- **Conflicts** — call out where reviewers disagree (e.g. one wants more density,
  another less).
- **Anchored change list** — concrete proposed edits, each mapped to the
  `css_selector`/element it targets and the reviewers who motivated it, ordered by
  impact. Distinguish must-fix from nice-to-have.
- **Status line** — reviewers, total comments, and how many are new since the last pull.

Close by offering to make the changes: regenerate the prototype, then
`/proto-up <path> --update <url>` to publish a new version behind the same link.
````

## Step 4 — Confirm and show the workflow
Tell the user setup is complete, then explain the loop:
- `/proto-up ./prototype.html` — uploads a self-contained HTML prototype and prints a shareable
  link to send reviewers. Add `--allow you@company.com` or `--allow company.com` to widen the
  reviewer allowlist; `--update <link>` publishes a new version behind the same link.
- `/proto-status <link>` — a cheap "is there new feedback yet?" check.
- `/proto-feedback <link>` — pulls the feedback and synthesizes it into themes, conflicts, and a
  concrete change list mapped to the prototype. Iterate: regenerate → `/proto-up --update` → repeat.

Then offer to generate a first prototype and run `/proto-up` on it so the user sees the loop.

---
ProtoPeek · https://protopeek.dev · a product of Brightwing Systems, LLC