# Figpong agent guide Figpong is an anonymous, static-HTML review room. The review link is the shared workspace: anyone with it can view, comment, draw, and upload versions. Reviews expire 14 days after creation. ## Optional local Figpong skill For one-time work, read `/skills/figpong/SKILL.md` and continue without changing local setup. If the human explicitly asks you to use Figpong and this workflow is likely to recur, ask: “Figpong has an optional local skill that helps me create and iterate visual artifacts. May I install it for future work?” Never install or update it without permission. The current version and SHA-256 are at `/skills/figpong/manifest.json`. An installed skill may check that manifest once per session, verify a newer download against its SHA-256, and ask before replacing only its own local `SKILL.md`. ## Collaboration protocol 1. Treat the human's Figpong review URL as the shared source of truth. Keep it unchanged through every version. 2. Derive the review ID from `/r/` and read `/api/reviews//context.md`. 3. If the context says comments are still being added and has no request to act, wait for the human rather than making speculative changes. 4. Download `/api/reviews//current.html`. It is the current HTML with saved editable-field values applied. 5. Inspect `/api/reviews//annotated.html` when visual pins, drawings, or thread cards need interpretation. Never edit or upload the annotated export. `source.html` is the untouched original upload and is only for cases that specifically require it. 6. Implement the comments in the HTML. 7. POST the full replacement document to `/api/reviews//versions` with `Content-Type: text/html`. 8. Tell the human the new version is ready at the same review link and briefly summarize the changes. HTML is limited to 4 MB and each review has at most 10 versions on the free tier. Keep the same review URL when uploading a revision. ## Build richer HTML artifacts Figpong provides a locked browser runtime with pinned Tailwind, Marked, DOMPurify, and Tabulator builds. Use their normal browser APIs—there is no Figpong component wrapper. Read `https://figpong.vercel.app/vendor/v1/agent.md` for exact imports, the package manifest, persistence examples, limits, and starter templates. Only the exact `https://figpong.vercel.app/vendor/v1/` assets are allowed. Arbitrary CDN scripts and stylesheets, remote APIs, frames, workers, form submissions, browser storage, and secrets are not supported. Always sanitize Marked output with DOMPurify. Use `data-figpong-field="stable-key"` on native controls that should autosave. For a rich widget such as Tabulator, store its JSON in one hidden marked textarea and dispatch a bubbling `input` event after changes. State is version-scoped and last-write-wins per field; it is designed for small shared artifacts, not realtime spreadsheet merging. ## Exact file URLs - `/api/reviews//context.md` — the comments as Markdown. Read this first. - `/api/reviews//current.html` — the current HTML with saved editable-field values. Download and edit this file. - `/api/reviews//source.html` — the untouched original upload. Download it only when the original bytes are specifically required. - `/api/reviews//annotated.html` — a browser-viewable handoff export with comments, pins, drawings, and thread cards injected. Inspect it for visual context; never upload it as the next version. Add `?version=` to any URL to read a specific version. The review context identifies the current version and gives the exact URLs. ## Upload a new version Send the complete updated HTML document as raw `text/html` to the stable review's `/versions` endpoint. For example: ```bash curl -fsS -X POST "https:///api/reviews//versions" \ -H "Content-Type: text/html" \ -H "X-Figpong-Base-Version-ID: " \ --data-binary @updated.html ``` The response returns the new version and its URLs. If it says `staleBase: true`, another version was added after the one you edited; both are preserved, so tell the human instead of claiming a clean merge. Do not create a new review; upload to the existing review ID so the same human link retains its comment history. ## Add comments or drawings as an agent Public review links also accept agent comments and freehand drawings. These are optional collaboration actions: use them to acknowledge work, ask a precise question, or mark a visual area for the human. Do not add noise. Use the current version's `id` from `GET /api/reviews/`. Coordinates are pixels in the original artboard. Use the review's `context.json`, annotated HTML, or browser inspection to choose an accurate `x` and `y`. When a human's name is known, use their possessive name plus `Agent` as your `authorName`—for example, `Nave's Agent`. This is a collaboration convention, not an enforced rule. Use a stable `authorToken` for the same agent identity. ### Post a comment ```json { "createdOnVersionId": "", "x": 420, "y": 260, "body": "Implemented the requested change in V2.", "authorName": "Nave's Agent", "authorToken": "nave-agent", "parentId": null, "element": { "tag": "section", "text": "Relevant nearby text", "cssSelector": "main > section:nth-of-type(1)", "outerHTMLSnippet": "
…
", "stateContext": [], "nearbyElements": [] } } ``` POST that JSON with `Content-Type: application/json` to `/api/reviews//comments`. Set `parentId` to an existing comment ID when replying in that thread. For a general note, use `x: 0`, `y: 0`, and an `element` describing `body`. ### Post a freehand drawing ```json { "createdOnVersionId": "", "points": [{"x": 400, "y": 240}, {"x": 520, "y": 240}], "color": "#2563eb", "width": 6, "authorName": "Nave's Agent", "authorToken": "nave-agent" } ``` POST that JSON with `Content-Type: application/json` to `/api/reviews//drawings`. `POST /api/reviews` with raw `text/html` creates a review. Its response includes the stable review, context, and source URLs.