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: correct drifted tutorial steps, API references, and page descriptions across the docs
nirholas79ddedd3c0a5
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 56ab17977..3223d3ecb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,16 +12,19 @@ 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]`- **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]`- **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 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]`- **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 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, 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 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 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]`-- **The smart-contract docs stop describing contracts that are not the ones deployed**: Anyone reading the ERC-8004 contract reference and calling the addresses it lists was working from the wrong interface. Those canonical addresses are upgradeable proxies running the ERC-8004 reference implementation, not the Solidity source in this repository, and the two are not the same contract. Checked with live calls against Base and Base Sepolia: the agent-listing, supply-count and existence-check helpers the page showed all revert, and every function documented for the reputation registry is absent from the registry actually deployed, which exposes a different interface entirely. The page now says which members answer on the deployed addresses and which exist only if you deploy the repository contracts yourself, and its copy-paste examples were rewritten to calls that run. The security page carried the same mistake in its validator section: it told operators to revoke a compromised validator key with a contract call that exists only on the undeployed source, when the deployed registry keeps no validator list at all and containment is key rotation plus filtering by validator address. Alongside those, the sign-language page advertised an npm install for a package the registry has never carried, and its published sign timings and one broken in-page link were corrected; the catalog quality gate page was missing one of the reasons it rejects a model. (`/docs/smart-contracts`) `[docs, fix]`- **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]`+- **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 returned a 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 landed 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 part 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 what does work, and name the two things that switch it off. (`/docs/troubleshooting`) `[fix, docs]`## 2026-08-14diff --git a/STRUCTURE.md b/STRUCTURE.mdindex cc9c98db4..8c1f770e1 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -55,7 +55,7 @@ bottom.| Crypto Data API docs / landing | [pages/crypto.html](pages/crypto.html) `→ /crypto` | In-repo · docs surface | Screenshot-worthy public docs + funnel-top for the free, keyless Crypto Data API (`/api/crypto/*`: token snapshot, security, holders, launches, bonding, whales, symbol, wallet, trending, portfolio, airdrops). Renders hero, endpoint table, tabbed quickstart (curl/JS/Python), per-endpoint request/response reference and a live "Try it" console. Probes production at runtime and marks each endpoint Live vs Coming soon (degrades gracefully while sibling endpoints roll out). CTAs funnel to paid uniques: [/launcher](pages/launcher.html), [/vanity-wallet](public/vanity-wallet.html), [/forge](pages/forge.html). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) || Free Crypto Data API + discovery | [api/crypto/index.js](api/crypto/index.js) `→ /api/crypto`, [api/crypto/openapi.js](api/crypto/openapi.js) `→ /api/crypto/openapi.json`, docs [docs/crypto-api.md](docs/crypto-api.md) `→ /docs/crypto-api` | Live · docs surface | Front door + OpenAPI 3.1 for the free, keyless Crypto Data API. Catalog assembler [api/_lib/crypto-catalog/index.js](api/_lib/crypto-catalog/index.js) merges `api/_lib/crypto-catalog/*.js` self-describing descriptors (currently `airdrops`, `bonding`, `holders`, `launches`, `portfolio`, `security`, `symbol`, `token`, `trending`, `wallet`, `whales`) via a static import barrel (the production source of truth, since Vercel's bundler only ships what static imports reach) plus an additive dev-time directory glob; skips malformed/throwing entries, never throws, valid-empty when zero. New descriptor = drop the file AND add its import line to the barrel. OpenAPI built from the same catalog via [api/_lib/crypto-catalog/openapi.js](api/_lib/crypto-catalog/openapi.js). Index does HTML/JSON content negotiation. Endpoint handlers live in `api/crypto/*.js`. Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) || Unified Crypto API aggregator — storefront + OpenAPI | Registry [api/v1/_providers.js](api/v1/_providers.js) (`providerCatalog()`), front door [api/v1/x/[...slug].js](api/v1/x/%5B...slug%5D.js) `→ /api/v1/x/<provider>/<endpoint>`, discovery `→ GET /api/v1/x`, storefront [pages/crypto-api.html](pages/crypto-api.html) `→ /crypto-api`, OpenAPI 3.1 [api/openapi-json.js](api/openapi-json.js) `→ /openapi.json`, docs § in [docs/api-reference.md](docs/api-reference.md#unified-api--apiv1x-aggregator), dir guide [api/v1/README.md](api/v1/README.md) | Live | Third-party crypto/DeFi/on-chain APIs (CoinGecko, DefiLlama × 2, Jupiter, DexScreener, Solana RPC, OpenAI-compatible) re-offered as one bill: free per-IP tier → BYOK pass-through → three.ws plan → x402 pay-per-call, in that order. Everything (OpenAPI paths, the `/crypto-api` live table, the docs quota table) renders from `providerCatalog()` at request/page-load time — no hand-enumeration, so a new provider descriptor shows up everywhere with zero page edits. Test: [tests/openapi-aggregator.test.js](tests/openapi-aggregator.test.js). Not to be confused with the separate `/api/crypto/*` bundle below (different campaign, different registry). Spec: x402-catalog campaign (retired 2026-07-28; readable in git history) |-| Free 3D API + docs | [api/3d/index.js](api/3d/index.js) `→ /api/3d`, [api/3d/openapi.js](api/3d/openapi.js) `→ /api/3d/openapi.json`, landing page [public/3d.html](public/3d.html) `→ /3d`, reference doc [docs/3d-api.md](docs/3d-api.md) `→ /docs/3d-api` | Live · docs surface | Front door + OpenAPI 3.1 for the free, keyless 3D API. Catalog assembler [api/_lib/3d-catalog/index.js](api/_lib/3d-catalog/index.js) merges `api/_lib/3d-catalog/*.js` descriptors (currently `generate`, `inspect`) via a static import barrel (production source of truth) plus an additive dev-time directory glob; new descriptor = drop the file AND add its barrel import line; skips malformed, never throws; OpenAPI built from the same catalog via [api/_lib/3d-catalog/openapi.js](api/_lib/3d-catalog/openapi.js). Index does HTML/JSON content negotiation and advertises the paid ladder (Forge Pro, Rigged Avatars). Docs page: hero, live endpoint table, runnable quickstart with a live "Run inspect" console, embedded `<model-viewer>` GLB preview, and the free→paid ladder. Free endpoints: [api/3d/generate.js](api/3d/generate.js) (prompt 12), [api/3d/inspect.js](api/3d/inspect.js) (prompt 13). GPT Store Actions surface: [api/3d/studio.js](api/3d/studio.js) `→ /api/3d/studio` — a store-compliant twin of `generate` that strips the x402/upgrade block, drops internal ids, and runs the [api/_mcp-studio/safety.js](api/_mcp-studio/safety.js) age-13+ content gate before any GPU work; backs the "three.ws 3D Studio" custom GPT ([prompts/store-submissions/_generated/openai-actions.yaml](prompts/store-submissions/_generated/openai-actions.yaml) + [openai-gpt-config.md](prompts/store-submissions/_generated/openai-gpt-config.md), store-submission prompt 12). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) |+| Free 3D API + docs | [api/3d/index.js](api/3d/index.js) `→ /api/3d`, [api/3d/openapi.js](api/3d/openapi.js) `→ /api/3d/openapi.json`, landing page [public/3d.html](public/3d.html) `→ /3d`, reference doc [docs/3d-api.md](docs/3d-api.md) `→ /docs/3d-api` | Live · docs surface | Front door + OpenAPI 3.1 for the free, keyless 3D API. Catalog assembler [api/_lib/3d-catalog/index.js](api/_lib/3d-catalog/index.js) merges `api/_lib/3d-catalog/*.js` descriptors (currently `generate`, `inspect`) via a static import barrel (production source of truth) plus an additive dev-time directory glob; new descriptor = drop the file AND add its barrel import line; skips malformed, never throws; OpenAPI built from the same catalog via [api/_lib/3d-catalog/openapi.js](api/_lib/3d-catalog/openapi.js). Index does HTML/JSON content negotiation and advertises the paid ladder (Forge Pro, Rigged Avatars). Docs page: hero, live endpoint table, runnable quickstart with a live "Run inspect" console, embedded `<model-viewer>` GLB preview, and the free→paid ladder. Free endpoints: [api/3d/generate.js](api/3d/generate.js) (prompt 12), [api/3d/inspect.js](api/3d/inspect.js) (prompt 13). GPT Store Actions surface: [api/3d/studio.js](api/3d/studio.js) `→ /api/3d/studio`, a store-compliant twin of `generate` that strips the x402/upgrade block, drops internal ids, and runs the [api/_mcp-studio/safety.js](api/_mcp-studio/safety.js) age-13+ content gate before any GPU work; backs the "three.ws 3D Studio" custom GPT ([prompts/store-submissions/_generated/openai-actions.yaml](prompts/store-submissions/_generated/openai-actions.yaml) + [openai-gpt-config.md](prompts/store-submissions/_generated/openai-gpt-config.md), store-submission prompt 12). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) || Paid Market Data API (x402, 17 endpoints) | Registry [api/_lib/market-data/registry.js](api/_lib/market-data/registry.js), fetchers [api/_lib/market-data/fetch.js](api/_lib/market-data/fetch.js), factory [api/_lib/market-data/endpoint.js](api/_lib/market-data/endpoint.js), routes `api/x402/market-*.js` `→ /api/x402/market-<category>`, free index [api/x402/market.js](api/x402/market.js) `→ /api/x402/market`, catalog projection [api/_lib/service-catalog/services/market-data.js](api/_lib/service-catalog/services/market-data.js), docs [docs/market-data-api.md](docs/market-data-api.md) `→ /docs/market-data-api` | Live | Every free /markets feed (coins, coin profile, price history, categories, exchanges, derivatives, global+Fear&Greed, ETH gas, trending, DeFi TVL, chains, ~15k yield pools, stablecoins, fees/revenue, DEX volumes, hacks) wrapped as pay-per-call x402 endpoints at $0.001 USDC (Solana/Base), plus the $0.005 one-call `market-pulse` bundle. One registry drives the live 402s, the discovery-doc listings, and the free index — zero drift by construction; the fetchers delegate to the SAME exported builders the free pages use (`api/coin/*`, `api/defi/*`), so paid data always matches the site. Params rejected pre-settle (422) and upstream outages (503) never charge the buyer. Tests: [tests/market-data-api.test.js](tests/market-data-api.test.js). || Datapoint fabric (x402, 480k+ endpoints) | Registry [api/_lib/market-data/datapoints.js](api/_lib/market-data/datapoints.js), dynamic route [api/x402/d/[...path].js](api/x402/d/%5B...path%5D.js) `→ /api/x402/d/<family>/<id>/<metric>`, free catalog [api/x402/d/index.js](api/x402/d/index.js) `→ /api/x402/d`, discovery slice `buildDatapointItems` in [api/wk.js](api/wk.js), docs § in [docs/market-data-api.md](docs/market-data-api.md#the-datapoint-fabric--480000-standalone-endpoints) | Live | Every individual market datapoint as its OWN standalone paid endpoint — one URL = one value = one $0.0005 USDC x402 micro-payment (override `X402_PRICE_DATAPOINT_<FAMILY>`). 9 families × 68 metrics × live id spaces ≈ 484k addressable endpoints (~17.5k coins × 20, ~15.5k pools × 7, ~6k protocols × 6, chains, stablecoins, exchanges, global/gas/fear-greed) served by ONE dynamic route reading the registry; ids are runtime values, nothing hardcodes a third-party asset. Path that cannot exist → 404/422 with NO 402 issued; unknown id/outage rejects pre-settle. Free catalog enumerates families, metrics, prices, and pages each family's full live id space (200/page) so crawlers can walk the universe; the .well-known discovery doc carries a curated runtime-derived slice (~83 concrete resources). Tests: [tests/market-datapoints.test.js](tests/market-datapoints.test.js). || Fits: the public cosmetics economy | [pages/fits.html](pages/fits.html) `→ /fits`, page module [src/fits.js](src/fits.js) + pure helpers [src/fits-lib.js](src/fits-lib.js), backends [api/cosmetics/leaderboard.js](api/cosmetics/leaderboard.js) + [api/cosmetics/earnings.js](api/cosmetics/earnings.js), engine [api/_lib/cosmetics-economy.js](api/_lib/cosmetics-economy.js) | Live | The settled-sale cosmetics ledger, promoted out of a panel inside `/play` into a public surface. Rarest premium fits ranked by how few wallets own them (owner count first, rarity as the tie-break, so a legendary never sorts under an equally-scarce rare), top collectors by rarity-weighted flex score, top creators by **actually settled** USDC, and a live sales drip; each fit deep-links to its coin world at `/play?coin=<mint>`. Plus a creator-earnings lookup any wallet can run without an account (lifetime + 30-day, paid vs pending, per-cosmetic and per-coin-world breakdowns), reachable in one click from each creator row rather than by copy-pasting an address. Coin mints are runtime ledger values, never hardcoded. Headline numbers are derived from the same rows rendered beneath them, so they cannot disagree; the volume tile is labelled as the returned sales window, not as an all-time total. Sub-cent sales keep their precision instead of collapsing to $0.00. Tests: [tests/fits-lib.test.js](tests/fits-lib.test.js) |diff --git a/data/pages.json b/data/pages.jsonindex 70182126f..782519042 100644--- a/data/pages.json+++ b/data/pages.json@@ -4680,7 +4680,7 @@{"path": "/tutorials/customize-appearance","title": "Tutorial · Customize size, position & background",- "description": "Tune every visible knob: bubble size, corner placement, background, rotation speed: entirely through data-* attributes.",+ "description": "Tune every visible knob on the <agent-3d> element: layout mode, corner placement, size, background, camera framing, and the ambient clip.","priority": 0.8,"changefreq": "monthly","added": "2026-05-14"@@ -4688,7 +4688,7 @@{"path": "/tutorials/swap-avatar-in-studio","title": "Tutorial · Pick & swap an avatar in Studio",- "description": "Visually browse the avatar gallery, switch bodies with one click, and have the change ripple to every embed without redeploying.",+ "description": "Swap an agent's 3D body from the Outfit panel in one click, and have the change reach every embed without touching your snippet.","priority": 0.8,"changefreq": "monthly","added": "2026-05-14"@@ -4696,7 +4696,7 @@{"path": "/tutorials/greeting-and-first-speech","title": "Tutorial · Add a greeting & first speech line",- "description": "Make your agent say hello the moment it loads: and have its mouth move with the words.",+ "description": "Make your agent say hello the moment it loads, and have its mouth move with the words.","priority": 0.8,"changefreq": "monthly","added": "2026-05-14"@@ -4712,7 +4712,7 @@{"path": "/tutorials/selfie-to-avatar","title": "Tutorial · Turn a selfie into a 3D avatar",- "description": "Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk: then put it on an agent.",+ "description": "Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk, then put it on an agent.","priority": 0.8,"changefreq": "monthly","added": "2026-06-21"@@ -4720,7 +4720,7 @@{"path": "/tutorials/view-in-ar","title": "Tutorial · View your 3D model in AR",- "description": "See any three.ws model in augmented reality and walk around it in your kitchen: straight from the browser, no app to install. iOS Quick Look and Android WebXR.",+ "description": "See any three.ws model in augmented reality and walk around it in your kitchen, straight from the browser with no app to install. iOS Quick Look, Android Scene Viewer, and WebXR.","priority": 0.8,"changefreq": "monthly","added": "2026-06-13"diff --git a/docs/3d-api.md b/docs/3d-api.mdindex 8359f2cef..8ffbc0b51 100644--- a/docs/3d-api.md+++ b/docs/3d-api.md@@ -10,7 +10,9 @@ Base URL: `https://three.ws`> This page documents the **free** 3D endpoints. Higher-quality generation and> rigging are paid: **Forge Pro** (quality tiers) at [`/api/x402/forge`](https://three.ws/api/x402/forge)-> and **Rigged Avatars** (animation-ready skeletons) via [`/api/forge?action=rig`](https://three.ws/api/forge).+> and **Rigged Avatars** (animation-ready skeletons) via `POST /api/forge?action=rig`+> (POST only, so there is nothing to open in a browser; the catalog link above+> quotes both).Prefer a browsable landing page? See [three.ws/3d](https://three.ws/3d) — hero,live endpoint table, a runnable inspection console, an embedded 3D viewer, and the@@ -126,9 +128,9 @@ model comes straight back:```json{"status": "done",- "glbUrl": "https://three.ws/cdn/forge/anon/a1b2c3d4.glb",- "viewerUrl": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2Fforge%2Fanon%2Fa1b2c3d4.glb",- "arUrl": "https://three.ws/api/ar?src=https%3A%2F%2Fthree.ws%2Fcdn%2Fforge%2Fanon%2Fa1b2c3d4.glb&title=a%20small%20ceramic%20robot%20figurine",+ "glbUrl": "https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/forge/40659d6097b0/0a527906-a087-45b7-afd4-8d401495787b.glb",+ "viewerUrl": "https://three.ws/viewer?src=https%3A%2F%2Fpub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev%2Fforge%2F40659d6097b0%2F0a527906-a087-45b7-afd4-8d401495787b.glb",+ "arUrl": "https://three.ws/api/ar?src=https%3A%2F%2Fpub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev%2Fforge%2F40659d6097b0%2F0a527906-a087-45b7-afd4-8d401495787b.glb&title=a%20small%20ceramic%20robot%20figurine","format": "glb","tier": "draft","free": true,@@ -136,6 +138,22 @@ model comes straight back:}```+**Treat `glbUrl` as opaque.** It is a fully-qualified URL on the object store, not+a path you can build yourself: the host comes from deployment config and the key+is assigned per generation. Follow the URL you were handed and pass it verbatim+into `viewerUrl` / `arUrl` style links rather than reconstructing one.++Server-side and CLI downloads (`curl -O`, a worker fetching bytes) can use+`glbUrl` directly. **Browser code on another origin should not**: the object+store answers without CORS headers and is rate-limited for bursts. Swap the host+for the first-party CDN instead, which serves the identical object with+`Access-Control-Allow-Origin: *` and a long edge cache:++```js+// https://<object-store>/forge/<hash>/<id>.glb → https://three.ws/cdn/forge/<hash>/<id>.glb+const browserUrl = 'https://three.ws/cdn/' + new URL(glbUrl).pathname.replace(/^\//, '');+```+`arUrl` is the place-in-your-room link (`/api/ar`): opened on a phone itlaunches AR directly — Scene Viewer on Android, Quick Look on iOS (GLB→USDZconverted in-page) — and on desktop it falls back to the interactive viewer.@@ -179,7 +197,7 @@ GET /api/3d/generate?job=f1.eyJwIjoibnZpZGlh...&title=a%20small%20ceramic%20robo{ "status": "pending", "job": "f1...", "poll": "/api/3d/generate?job=f1...&title=...", "retryAfter": 3 }// ready-{ "status": "done", "job": "f1...", "glbUrl": "https://three.ws/cdn/forge/anon/done.glb",+{ "status": "done", "job": "f1...", "glbUrl": "https://<object-store>/forge/<hash>/<id>.glb","viewerUrl": "https://three.ws/viewer?src=...", "arUrl": "https://three.ws/api/ar?src=...&title=...","format": "glb", "tier": "draft", "free": true }@@ -212,11 +230,11 @@ curl -s -X POST https://three.ws/api/3d/generate \# → { "status": "pending", "job": "f1...", "poll": "/api/3d/generate?job=f1..." }# (or { "status": "done", "glbUrl": "..." } if it finished inline)-# 2. Poll until done, then download the GLB+# 2. Poll until done, then download the GLB at the glbUrl you were handedcurl -s 'https://three.ws/api/3d/generate?job=f1...'-# → { "status": "done", "glbUrl": "https://three.ws/cdn/forge/anon/....glb", ... }+# → { "status": "done", "glbUrl": "https://<object-store>/forge/<hash>/<id>.glb", ... }-curl -sL -o model.glb 'https://three.ws/cdn/forge/anon/....glb'+curl -sL -o model.glb '<the glbUrl from step 2>'```The `glbUrl` is a real, durable GLB — open `viewerUrl` in a browser to inspect it,@@ -301,11 +319,14 @@ to create, no monthly plan, no key to provision — just one USDC payment per mo### Quality tiers-| Tier | Price (USDC) | Geometry | Textures | Best for |-|------------|--------------|---------------------|-----------------|-----------------------------------|-| `draft` | **$0.05** | ~12k tris, low-poly | none | Blockout, iteration, previews |-| `standard` | **$0.15** | ~30k tris, balanced | none | The default for most assets |-| `high` | **$0.50** | ~200k tris, max | **PBR + HD** | Hero assets, product/NFT renders |+| Tier | Price (USDC) | Geometry | Textures | Best for |+|------------|--------------|---------------------|---------------------|-----------------------------------|+| `draft` | **$0.05** | ~12k tris, low-poly | baked, 1K | Blockout, iteration, previews |+| `standard` | **$0.15** | ~30k tris, balanced | baked, 2K | The default for most assets |+| `high` | **$0.50** | ~200k tris, max | **PBR + HD**, 4K | Hero assets, product/NFT renders |++Every tier ships a textured mesh; the ladder is bake resolution plus, at `high`,+full PBR material channels rather than a single baked colour map.Prices are the flat per-call retail price and are the single source of truth in[`api/_lib/forge-tiers.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/forge-tiers.js);@@ -352,7 +373,7 @@ tier at deploy time without touching settlement.```bashcurl -s 'https://three.ws/api/forge?job=f1.eyJ…'- # → { "status": "done", "glb_url": "https://three.ws/cdn/forge/…/model.glb", … }+ # → { "status": "done", "glb_url": "https://<object-store>/forge/<hash>/<id>.glb", … }```A draft prompt often finishes inside the submit window and comes back inline with@@ -414,9 +435,8 @@ re-validated per hop.{"url": "https://three.ws/avatars/cesium-man.glb","valid": true,- "sizeBytes": 495956,"stats": {- "vertices": 3272,+ "vertices": 3273,"triangles": 4672,"materials": 1,"textures": 1,@@ -427,9 +447,13 @@ re-validated per hop."scenes": 1,"skins": 1,"joints": 19,+ "indexedPrimitives": 1,+ "nonIndexedPrimitives": 0,+ "extensionsRequired": [],"container": "glb",- "generator": "COLLADA2GLTF"+ "generator": "glTF-Transform v4.4.0"},+ "sizeBytes": 438044,"recommendations": [{"severity": "info",@@ -437,14 +461,35 @@ re-validated per hop."fix": "No action needed — the model is already well-suited for web delivery."}],- "validation": { "valid": true, "numErrors": 0, "numWarnings": 0, "numInfos": 0, "numHints": 0 },- "ts": "2026-07-07T00:00:00.000Z"+ "validation": {+ "valid": true,+ "validatorVersion": "2.0.0-dev.3.10",+ "numErrors": 0,+ "numWarnings": 1,+ "numInfos": 0,+ "numHints": 0,+ "issues": [+ {+ "code": "NODE_SKINNED_MESH_NON_ROOT",+ "message": "Node with a skinned mesh is not root. Parent transforms will not affect a skinned mesh.",+ "severity": "warning",+ "pointer": "/nodes/2"+ }+ ],+ "truncated": false+ },+ "ts": "2026-08-15T06:37:05.768Z"}```+That is the verbatim response for the URL in the curl block below, so you can+diff your own call against it.+`recommendations` is ordered **most severe first** (`critical` → `warn` →-`info`); each item is a `{ severity, issue, fix }` triple — the problem and the-concrete action. `valid` reflects the glTF-Validator's error count.+`info`); each item is a `{ severity, issue, fix }` triple: the problem and the+concrete action. `valid` reflects the glTF-Validator's error count, so a model+can be `valid: true` and still carry warnings, as this one does. `validation.issues`+carries those individual findings (`truncated` says whether the list was cut).### curldiff --git a/docs/agenc.md b/docs/agenc.mdindex 46089d154..3adf06bc4 100644--- a/docs/agenc.md+++ b/docs/agenc.md@@ -23,6 +23,7 @@ work is posted, and how a task moves from posted → claimed → completed.| Endpoint | Method | Returns ||---|---|---|| `/api/agenc/list-tasks?creator=<base58>&cluster=devnet` | GET | Task PDAs for a creator. |+| `/api/agenc/recent-tasks?cluster=devnet[&limit=6]` | GET | The newest task PDAs three.ws itself wrote on-chain, from the platform's own journal. || `/api/agenc/get-task?taskPda=<base58>&cluster=devnet[&lifecycle=1]` | GET | Task state, optionally with lifecycle events. || `/api/agenc/get-task?creator=<base58>&taskId=<hex\|label>&cluster=devnet` | GET | Same, addressed by creator + task id. || `/api/agenc/get-agent?agentPda=<base58>&cluster=devnet` | GET | Agent registry record. |@@ -34,6 +35,51 @@ when unused. Both `devnet` and `mainnet` clusters are addressable via `cluster`.`cluster` defaults to `mainnet`; note the AgenC program's populated deployment ison **devnet** today, so a mainnet read of a real task normally returns `not_found`.+### Finding a task to read++`list-tasks` can only answer once you already know a creator wallet, which is no+help to a client holding nothing. `recent-tasks` closes that gap: it returns the+task PDAs three.ws has posted, claimed, or settled through the [Agora](agora.md)+rail, newest first, read from the platform's own journal rather than the chain+(one DB query, no `getProgramAccounts` scan, so it answers in milliseconds).++```bash+curl -s 'https://three.ws/api/agenc/recent-tasks?cluster=devnet&limit=3'+```++```json+{+ "ok": true,+ "cluster": "devnet",+ "count": 3,+ "degraded": false,+ "tasks": [+ { "taskPda": "4TyX1R7t7m…6gpR", "lastActivityAt": "2026-08-06T05:53:35.045Z",+ "rewardLabel": "0.002 SOL", "kinds": ["claimed_task", "completed_task", "earned"] }+ ]+}+```++It is a pointer list, not a source of truth: the journal records what three.ws+wrote, so verify anything you act on with `get-task`, which reads the chain.+`degraded: true` with an empty `tasks` array means the journal was unreachable+and the chain reads are unaffected. [`/agenc/embodied`](https://three.ws/agenc/embodied)+uses this endpoint to offer live tasks to a visitor who has no address in hand.++### Task states++`state` is AgenC's on-chain `TaskState` enum, verbatim. There are six, and the+labels are exactly these strings (two of them contain a space):++`Open` · `In Progress` · `Pending Validation` · `Completed` · `Cancelled` ·+`Disputed`++There is no `Claimed` and no `Expired`: a claim moves a task to `In Progress`, and+a lapsed deadline leaves it `Open` until its creator cancels. Client code that+keys on state (a color map, an animation switch, a CSS class) must use these+strings. Note that `class="state-In Progress"` is not one class name but two, so+match on a data attribute (`[data-state='In Progress']`) instead.+`x402-services` is the odd one out: it reads the x402 Bazaar rather than the chain,and returns each discovered endpoint with a deterministic `taskIdSeed` so the sameservice always maps to the same AgenC task PDA when someone posts it. `maxPrice` is@@ -44,7 +90,7 @@ an atomic amount (`10000` = 0.01 USDC), not a decimal.| Status | Body `error` | Meaning ||---|---|---|| 400 | `validation_error` | A missing or malformed parameter; the message names it. |-| 404 | `not_found` | Unknown action, or the PDA holds no such task/agent on that cluster. |+| 404 | `not_found` | Unknown action, or the PDA holds no such task/agent on that cluster. An address that holds some *other* account decodes as a discriminator mismatch and is reported here too, not as a 500. || 405 | `method_not_allowed` | Wrong verb (the reads are GET, `link` is POST). || 429 | `rate_limited` | Per-IP limit; retry after the window in the response. || 502 | `facilitator_error` | `x402-services` only: every Bazaar facilitator failed. |diff --git a/docs/agent-economy-volume.md b/docs/agent-economy-volume.mdindex 2335dce9b..31faed8fd 100644--- a/docs/agent-economy-volume.md+++ b/docs/agent-economy-volume.md@@ -222,9 +222,11 @@ page shows it as a star figure next to the hire count.`hirer_agent_id` and ordered by `spent_usd` descending.Both leaderboards respect agent privacy: `url` is `null` when the agent's-identity is not public, which makes the page render an unlinked row, and+identity is not public *or* no longer exists (a deleted agent leaves no identity+row to link to), which makes the page render an unlinked row, and`avatar_thumbnail_url` is populated only when the linked avatar's visibility is-`public` or `unlisted`. A row with no avatar renders initials instead.+`public` or `unlisted`. A row with no avatar renders initials instead, and so+does a row whose stored thumbnail has since been pruned.**`recent[]`**: the latest completed hires ordered by `completed_at` descending,with the skill, the amount, the network, and the settlement signature.diff --git a/docs/agent-manifest.md b/docs/agent-manifest.mdindex a16aa06ad..fbf0b1fcc 100644--- a/docs/agent-manifest.md+++ b/docs/agent-manifest.md@@ -58,12 +58,15 @@ import { loadManifest, normalize } from 'https://three.ws/agent-3d/1.5.2/agent-3// One call for every source form the element accepts: agent:// (resolved// through the ERC-8004 registry on the named chain), ipfs://, ar://, and// plain HTTPS.-const manifest = await loadManifest('https://cdn.acme.com/aria/manifest.json');+// Any live agent on the platform serves one, so this runs as written:+const manifest = await loadManifest(+ 'https://three.ws/api/agents/27a0f649-3b59-4552-bb0b-faf616ac448b/manifest',+);console.log(manifest.name, manifest.body.uri);```-`loadManifest` returns the manifest already normalized: it stamps `_baseURI` with the URL it fetched from, so relative paths (`instructions.md`, `skills/wave/`, `memory/MEMORY.md`) resolve correctly, and it adapts an ERC-8004 registration JSON into this manifest shape when that is what the URI serves. Call `fetchRelative(manifest, 'instructions.md')` to pull a bundle file. If you already hold the parsed JSON, `normalize(json, { baseURI })` does the shape work alone.+`loadManifest` returns the manifest already normalized. It records the directory the manifest was fetched from in `_baseURI`, which is what makes the bundle's relative paths (`instructions.md`, `skills/wave/`, `memory/MEMORY.md`) resolvable, and it adapts an ERC-8004 registration JSON into this manifest shape when that is what the URI serves. Call `fetchRelative(manifest, 'instructions.md')` to pull a bundle file against that base. If you already hold the parsed JSON, `normalize(json, { baseURI })` does the shape work alone.> `@three-ws/avatar-schema` is **not** the validator for this document. It> validates the *avatar* manifest (`avatar.v1.json`: `schemaVersion`, `mesh`,diff --git a/docs/avatar-cli.md b/docs/avatar-cli.mdindex 32bc815c7..828592b76 100644--- a/docs/avatar-cli.md+++ b/docs/avatar-cli.md@@ -20,7 +20,7 @@ three-ws-avatar --version``````-0.2.1+0.2.0```Or run it without installing. The package has exactly one binary, so `npx` resolves it directly:@@ -32,7 +32,7 @@ npx @three-ws/avatar-cli --versionPin the version in anything automated so a future release cannot change your build's behavior:```bash-npx @three-ws/[email protected] validate manifest.json+npx @three-ws/[email protected] validate manifest.json```Node 18 or newer. The CLI has one runtime dependency, `@three-ws/avatar-schema`, which carries the JSON Schema it validates against.@@ -89,7 +89,7 @@ three-ws-avatar init --owner <id> --name <name> --mesh <path> [options]| Flag | Required | Description ||---|---|---|-| `--owner <caip10\|0x…>` | yes | Owner identity. Full CAIP-10 (`eip155:1:0xabc…`) or a bare `0x…` address, which is assumed to be `eip155:1`. |+| `--owner <caip10\|sol\|0x…>` | yes | Owner identity. Full CAIP-10 (`eip155:1:0xabc…`), a bare Solana address, which is assumed to be `solana:mainnet-beta`, or a bare `0x…` address, which is assumed to be `eip155:1`. || `--name <string>` | yes | Display name. If it looks like a name service handle (`nick.eth`, `nick.ws`, `nick.sol`) it also becomes the manifest `id`. || `--mesh <path>` | yes | Path to a `.glb`, `.gltf`, or `.vrm` file. Must exist; the extension decides `mesh.format`. || `--skeleton <name>` | no | One of `avaturn`, `mixamo`, `rpm`, `vrm-humanoid`, `custom`. Default `avaturn`. |diff --git a/docs/changelog.md b/docs/changelog.mdindex 6723d7ef6..a98d11ee7 100644--- a/docs/changelog.md+++ b/docs/changelog.md@@ -303,7 +303,7 @@ For contributors and maintainers. A release follows these steps:5. A GitHub Release is created from the tag with the changelog entry as the body.6. `npm run build:all` produces the platform bundle and the CDN library build.7. `npm run publish:lib` copies the CDN bundle into `dist/agent-3d/{version}/`, generates an `integrity.json` sidecar with SHA-384 hashes, updates the rolling channel aliases (`1.5`, `1`, `latest`), and writes a `versions.json` manifest.-8. The image is deployed to Google Cloud Run with `npm run deploy:gcp:full`, which serves the updated `dist/` directory — including the CDN library build — from the `three-ws-api` service. That one command runs the full `build:gcp` chain and then `deploy:gcp`; a bare `npm run build` is not enough on its own, because the deploy gate checks `dist/` for the UMD library that `build:lib:full` and `publish:lib` put there.+8. The image is deployed to Google Cloud Run with `npm run deploy:gcp:full`, which serves the updated `dist/` directory (including the CDN library build) from the `three-ws-api` service. That one command runs the full `build:gcp` chain and then `deploy:gcp`; a bare `npm run build` is not enough on its own, because the deploy gate checks `dist/` for the UMD library that `build:lib:full` and `publish:lib` put there.The SDK (`@three-ws/sdk`) is published to npm separately:diff --git a/docs/github-memory-seeding.md b/docs/github-memory-seeding.mdindex 959294bc1..564b17495 100644--- a/docs/github-memory-seeding.md+++ b/docs/github-memory-seeding.md@@ -134,7 +134,12 @@ unaffected: no other feature depends on these variables.## APIAll three calls are owner-only: the session (or bearer) user must own the-agent. Browser mutations carry the standard CSRF token.+agent. The two mutations (POST and DELETE) additionally require the standard+CSRF token in `x-csrf-token` when the caller authenticates with a session+cookie: without it they answer `403 csrf_missing` and change nothing. Bearer+callers are exempt, because a bearer token is not attached automatically by a+browser the way a cookie is. Mint one from `GET /api/csrf-token`; the shared+front-end client attaches it for you.### `GET /api/agents/:id/memory/seed/github`@@ -207,13 +212,21 @@ with the connection row itself, and then asks GitHub to revoke the OAuth grant| Code | HTTP | Meaning ||---|---|---|| `unauthorized` | 401 | Sign-in required |+| `csrf_missing` / `csrf_invalid` | 403 | A cookie-authenticated POST or DELETE arrived without a valid `x-csrf-token` || `not_found` | 404 | No such agent, or it is not yours (a malformed id also answers 404, never a 500) || `not_connected` | 412 | Connect GitHub first; the response carries `connect_url` || `invalid_selection` | 400 | A selected key is not in the catalog you were shown; `rejected` names each one || `empty_selection` | 400 | Pick your profile or at least one repository || `distill_error` | 502 | The selected material yielded no usable facts; add a README or another repository |+| `distill_unavailable` | 503 | Every model provider was busy, so nothing was read into memory and the existing memories are untouched. Carries `retry_at` (when this agent's next seed is allowed) and `providers_tried` || rate limited | 429 | One seed per agent per 6 hours |+Only `distill_error` and `distill_unavailable` are reachable after the seed+budget has been charged: the budget is taken once the selection is known good,+immediately before the README reads and the distilling pass. Every other+refusal above happens before that point and leaves your window intact, so a+mistyped or stale pick costs you nothing but the retry.+## Source| Piece | File |diff --git a/docs/market-data-api.md b/docs/market-data-api.mdindex 8ed927378..0e4cfc6f3 100644--- a/docs/market-data-api.md+++ b/docs/market-data-api.md@@ -4,7 +4,7 @@ The same live market data behind every three.ws `/markets` page — coin prices,- **Free index (start here):** [`GET /api/x402/market`](https://three.ws/api/x402/market): lists every paid `market-*` endpoint with its live price, params, and a runnable example, including the `market-heatmap` and `market-mood` siblings below- **Discovery:** every endpoint is listed in [`/.well-known/x402.json`](https://three.ws/.well-known/x402.json), so x402scan, agentic.market, and CDP Bazaar crawlers index it automatically-- **Pricing:** $0.001 USDC per call for every category; the `market-pulse` bundle is $0.005+- **Pricing:** $0.001 USDC per call for every category endpoint in the table below; the `market-pulse` bundle is $0.005, and the `market-heatmap` / `market-mood` composites are $0.002- **Rails:** x402 v2, `exact` scheme — USDC on Solana mainnet or Base mainnet## Why pay when the pages are free?@@ -37,7 +37,7 @@ Full per-endpoint parameter docs are in the free index (`/api/x402/market`) and## The datapoint fabric — 1,000,000+ standalone endpoints-Beyond the 17 category endpoints, **every individual datapoint is its own paid endpoint**: one URL, one value, one micro-payment. The fabric at `/api/x402/d/<family>/<id>/<metric>` makes every (family, id, metric) triple individually addressable — ~17,500 coins × 20 metrics, ~15,500 yield pools × 7, ~6,000 protocols × 6, **per-contract token market + security for any Solana mint or EVM address** (10 + 6 metrics, unbounded), plus chains, stablecoins, exchanges, categories, DEXs, fees/revenue, derivative venues, and the no-id global/gas/fear-greed families. **$0.0005 USDC per datapoint** (override per family with `X402_PRICE_DATAPOINT_<FAMILY>`).+Beyond the 17 category endpoints, **every individual datapoint is its own paid endpoint**: one URL, one value, one micro-payment. The fabric at `/api/x402/d/<family>/<id>/<metric>` makes every (family, id, metric) triple individually addressable: ~17,000 coins × 20 metrics, ~15,000 yield pools × 7, ~6,000 protocols × 6, **per-contract token market + security for any Solana mint or EVM address** (10 + 6 metrics, unbounded), plus chains, stablecoins, exchanges, categories, DEXs, fees/revenue, derivative venues, and the no-id global/gas/fear-greed families. The free catalog reports the live total as `endpoint_count_approx` (1,126,963 across 15 families at the time of writing); that field is the source of truth, not this paragraph. **$0.0005 USDC per datapoint** (override per family with `X402_PRICE_DATAPOINT_<FAMILY>`).```bash# Free catalog: families, metrics, prices, live endpoint countdiff --git a/docs/mcp-safety.md b/docs/mcp-safety.mdindex 3fb6c3662..ece12d7d3 100644--- a/docs/mcp-safety.md+++ b/docs/mcp-safety.md@@ -170,11 +170,20 @@ Refetch it rather than pinning a copy. Tools get added; a policy fetched at builtime goes stale, and a stale allowlist is how a new mutating tool ends up trustedby an old config.-> Six tool names are published by two different servers (`sns_resolve`,+> Nine tool names are published by two different servers (`sns_resolve`,> `find_services`, `pay_and_call`, `list_animations`, `render_avatar`,-> `kol_leaderboard`). The namespaced `mcp__<server>__<tool>` id is the key, not+> `kol_leaderboard`, `create_agent_persona`, `get_agent_persona`, `persona_say`).+> The namespaced `mcp__<server>__<tool>` id is the key, not> the bare name. The `<server>` segment is the name **you** gave that server in> your own client config; the policy uses the id three.ws publishes for it.+>+> That list grows as servers are added, so re-derive it rather than trusting the+> names above:+>+> ```bash+> curl -s https://three.ws/mcp-catalog.json \+> | jq -r '.tools | group_by(.name)[] | select(length > 1) | .[0].name'+> ```---diff --git a/docs/package-extraction.md b/docs/package-extraction.mdindex fbf46211a..8e9b0da26 100644--- a/docs/package-extraction.md+++ b/docs/package-extraction.md@@ -1,4 +1,4 @@-# Package extraction — breaking the monorepo into standalone repos+# Package extraction: breaking the monorepo into standalone reposWe are graduating the reusable packages out of the `three.ws` monorepo into theirown GitHub repos that publish to npm (or, for the VS Code extension, the@@ -6,7 +6,7 @@ Marketplace) independently. This is the playbook. **We start with the x402 famil## Why-The x402 packages (`@three-ws/x402-*`) are general-purpose — a buyer-side fetch+The x402 packages (`@three-ws/x402-*`) are general-purpose: a buyer-side fetchwrapper, a seller-side core, MCP servers, payment modals. They are useful farbeyond three.ws, they version on their own cadence, and bundling them in a 60+directory monorepo hides their issue tracker, inflates clone size, and couples@@ -15,7 +15,7 @@ their releases to unrelated platform commits. Standalone repos fix all four.## Decisions (locked)- **One repo per package** (polyrepo), not a shared x402 monorepo.-- **History preserved** via `git filter-repo --subdirectory-filter` — blame and+- **History preserved** via `git filter-repo --subdirectory-filter`, so blame andauthorship carry across.- **Scope/owner unchanged**: keep publishing as `@three-ws/*`, host under`github.com/nirholas`. No renames, no broken installs.@@ -45,38 +45,48 @@ monorepo first, then extract.All seven extract cleanly with full history. Six are npm packages already liveunder `@three-ws/*`; `vscode-x402` targets the VS Code Marketplace.+Versions move, so read this table as a snapshot and re-derive it before a+release: `npm view <pkg> version` for the live column, the package's own+`package.json` for the local one. Measured 2026-08-15.+| Package | Monorepo path | npm (live) | Local ver | Build | Tests | Notes ||---|---|---|---|---|---|---|-| `@three-ws/x402-fetch` | `packages/x402-fetch` | 1.0.1 | 1.0.1 | vite | 7 pass | buyer-side fetch wrapper |-| `@three-ws/x402-server` | `packages/x402-server` | 0.1.0 | 0.1.0 | — | pass | seller-side core |-| `@three-ws/x402-mcp` | `packages/x402-mcp` | 0.2.0 | 0.2.0 | ✓ | pass | MCP server |-| `@three-ws/ibm-x402-mcp` | `packages/ibm-x402-mcp` | 1.1.0 | 1.1.0 | ✓ | pass | IBM MCP variant |-| `@three-ws/x402-modal` | `x402-modal-sdk` | 0.2.0 | 0.2.0 | esbuild | pass | payment modal SDK |-| `@three-ws/x402-payment-modal` | `x402-payment-modal` | 1.1.0 | **1.2.0** | esbuild | 14 pass | publishes 1.2.0 (deps fixed — see below) |-| `@three-ws/vscode-x402` | `packages/vscode-x402` | — | 0.1.0 | esbuild | — | **Marketplace**, not npm; needs name/publisher fix |+| `@three-ws/x402-fetch` | `packages/x402-fetch` | 1.0.2 | **1.0.3** | vite | 7 pass | buyer-side fetch wrapper |+| `@three-ws/x402-server` | `packages/x402-server` | 0.1.2 | 0.1.2 | none | 24 pass | seller-side core |+| `@three-ws/x402-mcp` | `packages/x402-mcp` | 0.2.1 | **0.2.2** | none | 10 pass | MCP server |+| `@three-ws/ibm-x402-mcp` | `packages/ibm-x402-mcp` | 1.1.2 | **1.1.3** | none | 37 pass | IBM MCP variant |+| `@three-ws/x402-modal` | `x402-modal-sdk` | 0.2.1 | **0.3.0** | esbuild | 24 pass | payment modal SDK |+| `@three-ws/x402-payment-modal` | `x402-payment-modal` | 1.2.0 | **1.2.1** | esbuild | 20 pass, 2 skipped | deps fixed, see below |+| `@three-ws/vscode-x402` | `packages/vscode-x402` | not published | 0.2.0 | esbuild | none | **Marketplace**, not npm; needs a name fix |++A bolded local version is ahead of npm and publishes on its next tag. The two+MCP packages ship their sources directly and have no build step, so "none" in+that column is correct rather than missing.### Fixes the split surfaced (already applied to the monorepo)- **`x402-payment-modal/build.mjs`** imported esbuild via a hardcoded- `../node_modules/esbuild/lib/main.js` — coupled to the monorepo's hoisted- layout, broken in a standalone repo. Changed to a bare `import 'esbuild'`,- which resolves in both.+ `../node_modules/esbuild/lib/main.js`, coupling it to the monorepo's hoisted+ layout and breaking it in a standalone repo. Changed to a bare+ `import 'esbuild'`, which resolves in both.- **`x402-payment-modal/package.json`** shipped a `server/` adapter importing`@solana/web3.js`, `@solana/spl-token`, and `express` with **zero declared- dependencies** — the published package was broken for anyone using the server- subpath. Added them as optional `peerDependencies` (keeps the browser install- lean) plus the Solana pair as `devDependencies` so tests/CI run.+ dependencies**, so the published package was broken for anyone using the+ server subpath. Added them as optional `peerDependencies` (keeps the browser+ install lean) plus the Solana pair as `devDependencies` so tests run.-### vscode-x402 — extra step before Marketplace publish+### vscode-x402: extra step before Marketplace publish-VS Code extensions cannot use a scoped `name`. Before `vsce publish`:+VS Code extensions cannot use a scoped `name`, and the package is still named+`@three-ws/vscode-x402`. Before `vsce publish`:-- set `name` to a plain id (e.g. `vscode-x402`),-- add a `publisher` field matching a registered Marketplace publisher,-- the CI workflow already uses `vsce publish` + `ovsx publish` (Open VSX) and- expects `VSCE_PAT` / `OVSX_PAT` secrets.+- set `name` to a plain id (e.g. `vscode-x402`); this is the one blocker left,+- the `publisher` field is already set to `three-ws`, which must match a+ registered Marketplace publisher,+- the extracted repo's publish workflow already uses `vsce publish` ++ `ovsx publish` (Open VSX) and expects `VSCE_PAT` / `OVSX_PAT` secrets.-## Owner handoff — the two steps that need credentials+## Owner handoff: the two steps that need credentialsEverything up to the GitHub/npm boundary is automated and verified. The final twosteps need the owner's credentials and cannot run from a collaborator session:@@ -96,17 +106,17 @@ steps need the owner's credentials and cannot run from a collaborator session:x402-payment-modal x402-payment-modalPKGS```- (`vscode-x402` is handled separately — see the Marketplace note above.)+ (`vscode-x402` is handled separately: see the Marketplace note above.)2. **Set the publish-token secret** on each new repo so its workflow canauthenticate to npm (`NPM_TOKEN`) or the Marketplace (`VSCE_PAT`/`OVSX_PAT`).-Already-published versions (e.g. x402-fetch 1.0.1) republish only after a version-bump — the workflow tags and publishes the version in `package.json`, so bump it-when there's something new to ship. `x402-payment-modal` is at an unpublished-1.2.0 and will publish on first tag.+Already-published versions republish only after a version bump: the workflow tags+and publishes the version in `package.json`, so bump it when there's something+new to ship. Five of the six npm packages currently sit one version ahead of the+registry (the bolded local versions above) and publish on their next tag.## After a package is extractedThe monorepo copy can stay (the platform still imports it locally) or be replacedwith the published dependency. That cutover is tracked per-package and is **not**-part of the extraction itself — extract and publish first, swap the import later.+part of the extraction itself: extract and publish first, swap the import later.diff --git a/docs/rig-doctor.md b/docs/rig-doctor.mdindex 33e1c06c8..cb36478ad 100644--- a/docs/rig-doctor.md+++ b/docs/rig-doctor.md@@ -216,7 +216,7 @@ if (report.verdict.level === 'fail') {Every sample rig is linkable, which is how the failure states in this document can be checked against a live page rather than taken on faith:- [A Mixamo rig that fully animates](https://three.ws/rig-doctor?sample=/avatars/michelle.glb)-- [A halfbody avatar with frozen legs](https://three.ws/rig-doctor?sample=/avatars/realistic-halfbody.glb)+- [A halfbody avatar with frozen arms and legs](https://three.ws/rig-doctor?sample=/avatars/realistic-halfbody.glb)- [A skinned but non-humanoid rig](https://three.ws/rig-doctor?sample=/avatars/fox.glb)- [A static mesh with no skeleton](https://three.ws/rig-doctor?sample=/avatars/mannequin.glb)diff --git a/docs/three-microbuy.md b/docs/three-microbuy.mdindex 6b5576921..d01fa1137 100644--- a/docs/three-microbuy.md+++ b/docs/three-microbuy.md@@ -112,8 +112,11 @@ lands in ~8–15s. Make sure the micro-buy wallet holds enough SOL for fees:## Turning it on```bash-# 1. Apply the schema.-npm run db:migrate -- --apply+# 1. Apply the schema. db:migrate already hardcodes --apply and has no dry run,+# so read db:status first: db:migrate applies EVERY pending migration, not+# just this lane's (api/_lib/migrations/20260717233000_three_microbuy.sql).+npm run db:status+npm run db:migrate# 2. Fund a wallet with USDC (+ a little SOL for fees). Reuse the buyback wallet, or# set a dedicated key so the two lanes don't compete for the same USDC:diff --git a/docs/trading-experiment.md b/docs/trading-experiment.mdindex 3f4c66d25..24465a5eb 100644--- a/docs/trading-experiment.md+++ b/docs/trading-experiment.md@@ -173,8 +173,12 @@ table was rewritten to match them:5. **A capped-upside/uncapped-downside arm loses even when it wins.** Thegraduation-ride arm won 63% of 90 trades and still lost money with TP 20 /SL 15 against occasional -99% rugs. Reward must be a multiple of risk- everywhere: no arm keeps a TP below 2x its SL, and no arm trades with a null- TP (that arm went 0-for-24).+ everywhere: no arm keeps a TP below 2x its SL, and no *ladderless* arm trades+ with a null TP (that arm went 0-for-24). A null TP is still correct on a+ ladder arm, where the ladder takes the stake back at 2x and the trailing stop+ governs the moon bag, which is why the setup script below leaves+ `take_profit_pct` null. The failure was an uncapped bag with nothing at all+ scheduled to take profit, not the absence of a ceiling as such.The applied changes: six lifetime-negative `new_mint` spray arms disabled (thattrigger went 4-for-64, -0.17 SOL, worst in the fleet), TP set on all 14 armsdiff --git a/docs/tutorials/connect-ai-brain.md b/docs/tutorials/connect-ai-brain.mdindex d468adef5..b7ca3d824 100644--- a/docs/tutorials/connect-ai-brain.md+++ b/docs/tutorials/connect-ai-brain.md@@ -1,15 +1,14 @@# Connect Anthropic, OpenAI, or xAI (Grok) as the brain-The agent's body is the avatar. The agent's voice is the TTS. The agent's *brain* is whatever LLM is generating its replies. By default the platform routes through a managed Claude endpoint, which works out of the box but bills against your free tier. The moment you want real production traffic, full control over which model runs, or your own usage observability, you bring your own API key.+The agent's body is the avatar. The agent's voice is the TTS. The agent's *brain* is whatever LLM is generating its replies. By default an embedded agent runs on a **free open-weight lane** (`openai/gpt-oss-20b:free`, routed through OpenRouter on the platform's key), which works out of the box at no cost to you. The moment you want a frontier model, full control over which one runs, or your own usage observability, you bring your own API key.-This tutorial covers the whole brain layer. Where the LLM call actually happens (and why your key never ends up in HTML), how to attach your Anthropic or OpenAI key in My Agents, choosing between Claude Sonnet 4.6, Claude Opus 4.7, the GPT-5.6 family, and the smaller models, the latency and cost tradeoffs, configuring streaming and system prompts, tool-use support per model, and where to watch your token spend. The embed snippet doesn't change when you switch models — every config is on the agent record.+This tutorial covers the whole brain layer. Where the LLM call actually happens (and why your key never ends up in HTML), how to attach your Anthropic, OpenAI, or xAI key, choosing between the Claude 5 family, the GPT-5.x family, Grok, and the free lanes, the latency and cost tradeoffs, how streaming and system prompts are configured, tool-use support per model, and where to watch your spend. The embed snippet doesn't change when you switch models — the model lives on the agent's embed policy, not in your HTML.**What you'll build:**-- An agent powered by your own Anthropic key, with model selection-- An agent powered by your own OpenAI key, switchable across the GPT-5.6 family+- An agent powered by your own Anthropic, OpenAI, or xAI key- A working understanding of which model fits which use case (cost, latency, capability)-- A streaming-enabled brain so replies feel responsive-- An observability dashboard you can use to monitor spend per agent+- An embed policy that pins the model, the monthly quota, and the per-minute rate limit+- A concrete read on what your agents are actually spending**Prerequisites:** You have an agent at [three.ws/my-agents](https://three.ws/my-agents). You have an API key from Anthropic ([console.anthropic.com](https://console.anthropic.com)), OpenAI ([platform.openai.com](https://platform.openai.com)), or xAI ([console.x.ai](https://console.x.ai)). Familiarity with the concept of system prompts (see [agent personality](/tutorials/agent-personality)).@@ -21,131 +20,133 @@ The single most important architectural detail: **the LLM call is server-side, aWhen the agent on the page calls `agent.say('hi')`, the flow is:-1. The browser sends the user's message, the agent ID, and a session token to `three.ws/api/chat`.-2. The platform looks up the agent's brain configuration (provider, model, system prompt, attached tools).-3. The platform looks up the agent owner's stored API key for that provider (or falls back to the managed free-tier credit).-4. The platform makes the LLM call from the server, streams the response back over Server-Sent Events to the browser.-5. The browser fires `brain:stream` events with chunks and a final `brain:message` event with the complete reply.+1. The browser posts an Anthropic-shape body (`{ model, system, messages, tools, stream }`) to `three.ws/api/llm/anthropic?agent=<agentId>` (`api/llm/anthropic.js`).+2. The proxy reads that agent's **embed policy** and checks the referring origin against its allowlist, its per-minute rate limit, and its monthly quota — all before a single upstream token is spent.+3. It resolves which model actually runs (see the clamp below), looks up the matching upstream credential, and calls the provider from the server.+4. The response streams back as Anthropic-shape Server-Sent Events, whatever the upstream was — Groq, OpenRouter, NVIDIA, Mistral, xAI, and Vertex are all translated into that one wire format so the browser parser never changes.+5. The runtime fires `brain:stream` events with chunks and a final `brain:message` event with the complete reply. Both are re-dispatched on the `<agent-3d>` host element, so you listen on the element.-This matters for three reasons:+This matters for four reasons:-- **Keys stay secret.** Even a "view source" attack on your page reveals nothing. The key lives only in the platform's key store.-- **Rate-limit shaping happens once, server-side.** The platform manages backoff and retries for you.-- **The embed snippet doesn't know which model is running.** You can swap from Claude Sonnet 4.6 to GPT-5.6 Sol in My Agents and every page that embeds your agent picks up the change on next load. No code edits anywhere.+- **Keys stay secret.** Even a "view source" attack on your page reveals nothing. Keys live only on the server.+- **Rate-limit shaping and quota happen once, server-side**, per agent, from the embed policy.+- **A visitor cannot escalate you onto a paid model.** The proxy clamps the requested model: a caller may pick freely among the free lanes, but any model billed to a first-party vendor key (every Claude and every Grok id) is forced back to whatever the *owner* configured in `policy.brain.model`. The response echoes the model actually used, so a clamped caller can see what it got.+- **The embed snippet doesn't know which model is running.** Change `policy.brain.model` and every page that embeds your agent picks up the change on next load. No code edits anywhere.-The corollary: setting `api-key="sk-ant-..."` directly on the `<agent-3d>` tag is supported but discouraged. It exposes your key in DOM. Use it only for local prototypes that never get deployed. Production agents store their key on the platform side.+There is also a lane-failover chain: if the configured model's upstream returns a quota/billing/rate-limit error mid-request, the proxy retries down a chain of free fallbacks rather than failing the turn, and the response reports the model it landed on.++The corollary: setting `api-key="sk-ant-..."` directly on the `<agent-3d>` tag is supported but discouraged. It exposes your key in the DOM. Use it only for local prototypes that never get deployed. Production agents keep their key server-side.---## Step 2 — Add your API key in My Agents-The key store is per-account, not per-agent — once you've added a key, every agent you own can use it.+Keys live at **[/dashboard/account](https://three.ws/dashboard/account)**, in the **AI Provider Keys** panel. The store is per-account, not per-agent — once you've added a key, every agent you own can use it.For Anthropic:1. Open [console.anthropic.com](https://console.anthropic.com).2. **Settings → API Keys → Create Key.** Give it a label like "three.ws production".3. Copy the key (it starts with `sk-ant-`). You won't see it again.-4. Open [three.ws/my-agents](https://three.ws/my-agents).-5. Click the gear icon → **API Keys → Anthropic → Add key.**-6. Paste, save.+4. Open [/dashboard/account](https://three.ws/dashboard/account) → **AI Provider Keys**.+5. Paste it into **Anthropic (Claude)** and save.For OpenAI:1. Open [platform.openai.com/api-keys](https://platform.openai.com/api-keys).2. **Create new secret key.** Label it.-3. Copy (starts with `sk-`).-4. In three.ws My Agents, **API Keys → OpenAI → Add key.**-5. Paste, save.+3. Copy it (starts with `sk-proj-`).+4. Paste it into **OpenAI (GPT-4)** in the same panel and save.For xAI (Grok):1. Open [console.x.ai](https://console.x.ai).2. **API Keys → Create API key.** Label it.-3. Copy (starts with `xai-`).-4. In three.ws My Agents, **API Keys → Grok (xAI) → Add key.**-5. Paste, save.+3. Copy it (starts with `xai-`).+4. Paste it into **Grok (xAI)** in the same panel and save.-You can store all three keys at once and route different agents to different providers.+You can store all three at once. The same panel also holds keys for the non-LLM providers the platform can call on your behalf (Meshy, Tripo, Rodin, Stability, Replicate, ElevenLabs).-After saving, the keys are stored encrypted at rest. The dashboard shows the last four characters and a creation timestamp; the full key is never displayed back. If you suspect a leak, rotate the key on the provider side and replace it in the dashboard — the platform invalidates the old one immediately.+Under the hood this is `GET`/`PATCH /api/user/provider-keys`. The `GET` returns only which providers are set — never a value — and a `PATCH` with `null` for a provider deletes that key. Keys are stored encrypted at rest and are never displayed back. If you suspect a leak, rotate it on the provider side and replace it here.---## Step 3 — Pick a model-Each agent has a single active brain at a time. You change it in the agent's settings panel under **Brain → Model**.+Each agent has a single active brain at a time, pinned as `brain.model` on its embed policy (Step 8 covers changing it). To compare models interactively before you commit, the **model grid and multi-model playground at [/dashboard/brain](https://three.ws/dashboard/brain)** streams the same prompt across several models side by side. That page reads its roster from `GET /api/brain/chat`, which reports every model and whether it is currently available, so it is the live source of truth rather than a hardcoded list.-The current production-ready models, with the tradeoffs that actually matter for agent use:+Prices below are USD per million tokens (input / output) from the platform's own price table (`api/_lib/llm-pricing.js`).### Anthropic models-**Claude Sonnet 4.6** (`claude-sonnet-4-6`) — the default for most agents.+**Claude Sonnet 5** (`claude-sonnet-5`) — the default recommendation.-- **Cost:** Low. Roughly $3 per million input tokens, $15 per million output. For a typical 20-turn chat this is fractions of a cent.-- **Latency:** First token in ~600ms. Full reply for a 2-sentence answer in 1.2-2 seconds.-- **Capability:** Excellent at tool use, structured output, and following system prompts. The right default for support, sales, concierge, and personal agents.+- **Cost:** $3 / $15. For a typical 20-turn chat this is fractions of a cent.+- **Capability:** Near-Opus quality on coding and agentic work at Sonnet cost. The right default for support, sales, concierge, and personal agents.- **Context window:** 200K tokens. Plenty of room for long system prompts and memory.-**Claude Opus 4.7** (`claude-opus-4-7`) — when you need the smartest model.+**Claude Opus 5** (`claude-opus-5`) — when you need depth.++- **Cost:** $5 / $25.+- **Capability:** Deep reasoning, agentic and long-horizon work. **Thinks by default**, which is the tradeoff: better answers on hard questions, more latency and more billed output tokens on easy ones.+- **Context window:** 200K tokens.-- **Cost:** ~5x Sonnet. Worth it for high-stakes agents (legal, medical, financial assistants) and complex reasoning chains.-- **Latency:** First token in ~1.2s. Full reply 2.5-4s for a typical turn.-- **Capability:** Best-in-class at multi-step reasoning, ambiguous instruction handling, and long-context retrieval. Holds character better under adversarial pressure.-- **Context window:** 200K tokens. Same headroom as Sonnet — the upgrade is depth of reasoning, not window size.+**Claude Fable 5** (`claude-fable-5`) — the most capable model on the platform.-**Claude Haiku 4.5** (`claude-haiku-4-5-20251001`) — when latency matters more than depth.+- **Cost:** $10 / $50.+- **Capability:** State-of-the-art reasoning, long-horizon agentic work, knowledge work, and vision. Reach for it when a specific quality gap survives prompt iteration on Opus.+- **Note:** thinking is always on and is not configurable; the proxy strips any non-adaptive `thinking` config rather than letting the upstream reject the call.-- **Cost:** ~1/3 of Sonnet.-- **Latency:** First token in ~250ms. Full reply in well under a second.+**Claude Haiku 4.5** (`claude-haiku-4-5`) — when latency matters more than depth.++- **Cost:** $1 / $5, a third of Sonnet.- **Capability:** Good for FAQ-style agents, lookups, and short interactions. Drops noticeably below Sonnet on long context or nuanced tone.-- **Use it when:** you have an agent that handles many short turns (a wave-and-greet, a status-check agent) and you want it to feel instant.+- **Use it when:** you have an agent handling many short turns (a wave-and-greet, a status-check agent) and you want it to feel instant.++The previous generation stays selectable and priced identically to its successor tier: **Claude Opus 4.7** (`claude-opus-4-7`, $5 / $25) and **Claude Sonnet 4.6** (`claude-sonnet-4-6`, $3 / $15). There is no reason to start a new agent on them, but existing agents keep working untouched.++> Both Opus 4.7+ and the whole Claude 5 family reject sampling parameters upstream. The proxy strips `temperature` for those models and upgrades a `budget_tokens`-style `thinking` config to the adaptive form, so an embed that ships its SDK's defaults doesn't draw an avoidable 400. You don't have to do anything; just don't expect `temperature` to change a Claude 5 reply.### OpenAI models-**GPT-5.6 Terra** (`gpt-5.6-terra`) is the comparable peer to Sonnet 4.6.+**GPT-5.6 Terra** (`gpt-5.6-terra`) is the balanced peer to Sonnet.-- **Cost:** $2.50 per million input, $15 per million output. The same band as Sonnet.-- **Latency:** First token in ~700ms.+- **Cost:** $2.50 / $15. The same band as Sonnet.- **Capability:** Strong at multimodal input and general chat. Tool use is reliable. The right OpenAI default for support, sales, and concierge agents.- **Context window:** 1M tokens.-**GPT-5.6 Sol** (`gpt-5.6-sol`) is the reasoning-grade OpenAI flagship, comparable to Opus.+**GPT-5.6 Sol** (`gpt-5.6-sol`) is the reasoning-grade OpenAI flagship.-- **Cost:** Premium ($5 per million input, $30 per million output). Comparable to Opus per token.-- **Latency:** Higher than Terra; first token in ~1.5s, more if reasoning is engaged.+- **Cost:** $5 / $30.- **Capability:** Frontier reasoning, coding, and agentic work. Excellent at hard tasks, math, and complex tool chains. Overkill for casual chat.- **Context window:** 1M tokens.**GPT-5.6 Luna** (`gpt-5.6-luna`) is the budget pick of the 5.6 family.-- **Cost:** $1 per million input, $6 per million output.-- **Latency:** Fast.-- **Capability:** Vision-capable, and roughly comparable to Haiku for short interactions. Less coherent on long conversations.+- **Cost:** $1 / $6.+- **Capability:** Vision-capable, roughly comparable to Haiku for short interactions. Less coherent on long conversations.- **Context window:** 1M tokens.**o3** (`o3`) is the reasoning specialist, with `o3-pro` above it.- **Cost:** Reasoning tokens bill as output, so replies cost more than their visible length suggests.-- **Latency:** Variable; it thinks before the first token arrives.- **Capability:** Deep chain-of-thought for math, logic, and structured planning. Not a general chat pick; reach for it when the agent's job is to reason, not to converse.-The platform also carries the wider OpenAI lineup: GPT-5.5 and GPT-5.5 Pro, the more affordable GPT-5.4 tier (`gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `gpt-5.4-nano`, the cheapest current GPT), and GPT-5.3 Codex (`gpt-5.3-codex`) for code-centric agents. The three 5.6 models above cover almost every agent use case; the rest are there when you want a specific cost or capability point.+The platform also carries GPT-5.5 and GPT-5.5 Pro, the more affordable GPT-5.4 tier (`gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `gpt-5.4-nano`, the cheapest current GPT), and GPT-5.3 Codex (`gpt-5.3-codex`) for code-centric agents.Legacy ids keep working: `gpt-4o`, `gpt-4o-mini`, and `o3-mini` are accepted as aliases and resolve to `gpt-5.6-sol`, `gpt-5.6-luna`, and `o3` (the GPT-4o family was deprecated upstream in July 2026), so existing agents upgrade in place with no config change.### xAI (Grok) models-**Grok 4.5** (`grok-4.5`) is the xAI flagship.+**Grok 4.5** (`grok-4.5`) is the xAI flagship: $2 / $6, cheaper than Sonnet per token, with a 500K context window. Frontier reasoning and strong real-time knowledge of X. A good pick for agents that discuss current events or social sentiment.++**Grok 4.3** (`grok-4.3`) is the long-context option: $1.25 / $2.50, 1M-token window. Reach for it when the agent carries very large system prompts or memory.-- **Cost:** $2 per million input, $6 per million output. Cheaper than Sonnet per token.-- **Latency:** First token in roughly a second.-- **Capability:** Frontier reasoning with strong real-time knowledge of X. Tool use is reliable. A good pick for agents that discuss current events or social sentiment.-- **Context window:** 500K tokens.+**Grok 4.1 Fast** (`grok-4.1-fast`) is the budget workhorse on paper ($0.20 / $0.50, 2M-token window), but check availability before you pin it: OpenRouter dropped it from its catalog, so it only runs when a first-party `GROK_API_KEY` is configured. `GET /api/brain/chat` reports it as unavailable otherwise.-**Grok 4.3** (`grok-4.3`) is the long-context option ($1.25 in / $2.50 out, 1M-token window). Reach for it when the agent carries very large system prompts or memory.+### Free lanes (no key, no bill)-**Grok 4.1 Fast** (`grok-4.1-fast`) is the budget workhorse ($0.20 in / $0.50 out, 2M-token window). Comparable to Haiku for short interactions and dramatically cheaper.+The embed default, `openai/gpt-oss-20b:free`, costs nothing and is tool-call capable. Signed-out callers are restricted to these free lanes on purpose, so an unauthenticated script can't drain the server's billed keys. Alongside GPT-OSS the platform carries free NVIDIA NIM models (Nemotron, DeepSeek, Kimi K2, Llama 4 Maverick, MiniMax M2), Groq's sub-second Llama lanes, SambaNova, Mistral's experiment tier, and Z.AI's GLM Flash. They are the fallback rungs the proxy walks when a paid lane errors, and they are perfectly serviceable as a primary brain for a low-stakes agent.### Picking a model@@ -153,15 +154,18 @@ A practical rule of thumb:| Use case | Recommended model ||---|---|-| Support / FAQ agent for a SaaS | Sonnet 4.6 or GPT-5.6 Terra |-| Personal-website-me agent | Sonnet 4.6 |-| Onboarding co-pilot, sales bot | Sonnet 4.6 |-| Museum tour guide, long-form domain agent | Sonnet 4.6, escalate to Opus only if needed |-| Legal, medical, financial assistant | Opus 4.7 or GPT-5.6 Sol |+| Kicking the tyres, low-stakes embed | `openai/gpt-oss-20b:free` (the default — no key, no bill) |+| Support / FAQ agent for a SaaS | Sonnet 5 or GPT-5.6 Terra |+| Personal-website-me agent | Sonnet 5 |+| Onboarding co-pilot, sales bot | Sonnet 5 |+| Museum tour guide, long-form domain agent | Sonnet 5, escalate to Opus 5 only if needed |+| Legal, medical, financial assistant | Opus 5 or GPT-5.6 Sol |+| Hardest reasoning, vision-heavy knowledge work | Fable 5 || Status-check, wave-and-greet, micro-interaction | Haiku 4.5 or GPT-5.6 Luna |-| Multi-step tool chains, code assistance | Opus 4.7 or GPT-5.6 Sol |+| Multi-step tool chains, code assistance | Opus 5 or GPT-5.6 Sol |+| Current events, social sentiment | Grok 4.5 |-Start at Sonnet 4.6 for almost everything. Move to Haiku if latency is the bottleneck. Move to Opus or GPT-5.6 Sol only when you have a specific quality issue that the smaller model can't fix with prompt iteration.+Start at Sonnet 5 for almost everything. Move to Haiku if latency is the bottleneck. Move to Opus 5, Fable 5, or GPT-5.6 Sol only when you have a specific quality issue that the smaller model can't fix with prompt iteration.---@@ -169,7 +173,9 @@ Start at Sonnet 4.6 for almost everything. Move to Haiku if latency is the bottlThe system prompt and the model are configured separately. You can swap models without touching the prompt, and vice versa.-In **Brain → System prompt**, paste your full prompt. The same prompt works across all the models above, with one caveat: smaller models (Haiku, GPT-5.6 Luna) follow instructions less precisely, so prompts written for them benefit from being shorter and more explicit. A 600-word prompt that Sonnet handles cleanly may overflow Haiku's instruction-following budget.+The prompt lives on the agent's persona, which you build in the **Brain Studio** panel of the agent editor. It is an interview, not a text box: you direct a character with trait sliders and sample exchanges, and the studio extracts the system prompt from that. Read the extracted prompt back with `GET /api/agents/:id/persona`.++The same prompt works across all the models above, with one caveat: smaller models (Haiku, GPT-5.6 Luna) follow instructions less precisely, so prompts written for them benefit from being shorter and more explicit. A 600-word prompt that Sonnet handles cleanly may overflow Haiku's instruction-following budget.If you're targeting Haiku or GPT-5.6 Luna specifically, trim:@@ -179,16 +185,15 @@ If you're targeting Haiku or GPT-5.6 Luna specifically, trim:For Sonnet, Opus, GPT-5.6 Terra, and GPT-5.6 Sol, the full prompt template from the [agent personality](/tutorials/agent-personality) tutorial works without modification.-A few configuration knobs alongside the prompt:+**Sampling knobs are set on the client, not in a dashboard.** The runtime's provider takes them when it is constructed, and the `<agent-3d>` element passes them through from the agent manifest's `brain` block:-| Setting | What it does | Recommended |-|---|---|---|-| **Temperature** | 0-2 range, controls randomness | 0.7-0.9 for chat agents, 0.3-0.5 for FAQ |-| **Max tokens** | Hard cap on reply length | 512 for voice agents, 1024 for text-mode |-| **Top-p** | Nucleus sampling threshold | Leave at default unless you have a specific reason |-| **Stream** | Whether to stream tokens as they arrive | On — see Step 5 |+| Setting | Where it lives | Default | Notes |+|---|---|---|---|+| `temperature` | `manifest.brain.temperature` | `0.7` | 0.8 is a safe centre for a conversational agent. **Silently stripped for Opus 4.7+ and the whole Claude 5 family**, which reject sampling parameters upstream. |+| `maxTokens` | `manifest.brain.maxTokens` | `4096` | The proxy defaults a missing value to 4096, and floors thinking-by-default models at 4096 so the visible reply isn't squeezed out by thinking tokens. |+| `thinking` | `manifest.brain.thinking` | `'auto'` | `'always'` requests extended thinking. Coerced to the adaptive form on models that demand it. |-The temperature setting is the second-most impactful knob after the prompt itself. Too low and the agent becomes mechanical; too high and it goes off-script. 0.8 is a safe centre for any conversational agent.+There is no top-p knob and no streaming toggle: the client always requests `stream: true` (see Step 5). A long, stable system prompt gets a prompt-cache breakpoint added automatically once it clears the per-model length threshold, which bills repeat turns at roughly a tenth of the input price. You don't opt in.---@@ -215,7 +220,7 @@ agent.addEventListener('brain:message', (e) => {For a custom chat UI, build incremental rendering on `brain:stream` so the user sees text arriving instead of waiting for the whole reply. The built-in chat input already does this — assistant messages fill in word by word.-To turn streaming off (rarely useful, but available if you're piping the output somewhere that can only handle complete messages), set **Brain → Stream → off** in the agent settings. You'll get a single `brain:message` event with the whole reply and no `brain:stream` events.+There is no streaming off-switch: the runtime always requests `stream: true`. If you need whole messages only, ignore `brain:stream` and read `brain:message`, which fires once with the complete reply — the same end state, with no wiring change.Streaming impacts perceived latency *much* more than actual end-to-end latency. A reply that takes 2 seconds to fully generate feels nearly instant with streaming on; without streaming, the same 2-second wait feels like the agent is broken.@@ -227,14 +232,19 @@ Tool use (the model invoking a function you've defined — a `searchProducts(que| Model | Tool use quality ||---|---|-| Claude Opus 4.7 | Excellent. Handles complex multi-tool chains and ambiguous tool selection cleanly. |-| Claude Sonnet 4.6 | Excellent. Indistinguishable from Opus for most tool flows. The default recommendation. |+| Claude Fable 5 | Excellent. The strongest option for long, ambiguous tool chains. |+| Claude Opus 5 | Excellent. Handles complex multi-tool chains and ambiguous tool selection cleanly. |+| Claude Sonnet 5 | Excellent. Indistinguishable from Opus for most tool flows. The default recommendation. || Claude Haiku 4.5 | Good for single-tool flows. Struggles with chains that require 3+ sequential tool calls. || GPT-5.6 Sol | Excellent, similar to Opus. Strong at parallel tool calls. || GPT-5.6 Terra | Very good. Slightly more prone to mis-formatting tool arguments than Sonnet. || GPT-5.6 Luna | Functional. Avoid for anything with 2+ tools or non-trivial schemas. |+| Grok 4.5 | Reliable. A fair substitute for Terra when you also want current-events knowledge. |+| Free lanes (GPT-OSS, NVIDIA NIM, Groq) | Tool-call capable — that is why they are the fallback rungs — but noticeably weaker at picking the right tool. Fine for one or two tools with simple schemas. |++If you're building a skill-heavy agent — one that needs to look up products, check inventory, search documentation, and place orders, all in one conversation — pick Sonnet 5 or GPT-5.6 Terra at minimum. Haiku and Luna are acceptable for single-purpose lookups but get confused on chains.-If you're building a skill-heavy agent — one that needs to look up products, check inventory, search documentation, and place orders, all in one conversation — pick Sonnet or GPT-5.6 Terra at minimum. Haiku and Luna are acceptable for single-purpose lookups but get confused on chains.+The runtime caps a single turn at 8 tool iterations, so a chain that can't resolve inside 8 round trips returns whatever it has rather than looping forever.See the [custom skill tutorial](/tutorials/custom-skill) for the full skill-writing workflow.diff --git a/docs/tutorials/deploy-to-vercel-custom-domain.md b/docs/tutorials/deploy-to-vercel-custom-domain.mdindex 7c2837a31..a6d174b91 100644--- a/docs/tutorials/deploy-to-vercel-custom-domain.md+++ b/docs/tutorials/deploy-to-vercel-custom-domain.md@@ -59,11 +59,13 @@ The repo ships a `vercel.json`. Read it once so you know what's working for you.{"buildCommand": "npm run build:vercel","outputDirectory": "dist",- "public": true,- "installCommand": "npm ci --prefer-offline --no-audit --no-fund",+ "installCommand": "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 PUPPETEER_SKIP_DOWNLOAD=1 npm ci --no-audit --no-fund","env": { "NODE_OPTIONS": "--no-deprecation" },"functions": {- "api/**/*.js": { "includeFiles": "node_modules/@zauthx402/sdk/dist/**" }+ "api/**/*.js": {+ "includeFiles": "{data/pages.json,sdk/src/sas-config.json}",+ "maxDuration": 30+ }},"routes": [{ "src": "/openapi\\.json", "dest": "/api/openapi-json" },@@ -73,10 +75,11 @@ The repo ships a `vercel.json`. Read it once so you know what's working for you.}```-Three things worth understanding:+Four things worth understanding:- **`buildCommand: npm run build:vercel`** runs the production build, including the prebuild step that generates the page index. The local `npm run dev` uses Vite directly; `build:vercel` is the optimized path that ships.- **`outputDirectory: dist`** is what Vercel serves as static files. After `npm run build`, `dist/` contains `index.html`, hashed JS bundles, the `cdn/` folder, sub-apps under `dist/chat/`, etc.+- **`functions`** sets per-route bundling and timeouts. The `api/**/*.js` entry above is the catch-all fallback; the real file layers dozens of more specific globs before it, giving slow routes (forge, streams, crons) a longer `maxDuration` and pulling in the data files each one reads. Add your own entry above the catch-all when a route needs more than 30 seconds.- **`routes`** rewrites specific paths to specific function files. The well-known routes (`/.well-known/x402.json` → `/api/wk?name=x402-discovery`) are how the platform exposes machine-readable discovery surfaces at the URLs the spec mandates.You shouldn't need to edit `vercel.json` for the basic deploy. The repo's defaults are tuned for the platform's actual route set.@@ -479,7 +482,7 @@ In rough order of likelihood:**The build breaks because Node version drifts.** Confirm `engines.node` in `package.json` matches what Vercel installs. The repo pins to `24.x`; Vercel respects this. If it ever stops, set `NODE_VERSION=24` in your project's env vars (build-time scope).-**A migration runs out of order.** Your `migrations/` directory is the source of truth — if two engineers add migrations on parallel branches, the lexically-earlier one applies first regardless of merge order. The fix: timestamp filenames (`20260514120000_add_x.sql`), don't number them (`002_add_x.sql`).+**A migration runs out of order.** Your `api/_lib/migrations/` directory is the source of truth: if two engineers add migrations on parallel branches, the lexically-earlier one applies first regardless of merge order. The fix: timestamp filenames (`20260514120000_add_x.sql`), don't number them (`002_add_x.sql`).**The CDN bundle gets stale at edges.** Vercel's edge respects `Cache-Control` headers. Make sure your build emits hashed filenames (`agent-3d.<hash>.js`) and your script tag references the canonical URL that always rewrites to the latest hash. The repo handles this; if you customize the build pipeline, don't break the hashing.diff --git a/docs/tutorials/embed-in-30-seconds.md b/docs/tutorials/embed-in-30-seconds.mdindex 82ebbd201..3e5c3e065 100644--- a/docs/tutorials/embed-in-30-seconds.md+++ b/docs/tutorials/embed-in-30-seconds.md@@ -27,10 +27,10 @@ Open [https://three.ws/create](https://three.ws/create) in a new tab. The editorIf you want to ship something working as fast as possible, skip every panel for now and click **Save** in the top-right of the editor. The platform creates an agent with the default body, the default personality, and a default greeting. Once saved, the URL in your browser's address bar becomes something like:```-https://three.ws/agent/0xabc123…def+https://three.ws/agent/d94d2a50-86fa-4d2e-b87b-580f7517aa4c```-The string after `/agent/` is your agent ID. Copy it. You will paste it into the `<agent-3d>` tag in the next step.+The string after `/agent/` is your agent ID: a UUID, assigned once and never reissued. Copy it. You will paste it into the `<agent-3d>` tag in the next step.### Path B — Customise first, then save@@ -116,7 +116,7 @@ When the browser hits these lines:5. Once the avatar is loaded, the element dispatches a `agent:ready` event you can listen to. The agent then begins its idle animation and waits for interaction.Notice what is *not* on this list:-- No iframe. The agent renders directly in your page's DOM, which means it inherits your site's CSS scope intentionally (we'll cover styling shadows in the customisation tutorial).+- No iframe. `<agent-3d>` is a real element in your page's DOM, so it participates in your layout like any other block. Its internals live in an open shadow root, so your site's stylesheet cannot accidentally break the chat chrome, and the chrome cannot leak styles back into your page. You still theme it deliberately, through inherited CSS custom properties and `::part()` selectors: the customisation tutorial covers both.- No second script tag. You don't need to load Three.js separately. You don't need to bundle anything.- No build step. The script is plain JavaScript, served minified from a CDN edge.@@ -160,7 +160,7 @@ Open developer tools (F12 or right-click → Inspect → Console). You should seIn the Network tab, filter by `three.ws`. You should see:-- `agent-3d.js` (the bundle, around 1–2 MB gzipped)+- `agent-3d.js` (the bundle, under 1 MB gzipped)- A request to the agents API with your agent ID- A request for the avatar GLB- A few smaller assets (animations, textures)diff --git a/docs/tutorials/emotion-from-data.md b/docs/tutorials/emotion-from-data.mdindex cdcacb614..cfd402ac1 100644--- a/docs/tutorials/emotion-from-data.md+++ b/docs/tutorials/emotion-from-data.md@@ -2,11 +2,11 @@An agent that just idles is furniture. An agent that visibly *reacts* — dances when something spikes, flinches when something drops, celebrates a milestone — reads as alive. three.ws ships a full animation library (idle, wave, dance, celebrate, jump, dozens more — browse them at [/animations](/animations)) and a public JS API to trigger any of it on command. This tutorial shows you how to point that at data you actually have: a live feed, a webhook, or a real AI model classifying arbitrary text.-You'll build two working pipelines — one with zero AI (a lexicon sentiment score, free, no key, triggering a real body animation), one with a real model in the loop (IBM Granite classifying arbitrary documents, feeding a wider set of gestures) — plus the cooldown pattern that keeps an automated agent from spamming animations every tick.+You'll build two working pipelines. One uses zero AI (a lexicon sentiment score, free, no key, triggering a real body animation), one puts a real model in the loop (IBM Granite reading arbitrary documents, feeding a graded set of gestures). Both use the cooldown pattern that keeps an automated agent from spamming animations every tick.**What you'll build:**- An agent that plays a real body animation (celebrate, dance, flinch) driven by a live sentiment feed, using only `<agent-3d>`'s public JS API-- A second pipeline where an actual AI model reads arbitrary text — reviews, tickets, chat logs, anything — and picks the matching gesture from a wider library, not just a three-way keyword split+- A second pipeline where an actual AI model reads arbitrary text (reviews, tickets, chat logs, anything) and picks the matching gesture from a graded score plus its risk flags, not just a keyword match- A cooldown/dedupe pattern so a fast-moving data source doesn't retrigger the same animation every poll- The two real, documented entry points for animation: `agent.play(clipName)` (exact clip) and `agent.playEmote(name)` (semantic, with a fallback chain)@@ -105,7 +105,9 @@ Save that as `index.html` and open it — no build step, no server, no wallet. S## Step 3 — The AI lane: real classification over arbitrary data, richer gestures-A lexicon scorer only works on short, informal text and only gives you positive/negative. For real documents — support tickets, product reviews, meeting transcripts, incident reports — you want a model that returns *structured* emotion: a sentiment score plus a breakdown across joy, anger, fear, sadness, surprise, and disgust, so you can pick a more specific reaction than a binary celebrate/flinch. `ibm_granite_analyze` (part of the [IBM Granite x402 MCP suite](../ibm-x402-mcp.md)) does exactly this for $0.04/call, no IBM account needed — you pay in USDC, it pays IBM.+A lexicon scorer only works on short, informal text, and it only fires on words it already knows. For real documents (support tickets, product reviews, meeting transcripts, incident reports) you want a model that actually reads the thing and returns *structured* output: a graded sentiment score plus the findings and risk flags behind it, so the reaction tracks the document's real tone instead of its vocabulary. `ibm_granite_analyze` (part of the [IBM Granite x402 MCP suite](../ibm-x402-mcp.md)) does exactly this for $0.04/call, no IBM account needed: you pay in USDC, it pays IBM.++The tool returns a fixed set of keys: `summary`, `entities`, `sentiment` (`{ overall, score }`, score in -1..1), `key_findings`, `risk_flags` (each with a `severity`), and `next_steps`. The two the animation layer cares about are `sentiment.score` and `risk_flags`.This is a server-side call (it needs a wallet to sign the payment), so it lives behind a small endpoint you host yourself and the browser polls. The `@three-ws/x402-fetch` package does the 402 → sign → retry dance for you — see [pay-for-x402-service](/tutorials/pay-for-x402-service) for the full protocol if you want the mechanics.@@ -117,16 +119,21 @@ import { withX402, privateKeyToWallet } from '@three-ws/x402-fetch';const wallet = privateKeyToWallet(process.env.SOLANA_PRIVATE_KEY); // funds the $0.04 callsconst fetchWithPay = withX402(fetch, wallet);-// Dominant emotion → the richest matching clip. exact-name clips (agent.play)+// Score band → the richest matching clip. exact-name clips (agent.play)// give a bigger, more specific performance than the 3-way emote chain.-const GESTURE_FOR = {- joy: 'celebrate',- surprise: 'silly',- anger: 'shake',- fear: 'defeated',- sadness: 'defeated',- disgust: 'angry',-};+// Bands, not a binary: a mildly positive review gets a wave, a glowing+// one gets a full celebrate.+const GESTURE_FOR_SCORE = [+ { min: 0.6, clip: 'celebrate' },+ { min: 0.25, clip: 'wave' },+ { min: -0.25, clip: null }, // middling: leave idle alone+ { min: -0.6, clip: 'concern' },+ { min: -1, clip: 'defeated' },+];++function clipForScore(score) {+ return GESTURE_FOR_SCORE.find((band) => score >= band.min)?.clip ?? null;+}async function gestureFor(document) {const res = await fetchWithPay('https://three.ws/api/ibm-mcp', {@@ -145,13 +152,19 @@ async function gestureFor(document) {const { result } = await res.json();const analysis = JSON.parse(result.content[0].text);- const breakdown = analysis.emotion_breakdown || {};- const [dominant, strength] = Object.entries(breakdown).sort((a, b) => b[1] - a[1])[0] || ['joy', 0];+ // A high-severity risk flag outranks the score: an incident report can read+ // as calm prose and still be the thing you want the agent to react to.+ const alarming = (analysis.risk_flags || []).some((f) => f.severity === 'high');+ if (alarming) return { clip: 'concern', strength: 1, summary: analysis.summary };++ const score = analysis.sentiment?.score;+ if (typeof score !== 'number') return null; // model returned no usable score// Below this, the signal is too weak to justify interrupting idle.+ const strength = Math.abs(score);if (strength < 0.3) return null;- return { clip: GESTURE_FOR[dominant] || null, strength, summary: analysis.summary };+ return { clip: clipForScore(score), strength, summary: analysis.summary };}```@@ -207,7 +220,8 @@ function reactIfConfident(clipOrEmoteName, { confident, useExactClip = false } =- **`agent.play('someClip')` does nothing.** The name is case-sensitive and must match a clip actually present on the rig — check the exact name at [/animations](/animations) or fall back to `playEmote()`, which degrades gracefully instead of silently failing.- **The agent keeps re-celebrating every poll.** You skipped the cooldown gate in Step 4, or your confidence threshold is too low for a noisy feed. Widen `COOLDOWN_MS` or raise the sample-size/strength floor.- **AI lane 402 loop / never resolves.** Your `SOLANA_PRIVATE_KEY` wallet has no USDC. Fund it with a few cents — see the [x402 payment flow](/tutorials/pay-for-x402-service).-- **`analysis.emotion_breakdown` is undefined.** You passed `analysis_type` other than `sentiment` — only that type returns the per-emotion breakdown; the other five types return type-specific fields instead (see [ibm-x402-mcp](../ibm-x402-mcp.md)).+- **`analysis.sentiment` is undefined.** Granite returned something that wasn't a clean JSON analysis object; the tool falls back to `{ ok: true, raw_response, parse_error }` in that case. Log `analysis.parse_error` and `analysis.raw_response` to see what came back. The `gestureFor()` above already treats a missing score as "no gesture" rather than crashing.+- **Every document scores middling and nothing ever plays.** `analysis_type: 'sentiment'` tunes the model toward tone; the other five types (`general`, `contract`, `financial`, `technical`, `medical`) return the same keys but reason about different things, so a contract analyzed as `general` often lands near 0. Match the type to your data (see [ibm-x402-mcp](../ibm-x402-mcp.md)).---@@ -215,7 +229,7 @@ function reactIfConfident(clipOrEmoteName, { confident, useExactClip = false } =- `agent.play(clipName)` for an exact clip, `agent.playEmote(name)` for a safer semantic trigger with a fallback chain — both are public methods on every `<agent-3d>` element, no library beyond the CDN script.- The free lane (`/api/social/sentiment-pulse`) proves the wiring with zero AI and zero cost.-- The AI lane (`ibm_granite_analyze` over x402) turns arbitrary documents into a richer emotion breakdown, unlocking more of the animation library than a simple positive/negative split.+- The AI lane (`ibm_granite_analyze` over x402) turns arbitrary documents into a graded sentiment score plus risk flags, which drives more of the animation library than a lexicon's positive/negative split can reach.- Gate every automated trigger behind a cooldown and a confidence floor — [`pumpfun-reactions.js`](../../src/widgets/pumpfun-reactions.js) is the production-grade version of this exact pattern, queueing and prioritizing real trade-feed events across 23 distinct clips.**Related tutorials:** [The JS API — animations, exact name vs. hint](/tutorials/js-api-events) · [Trigger the agent from page events](/tutorials/trigger-from-page-events) · [Animate your avatar](/tutorials/animate-your-avatar) · [Discover and pay for an x402 service](/tutorials/pay-for-x402-service)diff --git a/docs/tutorials/explore-docs-world.md b/docs/tutorials/explore-docs-world.mdindex c6d4e5a73..e5665ce6b 100644--- a/docs/tutorials/explore-docs-world.md+++ b/docs/tutorials/explore-docs-world.md@@ -42,13 +42,24 @@ https://three.ws/docs/world#forge## 4. Use the index instead of walking-The **☰ Index** chip (top left) lists all fourteen sections. Picking one teleports you to its pavilion and opens its page list. This is also the fully keyboard-accessible path through the world: Tab to the chip, Enter, arrow through the list.+The **☰ Index** chip (top left) lists all fourteen sections. Picking one teleports you to its pavilion and opens its page list. This is also a fully keyboard-accessible path through the world: Tab to the chip, Enter, arrow through the list.-## 5. Change the camera+## 5. Search when you already know the page++Walking is the point of this surface, but hunting fourteen pavilions for a page you can already name is not. Press `/` (or Ctrl+K, Cmd+K on a Mac) anywhere in the world and a search palette opens over the scene, ranking every documented page. Typos are tolerated: the palette uses the same fuzzy scorer as the rest of the platform, so `marketpalce` still finds the marketplace page.++Each result offers two actions:++- **Enter** reads the page now, and stands your avatar at its pavilion so closing the reader leaves you where that page lives.+- **Shift+Enter** has the world walk you there, routing around the other pavilions and opening the page on arrival.++Pages you opened recently are listed first when the box is empty.++## 6. Change the cameraPress C (or the camera chip, top right) to cycle the four platform camera modes: Follow, Cinematic, First Person, Top Down. These are the same modes `/walk` and `/play` use, and your choice is remembered.-## 6. Bring your own avatar+## 7. Bring your own avatarBy default you walk as the base mannequin. Any rigged humanoid GLB can replace it via the `avatar` query parameter:diff --git a/docs/tutorials/find-a-better-exit-policy.md b/docs/tutorials/find-a-better-exit-policy.mdindex 0cc33c0f8..b10822f24 100644--- a/docs/tutorials/find-a-better-exit-policy.md+++ b/docs/tutorials/find-a-better-exit-policy.md@@ -50,12 +50,17 @@ curl -s 'https://three.ws/api/sniper/exit-lab?window=all&limit=500' \```json{- "scanned": 239,- "replayable": 234,+ "scanned": 313,+ "replayable": 306,"excluded": ["laddered"]}```+Those counts grow every time the fleet closes a position, so yours will be+larger. The shape is the part that matters: `scanned` is every closed position+the corpus reached, `replayable` is how many survived the exclusions, and+`excluded` names why the rest were dropped.+**The first thing to notice is that "net result" and "actually booked" are notthe same number, and they are not supposed to be.**@@ -188,8 +193,8 @@ https://three.ws/exit-lab?stopLossPct=15&trailingStopPct=10&takeProfitPct=off&inThat link is the unit of a useful argument about exits. Instead of "I think thestop is too wide", you can send a page that shows what a tighter stop would have-returned over 234 real trades, with the caveats attached and the underlying-transactions one click away.+returned over every replayable trade in the corpus, with the caveats attached and+the underlying transactions one click away.If you run your own agent, the same parameters are what[`/api/sniper/strategy`](../api-reference.md) accepts, so a finding here mapsdiff --git a/docs/tutorials/greeting-and-first-speech.md b/docs/tutorials/greeting-and-first-speech.mdindex e8530314c..4f019a20e 100644--- a/docs/tutorials/greeting-and-first-speech.md+++ b/docs/tutorials/greeting-and-first-speech.md@@ -42,6 +42,8 @@ Two things worth knowing about this snippet:That's a working greeting. The rest of this tutorial is about doing it well rather than doing it at all.+> **The editor's "Greeting" field is a different thing.** The agent editor has a **Greeting (demo first message)** field, and it is easy to assume filling it in makes your embed talk. It does not. That field is the opening line published in the agent's signed manifest and shown on platform surfaces that demo the agent (its marketplace card, a Widget Studio talking-agent widget, an exported agent JSON). `<agent-3d>` does not read it. On your own page, the greeting is the JavaScript below.+---## Step 2 — When the greeting firesdiff --git a/docs/tutorials/mcp-server-for-your-agent.md b/docs/tutorials/mcp-server-for-your-agent.mdindex ca8240d80..dc77d189c 100644--- a/docs/tutorials/mcp-server-for-your-agent.md+++ b/docs/tutorials/mcp-server-for-your-agent.md@@ -479,12 +479,21 @@ The shape:{"resource": "https://three.ws/api/mcp","authorization_servers": ["https://three.ws"],- "scopes_supported": ["mcp", "mcp:tools", "mcp:resources"],"bearer_methods_supported": ["header"],- "resource_documentation": "https://three.ws/docs/mcp"+ "resource_documentation": "https://three.ws/docs/mcp",+ "scopes_supported": [+ "avatars:read", "avatars:write", "avatars:delete",+ "profile", "offline_access",+ "memory:read", "memory:write",+ "agents:read", "agents:write",+ "wallet:read", "wallet:write",+ "services:write"+ ]}```+Note the scopes are per-capability, not one blanket `mcp` scope. A client asks for exactly what it needs (`avatars:read` to render, `memory:write` to store a memory), so a token that leaks cannot do more than the tool it was minted for.+To wire this on your own server, add `api/wk-oauth-protected-resource.js`:```jsdiff --git a/docs/tutorials/paid-x402-endpoint.md b/docs/tutorials/paid-x402-endpoint.mdindex 538f72d6c..120e86ea1 100644--- a/docs/tutorials/paid-x402-endpoint.md+++ b/docs/tutorials/paid-x402-endpoint.md@@ -61,7 +61,7 @@ Good candidates in 2026, with concrete examples already running in production:- **Reputation lookup.** `/api/x402/agent-reputation` — pulls an ERC-8004 agent's review history from on-chain and returns aggregate scores.- **Symbol availability.** `/api/x402/symbol-availability` — checks whether a Pump.fun ticker is already used by another agent in the registry.-This tutorial builds **a simplified model-check endpoint**. The full production version is at `/workspaces/three.ws/api/x402/model-check.js` in the three.ws repo — read it for reference. We'll build a leaner version end-to-end that's easier to follow.+This tutorial builds **a simplified model-check endpoint**. The full production version is at [`api/x402/model-check.js`](https://github.com/nirholas/three.ws/blob/main/api/x402/model-check.js) in the three.ws repo. Read it for reference. We'll build a leaner version end-to-end that's easier to follow.The work: take a `?url=` query param pointing at a glTF or GLB file, fetch it, count primitives and materials, return JSON. Price: $0.001 USDC per call (1000 micro-USDC).diff --git a/docs/tutorials/read-the-trading-fleet.md b/docs/tutorials/read-the-trading-fleet.mdindex 215677c04..5263af9d2 100644--- a/docs/tutorials/read-the-trading-fleet.md+++ b/docs/tutorials/read-the-trading-fleet.md@@ -166,14 +166,28 @@ that never fills is not being cautious, it is stuck.## Step 7: Verify anything you doubt on-chainEvery fill is signed by the agent's own wallet, so nothing here has to be taken-on trust. The leaderboard exposes each agent's wallet and an explorer link:+on trust. The same response carries a `trades` array, and every trade links both+legs straight to Solscan:```bashcurl -s 'https://three.ws/api/sniper/leaderboard?window=all' \- | jq '.leaderboard[] | {agent_name, wallet, wallet_explorer_url}'+ | jq '.trades[] | {agent_name, symbol, pnl_sol, exit_reason, buy_url, sell_url}'```-Open the explorer link and the transactions are there in the order the platform+To go the other way, from an agent to its whole on-chain history, take the wallet+off the leaderboard row and open it in an explorer:++```bash+curl -s 'https://three.ws/api/sniper/leaderboard?window=all' \+ | jq -r '.leaderboard[] | select(.wallet and .wallet != "pending")+ | "\(.agent_name)\thttps://solscan.io/account/\(.wallet)"'+```++That filter is not decoration. An agent whose wallet has not been provisioned yet+reports `null`, and one mid-provision reports the literal string `"pending"`.+Both would otherwise build an explorer URL that resolves to nothing.++Open either link and the transactions are there in the order the platformclaims. If a number on a three.ws page ever disagrees with the chain, the chain isright and it is a bug worth reporting.diff --git a/docs/tutorials/self-host-agent-backend.md b/docs/tutorials/self-host-agent-backend.mdindex 7ac2fe66c..a05c5c07b 100644--- a/docs/tutorials/self-host-agent-backend.md+++ b/docs/tutorials/self-host-agent-backend.md@@ -8,9 +8,9 @@ This is the heaviest tutorial in the Advanced tier. It's worth doing in full if**What you'll build:**-- A local development setup running the full stack (front-end + Vercel functions + Cloudflare workers + database)+- A local development setup running the full stack (front-end + Vercel functions + database + object storage)- A production deployment on Vercel under a custom domain-- Cloudflare workers proxying Anthropic and OpenAI traffic with your own keys+- Anthropic and OpenAI served from your own keys, held server-side in your deployment- An `agent-3d.js` embed script served from your CDN, so embeds on third-party sites point at *your* infrastructure- The full set of environment variables wired correctly across local, preview, and production- A hardening pass: CORS, rate limiting, secret hygiene, audit logging@@ -40,10 +40,12 @@ The platform is intentionally composed of small, independently deployable servic**Serverless functions (Vercel).** Everything under `api/`. Each `.js` file is a Vercel function. These handle: agent CRUD, MCP server endpoint, x402 paid endpoints, ERC-8004 prep/confirm flows, Pump.fun integration, OAuth callbacks, signed-URL avatar storage, etc. The file path is the route — `api/agents.js` becomes `/api/agents`.-**Cloudflare workers (`workers/`).** Edge proxies in front of model providers. The two important ones are:+**Workers (`workers/`).** Everything that doesn't fit in a serverless function. Two distinct kinds live here:-- A general LLM proxy that fronts Anthropic and OpenAI: rate-limits per agent, redacts logs, and lets you swap keys without redeploying the platform-- A Pump.fun MCP worker that maintains live websocket connections to the Pump.fun program (Vercel functions can't hold long-lived sockets cheaply)+- **The Pump.fun MCP worker** (`workers/pump-fun-mcp/`), the one Cloudflare Worker in the tree. It maintains live websocket connections to the Pump.fun program, which Vercel functions can't hold cheaply.+- **GPU model workers** (`workers/model-trellis/`, `workers/rig/`, `workers/remesh/`, and about two dozen more), containers that run 3D generation, rigging, and mesh processing. Each deploys from its own `cloudbuild.yaml` and is only needed if you want the Forge feature it backs.++Model-provider traffic does *not* go through a worker: Anthropic and OpenAI are called directly from the serverless functions, with the keys held in the deployment env.**Database (Postgres).** Stores agents, manifests, accounts, sessions, audit logs, skill access grants, x402 receipts. Schema is checked in.@@ -53,7 +55,7 @@ The platform is intentionally composed of small, independently deployable servic**Embed bundle (`/agent-3d/<version>/agent-3d.js`, also `/dist-lib/agent-3d.js`).** The `<agent-3d>` custom-element bundle, built by `npm run build:lib` from `src/lib.js` into `dist-lib/` and served from the same deployment. Third-party sites load this script tag and your domain ends up in their `<script src="...">`.-Everything except the database and Cloudflare workers can live on a single Vercel project. The minimum production deployment is: 1 Vercel project, 1 Cloudflare worker, 1 Postgres database, 1 R2 bucket.+Everything except the database, object storage, and the workers can live on a single Vercel project. The minimum production deployment is: 1 Vercel project, 1 Postgres database, 1 bucket. No worker is required for the core agent loop; add them only for the Pump.fun feed and the Forge.---@@ -116,19 +118,21 @@ Copy the connection string. It looks like `postgresql://user:pass@host/db?sslmod**Supabase.** Works fine; use the "transaction" pooler URL, not the direct URL, to avoid connection limits in serverless.-Once you have a connection string, run the schema:+Once you have a connection string, put it in your env file as `DATABASE_URL` and bootstrap the database:```bash-psql "$DATABASE_URL" -f api/_lib/schema.sql+npm run db:bootstrap```+Do not apply `api/_lib/schema.sql` by hand. The core schema is only the first of four steps: `db:bootstrap` runs `api/_lib/schema.sql`, then `specs/schema/indexer_state.sql`, then `specs/schema/agent_delegations.sql`, then every incremental migration in `api/_lib/migrations/`. The order matters because later migrations `ALTER` tables the base files create, and a `psql -f schema.sql` alone leaves you with a database that is missing most tables. Every step is idempotent, so re-running it on a live database is a no-op.+Confirm the tables exist:```bashpsql "$DATABASE_URL" -c "\dt"```-You should see tables like `agents`, `accounts`, `sessions`, `audit_log`, `x402_receipts`, `skill_grants`, etc.+You should see tables like `users`, `sessions`, `avatars`, `agent_identities`, `usage_events`, `audit_log`, and `x402_receipts`, plus everything the migrations add (`forge_creations`, `agent_custody_events`, and so on).---@@ -163,19 +167,18 @@ cp .env.example .env.developmentOpen `.env.development` and fill in the values. The file is long; here's the irreducible minimum to get local dev running:-```env-# Front-end-VITE_API_BASE=http://localhost:3000+There is deliberately no front-end API-base variable. The embed bundle derives its API origin from the script's own URL at runtime (Step 11), so nothing about the front-end is baked in at build time.+```env# DatabaseDATABASE_URL=postgresql://...-# Object storage-R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com-R2_BUCKET=three-ws-fork-assets-R2_ACCESS_KEY_ID=<from cloudflare>-R2_SECRET_ACCESS_KEY=<from cloudflare>-R2_PUBLIC_BASE=https://pub-<id>.r2.dev # the bucket's public hostname+# Object storage (S3-compatible; R2 is just one provider that fits)+S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com+S3_BUCKET=three-ws-fork-assets+S3_ACCESS_KEY_ID=<from cloudflare>+S3_SECRET_ACCESS_KEY=<from cloudflare>+S3_PUBLIC_DOMAIN=https://pub-<id>.r2.dev # the bucket's public hostname# Model providers (used by the chat function and the worker proxy)ANTHROPIC_API_KEY=sk-ant-...@@ -191,19 +194,16 @@ X402_ASSET_ADDRESS_BASE=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913X402_MAX_AMOUNT_REQUIRED=1000CDP_API_KEY_ID=CDP_API_KEY_SECRET=-X402_CDP_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402+X402_CDP_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402/facilitatorX402_FACILITATOR_URL_BASE=https://facilitator.payai.networkX402_FACILITATOR_URL_SOLANA=https://facilitator.payai.network-# Session/CSRF secrets — generate fresh with `openssl rand -hex 32`+# Session secret. Generate fresh with `openssl rand -hex 32`SESSION_SECRET=<random hex>-CSRF_SECRET=<random hex>--# Cloudflare worker URLs (set after Step 7)-LLM_WORKER_URL=-PUMPFUN_MCP_WORKER_URL=```+CSRF protection is on by default and derives its token from the session, so there is no separate CSRF secret to set. `CSRF_DISABLED=1` exists as a local-debugging escape hatch; never set it in a deployed environment.+The exhaustive list of env vars is in `.env.example`. Most are optional — you can leave them empty until you need the feature they unlock. For example, you don't need `HELIUS_API_KEY` to run an agent; you only need it if you're enabling the Pump.fun live feed.Do **not** commit `.env.development`. It's in `.gitignore` already; double-check with `git status`.@@ -224,7 +224,7 @@ In another terminal, sanity-check the API:curl http://localhost:3000/api/healthz```-You should see `{"ok": true}` or similar.+You should get a JSON body starting `{"status":"ok","service":"3d-agent",...}`, with `uptime`, the resolved `version`, and a per-subsystem readiness block (`x402`, mail, and so on). Anything other than `"status":"ok"` names the subsystem that is unhappy.Now open `http://localhost:3000` in a browser. You should land on the platform's home page. Click into the editor — drag any GLB onto it — confirm the avatar loads. Open DevTools → Console. **There should be no red errors.** If there are, the most common causes:@@ -238,38 +238,27 @@ If the avatar loads and you can send a chat message that gets a real model respo## Step 7 — Deploy the Cloudflare workers-The LLM proxy worker lives at `workers/` (alongside the strategy executor). The proxy is responsible for:+**There is no LLM proxy worker to deploy.** Model traffic is served by the platform's own serverless functions: `api/chat.js` and `api/brain/chat.js` route through `api/_lib/llm.js` and `api/llm/anthropic.js`, reading `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from the deployment env. Keys stay server-side, rate limiting is enforced by `api/_lib/rate-limit.js` (Step 13), and streaming is handled in the function. Setting those two keys in Step 5 is all the wiring the chat path needs, so this step is optional.-- Holding the production Anthropic/OpenAI keys server-side-- Rate-limiting per agent (so a runaway agent doesn't bankrupt your provider budget)-- Streaming responses back to the browser-- Stripping or appending headers as required--Configure and deploy:+The one Cloudflare worker in the tree is the Pump.fun MCP worker, which exists because Vercel functions cannot hold long-lived websockets cheaply. Deploy it only if you want the Pump.fun live feed:```bash-cd workers-cp wrangler.example.toml wrangler.toml+cd workers/pump-fun-mcp```-Edit `wrangler.toml` and fill in your worker name and the secrets bindings. The example file lists the required vars: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, plus optional Helius keys for the Pump.fun worker.--Set secrets via wrangler (don't put them in `wrangler.toml`):+Its `wrangler.toml` is committed and already configured; every variable is optional and documented in the comment block at the top of that file and in its `README.md`. Set the ones you want as secrets rather than editing them into the file:```bash-wrangler secret put ANTHROPIC_API_KEY-wrangler secret put OPENAI_API_KEY+npx wrangler@4 secret put SOLANA_RPC_URL```Deploy:```bash-wrangler deploy+npx wrangler@4 deploy```-You'll get a URL like `https://three-ws-llm.<account>.workers.dev`. Put that into your `.env.development` and (later) your Vercel project as `LLM_WORKER_URL`.--If you're running the Pump.fun feed, repeat for `workers/pump-fun-mcp/`.+You'll get a URL like `https://pump-fun-mcp.<account>.workers.dev`. The worker is reached directly by the surfaces that use it; there is no worker-URL env var to thread back into the platform.---@@ -290,13 +279,7 @@ This builds:- The `<agent-3d>` embed bundle into `dist-lib/agent-3d.js` (ES module; `npm run build:lib:full` adds the UMD build)- The chat sub-app into `dist/chat/` (via `npm run build:chat`)-Look at `dist/` — there should be an `index.html`, hashed bundles, and the various sub-apps, with the embed bundle in `dist-lib/`. If the build prints warnings about missing env vars (e.g., `VITE_*` vars that the front-end reads at build time), set them before re-running:--```bash-VITE_API_BASE=https://<your-domain>.vercel.app npm run build-```--For preview/staging builds the API base can point at the preview deployment; for production, point it at the final domain.+Look at `dist/`. There should be an `index.html`, hashed bundles, and the various sub-apps, with the embed bundle in `dist-lib/`. Nothing about the API origin is baked in at build time, so the same `dist/` is valid on preview and production alike; the bundle resolves its origin at runtime (Step 11). The handful of `VITE_*` vars that *are* read at build time are third-party client IDs (`VITE_PRIVY_APP_ID`, `VITE_WALLETCONNECT_PROJECT_ID`, `VITE_AVATURN_DEVELOPER_ID`), and each only gates the feature it belongs to. Set the ones whose features you want before re-running the build.---@@ -322,8 +305,8 @@ cat .env.production | vercel env import productionA few env vars that have to be set per-environment:-- `VITE_API_BASE` — must be the public URL of *that* environment (preview, production, etc.)-- `SESSION_SECRET`, `CSRF_SECRET` — use **different secrets per environment**. Don't reuse production secrets in preview.+- `DATABASE_URL`: point preview at a Neon branch database, never at the production one+- `SESSION_SECRET`: use a **different secret per environment**. Don't reuse the production secret in preview.- `X402_PAY_TO_BASE` — use **different wallets per environment** so you can identify which environment generated which receipt.Deploy a preview to validate:@@ -438,7 +421,7 @@ Without Redis, the in-memory fallback works for a single Vercel function instancA few non-negotiables for the env vars you just set:- **Never commit any of them.** `.env.development`, `.env.preview`, `.env.production` are all gitignored. Confirm with `git check-ignore .env.production`.-- **Rotate on personnel changes.** If anyone with access leaves the project, rotate `SESSION_SECRET`, `CSRF_SECRET`, the LLM keys, and the wallet private keys.+- **Rotate on personnel changes.** If anyone with access leaves the project, rotate `SESSION_SECRET`, the LLM keys, and the wallet private keys.- **Use separate keys per environment.** Don't share `ANTHROPIC_API_KEY` between local dev and production — it makes log attribution impossible and one buggy local script can torch the production rate-limit window.- **Sweep wallet balances.** `X402_PAY_TO_BASE` receives USDC. Sweep to a cold address daily or set up an automated sweep transaction.- **CDP keys are sensitive.** Treat them like AWS keys. Coinbase rotates them via the dashboard at any time.@@ -447,22 +430,25 @@ A few non-negotiables for the env vars you just set:## Step 15 — Hardening: audit logging-`api/_lib/audit.js` writes structured records to the `audit_log` table. The platform already writes audit entries for: agent creation, manifest changes, on-chain registrations, x402 payments, skill grants, account-level writes.+`api/_lib/audit.js` writes structured records to the `audit_log` table (created by `api/_lib/migrations/2026-05-01-audit-log.sql`, which `db:bootstrap` applied in Step 3).-In your fork, you'll add audit entries for your own routes:+In your fork, you'll add audit entries for your own routes. `logAudit` is fire-and-forget: it never throws and never adds database latency to the response.```js-import { audit } from './_lib/audit.js';--await audit({- actor: auth.userId, // or wallet address, or null for unauthenticated- action: 'custom.action',- target: targetId,- meta: { request: summarize(req.body) },+import { logAudit } from './_lib/audit.js';++logAudit({+ userId: auth.userId, // null when the actor is unknown or the system+ action: 'delete_avatar', // short kebab-case verb+ resourceId: targetId,+ meta: { reason }, // small JSON blob; avoid PII+ req, // captures IP + user agent});```-Hard rule: every mutation to a user-visible record must produce an audit row. The point isn't compliance for its own sake — it's that when something weird happens (a manifest gets corrupted, a wallet drains, an admin role is granted), the audit trail is the only artifact that survives.+There is an awaitable twin, `logAuditNow(entry)`, which resolves `true` when the row landed and `false` when it was dropped. Use it only where the row itself is the deliverable and the caller reports that outcome (the legal-acceptance endpoints do); everything else wants `logAudit`.++The policy the platform follows: log sensitive state changes that need an after-the-fact "who did what, when" trail: deletions, revocations, ownership transfers. Reads, idempotent updates, and analytics belong in `usage_events` instead, so the audit trail stays legible. The point isn't compliance for its own sake. It's that when something weird happens (a manifest gets corrupted, a wallet drains, an admin role is granted), the audit trail is the only artifact that survives.Export the audit log to long-term storage if your compliance demands it. The schema is plain Postgres; `pg_dump` works.@@ -501,7 +487,7 @@ npm run build # confirm it still buildsgit push origin main```-Vercel auto-redeploys. New schema migrations (if any) land in `api/_lib/migrations/` — re-run them against your database. The repo uses simple forward-only SQL migrations; check the directory's README for the runner script.+Vercel auto-redeploys. New schema migrations (if any) land in `api/_lib/migrations/` as forward-only SQL. Preview what an upstream merge brought in with `npm run db:status`, then apply it with `npm run db:migrate`. Read the status output first: `db:migrate` applies immediately with no dry run, and it applies *every* pending migration, not just the ones you were expecting.If you've forked aggressively and diverged, you may want to keep your changes in a long-running `your-company/main` branch and merge from `upstream/main` periodically with a clear strategy (e.g., quarterly cadence, with a dedicated "merge upstream" PR).@@ -515,9 +501,8 @@ Before you point real traffic at your deployment, walk through this list. If any- `npm run build` passes locally with production env- `/api/healthz` returns 200 on the production URL- A test agent can be created, edited, saved, and embedded-- The LLM proxy worker is deployed and `LLM_WORKER_URL` points to it-- A test chat message gets a real model response in production-- Database schema matches `api/_lib/schema.sql` (run `pg_dump --schema-only` and diff)+- `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` are set in production, and a test chat message gets a real model response there+- `npm run db:status` reports no pending migrations against the production database- Upstash rate-limiting is wired (or you have a clear plan for when to add it)- `X402_PAY_TO_BASE` is a wallet you control and the private key is held securely (hardware wallet, KMS, or equivalent — *not* in plaintext anywhere)- CDP keys are set so x402 settlements route through CDP (otherwise endpoints don't get cataloged in agentic.market)@@ -536,7 +521,9 @@ A few things you should know going in:**Some upstream features require platform-only secrets.** The hosted three.ws has access to API keys and wallets that aren't published. If you fork, those features (e.g., the platform-managed agent treasury) won't work as-is — you'll either disable them or wire your own equivalents. The code paths that depend on platform secrets are clearly conditional on env-var presence; if your env var is empty, the feature is hidden in the UI.-**You become responsible for security patches.** Vercel handles its own infrastructure. You handle the application code. Subscribe to GitHub Dependabot alerts on your fork. The repo lists Apache-2.0 as its license — you can ship patches yourself, but you should also feed them upstream if they're not specific to your deployment.+**Check the license before you deploy anything.** The repo's `LICENSE` is proprietary, not open source: "All rights reserved", with use, copying, modification, and distribution requiring the copyright owner's express written permission. Reading the source is not the same as being licensed to run a fork of it, so get that permission in writing before you stand up a deployment. Everything below assumes you have it.++**You become responsible for security patches.** Vercel handles its own infrastructure. You handle the application code. Subscribe to GitHub Dependabot alerts on your fork, and feed fixes back upstream when they aren't specific to your deployment.**Cost shapes:**@@ -553,7 +540,7 @@ A self-hosted instance with light traffic runs at $20–50/month all-in. The dom## What you learned-- The component breakdown: front-end, Vercel functions, Cloudflare workers, Postgres, R2, CDN+- The component breakdown: front-end, Vercel functions, workers, Postgres, object storage, CDN- How to bring up a development instance with a real database, real model providers, and real wallets- How to deploy to production on Vercel with your own domain and CDN- How to swap the CDN base so third-party embeds point at your infrastructurediff --git a/docs/tutorials/selfie-to-avatar.md b/docs/tutorials/selfie-to-avatar.mdindex 37f4723aa..13c6e0cc8 100644--- a/docs/tutorials/selfie-to-avatar.md+++ b/docs/tutorials/selfie-to-avatar.md@@ -195,7 +195,8 @@ Because the output is a clean, rigged glTF 2.0 file, it isn't locked to three.ws- **Animate it** in the [Animation Studio](/pose) — load it, browse the clip gallery, and retarget motion onto it live. It works because it's rigged.- **Download the GLB** from the avatar page to use it in Unity, Unreal, Blender, or any glTF-aware tool.- **Embed it** on a website with the web component — see [Embed in 30 seconds](/tutorials/embed-in-30-seconds).-- **Refine the look** with [Customize your agent's appearance](/tutorials/customize-appearance) — clothing, accessories, and more layer on without re-rigging.+- **Refine the look** in the avatar editor at `/avatars/<id>/edit`. Clothing and accessories layer on top of the GLB without re-rigging it; [Avatar Creation](../avatar-creation.md) documents how that layering works.+- **Tune how it looks on your site** with [Customize size, position and background](/tutorials/customize-appearance), which covers the embed's layout, framing, and backdrop.---@@ -244,5 +245,5 @@ The result is a standard `.glb` that animates in the [Animation Studio](/pose),- [Turn Photos into a 3D Model](/tutorials/image-to-3d) — reconstruct an *object* (not a person) from a few photos in the Forge.- [Animate your avatar](/tutorials/animate-your-avatar) — apply and tune motion on the rigged avatar you just built.- [Avatar Creation](../avatar-creation.md) — the full reference: every creation path, rig requirements, and accessories.-- [Customize your agent's appearance](/tutorials/customize-appearance) — clothing, accessories, and styling on top of your avatar.+- [Customize size, position and background](/tutorials/customize-appearance): how the finished avatar is framed and placed once it is embedded on a page.- [Give your agent a personality](/tutorials/agent-personality) — turn the body into a character.diff --git a/docs/tutorials/share-your-agent.md b/docs/tutorials/share-your-agent.mdindex 3528a4b8f..35068371e 100644--- a/docs/tutorials/share-your-agent.md+++ b/docs/tutorials/share-your-agent.md@@ -22,18 +22,18 @@ Go to [https://three.ws/my-agents](https://three.ws/my-agents). Sign in if you'rYou see a grid of every agent you own. Click the agent you want to share. The agent's profile page opens at a URL of this shape:```-https://three.ws/agent/<id>+https://three.ws/agent/d94d2a50-86fa-4d2e-b87b-580f7517aa4c```-The `<id>` is your agent's permanent identifier. It looks like a hex string or a slugified handle, depending on how the agent was created. Copy the full URL from the browser's address bar — that's the canonical public link.+The `<id>` is your agent's permanent identifier: a UUID, assigned when the agent is first saved. Copy the full URL from the browser's address bar and it works forever.A few practical notes:- **The URL is permanent.** It does not change when you update the agent's body, personality, name, or skills. Embeds, QR codes, business cards, and conference badges you produce today remain valid indefinitely.-- **The URL is public.** Anyone with the link can open it. There is no login required to talk to a public agent.-- **The URL is canonical.** Even if the platform's user-facing URL structure ever evolves, the agent ID itself is a stable platform reference. Old links continue to redirect.+- **The URL is public.** Anyone with the link can open it. There is no login required to talk to an agent.+- **`/agent/<id>` redirects to `/agents/<id>`.** The profile page's canonical address is the plural form, and the singular one issues a permanent redirect to it. Both are safe to hand out; links printed years ago keep resolving.-If you ever forget the URL, the "Copy share link" button on the agent profile page copies the canonical version to your clipboard.+There is a **Share** button on the profile page: one floating above the fold on the hero, one in the action row. Either opens a share panel that shows the exact card your link will unfurl as, with **Copy link**, **Share on X**, **Share on Farcaster**, and **Remix in three.ws**. The link it copies is the share URL from Step 3, not the bare profile URL, because that is the one carrying the rich preview.Every public agent is also in the platform's own directory, which is a plain open endpoint. Press the button and you are looking at the live directory, portrait and all, the way it exists as you read this:@@ -105,57 +105,81 @@ Don't tint both foreground and background; the contrast will drop too low and scWhen you paste your agent URL into iMessage, WhatsApp, Slack, Discord, Telegram, Twitter / X, LinkedIn, Bluesky, Mastodon — every modern chat and social platform fetches the URL, extracts a preview, and shows the recipient a card with a title, description, and image. The right preview can be the difference between a recipient clicking the link and ignoring it.-three.ws sets Open Graph and Twitter Card meta tags automatically on every agent page. You do not need to configure anything for the previews to work — they ship by default.+three.ws builds those tags automatically. You do not configure anything for the previews to work, but you do need to share the right URL.++### Share the `/share` URL, not the bare profile URL++The agent profile page at `/agent/<id>` is a JavaScript app. Its HTML carries the generic three.ws card, because at the moment a crawler fetches it, the page has not yet loaded which agent it is about. So the platform serves a second, server-rendered address purely for crawlers:++```+https://three.ws/agent/<id>/share+```++That page is plain HTML with your agent's real meta baked into the `<head>`, and a redirect that sends a human straight on to `/agent/<id>`. A recipient who taps the link never sees it; the unfurler does. This is the URL the Share button copies, and the one to paste anywhere a preview matters.### What the previews contain-When a platform fetches `https://three.ws/agent/<id>`, it sees:+When a platform fetches `https://three.ws/agent/<id>/share`, it sees:-- **og:title** — Your agent's name. Example: "Iris".-- **og:description** — Your agent's one-line description from the editor. Example: "Personal AI guide for Lumen customers."-- **og:image** — A pre-rendered preview image of the agent. This is generated automatically the first time someone shares the URL, then cached on the platform CDN.-- **og:url** — The canonical public URL of the agent.-- **og:type** — `website`.-- **twitter:card** — `summary_large_image`, so the Twitter preview shows the big-image card.-- **twitter:title**, **twitter:description**, **twitter:image** — Twitter-specific duplicates of the OG fields.+- **og:title**: `<agent name> · 3D AI Agent · three.ws`, or `<agent name> · 3D AI Agent on <chain> · three.ws` when the agent has been deployed on-chain.+- **og:description**: Your agent's description (first 120 characters), the chain it is deployed on if any, then `3D AI Agent on three.ws`.+- **og:image**: Your avatar's rendered thumbnail when the avatar's visibility is public or unlisted. Otherwise a generated SVG card from `/api/og/agent?id=<id>` carrying the agent's name and its chain badge.+- **og:url**: The `/share` URL itself. **og:type** is `profile`.+- **twitter:card**: `summary_large_image`, so X renders the big-image card, alongside `twitter:title`, `twitter:description`, and `twitter:image`.+- A **Farcaster Frame** block, so the same link renders as a frame in Farcaster clients.+- A **link rel="alternate" oEmbed** pointer at `/api/oembed`, so embedders that speak oEmbed can resolve the agent without scraping.-The preview image is a still render of your agent — same body, same lighting as the live page, framed for the 1200×630 standard OG image aspect. The agent's name is composited onto the corner of the image. The whole thing reads as "this is an agent you can talk to" without the recipient having to open the link first.+Both image paths target the 1200x630 standard OG aspect.-### How the preview image is generated+There is also a wallet variant, `/agent/<id>/share?wallet=1`, which swaps the copy and the deep link over to the agent's wallet view and always uses the generated card (the card is what carries the wallet identity). Use it when the thing you are sharing is the agent's wallet rather than the agent.-When an OG-fetcher (iMessage's link-unfurler, Slack's link preview service, Twitter's card scraper) hits your agent's URL for the first time, the platform spins up a headless WebGL renderer, loads the agent's GLB, renders a single high-quality frame against a neutral background, composites the name on top, and saves the result to the CDN. The whole render takes about two seconds.+### Preview freshness-After that first render, the image is cached on the CDN for ~24 hours. So:+Nothing is pre-rendered and nothing needs purging. The share page is generated per request from the agent's current row in the database, and the generated card is drawn on demand:-- The first share of a brand-new agent will see a "loading" image for a few seconds (most platforms show their own placeholder during this window)-- Subsequent shares within ~24 hours are instant — the cached image is served-- After 24 hours, the next share triggers a re-render. This is useful: if you've swapped the agent's body in Studio, the new body shows up in social previews within a day automatically+- The share page is cached `max-age=60` in the browser and `s-maxage=600` at the edge, with a one-hour stale-while-revalidate window.+- The generated SVG card is cached `max-age=180` / `s-maxage=900`, with a two-minute stale-while-revalidate window.-If you need an instant re-render — say, you've changed the agent's body for a launch and want fresh previews — there's a "Refresh preview image" button on the agent profile page that purges the CDN cache and forces a fresh render on the next share.+So a rename, a description edit, or a body swap shows up in new previews within minutes, with no button to press. The lag you are more likely to hit is on the other side: X, Slack, and Facebook each cache what they scraped, sometimes for days. That is what the debuggers below are for.### Verifying the preview before sharing-Don't ship a link without testing the preview first. Run the URL through a debugger:+Don't ship a link without testing the preview first. There are three levels of check, cheapest first.++**The share panel.** Open your agent's profile page and click **Share**. The panel renders the real card image at the top, so you see what the link unfurls as before you send it anywhere.-- [Twitter Card Validator](https://cards-dev.twitter.com/validator) — Paste the URL, see the preview Twitter will render.-- [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/) — Same for Facebook, Messenger, WhatsApp, and Instagram.-- [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/) — Same for LinkedIn.+**Read the tags yourself.** One command, no third party, no cache in the way:-Run your agent URL through at least Twitter and Facebook before a big share. If a preview looks wrong, the most common causes are:+```bash+curl -s https://three.ws/agent/YOUR_AGENT_ID/share \+ | grep -o '<meta[^>]*og:[^>]*>'+```++You should see your agent's name in `og:title` and a real image URL in `og:image`. If `og:title` says "Agent" and nothing else, the agent's name is unset.++**Platform debuggers**, for when a specific network is showing something stale:++- [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/): Facebook, Messenger, WhatsApp, and Instagram. Has a "Scrape Again" button.+- [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/): LinkedIn, with the same re-inspect behaviour.+- [Twitter Card Validator](https://cards-dev.twitter.com/validator): X's card preview. It now requires a logged-in developer account, so the `curl` check above is usually faster.-- The agent's name or description is unset in the editor → set them-- The preview image hasn't generated yet → wait one minute and retry-- A platform has cached an old version → use the platform's debugger (each tool above has a "re-scrape" button)+If a preview looks wrong, the causes in order of likelihood are:++- **You shared `/agent/<id>` instead of `/agent/<id>/share`.** That gets the generic three.ws card. This is by far the most common one.+- **The agent's name or description is unset** → set them in the editor and re-check.+- **The avatar is private**, so the card falls back to the generated SVG rather than your avatar's thumbnail → set the avatar's visibility to unlisted or public in the [avatar dashboard](/dashboard/avatars).+- **A platform cached an old version** → use its debugger's re-scrape button.### Customising the preview-Most agents look right with the default preview. If you want to customise:+The card is assembled from the agent's own record, so you customise it by editing the agent, not by editing a preview setting:-- The **name** is read from the agent's name field in the editor.-- The **description** is read from the agent's description field in the editor.-- The **image background** can be set per agent in the editor's Brand panel: a solid colour, a gradient, or a fixed background image upload. The agent body composites in front.+- The **name** is the agent's name field in the editor. It becomes `og:title`.+- The **description** is the agent's description field. It becomes `og:description`, truncated to the first 120 characters, so put the point first.+- The **image** is your avatar's thumbnail when the avatar's visibility is public or unlisted. Swap the agent's body (see [Pick and swap an avatar in Studio](/tutorials/swap-avatar-in-studio)) and the card follows within minutes.+- The **chain badge** appears by itself once the agent is deployed on-chain, both in the title and on the generated card.-Keep the name short (under 30 characters) and the description specific (under 120 characters). Both render onto the image; long strings overflow and the platform clips them.+Keep the name short and the description specific and front-loaded. Long strings are clipped, not wrapped.---@@ -168,7 +192,7 @@ Each platform has its own conventions. Here is what works on each.A line of plain text at the bottom of your email signature is the most under-used share context for personal agents.```-Talk to my AI: https://three.ws/agent/YOUR_AGENT_ID+Talk to my AI: https://three.ws/agent/YOUR_AGENT_ID/share```The recipient sees the link and the email client unfurls a preview card if it supports OG (Gmail, Apple Mail, Outlook all do). For agents that represent you personally, this is a way to let every email recipient interact with your AI persona without an explicit invite.@@ -178,7 +202,7 @@ The recipient sees the link and the email client unfurls a preview card if it suA simple post with the URL works, but the engagement is higher if you give context:```-Built a 3D AI agent that knows my work. Ask it anything → https://three.ws/agent/YOUR_AGENT_ID+Built a 3D AI agent that knows my work. Ask it anything → https://three.ws/agent/YOUR_AGENT_ID/share```X expands the URL into a large image card. The agent's preview image shows. Don't add a screenshot — let the auto-preview do the work; otherwise the platform sometimes hides the card.@@ -190,7 +214,7 @@ LinkedIn's link unfurling is conservative. The post performs better if you write```I built a personal AI assistant that visitors can talk to instead of reading my "About me" page. It knows my work, my availability, and what I'm building right now.-Try it: https://three.ws/agent/YOUR_AGENT_ID+Try it: https://three.ws/agent/YOUR_AGENT_ID/share```LinkedIn shows the preview card below your post. Engagement is highest within the first few hours, so post during your network's morning timezone.@@ -274,7 +298,7 @@ Your share strategy:1. **Embed on your portfolio site** — Following [Embed in 30 seconds](/tutorials/embed-in-30-seconds), you've added the one-line embed to the home page of your portfolio. Visitors can talk to Mara without leaving your site.-2. **Public link in your email signature** — At the bottom of every email you send: "Available 24/7 to chat about projects → https://three.ws/agent/mara-uxconsultant". Recipients can talk to Mara even when you're asleep.+2. **Public link in your email signature.** At the bottom of every email you send: "Available 24/7 to chat about projects → https://three.ws/agent/<MARA_ID>/share". Recipients can talk to Mara even when you're asleep, and the mail client unfurls her card inline.3. **QR on the back of your business card** — At networking events, instead of "I'll email you next week", you say "Scan my card, ask Mara about my work, and book a call directly through her if it's a fit". The conversation happens on your terms, on her schedule.@@ -298,19 +322,25 @@ A few practical implications:- **Tell the agent what it can and cannot say.** A line like "Never share my home address, phone number, or contract rates" in the system prompt is followed reliably by modern LLMs.- **Memory is private to your agent's record on the platform.** It's not shared with other agents and not visible to other users. But you, the owner, can see conversation logs in the editor.-If you want a private agent — one that only lives on a specific embed and isn't reachable from a public URL — toggle the "Public profile" switch off in the editor's settings panel. The agent ID still works for embeds; the public profile URL returns a 404. This is the right setting for internal tools, B2B-only embeds, and any agent that should not be discoverable.+**There is no private-profile switch, and this matters.** Every saved agent has a reachable profile page. What you *can* control is discoverability and assets, which are two separate settings:++- **Marketplace listing.** An agent is unpublished until you publish it, and only published agents appear in the [marketplace](/marketplace) and its category browsing. Unpublishing removes an agent from the directory; it does not close the profile URL.+- **Avatar visibility.** Your avatar has its own private / unlisted / public setting in the [avatar dashboard](/dashboard/avatars). A private avatar is not served from any public endpoint, which is also why the agent's social card falls back to the generated SVG rather than the avatar's thumbnail.++So plan on the URL being reachable by anyone who has it. For genuinely internal tooling, do not put the knowledge in a hosted agent's system prompt at all.---## What you learned-- Every agent has a permanent public URL at `https://three.ws/agent/<id>`+- Every agent has a permanent public URL at `https://three.ws/agent/<id>`, where the id is a UUID- The URL is stable across body swaps, system prompt updates, and skill changes+- Rich previews come from `https://three.ws/agent/<id>/share`, a server-rendered page that carries the agent's real Open Graph, Twitter Card, and Farcaster Frame meta and forwards humans to the profile+- The Share button on the profile page shows that card and copies the `/share` link for you+- Nothing is pre-rendered and nothing needs purging: edits appear in new previews within minutes, and the stale copy you see is usually the sharing platform's own cache- A QR code generated from any standard service points to that URL for offline share-- Open Graph and Twitter Card meta tags are set automatically, with a pre-rendered preview image-- Social preview images are generated on first share, cached 24 hours, and can be force-refreshed- The three share formats — embed, link, QR — are complementary; a complete strategy uses all three-- Public agents are genuinely public; configure the system prompt and skills accordingly, or toggle the public profile off for private use cases+- Every agent profile is reachable by anyone with the link; discoverability is controlled by marketplace publishing, and asset exposure by avatar visibilityThe agent's URL is the durable handle. Embed it, link it, print it. The agent shows up everywhere, identical, maintained from a single source of truth.diff --git a/docs/tutorials/sperax-tour.md b/docs/tutorials/sperax-tour.mdindex a21d893ab..7ba471b09 100644--- a/docs/tutorials/sperax-tour.md+++ b/docs/tutorials/sperax-tour.md@@ -45,7 +45,7 @@ Click **⬇ Get the code**. Because a partner template targets a real, already-b**2. Drop the tag on the page.** Paste the generated `<script>` tag right before `</body>`, swapping the placeholder URL for the one from step 1:```html-<script src="https://unpkg.com/@three-ws/[email protected]/dist/tour.global.js"+<script src="https://unpkg.com/@three-ws/[email protected]/dist/tour.global.js"data-tourdata-curriculum="https://cdn.sperax.io/tour/curriculum.json"defer></script>diff --git a/docs/tutorials/swap-avatar-in-studio.md b/docs/tutorials/swap-avatar-in-studio.mdindex 681cfbcd9..90f975c43 100644--- a/docs/tutorials/swap-avatar-in-studio.md+++ b/docs/tutorials/swap-avatar-in-studio.md@@ -1,251 +1,185 @@# Pick & swap an avatar in Studio-Your agent has a mind: a name, a personality, a set of skills, memory, and a wallet. Separately, your agent has a body: a 3D model that visitors see and interact with. The platform keeps these two things distinct on purpose. The mind is the durable identity. The body is a presentation choice that you can change at any time without affecting the rest.+Your agent has a mind: a name, a personality, a set of skills, memory, and a wallet. Separately, your agent has a body: a 3D model that visitors see and interact with. The platform keeps these two things distinct on purpose. The mind is the durable identity. The body is a presentation choice you can change at any time without affecting the rest.-Widget Studio is where you make that choice. You open it, browse the gallery, preview the candidate bodies on top of your agent's actual brain, and pick the one you want live. The snippet you've already embedded on your customer's site does not change. The next time the page loads, the new body is what visitors see.--This tutorial walks through the full Studio flow, explains what changes server-side versus snippet-side when you swap, and shows you how to maintain a small library of swappable bodies for the same agent.+This tutorial covers both halves of that. You swap the body in the agent editor's **Outfit** panel, in one click. Then you take the result into **Widget Studio**, which is a different surface with a different job: turning any avatar into an embeddable widget.**What you'll build:**-- A working understanding of how Studio fits between editor and embed-- A swap of your agent's body to a different avatar, live, in under five minutes+- A swap of your agent's body to a different avatar, live, in under a minute- A small personal library of avatars you can rotate between for seasons, campaigns, or audiences+- A widget built in Studio from the avatar you picked- The mental model for separating identity (the agent) from presentation (the avatar)**Prerequisites:** A saved agent on three.ws. If you've worked through [Embed in 30 seconds](/tutorials/embed-in-30-seconds), you already have one.----## Step 1 — Open Widget Studio--Go to [https://three.ws/studio](https://three.ws/studio). Sign in if you're not already.+## Step 1: Know which surface does what-Studio opens with a split layout. On the left is your agent — already loaded, animating, ready. On the right is the avatar gallery: a grid of 3D bodies the platform hosts, your own uploads, and any community-published avatars you can use freely.+Two surfaces have "studio" energy and they are often confused. They do not overlap:-If you have more than one agent in your account, there's an agent selector at the top of the left panel. Pick the one you want to modify; the rest of the page updates to show that agent's current body.+| Surface | Where | What it changes |+| --- | --- | --- |+| **Agent editor, Outfit panel** | `/agent/<id>/edit` | The agent's own body, animation set, and animation states. This is where a swap happens. |+| **Widget Studio** | [/studio](/studio) | Builds a standalone embeddable widget from an avatar. Does not modify any agent. |+| **Avatar dashboard** | [/dashboard/avatars](/dashboard/avatars) | Creates, names, deletes avatars, and sets each one's visibility. |-> The studio is genuinely a "studio" rather than a settings page. You can spend ten minutes in here just trying bodies on, the same way you'd browse outfits in a fitting room. Nothing is final until you save.+If you are trying to change what your embedded agent looks like, you want the first row. Studio is Step 6.----## Step 2 — Understand the gallery's structure--The avatar gallery has a few visible sections worth knowing about. They control what shows up when you search and where new avatars come from over time.--### Platform avatars--The default tab. These are bodies the three.ws team curates: a balanced set of styles (realistic, stylised, abstract), gender presentations, ethnicities, and aesthetic moods. They're stored on the platform's CDN, optimised for fast load, and tested for animation compatibility — every animation in the standard library plays correctly on every platform avatar.--You can filter by:--- **Style** — realistic, stylised, low-poly, geometric, abstract-- **Use case** — support, hero, mascot, narrator, professional-- **Polygon count** — useful if you're embedding on a low-end-device-heavy site--Click any tile to preview the avatar on your agent — the left panel updates in real time, and your agent's actual greeting and idle animations play on the new body.--### Your uploads+## Step 2: Open the Outfit panel-If you've ever uploaded a GLB through the editor or the upload flow, those files appear here under "Your avatars". The platform stores them on its CDN with the right CORS headers so the embed loader can fetch them from anywhere.+Open [https://three.ws/my-agents](https://three.ws/my-agents) and click the agent you want to change. On its profile page, click **✏ Edit Agent** (visible to you as the owner). That lands you on `/agent/<id>/edit`.-If you haven't uploaded anything yet, this section is empty and the studio shows a hint pointing to the upload flow. Custom uploads are covered in their own tutorial — for this one, we stick with platform and community avatars.+Scroll to the **Outfit** panel. It has three sections stacked in order:-### Community avatars+- **Avatar**: the grid of bodies you can put on this agent. This is the one this tutorial is about.+- **Animations**: which clips from the three.ws animation library this agent is allowed to play. Changing this needs an explicit **Save selection**.+- **Animation states**: which clip plays in each behaviour state, so the avatar crossfades sensibly as it speaks, walks, and reacts. Saved with **Save states**.-Avatars that other three.ws users have published as freely usable. This section grows over time. Each tile shows the creator's handle and a license note (most community avatars are CC-BY or CC0). Click the creator handle to see their full set.+A live 3D preview of the agent sits in the left column, so you are always looking at the current body while you work.----## Step 3 — Preview before committing+## Step 3: Read the avatar grid-This is the single most important habit to form when working with Widget Studio: preview every candidate body fully before saving. Click on each candidate and let it run for at least twenty seconds in the preview panel. You'll notice things you'd otherwise miss.+The grid lists the avatars on your account, newest first, up to fifty. Each tile shows the avatar's thumbnail and name. The body currently on this agent carries a **Current** badge, so you never have to guess which one is live.-The preview panel runs your agent's actual configuration on the new body. So you see:+Two things sit alongside the grid:-- How the avatar holds its head while idle-- How it gestures when speaking-- How the wave clip looks (try clicking "Wave" in the preview controls)-- How the talk-mouth animation reads — some stylised characters have very expressive mouth shapes, others almost none-- Whether the lighting in the scene flatters this particular model+- A **Create new** tile (the `+`). It opens a menu with the four real ways to get a new body: **three.ws Studio** (the in-browser builder for hair, clothing, and body), **three.ws Selfie** (a photo becomes a photoreal avatar, covered in [Turn a selfie into a 3D avatar](/tutorials/selfie-to-avatar)), **Upload GLB** (bring your own model), and **Browse public gallery** (pick from community avatars).+- A **Manage in dashboard ›** link to [/dashboard/avatars](/dashboard/avatars), where you rename, delete, and set visibility.-A few practical checks that pay off:+If you have no avatars yet, the grid says so and points you at the dashboard instead of showing an empty box.-- **Wave test** — Every avatar should be able to wave. If the wave looks broken (arm goes through the chest, hand stays at the side), the avatar's rig is incomplete; pick a different one.-- **Talk test** — Type a sentence into the preview chat input. The avatar should move its mouth and gesture lightly. If it doesn't, the talk animation isn't bound; pick a different one.-- **Idle test** — Watch the avatar for twenty seconds with no input. The idle should feel natural, not robotic. Notice the breathing, the small head turns, the weight shifts.+----When something feels right, you'll know — the preview panel feels like a real conversation rather than a mannequin.+## Step 4: Perform the swap----+Click a tile. That is the whole interaction.-## Step 4 — What happens when you swap+There is no confirmation dialog and no separate save button for the avatar: the click sends the change immediately, the status line under the heading reads `Saving…` and then `Saved.`, the **Current** badge moves to the tile you picked, and the 3D preview reloads on the new body. If something goes wrong, the same line shows the error rather than failing silently.-This is the part most people get wrong on their first try, and the part the studio is most useful for clarifying. Here is what changes — and, just as importantly, what does *not* change — when you save a new body.+Under the hood that click is one request:-### Server-side: the agent record updates+```+PUT /api/agents/<agent-id>+Content-Type: application/json-The platform stores each agent as a record. The record has:+{ "avatar_id": "<the avatar you clicked>" }+```-- An agent ID (permanent, never changes)-- A name-- A personality / system prompt-- A skills list-- A memory configuration-- A wallet-- And a pointer to a body — that pointer is a URL of a GLB file+The call is owner-scoped, so you can only re-body agents you own.-When you save a new body in Studio, the only field that changes in that record is the body URL. Everything else — name, personality, skills, memory, wallet, the ID — stays exactly as it was. The agent is the same entity. It just dresses differently.+### What changes, and what does not-### Snippet-side: nothing changes+The platform stores each agent as a record holding its ID, name, personality, skills, memory configuration, wallet, and a pointer to a body. **A swap changes only the body pointer.** Name, personality, skills, memory, wallet, and the agent ID are untouched. The agent is the same entity, and a returning visitor's conversation history is still there. It just dresses differently.-This is the crucial property. Your embed snippet is:+Your embed snippet does not change either:```html<script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js"></script><agent-3d agent-id="YOUR_AGENT_ID" mode="floating"></agent-3d>```-There is no body URL in this snippet. The `<agent-3d>` element references the agent by its ID, and the embed runtime fetches the current body URL from the platform every time a visitor loads the page. When you swap the body in Studio, the next page load returns the new body. The customer site doesn't need to be re-deployed, the snippet doesn't need to be edited, the cached HTML on Cloudflare doesn't need to be purged.--This is by design and it's worth pausing on, because it changes how you operate at scale. You can:--- Run a seasonal avatar swap across hundreds of customer sites in one click-- A/B test two different bodies for the same brain across two agent IDs without touching any client code-- Replace a corrupted GLB at the source and have every embed self-heal on next page load-- Move from a placeholder avatar to a final-art avatar mid-campaign without coordinating a single deploy--Once the snippet is in place, the body lives entirely in the platform's control.--### What about cached GLBs?--The platform serves GLBs with reasonable cache headers — typically a few hours of freshness, then revalidate. When you save a swap in Studio, visitors who already have the page open keep the old body until they refresh. Visitors who arrive after the swap get the new body within at most an hour or two (and usually immediately, because most CDN edges revalidate on every miss).+There is no body URL in that snippet. The `<agent-3d>` element references the agent by ID and resolves the current body from the platform on every page load. Swap the body and the next page load shows it: no redeploy, no snippet edit, no cache purge on the customer's site.-If you need an instant swap — say, you're fixing a visibly broken avatar for an important demo — the platform exposes a "Bust cache" button in Studio's save dialog. Use it sparingly; it forces every CDN edge to refetch.+This is what makes the pattern useful at scale. You can run a seasonal swap across every site that embeds you in one click, replace a broken GLB at the source and have every embed self-heal on the next load, or move from a placeholder body to final art mid-campaign without coordinating a single deploy.------## Step 5 — Perform a swap+### Why there is nothing to purge-Time to do the thing. With the studio open and your agent loaded:+Two caching facts make the swap effectively instant, and it is worth knowing them so you do not go hunting for a cache-busting button that does not exist:-1. **Pick a candidate.** Browse the gallery, click an avatar that matches the mood you want.-2. **Preview thoroughly.** Use the controls under the preview panel — Wave, Idle, Greet, Talk — and try at least the first three.-3. **Click Save** in the preview panel's footer. A confirmation dialog appears with two options: **Save** (default cache behaviour, fast and free) or **Save and bust cache** (instant propagation, use only when needed).-4. **Click Save.** The platform updates the agent record. The dialog closes.-5. **Open your embedded page in a new tab.** The new body appears.+- The agent record is served `Cache-Control: no-store`, so a page load always reads the current body pointer. There is no stale-manifest window.+- Each avatar is a distinct object at a distinct URL, so a swap points at a different file rather than replacing the bytes behind one. GLBs are served long-lived on purpose (`public, max-age=604800, stale-while-revalidate=2592000`), with `Access-Control-Allow-Origin: *` and `Content-Type: model/gltf-binary`, so the old body stays cached for the visitors still on it and the new body is fetched fresh.-That's the whole flow. In practice, on a real connection, a swap takes about ten seconds from click to live.+The only visitors who keep seeing the old body are the ones with the page already open, and only until they refresh.----## Step 6 — Build a personal avatar library+## Step 5: Build a personal avatar library-Studio is not just for one-off swaps; it's also where you maintain a small library of bodies you cycle between for different contexts. A few patterns that pay off.+The Outfit grid is your library, so it pays to keep a few deliberate bodies in it rather than one.### Seasonal swaps-Holiday avatars are a small detail that visitors notice. A "winter outfit" body for December and January, a "summer / outdoor" body for the warmer months, a "back to school" body in September. The brain is unchanged — your agent's personality persists across seasons. Only the appearance shifts. Use Studio's preview to make sure the seasonal avatar still feels like the same character (similar build, hair colour, posture); otherwise visitors will feel a discontinuity.+Holiday avatars are a small detail visitors notice: a winter body for December and January, a summer body for the warmer months. The brain is unchanged, so your agent's personality persists across seasons. Use the live preview to check the seasonal body still reads as the same character (similar build, hair colour, posture), otherwise visitors feel a discontinuity.### Campaign avatars-If you run product launches, your agent can wear a launch-themed body for the launch week. Examples: a body holding the new product, a body wearing the launch t-shirt, a body in the launch's colour palette.--### Audience-specific avatars+If you run product launches, your agent can wear a launch-themed body for launch week: holding the new product, wearing the launch shirt, or in the launch's colour palette.-You can run two agents with the same brain and different bodies, embedded on different pages:+### Audience-specific agents-- `agent_dev_id` — wears a developer-coded body, embedded on your docs and changelog-- `agent_sales_id` — wears a polished body, embedded on your marketing and pricing pages+Run two agents with the same personality and different bodies, embedded on different pages: a developer-coded body on your docs and changelog, a polished one on marketing and pricing. Same brain, different perceived audience. Create the second agent from [My Agents](/my-agents), then set its body here.-Both agents have the same personality, the same memory, the same skills. Only the body — and therefore the perceived audience — differs. The split is set up by duplicating the agent in My Agents at [https://three.ws/my-agents](https://three.ws/my-agents) and then using Studio to pick the right body for each clone.+### A test body-### Test bodies--It's useful to keep one "test" body in your library — something visually distinct, like a bright-coloured low-poly character — that you swap to when you're verifying a deployment. You can tell at a glance whether the page is showing the test body (deployment worked, cache busted, embed is live) or the production body (it's serving stale).+Keep one visually unmistakable body, such as a bright low-poly character, and swap to it when you are verifying a deployment. You can tell at a glance whether a page is serving the new build or a stale one.----## Step 7 — How the platform serves avatars--A short technical note for engineers, in case it matters for your stack.--Every platform avatar and every user upload is stored in the three.ws CDN, served from edge nodes globally. The URL format is approximately:--```-https://three.ws/cdn/avatars/<hash>.glb-```+## Step 6: Take the avatar into Widget Studio-The hash is a content-addressable digest, which means the same GLB always has the same URL, and uploading a new version generates a new URL. The agent record stores the current URL; Studio updates that pointer when you swap.+[Widget Studio](/studio) is the other half of the story. It does not touch your agents; it turns an avatar into a self-contained embeddable widget with its own URL and snippet. It runs as four numbered steps across three columns.-Headers served on every GLB:+**1. Pick avatar.** Your own avatars appear here, but only the ones whose visibility is public or unlisted (a widget is served to strangers, so a private avatar cannot back one). Set visibility in the [avatar dashboard](/dashboard/avatars). There is also a search box for browsing public avatars, and a demo agent is pre-loaded so you can try the studio before signing in.-- `Access-Control-Allow-Origin: *` — so the embed loader can fetch the file from any customer domain-- `Cache-Control: public, max-age=86400, must-revalidate` — one-day freshness with revalidation-- `Content-Type: model/gltf-binary` — correct MIME type for GLB+**2. Pick widget type.** Each type is a different layout, not a different avatar:-Files are not gzipped (GLBs are already binary-packed and don't benefit) but textures inside the GLB are compressed using KTX2 / Basis when present.+- **Turntable Showcase**: hero banner, auto-rotate, no UI.+- **Animation Gallery**: click through every clip on a rigged avatar.+- **Talking Agent**: embodied chat, your agent on your site.+- **ERC-8004 Passport**: on-chain identity card for any agent.+- **Hotspot Tour**: annotated 3D scene with clickable points of interest.+- **Walking Avatar**: a roaming avatar visitors steer with a joystick or the keyboard.+- **Pump.fun Live Feed**, **Smart Money Feed**, **Live Trades Canvas**, **Bonding Curve**: live market surfaces narrated or visualised by the avatar.-The "Bust cache" save option in Studio sends a purge signal to the edge network, which clears the cached object on every edge node usually within ten seconds.+**3. Brand.** Colours, environment, captions, and behaviour, with the middle column previewing every change live. The preview has a desktop / tablet / mobile switcher, and a **Use current view** button that locks whatever camera angle you have dragged to as the widget's default framing.-This matters in two cases:+Then **Generate**. A modal opens with the widget's live URL, a width and height, and two copy-ready snippets: an `<iframe>` and a script tag. **Save draft** keeps work in progress without publishing.-- You're embedding on a customer site with a strict CSP. Add `https://three.ws` to `connect-src` and you're done.-- You're embedding on a site behind a corporate proxy that strips `Access-Control-Allow-Origin`. The proxy needs to be configured to let three.ws responses through unmodified.+The important distinction: a widget built here is pinned to the avatar you chose. Swapping your *agent's* body in Step 4 does not re-point an existing widget. If you want the widget to follow the agent, use the **Talking Agent** type, which is backed by the agent rather than by a bare avatar.----## Step 8 — A worked example--Let's run through a realistic scenario end to end.--Imagine you're running an online cooking school called "Hearth". You have a single agent named "Chef Olive" — friendly, knowledgeable, helps visitors pick the right course. Your agent is embedded on three pages: the home page, the course catalogue, and the pricing page. The current avatar is a stylised character in chef's whites — clean, professional, on-brand.--For your spring promotion, you want to swap the avatar to one wearing a green apron with a fresh-greens basket — same character build, same posture, same hair, but a clearly springtime variant. The agent's voice, personality, course knowledge, and memory of past conversations all stay the same.--Here's the flow:--1. Open [https://three.ws/studio](https://three.ws/studio). Select Chef Olive in the agent selector.-2. In the gallery, type "chef" in the search box. A handful of chef-style avatars surface, including the current production one.-3. Click the spring-apron candidate. The preview panel updates. Chef Olive — same voice, same greeting — appears in the new body.-4. Run the previews: wave, idle, talk. They all read well.-5. Click **Save**. Choose normal save (no cache bust — your spring campaign isn't time-critical).-6. Open the live home page in a private window. Chef Olive appears in the spring apron.--Visitors who land on the page during the next hour see the new body. Past conversation history is unchanged — a returning visitor who chats again finds Olive remembers their previous questions, just dressed differently for the season.--When the promotion ends, you return to Studio, swap back to the original whites, and save. The agent is back in its everyday outfit. No client code touched. No customer notified. No deploy run.-----+## Step 7: A worked example-## Step 9 — When to use Studio versus the full editor+You run an online cooking school called "Hearth", with a single agent named "Chef Olive" embedded on your home page, course catalogue, and pricing page. The current body is a stylised character in chef's whites.-A small clarification, because new users often conflate the two surfaces.+For a spring promotion you want a green-apron variant: same character build, same posture, clearly springtime. Olive's voice, personality, course knowledge, and memory all stay the same.-The **editor** at [https://three.ws/create](https://three.ws/create) is where you set the agent's identity: name, personality, skills, memory, wallet, voice. It's a designer surface for the brain.+1. Open [My Agents](/my-agents), click Chef Olive, click **✏ Edit Agent**.+2. Scroll to **Outfit**. The current whites tile carries the **Current** badge.+3. Click the spring-apron tile. The status line reads `Saved.` and the preview reloads on the new body.+4. Open your live home page in a private window. Olive is in the spring apron.-**Studio** at [https://three.ws/studio](https://three.ws/studio) is where you tune the agent's appearance: the body and the embed presentation. It's a designer surface for the visual layer.+Total elapsed time is a few seconds, and no client code was touched. When the promotion ends, click the whites tile again.-There is some overlap — Studio shows you which body is currently set, and the editor shows you a preview of the agent — but the principle is: brain in editor, body in studio. If you find yourself trying to write a system prompt in Studio or pick a body from the editor, you've taken the long way; switch surfaces and the right controls appear.+Note what did *not* happen: no deploy, no cache purge, no customer notified, and no loss of conversation history. A returning visitor finds Olive remembers their previous questions, just dressed differently.---## What you learned-- Widget Studio at [https://three.ws/studio](https://three.ws/studio) is the home for swapping an agent's body-- The platform separates the agent (mind, identity, wallet, memory) from the avatar (3D body, presentation)-- A swap updates one field on the server-side agent record and changes nothing about the embed snippet on customer sites-- Cache propagation is automatic within an hour, or instant with the "Bust cache" option-- A small personal library of avatars — seasonal, campaign, audience-specific, test — pays off for any agent you run beyond a single use case-- Avatars are served from the three.ws CDN with the right CORS and cache headers for embed use+- The body swap lives in the agent editor's **Outfit** panel at `/agent/<id>/edit`, not in Widget Studio+- Clicking an avatar tile saves immediately: one `PUT /api/agents/<id>` carrying `avatar_id`, with the **Current** badge and the live preview confirming it+- A swap changes one field. Name, personality, skills, memory, wallet, and the agent ID are untouched+- The embed snippet never changes, because `<agent-3d agent-id="…">` resolves the current body on every page load+- Nothing needs purging: the agent record is `no-store`, and each avatar is a distinct long-lived object+- **Widget Studio** at [/studio](/studio) is a separate surface that builds standalone widgets from an avatar, across ten widget types+- Avatar visibility (private / unlisted / public) is set in the [avatar dashboard](/dashboard/avatars) and gates whether an avatar can back a widget or a social card-The key insight is the snippet's stability. Once embedded, your customers' pages never need to change. You can update the body monthly, weekly, daily — visitors always see the current version, and the integration on the customer site keeps working without re-deploys.+The key insight is the snippet's stability. Once embedded, your customers' pages never need to change. You can update the body monthly, weekly, or daily, and visitors always see the current version.---## Next steps- [Customize size, position and background](/tutorials/customize-appearance) — once the body is right, tune the embed presentation-- [Embed in 30 seconds](/tutorials/embed-in-30-seconds) — revisit the one-line embed if you skipped it+- [Turn a selfie into a 3D avatar](/tutorials/selfie-to-avatar): put a real likeness in the Outfit grid+- [Embed in 30 seconds](/tutorials/embed-in-30-seconds): revisit the two-tag embed if you skipped it- [Add a greeting and first speech line](/tutorials/greeting-and-first-speech) — give every visitor a spoken welcome- [Share your agent](/tutorials/share-your-agent) — generate a public URL, QR code, and social previews- [Build your first agent](/tutorials/first-agent) — drop down to the manifest and skill level if you want full controldiff --git a/docs/tutorials/trigger-from-page-events.md b/docs/tutorials/trigger-from-page-events.mdindex 28fc87f0f..ec9077ad3 100644--- a/docs/tutorials/trigger-from-page-events.md+++ b/docs/tutorials/trigger-from-page-events.md@@ -185,7 +185,7 @@ async function setupSignupCelebration() {setupSignupCelebration();```-`playEmote` falls through a chain of clip names (`celebrate` → `cheer` → `wave`, or `flinch` → `concern`), so the reaction works regardless of what's baked into the loaded GLB.+`playEmote` falls through a chain of clip names (`celebrate` → `wave`, `cheer` → `celebrate` → `wave`, `flinch` → `defeated` → `concern` → `shake`), so the reaction works regardless of what's baked into the loaded GLB. If no clip in the chain exists, it falls back to a procedural head bob rather than doing nothing, and returns `false` so you can tell a real clip fired from the fallback.The pattern generalises: any form on your page — newsletter signup, contact form, lead capture, checkout — fits the same shape. Real fetch, branch on result, agent reacts.diff --git a/docs/tutorials/upload-custom-glb.md b/docs/tutorials/upload-custom-glb.mdindex 0b2ff38fe..f5f0101c9 100644--- a/docs/tutorials/upload-custom-glb.md+++ b/docs/tutorials/upload-custom-glb.md@@ -7,7 +7,7 @@ This tutorial covers the whole pipeline. Where compatible GLBs come from, what m**What you'll build:**- A custom, rigged 3D avatar running on your live agent- A workflow for validating GLBs before upload so failures happen in your editor, not in production-- A fix-list for the common failure modes (no idle clip, broken skinning, unsupported materials, oversize files)+- A fix-list for the common failure modes (a rig that won't canonicalize, mis-named clips, broken skinning, unsupported materials, oversize files)- A baked, draco-compressed GLB that loads fast on mobile**Prerequisites:** Comfort with a file manager and the command line. Some familiarity with Blender helps for the optional baking step but is not required. You should have an existing agent in [three.ws/my-agents](https://three.ws/my-agents) to swap a body into.@@ -16,21 +16,23 @@ This tutorial covers the whole pipeline. Where compatible GLBs come from, what m## Step 1 — Understand what the runtime expects-A GLB is just a binary glTF — a 3D scene packaged in a single file. The runtime accepts any valid glTF 2.0 GLB, but to function as a *conversational agent body* it needs three things on top of the basic geometry:+A GLB is just a binary glTF — a 3D scene packaged in a single file. The runtime accepts any valid glTF 2.0 GLB. To function as a *conversational agent body*, the one thing that really matters on top of the basic geometry is:-1. **A skeleton (armature) the runtime can read.** The bones should follow a humanoid pattern — head, neck, spine, two arms, two legs. Mixamo and most humanoid avatar pipelines output skeletons that the runtime understands directly.-2. **An idle animation clip.** Without an idle, the avatar stands in T-pose between turns, which looks like a broken model. Any clip whose name contains "idle" (case-insensitive) works.-3. **At least one talk-style clip.** Used while the agent is speaking. Names containing "talk", "yes", or "wave" all match the runtime's hint search.+**A humanoid skeleton (armature) the runtime can name-map.** Bones following a humanoid pattern — head, neck, spine, two arms, two legs. There is no rig allowlist: `src/glb-canonicalize.js` maps the common conventions (Mixamo, Avaturn, Unreal, VRM/VRoid, VRM 1.0, Daz/Genesis, MakeHuman, Blender `.L` suffixes, simple `shoulderL` rigs) onto one canonical bone set.-That's the *minimum*. A great avatar also has:+**You do not have to ship animation clips.** Once the skeleton canonicalizes, `src/animation-retarget.js` retargets the platform's pre-baked clip library (idle, walk, and the emotes) onto your rig, legs included. A rig that genuinely can't be skeleton-driven — no skin, a non-humanoid prop — falls back to the default rig rather than freezing. And if only *some* bones name-map, `relaxUndrivenArms()` swings the un-driven arms down to a relaxed rest, so an avatar never reads as a broken bind-pose T-pose.++Baking your own clips in is therefore an *upgrade*, not a requirement. Do it when you want motion the shared library doesn't have — a brand-specific gesture, a costume-driven idle. Clips are matched by a case-insensitive substring search on the clip name, so `idle`, `idle_loop`, and `IdleBreathing` all satisfy an "idle" lookup; `talk`, `yes`, and `wave` all match the talk-style hint.++Beyond the rig, a great avatar has:- A wave clip (`wave`, `WaveLoop`, etc.) for greetings- Emote clips (`celebrate`, `cheer`, `flinch`, `concern`) for product moments- Sensible material setup — PBR (`pbrMetallicRoughness`) materials, no unsupported extensions- Textures sized for the web — 1024×1024 or 2048×2048 at most, JPEG or WebP rather than PNG where possible-- Draco compression, bringing the file under ~10 MB+- Compressed geometry, bringing the file under ~10 MB-If your GLB is missing the bare minimum, you'll see it in T-pose. If it lacks the niceties, it works but feels heavy and pops in slowly on mobile.+If it lacks the niceties, it works but feels heavy and pops in slowly on mobile.---@@ -52,15 +54,15 @@ Workflow:Mixamo characters work *out of the box* with the runtime. This is the recommended path if you don't already have a model.-### three.ws Studio+### Avatar Studio-[three.ws Studio](https://studio.three.ws) lets you create a stylised avatar in minutes with full body customisation. The download is a single GLB with a clean skeleton and Mixamo-compatible rig.+[Avatar Studio](https://three.ws/avatar-studio) lets you create a stylised avatar in minutes with full body customisation (body, hair, face, clothing, accessories). The export is a single GLB with a clean skeleton and Mixamo-compatible rig. It is also reachable at [/create/studio](https://three.ws/create/studio), and the [Forge](https://three.ws/create) opens it in a modal. (Don't confuse it with [/studio](https://three.ws/studio), which is Widget Studio, the embed-snippet builder.)Workflow:-1. Open [three.ws Studio](https://studio.three.ws).-2. Customise your avatar and click **Export**.-3. The GLB has the body and skin but no animations baked in — you'll need to add at least an idle clip. See Step 5 for adding clips with `gltf-transform`.+1. Open [Avatar Studio](https://three.ws/avatar-studio).+2. Customise your avatar and click **Save Avatar**.+3. The GLB has the body and skin but no bespoke animation clips baked in. You don't have to add any: the platform retargets its pre-baked idle/walk/emote library onto any humanoid rig it can canonicalize, so a Studio avatar animates as soon as it is on an agent. Bake your own clips into the file only when you want motion the library doesn't have — Step 4 covers merging clips in.### Photo-to-avatar@@ -95,7 +97,7 @@ What to look for in the report:|---|---|| **Errors** | Any errors mean the file will fail to load. Fix them all before uploading. || **Warnings** | Most are cosmetic. Texture-size warnings ("3.4 MB PNG") and "unused material" warnings are worth fixing for performance, but won't break the agent. |-| **Animations** | The clip list. Look for at least one clip whose name contains "idle". Click each one to preview. |+| **Animations** | The clip list. If you baked your own clips in, confirm at least one name contains "idle" so the hint search finds it. A file with no clips is fine: the platform's own library retargets onto the rig. Click each one to preview. || **Skeleton** | Reports whether the rig is humanoid. A "non-humanoid skeleton" message means the runtime won't be able to drive head-look or wave gestures. || **Materials** | Lists each material's type. PBR (`pbrMetallicRoughness`) is the safe one. Any extension flagged with "unsupported" means that material will render as a fallback grey. || **File size** | The full size and a breakdown. Mesh + textures over ~10 MB is too heavy for mobile. |@@ -122,31 +124,69 @@ npm run optimize:glb -- public/avatars/your-character.glb> **`optimize:glb` uses WebP, not Draco.** The avatar runtime *does* decode Draco — the viewer and the avatar body loaders wire a `DRACOLoader` pointed at the vendored `/three/draco/` decoder, so a Draco-compressed GLB loads fine (that's Step 5). `optimize:glb` itself deliberately stays within plain glTF 2.0 and leans on WebP textures for its ~90% size win, so its output needs no decoder at all. See [docs/3d-asset-pipeline.md](../3d-asset-pipeline.md) for the full format and pipeline reference.-Outside the repo, [gltf-transform](https://gltf-transform.dev) is a Node-based CLI maintained as part of the glTF ecosystem that also handles the conversion:+Outside the repo, install the same converter directly. [FBX2glTF](https://github.com/facebookincubator/FBX2glTF) (Meta's converter) ships as a prebuilt binary inside the `fbx2gltf` npm package, and it is exactly what `npm run convert:fbx` wraps:```bash-# One character FBX with one baked-in animation:-npx @gltf-transform/cli@latest fbx2glb your-character.fbx your-character.glb+npm i -D fbx2gltf```-If you downloaded several animations separately (idle, talk, wave as standalone FBXs), merge them into a single GLB with named clips:+The package exports a function, not a CLI shim — there is no `npx fbx2gltf`. Call it from a small script:-```bash-# Convert each FBX into a GLB first-npx @gltf-transform/cli@latest fbx2glb idle.fbx idle.glb-npx @gltf-transform/cli@latest fbx2glb talk.fbx talk.glb-npx @gltf-transform/cli@latest fbx2glb wave.fbx wave.glb+```js+// convert.mjs — node convert.mjs your-character.fbx your-character.glb+import { createRequire } from 'node:module';+import { renameSync } from 'node:fs';++const convert = createRequire(import.meta.url)('fbx2gltf');+const [input, output] = process.argv.slice(2);++// A destination ending in .glb yields binary glTF. Some builds write to a+// slightly different path and return it, so normalize to what you asked for.+const written = await convert(input, output, ['--pbr-metallic-roughness']);+if (written && written !== output) renameSync(written, output);+console.log(`wrote ${output}`);+```-# Merge animations into the character GLB-npx @gltf-transform/cli@latest merge your-character.glb idle.glb talk.glb wave.glb out.glb+PBR metallic-roughness materials, the skeleton, skin weights, animation clips, and textures all survive the conversion. If you would rather drive the binary straight from a shell, it is at `node_modules/fbx2gltf/bin/<Darwin|Linux|Windows_NT>/FBX2glTF`; run it with `--help` to see the flags (note that its `-o` takes a path *without* a suffix, which is why the wrapper above normalizes the result).-# Rename animation clips so the runtime's hint search picks them up-npx @gltf-transform/cli@latest rename --map "mixamo.com=Talk" out.glb out-named.glb+> **`gltf-transform` cannot read FBX.** It is a glTF-to-glTF toolkit — every command it exposes takes a `.glb`/`.gltf` in and writes one out, so there is no `fbx2glb`. Use it for the *optimization* steps below, after FBX2glTF has produced a GLB. It also has no `rename` and no `script` subcommand; renaming clips is a Blender or Document-API job (below).++If you downloaded several animations separately (idle, talk, wave as standalone FBXs), convert each with the script above and merge them into a single GLB:++```bash+# Merge the animation GLBs into the character GLB+npx @gltf-transform/cli@latest merge your-character.glb idle.glb talk.glb wave.glb out.glb```-The `rename` step matters. Mixamo names every clip `mixamo.com` by default, which is useless for the runtime's name-based hint matching. Set deliberate names — `Idle`, `Talk`, `Wave`, `Celebrate` — so `playAnimationByHint('idle')` and friends find the right clip.+Then rename the clips. Mixamo names every clip `mixamo.com` by default, which is useless for the runtime's name-based hint matching. Set deliberate names — `Idle`, `Talk`, `Wave`, `Celebrate` — so `playAnimationByHint('idle')` and friends find the right clip. Two ways:-A faster workflow if you have several clips: open the merged GLB in Blender, manually rename each animation in the NLA editor, re-export. Either approach works.+- **Blender (no code):** open the merged GLB, rename each action in the NLA editor, re-export. This is the faster path for a handful of clips.+- **The glTF Transform Document API (scriptable):** the library is a normal npm package, so write a tiny Node script against it. There is no CLI subcommand for this.++```js+// rename-clips.mjs — node rename-clips.mjs merged.glb renamed.glb+import { NodeIO } from '@gltf-transform/core';+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';+import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer';++const NAMES = ['Idle', 'Talk', 'Wave', 'Cheer'];+const [input, output] = process.argv.slice(2);++// Registering the extensions is not optional: most three.ws avatars ship+// EXT_meshopt_compression, and a bare NodeIO throws+// `Missing required extension, "EXT_meshopt_compression"` on read.+const io = new NodeIO()+ .registerExtensions(ALL_EXTENSIONS)+ .registerDependencies({ 'meshopt.decoder': MeshoptDecoder, 'meshopt.encoder': MeshoptEncoder });++const document = await io.read(input);+document.getRoot().listAnimations().forEach((anim, i) => {+ if (NAMES[i]) anim.setName(NAMES[i]);+});+await io.write(output, document);+```++Install its three dependencies first: `npm i -D @gltf-transform/core @gltf-transform/extensions meshoptimizer`. Clip order follows merge order, so pass the animation GLBs to `merge` in the order you list them in `NAMES`.---@@ -159,10 +199,10 @@ The runtime ships with the Draco decoder baked in, so compressed GLBs load transTo compress:```bash-npx @gltf-transform/cli@latest draco --quantization 14 your.glb your-draco.glb+npx @gltf-transform/cli@latest draco --quantize-position 14 your.glb your-draco.glb```-The `--quantization 14` flag balances size against visual quality. The default (14 for position, 12 for normals) is fine for almost all humanoid avatars. If you're seeing visible warping in the mesh after compression, bump it to 16. Anything above 16 stops shrinking the file usefully.+Quantization is per-attribute, not one global flag: `--quantize-position` (default 14), `--quantize-normal` (10), `--quantize-texcoord` (12), `--quantize-color` (8), and `--quantize-generic` (12), each accepting 1-16 bits. The defaults are fine for almost all humanoid avatars, so the command above is really just being explicit. If you see visible warping in the mesh after compression, raise `--quantize-position` to 16, which is the ceiling — there is nothing above it.Compare before/after sizes:@@ -194,16 +234,22 @@ JPEG and WebP are dramatically smaller than PNG for diffuse and ARM maps. PNG is## Step 7 — Upload via the dashboard-With a validated, compressed GLB in hand:+With a validated, compressed GLB in hand, this is two steps: get the file into your avatar library, then point an agent at it.++**Upload the GLB**-1. Go to [three.ws/my-agents](https://three.ws/my-agents).-2. Select the agent you want to give a new body, or click **New agent**.-3. Open the **Body** tab.-4. Drag the GLB onto the drop zone, or click **Upload** and pick the file.-5. The dashboard runs the validator again as part of the upload, then renders a preview in the right pane.-6. Click **Save body**.+1. Go to [three.ws/create](https://three.ws/create).+2. Pick the **Upload your own GLB** card.+3. Drop the `.glb` file, or click to choose it. The header is checked before anything uploads, so a mis-renamed file is rejected immediately rather than half-saved.+4. The avatar lands in your library at [/dashboard/avatars](https://three.ws/dashboard/avatars).-The dashboard stores the GLB on the platform CDN with the right CORS headers and `Cache-Control` for fast subsequent loads. No further hosting steps needed.+**Attach it to an agent**++1. Open the agent in the editor and go to its **Outfit** panel.+2. Under **Avatar**, pick the avatar you just uploaded. Upload progress and a **Cancel** control show inline; the selection is saved to the agent as soon as the attach completes.+3. The same panel is where you pick which clips from the three.ws library the agent uses (**Animations**), which clip plays per behaviour (**Animation states**), and its **Gesture slots**.++The platform stores the GLB on its CDN with the right CORS headers and `Cache-Control` for fast subsequent loads. No further hosting steps needed.Once the body is saved, every embed of that agent — `<agent-3d agent-id="...">`, script-tag embeds, iframe widgets — picks up the new body on next page load. No code changes anywhere.@@ -213,19 +259,18 @@ Once the body is saved, every embed of that agent — `<agent-3d agent-id="...">Almost every upload failure falls into one of these categories. The validator catches them, but knowing what each one means cuts your debug time dramatically.-### Failure A: T-pose, no animation playing+### Failure A: frozen, no animation playing-**Symptom:** Body loads fine, but stands frozen in T-pose.+**Symptom:** Body loads fine, but stands frozen instead of breathing.-**Cause:** No clip whose name matches the runtime's idle hint. The runtime searches case-insensitively for `idle` in clip names.+**Cause:** Two different ones, and they need different fixes.-**Fix:** Rename your idle clip to include "idle" — `Idle`, `idle_loop`, `IdleBreathing` all match.+1. **The skeleton didn't canonicalize.** The retargeting layer couldn't name-map the rig, so the shared clip library has nothing to drive. This is the real failure, and it shows in the validator as a non-humanoid skeleton.+2. **You baked in clips but named them badly.** If the GLB ships its own clips, the runtime prefers them and searches case-insensitively for `idle` in the names. `mixamo.com` matches nothing.-```bash-npx @gltf-transform/cli@latest rename --map "mixamo.com=Idle" your.glb out.glb-```+**Fix for (1):** rename the bones to a convention `glb-canonicalize.js` knows — Mixamo (`mixamorigHead`), VRM, Avaturn, Unreal, Daz, MakeHuman, or Blender `.L`/`.R` suffixes. Hitting a genuinely new skeleton convention is a gap worth reporting rather than working around.-Or rename in Blender's NLA editor and re-export.+**Fix for (2):** rename your idle clip to include "idle" — `Idle`, `idle_loop`, `IdleBreathing` all match. Use Blender's NLA editor or the `rename-clips.mjs` script from Step 4; `gltf-transform` has no `rename` command.### Failure B: Animation plays but the mesh deforms wrong@@ -273,7 +318,7 @@ npx @gltf-transform/cli@latest optimize \your.glb optimized.glb```-The `optimize` command bundles draco, texture resize, image format change, and mesh simplification. For aggressive size reduction it usually drops a 15 MB GLB to 2–3 MB.+The `optimize` command bundles geometry compression, texture resize, image format change, and mesh simplification. Note its default compression is **meshopt**, not Draco: pass `--compress draco` if you specifically want Draco (or `--compress quantize`, or `false` to skip it). For aggressive size reduction it usually drops a 15 MB GLB to 2–3 MB.### Failure E: Validator complains "node has no skin"@@ -296,12 +341,13 @@ Here's the end-to-end. Pick a Mixamo character, ship it as a custom agent body.# - Waving.fbx (Without Skin)# - Cheering.fbx (Without Skin)-# 2. Convert each FBX to GLB+# 2. Convert each FBX to GLB with the convert.mjs wrapper from Step 4for f in *.fbx; do- npx @gltf-transform/cli@latest fbx2glb "$f" "${f%.fbx}.glb"+ node convert.mjs "$f" "${f%.fbx}.glb"done-# 3. Merge the character GLB with the animation GLBs+# 3. Merge the character GLB with the animation GLBs.+# Merge order sets clip order, which the rename step relies on.npx @gltf-transform/cli@latest merge \"your-character.glb" \"Breathing Idle.glb" \@@ -312,22 +358,8 @@ npx @gltf-transform/cli@latest merge \# 4. Rename clips so the runtime's hint search picks them up.# Mixamo names everything "mixamo.com" by default — fix that.-# Use a glTF editor (Blender or Gestaltor) to rename, or:-npx @gltf-transform/cli@latest script renames.js merged.glb renamed.glb-```--For the rename script (`renames.js`), `gltf-transform` lets you write a small node program against its Document API. The simplest version:--```js-// renames.js-const animationNames = ['Idle', 'Talk', 'Wave', 'Cheer'];--module.exports = (document) => {- const root = document.getRoot();- root.listAnimations().forEach((anim, i) => {- if (animationNames[i]) anim.setName(animationNames[i]);- });-};+# Use a glTF editor (Blender or Gestaltor), or the Step 4 script:+node rename-clips.mjs merged.glb renamed.glb``````bash@@ -341,7 +373,7 @@ npx @gltf-transform/cli@latest optimize \# Drag final.glb onto https://three.ws/validation# Confirm: file < 5 MB, animations named correctly, no errors.-# 7. Upload at https://three.ws/my-agents+# 7. Upload at https://three.ws/create, then attach it in the agent editor's Outfit panel```Total: 15–25 minutes the first time, 5 minutes once you've done it. The script-based renames step is the only fiddly part; everything else is one-line commands.@@ -352,7 +384,7 @@ Total: 15–25 minutes the first time, 5 minutes once you've done it. The scriptOnce uploaded:-1. Open any page that embeds the agent (your homepage, the studio preview, [three.ws/my-agents](https://three.ws/my-agents) → preview).+1. Open any page that embeds the agent (your homepage, or the live preview in the agent editor's Outfit panel).2. Confirm the new body loads — no T-pose, no warped limbs.3. Send a chat message — the agent should switch to the talk clip while replying.4. In a browser console, fire each clip by name:@@ -377,7 +409,7 @@ The full custom-GLB pipeline:- The runtime needs a humanoid skeleton, an idle clip, and a talk clip; it likes a wave and a celebrate too- The validator at [three.ws/validation](https://three.ws/validation) catches every common failure before upload- Mixamo's `mixamo.com` clip names need renaming so the hint search finds them-- `gltf-transform optimize` is the one command that handles draco, resize, and simplify in one pass+- `gltf-transform optimize` is the one command that handles geometry compression, resize, and simplify in one pass (meshopt by default; `--compress draco` for Draco)- The dashboard upload path stores the GLB with correct CORS — no separate hosting work neededOnce the body is on the platform, the embed snippet doesn't change. The same `<agent-3d agent-id="...">` tag picks up the new body automatically.diff --git a/docs/tutorials/view-in-ar.md b/docs/tutorials/view-in-ar.mdindex dacdd80d1..e32ff6c27 100644--- a/docs/tutorials/view-in-ar.md+++ b/docs/tutorials/view-in-ar.md@@ -103,13 +103,15 @@ If you're using the iframe embed, add `xr-spatial-tracking` to the `allow` attri```html<iframe- src="https://three.ws/embed/avatar/13f259c7-7024-4d68-b1f0-dbbf52c06209"+ src="https://three.ws/embed/avatar?id=13f259c7-7024-4d68-b1f0-dbbf52c06209"allow="microphone; camera; xr-spatial-tracking; fullscreen"width="400"height="500"></iframe>```+An avatar id goes in the `id` query parameter, as above. The shorter path form, `/embed/avatar/<handle>`, is for a claimed handle (3 to 30 characters), not for a UUID.+Without `xr-spatial-tracking`, the browser blocks `navigator.xr` inside the frame and the AR button won't appear.---diff --git a/docs/x402-distribution.md b/docs/x402-distribution.mdindex 9ab9a89d1..536dfb6ba 100644--- a/docs/x402-distribution.md+++ b/docs/x402-distribution.md@@ -98,8 +98,13 @@ search results after 30 days without a settle**.`x-payment-info` + `responses.402` + request/response schemas — all emitted by[`api/openapi-json.js`](../api/openapi-json.js)), and (3) probing each paidroute's live 402 challenge. Validate any time with- `npx -y @agentcash/discovery@latest discover https://three.ws` and- `… check https://three.ws/<paid-route>`.+ `npx -y @agentcash/discovery@latest discover https://three.ws`, and a single+ route with+ `npx -y @agentcash/discovery@latest check https://three.ws/api/x402/crypto-intel`.+ `check` reads the OpenAPI spec, so pass a route the spec actually carries (the+ `/api/v1/x/*` proxy lane, `/api/mcp`, and the paid routes enumerated in+ `openapi-json.js`); a route outside it answers `L3_NOT_FOUND` even though its+ live 402 challenge is perfectly valid.- **Critical invariant — the `PAYMENT-REQUIRED` header carries the bazaarblock.** AgentCash's probe reads the 402 challenge from the `PAYMENT-REQUIRED`**response header** in preference to the JSON body, and checksdiff --git a/docs/x402-ring-economy.md b/docs/x402-ring-economy.mdindex 88b3029a7..07c385450 100644--- a/docs/x402-ring-economy.md+++ b/docs/x402-ring-economy.md@@ -503,8 +503,15 @@ to one alert per class per day.# 1. Generate the wallets (no chain, no funding — just keys).node scripts/x402-ring-setup.mjs-# 2. Apply the schema.-psql "$DATABASE_URL" -f api/_lib/migrations/2026-07-01-x402-ring-economy.sql+# 2. Apply the schema through the migration runner, never raw psql: it stamps+# api/_lib/migrations/*.sql into `schema_migrations` by sha256, and the+# deploy gate (npm run db:check) reads that ledger. A file applied by hand+# stays "pending" forever and blocks the next deploy. Preview first, because+# db:migrate applies EVERY pending migration with no dry run of its own.+npm run db:status # lists what is pending; writes nothing+npm run db:migrate # applies them (the ring lane needs 2026-07-01-x402-ring-economy.sql,+ # 2026-07-03-x402-ring-agents.sql, 2026-07-03-x402-ring-leak-scan.sql+ # and, for the payer pool below, 2026-07-17-x402-ring-pool.sql)# 3. Set env on the Cloud Run service, from the printed block# (gcloud run services update three-ws-api --region us-central1 --update-env-vars …):diff --git a/public/changelog.json b/public/changelog.jsonindex a4b7ca3b6..5f8adf5e9 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T06:45:57.352Z",+ "generated_at": "2026-08-15T06:48:22.664Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -16,17 +16,6 @@"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",@@ -104,22 +93,11 @@"fix"]},- {- "date": "2026-08-15",- "type": "update",- "title": "The 3D API and agent manifest references now match what the endpoints actually return",- "summary": "The agent manifest page told you to validate a manifest with assertValid from @three-ws/avatar-schema. That package validates avatar manifests (mesh, skeleton, owner), not agent manifests, so the sample always threw. It now shows loadManifest from the published bundle, running against a live agent, and says plainly which document the avatar schema covers. On the 3D API page, the sample responses showed a model URL shape the service never returns, the inspect example was a stale capture of a model that has since been re-exported, and the Forge Pro tier table claimed draft and standard generations come back with no textures when every tier bakes them (1K, 2K, and 4K plus PBR at high). All three are corrected against live calls, and the page now explains why browser code should load a generated GLB through the first-party CDN path rather than the object store URL directly.",- "link": "/docs/3d-api",- "tags": [- "fix",- "docs"- ]- },{"date": "2026-08-15","type": "update","title": "The 3D pipeline docs stop telling you to run a command that does not exist",- "summary": "Every paid stage on the 3D asset pipeline page (rig, remesh, game-ready, stylize, background removal) showed you how to pay for it by running `npx @x402/fetch`. There is no such command: that package publishes a library, not a CLI, so anyone who copied a sample got `could not determine executable to run` and no asset. The samples are now the real thing: an unpaid curl that returns the live 402 challenge and costs nothing, plus one Node snippet that wraps fetch with our published @three-ws/x402-fetch buyer and actually settles. The end-to-end generate-rig-gameready walkthrough was rewritten the same way and now polls the forge job with the fields the API really returns. The page also stops promising a specific settlement network, because the 402 challenge names the networks itself. Alongside it: the changelog page's CDN pinning table listed four alias URLs that all 404, and pointed at an integrity file for a version that no longer publishes one; the AgenC page's opening sentence linked the word AgenC to a different protocol's page; and the vanity protocol spec showed a stale copy of the service key document, which now matches what the live endpoint serves.",+ "summary": "Every paid stage on the 3D asset pipeline page (rig, remesh, game-ready, stylize, background removal) showed you how to pay for it by running npx @x402/fetch. There is no such command: that package publishes a library, not a CLI, so anyone who copied a sample got 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.","link": "/docs/3d-pipeline","tags": ["docs",@@ -140,9 +118,9 @@{"date": "2026-08-15","type": "update",- "title": "The Agent Exchange stops offering a purchase its wallet cannot pay for",- "summary": "On /agent-exchange two 3D agents buy and sell live crypto intel, and the buyer settles $0.01 of real USDC on Solana for every signal. The page already warned you when the buyer's wallet was too empty to settle, but it left the Buy intel button live anyway, so the only thing a click could produce was a failed payment. The button now turns itself off and says why, and the warning carries a Check again button, so a wallet you fund while the page is open recovers without a reload. The balance is also re-read after every purchase, so a settlement that empties the wallet is reflected immediately instead of one click too late. When the balance check itself does not answer, the page used to say nothing at all and quietly log a browser error; it now tells you the balance is unknown and offers the same retry. Two smaller fixes came with it: the page title and the buy button were being rewritten at load time from the translation catalog, which had drifted from the page and still carried the old punctuation, now corrected in all 85 languages; and the two avatar frames were keyboard stops that did nothing and showed no focus outline, so they are out of the tab order and the topic chips and buy button are two tabs closer for anyone navigating by keyboard.",- "link": "/agent-exchange",+ "title": "The agent economy volume dashboard stops sending you to profiles that are not there",+ "summary": "Top earners and top spenders on the agent-to-agent volume page linked every ranked agent to a profile, including agents whose identity had been deleted. Those rows sent you to an empty profile shell for an agent that no longer exists. Both leaderboards now name a departed agent without linking it, the same rule the settled-hire feed below them already followed, and a row whose stored avatar has been pruned falls back to its initials tile instead of a broken-image icon. The page also cleared its accessibility floor: the small print under each stat, the footnote, and the retry button were all below the WCAG AA contrast minimum in dark mode, and in light mode the cyan links and the green live badge were effectively unreadable. Links inside the empty-state sentences now carry a standing underline, so they are not marked by colour alone.",+ "link": "/agent-economy-volume","tags": ["fix","improvement"@@ -175,25 +153,13 @@"date": "2026-08-15","type": "update","title": "The embed tutorials now name the attribute that actually hides the built-in chat",- "summary": "Several tutorials told you to set avatar-chat=\"off\" to hide an agent's built-in chat input. It does not do that: it moves the avatar out of the chat column and lays the chat out as a plain bottom bar, leaving the input on screen. The multi-agent walkthrough leaned on it to keep its behind-the-scenes stage-director messages hidden, so anyone following it verbatim saw those messages leak into the visible chat. Every affected tutorial now uses chat=\"off\", the real bare-avatar switch, and notes that the brain still boots behind it so say(), ask(), and the event stream keep working. The same accuracy pass corrected the walking-avatar leaderboard example, which read fields the API never returns and so always rendered an empty top-walkers list, and the JavaScript API event table, which named the wrong key for the skill a tool-call event reports.",+ "summary": "Several tutorials told you to set avatar-chat=\"off\" to hide an agent's built-in chat input. It does not do that: it moves the avatar out of the chat column and lays the chat out as a plain bottom bar, leaving the input on screen. The multi-agent walkthrough leaned on it to keep its behind-the-scenes stage-director messages hidden, so anyone following it verbatim saw those messages leak into the visible chat. 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.","link": "/tutorials/web-component-end-to-end","tags": ["fix","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, 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",@@ -227,17 +193,6 @@"improvement"]},- {- "date": "2026-08-15",- "type": "update",- "title": "The smart-contract docs stop describing contracts that are not the ones deployed",- "summary": "Anyone reading the ERC-8004 contract reference and calling the addresses it lists was working from the wrong interface. Those canonical addresses are upgradeable proxies running the ERC-8004 reference implementation, not the Solidity source in this repository, and the two are not the same contract. Checked with live calls against Base and Base Sepolia: the agent-listing, supply-count and existence-check helpers the page showed all revert, and every function documented for the reputation registry is absent from the registry actually deployed, which exposes a different interface entirely. The page now says which members answer on the deployed addresses and which exist only if you deploy the repository contracts yourself, and its copy-paste examples were rewritten to calls that run. The security page carried the same mistake in its validator section: it told operators to revoke a compromised validator key with a contract call that exists only on the undeployed source, when the deployed registry keeps no validator list at all and containment is key rotation plus filtering by validator address. Alongside those, the sign-language page advertised an npm install for a package the registry has never carried, and its published sign timings and one broken in-page link were corrected; the catalog quality gate page was missing one of the reasons it rejects a model.",- "link": "/docs/smart-contracts",- "tags": [- "docs",- "fix"- ]- },{"date": "2026-08-15","type": "update",@@ -253,12 +208,11 @@{"date": "2026-08-15","type": "update",- "title": "The vanity SDK now uses the payment wallet you hand it, and the in-chat 3D avatar keeps its tuned lighting",- "summary": "Three fixes in the developer packages. The @three-ws/vanity SDK documented a fetch option on its paid address-grinding lane but silently ignored it, so a developer who passed a payment-enabled fetch got a payment-required error back instead of the keypair they paid for; that option now works, as do a custom API host and key. The avatar MCP server's in-chat 3D viewer had been hand-tuned with softer shadows, brighter exposure and a neutral environment light, but the script that rebuilds it before every release still produced the old flat version, so the next release would have quietly undone the tuning; the script now produces the tuned viewer, and the same settings apply to the fallback view for chat apps that cannot run the interactive one. The tool SDK's quick-start example pointed at an API that does not exist and skipped the wrapper an MCP server needs to return anything at all, so following it produced a tool that answered with nothing; it now runs end to end against a real free three.ws endpoint.",- "link": null,+ "title": "Three docs pages stop pointing readers at a dead page, a missing section, and a snippet that does nothing",+ "summary": "The Vanity page told you to grind a long address yourself \"in the browser at /vanity\", but that path has never existed and returned a 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 landed 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 part 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 what does work, and name the two things that switch it off.",+ "link": "/docs/troubleshooting","tags": ["fix",- "sdk","docs"]},diff --git a/public/changelog.xml b/public/changelog.xmlindex 297bd5dbf..ce18d1fef 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -54,6 +54,14 @@<category>fix</category><description>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.</description></item>+ <item>+ <title>Seeding an agent from GitHub is locked to your own click, and a mistyped pick no longer costs you six hours</title>+ <link>https://three.ws/docs/github-memory-seeding</link>+ <guid isPermaLink="false">2026-08-15:Seeding an agent from GitHub is locked to your own click, and a mistyped pick no longer costs you six hours</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>security</category>+ <description>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.</description>+ </item><item><title>Self-hosting docs no longer hand you a command that wipes your environment</title><link>https://three.ws/docs/deployment</link>@@ -62,6 +70,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 pipeline docs stop telling you to run a command that does not exist</title>+ <link>https://three.ws/docs/3d-pipeline</link>+ <guid isPermaLink="false">2026-08-15:The 3D pipeline docs stop telling you to run a command that does not exist</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>docs</category>+ <description>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.</description>+ </item><item><title>The Agent Economy demo works again when you just pick a service, and it fits a phone screen</title><link>https://three.ws/agent-economy</link>@@ -70,6 +86,14 @@<category>fix</category><description>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.</description></item>+ <item>+ <title>The agent economy volume dashboard stops sending you to profiles that are not there</title>+ <link>https://three.ws/agent-economy-volume</link>+ <guid isPermaLink="false">2026-08-15:The agent economy volume dashboard stops sending you to profiles that are not there</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>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.</description>+ </item><item><title>The agent-payment and MCP docs now show the code that actually ships</title><link>https://three.ws/docs/aws-builder-center-agent-payment-sessions</link>@@ -87,12 +111,12 @@<description>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.</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>+ <title>The embed tutorials now name the attribute that actually hides the built-in chat</title>+ <link>https://three.ws/tutorials/web-component-end-to-end</link>+ <guid isPermaLink="false">2026-08-15:The embed tutorials now name the attribute that actually hides the built-in chat</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, and a task that cannot be read is retried with a backoff instead of being re-requested every four seconds forever.</description>+ <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 guard and gesture tutorials stop teaching steps that fail, and one that wiped your clip list</title>@@ -118,14 +142,6 @@<category>fix</category><description>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.</description></item>- <item>- <title>The smart-contract docs stop describing contracts that are not the ones deployed</title>- <link>https://three.ws/docs/smart-contracts</link>- <guid isPermaLink="false">2026-08-15:The smart-contract docs stop describing contracts that are not the ones deployed</guid>- <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>- <category>docs</category>- <description>Anyone reading the ERC-8004 contract reference and calling the addresses it lists was working from the wrong interface. Those canonical addresses are upgradeable proxies running the ERC-8004 reference implementation, not the Solidity source in this repository, and the two are not the same contract. Checked with live calls against Base and Base Sepolia: the agent-listing, supply-count and existence-check helpers the page showed all revert, and every function documented for the reputation registry is absent from the registry actually deployed, which exposes a different interface entirely. The page now says which members answer on the deployed addresses and which exist only if you deploy the repository contracts yourself, and its copy-paste examples were rewritten to calls that run. The security page carried the same mistake in its validator section: it told operators to revoke a compromised validator key with a contract call that exists only on the undeployed source, when the deployed registry keeps no validator list at all and containment is key rotation plus filtering by validator address. Alongside those, the sign-language page advertised an npm install for a package the registry has never carried, and its published sign timings and one broken in-page link were corrected; the catalog quality gate page was missing one of the reasons it rejects a model.</description>- </item><item><title>The vanity receipt verifier stops calling honest receipts fraudulent, and the avatar CLI takes a Solana address</title><link>https://three.ws/docs/rig-doctor</link>@@ -134,6 +150,14 @@<category>fix</category><description>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.</description></item>+ <item>+ <title>Three docs pages stop pointing readers at a dead page, a missing section, and a snippet that does nothing</title>+ <link>https://three.ws/docs/troubleshooting</link>+ <guid isPermaLink="false">2026-08-15:Three docs pages stop pointing readers at a dead page, a missing section, and a snippet that does nothing</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <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 returned a 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 landed 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 part 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 what does work, and name the two things that switch it off.</description>+ </item><item><title>Agent Interaction Lab</title><link>https://three.ws/demos/agents</link>diff --git a/public/features.json b/public/features.jsonindex c3f38926e..647fd6a10 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T06:45:57.213Z",+ "generated_at": "2026-08-15T06:48:22.550Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/public/llms-full.txt b/public/llms-full.txtindex 8584ef5d7..dca9610f4 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -3681,19 +3681,19 @@ Drop one script tag into any HTML page. Your agent loads, auto-sizes, and startsURL: https://three.ws/tutorials/customize-appearance-Tune every visible knob: bubble size, corner placement, background, rotation speed: entirely through data-* attributes.+Tune every visible knob on the <agent-3d> element: layout mode, corner placement, size, background, camera framing, and the ambient clip.### Tutorial · Pick & swap an avatar in StudioURL: https://three.ws/tutorials/swap-avatar-in-studio-Visually browse the avatar gallery, switch bodies with one click, and have the change ripple to every embed without redeploying.+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 · Add a greeting & first speech lineURL: https://three.ws/tutorials/greeting-and-first-speech-Make your agent say hello the moment it loads: and have its mouth move with the words.+Make your agent say hello the moment it loads, and have its mouth move with the words.### Tutorial · Share your agent (link, QR, social preview)@@ -3705,13 +3705,13 @@ Get a permanent link to your agent, generate a QR for print, and set the Open GrURL: https://three.ws/tutorials/selfie-to-avatar-Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk: then put it on an agent.+Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk, then put it on an agent.### Tutorial · View your 3D model in ARURL: https://three.ws/tutorials/view-in-ar-See any three.ws model in augmented reality and walk around it in your kitchen: straight from the browser, no app to install. iOS Quick Look and Android WebXR.+See any three.ws model in augmented reality and walk around it in your kitchen, straight from the browser with no app to install. iOS Quick Look, Android Scene Viewer, and WebXR.### Tutorial · Import an avatar by URLdiff --git a/public/llms.txt b/public/llms.txtindex e26dd13ea..f916bdb65 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -647,12 +647,12 @@ Docs, tutorials, and reference.- [Tutorial · Getting started (hosted)](https://three.ws/tutorials/getting-started): A five-minute, no-code tour: create an agent, pick a body, give it a personality, share the URL.- [Tutorial · Explore the docs as a 3D world](https://three.ws/tutorials/explore-docs-world): Walk an avatar through the documentation: fourteen sections as glowing pavilions, live pages read in-world, shareable deep links, and your own GLB as the body.- [Tutorial · Embed in 30 seconds](https://three.ws/tutorials/embed-in-30-seconds): Drop one script tag into any HTML page. Your agent loads, auto-sizes, and starts animating.-- [Tutorial · Customize size, position & background](https://three.ws/tutorials/customize-appearance): Tune every visible knob: bubble size, corner placement, background, rotation speed: entirely through data-* attributes.-- [Tutorial · Pick & swap an avatar in Studio](https://three.ws/tutorials/swap-avatar-in-studio): Visually browse the avatar gallery, switch bodies with one click, and have the change ripple to every embed without redeploying.-- [Tutorial · Add a greeting & first speech line](https://three.ws/tutorials/greeting-and-first-speech): Make your agent say hello the moment it loads: and have its mouth move with the words.+- [Tutorial · Customize size, position & background](https://three.ws/tutorials/customize-appearance): Tune every visible knob on the <agent-3d> element: layout mode, corner placement, size, background, camera framing, and the ambient clip.+- [Tutorial · Pick & swap an avatar in Studio](https://three.ws/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 · Add a greeting & first speech line](https://three.ws/tutorials/greeting-and-first-speech): Make your agent say hello the moment it loads, and have its mouth move with the words.- [Tutorial · Share your agent (link, QR, social preview)](https://three.ws/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 · Turn a selfie into a 3D avatar](https://three.ws/tutorials/selfie-to-avatar): Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk: then put it on an agent.-- [Tutorial · View your 3D model in AR](https://three.ws/tutorials/view-in-ar): See any three.ws model in augmented reality and walk around it in your kitchen: straight from the browser, no app to install. iOS Quick Look and Android WebXR.+- [Tutorial · Turn a selfie into a 3D avatar](https://three.ws/tutorials/selfie-to-avatar): Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk, then put it on an agent.+- [Tutorial · View your 3D model in AR](https://three.ws/tutorials/view-in-ar): See any three.ws model in augmented reality and walk around it in your kitchen, straight from the browser with no app to install. iOS Quick Look, Android Scene Viewer, and WebXR.- [Tutorial · Import an avatar by URL](https://three.ws/tutorials/import-avatar-url): Bring any hosted glTF/GLB avatar into three.ws by link: auto-validated, auto-rigged, ready for an agent.- [Tutorial · Add the Walk Companion to your site](https://three.ws/tutorials/walk-companion): Drop a 3D avatar that strolls across any web page (corner mascot or full-page playground) with one script tag, the npm SDK, or a postMessage bridge.- [Tutorial · Load a ready-made 3D tour for a DeFi protocol (Sperax)](https://three.ws/tutorials/sperax-tour): The Tour Builder's first template: an 8-stop guided tour of Sperax's USDs auto-yield stablecoin, ready to load, edit, and export as a one-tag snippet in minutes.diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex 41715ae8a..8166ea3bb 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -4468,21 +4468,21 @@<a href="/tutorials/customize-appearance"><span class="sm-title">Tutorial · Customize size, position & background</span><span class="sm-path">/tutorials/customize-appearance</span>- <span class="sm-desc">Tune every visible knob: bubble size, corner placement, background, rotation speed: entirely through data-* attributes.</span>+ <span class="sm-desc">Tune every visible knob on the <agent-3d> element: layout mode, corner placement, size, background, camera framing, and the ambient clip.</span></a></li><li><a href="/tutorials/swap-avatar-in-studio"><span class="sm-title">Tutorial · Pick & swap an avatar in Studio</span><span class="sm-path">/tutorials/swap-avatar-in-studio</span>- <span class="sm-desc">Visually browse the avatar gallery, switch bodies with one click, and have the change ripple to every embed without redeploying.</span>+ <span class="sm-desc">Swap an agent's 3D body from the Outfit panel in one click, and have the change reach every embed without touching your snippet.</span></a></li><li><a href="/tutorials/greeting-and-first-speech"><span class="sm-title">Tutorial · Add a greeting & first speech line</span><span class="sm-path">/tutorials/greeting-and-first-speech</span>- <span class="sm-desc">Make your agent say hello the moment it loads: and have its mouth move with the words.</span>+ <span class="sm-desc">Make your agent say hello the moment it loads, and have its mouth move with the words.</span></a></li><li>@@ -4496,14 +4496,14 @@<a href="/tutorials/selfie-to-avatar"><span class="sm-title">Tutorial · Turn a selfie into a 3D avatar</span><span class="sm-path">/tutorials/selfie-to-avatar</span>- <span class="sm-desc">Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk: then put it on an agent.</span>+ <span class="sm-desc">Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk, then put it on an agent.</span></a></li><li><a href="/tutorials/view-in-ar"><span class="sm-title">Tutorial · View your 3D model in AR</span><span class="sm-path">/tutorials/view-in-ar</span>- <span class="sm-desc">See any three.ws model in augmented reality and walk around it in your kitchen: straight from the browser, no app to install. iOS Quick Look and Android WebXR.</span>+ <span class="sm-desc">See any three.ws model in augmented reality and walk around it in your kitchen, straight from the browser with no app to install. iOS Quick Look, Android Scene Viewer, and WebXR.</span></a></li><li>diff --git a/public/tutorials-manifest.js b/public/tutorials-manifest.jsindex 13af14e13..718a37d3a 100644--- a/public/tutorials-manifest.js+++ b/public/tutorials-manifest.js@@ -104,7 +104,7 @@slug: 'customize-appearance',tier: 'easy',title: 'Customize size, position & background',- blurb: 'Tune every visible knob — bubble size, corner placement, background, rotation speed — entirely through data-* attributes.',+ blurb: 'Tune every visible knob on the <agent-3d> element: layout mode, corner placement, size, background, camera framing, and the ambient clip.',builds: 'A pixel-perfect floating agent that matches your site',time: '8 min',previewModel: '/animations/soldier.glb',@@ -114,17 +114,17 @@slug: 'swap-avatar-in-studio',tier: 'easy',title: 'Pick & swap an avatar in Studio',- blurb: 'Visually browse the avatar gallery, switch bodies with one click, and have the change ripple to every embed without redeploying.',+ blurb: 'Swap an agent\'s 3D body from the Outfit panel in one click, and have the change reach every embed without touching your snippet.',builds: 'A library of swappable avatar bodies for the same agent',time: '6 min',previewModel: '/avatars/cz.glb',- ctaPrimary: { label: 'Open Widget Studio', href: '/studio' },+ ctaPrimary: { label: 'Open My Agents', href: '/my-agents' },},{slug: 'greeting-and-first-speech',tier: 'easy',title: 'Add a greeting & first speech line',- blurb: 'Make your agent say hello the moment it loads — and have its mouth move with the words.',+ blurb: 'Make your agent say hello the moment it loads, and have its mouth move with the words.',builds: 'An agent that greets every visitor by voice',time: '7 min',previewModel: '/animations/robotexpressive.glb',@@ -144,7 +144,7 @@slug: 'selfie-to-avatar',tier: 'easy',title: 'Turn a selfie into a 3D avatar',- blurb: 'Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk — then put it on an agent.',+ blurb: 'Snap or upload a photo and get a rigged 3D avatar that can walk, wave, and talk, then put it on an agent.',builds: 'A rigged 3D avatar of a real face, ready to animate',time: '8 min',previewModel: '/avatars/cz.glb',@@ -154,7 +154,7 @@slug: 'view-in-ar',tier: 'easy',title: 'View your 3D model in AR',- blurb: 'See any three.ws model in augmented reality and walk around it in your kitchen — straight from the browser, no app to install. iOS Quick Look and Android WebXR.',+ blurb: 'See any three.ws model in augmented reality and walk around it in your kitchen, straight from the browser with no app to install. iOS Quick Look, Android Scene Viewer, and WebXR.',builds: 'A 3D model you can place and view in your real room',time: '8 min',previewModel: '/animations/robotexpressive.glb',