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(packages): correct the avatar-cli and vision-mcp examples and log the fixes for holders
nirholas166b73fd27b6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 276352b72..a41877fcc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Docs pages stop opening with a wall of raw metadata, and the AWS pages say where the Marketplace listing actually stands**: Nine documentation pages are written as article drafts, so each one starts with a small block of publishing metadata: the title, where it is meant to run, its tags. That block is meant for the tooling, not for you, but the docs reader had no idea what it was and rendered it as an enormous heading at the very top of the article, above the actual writing. It is now recognised and hidden, on the page and in the Copy page text, so those articles begin where they should. Reading the same pages closely turned up claims that had drifted: several said three.ws was already live on AWS Marketplace and billing usage to your AWS invoice. The integration is built and deployed, but the listing itself has not been published yet and the pricing decision is a free subscription with no AWS metering, so the AWS pages now say exactly that and point at the page that tracks the status. The MCP article's vanity-address tool was also listed at a metered price of up to fifty cents; it is a flat five cents per grind, which is what the code has always charged. (`/docs/aws-marketplace`) `[docs, fix]`- **Eight build tutorials now match what the platform actually does**: An audit of eight tutorials found instructions that could not work. The AI-brain tutorial described a model line-up that had been superseded: it never mentioned the Claude 5 family (Sonnet 5, Opus 5, Fable 5), which are live and selectable, and it recommended Sonnet 4.6 as the default. It also sent you to screens that do not exist, telling you to add API keys under a gear icon in My Agents and to change models, sampling knobs, and streaming under a Brain menu. Provider keys actually live in the AI Provider Keys panel on your account page, the model is a field on the agent's embed policy, and streaming has no off-switch. The promised usage tab with token charts and threshold emails did not exist either; the tutorial now documents the real per-agent usage read and points at the monthly quota and per-minute rate limit, which are the controls actually enforced before your money is spent. It also now explains that a visitor can never escalate your agent onto a paid model. The custom-GLB tutorial was worse for anyone following along: it linked a Studio address that no longer resolves, and four of its commands invoked gltf-transform subcommands that have never existed, so converting an FBX, renaming animation clips, and the full Mixamo walkthrough all failed at the first step. Those are replaced with the converter the platform itself uses and a clip-renaming script that was run against a real avatar to confirm it works. Its Draco flag was wrong, its upload path pointed at the wrong page, and it still warned that an avatar without an idle clip would stand frozen in a T-pose, which stopped being true when animation retargeting became universal. Finally, the page-events tutorial listed the wrong fallback order for emote animations. (`/tutorials/connect-ai-brain`) `[docs, fix]`- **Oracle stops answering "nothing is happening" when the database is the thing that is down**: Several Oracle reads shared a habit: if the database was unreachable for a few seconds, they answered normally with an empty result. The movers panel said nothing was moving, the stats hero said no coin had ever been scored and no agent was armed, a coin's conviction sparkline came back flat, and the machine-readable signal endpoint told autonomous agents there were no plays, which is exactly the cue for an agent to stand down. Every one of those answers was then cached at the edge for a minute or two, so a blip lasting seconds kept showing a dead market long after the database was back. Those endpoints now tell the difference between a connectivity failure and an ordinary query fault: the first is reported honestly as a temporary outage with a retry hint and is never cached, the second still degrades to the empty answer it always did. The social ingest got the sharper end of the same bug: it used to reply that a batch had been accepted while reporting zero mints written, a receipt for a write that never landed. It now fails loudly so the sender retries. Shared conviction cards behave too: one built during an outage is no longer pinned to a coin's link preview for 15 minutes. (`/oracle`) `[fix, improvement]`+- **Pinning an avatar to IPFS works for real avatars, not just tiny ones**: Minting an avatar from the Avatar Studio pins the model and its metadata to IPFS, and the whole file is sent through the platform so the storage credential never has to reach your browser. The endpoint said it accepted files up to 10 MB, but it was actually rejecting anything over roughly 730 KB, which is smaller than almost any real avatar. The error it gave back was a bare 'payload too large' that named no limit, so there was nothing to act on. The cause was two size limits that had never been reconciled: files are sent as text, which makes them a third larger in transit, and the transport limit was left at its default while the documented limit was set eight times higher. The limits now agree. Inline uploads are accepted up to 5 MB, which is what the request size can actually carry, and anything larger has a clear path: upload it to storage first and pin it by URL, a lane that has always accepted 50 MB. Over-sized uploads now say which ceiling was crossed. Two smaller fixes came with it: the filename you send is now the filename filed with the storage provider, instead of every avatar being stored as 'avatar.glb' and every metadata file as 'manifest.json', which made a pin list impossible to read; and a request with a genuine mistake in it, such as a file from somewhere the platform does not own, now gets an error explaining the mistake rather than a generic 'service unavailable' that hid it. The endpoint is now documented in the API reference. `[fix, docs]`- **Plan checkout: a paid upgrade can only ever settle on real mainnet, and a late payment is no longer stranded**: Paying for a plan creates a quote, you send the funds, then the server checks the chain before it upgrades you. Three things in that path were wrong. The checkout side has always refused test-network quotes in production, because test-network dollars are free from a faucet, but the confirm side still let a caller name the test network itself, and it is the confirm side that decides which chain it looks at and which dollar it accepts. Both ends now read the same setting, so a production upgrade can only ever be settled by real funds on mainnet. Second, an Ethereum-side payment has to wait twelve blocks before it counts, which meant funds sent near the end of a session could land on-chain and then be refused for arriving late, with the money already gone; that lane now honors the same one-hour grace window the Solana lane has, so an on-chain payment is always claimable. Third, confirming an Ethereum payment could reach a Solana quote and mark it expired, and asking to buy a skill from a malformed agent id answered a generic server error instead of telling you what was wrong with the request. (`/pricing`) `[fix, security]`- **Seeding an agent from GitHub is locked to your own click, and a mistyped pick no longer costs you six hours**: 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. (`/docs/github-memory-seeding`) `[security, fix]`- **Self-hosting docs no longer hand you a command that wipes your environment**: The deployment guide told self-hosters to set Cloud Run environment variables with `gcloud run services update --set-env-vars`. That flag replaces the service environment wholesale, so following the instruction for a single key silently deletes every other variable the service had. The guide now uses `--update-env-vars` and says plainly why. Four more corrections landed in the same sweep across the deployment, configuration and contributing pages: the Avaturn signup link and the GitHub Discussions links were dead (Discussions are not enabled on the repository, so bug reports and design questions both go to Issues); the in-browser avatar builder was documented as needing its own hosted origin in production when the normal build already serves it same-origin at /avatar-studio; and three counts that had drifted from the code (cron jobs, MCP server packages, contract tests) were replaced with pointers to the files that hold the real numbers. (`/docs/deployment`) `[docs, fix]`diff --git a/data/changelog.json b/data/changelog.jsonindex b16e6dd47..1317d1f74 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,15 @@{"$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": "Pinning an avatar to IPFS works for real avatars, not just tiny ones",+ "summary": "Minting an avatar from the Avatar Studio pins the model and its metadata to IPFS, and the whole file is sent through the platform so the storage credential never has to reach your browser. The endpoint said it accepted files up to 10 MB, but it was actually rejecting anything over roughly 730 KB, which is smaller than almost any real avatar. The error it gave back was a bare 'payload too large' that named no limit, so there was nothing to act on. The cause was two size limits that had never been reconciled: files are sent as text, which makes them a third larger in transit, and the transport limit was left at its default while the documented limit was set eight times higher. The limits now agree. Inline uploads are accepted up to 5 MB, which is what the request size can actually carry, and anything larger has a clear path: upload it to storage first and pin it by URL, a lane that has always accepted 50 MB. Over-sized uploads now say which ceiling was crossed. Two smaller fixes came with it: the filename you send is now the filename filed with the storage provider, instead of every avatar being stored as 'avatar.glb' and every metadata file as 'manifest.json', which made a pin list impossible to read; and a request with a genuine mistake in it, such as a file from somewhere the platform does not own, now gets an error explaining the mistake rather than a generic 'service unavailable' that hid it. The endpoint is now documented in the API reference.",+ "tags": [+ "fix",+ "docs"+ ]+ },{"date": "2026-08-15","title": "Eight build tutorials now match what the platform actually does",diff --git a/docs/tutorials/emotion-from-data.md b/docs/tutorials/emotion-from-data.mdindex b54b9c89a..b28ab6dd4 100644--- a/docs/tutorials/emotion-from-data.md+++ b/docs/tutorials/emotion-from-data.md@@ -16,7 +16,7 @@ You'll build two working pipelines. One uses zero AI (a lexicon sentiment score,## Step 1: The two animation entry points-Every `<agent-3d>` element exposes two public methods for triggering body animation, and, per the [JS API tutorial](/tutorials/js-api-events#step-5--animations-exact-clip-vs-emote), they answer different questions.+Every `<agent-3d>` element exposes two public methods for triggering body animation, and, per the [JS API tutorial](/tutorials/js-api-events#step-5-animations-exact-clip-vs-emote), they answer different questions.**`agent.play(clipName)`**: plays the clip with that *exact* name from the loaded library or GLB. Case-sensitive; if the name isn't found, nothing plays. Use this once you know what's actually in the rig, e.g. `agent.play('rumba')`, `agent.play('thriller')`, `agent.play('celebrate')`. The full catalog (idle, locomotion, dance, gesture, action, sport, reaction, fitness, every clip a real, retargetable library entry, never hardcoded per-rig) is browsable at [/animations](/animations).diff --git a/packages/avatar-cli/README.md b/packages/avatar-cli/README.mdindex 1abcfa0a6..c0683e6b1 100644--- a/packages/avatar-cli/README.md+++ b/packages/avatar-cli/README.md@@ -57,11 +57,12 @@ three-ws-avatar init \--mesh ./michelle.glb \--skeleton mixamo \--out manifest.json-# → wrote /…/manifest.json (validated against @three-ws/avatar-schema before writing)+# → ok wrote /…/manifest.json (validated against @three-ws/avatar-schema before writing)+# plus a summary line for id, skeleton, and mesh (format · size · sha256)# 3. Validate itthree-ws-avatar validate manifest.json-# → ok: manifest.json+# → ok manifest.json is valid# 4. Print embed snippetsthree-ws-avatar preview manifest.json@@ -106,7 +107,7 @@ you get JSON back, it's spec-compliant by definition.### `validate` — check a manifest```bash-three-ws-avatar validate manifest.json # → ok: manifest.json+three-ws-avatar validate manifest.json # → ok manifest.json is validthree-ws-avatar validate manifest.json --json # → {"valid":true,"path":"manifest.json"}```diff --git a/packages/vision-mcp/examples/README.md b/packages/vision-mcp/examples/README.mdindex 3003ff1db..689e415f7 100644--- a/packages/vision-mcp/examples/README.md+++ b/packages/vision-mcp/examples/README.md@@ -80,6 +80,7 @@ The image must be a public https URL serving JPEG, PNG, WebP, or GIF (the visionserver fetches it, so private and loopback hosts are rejected). To read a localfile instead, base64 it and pass `image` + `imageType` to the same tools.-A free NIM lane can exceed its deadline under load; the example retries an-`upstream_error` / `timeout` / `network_error` once, then reports the tool's own-error code rather than a stack trace.+A busy free NIM lane can exceed its deadline; the example retries an+`upstream_error` / `timeout` / `network_error` up to three attempts with a short+backoff (you will see `(upstream_error on attempt 1, retrying)` when that+happens), then reports the tool's own error code rather than a stack trace.diff --git a/packages/vision-mcp/examples/read-an-image.mjs b/packages/vision-mcp/examples/read-an-image.mjsindex 24a4a8edf..c87e76f2d 100644--- a/packages/vision-mcp/examples/read-an-image.mjs+++ b/packages/vision-mcp/examples/read-an-image.mjs@@ -36,9 +36,12 @@ function childEnv() {return env;}-// A free NIM lane occasionally exceeds its deadline under load; the next call-// lands on a healthy one. Retry those two codes once, and only those.+// A busy free NIM lane can exceed its deadline; the next call usually lands on a+// healthy one. Retry those three codes, and only those, with a short backoff.const TRANSIENT = new Set(['upstream_error', 'timeout', 'network_error']);+const MAX_ATTEMPTS = 3;++const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));/** Call a tool and parse the JSON payload its single text block carries. */async function callTool(client, name, args, attempt = 1) {@@ -46,9 +49,10 @@ async function callTool(client, name, args, attempt = 1) {const text = res?.content?.find((part) => part.type === 'text')?.text ?? '{}';const payload = JSON.parse(text);if (res.isError || payload.ok === false) {- if (attempt === 1 && TRANSIENT.has(payload.error)) {- console.log(` (${payload.error} on the first try, retrying once)`);- return callTool(client, name, args, 2);+ if (attempt < MAX_ATTEMPTS && TRANSIENT.has(payload.error)) {+ console.log(` (${payload.error} on attempt ${attempt}, retrying)`);+ await wait(attempt * 1000);+ return callTool(client, name, args, attempt + 1);}throw Object.assign(new Error(payload.message || `${name} failed`), { tool: name, payload });}diff --git a/public/changelog.json b/public/changelog.jsonindex dc487c3a1..da50202f7 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T06:57:50.640Z",+ "generated_at": "2026-08-15T06:59:40.797Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -81,6 +81,17 @@"improvement"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "Pinning an avatar to IPFS works for real avatars, not just tiny ones",+ "summary": "Minting an avatar from the Avatar Studio pins the model and its metadata to IPFS, and the whole file is sent through the platform so the storage credential never has to reach your browser. The endpoint said it accepted files up to 10 MB, but it was actually rejecting anything over roughly 730 KB, which is smaller than almost any real avatar. The error it gave back was a bare 'payload too large' that named no limit, so there was nothing to act on. The cause was two size limits that had never been reconciled: files are sent as text, which makes them a third larger in transit, and the transport limit was left at its default while the documented limit was set eight times higher. The limits now agree. Inline uploads are accepted up to 5 MB, which is what the request size can actually carry, and anything larger has a clear path: upload it to storage first and pin it by URL, a lane that has always accepted 50 MB. Over-sized uploads now say which ceiling was crossed. Two smaller fixes came with it: the filename you send is now the filename filed with the storage provider, instead of every avatar being stored as 'avatar.glb' and every metadata file as 'manifest.json', which made a pin list impossible to read; and a request with a genuine mistake in it, such as a file from somewhere the platform does not own, now gets an error explaining the mistake rather than a generic 'service unavailable' that hid it. The endpoint is now documented in the API reference.",+ "link": null,+ "tags": [+ "fix",+ "docs"+ ]+ },{"date": "2026-08-15","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex a055565ab..44117e7cc 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -62,6 +62,14 @@<category>fix</category><description>Several Oracle reads shared a habit: if the database was unreachable for a few seconds, they answered normally with an empty result. The movers panel said nothing was moving, the stats hero said no coin had ever been scored and no agent was armed, a coin's conviction sparkline came back flat, and the machine-readable signal endpoint told autonomous agents there were no plays, which is exactly the cue for an agent to stand down. Every one of those answers was then cached at the edge for a minute or two, so a blip lasting seconds kept showing a dead market long after the database was back. Those endpoints now tell the difference between a connectivity failure and an ordinary query fault: the first is reported honestly as a temporary outage with a retry hint and is never cached, the second still degrades to the empty answer it always did. The social ingest got the sharper end of the same bug: it used to reply that a batch had been accepted while reporting zero mints written, a receipt for a write that never landed. It now fails loudly so the sender retries. Shared conviction cards behave too: one built during an outage is no longer pinned to a coin's link preview for 15 minutes.</description></item>+ <item>+ <title>Pinning an avatar to IPFS works for real avatars, not just tiny ones</title>+ <link>https://three.ws/changelog</link>+ <guid isPermaLink="false">2026-08-15:Pinning an avatar to IPFS works for real avatars, not just tiny ones</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>Minting an avatar from the Avatar Studio pins the model and its metadata to IPFS, and the whole file is sent through the platform so the storage credential never has to reach your browser. The endpoint said it accepted files up to 10 MB, but it was actually rejecting anything over roughly 730 KB, which is smaller than almost any real avatar. The error it gave back was a bare 'payload too large' that named no limit, so there was nothing to act on. The cause was two size limits that had never been reconciled: files are sent as text, which makes them a third larger in transit, and the transport limit was left at its default while the documented limit was set eight times higher. The limits now agree. Inline uploads are accepted up to 5 MB, which is what the request size can actually carry, and anything larger has a clear path: upload it to storage first and pin it by URL, a lane that has always accepted 50 MB. Over-sized uploads now say which ceiling was crossed. Two smaller fixes came with it: the filename you send is now the filename filed with the storage provider, instead of every avatar being stored as 'avatar.glb' and every metadata file as 'manifest.json', which made a pin list impossible to read; and a request with a genuine mistake in it, such as a file from somewhere the platform does not own, now gets an error explaining the mistake rather than a generic 'service unavailable' that hid it. The endpoint is now documented in the API reference.</description>+ </item><item><title>Plan checkout: a paid upgrade can only ever settle on real mainnet, and a late payment is no longer stranded</title><link>https://three.ws/pricing</link>diff --git a/public/features.json b/public/features.jsonindex ee9dd9b33..4255eff93 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T06:57:50.370Z",+ "generated_at": "2026-08-15T06:59:40.624Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/tests/branding-allowlist.json b/tests/branding-allowlist.jsonindex add26c626..8d73244e2 100644--- a/tests/branding-allowlist.json+++ b/tests/branding-allowlist.json@@ -528,5 +528,25 @@"pattern": "Mixamo, Avaturn, VRM/VRoid, Daz/Genes","file": "docs/announcement-coverage.md","reason": "Coverage table quoting @three-ws/retarget's own package description verbatim; the rig-name list is the same factual interop reference as the other retargeter mentions above, not product copy naming a competing feature."+ },+ {+ "pattern": "Sign up through the [Avaturn developer docs](https://docs.avaturn.me/).",+ "file": "docs/configuration.md",+ "reason": "Setup step for AVATURN_API_KEY, which is already exempt as an environment variable name. The reader has to be told whose developer portal issues that key, so naming the vendor is the instruction, not product copy."+ },+ {+ "pattern": "# Get key through the Avaturn developer docs: https://docs.avaturn.me/",+ "file": "docs/deployment.md",+ "reason": "Same AVATURN_API_KEY provisioning step as docs/configuration.md, here as a comment beside the variable in the deployment env list."+ },+ {+ "pattern": "Mixamo, Avaturn, Unreal, VRM/VRoid, VRM 1.0, Daz/Genesis, MakeHuman, Blender",+ "file": "docs/tutorials/upload-custom-glb.md",+ "reason": "Factual list of the third-party rig-name conventions glb-canonicalize.js maps onto the canonical bone set, the same interop listing already exempt in docs/avatar-pipeline.md and CLAUDE.md's 'Avatar animation is universal' note."+ },+ {+ "pattern": "Mixamo (`mixamorigHead`), VRM, Avaturn, Unreal, Daz, MakeHuman, or Blender",+ "file": "docs/tutorials/upload-custom-glb.md",+ "reason": "The repair instruction has to name the conventions the canonicalizer recognizes so a reader knows what to rename their bones to; technical identifiers rather than product copy."}]