# Scope & Settle: judging walkthrough

Use [judge entry](https://scope-and-settle.hperkins.com/judge), the private judging code, and the dedicated **personal sandbox buyer** supplied in the private testing instructions. No provider keys or local backend are needed for this hosted path. All content and payments are synthetic.

1. **Start your demo.** Enter the judging code and choose **Start a new demo**. Expect private designer access for a fresh run. Save it privately; it grants a role, not a verified identity. **Resume my demo on this browser** resumes only the run stored in that browser. Each click on Start deliberately creates a different run.
2. **Install the plugin.** Download the ZIP from judge entry and extract it. In **Figma desktop → Plugins → Development → Import plugin from manifest**, select the extracted `manifest.json`. Keep `code.js` and `ui.html` beside it. The ZIP's `SOURCE.json` records the source commit and file checksums; `/downloads/SHA256SUMS` provides the ZIP checksum.
3. **Open the designated file.** Follow the Figma link on judge entry and sign in to your own Figma account. The synthetic file permits editing by anyone with its link; no team invitation or paid seat is needed. Open this same file in Figma desktop. If Desktop has multiple accounts, check the editor avatar: changing the Home account may leave an existing file tab signed in as another account. An arbitrary duplicate has a different file key and cannot supply this hosted demo's comments. Select the **Desktop checkout — synthetic demo** frame. Run **Scope & Settle** from Development.
4. **Set the agent's boundaries.** Copy designer access from judge entry, paste it into the plugin, and click **Connect**. In **Rates, limits and client access**, select the **$250 mobile-layout** rate, a **$250** per-quote maximum, **$500** cumulative allowance and quantity **1**. Leave optional Figma authors/replies and invoice reminders off for this first portal test. Check the explicit authorization box and choose **Approve & enable agent**. Copy the generated private portal link. The examples are not authorized until you approve them.
5. **Request and approve as the client.** Open the private client portal in a separate tab. Send **“Can you add the mobile checkout?”**. You can close the plugin: the hosted worker continues. Expect a live AI assessment and an automatic **$250** quote, or an honest clarification/exception if the model cannot establish full coverage. No recorded answer is substituted. Inspect the exact deliverables, revision and total; check client consent and choose **Approve revision 1 & prepare PayPal invoice**. No designer quote-confirmation click is required inside the approved policy. Client approval does not mean payment.
6. **Pay in sandbox.** Open the PayPal sandbox invoice and sign in with the dedicated personal buyer supplied privately. Complete the **$250 sandbox payment**. Do not use a real PayPal account or card. Return to the client portal and choose **Refresh payment**; expect **Paid**, based on PayPal invoice retrieval. Reopen the plugin, then refresh **Change orders** or choose **Check payment**; expect **Paid** and **$0.00 due** on the same revision. The agent also checks pending invoices and records signed webhook reconciliation through the existing payment path.
7. **Start again.** Under designer **Demo controls**, choose **Reset my demo** and confirm. Expect a clean run with replacement access. This revokes the old run's designer and client access and clears its local evidence/orders. PayPal keeps sandbox invoices. Other judges' runs and the shared AI spending ledger remain intact.

## Optional assessment and exception checks

- **Native frame context:** expand **Assess a request or review terms yourself**, select the actual Figma comment, attach the selected frame and assess against the brief. This remains a designer-reviewed path. Automatic background assessment uses request text and the brief; it does not silently export a fresh frame while Figma is closed.
- **Limits:** in a fresh run, set the per-quote maximum to $200 while allowing the $250 rate. A supported mobile-layout request becomes an exception rather than a $250 automatic quote. Review the exception, confirm manual terms, and verify that the client receives the reviewed revision in the same portal. Do not complete another payment just to demonstrate the limit.
- **Clarification:** request a deliverable that the rate card does not cover. The agent asks at most two clarification rounds before escalating. No invented rate or charge is permitted.
- **Figma intake:** choose the actual client's stable author ID in settings, approve the policy, then have that author post a new root comment. Only threads created after enabling are monitored. Selecting a display name alone does not authorize authorship. If another judge already owns that author route, use the independent portal path. Thread replies require comment-write permission and a separate opt-in; the public thread never receives the private portal link.
- **Pause/reopen:** pause the policy and submit no further requests. Existing quotes still require client consent; pausing or closing Figma is not payment or cancellation. Reopening restores the same server state. The agent stops at its displayed access expiry or parent revocation.

## Recovery

- **Expired session:** ordinary sessions last at most 60 minutes. Browser and plugin renew automatically using their separately scoped resume credential. Access normally ends December 16, 2026 at 16:00 UTC. Revocation, editing a client proposal, and reset invalidate the affected access immediately. Entry can create a fresh run while the judging code remains valid.
- **Reopen client review:** use **Client review link** on the designer's current order. It reopens that revision even after approval/payment and does not create another invoice. Editing requires a fresh client review and explicit approval.
- **Lost browser state:** use privately saved designer access in Connect, or use the judging code to start a new run. Private access is stored in browser local/session storage and Figma `clientStorage`; use an isolated browser profile and your own Figma account. Closing the plugin retains its access. The client portal has **Close private access on this browser**. A replacement portal link revokes the previous link.
- **Agent exception:** review the reason in **Only exceptions need you**. Review terms manually, retry within policy where offered, or handle it directly. Uncertain Figma/PayPal reminder delivery is not blindly retried; inspect the existing thread/invoice first. Routine portal delivery does not send email notifications.
- **Plugin already shows a workspace:** it restored its saved run. Continue that run, or use **Demo controls → Reset my demo** when you intentionally want to clear it and begin again. Starting a new run at judge entry in a browser does not switch an already-connected plugin. Reset revokes the old run's access and removes its local records, so do not reset a run whose evidence you want to retain.
- **Interrupted invoice:** approval remains saved. The designer can choose **Prepare PayPal invoice** again. The backend reconciles and resumes the same invoice rather than generating another one.
- **Delayed webhook:** **Check payment** / **Refresh payment status** directly retrieves PayPal truth. Manual refresh is separate from signed webhook evidence; the verification notes record whether a real callback was received.
- **Wrong Figma file:** open the designated file and rerun the plugin. Frame attachment is disabled for another file. Comments and the brief always come from the configured file.
- **An older development build opens:** in Plugins & widgets, find the old Scope & Settle entry by its local manifest path and choose its menu → Remove. This removes the development registration, not its source files. Keep only the entry pointing to the freshly extracted ZIP, then rerun it. Registrations with the same plugin ID can otherwise launch the older build.
- **Figma access unavailable:** use **Open browser workspace** to exercise comments, assessment, terms, approval and payment. Native frame selection/export still requires Figma desktop and edit access.
- **AI allowance exhausted:** the app stops live requests and shows the error. Reset and new runs do not reset the allowance. **Prepare a manual proposal** is an explicitly labeled payment-testing path; it is not live AI evidence.

The prebuilt plugin calls only the displayed hosted origin. No provider keys, judging code or sandbox buyer password are included in the ZIP. Keep private credentials and role links out of public source and recordings.

For local setup use the repository README with Node 24, `pnpm install --frozen-lockfile`, your own explicit sandbox/provider configuration, then `pnpm build` and `pnpm start` in `app`. Build the plugin with the matching `PUBLIC_BASE_URL`. Restore the synthetic file using `docs/FIGMA-JUDGING-FILE.md`; a restored file requires configuring its actual file key before provisioning new judging access.