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(changelog): publish the embodied AgenC demo entry to the holder feeds and retire its work order
nirholase13ede39eafd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a41877fcc..d556b758c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr## 2026-08-15- **A broken paid endpoint is no longer reported as a free one**: Payment sessions let you hand an agent a budget instead of a key, and two parts of that path judged an endpoint by one rule: if it did not ask for payment, the call was free. That is only true when the endpoint actually succeeded. A paid API answering 404, 400, or 500 was being scored as a free call, and the consequences ran in the wrong direction in both places. The dry run at /pay/simulator, whose whole job is to tell you in advance whether a budget and an allowlist will carry a workload, reported a plan as feasible at a cost of nothing when in fact every endpoint in it was erroring: free calls are never priced, never allowlist-checked, and never counted, so a wall of failures looked like a clean run. And an agent spending through a session got back a success envelope saying no payment was needed for an endpoint that had just failed on it. Both now separate the two cases: a real success with no payment challenge is still free and still costs nothing, while an error status is reported as an endpoint failure carrying the status the endpoint actually returned. No session is charged either way. The simulator lists each failing endpoint by name in its problems list and no longer calls the plan feasible. (`/pay/simulator`) `[fix]`+- **A shared link to a docs page now opens that page instead of stranding you**: 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. (`/docs/agent-wallets`) `[fix, docs]`- **A silent outage in the agent reasoning ledger now reports itself**: Every agent decision is committed to a hash chain, and that chain head is written to Solana on a schedule so anyone can check the history was never edited. The wallet that pays for those on-chain writes ran empty, and the scheduled job could not tell that apart from the harmless case where no signing key is set up at all: it answered a healthy 200 every ten minutes while re-sending the same doomed transaction for twelve agents in a row, and not one head reached the chain. A rejected write is now reported as a rejected write, the rest of the run stops instead of repeating a failure that cannot succeed, and it raises an alert so the wallet gets refilled. Verifying a ledger already worked without the on-chain leg and still does: the recomputed hash chain is the tamper proof, the on-chain write is the independent timestamp on top of it. Separately, the once-a-minute economy heartbeat now refuses to drive production from a machine that is not production, so a developer running it locally can no longer fire thirty-six live money engines at the real site. (`/docs/reasoning-ledger`) `[fix, infra]`- **Arming an Oracle agent for live trading no longer rounds your trade size up**: The arm page clamps the risk knobs on the server so a bad number can never reach the trading loop, and those clamps have a floor: the smallest trade the loop will place is 0.001 SOL. That floor was being applied in the wrong direction. Ask to arm a live agent with a per-trade size of zero, and instead of being told no, you were armed for real spending at 0.001 SOL a trade with a half-SOL daily ceiling you never asked for. The check meant to catch this looked at the number after the clamp had already raised it, so it could never fire. Arming live now refuses any per-trade size below the floor, and any daily cap smaller than a single trade, and tells you which number to fix; nothing is armed until you do. Clamping a too-large number back down to the ceiling is unchanged, and simulate runs keep the same forgiving behaviour as before. The arm page also shows the reason a save was rejected instead of one generic line, so an ownership problem no longer reads the same as a bad trade size, and a failed Telegram test now prints what Telegram actually said. (`/oracle/arm`) `[fix, security]`- **Avatars can move their lips again: the Audio2Face lane is back**: Every call that turns speech into facial animation had been failing with an upstream not-found error, so a talking avatar spoke with a frozen face and the one-shot say() path returned nothing usable. The hosted model id the lane pointed at had stopped resolving for our NVIDIA account. It now points at the hosted Audio2Face NIM that is actually live, verified end to end: a synthesized clip drives a 30 fps ARKit blendshape track whose jaw genuinely opens and closes with the words. The discovery helper that finds these model ids was missing the name NVIDIA publishes them under, which is why the outage looked like a configuration mystery; it now finds them. `[fix]`@@ -17,6 +18,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **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]`+- **The 3D API and agent manifest references now match what the endpoints actually return**: 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. The prompt art-director note is confirmed accurate and the code comment that contradicted it was fixed. (`/docs/3d-api`) `[fix, docs]`- **The 3D pipeline docs stop telling you to run a command that does not exist**: 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 a could-not-determine-executable error 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 and game-ready 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 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 opening sentence linked the word AgenC to a different protocol page; and the vanity protocol spec showed a stale copy of the service key document, which now matches what the live endpoint serves. (`/docs/3d-pipeline`) `[docs, fix]`- **The Agent Economy demo works again when you just pick a service, and it fits a phone screen**: On the Agent Economy page, two 3D agents trade with each other for real SOL: Nova buys a market read, an on-chain insight, or a risk score from Oracle. Picking a service and typing nothing in the optional topic box, which is what almost everyone does, sent the request off in a shape the endpoint refused, so the demo answered with a validation error instead of a trade. It now sends the request correctly, and the endpoint accepts an empty topic besides. On a phone the page was worse than broken: the transaction feed and the status line, the entire output of the demo, were cut off the bottom of the screen with no way to scroll to them, and the floating language button sat on top of the footer links. The centre column now scrolls, the feed keeps a readable height, and the footer stays clickable. Three failure states also stopped lying: a payment that could not go through no longer ends on Transaction complete, a request that never reached the server now says so and offers to try again, and unreadable wallet balances now say they are unavailable and offer a retry instead of spinning forever. (`/agent-economy`) `[fix, improvement]`- **The agent economy volume dashboard stops sending you to profiles that are not there**: 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. (`/agent-economy-volume`) `[fix, improvement]`@@ -24,6 +26,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **The agent-payment and MCP docs now show the code that actually ships**: Three developer docs had drifted from the code they document, in ways that cost a reader real time. The Payment Sessions walkthrough, which is the guide for giving an agent a budget instead of a wallet key, quoted five snippets that no longer match the source: the branch that refuses a payment when the budget will not cover it, the host-allowlist check (which has moved into a shared module so the dry-run simulator and the live enforcement can never disagree), the expiry sweep that refunds unspent budget, the dollars-to-atomic-units helper, and a column missing from the table definition. All five now match the shipped code line for line, and the page links the two source files it had not been pointing at. The MCP article listed the Solana vanity grinder at up to $0.50 scaled by the work done; it is a flat $0.05 per successful grind, and its setup example set a wallet variable the package does not read, so anyone copying it would have configured a payout address that was silently ignored. That example now shows only the variable that works, and says plainly that settlement is USDC on Solana mainnet. The IBM Granite forecasting example showed three data points for a tool that requires at least sixty-four, so a copied sample was guaranteed to be rejected; it now says so. (`/docs/aws-builder-center-agent-payment-sessions`) `[docs, fix]`- **The Alibaba Cloud MCP server starts now, and five MCP packages document how to import them**: The @three-ws/alibaba-cloud-mcp package, which lets an agent use Qwen chat, embeddings, and model discovery on your own Alibaba Cloud key, could not start at all. Two faults, both on the first line of use: the check for whether the file was launched directly crashed before the server ever opened, and the three tools were registered with a schema format the MCP library rejects. Both are fixed, so the server now boots, advertises its tools, and answers a client. The payment-sessions MCP package had a documentation fault with the same cost: its quick start told you to set your session variable to the whole cookie including the name, which the server then wrapped in the cookie name again, so every session-management call came back unauthorized. It now says to use the cookie value, and ships its two runnable examples inside the published package instead of only in the repository. Five packages (payment sessions, Agora, alerts, the assistant widget, and Alibaba Cloud) gained a Programmatic use section showing the exact code to import their tools into a host of your own, and the sniper package's HTTP table now lists every endpoint it actually serves, including the paid close-position route it had left out. `[fix, sdk, docs]`- **The embed tutorials now name the attribute that actually hides the built-in chat**: 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. The affected tutorials now use chat="off", the real bare-avatar switch, and note 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. (`/tutorials/web-component-end-to-end`) `[fix, docs]`+- **The embodied AgenC demo hands you a live task, and reacts to the state a claimed task is actually in**: The /agenc/embodied page binds a 3D agent to a real AgenC task on Solana, and until now it opened on an empty input box: it needed a task account address and offered no way anywhere on the page to find one. It now lists real tasks three.ws itself posted, claimed, and settled on-chain, newest first, so the demo works the moment it loads; a new public read, /api/agenc/recent-tasks, serves that list. Two things it showed were also wrong. The scene coloured itself for a state named Claimed, which the chain has never used: a claimed task is In Progress on-chain, so the halo, the badge, and the per-state animation switch all sat inert through the one transition the demo exists to show. And the page named a program address that no read has touched since the protocol's interface moved; it now shows the program each live read actually ran against. Pasting an address that holds something other than a task used to report a server error, as though the platform were broken, rather than saying no such task exists there; that is now a plain not-found, with the page telling you to check the address or switch cluster. The panel has designed loading, empty, and error states throughout, the form fields have real labels, the layout no longer scrolls sideways on a phone, and a task that cannot be read is retried with a backoff instead of being re-requested every four seconds forever. (`/agenc/embodied`) `[fix, improvement, feature]`- **The guard and gesture tutorials stop teaching steps that fail, and one that wiped your clip list**: 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. (`/docs/tutorials/write-a-guard`) `[docs, fix]`- **The persona builder stops reporting a model outage as if you had been signed out**: The two routes behind the persona builder (the one that turns your interview answers or a sample of your own writing into a structured persona, and the one that replies to you in that persona's voice) used to hand you whatever status code the model provider returned. If a server-side key expired, the provider answered 401 and so did we, which reads to a browser as an expired session on a request where nothing was wrong with your sign-in. Both now report a provider failure as exactly what it is: a server-side fault, with a plain message and no implication that you need to log back in. Separately, when the platform's daily model-spend ceiling is reached, the builder now says so and tells you when it resets, instead of asking you to retry something that could not have succeeded for the rest of the day. Both routes also now record their model usage against your account, so the spend they generate is visible and capped rather than untracked, and the daily extraction budget now holds across every server instance instead of being counted separately on each one. `[fix, improvement]`- **The plugin marketplace stops hiding a plugin when you page through it**: Browsing plugins a page at a time could show you the same plugin twice and never show another one at all. The catalogue was sorted by install count and publish date, and the built-in plugins were all published in the same instant with zero installs, so that sort left them tied and the database was free to order the tied rows differently on every request. One plugin therefore landed on two consecutive pages and one fell through the gap. The order is now decided all the way down, so paging through the catalogue returns every plugin exactly once. Searching also takes your text literally: typing a percent sign or an underscore used to act as a database wildcard and match rows it should not. Publishing got stricter at the same time, because a plugin manifest is handed to the model as a tool definition by whoever installs it: a tool name now has to be plain letters, digits, underscores, or hyphens, every tool needs a real description, and a manifest has to fit the same 64KB ceiling that importing one by URL already enforced. And pointing the importer at a repository web page instead of the raw manifest file now says exactly that, rather than showing a raw parser error. (`/marketplace`) `[fix, improvement]`@@ -31,6 +34,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **The vanity receipt verifier stops calling honest receipts fraudulent, and the avatar CLI takes a Solana address**: Two documented commands did not do what their page said. The command-line verifier for a provably-fair vanity address receipt scored the difficulty claim with the retired flat model, the one that treats every Base58 character as equally likely. Every receipt issued since the leading-character correction landed therefore failed its difficulty check and was reported as untrustworthy, even though the in-browser verifier at /vanity/verify passed the same receipt. The verifier now reads the model each receipt names in its own signed difficulty block, exactly as the page and the SDK do, so current receipts verify and older ones keep verifying under the model they were issued under. Separately, the Rig Doctor page showed an avatar-manifest command taking a Solana address as the owner, which the CLI rejected outright: it understood Ethereum addresses and full CAIP-10 identifiers and nothing else. Since Solana is the home chain, a bare Solana address is now accepted and recorded as solana:mainnet-beta. Alongside those, eight tutorial and reference pages were audited against the code they describe: the Vercel self-hosting guide had a stale copy of the config file and pointed at a migrations folder that has moved, the MCP guide listed three placeholder OAuth scopes where the live server publishes twelve real per-capability ones, and the Avatar CLI page pinned a version number that npm has never had. (`/docs/rig-doctor`) `[fix, docs, sdk]`- **The vanity SDK now uses the payment wallet you hand it, and the in-chat 3D avatar keeps its tuned lighting**: 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. `[fix, sdk, docs]`- **Three docs pages stop pointing readers at a dead page, a missing section, and a snippet that does nothing**: The Vanity page told you to grind a long address yourself in the browser at /vanity, but that path has never existed and answers 404; the in-browser grinder lives at /vanity-wallet, and both links on the page now go there. In Troubleshooting, the fix for a Quick Look model that opens and instantly closes linked to a model-optimization section that is not on the AR page, so the link dropped you at the top with nothing to read; it now opens the section that actually covers it. The same page told you to add a responsive attribute to size an inline embed, with a snippet that set the width in CSS. Neither half worked: responsive sizing is already on by default, and the element reads the width attribute rather than the computed style, so the documented snippet never produced the 3:4 ratio it promised. The instructions now show the form that does work, and name the two things that switch it off. (`/docs/troubleshooting`) `[fix, docs]`+- **Two tutorials stop shipping code samples that quietly do nothing**: An audit of eight developer tutorials found two whose main code sample looked right and silently failed. The custom-skill weather handler split the weather API's reply on a plus sign, but the temperature field arrives with a leading plus of its own, so every field after the condition landed one slot off and the temperature always came back empty; it also mapped the fahrenheit option to a format code that means feels-like rather than Fahrenheit, so the celsius and fahrenheit paths returned the same units. Both are fixed and the sample was run against the live API in both unit modes. The gesture tutorial's AI lane read an emotion-breakdown field the Granite analysis tool has never returned, so the strength check never passed and the agent never played a single animation; it now reads the score and risk flags the tool actually returns, and grades the gesture across four bands instead of a binary. Separately, twelve tutorial hero buttons pointed at anchors on the docs hub that stopped existing when the hub split into per-topic pages, and now open the real pages; a placeholder URL in the Pump.fun tutorial was being parsed as HTML, which broke a link and injected stray elements into the page; and the self-host guide was corrected throughout, including storage variable names that no longer matched the code, a database step that left most tables uncreated, an audit-logging example importing a function that does not exist, a Cloudflare worker setup for a proxy the platform does not run, and a license claim that described the repository as open source when it is not. (`/tutorials/custom-skill`) `[docs, fix]`- **Voice and vision SDKs ship runnable examples, and the x402 seller SDK reads its Solana sponsor from the environment**: @three-ws/voice and @three-ws/vision-mcp now include example scripts you can run as-is against the live free lanes: the voice one speaks a sentence, animates a face from those exact bytes, and transcribes it back; the vision one probes the lane, writes alt text for an image, and reads the text off it. @three-ws/x402-server used to demand the Solana sponsor account as a code option even though its own error message told you to set X402_FEE_PAYER_SOLANA, so a correctly configured deployment still got missing_fee_payer; it now reads that environment variable when the option is omitted. The VS Code x402 extension's endpoint scaffolder was generating Base-only endpoints and now generates Solana-first ones, matching every paid route on the platform, and it ships with a test suite covering which payment requirement it selects. `[sdk, fix]`## 2026-08-14@@ -3149,7 +3153,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Tutorial · Multi-agent coordination** (`/tutorials/multi-agent-coordination`): Two or more agents on the same page that talk to each other: turn-taking, shared memory, delegating subtasks.- **Tutorial · Pick & swap an avatar in Studio** (`/tutorials/swap-avatar-in-studio`): Swap an agent's 3D body from the Outfit panel in one click, and have the change reach every embed without touching your snippet.- **Tutorial · Self-host the agent backend** (`/tutorials/self-host-agent-backend`): Run the full three.ws backend on your own infrastructure: workers, function endpoints, model proxies. No three.ws dependency in production.-- **Tutorial · Share your agent (link, QR, social preview)** (`/tutorials/share-your-agent`): Get a permanent link to your agent, generate a QR for print, and set the Open Graph preview so it looks good in tweets.+- **Tutorial · Share your agent (link, QR, social preview)** (`/tutorials/share-your-agent`): Get a permanent link to your agent, generate a QR for print, and share the URL that unfurls with its real name, description, and card.- **Tutorial · Trigger the agent from page events** (`/tutorials/trigger-from-page-events`): Make your agent react to clicks, scrolls, form submits, and route changes: turn it into a real co-pilot, not a chat widget.- **Tutorial · Upload a custom GLB avatar** (`/tutorials/upload-custom-glb`): Bring your own model: any glTF 2.0 .glb from Blender, three.ws Studio, or any other source. Get it validated, fixed, and live.- **Tutorial · Use the <agent-3d> web component end-to-end** (`/tutorials/web-component-end-to-end`): Skip the script tag: drop a real custom element into your DOM, bind attributes, and use the full event lifecycle.diff --git a/data/changelog.json b/data/changelog.jsonindex ecd7ff1fe..2757b8bf0 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-15",+ "title": "Two tutorials stop shipping code samples that quietly do nothing",+ "summary": "An audit of eight developer tutorials found two whose main code sample looked right and silently failed. The custom-skill weather handler split the weather API's reply on a plus sign, but the temperature field arrives with a leading plus of its own, so every field after the condition landed one slot off and the temperature always came back empty; it also mapped the fahrenheit option to a format code that means feels-like rather than Fahrenheit, so the celsius and fahrenheit paths returned the same units. Both are fixed and the sample was run against the live API in both unit modes. The gesture tutorial's AI lane read an emotion-breakdown field the Granite analysis tool has never returned, so the strength check never passed and the agent never played a single animation; it now reads the score and risk flags the tool actually returns, and grades the gesture across four bands instead of a binary. Separately, twelve tutorial hero buttons pointed at anchors on the docs hub that stopped existing when the hub split into per-topic pages, and now open the real pages; a placeholder URL in the Pump.fun tutorial was being parsed as HTML, which broke a link and injected stray elements into the page; and the self-host guide was corrected throughout, including storage variable names that no longer matched the code, a database step that left most tables uncreated, an audit-logging example importing a function that does not exist, a Cloudflare worker setup for a proxy the platform does not run, and a license claim that described the repository as open source when it is not.",+ "tags": [+ "docs",+ "fix"+ ],+ "link": "/tutorials/custom-skill"+ },{"date": "2026-08-15","title": "A shared link to a docs page now opens that page instead of stranding you",diff --git a/prompts/swarm-100/route-agenc-embodied.md b/prompts/swarm-100/route-agenc-embodied.mddeleted file mode 100644index 1642b198c..000000000--- a/prompts/swarm-100/route-agenc-embodied.md+++ /dev/null@@ -1,119 +0,0 @@-# Route audit: /agenc/embodied (AgenC · Embodied)--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. 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==='/agenc/embodied')console.log(JSON.stringify(g,null,2))"--2. Find the serving implementation: grep "/agenc/embodied" 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/agenc/embodied--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: /agenc/embodied ("AgenC · Embodied", section "main").-Declared purpose: Watch two AI agents negotiate and coordinate a task, embodied as 3D characters: the AgenC coordination protocol made visible.--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/agenc/embodied. 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 /agenc/embodied: 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/swarm-100/route-agenc-embodied.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 6dea748c8..b2b901e24 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T07:00:54.005Z",+ "generated_at": "2026-08-15T07:08:10.586Z","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",@@ -125,6 +136,17 @@"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. The prompt art-director note is confirmed accurate and the code comment that contradicted it was fixed.",+ "link": "/docs/3d-api",+ "tags": [+ "fix",+ "docs"+ ]+ },{"date": "2026-08-15","type": "update",@@ -203,6 +225,18 @@"docs"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "The embodied AgenC demo hands you a live task, and reacts to the state a claimed task is actually in",+ "summary": "The /agenc/embodied page binds a 3D agent to a real AgenC task on Solana, and until now it opened on an empty input box: it needed a task account address and offered no way anywhere on the page to find one. It now lists real tasks three.ws itself posted, claimed, and settled on-chain, newest first, so the demo works the moment it loads; a new public read, /api/agenc/recent-tasks, serves that list. Two things it showed were also wrong. The scene coloured itself for a state named Claimed, which the chain has never used: a claimed task is In Progress on-chain, so the halo, the badge, and the per-state animation switch all sat inert through the one transition the demo exists to show. And the page named a program address that no read has touched since the protocol's interface moved; it now shows the program each live read actually ran against. Pasting an address that holds something other than a task used to report a server error, as though the platform were broken, rather than saying no such task exists there; that is now a plain not-found, with the page telling you to check the address or switch cluster. The panel has designed loading, empty, and error states throughout, the form fields have real labels, the layout no longer scrolls sideways on a phone, and a task that cannot be read is retried with a backoff instead of being re-requested every four seconds forever.",+ "link": "/agenc/embodied",+ "tags": [+ "fix",+ "improvement",+ "feature"+ ]+ },{"date": "2026-08-15","type": "update",@@ -282,6 +316,17 @@"docs"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "Two tutorials stop shipping code samples that quietly do nothing",+ "summary": "An audit of eight developer tutorials found two whose main code sample looked right and silently failed. The custom-skill weather handler split the weather API's reply on a plus sign, but the temperature field arrives with a leading plus of its own, so every field after the condition landed one slot off and the temperature always came back empty; it also mapped the fahrenheit option to a format code that means feels-like rather than Fahrenheit, so the celsius and fahrenheit paths returned the same units. Both are fixed and the sample was run against the live API in both unit modes. The gesture tutorial's AI lane read an emotion-breakdown field the Granite analysis tool has never returned, so the strength check never passed and the agent never played a single animation; it now reads the score and risk flags the tool actually returns, and grades the gesture across four bands instead of a binary. Separately, twelve tutorial hero buttons pointed at anchors on the docs hub that stopped existing when the hub split into per-topic pages, and now open the real pages; a placeholder URL in the Pump.fun tutorial was being parsed as HTML, which broke a link and injected stray elements into the page; and the self-host guide was corrected throughout, including storage variable names that no longer matched the code, a database step that left most tables uncreated, an audit-logging example importing a function that does not exist, a Cloudflare worker setup for a proxy the platform does not run, and a license claim that described the repository as open source when it is not.",+ "link": "/tutorials/custom-skill",+ "tags": [+ "docs",+ "fix"+ ]+ },{"date": "2026-08-15","type": "update",@@ -30037,7 +30082,7 @@"date": "2026-05-14","type": "launch","title": "Tutorial · Share your agent (link, QR, social preview)",- "summary": "Get a permanent link to your agent, generate a QR for print, and set the Open Graph preview so it looks good in tweets.",+ "summary": "Get a permanent link to your agent, generate a QR for print, and share the URL that unfurls with its real name, description, and card.","link": "/tutorials/share-your-agent","tags": ["launch"diff --git a/public/changelog.xml b/public/changelog.xmlindex 44117e7cc..bddad8fe7 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -14,6 +14,14 @@<category>fix</category><description>Payment sessions let you hand an agent a budget instead of a key, and two parts of that path judged an endpoint by one rule: if it did not ask for payment, the call was free. That is only true when the endpoint actually succeeded. A paid API answering 404, 400, or 500 was being scored as a free call, and the consequences ran in the wrong direction in both places. The dry run at /pay/simulator, whose whole job is to tell you in advance whether a budget and an allowlist will carry a workload, reported a plan as feasible at a cost of nothing when in fact every endpoint in it was erroring: free calls are never priced, never allowlist-checked, and never counted, so a wall of failures looked like a clean run. And an agent spending through a session got back a success envelope saying no payment was needed for an endpoint that had just failed on it. Both now separate the two cases: a real success with no payment challenge is still free and still costs nothing, while an error status is reported as an endpoint failure carrying the status the endpoint actually returned. No session is charged either way. The simulator lists each failing endpoint by name in its problems list and no longer calls the plan feasible.</description></item>+ <item>+ <title>A shared link to a docs page now opens that page instead of stranding you</title>+ <link>https://three.ws/docs/agent-wallets</link>+ <guid isPermaLink="false">2026-08-15:A shared link to a docs page now opens that page instead of stranding you</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>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.</description>+ </item><item><title>A silent outage in the agent reasoning ledger now reports itself</title><link>https://three.ws/docs/reasoning-ledger</link>@@ -94,6 +102,14 @@<category>docs</category><description>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.</description></item>+ <item>+ <title>The 3D API and agent manifest references now match what the endpoints actually return</title>+ <link>https://three.ws/docs/3d-api</link>+ <guid isPermaLink="false">2026-08-15:The 3D API and agent manifest references now match what the endpoints actually return</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>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. The prompt art-director note is confirmed accurate and the code comment that contradicted it was fixed.</description>+ </item><item><title>The 3D pipeline docs stop telling you to run a command that does not exist</title><link>https://three.ws/docs/3d-pipeline</link>@@ -150,6 +166,14 @@<category>fix</category><description>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. The affected tutorials now use chat="off", the real bare-avatar switch, and note 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.</description></item>+ <item>+ <title>The embodied AgenC demo hands you a live task, and reacts to the state a claimed task is actually in</title>+ <link>https://three.ws/agenc/embodied</link>+ <guid isPermaLink="false">2026-08-15:The embodied AgenC demo hands you a live task, and reacts to the state a claimed task is actually in</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>The /agenc/embodied page binds a 3D agent to a real AgenC task on Solana, and until now it opened on an empty input box: it needed a task account address and offered no way anywhere on the page to find one. It now lists real tasks three.ws itself posted, claimed, and settled on-chain, newest first, so the demo works the moment it loads; a new public read, /api/agenc/recent-tasks, serves that list. Two things it showed were also wrong. The scene coloured itself for a state named Claimed, which the chain has never used: a claimed task is In Progress on-chain, so the halo, the badge, and the per-state animation switch all sat inert through the one transition the demo exists to show. And the page named a program address that no read has touched since the protocol's interface moved; it now shows the program each live read actually ran against. Pasting an address that holds something other than a task used to report a server error, as though the platform were broken, rather than saying no such task exists there; that is now a plain not-found, with the page telling you to check the address or switch cluster. The panel has designed loading, empty, and error states throughout, the form fields have real labels, the layout no longer scrolls sideways on a phone, and a task that cannot be read is retried with a backoff instead of being re-requested every four seconds forever.</description>+ </item><item><title>The guard and gesture tutorials stop teaching steps that fail, and one that wiped your clip list</title><link>https://three.ws/docs/tutorials/write-a-guard</link>@@ -206,6 +230,14 @@<category>fix</category><description>The Vanity page told you to grind a long address yourself in the browser at /vanity, but that path has never existed and answers 404; the in-browser grinder lives at /vanity-wallet, and both links on the page now go there. In Troubleshooting, the fix for a Quick Look model that opens and instantly closes linked to a model-optimization section that is not on the AR page, so the link dropped you at the top with nothing to read; it now opens the section that actually covers it. The same page told you to add a responsive attribute to size an inline embed, with a snippet that set the width in CSS. Neither half worked: responsive sizing is already on by default, and the element reads the width attribute rather than the computed style, so the documented snippet never produced the 3:4 ratio it promised. The instructions now show the form that does work, and name the two things that switch it off.</description></item>+ <item>+ <title>Two tutorials stop shipping code samples that quietly do nothing</title>+ <link>https://three.ws/tutorials/custom-skill</link>+ <guid isPermaLink="false">2026-08-15:Two tutorials stop shipping code samples that quietly do nothing</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>docs</category>+ <description>An audit of eight developer tutorials found two whose main code sample looked right and silently failed. The custom-skill weather handler split the weather API's reply on a plus sign, but the temperature field arrives with a leading plus of its own, so every field after the condition landed one slot off and the temperature always came back empty; it also mapped the fahrenheit option to a format code that means feels-like rather than Fahrenheit, so the celsius and fahrenheit paths returned the same units. Both are fixed and the sample was run against the live API in both unit modes. The gesture tutorial's AI lane read an emotion-breakdown field the Granite analysis tool has never returned, so the strength check never passed and the agent never played a single animation; it now reads the score and risk flags the tool actually returns, and grades the gesture across four bands instead of a binary. Separately, twelve tutorial hero buttons pointed at anchors on the docs hub that stopped existing when the hub split into per-topic pages, and now open the real pages; a placeholder URL in the Pump.fun tutorial was being parsed as HTML, which broke a link and injected stray elements into the page; and the self-host guide was corrected throughout, including storage variable names that no longer matched the code, a database step that left most tables uncreated, an audit-logging example importing a function that does not exist, a Cloudflare worker setup for a proxy the platform does not run, and a license claim that described the repository as open source when it is not.</description>+ </item><item><title>Voice and vision SDKs ship runnable examples, and the x402 seller SDK reads its Solana sponsor from the environment</title><link>https://three.ws/changelog</link>@@ -22996,7 +23028,7 @@<guid isPermaLink="false">2026-05-14:Tutorial · Share your agent (link, QR, social preview)</guid><pubDate>Thu, 14 May 2026 12:00:00 GMT</pubDate><category>launch</category>- <description>Get a permanent link to your agent, generate a QR for print, and set the Open Graph preview so it looks good in tweets.</description>+ <description>Get a permanent link to your agent, generate a QR for print, and share the URL that unfurls with its real name, description, and card.</description></item><item><title>Tutorial · Trigger the agent from page events</title>diff --git a/public/features.json b/public/features.jsonindex 44f9f720f..f71efd95b 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T07:00:53.794Z",+ "generated_at": "2026-08-15T07:08:10.421Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",@@ -6110,7 +6110,7 @@{"path": "/tutorials/share-your-agent","title": "Tutorial · Share your agent (link, QR, social preview)",- "description": "Get a permanent link to your agent, generate a QR for print, and set the Open Graph preview so it looks good in tweets.",+ "description": "Get a permanent link to your agent, generate a QR for print, and share the URL that unfurls with its real name, description, and card.","added": "2026-05-14","auth": null,"indexable": true,