# .cursorrules — TestMyVibes Auto-Test Loop

When the user asks you to "test and fix until passing" or "run the TestMyVibes loop",
follow these rules exactly.

## TestMyVibes Auto-Test Loop (Cursor)

You are running a bounded "publish → test → fix → republish" loop using TestMyVibes
human + AI QA. Follow these steps EXACTLY. Do not skip the guard rails.

### Configuration

- TESTMYVIBES_API_KEY = {{API_KEY}}
- PROJECT_URL         = {{PROJECT_URL}}
- MAX_ITERATIONS      = 5
- CREDIT_BUDGET       = 25   # total credits allowed across the whole loop
- API_BASE            = https://testmyvibes.com

### Loop

Repeat steps 1–6 up to MAX_ITERATIONS times.

1. **Publish.** Run the user's deploy command (e.g. `vercel --prod`, `git push`, or whatever the project uses) and wait for it to finish.
   Confirm the deployed PROJECT_URL is reachable before continuing.

2. **Trigger a test.** POST to `https://testmyvibes.com/v1/replit/test`. Always send the
   `X-Agent-Skill` and `X-Agent-Iteration` headers so the dashboard can
   group consecutive jobs into a single loop session and show users how many
   credits the whole loop consumed:
   ```http
   POST https://testmyvibes.com/v1/replit/test
   Authorization: Bearer {{API_KEY}}
   Content-Type: application/json
   X-Agent-Skill: cursor
   X-Agent-Iteration: <N>           # 1 on first run, increment each loop

   {
     "url": "{{PROJECT_URL}}",
     "feature": "<short description of what changed this iteration, or omit on first run>",
     "accessInstructions": "<optional: admin login or how to reach protected areas, e.g. 'login at /admin with user/pass admin@test.com / s3cret'>"
   }
   ```
   Save the returned `jobId`, `creditsDeducted`, and `loopSession.id`
   (the server returns it on the first iteration; reuse it on later iterations).
   Track a running total: `creditsUsed += creditsDeducted`.

3. **Budget check.** If `creditsUsed >= CREDIT_BUDGET`, STOP and report
   to the user: "Credit budget reached after N iterations." Then call the
   finalize endpoint so the dashboard records why the loop ended:
   ```http
   POST https://testmyvibes.com/v1/replit/loop-session/<loopSession.id>/finalize
   Authorization: Bearer {{API_KEY}}
   Content-Type: application/json

   { "finalStatus": "budget_exhausted" }
   ```
   Do not run another test.

4. **Wait for the agent plan.** Poll
   `GET https://testmyvibes.com/v1/replit/agent-plan/:jobId?iteration=<N>` every 30 seconds
   (with the same `Authorization: Bearer` header) until the response has
   `ready: true`. While not ready, the response includes
   `estimatedWaitMinutes` — surface that to the user so they know the wait.
   The server echoes back `iteration` and includes a `loopSession` summary
   so you can stitch the timeline together. Stop polling after 90 minutes and
   report a timeout.

5. **Inspect the plan.**
   - If `nextStep === "all_clear"`: STOP. Report success to the user with
     the final `healthScore` and a link to the job's report.
   - Otherwise (`nextStep === "fix_and_retest"`), the response includes
     `actions`, an array of `{ type: "fix", bugTitle, severity, suggestedFix,
     reproductionSteps, checklistItemId? }`. Apply EACH `suggestedFix` as a
     code change. Be conservative — keep changes minimal and scoped to the
     described bug.
   - **Fallback:** if `nextStep === "fix_and_retest"` but `actions` is
     empty, call `GET https://testmyvibes.com/v1/replit/status/:jobId` and read
     `result.items[]` — the failing items (`status === "fail"`) include a
     `note` (and sometimes a `screenshotUrl`) describing what broke. Fix
     from those instead.
   - The response also includes `retestCommand: { method, url, body }`.
     Re-use the `url` and `body` for step 2 of the next iteration, but
     remember to (a) re-add the `Authorization: Bearer` header — it is NOT
     in the body — and (b) optionally set `body.feature` to a short
     description of what you just changed, so the next test run can focus on
     the fix.

6. **Same-bug guard.** Before starting iteration N+1, compare `actions[].bugTitle`
   from this iteration to the previous iteration's titles. If TWO consecutive
   iterations report the same bug title — OR if two consecutive iterations
   both return empty `actions` while `nextStep` is still `fix_and_retest` —
   STOP, finalize the loop with `{ "finalStatus": "same_bug_twice" }`, and
   ask the user how to proceed. Do not silently keep trying. (The server also
   detects identical bug titles independently and will set
   `loopSession.finalStatus = "same_bug_twice"`.)

After MAX_ITERATIONS, STOP, finalize the loop with
`{ "finalStatus": "max_iterations" }`, and summarize: how many bugs were
fixed, how many remain, and total credits consumed. When the loop finishes
cleanly the server already records `finalStatus: "all_clear"`, so no
finalize call is needed in that case.

### Multi-role scenarios (use `/v1/replit/sessions` instead of `/v1/replit/test`)

Some apps only make sense when **two or more users interact at the same time**:
a buyer browses a seller's listing, a host invites a guest into a room, an admin
moderates a member's post. A single tester running through a checklist alone
cannot exercise those flows. For these scenarios, **switch from
`POST /v1/replit/test` to `POST /v1/replit/sessions`** so the platform books
multiple human checkers into the same coordinated session.

Pick `/v1/replit/sessions` whenever the user describes the app using two or
more named roles (e.g. "buyer + seller", "host + guest", "admin + member",
"teacher + student", "driver + rider"). Otherwise stick with the single-tester
`/v1/replit/test` flow above.

```http
POST https://testmyvibes.com/v1/replit/sessions
Authorization: Bearer {{API_KEY}}
Content-Type: application/json
X-Agent-Skill: cursor
X-Agent-Iteration: <N>

{
  "url": "{{PROJECT_URL}}",
  "feature": "<short description of the multi-role flow>",
  "scenarioBrief": "<1-3 sentences describing what each role does, e.g. 'Seller posts a listing. Buyer finds it via search and completes checkout. Admin reviews the order in the dashboard.'>",
  "slots": [
    { "roleLabel": "Seller", "targetDevice": "desktop" },
    { "roleLabel": "Buyer",  "targetDevice": "mobile" },
    { "roleLabel": "Admin" }
  ],
  "accessInstructions": "<optional: per-role logins, e.g. 'Seller: seller@test.com / pw. Buyer: buyer@test.com / pw.'>"
}
```

`slots` schema:

- 2-10 entries, one per simultaneous role.
- `roleLabel` (required) — short human label like "Seller", "Buyer", "Host".
- Optional targeting fields per slot: `targetDevice` (`desktop` | `mobile` |
  `tablet`), `targetOS`, `targetBrowser`, `targetScreenSize`,
  `targetNetwork`. Omit any field you don't care about.

The response includes `sessionId`, `checkerCount`, `creditsDeducted`
(= per-slot cost × number of slots), `creditsRemaining`, `sessionUrl`, and a
`slots[]` array where each entry has its own `jobId` and `statusUrl`. Each
slot's `jobId` plugs into the same `GET /v1/replit/status/:jobId` and
`GET /v1/replit/agent-plan/:jobId` endpoints used by the single-tester loop —
poll each one and apply fixes the same way as steps 4-6 above. Each session
deducts `perSlot × slots.length` credits, so size your CREDIT_BUDGET
accordingly.

Note: `POST /v1/replit/sessions` does NOT return a `loopSession` object in
its response — loop-session tracking (and the
`/v1/replit/loop-session/:id/finalize` call) only kicks in once you start
sending follow-up `POST /v1/replit/test` calls with the
`X-Agent-Skill`/`X-Agent-Iteration` headers to fix bugs surfaced by the
session. Treat the initial `/sessions` POST as iteration 0 (a one-shot
multi-role probe), then run the standard single-tester loop above against the
deployed app for each iteration of fixes.

### Server-side budget enforcement

The same MAX_ITERATIONS / CREDIT_BUDGET caps are also enforced server-side per
project, so even if you ignore the rules above the API will refuse the call.
If `POST /v1/replit/test` returns HTTP **429** with one of these codes,
STOP IMMEDIATELY — do NOT retry blindly:

- `AUTO_LOOP_BUDGET_EXCEEDED` — the project hit its per-window iteration
  or credit cap. The response includes `windowMinutes`, `iterations`,
  `maxIterations`, `creditsSpent`, and `creditBudget`. Finalize the loop
  with `{ "finalStatus": "budget_exhausted" }` and tell the user to raise
  the budget on the project page or wait for the window to roll over.
- `AUTO_LOOP_PAUSED` — the user hit "Pause auto-testing" on the dashboard.
  Finalize with `{ "finalStatus": "stopped" }` and tell the user the loop
  was paused from the dashboard.

### Hard rules

- Never exceed MAX_ITERATIONS or CREDIT_BUDGET.
- Never store TESTMYVIBES_API_KEY in code that gets committed publicly.
- Never call `/v1/replit/test` more than once per iteration.
- Never apply a fix you don't understand — if a `suggestedFix` is unclear,
  STOP and ask the user.
- Always show the user the link to the latest job so they can watch the screen
  recording (the dashboard shows it under Reports).

### Why this is bounded

Each test consumes real credits (typically 1–5 per run). The loop is capped so
a runaway agent cannot drain the user's account. The "same bug twice" rule
prevents the agent from burning credits chasing an unfixable issue.