# pingfusi — Full Reference

> Copy any site or element, then verify the result: file a test task, pingfusi
> tests your build, and structured results (pinned comments, per-step proof of
> work, screenshots) flow back to your agent. Plus quick subjective polls.

## Integration

### MCP (recommended)

pingfusi speaks the Model Context Protocol over a streamable HTTP transport
at `https://pingfusi.com/api/mcp`. One-command setup for Claude Code, Claude Desktop,
and Cursor:

```bash
npx pingfusi setup
```

Or add to your MCP client config manually:

```json
{
  "mcpServers": {
    "pingfusi": {
      "url": "https://pingfusi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

The MCP transport is **stateless** (no session required). You can also POST
JSON-RPC requests directly.

### Authentication

All requests must include `Authorization: Bearer <token>`. Tokens are
created and rotated from https://pingfusi.com/dashboard. The plaintext token is
shown exactly once on rotation — copy it then. Server stores only its
sha256 hash.

### Component-level feedback

pingfusi renders the build and pins comments to exact components, works through
the step checklist, and (for clone-compare tests) aligns elements onto the
original, all natively. Nothing to add to your build; just make the `url`
publicly reachable.

## Tools

Tools are named after the job you want done. One filing tool covers three
jobs — `pingfusi_review_website` (a page or build), `pingfusi_compare_clone`
(send `url` = the original/ground-truth and `draft_url` = your clone), and
`pingfusi_review_video` (pins `media_type='video'`; send `video_url`, never
`url`/`draft_url`) — so they share the input table below.

**Legacy tool names:** the original `cpyany_*` names (`cpyany_test`,
`cpyany_test_results`, `cpyany_poll`, `cpyany_poll_results`,
`cpyany_wait`, `cpyany_check_source`) are still registered and behave
identically, so older installs keep working. Use the job names for anything new.

### pingfusi_review_website / pingfusi_compare_clone / pingfusi_review_video

File a review round and start its automatic wait chain. Each client-safe leg
returns before common MCP timeouts. If pending, immediately call
`pingfusi_wait` and repeat while pending; never return pending to the user or
retry the original filing. Passive snapshots do not renew an idle task.
Uses 1 credit per completed result.

Verification is an iteration loop, not a one-shot check. After results arrive,
do not stop unless the verification returns an approval verdict (e.g. Pass /
Approved / Good to go) with no unresolved comments. If it returns Fail/Blocked,
requested changes, unresolved comments, or any non-approval verdict, update the
implementation, publish the fixed build again (a new `pingfusi publish` mints a
new /d/<slug>, so file the next round with the new URL — or redeploy your
preview), file another round, and repeat until it approves or the user
tells you to stop.

**Input:**

| field | type | required | description |
|-------|------|----------|-------------|
| `instructions` | string | yes | What to do, one step per line (10–1000 chars). Overwritten by `steps` texts when provided. |
| `url` | string | no | The build to open and test. **Must be publicly reachable** — it's opened remotely, so localhost dead-ends. Static output can be hosted here: `npx pingfusi publish <built-dir>` (or POST `https://pingfusi.com/api/draft`) returns a `https://pingfusi.com/d/<slug>` URL live for 48 hours, independent of your machine. Deploy a preview when the build needs a server, a login, or persisted state — hosted drafts are static and sandboxed (no cookies/localStorage, no form posts). |
| `draft_url` | string | no | Clone-compare: your work-in-progress clone to compare against `url` (the original/ground-truth). pingfusi compares them side by side; your `steps` become the questions answered about the match. Pairs with `pingfusi_check_source` (below). |
| `steps` | object[] | no | STRONGLY PREFERRED: structured steps with verification rules (below). 1–20 items. |
| `expected` | string | no | What should happen if it's working. |
| `verdict_options` | string[] | no | Verdict buttons (default ["Pass","Fail","Blocked"]). Use task-specific words ("Smooth","Janky"). |
| `require_evidence` | enum | no | "screenshot" (default), "recording", or "none". Saved comments or all auto-verified steps qualify; screenshot also accepts attached media and declared clone-comparison answers, while recording accepts attached video. |
| `n_target` | int | no | Independent results: default 1, broader read 5, complex/high-confidence 15–20. |
| `deadline_seconds` | int | no | Initial idle lease (default 120, max 259200). Active waits renew the default lease. Governs feed visibility for new claims; a reviewer mid-review can still finish after it lapses. |
| `idempotency_key` | string | no | Repeats return the existing task. |

**Steps with verification rules** — you wrote the code, so you know what
"done" looks like. Attach a `check` to every step you can; pingfusi observes
the page and auto-verifies them:

```json
"steps": [
  { "text": "Open the pricing page",   "check": { "type": "url",   "pattern": "/pricing" } },
  { "text": "Click 'Choose Pro'",      "check": { "type": "click", "selector": ".featured button" } },
  { "text": "Fill the email field",    "check": { "type": "fill",  "selector": "input[type=email]" } },
  { "text": "Comment on anything off", "check": { "type": "comment" } },
  { "text": "Does it feel premium?",   "check": null }
]
```

`check: null` = judgment step ticked by hand.

### pingfusi_review_results

Read a round's results. Free, unlimited, and passive: this does not renew the
task's idle lease. If pending, continue through `pingfusi_wait`, repeating
until feedback arrives or the user cancels.
Treat the returned verdict/comments as authoritative acceptance criteria.
Continue the fix → deploy → re-test loop until the latest result explicitly
approves the work.

**Output (structuredContent):** per response — `choice` (verdict),
`free_text` (notes/summary), `media_url` (short-lived signed screenshot or
recording URL your agent can open), and `steps_result`: the per-step truth
report, each entry `{text, done, via}` where `via` is `"auto"`
(machine-verified — strongest signal the work happened), `"manual"`
(attested), or `null` (not done). Plus `comments`: every pinned
comment as `{target, selector, text}` — the element's label, a CSS
selector you can locate in code, and what was reported about it.

Results are ground truth — you see what was reported, not who reported it.

### pingfusi_check_source

For **clone-compare** rounds (filed with both `url` and `draft_url`). Free,
read-only. When the verification flags elements where your clone is off, that
alignment feedback is the acceptance criteria. The original's authored source
is the best implementation aid — on a real Next.js + Tailwind site the classes
spell out the spacing and breakpoints (e.g. `max-w-[1400px]`,
`min-[1400px]:gap-8`). Measuring rendered pixels misses values that are
sitting in the markup.

`pingfusi_check_source(ping_id)` reads the **original's authored HTML source** for
exactly the elements that were pinned — using the verification's own cross-site
element correspondence — and diffs each against your clone. **Call it BEFORE
editing** so you can satisfy the requested move/match/delete from source, not
from eyeballed geometry. Use browser/source checks to implement and confirm the
verification feedback, not to overrule it.

**Output (structuredContent):** `pairs[]`, each `{ flagged,
original, clone, mismatches, status }` where `original`/`clone` carry the
element's authored `classes` + `inline_style` plus `matched_via` (how it was
located — `"selector"`, `"text-exact"`, `"text-prefix"`, `"text-contains"`,
`"text-compact"`, or `"ancestor-wrapper"`; text/compact/ancestor matches are
weaker than a selector hit) and `anchor_tag` (set on `"ancestor-wrapper"`: the
tag that matched the text before classes were read from the styled parent).
`mismatches` lists classes the clone is missing or has extra (and inline-style
property diffs), and `status` is `"resolved"` or `"needs_live_inspection"`
(couldn't locate it in static HTML — likely client-rendered; open it live and
read getComputedStyle). The result also carries a top-level `font_audit`
(`{ original, clone, diff, live_instruction? }`) comparing the fonts each page
actually loads — variable vs static, weight range, optical-sizing — which catches
"looks heavier/lighter" bugs that leave no class/inline-style trace. v1 parses
served HTML, so it covers SSR'd / Tailwind sites.

### pingfusi_quick_question

The lighter sibling: ask a subjective question answerable from its own text
("which name fits better: 'Brewly' or 'Cuppa'?"). TEXT-ONLY: the reviewer sees
nothing but the question string and choices — no URL opens, no image renders,
and a pasted link is dead text. Anything a reviewer must look at (a page,
build, design, or video) gets published (`npx pingfusi publish`) and filed as
`pingfusi_review_website` / `pingfusi_compare_clone` / `pingfusi_review_video`
instead. Each wait leg blocks up to
45s; pending legs continue automatically through `pingfusi_wait`. Agent-filed pings default to a 120s idle lease. 1 credit per response.
If the filing leg returns pending, immediately call `pingfusi_wait` and repeat
until an answer arrives or the user cancels.

| field | type | required | description |
|-------|------|----------|-------------|
| `question` | string | yes | 10–500 chars |
| `choices` | string[] | no | 2–8 multiple-choice options. Omit for free text. |
| `n_target` | int | no | Default 1, max 20. |
| `audience_tags` | string[] | no | Only responses whose profile tags include ALL of these. |
| `deadline_seconds` | int | no | How long the ping stays open (default 120, max 86400). |
| `idempotency_key` | string | no | Replay-safe retries. |

### pingfusi_quick_question_results

Passive snapshot of a `pingfusi_quick_question` (late arrivals). Same output shape.
Free, but does not renew the ping's idle lease. If pending, continue with
`pingfusi_wait` rather than returning to the user.

**Status values (all tools):**

- `complete` — n_target met (or balance ran out mid-flow; you keep what you paid for).
- `pending` — immediately call `pingfusi_wait` and repeat; this is not a final answer.
- `expired` — fully closed.
- `insufficient_credits` — balance was 0; nothing created, no charge; includes `topup_url`.
- `rate_limited` — includes `retry_after_seconds`.
- `not_found` — unknown id, or not yours.

Errors carry `isError: true` in the MCP response so agents can branch.

## Credits and pricing

- 1 credit per completed result. You only use credits for results returned.
- Most tasks use about 5 credits. Quick checks can use 1;
  complex or high-confidence reviews may use 15–20.
- 2 free answered reviews on signup. Qaping playtests have no standard free allowance.
- Monthly plan: 100 credits for $30/month through Stripe Checkout.
- Unused monthly credits expire at the billing-period boundary; no rollover.
- 60 task/poll creations per asker per hour. Reads are unlimited.

**Charging model:** at creation we only verify balance ≥ 1. Each accepted
result deducts 1 credit in the same Postgres transaction that records it.
If balance hits 0 mid-flow the task early-closes; you pay for what you got.

## Use cases

- **Post-ship QA**: "Complete the checkout on this preview — anything broken
  or confusing?" (steps with click/fill checks, screenshot required)
- **Perceptual checks**: "Scroll the landing page — smooth or janky?",
  "does this look right on a real phone?" (tested on real devices)
- **Real-world reach**: "Sign in with Google on the preview — did it actually
  log you in?", "did the test purchase email a receipt?"
- **Component feedback**: comments pinned to exact elements, returned
  with CSS selectors your agent can act on directly.
- **Copy & taste** (`pingfusi_quick_question`): "Which CTA copy reads more
  urgent: 'Start now' or 'Ship today'?" — text-only, so paste the copy into the
  question; a question about UI the reviewer would need to see is a review, not
  a quick question.

## Identity & data model

- Identity is owned by Clerk (Apple, Google, email).
- Tasks ("pings"), responses, comments, and credit transactions live in
  Postgres (Supabase) with per-asker rate limits and balances.
- Results are returned without exposing who produced them.

## Reliability

- Stateless function invocations on Vercel; no in-memory session state.
- Idempotency on task creation (per-asker key) and Stripe webhooks.
- Credit deduction and seat claims run in `SELECT ... FOR UPDATE`
  transactions — no oversells under concurrent verification.

## Key pages

- Landing: https://pingfusi.com
- Sign up: https://pingfusi.com/sign-up
- Dashboard: https://pingfusi.com/dashboard
- Answer feed: https://pingfusi.com/answer
- AI plugin manifest: https://pingfusi.com/.well-known/ai-plugin.json
- llms.txt overview: https://pingfusi.com/llms.txt

## Contact

- Website: https://pingfusi.com
- Support: https://pingfusi.com/support