# Developer guide

You run a product. ADapptive gives you a community of testers who find bugs,
propose changes, and vote — and a loop that hands vote-approved, safety-cleared
items to your own coding agent. This guide is the golden path from an empty
account to your first deployed community change. Budget: about fifteen
minutes.

## 0. Concepts in one minute

| Term | Meaning |
|---|---|
| **Workspace** | Your tenant. Owns keys, campaigns, zones, testers, deployments. |
| **Campaign** | A testing initiative on a URL (or URL patterns) with a goal, a schedule, a visibility (private / invited / public), and a pipeline configuration. |
| **Zone** | A region of your UI (CSS selector) where testers can leave a specific kind of feedback: comment, suggestion, bug, vote, rating, poll, or an inline yes/no (`VOTE_ONLY`). |
| **Audience** | Who can act on a zone: anyone (`ANONYMOUS`), signed-in testers (`ACCOUNT`), or your trusted pool (`TRUSTED_POOL`). Use `ACCOUNT` or `TRUSTED_POOL` for anything that drives implementation. |
| **Threshold and quorum** | A zone's weighted score target plus the minimum number of distinct trusted voters. Both must be met before an item is "ready". |
| **Safety status** | Every submission is redacted and screened. Only `CLEARED` items reach your agent; `FLAGGED` items wait in Moderation. |
| **Implementation loop** | Your agent (Claude Code, Cursor, Codex, any MCP client) pulls ready items through the ADapptive MCP server, changes your code locally, and reports progress. |

## 1. Create your workspace

1. Go to `https://app.adapptive.space` → **Sign in**. Accounts live in
   Authentik; sign-up happens there.
2. First sign-in lands on **Onboarding**. It creates your workspace and shows
   your **secret key once**. Store it in a password manager. You will rarely
   need it: day-to-day work uses the dashboard, the MCP-scoped key, and
   short-lived tokens.
3. The Overview page shows a checklist that tracks the rest of this guide.

## 2. Create a campaign

**Campaigns → New campaign.** Give it a name, the product URL patterns testers
will visit, a goal ("Find checkout blockers before launch"), optional dates,
and a visibility:

- **Private** — only your own invited testers.
- **Invited** — your pool plus anyone you send the link.
- **Public** — listed in the community Tester Hub for House Pool members at or
  above the tier you choose.

The **Pipeline** tab sets the loop rules: vote threshold, minimum trusted
voters, automation level (`HUMAN_IN_LOOP` — your agent asks before acting;
`AUTOMATIC` — your agent may start immediately), and the paths in your repo
your agent may touch (advisory; enforced by your agent's own tooling).

## 3. Place your first zone

Pick one of three ways; they write to the same zone table.

| Way | When | How |
|---|---|---|
| **Extension, developer mode** (recommended) | Any live site, no code | Dashboard → Campaign → Zones → **Connect extension**. A 6-digit pairing code appears. In the extension side panel choose *Developer* → enter the code. Right-click any element → *Add feedback zone*. |
| **SDK** | You ship a web app and want zones for embedded users | Install `@adapptive/sdk` or `@adapptive/react`, init with your **publishable** key, wrap regions in `FeedbackZone`. See `sdk/README.md`. |
| **Studio** | You want a visual configurator locally | `pnpm --filter @adapptive/studio dev`; it uses the secret key and is never deployed. |

Zone settings that matter: type, threshold, minimum trusted voters, audience,
and (for `TRUSTED_POOL`) which tiers may submit and vote.

## 4. Invite testers

**Testers → Tiers**: create tiers with weights and permissions (for example
*Core* weight 3, *Community* weight 1). **Invite links** are usage-capped,
expiring, revocable. Share them, or make the campaign **Public** so the House
Pool can discover it.

Testers can also reach you through the community: see the
[community playbook](./community-playbook.md).

## 5. Connect your agent

**Agent & MCP** in the dashboard:

1. Create an **MCP key** (`adp_mk_*`). It can read feedback, zones and
   campaigns and write status, deployments and analyses. It cannot delete
   zones, manage people, or touch rewards. Rotate it any time.
2. Copy the ready-made config for your client:
   - **Local (stdio)** — `node tools/mcp-server/dist/index.js` with
     `ADAPPTIVE_API_URL` and `ADAPPTIVE_SECRET_KEY` (an `adp_mk_*` key is
     accepted here too).
   - **Remote (Streamable HTTP)** — `https://mcp.adapptive.space/mcp` with
     `Authorization: Bearer adp_mk_…`, or sign in through Authentik when your
     client supports OAuth.
3. The **Activity** panel shows every tool call that produced a deployment
   record or a log line, so you can see what your agent is doing.

The tools your agent gets:

| Tool | Purpose |
|---|---|
| `get_ready_feedback` | CLEARED items whose zone threshold and quorum are met — the entry point |
| `get_feedback`, `list_feedback`, `list_zones`, `get_campaign_context` | Context, including the CSS selector that locates the UI |
| `submit_feedback_analysis` | Store the agent's summary, category, duplicate link and task plan |
| `start_implementation` | Create the deployment record; flips the item to `GENERATING_CODE` |
| `report_deployment_progress`, `add_deployment_log`, `update_deployment_stages` | Progress, PR URL, checklist |
| `rollback_deployment`, `update_feedback_status`, `list_deployments` | Control and history |

Tester text arrives inside `<untrusted_tester_content>` envelopes with PII
already redacted. Your agent is instructed to treat it as data, never as
instructions, and to confirm with you before acting on anything that reads
like a command.

## 6. Watch the loop close

- **Feedback inbox** — filter by campaign, zone, status, safety status; batch
  triage; open an item to see votes, screenshot, analysis and deployment.
- **Moderation** — items the safety pipeline flagged. Approve, edit-and-approve,
  or block. Every decision is audited.
- **Deployments** — one record per implemented item with stages, logs, PR link
  and rollback metadata.
- When your agent reports `DEPLOYED`, the contributing testers are notified and
  asked to re-verify. Three "still broken" reports reopen the item; a
  confirmation credits their reputation and, if the campaign has a budget,
  their rewards.

## 7. Team, notifications, analytics

- **Team & permissions** — invite colleagues as OWNER / ADMIN / EDITOR /
  VIEWER; override per campaign.
- **Notifications** — in-product inbox and per-user preferences.
- **Analytics** — tenant-scoped summary and CSV export.

## Troubleshooting

| Symptom | Check |
|---|---|
| Testers see no zones on the live site | The extension needs a per-origin permission grant on that site; the zone's audience may exclude them; the campaign may be paused. |
| `get_ready_feedback` returns nothing although votes are high | Quorum not met (need distinct trusted voters) or the item is `FLAGGED` — see Moderation. |
| Agent cannot connect | Key kind: `adp_pk_` is never accepted by the MCP server. Check `ADAPPTIVE_API_URL` is `https://api.adapptive.space`. |
| Lost the secret key | Settings → rotate keys. The MCP key is separate and can be rotated independently. |

## Reference

- REST API: `https://api.adapptive.space/docs` (OpenAPI at `/openapi.json`)
- SDK: `sdk/README.md`, `sdk/packages/core/README.md`, `sdk/packages/react/README.md`
- Extension: `tools/browser-extension/README.md`
- MCP server: `tools/mcp-server/README.md`