# Phuze Setup — Agent Instructions

Phuze is an email magic link auth service. Clients register via API, embed a JS widget, and verify sessions server-side with one fetch call.

Base URL: `https://phuze.edato.me/api/v1`
Widget: `https://phuze.edato.me/phuze.js`
Intro: `https://phuze.edato.me/intro`
Docs: `https://phuze.edato.me/docs`

> **Already have `publishable_key` and `secret_key`?** Skip to [phuze-skill.md](https://phuze.edato.me/phuze-skill.md) for integration instructions.

---

## ⚠ Alpha Access Required

Phuze is currently invite-only. Registration returns `403 Forbidden` unless the user's email is approved or they provide an invite code.

If you receive `403`, stop. Tell the user: "Your email is not approved for Phuze alpha — contact phuze-alpha@edato.me to request access, or share an invite code."

---

## AGENT INSTRUCTIONS — Complete This Before Writing Any Code

**You run the curl commands below.** Do not insert placeholder keys. Do not ask the user to register manually. The user only needs to check their email for a 6-digit code.

If your environment does not support command execution, ask the user to run the exact curl commands and paste the full JSON response back to you. Do not proceed until you have real key values.

---

**Follow these steps exactly, in order:**

1. **Ask the user:** "What email address should I register your Phuze account with? You'll receive a 6-digit code there."
2. **Ask the user:** "What domain will this app be hosted on? (e.g. `myapp.com` — no `https://`, no trailing slash)"
3. **Ask the user:** "Do you have a Phuze invite code? Share it now if so — otherwise I'll try registering without one."

4. **YOU run this curl command now** (fill in real values; include `invite_code` only if provided):

```bash
curl -X POST https://phuze.edato.me/api/v1/clients \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","email":"USER_EMAIL","domains":["USER_DOMAIN"]}'

# With an invite code:
# -d '{"name":"My App","email":"USER_EMAIL","domains":["USER_DOMAIN"],"invite_code":"XXXX-XXXX-XXXX"}'
```

   - **`403 Forbidden`:** Stop. Tell the user their email is not approved. Do not write any code.
   - **Success:** You receive `{ "client_id": "cl_...", "status": "pending" }`. Continue.

5. **Tell the user:** "Check your email for a 6-digit activation code and give it to me."
6. **Wait for the code**, then **YOU run this curl command**:

```bash
curl -X POST https://phuze.edato.me/api/v1/clients/activate \
  -H "Content-Type: application/json" \
  -d '{"email":"USER_EMAIL","code":"CODE_FROM_USER"}'
```

7. **The response contains three keys — shown only once.** Save them immediately to the project's environment variables:

| Response field | Environment variable | Scope |
|---|---|---|
| `publishable_key` | `NEXT_PUBLIC_PHUZE_PUBLISHABLE_KEY` | Frontend (safe to expose) |
| `secret_key` | `PHUZE_SECRET_KEY` | Server only — never expose |
| `cli_token` | *(optional)* | CLI management |

8. **Setup complete.** Continue to [phuze-skill.md](https://phuze.edato.me/phuze-skill.md) for widget integration and session verification.

---

→ **Next: [phuze-skill.md](https://phuze.edato.me/phuze-skill.md)** — Widget integration, server-side verification, TypeScript types, common pitfalls.