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(tutorials): correct the optimizer figures and the free-call note against the live API

nirholas6927c7d98e30
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0001a94cf..f728b0920 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Crypto news stops leading with gold prices and Indian equities**: The filter that decides whether a story from a broad outlet belongs in a crypto feed matched its keyword list as raw text, so "defi" fired inside the ordinary word "defied" and three Economic Times headlines about Indian share prices led /markets/news and the top of the daily digest. The ticker detector had the same flaw: it read the English word "near" as NEAR Protocol, "optimism" as OP, and "maker" as MKR, which pinned live price widgets to unrelated stories and pushed NEAR to third place in the archive trending strip on the strength of phrases like "near-term profit booking". Both now match whole words, and those three projects count only when the story actually names them. Separately, the FXStreet feed we pull was the publisher site-wide one (gold, EUR/JPY, central banks) rather than its crypto desk, so "India Gold price today" arrived pre-approved; it now points at the crypto feed. (`/markets/news`) `[fix, improvement]`
- **Draft with AI actually returns drafts, and the X panel stops 500ing on a bad id**: The Draft and Draft x3 buttons in the agent's X panel asked the server for tweet options and got back a differently shaped answer, so the panel cleared itself and showed nothing every time. Drafting now returns the options it was asked for: one per click of Draft x3, each written from its own angle, in the tone picked in the panel and in the voice of the agent it belongs to, with Thread mode splitting a completion into real thread parts. Drafting is also gated like every other write, so another site cannot spend a signed-in account's model budget. Elsewhere on the same panel, a malformed id or agent filter now comes back as a plain validation error instead of a server error, approving a queued post can no longer be published twice by a double click, and scheduling has a sane ceiling on how many posts and rules one account can queue. `[fix, improvement]`
- **Eight docs pages checked line by line, and four stale claims corrected**: A sweep of the viability, press kit, partners, agent identities, OKX marketplace, avatar engines, stage, and world lines pages, with every command in them actually run and every link followed. Four things were wrong and are now right. The partners page pointed the NVIDIA row at a docs path when the card on the live page goes to /nvidia. The agent identity docs claimed a job handle expires after about thirty days, which nothing in the code enforces; the page now states what is true, that the signed handle carries no expiry and the job record stays readable. The marketplace page showed a create call replying with a queued status and a generation stage, neither of which the endpoint has ever returned, so an agent coding against the sample would have waited on a state that never arrives; the page and the endpoint's own published example now show the running status and generate stage the code emits. The same page read as though our marketplace listing were live when it is still in review, and now says so plainly. The world lines anti-cheat table was also missing one of the per-IP limits it lists. (`/docs/partners`) `[docs, fix]`
+- **Eight more docs pages audited, and the embed snippet that would have failed on paste is fixed**: A line-by-line sweep of the walk leaderboard, Atlas, repository guards, wallet sign-in, spending envelope, avatar image render, character library embed, and skill trial pages, with every command in them run against the live API. The embed tutorial pinned a Subresource Integrity hash that no longer matched the script it names, so a reader who pasted it got a blank box and a browser console error instead of a character; it now carries the hash the site itself publishes. The skill trial page printed a start-trial response the endpoint never returns, and now shows the real one plus the two refusals a seller has to handle. The walk leaderboard page listed the walk documentation set with two pages missing. The Atlas page said the slash key always opens search, when a page that claims that key keeps it. The spending envelope page quoted a free-call note with the wrong wording and now matches the API, and the render tutorial's optimizer figures were stale, so it now tells you to read the byte headers instead of the printed numbers. (`/docs/tutorials/character-library-to-embed`) `[docs, fix]`
- **Eleven links that led nowhere now land where they promise**: The audit that guards every page against dead ends had a hole in it: the rule that serves the not-found page matched every address on the site, so the audit read every link as reachable and reported a clean bill of health it could not vouch for. With that fixed, eleven links turned out to lead to pages that were never built. Sign in to save on the choreography and gesture pages pointed at an address that does not exist, so the one thing those pages ask you to do could not be done. The extension terms page linked its own terms of service to a missing address, twice. The motion studio offered to show you how to capture an avatar from a selfie and led nowhere, as did the pricing page's link to your account, the memory tutorial's link to your library, and two entries in the dashboard trading menu. Pressing Message on a friend in the 3D world walked you into a blank page instead of the conversation, and now opens the thread with that person. Three outbound links to other projects' documentation had rotted and now point at the pages that replaced them. The audit itself was rebuilt to be trustworthy: it no longer calls a live site dead because the site answers a robot differently than a browser, and it no longer treats the blog and docs it ships, or the app manifest it generates, as missing files. `[fix, improvement]`
- **Every agent now has a verifiable on-chain history you can read on its page**: Agents do things on-chain after they are registered: they launch a token, collect reputation attestations, change hands, delegate execution rights. Until now the platform recorded only who an agent currently was, so all of that history was dropped, and anyone who wanted it had to scan a chain themselves. Open any agent under the Discover directory and there is now an On-chain history panel: a timeline of everything the platform has indexed for that agent, each entry stamped with the real time the chain says it happened and linked to the transaction on a block explorer so you can check it yourself. The same data is available to developers as one public endpoint. Three failures were fixed to make it real. The Solana half of the indexer was crashing on every single agent it looked at, so despite tracking more than fifteen hundred agents it had recorded zero events; it now records them, and a token launch names the agent's actual coin instead of the wrapped SOL that paid for it. On the EVM side, five of the twenty-two supported chains were producing blocks faster than the indexer could read them, so their backlog grew every hour while the status page called them healthy: the indexer now widens its reading window until it catches up, and the status page publishes how many blocks behind the worst chain is, as a number. Reputation was the third: the platform was already asking every EVM chain for agent feedback and vouches on every pass, then throwing the answers away, so not a single reputation event had ever reached the index. Those now land alongside the rest of an agent's history, with the score, its tags, and a link to the attestation. (`/docs/agent-index`) `[feature, fix, infra]`
- **Every avatar you scan now arrives with an on-chain identity of its own, minted for you in the background**: When a scan or a prompt finishes building your avatar, the finished model is written to permanent storage and the agent behind it is given a real on-chain identity at the same moment. It is a Metaplex Core asset on Solana, minted into the platform's own agent collection with the royalty terms and registry enrolment every other platform mint carries, and it is owned by the agent's own wallet rather than by us. There is no wallet prompt, no fee, and no step to remember: by the time the avatar shows up in your library the identity already exists and anyone can look it up. It is created as a draft, which means it says the agent exists and this is its avatar, not that it is live and taking work. Going live stays a deliberate choice you make later. If the mint cannot run for any reason your avatar is completely unaffected, because it is already delivered and saved before the mint is ever attempted. Agents that want an Ethereum-side identity as well can have one registered under the ERC-8004 standard, and the whole path is now documented, including the single setting an operator flips to arm it for the main Solana network and the script that proves the whole chain end to end on the test network. (`/create/selfie`) `[feature, docs]`
diff --git a/data/changelog.json b/data/changelog.json
index 37f2407b8..fd5c726ff 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$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-14",
+ "title": "Eight more docs pages audited, and the embed snippet that would have failed on paste is fixed",
+ "summary": "A line-by-line sweep of the walk leaderboard, Atlas, repository guards, wallet sign-in, spending envelope, avatar image render, character library embed, and skill trial pages, with every command in them run against the live API. The embed tutorial pinned a Subresource Integrity hash that no longer matched the script it names, so a reader who pasted it got a blank box and a browser console error instead of a character; it now carries the hash the site itself publishes. The skill trial page printed a start-trial response the endpoint never returns, and now shows the real one plus the two refusals a seller has to handle. The walk leaderboard page listed the walk documentation set with two pages missing. The Atlas page said the slash key always opens search, when a page that claims that key keeps it. The spending envelope page quoted a free-call note with the wrong wording and now matches the API, and the render tutorial's optimizer figures were stale, so it now tells you to read the byte headers instead of the printed numbers.",
+ "tags": [
+ "docs",
+ "fix"
+ ],
+ "link": "/docs/tutorials/character-library-to-embed"
+ },
{
"date": "2026-08-14",
"title": "The privacy policy's data table no longer pushes the page sideways on a phone",
diff --git a/docs/tutorials/agent-spending-envelope.md b/docs/tutorials/agent-spending-envelope.md
index 83aadba06..4bda1ee3b 100644
--- a/docs/tutorials/agent-spending-envelope.md
+++ b/docs/tutorials/agent-spending-envelope.md
@@ -258,7 +258,7 @@ curl -s $BASE/api/pay/execute \
{
"ok": true,
"paid": false,
- "note": "Endpoint served response without a 402 - no payment needed.",
+ "note": "Endpoint served response without a 402. No payment needed.",
"status": 200,
"result": { "ok": true, "method": "GET", "headers": { "...": "..." }, "body": null, "ts": "..." }
}
diff --git a/docs/tutorials/render-avatar-images.md b/docs/tutorials/render-avatar-images.md
index cd139b0b4..e27202349 100644
--- a/docs/tutorials/render-avatar-images.md
+++ b/docs/tutorials/render-avatar-images.md
@@ -376,10 +376,11 @@ curl -sL -D - -o small.glb "$REMY" | grep -i 'x-three-ws'
```
x-three-ws-source-bytes: 20566060
-x-three-ws-output-bytes: 1737840
+x-three-ws-output-bytes: 1479972
+x-three-ws-optimize: none
```
-20.6 MB down to 1.7 MB, a 92% cut, mostly from capping textures at 512px and dropping non-ARKit morph targets. `textureSize` accepts `128`, `256`, `512`, `1024`, `2048`; `lod=1` or `lod=2` adds progressively more aggressive welding; `morphs=arkit52` drops every morph target outside the standard set. `src` must be on a three.ws-controlled origin (the app origin or the CDN host), otherwise it is `400 untrusted_source`. Full parameter list in the [Media & Render API reference](/docs/media-api.md).
+20.6 MB down to 1.5 MB, better than a 90% cut, mostly from capping textures at 512px and dropping non-ARKit morph targets. Read the two byte headers rather than the numbers printed here: the exact output size moves as the pipeline improves. `x-three-ws-optimize` names the mesh-compression scheme that survived (`draco`, `meshopt`, `none`, or `source` when the pipeline could not beat the original and handed the source bytes back untouched); `none` here means the saving came from textures and morphs alone. `textureSize` accepts `128`, `256`, `512`, `1024`, `2048`; `lod=1` or `lod=2` adds progressively more aggressive welding; `morphs=arkit52` drops every morph target outside the standard set. `src` must be on a three.ws-controlled origin (the app origin or the CDN host), otherwise it is `400 untrusted_source`. Full parameter list in the [Media & Render API reference](/docs/media-api.md).
Best part: the optimizer's own URL is a public https URL, so you can hand it straight to the renderer and never store an intermediate file.
diff --git a/prompts/swarm-100/docs-batch-25.md b/prompts/swarm-100/docs-batch-25.md
deleted file mode 100644
index d8d4ce815..000000000
--- a/prompts/swarm-100/docs-batch-25.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Docs audit batch 25: /docs/walk-leaderboard through /tutorials/sell-a-skill-with-a-trial
-
-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/walk-leaderboard /docs/atlas /docs/guards /tutorials/wallet-sign-in /tutorials/agent-spending-envelope /tutorials/render-avatar-images /tutorials/character-library-to-embed /tutorials/sell-a-skill-with-a-trial; 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/walk-leaderboard ("Docs: Walk Leaderboard")
-- /docs/atlas ("Docs: Atlas and Cmd+K search")
-- /docs/guards ("Repository guards")
-- /tutorials/wallet-sign-in ("Tutorial · Add Wallet Sign-In to Your App")
-- /tutorials/agent-spending-envelope ("Tutorial · Give an Agent a Spending Envelope")
-- /tutorials/render-avatar-images ("Tutorial · Render Avatars as Images")
-- /tutorials/character-library-to-embed ("Tutorial · Character Library to a Live Embed")
-- /tutorials/sell-a-skill-with-a-trial ("Tutorial · Sell a Skill With a Free Trial That Converts")
-
-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-25.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.json
index 5e2e55f34..eabe0ea62 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-14T21:10:59.178Z",
+ "generated_at": "2026-08-14T21:58:07.469Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -402,6 +402,17 @@
"fix"
]
},
+ {
+ "date": "2026-08-14",
+ "type": "update",
+ "title": "Eight more docs pages audited, and the embed snippet that would have failed on paste is fixed",
+ "summary": "A line-by-line sweep of the walk leaderboard, Atlas, repository guards, wallet sign-in, spending envelope, avatar image render, character library embed, and skill trial pages, with every command in them run against the live API. The embed tutorial pinned a Subresource Integrity hash that no longer matched the script it names, so a reader who pasted it got a blank box and a browser console error instead of a character; it now carries the hash the site itself publishes. The skill trial page printed a start-trial response the endpoint never returns, and now shows the real one plus the two refusals a seller has to handle. The walk leaderboard page listed the walk documentation set with two pages missing. The Atlas page said the slash key always opens search, when a page that claims that key keeps it. The spending envelope page quoted a free-call note with the wrong wording and now matches the API, and the render tutorial's optimizer figures were stale, so it now tells you to read the byte headers instead of the printed numbers.",
+ "link": "/docs/tutorials/character-library-to-embed",
+ "tags": [
+ "docs",
+ "fix"
+ ]
+ },
{
"date": "2026-08-14",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 6f248b9d6..b8fa10bdd 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -302,6 +302,14 @@
<category>docs</category>
<description>A sweep of the viability, press kit, partners, agent identities, OKX marketplace, avatar engines, stage, and world lines pages, with every command in them actually run and every link followed. Four things were wrong and are now right. The partners page pointed the NVIDIA row at a docs path when the card on the live page goes to /nvidia. The agent identity docs claimed a job handle expires after about thirty days, which nothing in the code enforces; the page now states what is true, that the signed handle carries no expiry and the job record stays readable. The marketplace page showed a create call replying with a queued status and a generation stage, neither of which the endpoint has ever returned, so an agent coding against the sample would have waited on a state that never arrives; the page and the endpoint's own published example now show the running status and generate stage the code emits. The same page read as though our marketplace listing were live when it is still in review, and now says so plainly. The world lines anti-cheat table was also missing one of the per-IP limits it lists.</description>
</item>
+ <item>
+ <title>Eight more docs pages audited, and the embed snippet that would have failed on paste is fixed</title>
+ <link>https://three.ws/docs/tutorials/character-library-to-embed</link>
+ <guid isPermaLink="false">2026-08-14:Eight more docs pages audited, and the embed snippet that would have failed on paste is fixed</guid>
+ <pubDate>Fri, 14 Aug 2026 12:00:00 GMT</pubDate>
+ <category>docs</category>
+ <description>A line-by-line sweep of the walk leaderboard, Atlas, repository guards, wallet sign-in, spending envelope, avatar image render, character library embed, and skill trial pages, with every command in them run against the live API. The embed tutorial pinned a Subresource Integrity hash that no longer matched the script it names, so a reader who pasted it got a blank box and a browser console error instead of a character; it now carries the hash the site itself publishes. The skill trial page printed a start-trial response the endpoint never returns, and now shows the real one plus the two refusals a seller has to handle. The walk leaderboard page listed the walk documentation set with two pages missing. The Atlas page said the slash key always opens search, when a page that claims that key keeps it. The spending envelope page quoted a free-call note with the wrong wording and now matches the API, and the render tutorial's optimizer figures were stale, so it now tells you to read the byte headers instead of the printed numbers.</description>
+ </item>
<item>
<title>Eleven links that led nowhere now land where they promise</title>
<link>https://three.ws/changelog</link>