Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(prompts): add the docs-accuracy and launches-route briefs to the finish queue

nirholas4f0a66a2b18a
diff --git a/prompts/finish/014-openai-pr-06-docs-accuracy-reconciliation.md b/prompts/finish/014-openai-pr-06-docs-accuracy-reconciliation.md
new file mode 100644
index 000000000..d7c5692f2
--- /dev/null
+++ b/prompts/finish/014-openai-pr-06-docs-accuracy-reconciliation.md
@@ -0,0 +1,94 @@
+# Task 06: Fix doc accuracy and reconcile the tool-count story (P1)
+
+Read [`openai-pr-00-START-HERE.md`](_context/openai-pr-00-START-HERE.md) first. This task cleans up the
+documentation drift the audit found, EXCEPT the two docs owned by other tasks
+(`apps-sdk/README.md` was Task 01, already landed on 2026-07-18; the `forge_free` tier
+claim is Task 03). Do not fight those tasks for those specific edits; coordinate.
+
+## The problems (verified)
+
+1. **Tool-count inconsistency.** The free MCP connector exposes **9** tools: 6
+ generation (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`,
+ `forge_avatar`, `refine_model`) + 3 persona (`create_agent_persona`,
+ `get_agent_persona`, `persona_say`). But docs tell different stories:
+ - `openai-submission.md` says "Nine tools."
+ - `docs/mcp-studio.md` headline tool table lists six, with the persona tools in a
+ later "Embodiment" section.
+ - Code comments drift: `tools.js:1-8` says "Six generation tools (five generators +
+ refine_model)"; `tests/mcp-studio.test.js` comment says "five allowed generation
+ tools" while the asserted array has six.
+ Reconcile these so every count is consistent and correct. The authoritative number
+ is whatever the running server returns from `tools/list`; verify it, then make all
+ docs and comments match.
+
+2. **model-viewer version is not single-sourced.** Three surfaces load different
+ `model-viewer` versions: `api/ar.js` launch page (3.5.0 via jsdelivr), the MCP
+ widget in `component.js` (3.5.0), and `/viewer.html` (4.0.0). Pick one version,
+ pin it in one place they all reference (a constant/shared import), or at minimum
+ document the intended version per surface and why they differ. A reviewer opening
+ two of our surfaces should not get two different renderer versions with no reason.
+
+3. **`docs/mcp-studio.md` cross-reference check.** It points the custom-GPT contract to
+ `./api-reference.md`. Verify that file exists and actually documents `/api/3d/studio`.
+ If not, fix the pointer to the authoritative schema (the served OpenAPI from Task 05)
+ or add the missing section. No dead doc links.
+
+4. **General accuracy sweep of the ChatGPT-surface docs.** Read
+ `docs/mcp-studio.md`, `docs/chatgpt-ar.md`, `docs/mcp-3d-studio.md`, and
+ `docs/ar.md` end to end against the code. Every `ui://` URI, file path, endpoint,
+ env var, and example must resolve and be correct. Fix any that are stale. The audit
+ already confirmed `docs/chatgpt-ar.md` correctly points at `component.js` (good) and
+ that `apps-sdk/README.md` was the worst offender; Task 01 rewrote it on 2026-07-18,
+ so treat it as correct unless a link in it stops resolving.
+
+## Constraints
+
+- Every rule in `openai-pr-00-START-HERE.md`. Docs are real implementations: every code sample
+ must run, every link must resolve to a live path (`CLAUDE.md` documentation rules).
+- Not a crypto surface; commit gate does not apply. Do not introduce any non-$THREE
+ coin reference into the docs.
+- Coordinate: `apps-sdk/README.md` was rewritten by Task 01 (landed) and is accurate;
+ leave the `forge_free` tier language to Task 03. If Task 03 has not landed yet, note
+ the dependency rather than duplicating its edits.
+
+## Verification
+
+- Start from the live `tools/list` output (call `/api/mcp-studio` with an
+ `initialize` + `tools/list` JSON-RPC batch) and confirm the count and names, then
+ grep every doc/comment for tool counts and confirm they match.
+- `grep -rn "model-viewer@" api public docs` shows a single intended version story.
+- Every internal doc link resolves (spot-check with a link checker or by opening each
+ referenced path).
+- `npm test` green (docs changes should not break tests, but run it).
+
+## Definition of done
+
+- [ ] Tool count is consistent and correct (9) across `openai-submission.md`,
+ `docs/mcp-studio.md`, code comments, and test comments.
+- [ ] model-viewer version is single-sourced or its per-surface difference is
+ documented and justified.
+- [ ] `docs/mcp-studio.md` cross-references resolve; no dead links in any
+ ChatGPT-surface doc.
+- [ ] All ChatGPT-surface docs are accurate against the code (paths, URIs, endpoints,
+ env vars, examples).
+- [ ] `data/changelog.json` entry with the `docs` tag.
+- [ ] `npm test` green.
+
+## Retire this prompt when it is done (required)
+
+1. Verify every Definition of done line against actual command output in front
+ of you. Never claim a line you did not verify.
+2. Record the outcome in this campaign's PROGRESS or INDEX file if it has one.
+3. Commit with explicit paths and a subject that describes the diff (house
+ style: type(scope): what changed and why a reader cares), and delete this
+ prompt file in that same commit:
+
+ git rm prompts/finish/014-openai-pr-06-docs-accuracy-reconciliation.md
+
+ A finished order left on disk reads as open work to the next agent, so the
+ shrinking directory is the campaign's progress ledger.
+
+If a line genuinely cannot pass inside this session (an external party must
+respond, or an owner-gated action is the final step), finish everything else,
+leave this file in place, and state exactly which line remains and who owns it.
+Never delete this file on a partial.
diff --git a/prompts/finish/107-swarm-100-route-launches.md b/prompts/finish/107-swarm-100-route-launches.md
new file mode 100644
index 000000000..42c9042c9
--- /dev/null
+++ b/prompts/finish/107-swarm-100-route-launches.md
@@ -0,0 +1,119 @@
+# Route audit: /launches (Agent Launches)
+
+How to run: paste this file's repo path into a fresh Claude Code chat in this
+repository and say "run this work order". This file is fully self-contained:
+it depends on no other prompt file anywhere. If sibling swarm-100 files in
+prompts/finish/ are gone, that work is done; if present, ignore them.
+Every claim below rots; step 0 re-measures, and what you measure wins.
+
+## Operating clause (binding)
+
+- Read CLAUDE.md first. Its rules override everything, including this file.
+- Finish 100% in this session. Never end the turn with a question, an option
+ list, or an unexecuted plan. A judgment call goes in one line of the final
+ report; it never becomes a question that halts work.
+- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
+ funds or any irreversible on-chain write, git push or a production deploy,
+ committing content that references a crypto project other than $THREE, and
+ destroying unrecoverable data.
+- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
+ commented-out code. Real APIs and real integrations only.
+- The em-dash and en-dash characters are banned in everything you write.
+- Concurrent agents share this worktree: stage explicit paths only (never a
+ bare add-everything), and commit finished work promptly.
+- Before committing, run: npm run check:rules -- --paths <files you touched>.
+ It must exit 0.
+
+## Step 0: re-derive the current state
+
+1. This route's declared entry (path, description, added date):
+
+ node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/launches')console.log(JSON.stringify(g,null,2))"
+
+2. Find the serving implementation: grep "/launches" in vercel.json (the live
+ route table server/index.mjs boots from), then list matching files in
+ pages/ and src/. STRUCTURE.md maps every surface to its directory if the
+ grep is ambiguous.
+3. Production right now:
+
+ curl -so /dev/null -w '%{http_code}\n' https://three.ws/launches
+
+4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).
+
+## Task: audit this one route end to end, then fix everything found
+
+Route: /launches ("Agent Launches", section "crypto").
+Declared purpose: Live public feed of every coin launched by a three.ws agent: market caps, graduation status, and the agent behind each launch.
+
+Drive the page in a real headless browser. Playwright is already a dev
+dependency; keep your probe script in the session scratchpad, never in the
+repo.
+
+1. Load http://localhost:3000/launches. Record the HTTP status, every console
+ error and warning, and every failed network request.
+2. Exercise it like a first-time user: click the primary actions, run the
+ primary flow if one exists, follow the page's internal links. Every button
+ must do something real; every link must resolve. If the page renders data,
+ prove in the network log that it came from a live endpoint, not a baked-in
+ fallback array.
+3. States: verify populated, empty, loading, and error states are designed and
+ reachable. Block the page's primary fetch in Playwright and confirm an
+ actionable error state appears, not a blank void or a raw exception.
+4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no
+ overlapping or clipped controls.
+5. Accessibility basics: one h1; interactive elements are real buttons or
+ links with visible focus states; images carry alt text; form fields have
+ labels.
+6. Head: a specific title tag and meta description that match the declared
+ purpose above.
+7. Fix every defect at its root in the page's real source files and re-run the
+ probe until clean. Defects in shared modules are in scope when this route
+ exercises them.
+
+## Definition of done
+
+- [ ] Local load of /launches: HTTP 200, zero console errors, zero unhandled
+ failed requests (a third-party outage must land in a designed fallback,
+ not a broken page).
+- [ ] No dead interactive element on the page: no stub href="#", no button
+ without a handler, no link to a missing path.
+- [ ] Empty, loading, error, and populated states verified.
+- [ ] 320 / 768 / 1440 px renders verified clean.
+- [ ] Title and meta description present and specific.
+- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.
+- [ ] Production status from step 0 recorded in the report; if production
+ needs a deploy to pick up a fix, the report says so (deploys stay
+ owner-gated).
+
+## Never blocked
+
+| Blocker | Resolution (act, do not ask) |
+|---|---|
+| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
+| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
+| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
+| Playwright browser missing | npx playwright install chromium |
+| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
+| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
+| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
+
+## Close out (required)
+
+1. Verify every Definition of done line with the actual command output in
+ front of you. Never claim a line you did not verify.
+2. Commit with explicit paths and a subject that describes the diff (house
+ style: type(scope): what changed and why a reader cares).
+3. Delete this prompt file in that same commit:
+
+ git rm prompts/finish/107-swarm-100-route-launches.md
+
+ The shrinking directory is this campaign's only progress ledger; there is
+ no progress log to update.
+4. Final report: what step 0 measured, what changed (file list), evidence per
+ Definition of done line, and any one-line judgment calls. No trailing
+ questions, no unexecuted plans.
+
+If a line genuinely cannot pass inside this session (an external party must
+respond, or an owner-gated action is the final step), finish everything else,
+leave this file in place, and state exactly which line remains and who owns
+it. Never delete this file on a partial.