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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(erc8004,solana): stop documenting a validator revocation call and an ABI that the deployed registries do not have
nirholas2c236295d7ed
diff --git a/data/changelog.json b/data/changelog.jsonindex 70f4c8b91..12dd695c4 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,26 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-08-15",+ "title": "The agent economy volume dashboard stops sending you to profiles that are not there",+ "summary": "Top earners and top spenders on the agent-to-agent volume page linked every ranked agent to a profile, including agents whose identity had been deleted. Those rows sent you to an empty profile shell for an agent that no longer exists. Both leaderboards now name a departed agent without linking it, the same rule the settled-hire feed below them already followed, and a row whose stored avatar has been pruned falls back to its initials tile instead of a broken-image icon. The page also cleared its accessibility floor: the small print under each stat, the footnote, and the retry button were all below the WCAG AA contrast minimum in dark mode, and in light mode the cyan links and the green live badge were effectively unreadable. Links inside the empty-state sentences now carry a standing underline, so they are not marked by colour alone.",+ "tags": [+ "fix",+ "improvement"+ ],+ "link": "/agent-economy-volume"+ },+ {+ "date": "2026-08-15",+ "title": "The guard and gesture tutorials stop teaching steps that fail, and one that wiped your clip list",+ "summary": "Two tutorials had drifted away from the code they document, and following either one exactly produced a bad outcome rather than a confusing one. The gesture tutorial's API example padded its request body with an empty clip array, and told readers that field was required; it has not been required for a while, and an empty array is a real value, so anyone who copied that snippet to change one gesture slot silently erased every custom clip on their agent. The endpoint's actual rule is now stated: every field is optional, present replaces it, absent leaves it alone. That page also listed four gestures on the /walk quick keys that are not on them, so pressing 1 through 8 never produced what it described; the eight keys are now named in order, with the wheel and the code call given for the four that have no key. The guard tutorial's registry entry left out the proof block, which the registry auditor has since made mandatory, so a reader who followed every step to the end hit a failure the page never mentioned. It now includes a working proof, shows the exact error you get without one, and adds a step for the command that runs it, which is the difference between a guard that is wired up and a guard anyone has shown still catches anything. Its summary line also described a completely different guard from the one it builds.",+ "tags": [+ "docs",+ "fix"+ ],+ "link": "/docs/tutorials/write-a-guard"+ },{"date": "2026-08-15","title": "Arming an Oracle agent for live trading no longer rounds your trade size up",diff --git a/docs/security.md b/docs/security.mdindex 3cbb9d5be..5b1e5c687 100644--- a/docs/security.md+++ b/docs/security.md@@ -201,9 +201,9 @@ Every registered agent card requires a `model.sha256` field. The `<three-d-agent### Validator compromise (V4)-Validator keys are dedicated signing keys, not personal wallets. If a validator key is compromised, the registry owner calls `removeValidator(address)`. Indexers treat attestations from that validator as expired from the removal block onward.+Validator keys are dedicated signing keys, not personal wallets. The deployed `ValidationRegistry` has **no validator allowlist** (`removeValidator(address)` exists only on `contracts/src/ValidationRegistry.sol`, which is deployed nowhere), so revocation is not an on-chain call: any address can answer a request addressed to it. Containment for a compromised validator key is therefore to rotate it (`scripts/erc8004/provision-validator-key.mjs` reprovisions `VALIDATOR_PRIVATE_KEY` on the API service) and to have indexers and resolvers filter by validator address, treating attestations signed by the retired key as expired from the rotation block onward.-The registry owner is currently the deployer EOA. Migration to a 3-of-5 Safe on Base is planned before public registration opens — allow-list changes will require multisig approval.+That places the whole burden on key custody: see the platform-validator note in [contracts/DEPLOYMENTS.md](../contracts/DEPLOYMENTS.md) and [docs/erc8004/validation-attestation.md](./erc8004/validation-attestation.md) for the operating rules.### Reputation gaming (V5)diff --git a/docs/solana.md b/docs/solana.mdindex ab8706044..71af0bc43 100644--- a/docs/solana.md+++ b/docs/solana.md@@ -68,7 +68,7 @@ Failing over is only half the contract. The other half is *how long* a lane stay| Plain rate limit (429, no quota wording) | 10 min | Transient burst throttling; the lane recovers on its own. || Bad or expired key (401, 403) | 30 min | An endpoint-wide credential problem. || Dead or misrouted URL (404, 410) | 30 min | Persistent misconfiguration, not a blip. |-| One refused *call shape* (403 + `Request blocked`) | 30 s | The lane is healthy; only this request is unwelcome. |+| One refused *call shape* (403 + `Request blocked`) | none for the lane | The lane is healthy; only this request is unwelcome, so the *method* is demoted on that endpoint (`markMethodDemotion`) and every other call shape keeps flowing. A caller that reaches `markEndpointCooldown` directly still gets the cheapest window, 30 s. || Provider 5xx | 2 min | Server-side wobble. || Fetch threw (DNS, connection) | 30 s | Network blip. |@@ -81,7 +81,7 @@ The second-to-last row is the subtle one, and it cost us a primary. Each provide"message": "Request blocked. Details: blocked parameter: params.1.programId" } }```-Read as a credential failure that benched the node for 30 minutes, and since token and USDC balance readers make that exact call constantly, a healthy primary evicted itself on its own routine traffic and the rotation cascaded onto whatever came next. So a 403 whose body names a blocked call shape now fails over for that one request and leaves the lane in service. A 403 that does *not* say so is still treated as a bad key and benched for the full 30 minutes. Both directions are covered by `tests/solana-rpc-priority-and-breaker.test.js`.+Read as a credential failure that benched the node for 30 minutes, and since token and USDC balance readers make that exact call constantly, a healthy primary evicted itself on its own routine traffic and the rotation cascaded onto whatever came next. So a 403 whose body names a blocked call shape now fails over for that one request and demotes only that method on that endpoint, leaving the lane serving everything else with no cooldown at all. A 403 that does *not* say so is still treated as a bad key and benched for the full 30 minutes. Both directions are covered by `tests/solana-rpc-priority-and-breaker.test.js`.The same distinction applies one layer up, to HTTP 200 responses carrying a JSON-RPC error. A provider refusing a call shape (PublicNode's `excluded from account secondary indexes`, Tatum's `available for paid plans only`) must rotate to the next lane, while a genuinely deterministic error (`invalid params`) must *not*, because every lane would fail it identically and rotating just multiplies one failure by the length of the chain.diff --git a/prompts/swarm-100/docs-batch-32.md b/prompts/swarm-100/docs-batch-32.mddeleted file mode 100644index c0df85417..000000000--- a/prompts/swarm-100/docs-batch-32.md+++ /dev/null@@ -1,100 +0,0 @@-# Docs audit batch 32: /docs/security through /docs/token-gated-3d-embeds--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 neighboring files in-prompts/swarm-100/ 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. Confirm each path below still exists in data/pages.json; a path that was- removed there is out of scope (note it in the report, skip it).-2. Start (or reuse) the local dev server: npm run dev (vite, port 3000).-3. Probe production for each path:-- for p in /docs/security /docs/seed-quality /docs/shared-utilities /docs/sign-language /docs/smart-contracts /docs/solana /docs/spatial-mcp /docs/token-gated-3d-embeds; do printf '%s ' "$p"; curl -so /dev/null -w '%{http_code}\n' "https://three.ws$p"; done--## Task: audit this batch of docs pages, then fix everything found--Pages in this batch:--- /docs/security ("Docs · Security")-- /docs/seed-quality ("Docs · The catalog quality gate")-- /docs/shared-utilities ("Docs · Shared utilities")-- /docs/sign-language ("Docs · Sign language, avatars that sign")-- /docs/smart-contracts ("Docs · ERC-8004 smart contracts")-- /docs/solana ("Docs · Solana agents")-- /docs/spatial-mcp ("Docs · Spatial MCP")-- /docs/token-gated-3d-embeds ("Docs · Token-gated 3D embeds")--For every page, in a real headless browser against localhost:--1. HTTP 200, zero console errors, zero unhandled failed requests.-2. Every link on the page resolves (internal paths exist in the route table;- anchors have targets). Fix or remove dead ones.-3. Content accuracy: the page documents current behavior. Spot-check its claims against the code it describes; where it names a command, run the command; where it shows a code sample, the sample must actually run. Fix stale claims in the same change.-4. Title tag and meta description present and specific.-5. Fix defects at their root and re-run until clean.--## Definition of done--- [ ] Every page in the batch loads locally with HTTP 200 and zero console- errors.-- [ ] Zero dead links across the batch.-- [ ] Every named command and code sample on these pages verified runnable, or corrected.-- [ ] Title and meta description verified on every page.-- [ ] npm run check:rules -- --paths <touched files> exits 0; npm test passes- if you touched code.-- [ ] Production status per page recorded in the report.--## 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/swarm-100/docs-batch-32.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.diff --git a/public/changelog.json b/public/changelog.jsonindex 8a6b74d76..a4b7ca3b6 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T06:42:28.569Z",+ "generated_at": "2026-08-15T06:45:57.352Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -16,6 +16,17 @@"fix"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "A shared link to a docs page now opens that page instead of stranding you",+ "summary": "Every cross-reference inside a docs page turns into a link like /docs/agent-wallets#financial-controls. Following one worked, but the URL you copied afterwards did not: on a fresh load the viewer only recognised the second half if that doc happened to be listed in the sidebar, and silently left you on the page you arrived from otherwise. Links to Financial controls, the x402 payment tutorial, and the wallet access and proof-of-custody chapters all failed that way. The viewer now asks the server whether the doc exists before giving up, so those links land where they say they will, and the browser tab takes the destination's name. Separately, /docs/3d-api was serving the 3D API landing page rather than the reference doc that the API's own discovery response, the OpenAPI license link, and the docs sidebar all point at; it now serves the reference doc, and the landing page keeps its home at /3d.",+ "link": "/docs/agent-wallets",+ "tags": [+ "fix",+ "docs"+ ]+ },{"date": "2026-08-15","type": "update",@@ -71,6 +82,17 @@"security"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "Seeding an agent from GitHub is locked to your own click, and a mistyped pick no longer costs you six hours",+ "summary": "Three fixes to the GitHub memory lane, the one that reads the profile, repositories, and READMEs you tick and distills them into what your agent knows about your work. First: writing or deleting those memories now requires the one-time token the site attaches to your own actions, so another site cannot make your browser re-seed or wipe an agent behind your back. Every neighbouring memory action already worked this way; this one did not. Second: seeding is allowed once every six hours per agent, and that window used to be spent by attempts that never read anything, so ticking nothing and pressing Seed, or picking a repository that had been renamed since the list loaded, locked you out for six hours over a correctable mistake. The window is now taken only once your selection checks out, immediately before anything is actually read. Third: when every model provider is busy at once, the seed used to fail with a bare internal error and a support reference; it now says plainly that nothing was read, that your existing memories are untouched, and roughly how long until you can try again.",+ "link": "/docs/github-memory-seeding",+ "tags": [+ "security",+ "fix"+ ]+ },{"date": "2026-08-15","type": "update",@@ -82,6 +104,28 @@"fix"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "The 3D API and agent manifest references now match what the endpoints actually return",+ "summary": "The agent manifest page told you to validate a manifest with assertValid from @three-ws/avatar-schema. That package validates avatar manifests (mesh, skeleton, owner), not agent manifests, so the sample always threw. It now shows loadManifest from the published bundle, running against a live agent, and says plainly which document the avatar schema covers. On the 3D API page, the sample responses showed a model URL shape the service never returns, the inspect example was a stale capture of a model that has since been re-exported, and the Forge Pro tier table claimed draft and standard generations come back with no textures when every tier bakes them (1K, 2K, and 4K plus PBR at high). All three are corrected against live calls, and the page now explains why browser code should load a generated GLB through the first-party CDN path rather than the object store URL directly.",+ "link": "/docs/3d-api",+ "tags": [+ "fix",+ "docs"+ ]+ },+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "The 3D pipeline docs stop telling you to run a command that does not exist",+ "summary": "Every paid stage on the 3D asset pipeline page (rig, remesh, game-ready, stylize, background removal) showed you how to pay for it by running `npx @x402/fetch`. There is no such command: that package publishes a library, not a CLI, so anyone who copied a sample got `could not determine executable to run` and no asset. The samples are now the real thing: an unpaid curl that returns the live 402 challenge and costs nothing, plus one Node snippet that wraps fetch with our published @three-ws/x402-fetch buyer and actually settles. The end-to-end generate-rig-gameready walkthrough was rewritten the same way and now polls the forge job with the fields the API really returns. The page also stops promising a specific settlement network, because the 402 challenge names the networks itself. Alongside it: the changelog page's CDN pinning table listed four alias URLs that all 404, and pointed at an integrity file for a version that no longer publishes one; the AgenC page's opening sentence linked the word AgenC to a different protocol's page; and the vanity protocol spec showed a stale copy of the service key document, which now matches what the live endpoint serves.",+ "link": "/docs/3d-pipeline",+ "tags": [+ "docs",+ "fix"+ ]+ },{"date": "2026-08-15","type": "update",@@ -93,6 +137,17 @@"improvement"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "The Agent Exchange stops offering a purchase its wallet cannot pay for",+ "summary": "On /agent-exchange two 3D agents buy and sell live crypto intel, and the buyer settles $0.01 of real USDC on Solana for every signal. The page already warned you when the buyer's wallet was too empty to settle, but it left the Buy intel button live anyway, so the only thing a click could produce was a failed payment. The button now turns itself off and says why, and the warning carries a Check again button, so a wallet you fund while the page is open recovers without a reload. The balance is also re-read after every purchase, so a settlement that empties the wallet is reflected immediately instead of one click too late. When the balance check itself does not answer, the page used to say nothing at all and quietly log a browser error; it now tells you the balance is unknown and offers the same retry. Two smaller fixes came with it: the page title and the buy button were being rewritten at load time from the translation catalog, which had drifted from the page and still carried the old punctuation, now corrected in all 85 languages; and the two avatar frames were keyboard stops that did nothing and showed no focus outline, so they are out of the tab order and the topic chips and buy button are two tabs closer for anyone navigating by keyboard.",+ "link": "/agent-exchange",+ "tags": [+ "fix",+ "improvement"+ ]+ },{"date": "2026-08-15","type": "update",@@ -116,6 +171,17 @@"docs"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "The embed tutorials now name the attribute that actually hides the built-in chat",+ "summary": "Several tutorials told you to set avatar-chat=\"off\" to hide an agent's built-in chat input. It does not do that: it moves the avatar out of the chat column and lays the chat out as a plain bottom bar, leaving the input on screen. The multi-agent walkthrough leaned on it to keep its behind-the-scenes stage-director messages hidden, so anyone following it verbatim saw those messages leak into the visible chat. Every affected tutorial now uses chat=\"off\", the real bare-avatar switch, and notes that the brain still boots behind it so say(), ask(), and the event stream keep working. The same accuracy pass corrected the walking-avatar leaderboard example, which read fields the API never returns and so always rendered an empty top-walkers list, and the JavaScript API event table, which named the wrong key for the skill a tool-call event reports.",+ "link": "/tutorials/web-component-end-to-end",+ "tags": [+ "fix",+ "docs"+ ]+ },{"date": "2026-08-15","type": "update",@@ -184,6 +250,18 @@"sdk"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "The vanity SDK now uses the payment wallet you hand it, and the in-chat 3D avatar keeps its tuned lighting",+ "summary": "Three fixes in the developer packages. The @three-ws/vanity SDK documented a fetch option on its paid address-grinding lane but silently ignored it, so a developer who passed a payment-enabled fetch got a payment-required error back instead of the keypair they paid for; that option now works, as do a custom API host and key. The avatar MCP server's in-chat 3D viewer had been hand-tuned with softer shadows, brighter exposure and a neutral environment light, but the script that rebuilds it before every release still produced the old flat version, so the next release would have quietly undone the tuning; the script now produces the tuned viewer, and the same settings apply to the fallback view for chat apps that cannot run the interactive one. The tool SDK's quick-start example pointed at an API that does not exist and skipped the wrapper an MCP server needs to return anything at all, so following it produced a tool that answered with nothing; it now runs end to end against a real free three.ws endpoint.",+ "link": null,+ "tags": [+ "fix",+ "sdk",+ "docs"+ ]+ },{"date": "2026-08-14","type": "launch",diff --git a/public/features.json b/public/features.jsonindex d21ca2d58..c3f38926e 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T06:42:30.798Z",+ "generated_at": "2026-08-15T06:45:57.213Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",