Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(x-posts): consolidate every X announcement draft into docs/x-posts

nirholasd60d45d1065f
diff --git a/docs/ALL.md b/docs/ALL.md
index 75ccd884c..4bf5ebbb1 100644
--- a/docs/ALL.md
+++ b/docs/ALL.md
@@ -1,7 +1,7 @@
<!-- GENERATED by scripts/combine-docs.mjs — do not edit by hand. Edit the source files under docs/ and re-run. -->
# three.ws — Combined Documentation
-> Single-file snapshot of every document under [`docs/`](.). Generated 2026-08-15 from **524 files** (~7416 KB).
+> Single-file snapshot of every document under [`docs/`](.). Generated 2026-08-20 from **549 files** (~7757 KB).
> The individual source files remain the canonical, editable copies — this file is a read-only aggregate.
## Table of contents
@@ -53,269 +53,274 @@
- [autonomous-economy.md](#sec-104)
- [autonomous-x402.md](#sec-105)
- [autopilot.md](#sec-106)
-- [avatar-cli.md](#sec-107)
-- [avatar-creation.md](#sec-108)
-- [avatar-engines.md](#sec-109)
-- [avatar-fidelity-program.md](#sec-110)
-- [avatar-inspector.md](#sec-111)
-- [avatar-pipeline.md](#sec-112)
-- [avatar-reconstruction.md](#sec-113)
-- [avatar-studio.md](#sec-114)
-- [avatar-thumbnails.md](#sec-115)
-- [avatar-wardrobe.md](#sec-116)
-- [aws-builder-center-agent-payment-sessions.md](#sec-117)
-- [aws-builder-center-marketplace-x402.md](#sec-118)
-- [aws-builder-center-mcp-agents.md](#sec-119)
-- [aws-builder-center.md](#sec-120)
-- [aws-marketplace-listing-kit.md](#sec-121)
-- [aws-marketplace.md](#sec-122)
-- [aws-partner-spotlight.md](#sec-123)
-- [bnb-babt-findings.md](#sec-124)
-- [bnb-payments.md](#sec-125)
-- [bnb-vault.md](#sec-126)
-- [bnb-world.md](#sec-127)
-- [brain.md](#sec-128)
-- [btn-pill-migration.md](#sec-129)
-- [build.md](#sec-130)
-- [ca2x402.md](#sec-131)
-- [capture.md](#sec-132)
-- [changelog.md](#sec-133)
-- [character-library.md](#sec-134)
-- [character-studio.md](#sec-135)
-- [chatgpt-3d-studio-gpt.md](#sec-136)
-- [chatgpt-ar.md](#sec-137)
-- [choreography.md](#sec-138)
-- [circulation-engine.md](#sec-139)
-- [clash.md](#sec-140)
-- [clip-director.md](#sec-141)
-- [coin-launches.md](#sec-142)
-- [coin-pages.md](#sec-143)
-- [coin-wars.md](#sec-144)
-- [coinmarketcap-article-play.md](#sec-145)
-- [coinmarketcap-article.md](#sec-146)
-- [coinmarketcap-live-article.md](#sec-147)
-- [compose.md](#sec-148)
-- [concierge.md](#sec-149)
-- [configuration.md](#sec-150)
-- [contributing.md](#sec-157)
-- [copy-trading.md](#sec-162)
-- [cosmos.md](#sec-163)
-- [creator-portfolio.md](#sec-164)
-- [crews.md](#sec-165)
-- [crypto-api.md](#sec-166)
-- [custody.md](#sec-167)
-- [daily-forge.md](#sec-168)
-- [daily-match.md](#sec-169)
-- [demo-routes.md](#sec-170)
-- [deployment.md](#sec-171)
-- [deployments.md](#sec-172)
-- [developer-platform.md](#sec-173)
-- [diorama.md](#sec-174)
-- [do-i-need-crypto.md](#sec-175)
-- [docs-world.md](#sec-176)
-- [draft-agent-mint.md](#sec-177)
-- [economy-heartbeat.md](#sec-178)
-- [economy-master.md](#sec-179)
-- [economy-solver.md](#sec-180)
-- [editor.md](#sec-181)
-- [education-pilot-bucharest.md](#sec-182)
-- [embedding.md](#sec-183)
-- [embody.md](#sec-184)
-- [erc8004.md](#sec-185)
-- [event-souvenirs.md](#sec-213)
-- [event-x-posts.md](#sec-214)
-- [examples.md](#sec-215)
-- [exit-lab.md](#sec-216)
-- [fact-check.md](#sec-217)
-- [farcaster-memory-seeding.md](#sec-218)
-- [financial-controls.md](#sec-219)
-- [fomo-verified-x-post.md](#sec-220)
-- [forge-background-generation.md](#sec-221)
-- [forge-off.md](#sec-222)
-- [forge-pipeline.md](#sec-223)
-- [forge.md](#sec-224)
-- [forged.md](#sec-225)
-- [free-crypto-apis.md](#sec-226)
-- [free-llm-providers.md](#sec-227)
-- [galaxy.md](#sec-228)
-- [generation-watch.md](#sec-229)
-- [genesis.md](#sec-230)
-- [genome.md](#sec-231)
-- [ghost-copy.md](#sec-232)
-- [github-memory-seeding.md](#sec-233)
-- [google-x-accounts.md](#sec-234)
-- [guardian.md](#sec-235)
-- [guards.md](#sec-236)
-- [hold-to-access.md](#sec-237)
-- [how-forge-works.md](#sec-238)
-- [how-it-works.md](#sec-239)
-- [i18n.md](#sec-240)
-- [ibm-community-article.md](#sec-241)
-- [ibm-community-blog-meetup-jessica.md](#sec-242)
-- [ibm-community-live-reaction-jessica.md](#sec-243)
-- [ibm-community-recap-jessica.md](#sec-244)
-- [ibm-community-recap-nichxbt.md](#sec-245)
-- [ibm-community-thread.md](#sec-246)
-- [ibm-community.md](#sec-247)
-- [ibm-x402-mcp.md](#sec-248)
-- [ibm.md](#sec-249)
-- [image-to-3d.md](#sec-250)
-- [in-game-economy.md](#sec-251)
-- [inference-node-operator.md](#sec-252)
-- [integrations.md](#sec-253)
-- [introduction.md](#sec-254)
-- [irl.md](#sec-255)
-- [js-api.md](#sec-257)
-- [kol-tracker.md](#sec-258)
-- [labor-market.md](#sec-259)
-- [launch-usecases.md](#sec-260)
-- [layers.md](#sec-261)
-- [likeness-eval.md](#sec-262)
-- [lipsync.md](#sec-263)
-- [listings.md](#sec-264)
-- [live-docs.md](#sec-265)
-- [live-steps.md](#sec-266)
-- [make-your-agent.md](#sec-267)
-- [market-data-api.md](#sec-268)
-- [marketplace.md](#sec-269)
-- [mcp-3d-studio.md](#sec-270)
-- [mcp-agent.md](#sec-271)
-- [mcp-safety.md](#sec-272)
-- [mcp-studio.md](#sec-273)
-- [mcp-tools.md](#sec-274)
-- [mcp-x402-bazaar.md](#sec-275)
-- [mcp.md](#sec-276)
-- [media-api.md](#sec-277)
-- [memetic-launcher.md](#sec-278)
-- [memory.md](#sec-279)
-- [meta-allocator.md](#sec-280)
-- [mint-mark.md](#sec-281)
-- [minted.md](#sec-282)
-- [mocap-studio.md](#sec-283)
-- [money-feed.md](#sec-284)
-- [money-flow-map.md](#sec-285)
-- [money-map.md](#sec-286)
-- [monitor.md](#sec-287)
-- [motion-swap.md](#sec-288)
-- [multi-agent.md](#sec-289)
-- [native-launchpad.md](#sec-290)
-- [news-rights.md](#sec-291)
-- [notifications.md](#sec-292)
-- [nvidia-apps-catalog-listing.md](#sec-293)
-- [nvidia-apps-catalog-request.md](#sec-294)
-- [nvidia-inception.md](#sec-295)
-- [nvidia-models.md](#sec-296)
-- [nvidia-nemotron-spotlight.md](#sec-297)
-- [object-library.md](#sec-298)
-- [okx-marketplace.md](#sec-299)
-- [onboarding-tier.md](#sec-300)
-- [onchain-agents.md](#sec-301)
-- [oracle.md](#sec-310)
-- [overlay-audit.md](#sec-311)
-- [package-extraction.md](#sec-312)
-- [partners.md](#sec-313)
-- [pay-skills-listing.md](#sec-315)
-- [payment-sessions.md](#sec-316)
-- [permissions.md](#sec-317)
-- [persona-hub.md](#sec-318)
-- [plan-checkout.md](#sec-319)
-- [play-boot-performance.md](#sec-320)
-- [play-forge-in-world.md](#sec-321)
-- [play-hardening.md](#sec-322)
-- [play-live-events.md](#sec-323)
-- [popular-3d-github-repos.md](#sec-324)
-- [portfolio.md](#sec-325)
-- [premium.md](#sec-326)
-- [press-kit.md](#sec-327)
-- [procedural-animation.md](#sec-328)
-- [provenance.md](#sec-329)
-- [pump-claims-channel.md](#sec-330)
-- [pump-fun-mcp-edge.md](#sec-331)
-- [pump-launch-repos.md](#sec-332)
-- [pump-launcher.md](#sec-333)
-- [pump-platform-fee.md](#sec-334)
-- [pumpfun-article-x-post.md](#sec-335)
-- [quick-start.md](#sec-356)
-- [radar.md](#sec-357)
-- [reasoning-ledger.md](#sec-358)
-- [recurring-payments.md](#sec-359)
-- [remix.md](#sec-360)
-- [reputation-staking-market.md](#sec-361)
-- [reputation.md](#sec-362)
-- [restyle.md](#sec-363)
-- [rig-doctor.md](#sec-364)
-- [risk-acknowledgment.md](#sec-365)
-- [robinhood-chain-markets.md](#sec-366)
-- [sas-attestations.md](#sec-367)
-- [scene-studio.md](#sec-368)
-- [sdk.md](#sec-369)
-- [security.md](#sec-370)
-- [seed-quality.md](#sec-371)
-- [selfie-to-avatar.md](#sec-372)
-- [share-and-embed.md](#sec-373)
-- [shared-utilities.md](#sec-374)
-- [showcase.md](#sec-375)
-- [sign-language.md](#sec-376)
-- [signals.md](#sec-377)
-- [site-performance.md](#sec-378)
-- [sketchfab.md](#sec-379)
-- [skill-royalties.md](#sec-380)
-- [skills.md](#sec-381)
-- [smart-contracts.md](#sec-382)
-- [smart-money.md](#sec-383)
-- [sniper-autonomy.md](#sec-384)
-- [social-layer.md](#sec-385)
-- [solana-pumpfun.md](#sec-386)
-- [solana-reputation.md](#sec-387)
-- [solana.md](#sec-388)
-- [spatial-mcp.md](#sec-389)
-- [splat.md](#sec-391)
-- [stage.md](#sec-392)
-- [start-here.md](#sec-393)
-- [strategy-objects.md](#sec-394)
-- [swarms.md](#sec-395)
-- [syndication.md](#sec-396)
-- [talking-avatar-video.md](#sec-397)
-- [terminal.md](#sec-398)
-- [three-microbuy.md](#sec-399)
-- [timeline.md](#sec-400)
-- [token-gated-3d-embeds.md](#sec-401)
-- [tokens-xyz.md](#sec-402)
-- [trader-card.md](#sec-403)
-- [trader-passport.md](#sec-404)
-- [trading-arenas.md](#sec-405)
-- [trading-copilot.md](#sec-406)
-- [trading-experiment.md](#sec-407)
-- [trading-hub.md](#sec-408)
-- [trading-surfaces.md](#sec-409)
-- [troubleshooting.md](#sec-410)
-- [trust-primitives.md](#sec-411)
-- [ui-juice.md](#sec-481)
-- [user-wallet.md](#sec-482)
-- [validation.md](#sec-495)
-- [vanity.md](#sec-496)
-- [vaults.md](#sec-497)
-- [viability.md](#sec-498)
-- [viewer.md](#sec-499)
-- [voice-lab.md](#sec-500)
-- [walk-leaderboard.md](#sec-501)
-- [web-component.md](#sec-502)
-- [widget-api.md](#sec-503)
-- [widget-studio.md](#sec-504)
-- [widgets.md](#sec-505)
-- [world-lines.md](#sec-506)
-- [x-archive.md](#sec-507)
-- [x-meetup-posts.md](#sec-509)
-- [x-memory-seeding.md](#sec-510)
-- [x402-buyer.md](#sec-511)
-- [x402-dev-tools.md](#sec-512)
-- [x402-distribution.md](#sec-513)
-- [x402-endpoints.md](#sec-514)
-- [x402-revenue.md](#sec-515)
-- [x402-ring-economy.md](#sec-516)
-- [x402-solana-july-roundup-response.md](#sec-517)
-- [x402-studio.md](#sec-518)
-- [x402.md](#sec-519)
+- [avatar-artifact.md](#sec-107)
+- [avatar-cli.md](#sec-108)
+- [avatar-creation.md](#sec-109)
+- [avatar-engines.md](#sec-110)
+- [avatar-fidelity-program.md](#sec-111)
+- [avatar-inspector.md](#sec-112)
+- [avatar-pipeline.md](#sec-113)
+- [avatar-reconstruction.md](#sec-114)
+- [avatar-studio.md](#sec-115)
+- [avatar-thumbnails.md](#sec-116)
+- [avatar-wardrobe.md](#sec-117)
+- [aws-builder-center-agent-payment-sessions.md](#sec-118)
+- [aws-builder-center-marketplace-x402.md](#sec-119)
+- [aws-builder-center-mcp-agents.md](#sec-120)
+- [aws-builder-center.md](#sec-121)
+- [aws-marketplace-listing-kit.md](#sec-122)
+- [aws-marketplace.md](#sec-123)
+- [aws-partner-spotlight.md](#sec-124)
+- [big-tech-recognition-week.md](#sec-125)
+- [bnb-babt-findings.md](#sec-126)
+- [bnb-payments.md](#sec-127)
+- [bnb-vault.md](#sec-128)
+- [bnb-world.md](#sec-129)
+- [brain.md](#sec-130)
+- [btn-pill-migration.md](#sec-131)
+- [build.md](#sec-132)
+- [ca2x402.md](#sec-133)
+- [capture.md](#sec-134)
+- [changelog.md](#sec-135)
+- [character-library.md](#sec-136)
+- [character-studio.md](#sec-137)
+- [chatgpt-3d-studio-gpt.md](#sec-138)
+- [chatgpt-ar.md](#sec-139)
+- [choreography.md](#sec-140)
+- [circulation-engine.md](#sec-141)
+- [clash.md](#sec-142)
+- [clip-director.md](#sec-143)
+- [coin-launches.md](#sec-144)
+- [coin-pages.md](#sec-145)
+- [coin-wars.md](#sec-146)
+- [coingecko-listing-update-2026-08.md](#sec-147)
+- [coinmarketcap-article-play.md](#sec-148)
+- [coinmarketcap-article.md](#sec-149)
+- [coinmarketcap-live-article.md](#sec-150)
+- [compose.md](#sec-151)
+- [concierge.md](#sec-152)
+- [configuration.md](#sec-153)
+- [contributing.md](#sec-160)
+- [copy-trading.md](#sec-165)
+- [cosmos.md](#sec-166)
+- [creator-portfolio.md](#sec-167)
+- [crews.md](#sec-168)
+- [crypto-api.md](#sec-169)
+- [custody.md](#sec-170)
+- [daily-forge.md](#sec-171)
+- [daily-match.md](#sec-172)
+- [demo-routes.md](#sec-173)
+- [deployment.md](#sec-174)
+- [deployments.md](#sec-175)
+- [developer-platform.md](#sec-176)
+- [diorama.md](#sec-177)
+- [do-i-need-crypto.md](#sec-178)
+- [docs-world.md](#sec-179)
+- [draft-agent-mint.md](#sec-180)
+- [economy-heartbeat.md](#sec-181)
+- [economy-master.md](#sec-182)
+- [economy-solver.md](#sec-183)
+- [editor.md](#sec-184)
+- [education-pilot-bucharest.md](#sec-185)
+- [embedding.md](#sec-186)
+- [embody.md](#sec-187)
+- [erc8004.md](#sec-188)
+- [event-souvenirs.md](#sec-216)
+- [examples.md](#sec-217)
+- [exit-lab.md](#sec-218)
+- [fact-check.md](#sec-219)
+- [farcaster-memory-seeding.md](#sec-220)
+- [financial-controls.md](#sec-221)
+- [forge-background-generation.md](#sec-222)
+- [forge-off.md](#sec-223)
+- [forge-pipeline.md](#sec-224)
+- [forge.md](#sec-225)
+- [forged.md](#sec-226)
+- [free-crypto-apis.md](#sec-227)
+- [free-llm-providers.md](#sec-228)
+- [galaxy.md](#sec-229)
+- [generation-watch.md](#sec-230)
+- [genesis.md](#sec-231)
+- [genome.md](#sec-232)
+- [ghost-copy.md](#sec-233)
+- [github-memory-seeding.md](#sec-234)
+- [google-x-accounts.md](#sec-235)
+- [guardian.md](#sec-236)
+- [guards.md](#sec-237)
+- [hold-to-access.md](#sec-238)
+- [how-forge-works.md](#sec-239)
+- [how-it-works.md](#sec-240)
+- [i18n.md](#sec-241)
+- [ibm-community-article.md](#sec-242)
+- [ibm-community-blog-meetup-jessica.md](#sec-243)
+- [ibm-community-live-reaction-jessica.md](#sec-244)
+- [ibm-community-recap-jessica.md](#sec-245)
+- [ibm-community-recap-nichxbt.md](#sec-246)
+- [ibm-community-thread.md](#sec-247)
+- [ibm-community.md](#sec-248)
+- [ibm-x402-mcp.md](#sec-249)
+- [ibm.md](#sec-250)
+- [image-to-3d.md](#sec-251)
+- [in-game-economy.md](#sec-252)
+- [inference-node-operator.md](#sec-253)
+- [integrations.md](#sec-254)
+- [introduction.md](#sec-255)
+- [irl.md](#sec-256)
+- [js-api.md](#sec-258)
+- [kol-tracker.md](#sec-259)
+- [labor-market.md](#sec-260)
+- [launch-usecases.md](#sec-261)
+- [layers.md](#sec-262)
+- [likeness-eval.md](#sec-263)
+- [lipsync.md](#sec-264)
+- [listings.md](#sec-265)
+- [live-docs.md](#sec-266)
+- [live-steps.md](#sec-267)
+- [make-your-agent.md](#sec-268)
+- [market-data-api.md](#sec-269)
+- [marketplace.md](#sec-270)
+- [mcp-3d-studio.md](#sec-271)
+- [mcp-agent.md](#sec-272)
+- [mcp-safety.md](#sec-273)
+- [mcp-studio.md](#sec-274)
+- [mcp-tools.md](#sec-275)
+- [mcp-x402-bazaar.md](#sec-276)
+- [mcp.md](#sec-277)
+- [media-api.md](#sec-278)
+- [memetic-launcher.md](#sec-279)
+- [memory.md](#sec-280)
+- [meta-allocator.md](#sec-281)
+- [mint-mark.md](#sec-282)
+- [minted.md](#sec-283)
+- [mocap-studio.md](#sec-284)
+- [money-feed.md](#sec-285)
+- [money-flow-map.md](#sec-286)
+- [money-map.md](#sec-287)
+- [monitor.md](#sec-288)
+- [motion-swap.md](#sec-289)
+- [multi-agent.md](#sec-290)
+- [native-launchpad.md](#sec-291)
+- [news-rights.md](#sec-292)
+- [notifications.md](#sec-293)
+- [nvidia-apps-catalog-listing.md](#sec-294)
+- [nvidia-apps-catalog-request.md](#sec-295)
+- [nvidia-inception.md](#sec-296)
+- [nvidia-models.md](#sec-297)
+- [nvidia-nemotron-ask-the-experts-questions.md](#sec-298)
+- [nvidia-nemotron-spotlight.md](#sec-299)
+- [nvidia-visibility-map.md](#sec-300)
+- [object-library.md](#sec-301)
+- [okx-marketplace.md](#sec-302)
+- [onboarding-tier.md](#sec-303)
+- [onchain-agents.md](#sec-304)
+- [openai-listing-channels.md](#sec-305)
+- [oracle-trading-mcp-plan.md](#sec-314)
+- [oracle.md](#sec-315)
+- [overlay-audit.md](#sec-316)
+- [package-extraction.md](#sec-317)
+- [partners.md](#sec-318)
+- [pay-skills-listing.md](#sec-320)
+- [payment-sessions.md](#sec-321)
+- [permissions.md](#sec-322)
+- [persona-hub.md](#sec-323)
+- [plan-checkout.md](#sec-324)
+- [play-boot-performance.md](#sec-325)
+- [play-forge-in-world.md](#sec-326)
+- [play-hardening.md](#sec-327)
+- [play-live-events.md](#sec-328)
+- [play-vehicles.md](#sec-329)
+- [popular-3d-github-repos.md](#sec-330)
+- [portfolio.md](#sec-331)
+- [premium.md](#sec-332)
+- [press-kit.md](#sec-333)
+- [procedural-animation.md](#sec-334)
+- [provenance.md](#sec-335)
+- [pump-claims-channel.md](#sec-336)
+- [pump-fun-mcp-edge.md](#sec-337)
+- [pump-launch-repos.md](#sec-338)
+- [pump-launcher.md](#sec-339)
+- [pump-platform-fee.md](#sec-340)
+- [quick-start.md](#sec-361)
+- [radar.md](#sec-362)
+- [reasoning-ledger.md](#sec-363)
+- [recurring-payments.md](#sec-364)
+- [remix.md](#sec-365)
+- [reputation-staking-market.md](#sec-366)
+- [reputation.md](#sec-367)
+- [restyle.md](#sec-368)
+- [rig-doctor.md](#sec-369)
+- [risk-acknowledgment.md](#sec-370)
+- [robinhood-chain-markets.md](#sec-371)
+- [sas-attestations.md](#sec-372)
+- [scene-studio.md](#sec-373)
+- [sdk.md](#sec-374)
+- [security.md](#sec-375)
+- [seed-quality.md](#sec-376)
+- [selfie-to-avatar.md](#sec-377)
+- [share-and-embed.md](#sec-378)
+- [shared-utilities.md](#sec-379)
+- [showcase.md](#sec-380)
+- [sign-language.md](#sec-381)
+- [signals.md](#sec-382)
+- [site-performance.md](#sec-383)
+- [sketchfab.md](#sec-384)
+- [skill-bundles.md](#sec-385)
+- [skill-royalties.md](#sec-386)
+- [skills.md](#sec-387)
+- [smart-contracts.md](#sec-388)
+- [smart-money.md](#sec-389)
+- [sniper-autonomy.md](#sec-390)
+- [social-layer.md](#sec-391)
+- [solana-pumpfun.md](#sec-392)
+- [solana-reputation.md](#sec-393)
+- [solana.md](#sec-394)
+- [spatial-mcp.md](#sec-395)
+- [splat.md](#sec-397)
+- [stage.md](#sec-398)
+- [start-here.md](#sec-399)
+- [strategy-objects.md](#sec-400)
+- [swarms.md](#sec-401)
+- [syndication.md](#sec-402)
+- [talking-avatar-video.md](#sec-403)
+- [terminal.md](#sec-404)
+- [three-microbuy.md](#sec-405)
+- [timeline.md](#sec-406)
+- [token-gated-3d-embeds.md](#sec-407)
+- [tokens-xyz.md](#sec-408)
+- [trader-card.md](#sec-409)
+- [trader-passport.md](#sec-410)
+- [trading-arenas.md](#sec-411)
+- [trading-copilot.md](#sec-412)
+- [trading-experiment.md](#sec-413)
+- [trading-hub.md](#sec-414)
+- [trading-surfaces.md](#sec-415)
+- [troubleshooting.md](#sec-416)
+- [trust-primitives.md](#sec-417)
+- [ui-juice.md](#sec-487)
+- [user-wallet.md](#sec-488)
+- [validation.md](#sec-501)
+- [vanity.md](#sec-502)
+- [vaults.md](#sec-503)
+- [viability.md](#sec-504)
+- [viewer.md](#sec-505)
+- [voice-lab.md](#sec-506)
+- [walk-leaderboard.md](#sec-507)
+- [web-component.md](#sec-508)
+- [widget-api.md](#sec-509)
+- [widget-studio.md](#sec-510)
+- [widgets.md](#sec-511)
+- [world-lines.md](#sec-512)
+- [x-archive.md](#sec-513)
+- [x-memory-seeding.md](#sec-515)
+- [x402-buyer.md](#sec-536)
+- [x402-dev-tools.md](#sec-537)
+- [x402-distribution.md](#sec-538)
+- [x402-endpoints.md](#sec-539)
+- [x402-revenue.md](#sec-540)
+- [x402-ring-economy.md](#sec-541)
+- [x402-solana-july-roundup-response.md](#sec-542)
+- [x402-studio.md](#sec-543)
+- [x402.md](#sec-544)
### agent-abilities
@@ -392,197 +397,220 @@
### content
-- [content/use-cases/README.md](#sec-151)
-- [content/use-cases/ai-agent-developer.md](#sec-152)
-- [content/use-cases/brand-marketer.md](#sec-153)
-- [content/use-cases/crypto-community.md](#sec-154)
-- [content/use-cases/game-studio.md](#sec-155)
-- [content/use-cases/indie-creator.md](#sec-156)
+- [content/use-cases/README.md](#sec-154)
+- [content/use-cases/ai-agent-developer.md](#sec-155)
+- [content/use-cases/brand-marketer.md](#sec-156)
+- [content/use-cases/crypto-community.md](#sec-157)
+- [content/use-cases/game-studio.md](#sec-158)
+- [content/use-cases/indie-creator.md](#sec-159)
### cookbook
-- [cookbook/asset-quality-gate.md](#sec-158)
-- [cookbook/mcp-3d-tool.md](#sec-159)
-- [cookbook/parallel-asset-pack.md](#sec-160)
-- [cookbook/text-to-3d-cli.md](#sec-161)
+- [cookbook/asset-quality-gate.md](#sec-161)
+- [cookbook/mcp-3d-tool.md](#sec-162)
+- [cookbook/parallel-asset-pack.md](#sec-163)
+- [cookbook/text-to-3d-cli.md](#sec-164)
### erc8004
-- [erc8004/validation-attestation.md](#sec-186)
+- [erc8004/validation-attestation.md](#sec-189)
### event-readiness
-- [event-readiness/01-play-first-impression.md](#sec-187)
-- [event-readiness/02-play-mobile.md](#sec-188)
-- [event-readiness/03-play-performance.md](#sec-189)
-- [event-readiness/04-play-multiplayer-net.md](#sec-190)
-- [event-readiness/05-play-economy-loops.md](#sec-191)
-- [event-readiness/06-play-auth-errors.md](#sec-192)
-- [event-readiness/07-platform-smoke-sweep.md](#sec-193)
-- [event-readiness/08-api-production-health.md](#sec-194)
-- [event-readiness/09-accessibility-i18n.md](#sec-195)
-- [event-readiness/10-event-day-runbook.md](#sec-196)
-- [event-readiness/11-event-live-ops.md](#sec-197)
-- [event-readiness/12-photo-mode-share.md](#sec-198)
-- [event-readiness/13-event-quests-leaderboard.md](#sec-199)
-- [event-readiness/14-welcome-concierge.md](#sec-200)
-- [event-readiness/15-live-hype-feed.md](#sec-201)
-- [event-readiness/16-invite-flow.md](#sec-202)
-- [event-readiness/17-plaza-live-show.md](#sec-203)
-- [event-readiness/18-coin-wars-portal.md](#sec-204)
-- [event-readiness/19-forge-props-live.md](#sec-205)
-- [event-readiness/20-world-chat-scrollback.md](#sec-206)
-- [event-readiness/21-party-system.md](#sec-207)
-- [event-readiness/22-venue-projector-mode.md](#sec-208)
-- [event-readiness/23-signature-wall.md](#sec-209)
-- [event-readiness/24-dance-off.md](#sec-210)
-- [event-readiness/LIVE-OPS.md](#sec-211)
-- [event-readiness/README.md](#sec-212)
+- [event-readiness/01-play-first-impression.md](#sec-190)
+- [event-readiness/02-play-mobile.md](#sec-191)
+- [event-readiness/03-play-performance.md](#sec-192)
+- [event-readiness/04-play-multiplayer-net.md](#sec-193)
+- [event-readiness/05-play-economy-loops.md](#sec-194)
+- [event-readiness/06-play-auth-errors.md](#sec-195)
+- [event-readiness/07-platform-smoke-sweep.md](#sec-196)
+- [event-readiness/08-api-production-health.md](#sec-197)
+- [event-readiness/09-accessibility-i18n.md](#sec-198)
+- [event-readiness/10-event-day-runbook.md](#sec-199)
+- [event-readiness/11-event-live-ops.md](#sec-200)
+- [event-readiness/12-photo-mode-share.md](#sec-201)
+- [event-readiness/13-event-quests-leaderboard.md](#sec-202)
+- [event-readiness/14-welcome-concierge.md](#sec-203)
+- [event-readiness/15-live-hype-feed.md](#sec-204)
+- [event-readiness/16-invite-flow.md](#sec-205)
+- [event-readiness/17-plaza-live-show.md](#sec-206)
+- [event-readiness/18-coin-wars-portal.md](#sec-207)
+- [event-readiness/19-forge-props-live.md](#sec-208)
+- [event-readiness/20-world-chat-scrollback.md](#sec-209)
+- [event-readiness/21-party-system.md](#sec-210)
+- [event-readiness/22-venue-projector-mode.md](#sec-211)
+- [event-readiness/23-signature-wall.md](#sec-212)
+- [event-readiness/24-dance-off.md](#sec-213)
+- [event-readiness/LIVE-OPS.md](#sec-214)
+- [event-readiness/README.md](#sec-215)
### irl
-- [irl/THREAT-MODEL.md](#sec-256)
+- [irl/THREAT-MODEL.md](#sec-257)
### openai-pr
-- [openai-pr/00-START-HERE.md](#sec-302)
-- [openai-pr/01-orphan-widget-resolution.md](#sec-303)
-- [openai-pr/02-wellknown-manifest-conflict.md](#sec-304)
-- [openai-pr/03-forge-free-tier-truth.md](#sec-305)
-- [openai-pr/04-openai-surface-test-coverage.md](#sec-306)
-- [openai-pr/05-custom-gpt-openapi-serving.md](#sec-307)
-- [openai-pr/06-docs-accuracy-reconciliation.md](#sec-308)
-- [openai-pr/07-final-verification-and-submit.md](#sec-309)
+- [openai-pr/00-START-HERE.md](#sec-306)
+- [openai-pr/01-orphan-widget-resolution.md](#sec-307)
+- [openai-pr/02-wellknown-manifest-conflict.md](#sec-308)
+- [openai-pr/03-forge-free-tier-truth.md](#sec-309)
+- [openai-pr/04-openai-surface-test-coverage.md](#sec-310)
+- [openai-pr/05-custom-gpt-openapi-serving.md](#sec-311)
+- [openai-pr/06-docs-accuracy-reconciliation.md](#sec-312)
+- [openai-pr/07-final-verification-and-submit.md](#sec-313)
### partners
-- [partners/sperax-proposal.md](#sec-314)
+- [partners/sperax-proposal.md](#sec-319)
### pumpfun-program
-- [pumpfun-program/README.md](#sec-336)
-- [pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md](#sec-337)
-- [pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md](#sec-338)
-- [pumpfun-program/docs/BREAKING_FEE_RECIPIENT.md](#sec-339)
-- [pumpfun-program/docs/CPI_README.md](#sec-340)
-- [pumpfun-program/docs/FAQ.md](#sec-341)
-- [pumpfun-program/docs/FEE_PROGRAM_README.md](#sec-342)
-- [pumpfun-program/docs/FEE_RECIPIENTS.md](#sec-343)
-- [pumpfun-program/docs/PUMP_CASHBACK_README.md](#sec-344)
-- [pumpfun-program/docs/PUMP_CREATOR_FEE_README.md](#sec-345)
-- [pumpfun-program/docs/PUMP_PROGRAM_README.md](#sec-346)
-- [pumpfun-program/docs/PUMP_SWAP_CREATOR_FEE_README.md](#sec-347)
-- [pumpfun-program/docs/PUMP_SWAP_README.md](#sec-348)
-- [pumpfun-program/docs/PUMP_SWAP_SDK_README.md](#sec-349)
-- [pumpfun-program/docs/instructions/BUY.md](#sec-350)
-- [pumpfun-program/docs/instructions/CLAIM_CASHBACK.md](#sec-351)
-- [pumpfun-program/docs/instructions/COIN_CREATION.md](#sec-352)
-- [pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md](#sec-353)
-- [pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md](#sec-354)
-- [pumpfun-program/docs/instructions/SELL.md](#sec-355)
+- [pumpfun-program/README.md](#sec-341)
+- [pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md](#sec-342)
+- [pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md](#sec-343)
+- [pumpfun-program/docs/BREAKING_FEE_RECIPIENT.md](#sec-344)
+- [pumpfun-program/docs/CPI_README.md](#sec-345)
+- [pumpfun-program/docs/FAQ.md](#sec-346)
+- [pumpfun-program/docs/FEE_PROGRAM_README.md](#sec-347)
+- [pumpfun-program/docs/FEE_RECIPIENTS.md](#sec-348)
+- [pumpfun-program/docs/PUMP_CASHBACK_README.md](#sec-349)
+- [pumpfun-program/docs/PUMP_CREATOR_FEE_README.md](#sec-350)
+- [pumpfun-program/docs/PUMP_PROGRAM_README.md](#sec-351)
+- [pumpfun-program/docs/PUMP_SWAP_CREATOR_FEE_README.md](#sec-352)
+- [pumpfun-program/docs/PUMP_SWAP_README.md](#sec-353)
+- [pumpfun-program/docs/PUMP_SWAP_SDK_README.md](#sec-354)
+- [pumpfun-program/docs/instructions/BUY.md](#sec-355)
+- [pumpfun-program/docs/instructions/CLAIM_CASHBACK.md](#sec-356)
+- [pumpfun-program/docs/instructions/COIN_CREATION.md](#sec-357)
+- [pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md](#sec-358)
+- [pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md](#sec-359)
+- [pumpfun-program/docs/instructions/SELL.md](#sec-360)
### specs
-- [specs/agent-trading.md](#sec-390)
+- [specs/agent-trading.md](#sec-396)
### tutorials
-- [tutorials/add-a-3d-assistant.md](#sec-412)
-- [tutorials/agent-personality.md](#sec-413)
-- [tutorials/agent-reputation.md](#sec-414)
-- [tutorials/agent-spending-envelope.md](#sec-415)
-- [tutorials/animate-your-agent.md](#sec-416)
-- [tutorials/animate-your-avatar.md](#sec-417)
-- [tutorials/arm-an-agent-sniper.md](#sec-418)
-- [tutorials/build-a-3d-asset-pipeline.md](#sec-419)
-- [tutorials/build-a-scene.md](#sec-420)
-- [tutorials/build-a-site-concierge.md](#sec-421)
-- [tutorials/character-library-to-embed.md](#sec-422)
-- [tutorials/claim-threews-name.md](#sec-423)
-- [tutorials/connect-ai-brain.md](#sec-424)
-- [tutorials/create-and-edit-memory.md](#sec-425)
-- [tutorials/custom-skill.md](#sec-426)
-- [tutorials/customize-appearance.md](#sec-427)
-- [tutorials/deploy-to-vercel-custom-domain.md](#sec-428)
-- [tutorials/earn-and-spend-in-play.md](#sec-429)
-- [tutorials/embed-in-30-seconds.md](#sec-430)
-- [tutorials/embed-on-website.md](#sec-431)
-- [tutorials/emotion-from-data.md](#sec-432)
-- [tutorials/explore-docs-world.md](#sec-433)
-- [tutorials/find-a-better-exit-policy.md](#sec-434)
-- [tutorials/first-agent.md](#sec-435)
-- [tutorials/first-prompt-to-3d.md](#sec-436)
-- [tutorials/generate-3d-api.md](#sec-437)
-- [tutorials/getting-started.md](#sec-438)
-- [tutorials/greeting-and-first-speech.md](#sec-439)
-- [tutorials/image-to-3d.md](#sec-440)
-- [tutorials/import-avatar-url.md](#sec-441)
-- [tutorials/js-api-events.md](#sec-442)
-- [tutorials/mcp-server-for-your-agent.md](#sec-443)
-- [tutorials/mine-vanity-address.md](#sec-444)
-- [tutorials/mint-pumpfun-token.md](#sec-445)
-- [tutorials/monetize-mcp-server.md](#sec-446)
-- [tutorials/multi-agent-coordination.md](#sec-447)
-- [tutorials/nvidia-3d-free.md](#sec-448)
-- [tutorials/nvidia-nim-self-host.md](#sec-449)
-- [tutorials/paid-x402-endpoint.md](#sec-450)
-- [tutorials/pay-for-x402-service.md](#sec-451)
-- [tutorials/personal-ai-site.md](#sec-452)
-- [tutorials/place-agent-irl.md](#sec-453)
-- [tutorials/prompts-for-3d.md](#sec-454)
-- [tutorials/read-the-trading-fleet.md](#sec-455)
-- [tutorials/register-onchain.md](#sec-456)
-- [tutorials/render-avatar-images.md](#sec-457)
-- [tutorials/self-host-agent-backend.md](#sec-458)
-- [tutorials/selfie-to-avatar.md](#sec-459)
-- [tutorials/sell-a-skill-with-a-trial.md](#sec-460)
-- [tutorials/share-your-agent.md](#sec-461)
-- [tutorials/ship-an-avatar-manifest.md](#sec-462)
-- [tutorials/shopify-shopping-assistant.md](#sec-463)
-- [tutorials/shopify-store-guide-advanced.md](#sec-464)
-- [tutorials/shopify-store-guide.md](#sec-465)
-- [tutorials/sign-with-your-avatar.md](#sec-466)
-- [tutorials/skill-with-database-auth.md](#sec-467)
-- [tutorials/solana-agent-reputation.md](#sec-468)
-- [tutorials/sperax-tour.md](#sec-469)
-- [tutorials/swap-avatar-in-studio.md](#sec-470)
-- [tutorials/text-to-3d.md](#sec-471)
-- [tutorials/trigger-from-page-events.md](#sec-472)
-- [tutorials/upload-custom-glb.md](#sec-473)
-- [tutorials/view-in-ar.md](#sec-474)
-- [tutorials/voice-and-lipsync.md](#sec-475)
-- [tutorials/walk-companion.md](#sec-476)
-- [tutorials/wallet-sign-in.md](#sec-477)
-- [tutorials/web-component-end-to-end.md](#sec-478)
-- [tutorials/write-a-guard.md](#sec-479)
-- [tutorials/x402-server-sdk.md](#sec-480)
+- [tutorials/add-a-3d-assistant.md](#sec-418)
+- [tutorials/agent-personality.md](#sec-419)
+- [tutorials/agent-reputation.md](#sec-420)
+- [tutorials/agent-spending-envelope.md](#sec-421)
+- [tutorials/animate-your-agent.md](#sec-422)
+- [tutorials/animate-your-avatar.md](#sec-423)
+- [tutorials/arm-an-agent-sniper.md](#sec-424)
+- [tutorials/build-a-3d-asset-pipeline.md](#sec-425)
+- [tutorials/build-a-scene.md](#sec-426)
+- [tutorials/build-a-site-concierge.md](#sec-427)
+- [tutorials/character-library-to-embed.md](#sec-428)
+- [tutorials/claim-threews-name.md](#sec-429)
+- [tutorials/connect-ai-brain.md](#sec-430)
+- [tutorials/create-and-edit-memory.md](#sec-431)
+- [tutorials/custom-skill.md](#sec-432)
+- [tutorials/customize-appearance.md](#sec-433)
+- [tutorials/deploy-to-vercel-custom-domain.md](#sec-434)
+- [tutorials/earn-and-spend-in-play.md](#sec-435)
+- [tutorials/embed-in-30-seconds.md](#sec-436)
+- [tutorials/embed-on-website.md](#sec-437)
+- [tutorials/emotion-from-data.md](#sec-438)
+- [tutorials/explore-docs-world.md](#sec-439)
+- [tutorials/find-a-better-exit-policy.md](#sec-440)
+- [tutorials/first-agent.md](#sec-441)
+- [tutorials/first-prompt-to-3d.md](#sec-442)
+- [tutorials/generate-3d-api.md](#sec-443)
+- [tutorials/getting-started.md](#sec-444)
+- [tutorials/greeting-and-first-speech.md](#sec-445)
+- [tutorials/image-to-3d.md](#sec-446)
+- [tutorials/import-avatar-url.md](#sec-447)
+- [tutorials/js-api-events.md](#sec-448)
+- [tutorials/mcp-server-for-your-agent.md](#sec-449)
+- [tutorials/mine-vanity-address.md](#sec-450)
+- [tutorials/mint-pumpfun-token.md](#sec-451)
+- [tutorials/monetize-mcp-server.md](#sec-452)
+- [tutorials/multi-agent-coordination.md](#sec-453)
+- [tutorials/nvidia-3d-free.md](#sec-454)
+- [tutorials/nvidia-nim-self-host.md](#sec-455)
+- [tutorials/paid-x402-endpoint.md](#sec-456)
+- [tutorials/pay-for-x402-service.md](#sec-457)
+- [tutorials/personal-ai-site.md](#sec-458)
+- [tutorials/place-agent-irl.md](#sec-459)
+- [tutorials/prompts-for-3d.md](#sec-460)
+- [tutorials/read-the-trading-fleet.md](#sec-461)
+- [tutorials/register-onchain.md](#sec-462)
+- [tutorials/render-avatar-images.md](#sec-463)
+- [tutorials/self-host-agent-backend.md](#sec-464)
+- [tutorials/selfie-to-avatar.md](#sec-465)
+- [tutorials/sell-a-skill-with-a-trial.md](#sec-466)
+- [tutorials/share-your-agent.md](#sec-467)
+- [tutorials/ship-an-avatar-manifest.md](#sec-468)
+- [tutorials/shopify-shopping-assistant.md](#sec-469)
+- [tutorials/shopify-store-guide-advanced.md](#sec-470)
+- [tutorials/shopify-store-guide.md](#sec-471)
+- [tutorials/sign-with-your-avatar.md](#sec-472)
+- [tutorials/skill-with-database-auth.md](#sec-473)
+- [tutorials/solana-agent-reputation.md](#sec-474)
+- [tutorials/sperax-tour.md](#sec-475)
+- [tutorials/swap-avatar-in-studio.md](#sec-476)
+- [tutorials/text-to-3d.md](#sec-477)
+- [tutorials/trigger-from-page-events.md](#sec-478)
+- [tutorials/upload-custom-glb.md](#sec-479)
+- [tutorials/view-in-ar.md](#sec-480)
+- [tutorials/voice-and-lipsync.md](#sec-481)
+- [tutorials/walk-companion.md](#sec-482)
+- [tutorials/wallet-sign-in.md](#sec-483)
+- [tutorials/web-component-end-to-end.md](#sec-484)
+- [tutorials/write-a-guard.md](#sec-485)
+- [tutorials/x402-server-sdk.md](#sec-486)
### ux-flows
-- [ux-flows/01-onboarding-creation.md](#sec-483)
-- [ux-flows/02-forge-text-to-3d.md](#sec-484)
-- [ux-flows/03-3d-editing-viewer.md](#sec-485)
-- [ux-flows/04-embed-widget-studio.md](#sec-486)
-- [ux-flows/05-discovery-social.md](#sec-487)
-- [ux-flows/06-marketplace-skills.md](#sec-488)
-- [ux-flows/07-crypto-trading-analytics.md](#sec-489)
-- [ux-flows/08-coin-launch-wallets.md](#sec-490)
-- [ux-flows/09-x402-agent-commerce.md](#sec-491)
-- [ux-flows/10-chat-brain-labs.md](#sec-492)
-- [ux-flows/11-account-dashboard.md](#sec-493)
-- [ux-flows/12-home-and-content.md](#sec-494)
+- [ux-flows/01-onboarding-creation.md](#sec-489)
+- [ux-flows/02-forge-text-to-3d.md](#sec-490)
+- [ux-flows/03-3d-editing-viewer.md](#sec-491)
+- [ux-flows/04-embed-widget-studio.md](#sec-492)
+- [ux-flows/05-discovery-social.md](#sec-493)
+- [ux-flows/06-marketplace-skills.md](#sec-494)
+- [ux-flows/07-crypto-trading-analytics.md](#sec-495)
+- [ux-flows/08-coin-launch-wallets.md](#sec-496)
+- [ux-flows/09-x402-agent-commerce.md](#sec-497)
+- [ux-flows/10-chat-brain-labs.md](#sec-498)
+- [ux-flows/11-account-dashboard.md](#sec-499)
+- [ux-flows/12-home-and-content.md](#sec-500)
### x-archive
-- [x-archive/trythreews-engagement.md](#sec-508)
+- [x-archive/trythreews-engagement.md](#sec-514)
+
+### x-posts
+
+- [x-posts/3d-ar-studio-launch.md](#sec-516)
+- [x-posts/3d-ar-studio-video-script.md](#sec-517)
+- [x-posts/README.md](#sec-518)
+- [x-posts/event-x-posts.md](#sec-519)
+- [x-posts/fomo-verified-x-post.md](#sec-520)
+- [x-posts/ibm-skillsbuild-x-post.md](#sec-521)
+- [x-posts/mcp-registry-fleet-x-post.md](#sec-522)
+- [x-posts/metaplex-agent-deployer-video-script.md](#sec-523)
+- [x-posts/metaplex-agent-deployer-x-post.md](#sec-524)
+- [x-posts/metaplex-agent-mcp-launch.md](#sec-525)
+- [x-posts/metaplex-agent-mcp-veo-script.md](#sec-526)
+- [x-posts/metaplex-agent-mcp-x-post.md](#sec-527)
+- [x-posts/news-archive-x-post.md](#sec-528)
+- [x-posts/onchain-agent-wallets-x-post.md](#sec-529)
+- [x-posts/oracle-trading-mcp-x-post.md](#sec-530)
+- [x-posts/pumpfun-article-x-post.md](#sec-531)
+- [x-posts/sperax-staking-in-chat-x-post.md](#sec-532)
+- [x-posts/threews-avatar-launch.md](#sec-533)
+- [x-posts/threews-avatar-video-script.md](#sec-534)
+- [x-posts/x-meetup-posts.md](#sec-535)
### zauth
-- [zauth/database.md](#sec-520)
-- [zauth/index.md](#sec-521)
-- [zauth/provider-hub.md](#sec-522)
-- [zauth/reposcan.md](#sec-523)
-- [zauth/vector.md](#sec-524)
+- [zauth/database.md](#sec-545)
+- [zauth/index.md](#sec-546)
+- [zauth/provider-hub.md](#sec-547)
+- [zauth/reposcan.md](#sec-548)
+- [zauth/vector.md](#sec-549)
---
@@ -1147,8 +1175,8 @@ This is the canonical reference for how three.ws moves a 3D character or motion
If you just want to add one animation or upload one avatar, the task guides are shorter:
- [docs/animations.md](#sec-093) — the animation registry, runtime loading, and agent slots.
-- [docs/avatar-creation.md](#sec-108) — the three ways to create an avatar (photo, builder, upload).
-- [docs/tutorials/upload-custom-glb.md](#sec-473) — Mixamo → GLB, validation, and the common failure modes.
+- [docs/avatar-creation.md](#sec-109) — the three ways to create an avatar (photo, builder, upload).
+- [docs/tutorials/upload-custom-glb.md](#sec-479) — Mixamo → GLB, validation, and the common failure modes.
This document is the *why and how* underneath all of those.
@@ -1467,11 +1495,11 @@ text/image ──► mesh_forge ──► static GLB ──► rig_mesh ──
three.ws runs a full 3D asset pipeline — the same lanes the platform uses to turn
a prompt into a rigged, game-ready character. Every working stage is sold as its
-own [x402](#sec-519) resource: an AI agent pays a few cents in USDC, hands in a URL,
+own [x402](#sec-544) resource: an AI agent pays a few cents in USDC, hands in a URL,
and gets back a finished asset URL. No API key, no account, no signup.
Nobody else in the x402 ecosystem offers this. The generation stage (text/image →
-3D) is [`/api/x402/forge`](#sec-514); the stages below are what you do to
+3D) is [`/api/x402/forge`](#sec-539); the stages below are what you do to
a mesh *after* it exists.
```
@@ -1484,7 +1512,7 @@ a mesh *after* it exists.
1. **One stage at a time** — `POST /api/x402/pipeline-<stage>`. One payment buys
one finished asset, returned inline as a durable first-party URL. This is the
reference below.
-2. **The whole chain in one call** — [`POST /api/x402/pipeline`](#sec-514).
+2. **The whole chain in one call** — [`POST /api/x402/pipeline`](#sec-539).
Submit an ordered chain (`generate → rig → remesh → gameready → stylize`); the
402 quote is the exact sum of the requested stages, and you poll the job free
at `GET /api/forge?job=<id>` while it advances. Use this when you want the full
@@ -1547,7 +1575,7 @@ console.log(output_url);
The wrapper answers the 402, signs the payment, and retries the same request, all
before your `await` resolves. Paying from a three.ws agent wallet instead of a
raw key, or settling on Solana, is covered in
-[x402 buyer client](#sec-511).
+[x402 buyer client](#sec-536).
## Stages
@@ -1706,9 +1734,9 @@ returned as-is. Poll budget is tunable via `X402_PIPELINE_POLL_BUDGET_MS`
## Related
-- [x402 paid endpoints](#sec-514) — the full catalog + pricing model
-- [x402 buyer client](#sec-511) — how to settle payments as an agent
-- [Avatar pipeline](#sec-112) — the generation + rig lanes in depth
+- [x402 paid endpoints](#sec-539) — the full catalog + pricing model
+- [x402 buyer client](#sec-536) — how to settle payments as an agent
+- [Avatar pipeline](#sec-113) — the generation + rig lanes in depth
---
@@ -2103,9 +2131,13 @@ recompute — never trust — each of the following. All must pass.
6. **signature** — Ed25519-verify the canonical message (§6) against the pinned
service key, AND the receipt's `servicePublicKey` equals the pinned key
(reject impostors that self-sign under a different key).
-7. **custody** *(optional)* — if the buyer opened the sealed envelope, the
- recovered 32-byte seed MUST equal `seed_{winningIndex}` and its Ed25519 public
- key MUST equal `receipt.address`.
+7. **custody** *(optional)*: whenever the verifier holds the 32-byte secret seed,
+ whether recovered by opening the sealed envelope or read straight from an
+ unsealed receipt's `seed` / `secretKey`, it MUST equal `seed_{winningIndex}`
+ and its Ed25519 public key MUST equal `receipt.address`. The web verifier at
+ [`/vanity/verify`](https://three.ws/vanity/verify) runs this check in both
+ cases: with the buyer's X25519 key for a sealed receipt, and with no key at
+ all for an unsealed one.
A single failing check means the receipt is not trustworthy. The negative test in
[`tests/vanity-verifiable-grind.test.js`](../tests/vanity-verifiable-grind.test.js)
@@ -2158,8 +2190,8 @@ Product and developer documentation for three.ws. Individual docs are served on
Start points:
-- [start-here.md](#sec-393): the front door for both creators and developers, with the reference shelf at the bottom.
-- [introduction.md](#sec-254) and [quick-start.md](#sec-356): the developer track.
+- [start-here.md](#sec-399): the front door for both creators and developers, with the reference shelf at the bottom.
+- [introduction.md](#sec-255) and [quick-start.md](#sec-361): the developer track.
- [ALL.md](ALL.md): generated single-file aggregate of the public docs (regenerate with `node scripts/combine-docs.mjs`; edit source files, never ALL.md).
- [api-reference.md](#sec-096): the REST API surface, with dedicated docs for the larger API families (crypto, 3D, market data, MCP).
@@ -2193,7 +2225,7 @@ leaves behind, and how to stop an agent that has gone wrong.
> [`scripts/a2a-spend-hardening-proof.mjs`](../scripts/a2a-spend-hardening-proof.mjs).
Related: [the agent wallet control API](#sec-071) for the other
-owner-only wallet surfaces, [financial controls](#sec-219) for
+owner-only wallet surfaces, [financial controls](#sec-221) for
the platform-wide picture, and [agent economy volume](#sec-052)
for what settled A2A payments add up to.
@@ -2553,7 +2585,7 @@ or task to the AgenC program. The write paths that do exist live elsewhere:
Treat this page's REST surface as **discovery + identity correlation**. For the
other writable on-chain identity, minting agents as Metaplex Core NFTs, see
-[Deploy agents on-chain (bulk)](#sec-301).
+[Deploy agents on-chain (bulk)](#sec-304).
## Relationship to Agora
@@ -2566,8 +2598,8 @@ AgenC endpoints here are the read/identity side.
## Related
- [Agora](#sec-075) — the economy and write lifecycle on top of AgenC.
-- [Agent reputation](#sec-056), [ERC-8004](#sec-185).
-- [Deploy agents on-chain (bulk)](#sec-301).
+- [Agent reputation](#sec-056), [ERC-8004](#sec-188).
+- [Deploy agents on-chain (bulk)](#sec-304).
---
@@ -4674,7 +4706,7 @@ Turn an agent into an on-chain business: its coin is its equity, its invoices ar
## Sentiment and narrative intel tools
-Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real comment thread for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
+Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
Sentiment-pulse fetches recent commentary from pump.fun's frontend-api-v3 comments endpoint (the same source the pump.fun coin page renders) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js); aixbt endpoints proxy the aixbt market-intelligence service.
@@ -7639,7 +7671,7 @@ Agents launched as pump.fun coins can charge for their services on-chain: build
## Sentiment and narrative intel tools
-Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real comment thread for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
+Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.
**How it works:** Sentiment-pulse fetches recent commentary from pump.fun's frontend-api-v3 comments endpoint (the same source the pump.fun coin page renders) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js); aixbt endpoints proxy the aixbt market-intelligence service.
@@ -13593,7 +13625,7 @@ would hide it.
## Related
-- [x402 revenue and receipts](#sec-515): the other side of the ledger. This
+- [x402 revenue and receipts](#sec-540): the other side of the ledger. This
page counts agent-to-agent payments recorded in `agent_hires`; endpoint revenue
paid **to** the platform's own paid endpoints is recorded separately in
`x402_audit_log`. Do not add the two together.
@@ -13630,7 +13662,7 @@ One completed job produces:
| `full_body[]` | Three 1024x1280 (4:5 portrait) renders, one per pose, same backdrop and lighting |
| `rigged_glb_url` | The avatar with a humanoid skeleton and skin weights |
| `mesh_glb_url` | The unrigged generated mesh, kept so a rig hiccup never loses the generation |
-| `viewer_url` | Deep link into the three.ws [viewer](#sec-499) for the rigged GLB |
+| `viewer_url` | Deep link into the three.ws [viewer](#sec-505) for the rigged GLB |
| `pose_studio_url` | Deep link into the [Animation Studio](#sec-092) for the rigged GLB |
Every render is persisted to object storage under `okx-identity/renders/<job>/` and served from a public URL, so the URLs in the response are permanent and hotlinkable.
@@ -13810,13 +13842,13 @@ Two environment overrides help a batch run outlast the rig lane's rate-limit bac
## Related
-- [OKX.AI Marketplace Services](#sec-299): the price, the payment challenge, the replay flow, the payment guarantees, and the decomposed single-capability 3D services that share these engines.
-- [Forge](#sec-224): the text and image to GLB generation pipeline this studio calls for the mesh and the auto-rig.
+- [OKX.AI Marketplace Services](#sec-302): the price, the payment challenge, the replay flow, the payment guarantees, and the decomposed single-capability 3D services that share these engines.
+- [Forge](#sec-225): the text and image to GLB generation pipeline this studio calls for the mesh and the auto-rig.
- [Animation Studio](#sec-092): the `/pose` surface the `pose_studio_url` deep link opens.
-- [Viewer](#sec-499): the `/viewer` surface the `viewer_url` deep link opens.
-- [MCP servers](#sec-276): the wider set of three.ws MCP endpoints this one follows the transport conventions of.
-- [Avatar Engines Atlas](#sec-109): what engine families exist for building human avatars, and which of them are wired into the commercial pipeline.
-- [Draft agent mint](#sec-177): the inactive on-chain identity minted for every finished reconstruction, Solana first with ERC-8004 alongside it.
+- [Viewer](#sec-505): the `/viewer` surface the `viewer_url` deep link opens.
+- [MCP servers](#sec-277): the wider set of three.ws MCP endpoints this one follows the transport conventions of.
+- [Avatar Engines Atlas](#sec-110): what engine families exist for building human avatars, and which of them are wired into the commercial pipeline.
+- [Draft agent mint](#sec-180): the inactive on-chain identity minted for every finished reconstruction, Solana first with ERC-8004 alongside it.
---
@@ -13976,8 +14008,8 @@ asks whether the job ran.
| Both crawl crons | [`api/cron/`](../api/cron) |
| Regression cover | [`tests/agent-index.test.js`](../tests/agent-index.test.js) |
-Related: [Trust primitives](#sec-411) scores an agent from on-chain
-evidence, and [Custody you can verify](#sec-167) covers the attestations the
+Related: [Trust primitives](#sec-417) scores an agent from on-chain
+evidence, and [Custody you can verify](#sec-170) covers the attestations the
`reputation` and `validation` classes carry.
---
@@ -14629,7 +14661,7 @@ Load from on-chain:
A manifest served from an API is a claim. A manifest that is **signed and pinned to IPFS** is evidence: anyone can fetch the CID, check the signature, and read the exact system prompt the agent was configured with, without an account and without trusting three.ws.
-three.ws signs and pins an agent's manifest automatically on every persona save. The envelope is ed25519-signed by the platform attester identity (the same Solana key behind [3D provenance credentials](#sec-329)) and pinned through the configured IPFS provider.
+three.ws signs and pins an agent's manifest automatically on every persona save. The envelope is ed25519-signed by the platform attester identity (the same Solana key behind [3D provenance credentials](#sec-335)) and pinned through the configured IPFS provider.
### What a signed envelope looks like
@@ -14786,7 +14818,7 @@ The `spec` field identifies the manifest format version. Current stable: `agent-
- [Memory Spec](../specs/MEMORY_SPEC.md) — memory file format and MEMORY.md index
- [Embed Spec](../specs/EMBED_SPEC.md) — `<agent-3d>` element attributes and events
- [Permissions Spec](../specs/PERMISSIONS_SPEC.md) — ERC-7710 delegation format and redemption
-- [Provenance](#sec-329) — signed content credentials for generated 3D assets, using the same attester identity as signed manifests
+- [Provenance](#sec-335) — signed content credentials for generated 3D assets, using the same attester identity as signed manifests
---
@@ -14798,7 +14830,7 @@ The `spec` field identifies the manifest format version. Current stable: `agent-
**Why autonomous agents need verifiable trust — and how three.ws delivers it on-chain.**
-This page is the *why*. For the practical how-to, see [Reputation System](#sec-362) (leaving and reading reviews) and [ERC-8004](#sec-185) (the identity standard underneath). To read a real agent's score five different ways, follow the [Read an agent's reputation](/tutorials/agent-reputation) tutorial. For the Solana side of the same idea — memo attestations, the AgenC coordination program, and the identity bridge — see [Agent Reputation on Solana](#sec-387).
+This page is the *why*. For the practical how-to, see [Reputation System](#sec-367) (leaving and reading reviews) and [ERC-8004](#sec-188) (the identity standard underneath). To read a real agent's score five different ways, follow the [Read an agent's reputation](/tutorials/agent-reputation) tutorial. For the Solana side of the same idea — memo attestations, the AgenC coordination program, and the identity bridge — see [Agent Reputation on Solana](#sec-393).
---
@@ -14862,7 +14894,7 @@ Each agent is an NFT; whoever owns the token controls the agent. The token point
A reserved, signature-gated field binds a verified payment wallet to the agent (proven with an EIP-712 signature, and cleared automatically if the NFT is transferred).
-> Full detail: [ERC-8004](#sec-185).
+> Full detail: [ERC-8004](#sec-188).
### 2. Reputation Registry — what others think of it
@@ -14891,7 +14923,7 @@ Reputation only matters because money moves on the other side of it. The two hal
1. **Discover** a service via the Identity Registry.
2. **Check** its reputation — proceed only if it clears your threshold.
-3. **Pay** — the service answers an HTTP `402` and the agent signs a stablecoin micropayment ([x402](#sec-519)).
+3. **Pay** — the service answers an HTTP `402` and the agent signs a stablecoin micropayment ([x402](#sec-544)).
4. **Vouch** — after the work, write feedback back to the Reputation Registry, closing the loop for the next agent.
The one-liner worth remembering:
@@ -14912,7 +14944,7 @@ The same on-chain data is exposed through every layer a reader might come from:
| Reputation panel | agent profiles | The embedded vouch/score widget on `https://three.ws/a/<chainId>/<agentId>` |
| `GET /api/agents/<id>/reputation` | apps | The agent's unified wallet trust score: a 0-100 credibility number derived from real ledger and on-chain activity, with a per-pillar breakdown and evidence links |
| `agent_reputation` MCP tool | AI agents | Paid ($0.01 USDC) read of identity + score + stake + recent events; resolves a wallet to its agent automatically |
-| `GET /api/x402/agent-reputation` | AI agents | Paid ($0.01) cross-chain 0–100 trust score for **any** counterparty — Solana/EVM wallet, pump.fun mint, ERC-8004 agent id, or three.ws agent_id (auto-detected). See [Trust primitives](#sec-411) |
+| `GET /api/x402/agent-reputation` | AI agents | Paid ($0.01) cross-chain 0–100 trust score for **any** counterparty — Solana/EVM wallet, pump.fun mint, ERC-8004 agent id, or three.ws agent_id (auto-detected). See [Trust primitives](#sec-417) |
| [Agent Passport](/agent-passport.html) | trust decisions | An A–D trust grade weighted toward credentialed and verified feedback |
| ERC-8004 helpers (`src/erc8004/reputation.js`; ABIs re-exported by `@three-ws/sdk`) | developers | `getReputation`, `getRecentReviews`, `getTotalStake`, `submitFeedback`, `stakeReputation` |
@@ -14951,7 +14983,7 @@ The only difference is **reach**. The Club's reputation dies the moment a wallet
That portability is what lets a three.ws agent be trusted by an agent that has never heard of three.ws. It's the foundation the agent economy is built on — and the reason reputation, not payments, is the harder and more important half of the stack.
-**Next:** [Read an agent's reputation](/tutorials/agent-reputation) · [Reputation on Solana](#sec-387) · [Leave a vouch](#sec-362) · [ERC-8004 identity](#sec-185) · [x402 payments](#sec-519)
+**Next:** [Read an agent's reputation](/tutorials/agent-reputation) · [Reputation on Solana](#sec-393) · [Leave a vouch](#sec-367) · [ERC-8004 identity](#sec-188) · [x402 payments](#sec-544)
---
@@ -15385,8 +15417,8 @@ relationship into an account with a real agent. Ambient discovery routes
through the agent too — the old "have you tried…" toast stays out of the corner
while the companion is live.
-Related: [web-component.md](#sec-502) (the embeddable `agent-3d`
-avatar), [coin-pages.md](#sec-143) (the market surfaces the shell
+Related: [web-component.md](#sec-508) (the embeddable `agent-3d`
+avatar), [coin-pages.md](#sec-145) (the market surfaces the shell
navigates), [STRUCTURE.md](../STRUCTURE.md) (surface map).
---
@@ -15402,7 +15434,7 @@ Claude surface — Claude Code, the Claude apps, the Agent SDK — how to use th
three.ws platform: create and rig 3D models, run a wallet, and buy/sell services in
the x402 agent economy.
-> Not to be confused with the [in-app skills system](#sec-381), which extends
+> Not to be confused with the [in-app skills system](#sec-387), which extends
> avatars and agents **inside** three.ws with `manifest.json` + `tools.json` +
> `handlers.js` bundles. Agent Skills are the inverse: they extend **external**
> AI agents with three.ws capabilities.
@@ -15521,7 +15553,7 @@ Every three.ws agent has its own custodial Solana wallet. The Agent Sniper is th
This doc explains the whole system, walks through the first live trade an agent closed on the platform (a real +42.38% exit, receipts included), and lays out where the system goes next.
-Related surfaces: [the trading surfaces](#sec-409) (Radar, Coin Intelligence, Mission Control), [trading experiment](#sec-407) (the laddered-exit research policy), [agent wallets](#sec-072) (how custody works), and the worker itself at `workers/agent-sniper/` (its README is the operator reference).
+Related surfaces: [the trading surfaces](#sec-415) (Radar, Coin Intelligence, Mission Control), [trading experiment](#sec-413) (the laddered-exit research policy), [agent wallets](#sec-072) (how custody works), and the worker itself at `workers/agent-sniper/` (its README is the operator reference).
---
@@ -15634,6 +15666,8 @@ The strategy row (`agent_sniper_strategies`, armed via `POST /api/sniper/strateg
| `initials_out_multiple` / `moonbag_min_pct` | The laddered exit: recover cost at N times entry, let the rest ride |
| `kill_switch` / `enabled` | Two independent off switches |
+Every field in that table is settable through `POST /api/sniper/strategy`; an omitted field keeps its stored value, and an explicit `null` clears the ones documented as clearable (`initials_out_multiple` back to the classic single-shot exit, the entry filters back to "no filter"). One column is deliberately not settable there: `auto_fund_enabled`, the consent for the platform's launcher master to top this agent's wallet up, is operator-granted against the row. Sending it in the body returns `400 bad_request` rather than being silently ignored, and `GET /api/sniper/strategy` reports it read-only so a dashboard can still show whether the treasury may refill the wallet.
+
Exit rules are evaluated in a fixed order (stop-loss, signal-flip, trailing-stop, take-profit, timeout) by a pure, unit-tested function (`workers/agent-sniper/exit-logic.js`), so a backtest and the live worker agree on exactly when a position closes.
### The `oracle_crossing` trigger
@@ -15669,8 +15703,8 @@ The direction of every bridge is the same: real, realized money is the ground tr
## Try it
- Arm your first strategy: [the sniper tutorial](/tutorials/arm-an-agent-sniper)
-- Watch the engine think: [Coin Intelligence and the trading surfaces](#sec-409)
-- The research policy behind laddered exits: [trading experiment](#sec-407)
+- Watch the engine think: [Coin Intelligence and the trading surfaces](#sec-415)
+- The research policy behind laddered exits: [trading experiment](#sec-413)
- The story of the first trade, for non-operators: [the blog post](/blog/first-autonomous-trade)
---
@@ -15696,7 +15730,7 @@ An agent is not one thing; it is a brain, a memory, a body, a wallet, and a set
skills, and until now each of those lived on a different page. Agent Studio unifies
them into one workspace so you can see the whole agent at once and watch changes take
effect immediately. It is the deep-authoring counterpart to the fast on-ramp in
-[Instant Agent Genesis](#sec-230): Genesis gets you a complete agent in a minute,
+[Instant Agent Genesis](#sec-231): Genesis gets you a complete agent in a minute,
Studio is where you make it exactly what you want. For the broader model of what an
agent is, see [Agent System](#sec-064).
@@ -15720,7 +15754,7 @@ real agent APIs.
- **The five tabs**, each a mount point the sub-studio fills:
- **Brain**: model and provider selection plus the reasoning setup, exercised live
against `/api/brain/chat` (the same multi-LLM backend documented in
- [Multi-LLM Brain](#sec-128)).
+ [Multi-LLM Brain](#sec-130)).
- **Memory**: what the agent remembers and for how long, over `/api/agent-memory`
and the `/api/memory/*` context, search, graph, and curate endpoints.
- **Body**: the 3D avatar, outfit, and animations, reflected live on the stage via
@@ -15797,8 +15831,8 @@ curl -s https://three.ws/api/agents/<agent-id>/pricing \
## Related
- [Agent System](#sec-064): the full model of what an agent is
-- [Instant Agent Genesis](#sec-230): create the agent Studio edits
-- [Multi-LLM Brain](#sec-128): the model backend behind the Brain tab
+- [Instant Agent Genesis](#sec-231): create the agent Studio edits
+- [Multi-LLM Brain](#sec-130): the model backend behind the Brain tab
- [Agent Skills](#sec-060): the capabilities the Skills tab manages
- [Agent Wallets](#sec-072): the wallet behind the Money tab
- Pages: [/agent-studio](https://three.ws/agent-studio), [/genesis](https://three.ws/genesis), [/brain](https://three.ws/brain)
@@ -15833,7 +15867,7 @@ user gesture. Nothing autoplays.
## Where the events come from
The symphony consumes the same live ticker documented in
-[Money Feed](#sec-284):
+[Money Feed](#sec-285):
1. `GET /api/feed?limit=40` paints the initial ledger (played silently as
backlog, not as notes).
@@ -15849,7 +15883,7 @@ you hear.
## What sounds map to what events
Every allow-listed feed type (see the type table in
-[Money Feed](#sec-284)) maps to one of six voices in
+[Money Feed](#sec-285)) maps to one of six voices in
`TYPE_TO_CATEGORY` in [`src/symphony-score.js`](../src/symphony-score.js).
Each voice has its own synth patch in the engine, its own color in the
visualization, and its own mute button in the legend.
@@ -15951,7 +15985,7 @@ cross-links are asserted statically by
## Related
-- [Money Feed](#sec-284): the activity bus this page renders, including
+- [Money Feed](#sec-285): the activity bus this page renders, including
the full event-type table and how events are published.
- [Agora](#sec-075): the on-chain economy lifecycle behind the `agora-*`
events.
@@ -16149,7 +16183,7 @@ Captures what is currently visible and describes it so the agent can react to wh
### Stage-scoped tools
-When the runtime is attached to an `<agent-stage>`, two extra tools are appended (see [multi-agent.md](#sec-289)): `observe_agents` (list the other agents on stage with names and positions) and `say_to_agent` (send a message to a named stagemate).
+When the runtime is attached to an `<agent-stage>`, two extra tools are appended (see [multi-agent.md](#sec-290)): `observe_agents` (list the other agents on stage with names and positions) and `say_to_agent` (send a message to a named stagemate).
---
@@ -16869,7 +16903,7 @@ POST /api/pump/launch-agent { "agent_id": "…", "name": "…", "symbol": "…"
```
This is the path that supports USDC-paired curves and binds the on-chain pump
-agent for buybacks. See [the pump.fun launcher](#sec-333).
+agent for buybacks. See [the pump.fun launcher](#sec-339).
Both paths write a `pump_agent_mints` row and call back into the plan to mark it
launched, so a coin appears on [/launches](https://three.ws/launches), in the
@@ -16943,10 +16977,10 @@ doubles as a check on the lane.
## Related
-- [The pump.fun launcher](#sec-333): the launch transaction itself
-- [Coin launches](#sec-142): the platform launch directory
-- [Platform fee](#sec-334): what three.ws takes on a launch
-- [Solana on pump.fun](#sec-386): the on-chain program surface
+- [The pump.fun launcher](#sec-339): the launch transaction itself
+- [Coin launches](#sec-144): the platform launch directory
+- [Platform fee](#sec-340): what three.ws takes on a launch
+- [Solana on pump.fun](#sec-392): the on-chain program surface
Note on promotion: `$THREE` is the coin three.ws promotes. Agent tokens are coins
users launch through the platform, rendered from the platform's own launch
@@ -16965,9 +16999,9 @@ Every three.ws agent owns one custodial **Solana** wallet. Seven owner-only HTTP
This document is the API reference the surrounding docs deliberately leave out. Read those first for the "why":
- [Agent wallets](#sec-072) for how the wallet is created, how its key is held, and which paths may spend.
-- [Custody you can verify](#sec-167) for the limits, the freeze switch, the Merkle proof of custody, and the social-recovery model.
-- [Financial controls](#sec-219) for the plain-English spend-rule layer and the anomaly guard behind `/solana/guard`.
-- [The Trading Copilot](#sec-406) for the conversational surface that proposes trades a human confirms.
+- [Custody you can verify](#sec-170) for the limits, the freeze switch, the Merkle proof of custody, and the social-recovery model.
+- [Financial controls](#sec-221) for the plain-English spend-rule layer and the anomaly guard behind `/solana/guard`.
+- [The Trading Copilot](#sec-412) for the conversational surface that proposes trades a human confirms.
- [Coin Autopilot](#sec-106) for the *coin* cockpit at `/api/pump/autopilot`. That is a different feature from the **Treasury Autopilot** documented here, which runs the agent's own wallet rather than a launched coin.
## Orientation
@@ -17879,7 +17913,7 @@ The first `snapshot` is pushed immediately on connect. The stream carries only t
## Recovery: guardians, threshold, and inheritance
-Source: [`api/agents/recovery.js`](../api/agents/recovery.js), engine in [`api/_lib/agent-recovery.js`](../api/_lib/agent-recovery.js). Product tour: [Recovery](#sec-050), and the counterpart console in [Guardian](#sec-235).
+Source: [`api/agents/recovery.js`](../api/agents/recovery.js), engine in [`api/_lib/agent-recovery.js`](../api/_lib/agent-recovery.js). Product tour: [Recovery](#sec-050), and the counterpart console in [Guardian](#sec-236).
Recovery transfers *ownership*, never the key. The wallet secret is never decrypted, displayed, or moved. This is the one surface here that is not owner-only: a guardian or a beneficiary is a first-class caller with a scoped view.
@@ -18021,7 +18055,7 @@ Guardian or beneficiary only. No body. Arms the dead-man switch once the owner h
## Solana guard: the self-defending wallet
-Source: [`api/agents/solana-guard.js`](../api/agents/solana-guard.js), scoring in [`api/_lib/wallet-anomaly.js`](../api/_lib/wallet-anomaly.js), event store in [`api/_lib/anomaly-events.js`](../api/_lib/anomaly-events.js). Behavior narrative: [Financial controls](#sec-219).
+Source: [`api/agents/solana-guard.js`](../api/agents/solana-guard.js), scoring in [`api/_lib/wallet-anomaly.js`](../api/_lib/wallet-anomaly.js), event store in [`api/_lib/anomaly-events.js`](../api/_lib/anomaly-events.js). Behavior narrative: [Financial controls](#sec-221).
Scoring and freezing happen inline on the spend path, not here. This endpoint is the owner's window into that system and the control over it: read the learned baseline and the anomaly timeline, tune sensitivity, set a safe-sweep address, and adjudicate a freeze.
@@ -18139,12 +18173,12 @@ curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/solana/guard" \
## Related
- [Agent wallets](#sec-072) for the wallet itself: creation, key custody, and the five spend paths.
-- [Custody you can verify](#sec-167) for limits, freeze, proof of custody, and the recovery model in prose.
-- [Financial controls](#sec-219) for the plain-English spend rules and the wallet-defense behaviors.
-- [The Trading Copilot](#sec-406) for the conversational read-and-propose surface over the same wallet.
+- [Custody you can verify](#sec-170) for limits, freeze, proof of custody, and the recovery model in prose.
+- [Financial controls](#sec-221) for the plain-English spend rules and the wallet-defense behaviors.
+- [The Trading Copilot](#sec-412) for the conversational read-and-propose surface over the same wallet.
- [Coin Autopilot](#sec-106) for the separate coin cockpit at `/api/pump/autopilot`.
- [What agents can do](#sec-009) for a page per wallet ability, including [Access](#sec-049), [Orders](#sec-040), [Intents](#sec-042), [Autopilot](#sec-041), [Portfolio](#sec-031), and [Recovery](#sec-050).
-- [Guardian console](#sec-235) for the other side of a recovery request.
+- [Guardian console](#sec-236) for the other side of a recovery request.
---
@@ -18156,7 +18190,7 @@ curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/solana/guard" \
Every three.ws agent owns a **custodial Solana wallet**. It is what lets an agent act on its own — pay for an API call, buy a coin, tip another agent, receive its earnings — without a human approving each transaction in a browser extension.
-This is the reference for the wallet itself: how it's created, how its key is held, what may spend from it, and where the controls live. For the owner-facing safety story (limits, freeze, proof, recovery) read [Custody you can verify](#sec-167). For the complete tour of everything the wallet can do, read [What agents can do → The Agent Wallet](#sec-023).
+This is the reference for the wallet itself: how it's created, how its key is held, what may spend from it, and where the controls live. For the owner-facing safety story (limits, freeze, proof, recovery) read [Custody you can verify](#sec-170). For the complete tour of everything the wallet can do, read [What agents can do → The Agent Wallet](#sec-023).
## What you get
@@ -18176,7 +18210,7 @@ The encryption key derives, via HKDF, from a dedicated secret (`WALLET_ENCRYPTIO
This is the same secret box used for coin treasuries and the launcher, so every custodial secret on the platform is held the same way.
-**What this means honestly:** the platform can sign for the agent. That is the point — an autonomous agent that needs you to approve each transaction is not autonomous. What the platform gives you in exchange is that everything it *can* do is capped by policy you set, halted by a freeze you control, recorded in an audit trail, and provable on-chain. See [custody.md](#sec-167).
+**What this means honestly:** the platform can sign for the agent. That is the point — an autonomous agent that needs you to approve each transaction is not autonomous. What the platform gives you in exchange is that everything it *can* do is capped by policy you set, halted by a freeze you control, recorded in an audit trail, and provable on-chain. See [custody.md](#sec-170).
## Who can spend
@@ -18185,9 +18219,9 @@ Five paths move funds out of an agent wallet, and **all five pass through one po
| Path | Trigger |
|------|---------|
| Withdraw | The owner sweeps funds out |
-| x402 pay | The agent pays for a paid API call. Also reachable from any paid checkout on the site: the [x402 payment modal](#sec-451) lists a signed-in user's agents next to Phantom, and picking one settles from that agent's wallet with no popup |
+| x402 pay | The agent pays for a paid API call. Also reachable from any paid checkout on the site: the [x402 payment modal](#sec-457) lists a signed-in user's agents next to Phantom, and picking one settles from that agent's wallet with no popup |
| Trade | A discretionary buy/sell from the wallet hub, or from the in-world coin widget's **Pay with** selector (SOL-denominated coins) |
-| Purchase | The agent buys a marketplace skill or asset for itself (see [Marketplace](#sec-269)), under its own daily purchase cap |
+| Purchase | The agent buys a marketplace skill or asset for itself (see [Marketplace](#sec-270)), under its own daily purchase cap |
| Snipe | The autonomous sniper worker executes a strategy |
Because enforcement lives at the signing boundary rather than in each feature, a new feature cannot accidentally introduce an unguarded spend path.
@@ -18209,7 +18243,7 @@ Two asymmetries are deliberate:
Coin-launch and bonding-curve activity carries an additional SOL-denominated policy (`max_sol_per_tx`, `daily_sol_cap`, an optional `allowed_mints` allowlist). A freshly provisioned agent that has never been configured defaults to **1 SOL per transaction and 5 SOL per rolling day**, so a stolen session token cannot drain it.
-On top of the numeric caps sit two additive layers, each of which can only ever *narrow* a spend, never widen it: [natural-language spend rules](#sec-219) that an LLM authors and deterministic code enforces, and a behavioral anomaly guard that freezes the wallet when a spend doesn't look like the agent's normal behavior.
+On top of the numeric caps sit two additive layers, each of which can only ever *narrow* a spend, never widen it: [natural-language spend rules](#sec-221) that an LLM authors and deterministic code enforces, and a behavioral anomaly guard that freezes the wallet when a spend doesn't look like the agent's normal behavior.
### The audit trail
@@ -18217,7 +18251,9 @@ Every spend writes a row to the custody event ledger — amount, USD value, dest
## Where owners manage it
-The **Agent Wallet Hub** lives at `/agent/:id/wallet`. Owners see all 23 sections; a visitor to a public agent page sees a read-only view (balance and deposit address only). A network selector switches every read and write between mainnet and devnet.
+The **Agent Wallet Hub** lives at `/agent/:id/wallet`. Owners see all 23 sections; a visitor to a public agent page sees a read-only view: Balance, Deposit, Trust, Trade, and Pulse. Everything a visitor sees is public on-chain data, so the balance a visitor reads is the same live figure the owner reads. The transaction feed is the exception: it is owner-only server-side, so the visitor's Balance tab says so and links to the block explorer instead. A network selector switches every read and write between mainnet and devnet.
+
+`/agent-wallet` is the same hub reached without naming an agent. It resolves the signed-in owner's agents: one agent opens its hub directly, several render a picker, none offers a route to create the first one, and a signed-out visitor is asked to sign in.
Key endpoints:
@@ -18235,11 +18271,11 @@ An agent can pay a human-readable name instead of a base58 address. `/api/x402/p
## Related
-- [Custody you can verify](#sec-167) — limits, freeze, Merkle proof-of-custody, social recovery and inheritance
-- [Financial controls](#sec-219) — plain-English spend rules, compiled and enforced deterministically
+- [Custody you can verify](#sec-170) — limits, freeze, Merkle proof-of-custody, social recovery and inheritance
+- [Financial controls](#sec-221) — plain-English spend rules, compiled and enforced deterministically
- [What agents can do](#sec-009) — the complete dossier, including a page per wallet ability
-- [x402 protocol](#sec-519) — how agents pay for services
-- [Coin launches](#sec-142) — how the wallet signs a pump.fun launch
+- [x402 protocol](#sec-544) — how agents pay for services
+- [Coin launches](#sec-144) — how the wallet signs a pump.fun launch
---
@@ -18282,10 +18318,53 @@ You don't use an avatar by itself, and you don't use an agent without a body. Pa
- **From an agent's Studio (Body tab)**: click `Change avatar`. This opens the avatar picker; selecting an avatar attaches that body to the agent (the personality is untouched).
- **From Studio** — pick both sides explicitly. Use this when you want full control over name, skills, description, and wallet setup before publishing.
-## How to tell which page you're on
+## One page, both kinds: the studio
+
+Agents and avatars share a single detail page. `/avatars/<id>` and `/agents/<id>` render the same layout: a 3D stage on the left, identity and actions on the right, and tabs for Overview, Chat, Pose, Skills, Plugins and Embed. Everywhere on the platform that links to an entity (the search bar, `/agents`, `/gallery`, the marketplace, the galaxy, launches, profiles) lands you here, so the thing you clicked always opens the same way.
+
+The two modes differ only where the underlying entity does:
+
+| | `/avatars/<id>` | `/agents/<id>` |
+|---|---|---|
+| Type pill | `Avatar · 3D Body` | `Agent · AI Identity` |
+| Title + description | The avatar's | The agent's |
+| Views in the switcher | 3D, Chat, AR, Embed | 3D, Chat, AR, Embed, Profile |
+| Primary action | `Start an agent` | `Full profile` |
+| Chat | Voices the body | Speaks as the agent, using its brain and memory |
+| Third tab | `Skills`: add-ons you attach to the body | `Capabilities`: the skills this agent exposes, and their real per-call price |
+| Signals row | Views, forks, version, created | Skills, conversations, wallet, on-chain identity, active since |
+| Relationship card | `Used by`: the agents wearing this body | `Wearing`: the body this agent wears |
+| Below the fold | Related avatars | Similar agents |
+| Wallet | Only via a bound agent | The agent's own custodial wallet |
+
+Both directions are one click apart: an agent's `Wearing` card opens its body's page, and a body's `Used by` grid opens each agent that wears it.
+
+### Reading an agent's capabilities
+
+The `Capabilities` tab is the honest answer to "what can I call, and what does it cost?" Each row shows the skill's readable name, its exact slug (the string you pass to the API or an x402 call), and a badge: `Free`, a real price such as `1 USDC`, or `Token gated` when access is holding an NFT rather than paying. A summary line above the list names the cheapest paid call, so you learn the floor without reading every row.
+
+Prices are read straight off the agent record as atomic integers in the mint's own decimals and formatted from those digits, never divided into a float, so a nine-decimal mint stays exact. Buying is not duplicated here: trials, time passes and purchase all live on the [full profile](#the-long-form-agent-profile), which every priced row links to.
+
+### Every tab is an address
+
+The section tabs are a real WAI-ARIA tab list: arrow keys move between them, `Home` and `End` jump to the ends, and only the selected tab sits in the page's tab order. Selecting one writes it into the URL (`?view=chat`, `?view=skills`), so any tab can be linked or bookmarked, and `Overview` is the bare canonical URL with no parameter.
+
+### How to tell which page you're on
+
+- The type pill under the header says it outright, and its `?` link leads back to this page.
+- If the page can talk back as a named identity with a wallet, it's an agent.
+
+### The long-form agent profile
-- Avatar pages (`/avatars/<id>`) show a type pill reading `Avatar · 3D Body`, with a help link that leads back to this page.
-- Agent pages live at `/agents/<id>` and show the agent's name, on-chain badge (if registered), and chat surface. If a page can talk back, it's an agent.
+An agent carries more than a body: capabilities and skill pricing, economy and holdings, an activity log, trust and on-chain identity, reviews, and developer tooling (embed snippets, MCP wiring, raw metadata). That lives one level deeper at `/agents/<id>/profile`, reachable from the `Full profile` button and the `Profile` segment of the view switcher. The pre-redesign layout is still served at `/agents/<id>/classic`.
+
+### Sharing and canonical URLs
+
+Every entity has exactly one canonical URL: `/avatars/<id>` or `/agents/<id>`. The `?view=` variants (chat, embed) and `?embed=1` are the same page in a different tab, and they all declare the canonical URL, so links collapse to one document when shared. An id shared on the wrong route redirects to the right one instead of showing "not found" (an agent id at `/avatars/<id>` lands on `/agents/<id>`, and the reverse).
+
+### Agents without a body
+
+Agents can exist before they wear anything. Their studio page still renders in full: the identity, wallet, chat and skills all work, and the stage explains the gap with two ways to close it (create a body, or pick one from the marketplace). Body-scoped surfaces (AR, the Pose tab, forks, GLB stats, coin launches) stay hidden rather than rendering empty shells.
## Frequently confused
@@ -18385,11 +18464,11 @@ An "awakening" envelope (no eligible trading agent yet) is still valid and fully
## Related
-- [Oracle](#sec-310) - the conviction engine this class of agent trades on
+- [Oracle](#sec-315) - the conviction engine this class of agent trades on
- [Agent reputation](#sec-056) - the Reasoning Ledger score behind the reputation ring
-- [Reputation](#sec-362) - how proven on-chain track records are computed
-- [The trading experiment](#sec-407) - an autonomous agent operating inside these limits, journaled
-- [Custody you can verify](#sec-167) - the spend caps and kill switch the autonomy runs under
+- [Reputation](#sec-367) - how proven on-chain track records are computed
+- [The trading experiment](#sec-413) - an autonomous agent operating inside these limits, journaled
+- [Custody you can verify](#sec-170) - the spend caps and kill switch the autonomy runs under
- [/activity](https://three.ws/activity) - every agent's live trades in real time
---
@@ -20340,9 +20419,9 @@ of rendering a fake zero.
## Related surfaces
-- [`/portfolio`](#sec-325): the live wallet portfolio; the two pages
+- [`/portfolio`](#sec-331): the live wallet portfolio; the two pages
cross-link and share the recent-wallet list.
-- [`/api/crypto/wallet`](#sec-166): the raw balance endpoint the token
+- [`/api/crypto/wallet`](#sec-169): the raw balance endpoint the token
diversity measurement rides on.
---
@@ -20422,10 +20501,10 @@ When `read.hallucination_guard.line_replaced` is true, the co-pilot caught a fig
## Related
-- [Custody you can verify](#sec-167) - the spend limits, firewall, and audit the "Act" path runs under
-- [Financial controls](#sec-219) - the plain-English rules and real-time defense on the same rails
-- [Oracle](#sec-310) - the platform conviction engine over the same launch universe
-- [Trading surfaces](#sec-409) - Mission Control executes through this same guarded path
+- [Custody you can verify](#sec-170) - the spend limits, firewall, and audit the "Act" path runs under
+- [Financial controls](#sec-221) - the plain-English rules and real-time defense on the same rails
+- [Oracle](#sec-315) - the platform conviction engine over the same launch universe
+- [Trading surfaces](#sec-415) - Mission Control executes through this same guarded path
- [/agi](https://three.ws/agi) - a fully autonomous agent reading and trading the same feed
---
@@ -20632,7 +20711,7 @@ If you extend the metric, keep two properties: the retention window must stay an
# Animation Studio: pose, keyframe, and sell motion
-Animation Studio is where a three.ws avatar (or a built-in mannequin) becomes animated. Click any body part and rotate it with a gizmo, or drag a hand or foot and let inverse kinematics solve the limb. Drop the pose as a keyframe, advance the playhead, re-pose, and drop another; the studio interpolates between them and plays the result. Export the finished motion as an animated GLB or as clip JSON, save it to your account, deep-link it to play on any avatar, hand it to [Scene Studio](#sec-368) to record as video, or list it for sale in the animation marketplace for USDC.
+Animation Studio is where a three.ws avatar (or a built-in mannequin) becomes animated. Click any body part and rotate it with a gizmo, or drag a hand or foot and let inverse kinematics solve the limb. Drop the pose as a keyframe, advance the playhead, re-pose, and drop another; the studio interpolates between them and plays the result. Export the finished motion as an animated GLB or as clip JSON, save it to your account, deep-link it to play on any avatar, hand it to [Scene Studio](#sec-373) to record as video, or list it for sale in the animation marketplace for USDC.
Page: [/pose](https://three.ws/pose) · API: `/api/animations/clips`
@@ -20666,7 +20745,7 @@ Under the motion generator sits a Spell box: type a word and the avatar spells i
A spelled word is shareable as a link: `https://three.ws/pose?spell=HELLO` opens the studio, auto-loads a rigged avatar (same roster as animation deep links), and spells the word on arrival.
-Fingerspelling is the deterministic, spelling-based subset of sign language, it spells English words rather than translating into grammatical ASL. The Studio's Spell box is spelling only. The platform also has a lexical vocabulary (words that are signed rather than spelled, on one or both hands), which drives [/sign-language](https://three.ws/sign-language), signed chat replies, and the `sign-language` embed attribute. See [docs/sign-language.md](#sec-376) for the whole system, or the tutorial [Make your avatar sign](https://three.ws/tutorials/sign-with-your-avatar) for a guided tour.
+Fingerspelling is the deterministic, spelling-based subset of sign language, it spells English words rather than translating into grammatical ASL. The Studio's Spell box is spelling only. The platform also has a lexical vocabulary (words that are signed rather than spelled, on one or both hands), which drives [/sign-language](https://three.ws/sign-language), signed chat replies, and the `sign-language` embed attribute. See [docs/sign-language.md](#sec-381) for the whole system, or the tutorial [Make your avatar sign](https://three.ws/tutorials/sign-with-your-avatar) for a guided tour.
### Export, save, and sell
@@ -20728,8 +20807,8 @@ An empty `tracks` array is rejected: a clip with no motion is not a clip. Track
- [Animations reference](#sec-093): the runtime clip registry, formats, and agent slots.
- [3D asset pipeline](#sec-002): how GLB, FBX, and clip JSON convert across the platform.
-- [Scene Studio](#sec-368): record your animation to video.
-- [Avatar Studio](#sec-114): build the avatar you animate here.
+- [Scene Studio](#sec-373): record your animation to video.
+- [Avatar Studio](#sec-115): build the avatar you animate here.
- [/marketplace](https://three.ws/marketplace): where listed animation clips are bought and sold.
---
@@ -20740,7 +20819,7 @@ An empty `tracks` array is rejected: a clip with no motion is not a clip. Track
# Animations
-Animations are the motion clips (idle, wave, dance, and about 2,000 more) that bring three.ws avatars to life. Browse and preview every clip at [three.ws/animations](https://three.ws/animations); this page is the developer reference for how the clip collections are organized, how the runtime loads them, and how agents pick which clip to play.
+Animations are the motion clips (idle, wave, dance, and about 3,000 more) that bring three.ws avatars to life. Browse and preview every clip at [three.ws/animations](https://three.ws/animations); this page is the developer reference for how the clip collections are organized, how the runtime loads them, and how agents pick which clip to play.
> For how FBX, GLB, and clip JSON relate — the formats, the conversions, and the full generate→rig→animate→export chain — see **[docs/3d-asset-pipeline.md](#sec-002)**. This page is the runtime registry and agent-slot reference.
@@ -20866,12 +20945,13 @@ Its measured companion is `public/animations/signatures.json`: a motion-signatur
## The /animations gallery
-[three.ws/animations](https://three.ws/animations) is the public browse surface over every clip: the curated studio manifest, the full R2-hosted motion-capture library (`GET /api/animations/library`, ~2,000 clips), and community-published clips (`GET /api/animations/clips?visibility=public`).
+[three.ws/animations](https://three.ws/animations) is the public browse surface over every clip: the curated studio manifest, the full R2-hosted motion-capture library (`GET /api/animations/library`, ~2,900 clips; `total` on that response is the live count), and community-published clips (`GET /api/animations/clips?visibility=public`).
-- **Poster thumbnails** — every clip has a WebP still of the preview avatar posed mid-motion. Rendered offline by `node scripts/build-animation-thumbnails.mjs` (drives `scripts/thumbnail-harness.html` in headless Chromium through the site's own retarget engine). Curated thumbs are committed at `public/animations/thumbs/<name>.webp`; library thumbs upload to R2 alongside their clips via `npm run mixamo:upload`, which publishes each one as the manifest entry's `thumb` URL. Added a clip? Re-run the thumbnail script, then re-upload.
+- **Poster thumbnails**: a WebP still of the preview avatar posed mid-motion, rendered offline by `node scripts/build-animation-thumbnails.mjs` (which drives `scripts/thumbnail-harness.html` in headless Chromium through the site's own retarget engine). Curated thumbs are committed at `public/animations/thumbs/<name>.webp`; library thumbs upload to R2 alongside their clips via `npm run mixamo:upload`, which publishes each one as the manifest entry's `thumb` URL. Added a clip? Re-run the thumbnail script, then re-upload. **The library manifest's `thumb` field is the only source of truth for a library thumbnail.** Coverage is partial (853 of 2,874 entries carry no `thumb` as of 2026-08-16), and the gallery renders the clip's icon for those instead of guessing a CDN path: the guess 404s on every one of them, which cost a blocked cross-origin request per card.
- **Categories** — the Mixamo catalog carries no category metadata, so `src/animation-categories.js` derives one per clip from its label (ordered keyword rules; curated clips keep their hand-assigned `animation-presets.js` category). Covered by `tests/animation-categories.test.js`, which also asserts <10% of the real library falls into the "More" catch-all.
- **Live previews** — one shared WebGL engine (`src/animations-live-preview.js`) serves every card hover and the detail modal: a single renderer + preview avatar; the canvas moves into whichever card is previewing. Nothing 3D loads until the first hover.
-- **Deep links** — `?clip=<id>` opens a clip's detail modal directly; `q`, `cat`, `filter`, and `sort` round-trip through the URL so filtered views are shareable.
+- **Deep links**: `?clip=<id>` opens a clip's detail modal directly; `q`, `cat`, `filter`, and `sort` round-trip through the URL so filtered views are shareable. Every one of them is validated against the values the controls can represent, so a hand-edited `?sort=bogus` falls back to `featured` rather than blanking the sort menu, and an arriving `?filter=once` presses the matching segmented button instead of filtering invisibly.
+- **Detail modal**: a real dialog. Focus moves into it on open, Tab wraps inside it, Escape closes it and returns focus to the card that opened it. Arrow keys step through the filtered list (except while a slider is focused, which owns its own arrows), and Space toggles playback. The transport row only appears once a clip is actually on the stage, so a preview that fails to load shows the error and its Studio link rather than controls that do nothing.
## Known issues
@@ -21515,7 +21595,7 @@ This is the reference for the three.ws HTTP API: every documented endpoint, its
Base URL: `https://three.ws/api`
-> For the in-browser JavaScript API (the `<agent-3d>` element, `Viewer`, `Runtime`, `SceneController`, skills, memory), see [js-api.md](#sec-257) and [web-component.md](#sec-502). For the high-level npm SDK, see [sdk.md](#sec-369).
+> For the in-browser JavaScript API (the `<agent-3d>` element, `Viewer`, `Runtime`, `SceneController`, skills, memory), see [js-api.md](#sec-258) and [web-component.md](#sec-508). For the high-level npm SDK, see [sdk.md](#sec-374).
The full machine-readable schema lives at [`https://three.ws/.well-known/openapi.yaml`](https://three.ws/.well-known/openapi.yaml). x402 paid endpoints are listed at [`/.well-known/x402.json`](https://three.ws/.well-known/x402.json) and the MCP endpoint is at [`/api/mcp`](https://three.ws/api/mcp).
@@ -21883,6 +21963,79 @@ Requires auth. Owner only. Soft-deletes via `deleted_at` timestamp.
---
+### Duplicate widget
+
+```
+POST /api/widgets/:id/duplicate
+```
+
+Requires auth. Owner only; bearer tokens need `avatars:write`. Clones the widget's type, name, config, avatar, and visibility into a new row with a freshly minted `wdgt_` id and ` (copy)` appended to the name (truncated to 120 characters). Cookie-session callers must send `X-CSRF-Token`; bearer callers are exempt.
+
+**Response** (`201`): the new widget object, same shape as create.
+
+---
+
+### Widget stats
+
+```
+GET /api/widgets/:id/stats
+```
+
+Requires auth. Owner only; bearer tokens need `avatars:read`. Returns the analytics envelope behind the dashboard's widget card: lifetime `view_count`, `last_viewed_at`, an 8-day zero-filled `recent_views_7d` sparkline, and the top five `top_referers` / `top_countries`.
+
+Talking-agent widgets additionally get `chat_count`, an 8-day `recent_chats_7d` sparkline of visitor messages, `top_questions` (visitor messages clustered by normalized prefix), `knowledge` (`doc_count` / `chunk_count` / `token_count`), and `sessions_7d` (`thread_count`, `avg_seconds`, `total_messages`). Those five fields are `null` for every other type. Response is cached `private, max-age=30`.
+
+---
+
+### Widget chat
+
+```
+POST /api/widgets/:id/chat
+```
+
+Talking-agent widgets only. Public widgets accept anonymous visitors; a private widget answers `404` to anyone but its owner. Rate limited per (IP, widget) at the owner's `config.visitorRateLimit.msgsPerMinute` (default 8); the owner's own preview is exempt.
+
+**Request body:** `{ message, history?, provider?, model?, visitor_id?, thread_id? }`. `message` is 1 to 4000 characters, `history` is up to 40 `{ role, content }` turns, and `visitor_id` / `thread_id` are opaque client-minted ids (8 to 64 url-safe characters) used to group transcripts. `provider` / `model` are honoured only when the owner left the brain on `auto` or a named provider; an owner who pinned `none` or `custom` cannot be overridden by a visitor.
+
+**Response:** an SSE stream (`text/event-stream`) with an `event: message` frame carrying `{ reply, actions }`, then `event: done`. Upstream trouble sends `event: error` instead. `actions` only ever contains skills the owner enabled (`wave`, `lookAt`, `playClip`, `remember`). Validation failures answer with an ordinary JSON `400` before the stream opens.
+
+Every turn on a real widget is persisted to its transcript with PII redacted; the public gallery's demo fixtures are stateless and keep no transcript. Replies the platform generated itself (no provider configured, or the whole failover chain refused) are stored with no provider or model attribution.
+
+---
+
+### Widget transcripts
+
+```
+GET /api/widgets/:id/transcripts
+GET /api/widgets/:id/transcripts?thread_id=<id>
+GET /api/widgets/:id/transcripts?format=csv
+```
+
+Requires auth. Owner only; bearer tokens need `avatars:read`. The list form returns `{ threads, next_cursor, totals }`, newest thread first, `limit` 1 to 100 (default 25) with keyset pagination through `before=<ISO timestamp>`. Passing `thread_id` returns `{ thread, messages }` for one conversation, or `404` if that thread is not on this widget. `format=csv` downloads up to 5000 messages as an attachment for spreadsheet review.
+
+---
+
+### Widget knowledge base
+
+```
+GET /api/widgets/:id/knowledge
+GET /api/widgets/:id/knowledge?test=<query>&top_k=<n>
+POST /api/widgets/:id/knowledge
+DELETE /api/widgets/:id/knowledge?doc_id=<id>
+```
+
+Requires auth. Owner only; bearer tokens need `avatars:read` for `GET` and `avatars:write` for the rest.
+
+`GET` lists the widget's docs with `status` (`queued`, `processing`, `ready`, `failed`), chunk and token counts. Adding `test=` runs the retrieval debugger: it embeds the probe query and returns the top-K matching chunks with cosine scores, so you can confirm a doc is reachable without spending a chat turn.
+
+`POST` ingests one document (talking-agent widgets only, 25 docs per widget). Body is one of `{ source_type: "url", source_url }`, or `{ source_type: "text" | "markdown" | "pdf", content, title }`. URLs are fetched and stripped to text server-side; PDFs are extracted in the browser and posted as text. Small docs embed inline and come back `ready`; large ones return `queued` and finish on the background worker.
+
+`DELETE` removes one doc and its chunks by `doc_id`.
+
+The knowledge routes need an embedding provider on the server (`NVIDIA_API_KEY` or `OPENAI_API_KEY`); without one they answer `503 embedder_unavailable` rather than guessing.
+
+---
+
### Open Graph share card
```
@@ -21969,6 +22122,59 @@ Append-only. Actions are never deleted. Optionally include an ERC-191 signature
---
+### Batch recent activity for many agents
+
+```
+GET /api/agents/activity?ids=<id>,<id>,...
+POST /api/agents/activity { "ids": ["<id>", "<id>"] }
+```
+
+Recent activity for a **list** of agents in one round-trip, plus which of them
+currently have a live screen caster pushing frames. Built for grids: a wall of
+agent cards would otherwise need one request (or one SSE stream) per card, and a
+browser only allows a handful of concurrent connections per origin.
+
+Public read, no auth. Up to 60 ids per call; anything that is not a UUID is
+dropped, and unknown ids are simply absent from `activity`. Each agent returns
+its 24 most recent actions, oldest-first, in the same entry shape the `log`
+event of the per-agent SSE stream (`GET /api/agent-screen-stream?agentId=<id>`)
+emits, so one renderer handles both.
+
+**Query / body parameters**
+
+| Parameter | Type | Description |
+| --------- | -------- | ------------------------------------------------------------ |
+| `ids` | string[] | Required. Agent IDs. Comma-separated on GET, an array on POST |
+
+**Response**
+
+```json
+{
+ "activity": {
+ "abc123": [
+ { "ts": 1786573115539, "activity": "Launched $THREE", "type": "pumpfun.launch" },
+ { "ts": 1786573802902, "activity": "Defended floor at 0.51 SOL", "type": "mm_defend",
+ "mm": { "type": "mm_defend", "floorSol": 0.5, "priceSol": 0.51, "sizeSol": 2,
+ "sideBuy": true, "simulate": false, "signature": null, "mint": null } }
+ ]
+ },
+ "casting": ["abc123"]
+}
+```
+
+`casting` lists the subset of the requested ids whose screen frame is still live
+in the frame store. A client typically renders every agent's `activity` straight
+away and opens a real SSE stream only for the ids in `casting`.
+
+**Example**
+
+```bash
+curl -s "https://three.ws/api/agents/activity?ids=$AGENT_A,$AGENT_B" \
+ | jq '{casting, counts: (.activity | map_values(length))}'
+```
+
+---
+
## Agent Memory API
### Fetch agent memory
@@ -22047,6 +22253,201 @@ Requires auth. Deletes a single memory by its platform ID.
---
+## Memory seed connectors API
+
+Public-footprint readers that turn an account handle into the raw material for a
+memory seed, plus the synthesizer that writes the seed itself. This is the lane
+behind [/demos/memory-seed](https://three.ws/demos/memory-seed) and the seed
+widget in `src/memory-seed.js`.
+
+Everything these endpoints read is already public. They are read-only, request
+no OAuth from the visitor, and store nothing; the consent-gated seeding flows
+that do write to an agent live at `/api/agents/:id/memory/seed/*` and are
+documented in [GitHub](#sec-234), [X](#sec-515)
+and [Farcaster](#sec-220) memory seeding.
+
+The three connectors are unauthenticated GETs, rate limited per IP, and cached
+at the edge for 5 minutes. A connector that cannot reach its upstream answers
+`200` with `{ "ok": false, "reason", "detail" }` so a partly-configured
+deployment degrades to a greyed-out card instead of a failed page; a bad handle
+is still a `4xx`.
+
+### GitHub footprint
+
+```
+GET /api/seed/github?handle=<user>
+```
+
+No credentials required. `GITHUB_TOKEN` is used when present, purely for the
+higher rate limit.
+
+```bash
+curl -s 'https://three.ws/api/seed/github?handle=nirholas'
+```
+
+```json
+{
+ "ok": true,
+ "handle": "nirholas",
+ "name": "nich",
+ "bio": "",
+ "followers": 617,
+ "public_repos": 223,
+ "top_repos": [
+ {
+ "name": "fresh-start",
+ "description": "The original repo, restored.",
+ "stars": 6250,
+ "language": null,
+ "html_url": "https://github.com/nirholas/fresh-start"
+ }
+ ],
+ "top_readme_excerpt": "# fresh-start"
+}
+```
+
+Errors: `400 invalid_request` (no handle), `400 invalid_handle` (illegal
+characters), `404 not_found` (no such user), `502 upstream_error`.
+
+---
+
+### Farcaster footprint
+
+```
+GET /api/seed/farcaster?handle=<fname-or-fid>
+```
+
+No credentials required. Reads through the platform's shared Farcaster client,
+which prefers Neynar when `NEYNAR_API_KEY` is set and otherwise falls back to a
+public Farcaster hub over HTTP (`FARCASTER_HUB_URL`, default
+`https://hub.pinata.cloud`).
+
+`lane` names the rung that answered. The hub serves raw protocol messages and
+therefore has no reaction counts, so `follower_count`, `following_count` and
+per-cast `engagement` are `null` on that lane rather than `0`. Casts are ranked
+by engagement where the lane knows it and by recency where it does not, with
+replies, link-only posts and duplicates dropped.
+
+```bash
+curl -s 'https://three.ws/api/seed/farcaster?handle=dwr'
+```
+
+```json
+{
+ "ok": true,
+ "lane": "hub",
+ "handle": "dwr",
+ "fid": 3,
+ "display_name": "Dan Romero",
+ "bio": "Working on Farcaster",
+ "follower_count": null,
+ "recent_casts": [
+ {
+ "text": "Best store-bought eggnog available on the west coast",
+ "timestamp": "2025-11-28T01:35:34.000Z",
+ "engagement": null
+ }
+ ]
+}
+```
+
+Errors: `400 invalid_request`, `400 invalid_handle`, `404 not_found`. A hub
+answers an unknown fname with `400` and a `NotFound` detail; that is normalised
+to a `404` here so a typo cannot read as an outage.
+
+---
+
+### X footprint
+
+```
+GET /api/seed/x?handle=<user>
+```
+
+X has no keyless public read lane, so this connector needs one of two credential
+sets and reports `ok: false` without either:
+
+1. `TWITTER_BEARER_TOKEN`, an app-only bearer from the developer portal.
+2. `X_API_KEY` + `X_API_SECRET`, the OAuth 1.0a consumer pair. The handler
+ exchanges them for an app-only bearer at runtime via `appLogin()`, so a
+ deployment that already holds the changelog poster's app credentials needs
+ nothing new provisioned.
+
+```bash
+curl -s 'https://three.ws/api/seed/x?handle=jack'
+```
+
+```json
+{
+ "ok": true,
+ "handle": "jack",
+ "name": "jack",
+ "bio": "no state is the best state",
+ "follower_count": 11300858,
+ "tweet_count": 30894,
+ "recent_tweets": [
+ {
+ "text": "joel is awesome",
+ "created_at": "2026-08-10T21:54:11.000Z",
+ "likes": 1458,
+ "retweets": 87,
+ "replies": 115
+ }
+ ],
+ "top_topics": [{ "topic": "agents", "count": 4 }]
+}
+```
+
+Errors: `400 invalid_request`, `400 invalid_handle`, `404 not_found`. A rate
+limit or outage on the timeline read keeps the profile payload and returns an
+empty `recent_tweets` rather than failing the request.
+
+---
+
+### Synthesize a memory seed
+
+```
+POST /api/seed/synthesize
+```
+
+Requires auth (session cookie or bearer token). Takes any subset of the three
+connector payloads verbatim and returns a 200-300 word markdown memory seed. The
+completion runs on the platform LLM chain (`api/_lib/llm.js`), which leads with
+free and keyless providers, so no provider key is required.
+
+**Request body**
+
+```json
+{
+ "connectors": {
+ "github": { "ok": true, "handle": "nirholas", "top_repos": [] },
+ "x": { "ok": true, "handle": "jack" },
+ "farcaster": { "ok": true, "handle": "dwr", "fid": 3 }
+ }
+}
+```
+
+Connector payloads carrying `ok: false` are ignored. At least one usable payload
+is required.
+
+**Response**
+
+```json
+{
+ "ok": true,
+ "memory_seed": "### Interests\nThe user is a prolific builder...",
+ "sources_used": ["github", "x", "farcaster"],
+ "tokens_used": 2670,
+ "usage": { "input_tokens": 2300, "output_tokens": 370 },
+ "model": "gemini-3.1-flash-lite"
+}
+```
+
+Errors: `401 unauthorized`, `400 validation_error` (unknown key, or no connector
+supplied), `400 no_signal` (every payload unusable), `429
+daily_spend_cap_exceeded`, `502 upstream_error`, `503 llm_unavailable`.
+
+---
+
## Chat / LLM API
### Agent chat
@@ -22191,6 +22592,120 @@ Your original body is never mutated, and none of this changes the response shape
---
+### Persona extraction
+
+```
+POST /api/persona/extract
+```
+
+Turns a short onboarding interview (or a block of the person's own writing) into a structured persona profile you can save on an agent and reuse as its voice. Requires auth: a session cookie, or a bearer API key carrying `avatars:read` or `avatars:write`. Try it live at [/demos/persona-extract.html](https://three.ws/demos/persona-extract.html).
+
+**Request body**: send exactly one of `answers` or `freeform`.
+
+```json
+{
+ "answers": [
+ { "question": "How do you like people to talk to you?", "answer": "Short. No preamble. Give me the number and the tradeoff." },
+ { "question": "What are you into?", "answer": "Solana infra, GPU pipelines, and shipping fast." },
+ { "question": "What phrases do you hate?", "answer": "Circle back. Synergy." }
+ ]
+}
+```
+
+| Field | Type | Notes |
+| ---------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
+| `answers` | array of `{question, answer}` | 1 to 12 entries. Both strings required and non-empty; each is truncated at 1200 chars. |
+| `freeform` | string | Alternative to `answers`: any sample of the person's writing. Truncated at 8000 chars. |
+
+`freeform` wins when both are present. A body with neither is a `400`.
+
+**Response `200`**
+
+```json
+{
+ "persona": {
+ "tone": "Direct and to the point with a focus on key information",
+ "vocabulary": ["number", "tradeoff", "shipping fast", "infra", "pipelines"],
+ "interests": ["Solana", "GPU pipelines", "software development"],
+ "communication_style": "terse",
+ "dont_say": ["Circle back", "Synergy"],
+ "sample_greeting": "What's the key issue and what are the numbers?"
+ },
+ "model": "Meta-Llama-3_3-70B-Instruct",
+ "tokens_used": 516,
+ "tokens_in": 415,
+ "tokens_out": 101,
+ "latency_ms": 3852
+}
+```
+
+`communication_style` is always one of `terse`, `detailed`, `playful`, `analytical`, `warm`. The server clamps the model's output before returning it: at most 10 `vocabulary` entries, 5 `interests`, and 3 `dont_say` entries. `model` names the provider rung that actually served the call, which varies with the failover chain, so do not pin behaviour to it.
+
+**Rate limit:** 5 per user per day. A malformed body is rejected before the limiter runs, so a typo never costs you a call.
+
+---
+
+### Persona preview
+
+```
+POST /api/persona/preview
+```
+
+Replies to one message in the voice of a persona, so a user can audition a profile before saving it. Same auth as extraction. Stateless: pass the persona on every call.
+
+**Request body**
+
+```json
+{
+ "persona": {
+ "tone": "Direct and to the point with a focus on key information",
+ "vocabulary": ["number", "tradeoff", "shipping fast"],
+ "communication_style": "terse",
+ "dont_say": ["Circle back"]
+ },
+ "user_message": "Should we ship the new forge lane today?"
+}
+```
+
+| Field | Type | Notes |
+| -------------- | ------ | ------------------------------------------------------------------------------------------------------- |
+| `persona` | object | Any object; the shape returned by `/api/persona/extract` is what the prompt is written for. Rejected above 8000 chars serialized, because the persona is pinned into the system prompt verbatim and its size is prompt size. |
+| `user_message` | string | Required, non-empty. Truncated at 1500 chars. |
+
+**Response `200`**
+
+```json
+{
+ "reply": "What are the performance numbers on the GPU pipelines? We need to ship fast, but only if the infra tradeoff is net positive.",
+ "model": "gemini-3.1-flash-lite",
+ "tokens_used": 326,
+ "tokens_in": 300,
+ "tokens_out": 26,
+ "latency_ms": 3016
+}
+```
+
+Replies are capped at 1 to 2 sentences by design; this endpoint is an audition surface, not a chat runtime. For a real conversation use [`POST /api/chat`](#agent-chat) or [`POST /api/brain/chat`](#brain-proxy-multi-provider-llm).
+
+**Rate limit:** 30 per user per hour.
+
+**Errors (both persona routes)**
+
+| Status | `error` | Meaning |
+| ------ | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `400` | `bad_request` | Malformed or missing fields. `error_description` names the offending one. |
+| `401` | `unauthorized` | No session and no bearer key with an `avatars:*` scope. |
+| `415` | `bad_request` | `content-type` was not `application/json`. |
+| `429` | `rate_limited` | Per-user budget spent. `retry_after` and the standard `ratelimit-*` headers are set. |
+| `429` | `daily_spend_cap_exceeded` | The account's daily LLM spend ceiling, not the call-count limiter. Resets on its own window. |
+| `502` | `upstream_error` | Every provider in the chain failed or returned an empty completion. Retryable. |
+| `502` | `parse_error` | The model answered with something other than a usable persona (extraction only). Retryable. |
+| `503` | `config_missing` | The deployment has no LLM provider configured. |
+
+Both routes run the shared multi-provider failover chain, so a single upstream `429`/`5xx` falls through to the next provider instead of reaching you.
+
+---
+
## TTS API
### Voice catalog
@@ -22208,7 +22723,7 @@ Gemini, NVIDIA), a session adds the metered ones (OpenAI, ElevenLabs), and an
| Param | Meaning |
| --- | --- |
-| `provider` | `edge`, `gemini`, `nvidia`, `openai`, `elevenlabs`. Omit for all. |
+| `provider` | `edge`, `gemini`, `nvidia`, `openai`, `elevenlabs`. Omit for all. Anything else is a `400 validation_error` listing the lanes that exist. |
| `q` | Substring match over name, id, locale, and labels. |
| `language` | Primary subtag or full locale, e.g. `ja`, `en-GB`. |
| `limit` | Max voices returned (default 400, max 2000). |
@@ -22281,6 +22796,14 @@ lanes require a session or bearer token.
`models` and `direction` fields say which). `speed` is clamped to 0.5 to 2.0.
Max 1,000 characters. ElevenLabs additionally accepts `voice_settings`.
+`voiceId` must be one the chosen lane publishes. A `voiceId` the lane does not
+have returns `400 validation_error` naming the id and the catalog URL to pick
+from, before anything is metered; it is never quietly swapped for the lane's
+default voice. Omit `voiceId` entirely to get the lane default on purpose.
+ElevenLabs is the exception: its catalog grows at runtime (cloning, library
+adds), so an id it does not recognize comes back as a `400` carrying the
+upstream verdict rather than being pre-checked here.
+
**Response**
Audio binary in the lane's container (`audio/mpeg` for Edge and ElevenLabs,
@@ -22292,6 +22815,19 @@ clip is cached in R2 for 30 days on a hash of the full request; cache hits are
never charged. A short credit balance returns `402 insufficient_credits` with a
`top_up_url`.
+**When a lane is down**
+
+An upstream failure answers with a single sentence a picker can render in
+`error_description`, the vendor's own text in `detail`, and the lane id in
+`provider`. A lane that refuses this deployment's credentials (an expired key, a
+billing hold) is then withheld for a few minutes: `/api/tts/catalog` reports it
+`available: false` with the reason, and a synthesis request aimed at it answers
+`503 lane_unavailable` carrying `retry_with: ["edge", "nvidia"]` instead of
+spending another doomed round trip. The window clears on its own, and a lane
+that serves successfully is restored immediately, so nothing has to be deployed
+or flipped by hand when the upstream problem is fixed. A request carrying your
+own `x-eleven-key` is never gated by the platform key's outage.
+
### ElevenLabs Voice Library
```
@@ -22304,7 +22840,9 @@ Search the public catalog ElevenLabs users share (`q`, `gender`, `accent`,
`POST { publicUserId, voiceId, name }` to copy one into the account behind the
request (yours with `x-eleven-key`, the platform's otherwise). The POST returns
a normal `voice_id` usable with `/api/tts/synthesize`. Both require auth and an
-ElevenLabs key.
+ElevenLabs key. A key ElevenLabs rejects returns `401 invalid_key` (here and on
+`/api/tts/eleven/voices`), so a client knows to ask for a new key rather than
+retry a `502` that will never clear.
### Text-to-speech (ElevenLabs, streaming)
@@ -22336,6 +22874,8 @@ Text-to-speech via ElevenLabs with R2 caching. Requires auth.
Audio binary. `Content-Type: audio/mpeg`.
+A `voiceId` the account behind the request does not have returns `400 validation_error` (the charge, if any, is refunded first); a genuine ElevenLabs fault stays `502 upstream_error`.
+
Responses are cached in R2 by `sha256(voiceId + text + modelId)` for 30 days — identical requests return cached audio without hitting ElevenLabs.
---
@@ -22631,7 +23171,37 @@ render URL-addressable for `og:image` unfurls, `<img>` tags, and markdown
embeds; responses CDN-cache for a day so crawlers hit chromium once per
model. Dimensions clamp to 64-2048; GLBs over 10 MB are rejected before the
browser boots; only public http(s) sources are fetched (SSRF-guarded);
-60 renders / 10 min / IP.
+60 renders / 10 min / IP, a budget shared with `/api/render/avatar-clip`.
+
+`background` is `transparent` or a CSS color (`#0a0a0a`, `#fff`,
+`rgb()`/`rgba()`, `hsl()`/`hsla()`, or a named color such as `midnightblue`).
+Anything else is `400 bad_request`: the value is composited into the render
+page, so it is validated rather than escaped.
+
+### Posed avatar renderer: `GET|POST /api/render/avatar-clip`
+
+```
+GET /api/render/avatar-clip → the pose catalog (id, label, group)
+POST /api/render/avatar-clip
+{
+ "glbUrl": "https://...", # required, public http(s)
+ "width": 1024, "height": 1024, # default 1024, clamped 64-2048
+ "background": "transparent", # or a CSS color, as above
+ "posePresetId": "wave", # any id from the GET catalog
+ "cameraOrbit": { "theta": 25, "phi": 75, "radius": null },
+ "expression": { "jawOpen": 0.4 } # ARKit-52 morph targets
+}
+→ image/png, plus x-render-pose / x-render-pose-label headers
+```
+
+The same renderer with a pose stage in front of it. `posePresetId` is retargeted
+onto the model's own rest pose through the studio's posing stack, so a preset
+lands the same way whatever naming convention the rig's skeleton uses, and a
+model with no recognizable humanoid skeleton renders in its bind pose instead of
+failing. `cameraOrbit.theta`/`phi` are degrees (yaw, and pitch from the top);
+`radius` is meters, or `null` to auto-frame from the bounding box. An unknown
+`posePresetId` is `400 unknown_pose`. Same 10 MB cap, SSRF guard, and render
+budget as `/api/render/glb`.
### Forge-Off votes — `POST /api/forge-vote`
@@ -22658,7 +23228,7 @@ x-forge-client: <stable browser id> # optional — resolves per-card `voted`
`sort=fresh` (default, newest-first) or `sort=top` (most-voted); `window=week`
narrows Top to the current Forge-Off week (Monday→Monday UTC). Full feature
-docs: [docs/forge-off.md](#sec-222).
+docs: [docs/forge-off.md](#sec-223).
### Model detail page read: `GET /api/forge-creation`
@@ -22727,7 +23297,9 @@ only.
```
GET /api/forged → recent agent-bought props (status done)
-GET /api/forged?category=crate → filter by prop family (crate|barrel|furniture|terrain)
+GET /api/forged?category=container → filter by prop family (club-decor|ar-object|
+ diorama-set|avatar-item|vehicle|container|
+ furniture|terrain)
GET /api/forged?status=all → include queued/failed rows (audit view)
GET /api/forged?limit=60 → page size (default 30, max 100)
```
@@ -22783,7 +23355,7 @@ the Avatar Studio re-skin idea (`src/avatar-studio-colorpicker.js`,
preset live in the browser (see [Restyle Studio](https://three.ws/restyle)), ask
an AI for a restyle from a plain-language instruction, or fan one preset out into
N reproducible colorway variants. Free and hosted — rate-limited, not x402 — the
-same implementation the paid `restyle_material` [MCP tool](#sec-274) calls as
+same implementation the paid `restyle_material` [MCP tool](#sec-275) calls as
a thin client, so the free web page and the paid agent tool never drift.
Every mesh edit is **non-destructive**: geometry and UVs are never touched (only
@@ -23177,7 +23749,7 @@ sample rate, whether the lane is configured).
Read American Sign Language fingerspelling from a webcam. No API key, no account,
no payment: rate-limited per IP. This is the input half of the platform's signing
-loop (the output half, avatars that sign, is [docs/sign-language.md](#sec-376)).
+loop (the output half, avatars that sign, is [docs/sign-language.md](#sec-381)).
**Video never reaches the platform.** The caller extracts MediaPipe Holistic
landmarks in the browser and posts coordinates only. `src/sign-input.js` ships a
@@ -23683,8 +24255,10 @@ curl -s 'https://three.ws/api/v1/market/projects?limit=5&chain=solana'
| Status | Code | Meaning |
| ------ | --------------- | ------------------------------------------------------------------------ |
| `429` | `rate_limited` | Either the shared aixbt ceiling or the per-IP gateway budget is spent |
-| `503` | `not_configured` | `AIXBT_API_KEY` isn't set on this deployment — never a raw 500 |
-| `502` | `aixbt_upstream_error` | aixbt returned an unexpected error — retry shortly |
+| `429` | `aixbt_rate_limited` | aixbt throttled this deployment's key upstream. Retry shortly. |
+| `502` / `504` | `aixbt_upstream_error` | aixbt is erroring or unreachable. The upstream status is relayed. |
+| `503` | `not_configured` | `AIXBT_API_KEY` isn't set on this deployment, never a raw 500 |
+| `503` | `aixbt_unauthorized` | aixbt rejected this deployment's key (expired, revoked, or below the plan the read needs). A deployment fault, never the caller's: these routes take no client credential, so they never answer `401`. |
---
@@ -23928,7 +24502,7 @@ progress, the three.ws launch directory, and whale activity. Each endpoint is a
thin wrapper: search shares its engine with the site's command-palette search
(`/api/pump/search`); trending, curve, and whales share their engines with the
free Crypto Data API's pump.fun endpoints (`/api/crypto/trending`, `/bonding`,
-`/whales` — see [docs/crypto-api.md](#sec-166)); launches shares its query
+`/whales` — see [docs/crypto-api.md](#sec-169)); launches shares its query
with the [/launches](https://three.ws/launches) page. No fork of any upstream
logic lives here — every /api/v1/pump/\* route imports the same shared module
its sibling already uses.
@@ -23997,7 +24571,7 @@ curl -s 'https://three.ws/api/v1/pump/search?q=three.ws'
Momentum-ranked "what's hot right now" — fuses windowed volume, buy pressure, a
volume-spike signal, and price change across pump.fun, DexScreener, and
(best-effort) GMGN smart money into one 0–100 score. Same engine as
-[`GET /api/crypto/trending`](#sec-166)
+[`GET /api/crypto/trending`](#sec-169)
(`api/_lib/crypto-trending.js` `composeTrending`), capped slimmer here (25 vs
50) to keep this door fast.
@@ -24062,7 +24636,7 @@ curl -s 'https://three.ws/api/v1/pump/trending?window=1h&limit=10'
Bonding-curve / graduation status for one pump.fun mint — % to graduation, SOL
in the curve, tokens remaining, market cap, and whether it has already migrated
to an AMM (Raydium / PumpSwap). Same engine as
-[`GET /api/crypto/bonding`](#sec-166)
+[`GET /api/crypto/bonding`](#sec-169)
(`api/_lib/pump-bonding.js` `getBondingStatus`).
```
@@ -24193,7 +24767,7 @@ oracle that otherwise sits behind the paid `GET /api/x402/pump-agent-audit`
(`"mode":"whale_activity"`) — the invented "bullish/bearish signal +
confidence" the paid oracle scores is deliberately dropped here, and the same
scan engine backs the free
-[`GET /api/crypto/whales`](#sec-166)
+[`GET /api/crypto/whales`](#sec-169)
(`api/_lib/pump-whale-scan.js` `scanTokenWhales` / `scanMarketWhales`).
```
@@ -24254,7 +24828,7 @@ curl -s 'https://three.ws/api/v1/pump/whales?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfz
A trader's daily on-chain score attestation (`threews.tradescore.v1`), served as a
portable credential and a database-free verifier. Full guide:
-[docs/trader-passport.md](#sec-404).
+[docs/trader-passport.md](#sec-410).
### Read a passport
@@ -24409,42 +24983,53 @@ Requires auth. Permanently revokes the key.
GET /api/explore
```
-Paginated search over ERC-8004 registered agents. No auth required.
+Paginated directory across every source the platform crawls: ERC-8004 registered agents (EVM), three.ws Solana agents, external Solana agents (Metaplex Agent Registry + AgenC), and public 3D avatars. No auth required.
**Query parameters**
-| Parameter | Type | Description |
-| --------- | ------- | ----------------------------------------------- |
-| `q` | string | Full-text search query |
-| `only3d` | `1` | Filter to agents with 3D avatars only |
-| `chain` | integer | Filter by chain ID |
-| `cursor` | string | ISO 8601 timestamp cursor for keyset pagination |
-| `limit` | integer | Max results (default: 20) |
+| Parameter | Type | Description |
+| ---------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `q` | string | Name/description substring search |
+| `source` | string | `all` (default), `onchain`, `avatar`, `solana`, or `agents` (every on-chain agent, no avatars) |
+| `only3d` | `1` | Only rows with a 3D body (avatars are always 3D) |
+| `chain` | integer | Filter by EVM chain ID (implicitly excludes avatars and Solana) |
+| `category` | string | Avatar `model_category` filter, single or comma-separated (`avatar`, `accessory`, `item`, `scene`, `creature`, `vehicle`, `other`) |
+| `quality` | string | `high` (default, hides auto-named junk) or `all` |
+| `cursor` | string | ISO 8601 timestamp cursor for keyset pagination |
+| `limit` | integer | Max results, 1 to 250 (default: 24) |
**Response**
```json
{
- "agents": [
+ "items": [
{
- "id": "onchain_abc",
+ "kind": "onchain",
+ "chainId": 8453,
+ "agentId": 42,
"name": "Aria",
"description": "Product guide",
- "avatar_url": "https://three.ws/avatars/default.glb",
- "thumbnail_url": "https://three.ws/avatars/thumbs/default.png",
- "chain_id": 8453,
- "chain_agent_id": 42,
- "registered_at": "2025-01-15T10:00:00Z",
- "services": [],
- "explorer_url": "https://basescan.org/..."
+ "detailUrl": "/a/8453/42",
+ "viewerUrl": "/app#model=...",
+ "registeredAt": "2025-01-15T10:00:00Z",
+ "services": []
+ },
+ {
+ "kind": "avatar",
+ "avatarId": "13f259c7-7024-4d68-b1f0-dbbf52c06209",
+ "name": "Michelle",
+ "detailUrl": "/avatars/13f259c7-7024-4d68-b1f0-dbbf52c06209",
+ "viewerUrl": "/app#model=...",
+ "glbUrl": "https://three.ws/avatars/michelle.glb"
}
],
- "total": 142,
- "total_3d": 89,
- "cursor": "2025-01-10T10:00:00Z"
+ "nextCursor": "2025-01-10T10:00:00Z",
+ "totals": { "all": 142, "threeD": 89, "onchain": 40, "solana": 12, "solanaExternal": 4, "avatars": 86 }
}
```
+Every item carries a `detailUrl`: the canonical on-platform detail page for that entity (`/avatars/:id` for avatars, `/agents/:id` for three.ws agents, `/a/:chainId/:agentId` for ERC-8004 agents, `/discover/a/sol/:asset` for external Solana agents). Link to it rather than assembling paths from ids.
+
---
### Featured agents
@@ -24457,21 +25042,23 @@ Public directory of ERC-8004 agents with 3D avatars, for homepage and gallery us
**Query parameters**
-| Parameter | Type | Description |
-| --------- | ------- | ------------------------------------------------------------------ |
-| `net` | string | `mainnet`, `testnet`, or `all` (default: `all`) |
-| `sort` | string | `newest` or `oldest` |
-| `chain` | integer | Filter by chain ID |
-| `limit` | integer | Max results (default: 20) |
-| `cursor` | string | Keyset pagination cursor (`registered_at,chain_id,agent_id` tuple) |
+| Parameter | Type | Description |
+| --------- | ------- | --------------------------------------------------------------------------------- |
+| `net` | string | `mainnet`, `testnet`, or `all` (default: `mainnet`) |
+| `sort` | string | `newest` or `oldest` (default: `newest`) |
+| `chain` | integer | Comma-separated chain IDs. Overrides `net`; an unknown ID is a `validation_error`. |
+| `limit` | integer | Max results, 1 to 60 (default: 24). A fractional value is floored. |
+| `cursor` | string | Keyset cursor from the previous page's `next_cursor`. Opaque, pass it back verbatim. |
+
+**Response:** `{ agents, total, next_cursor }`, each agent shaped as in `/api/explore`. `total` is the count for the current filter, not the page. `next_cursor` is `null` on the last page.
-**Response:** Same shape as `/api/explore`. Cursor encodes the full keyset tuple for stable pagination under concurrent inserts.
+The cursor encodes the full keyset tuple (registration timestamp, chain ID, agent ID) so pagination stays stable while the crawler inserts. Two properties matter if you are reproducing it: the timestamp is carried at Postgres' own microsecond precision (re-rendering it through a millisecond clock repeats or skips the boundary row), and an agent whose registry event carried no timestamp sorts under `-infinity`, at the end of `newest` and the start of `oldest`, rather than dropping out of the walk. A cursor that does not decode is a `400` `validation_error`, never a silent reset to page one.
---
## Social & Community API
-The endpoints behind the platform's social layer: the activity feed, the follow graph, notifications, the unified leaderboard, creator portfolios, and cross-entity search. Overview and how the pieces interconnect: [The social layer](#sec-385).
+The endpoints behind the platform's social layer: the activity feed, the follow graph, notifications, the unified leaderboard, creator portfolios, and cross-entity search. Overview and how the pieces interconnect: [The social layer](#sec-391).
### Activity feed
@@ -24510,7 +25097,7 @@ Reverse-chronological creation events (avatars, agents, coins, forged models, sa
Items of `kind: "follow"` also carry a `target` shaped like `actor`. `actor.username` is `null` for creations made while signed out.
-Not the same endpoint as `GET /api/feed`, the public Money Pulse ticker ([Money Feed](#sec-284)).
+Not the same endpoint as `GET /api/feed`, the public Money Pulse ticker ([Money Feed](#sec-285)).
---
@@ -24594,6 +25181,8 @@ DELETE /api/users/:username/follow
The social-graph edge for a public profile. GET is viewer-specific (never cached). POST and DELETE are idempotent, require a session + CSRF token, block self-follows (400), and return the same envelope as GET so one round-trip updates both the button and the counts. A genuinely new edge notifies the followed user exactly once.
+`followers_count` and `following_count` count only reachable profiles: live accounts that have claimed a username. That is exactly the set `GET /api/users/:username/follows` lists, so the number and the list always agree. The same rule applies to the `stats.followers` / `stats.following` fields on `GET /api/users/:username`.
+
**Response (all three methods)**
```json
@@ -24621,7 +25210,7 @@ GET /api/users/:username/follows
| `limit` | integer | 1..100 |
| `offset` | integer | Pagination offset |
-Each row carries `is_following` (does the signed-in viewer follow that row's user) for follow-back buttons.
+Each row carries `is_following` (does the signed-in viewer follow that row's user) for follow-back buttons. Accounts without a username are excluded in the query, not after paging, so `limit`, `offset`, and `has_more` count the same rows you receive.
---
@@ -24632,7 +25221,17 @@ GET /api/users/:username
GET /api/users/:username/creations
```
-Public profile and the cursor-paginated portfolio of forged models and saved worlds attributed to that creator. Powers `/u/:username`.
+Public profile and the cursor-paginated portfolio of forged models, saved worlds, and restyled models attributed to that creator. Powers `/u/:username`.
+
+**Query parameters (`/creations`)**
+
+| Parameter | Type | Description |
+| --------- | ------- | -------------------------------------------------------------------- |
+| `type` | string | `model`, `world`, or `restyle`. Omit for all three. Anything else 400s |
+| `before` | string | ISO 8601 cursor, echoed back as `next`. A non-date value 400s |
+| `limit` | integer | 1..48, default 24 |
+
+**Response:** `{ items: [{ id, type, title, prompt, thumbnailUrl, category, viewerUrl, createdAt }], next }`. `next` is the cursor to pass as `before` for the following page, or `null` on the last page.
---
@@ -24817,12 +25416,14 @@ breakdown, and a 30-day daily series. Backed by
GET /api/v1/agents/:caip
```
-Public, gateway-cached resolver for an ERC-8004 agent. `:caip` is a URL-encoded CAIP-style ref — `eip155:<chainId>:<registryAddress>/<tokenId>` — so consumers (the badge web component, indexers, third-party sites) don't have to do RPC + IPFS + sha256 verification themselves. No auth required.
+Public, gateway-cached resolver for an ERC-8004 agent. `:caip` is a CAIP-style ref (`eip155:<chainId>:<registryAddress>/<tokenId>`), so consumers (the badge web component, indexers, third-party sites) don't have to do RPC + IPFS + sha256 verification themselves. No auth required.
+
+Pass the ref with its `/` as a real path separator. Percent-encoding the colons is fine; percent-encoding the slash is not, because the API dispatcher rejects any path segment that decodes to contain a separator (that is the guard which stops `%2f..%2f..` traversal), so a `%2F` ref 404s before it reaches the resolver.
**Example**
```
-GET /api/v1/agents/eip155%3A8453%3A0x8004A169...%2F1
+GET /api/v1/agents/eip155:8453:0x8004A169.../1
```
**Response:** `{ ref, chainId, agentId, registry, owner, tokenURI, card, verified: { modelSha256, cardSchema }, fetchedAt }` — `card` is the resolved agent card JSON.
@@ -24879,7 +25480,7 @@ GET answers `405` with `allow: POST, DELETE`.
`render_avatar` enforces the agent's embed policy (allowed origins, allowed surfaces). Model URLs must be HTTPS — SSRF protections block private IP ranges.
-This table is the core subset. The server registers many more tools (minting, gated embeds, memory, oracle and pump.fun intel, trader analytics, crypto data). Call `tools/list`, or see the [MCP documentation](#sec-276) and the [MCP Tools Catalog](#sec-274).
+This table is the core subset. The server registers many more tools (minting, gated embeds, memory, oracle and pump.fun intel, trader analytics, crypto data). Call `tools/list`, or see the [MCP documentation](#sec-277) and the [MCP Tools Catalog](#sec-275).
**Example JSON-RPC request**
@@ -24992,7 +25593,7 @@ Both header names are read case-insensitively and both receipt names are emitted
| `POST /api/mcp-3d` | MCP (Streamable HTTP) | Base + X Layer (+ Solana when configured) |
| `POST /api/okx/3d/<service>` | A2MCP (decomposed 3D studio) | X Layer first, then Solana/Base |
-The full seller-side wire contract — challenge fields, verify→work→settle order, the `PAYMENT-SIGNATURE` payload shape, and the settlement receipt — is pinned in [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md). The per-service catalog and runnable curls are in [`docs/okx-marketplace.md`](#sec-299).
+The full seller-side wire contract — challenge fields, verify→work→settle order, the `PAYMENT-SIGNATURE` payload shape, and the settlement receipt — is pinned in [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md). The per-service catalog and runnable curls are in [`docs/okx-marketplace.md`](#sec-302).
---
@@ -25014,7 +25615,7 @@ The buyer-side counterpart to the x402 endpoints above. Everything so far assume
You fund a budget from your [credits](payment-sessions.md#prepaid-credits), set the policy, and receive a bearer token. The agent presents that token to `/api/pay/execute`; the platform's own wallet signs the on-chain transfer. A stolen token buys at most the remaining budget, only at hosts you approved, only until the session expires.
-Conceptual guide: [Payment sessions](#sec-316). Step-by-step walkthrough: [Give an agent a spending envelope](#sec-415). Enforcement source: [`api/_lib/pay/spend-governor.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/pay/spend-governor.js).
+Conceptual guide: [Payment sessions](#sec-321). Step-by-step walkthrough: [Give an agent a spending envelope](#sec-421). Enforcement source: [`api/_lib/pay/spend-governor.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/pay/spend-governor.js).
### Authentication
@@ -25374,7 +25975,7 @@ Public, unauthenticated, CORS-open proxies over CoinGecko (plus a news
aggregator) that power the [/coins](https://three.ws/coins) markets index and
the `/coin/:id` detail pages. Responses are CDN-cached (30–300 s), so polling
faster than the cache window returns the same payload. See
-[docs/coin-pages.md](#sec-143) for the product surface.
+[docs/coin-pages.md](#sec-145) for the product surface.
### Coin detail
@@ -25894,7 +26495,7 @@ fetched_at }`.
`paragraphs[]` is a bounded lead excerpt, not the article body: capped to 2
paragraphs / 400 characters by `excerptParagraphs()` in
[api/_lib/news-rights.js](../api/_lib/news-rights.js), the single choke point
-every response passes through (see [docs/news-rights.md](#sec-291)).
+every response passes through (see [docs/news-rights.md](#sec-292)).
`excerpt_truncated` is `true` whenever the source ran longer than the quoted
excerpt; `full_text_url` is where to send the reader for the rest. This is a
hard limit for every publisher, not a per-source policy — a story removed at a
@@ -26236,8 +26837,9 @@ returns `vertexaisearch.cloud.google.com` for every result.
GCP project configured (local dev without credentials). A designed "not
available here" state, not an error.
- `400 missing_query` — `q` was absent or empty.
-- `502` — the upstream grounded call failed (auth, quota, safety block, or
- timeout). Retryable.
+- `502 upstream_error`: the upstream grounded call failed (auth, quota, safety
+ block, or timeout). Retryable. Body is the standard error shape,
+ `{ "error": "upstream_error", "error_description": "search upstream failed, retry shortly" }`.
Results are edge-cached for 60 seconds (`stale-while-revalidate` 300).
@@ -26471,6 +27073,7 @@ curl 'https://three.ws/api/animations/signatures?similar=wave&limit=5'
```
GET /api/play/population
GET /api/play/population?coin=<mint-or-contract>
+GET /api/play/population?by=coin
```
How many people are standing in the `/play` worlds right now. No auth, CORS open, cached 5 seconds at the edge.
@@ -26479,6 +27082,8 @@ How many people are standing in the `/play` worlds right now. No auth, CORS open
`coin` narrows the count to one community's worlds (a Solana mint or an EVM contract address). Anything that is not a well-formed address is ignored rather than forwarded, and the response reports the filter that was actually applied.
+`by=coin` adds `byCoin`, a mint to headcount map covering every live world, so a page listing many communities gets all of their counts from one request instead of one request per card (this is what the `/play` lobby paints on its cards). Keys are re-validated as addresses before they are republished, and worlds with nobody in them are left out. `byCoin` is **absent**, not empty, when the multiplayer server is older than this parameter: an absent map means "unknown" and an empty map means "measured, nobody anywhere", and a caller must not render the first as zeroes.
+
**Response**
```json
@@ -26490,6 +27095,18 @@ How many people are standing in the `/play` worlds right now. No auth, CORS open
}
```
+With `by=coin`:
+
+```json
+{
+ "ok": true,
+ "coin": null,
+ "players": 7,
+ "rooms": 3,
+ "byCoin": { "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump": 5 }
+}
+```
+
When the multiplayer server is unreachable the endpoint still answers `200`, with the count omitted:
```json
@@ -26514,7 +27131,7 @@ POST /api/wars?action=leave take a community out of the queue
POST /api/wars?action=report game-server only, HMAC-signed battle result
```
-Coin Wars is community-vs-community combat: two coin communities meet in one arena, the side that reaches the kill cap first wins, and an Elo ladder is recomputed from the battle ledger. This endpoint is what the war portal in every `/play` world reads and what the arena at [`/play/war`](https://three.ws/play/war) queues through. The reads are open and CORS-enabled; the report write is signed. Full subsystem doc: [Coin Wars](#sec-144).
+Coin Wars is community-vs-community combat: two coin communities meet in one arena, the side that reaches the kill cap first wins, and an Elo ladder is recomputed from the battle ledger. This endpoint is what the war portal in every `/play` world reads and what the arena at [`/play/war`](https://three.ws/play/war) queues through. The reads are open and CORS-enabled; the report write is signed. Full subsystem doc: [Coin Wars](#sec-146).
Standings are **not** computed here. `multiplayer/src/war-standings.js` folds the `clash_battles` ledger, and it is the same module the arena's league uses, so a rating in the world and a rating in the API can never disagree.
@@ -26747,6 +27364,119 @@ page strip (on-chain agents, attestations, forge models).
---
+## Unstoppable Agent API
+
+The [Unstoppable Agent](/unstoppable) is a self-funding autonomous agent: it
+owns a USDC treasury, earns by serving paid status checks over x402, spends on
+its own thinking within a budget, tracks its runway, and writes a strategic
+reflection once a day. Two endpoints expose the same state at two fidelities.
+
+### Public snapshot (free)
+
+```
+GET /api/agents/unstoppable-public
+```
+
+No auth, no payment, IP rate-limited, CORS open. Edge-cached for 300 seconds
+(one agent tick) and trimmed to the 8 most recent activity rows. This is the
+read the `/unstoppable` dashboard renders, so every visitor sees the agent's
+real numbers without a wallet.
+
+**Response**
+
+```json
+{
+ "available": true,
+ "live": false,
+ "as_of": "2026-08-15T19:20:39.822Z",
+ "refresh_seconds": 300,
+ "status": "running",
+ "treasury": {
+ "balance_usdc": "8.930000",
+ "balance_usdc_atomics": 8930000,
+ "runway_days": 9999,
+ "lifetime_earned_usdc": "8.930000",
+ "lifetime_spent_usdc": "0.000000"
+ },
+ "activity_24h": {
+ "earnings_usdc": "0.000000",
+ "costs_usdc": "0.000000",
+ "net_usdc": "0.000000"
+ },
+ "recent_activity": [
+ {
+ "action_type": "earn",
+ "description": "Revenue from status_check: $0.010000 USDC",
+ "cost_usdc": "0.000000",
+ "revenue_usdc": "0.010000",
+ "created_at": "2026-08-15T19:12:11.402Z"
+ }
+ ],
+ "latest_reflection": {
+ "date": "2026-08-15",
+ "summary": "Revenue covered thinking costs today.",
+ "strategy_notes": "Continue status-check monetization."
+ },
+ "live_endpoint": "/api/agents/unstoppable-status",
+ "live_price_usdc": "0.010000",
+ "live_price_atomics": "10000",
+ "agent_info": { "name": "Unstoppable", "purpose": "Self-sustaining autonomous agent on three.ws", "service": "Paid status checks via x402" }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `live` | Always `false` here. The paid endpoint returns the real-time reading. |
+| `as_of` | When this snapshot was generated. It can be up to `refresh_seconds` old. |
+| `status` | `running`, `conservation`, or `halted`, derived from the treasury mode |
+| `treasury.runway_days` | Balance divided by the last-24h burn. `9999` means no burn was measured, not a 27-year runway. |
+| `live_price_usdc` | What the real-time reading costs over x402, so a client can quote it without probing for a 402 |
+
+**When the database is unreachable**
+
+```json
+{ "available": false, "reason": "db_unavailable", "live": false, "live_endpoint": "/api/agents/unstoppable-status" }
+```
+
+Still `200`, cached 15 seconds. Check `available` before reading the treasury:
+a failed read must never render as a broke agent, which is exactly what a
+zeroed balance would look like.
+
+```bash
+curl -s https://three.ws/api/agents/unstoppable-public | jq 'select(.available) | {status, balance: .treasury.balance_usdc}'
+```
+
+### Live reading (paid, $0.01 USDC)
+
+```
+GET /api/agents/unstoppable-status
+```
+
+x402-paid, Bazaar-discoverable, settles in USDC on Base or Solana. Same shape
+as the snapshot plus `activity_24h.action_count`, and it carries 20 activity
+rows instead of 8. Two differences matter: the reading is real-time rather than
+tick-cached, and a settled payment calls `recordRevenue()`, so this is the only
+read that extends the runway it reports. Without an `X-PAYMENT` header it
+returns the standard `402` quote.
+
+```bash
+# First call returns 402 with the payment requirements
+curl -s https://three.ws/api/agents/unstoppable-status
+
+# Retry with the payment header for the live reading
+curl -s https://three.ws/api/agents/unstoppable-status \
+ -H "X-Payment: <your-x402-payment-header>"
+```
+
+A caller with the `x402:bypass` scope is served free by the access-control hook
+and is deliberately NOT credited as revenue: reporting money the agent never
+earned would inflate the runway this endpoint exists to report honestly.
+
+See [agents/unstoppable/README.md](https://github.com/nirholas/three.ws/blob/main/agents/unstoppable/README.md)
+for the tick lifecycle and the treasury rules.
+
+---
+
## Referrals API
Every three.ws account carries a referral code. A share link is any page URL
@@ -26797,8 +27527,12 @@ Privacy and counting rules, both deliberate:
- An unknown code still records a visit with no referrer attached, so traffic on
a dead or mistyped link stays visible instead of vanishing.
-A malformed or missing code returns `400 invalid_code`. The endpoint is rate
-limited per IP; over the limit returns `429` with a `retry-after` header.
+A malformed or missing code returns `400 invalid_code`. A body the endpoint
+cannot read at all is reported as its own failure rather than blamed on the
+code: a request without `content-type: application/json` returns
+`415 unsupported_media_type`, an unparseable body returns `400 bad_request`, and
+an oversized one returns `413 payload_too_large`. The endpoint is rate limited
+per IP; over the limit returns `429` with a `retry-after` header.
---
@@ -26870,6 +27604,148 @@ curl -s -b cookies.txt 'https://three.ws/api/users/referrals?funnel_days=7' | jq
---
+## Transaction API: build and explain
+
+Three endpoints the in-app wallet and the chat wallet tools
+([chat/src/tools.js](../chat/src/tools.js)) use to prepare a transaction for the
+user's wallet to sign, and to read one back in plain English. **The server never
+signs and never broadcasts**: it returns unsigned bytes, and the wallet owns the
+approval.
+
+### Build a Solana transfer
+
+```
+POST /api/tx/solana/build-transfer
+```
+
+Session cookie required (`401 unauthorized` without one). Builds an unsigned legacy
+transaction moving SOL or any SPL token from `sender` to `recipient`.
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `sender` | string | required | Base58 wallet address. Also the fee payer. |
+| `recipient` | string | required | Base58 wallet address. |
+| `amount` | number | required | UI amount (SOL, or whole tokens), > 0 and at most 1e12. Converted to base units with fixed-point string math, so no float drift. |
+| `token` | string | `SOL` | `SOL` for a native transfer, otherwise the SPL mint address. |
+| `memo` | string | none | Attached as an SPL Memo instruction. Max 512 bytes. |
+| `network` | string | `mainnet` | `mainnet` or `devnet`. |
+
+The mint's owning program is read from the chain, so **Token-2022 mints work**,
+including `$THREE` and every other pump.fun-era launch. The transfer instruction is
+`TransferChecked`, which Token-2022 mints carrying a transfer-fee extension require.
+The recipient's associated token account is created in the same transaction when it
+does not exist yet, paid for by the sender.
+
+```json
+{
+ "transaction": "AQAAAAAA...",
+ "network": "mainnet",
+ "blockhash": "7yfLFPfbbzAk52tx5BxfsDcfrneAoJfwEihVJtnkM9ph",
+ "lastValidBlockHeight": 417508552
+}
+```
+
+Deserialize `transaction` (base64), have the wallet sign it, then broadcast and
+confirm against `blockhash` / `lastValidBlockHeight`.
+
+Caller faults answer 4xx before anything is built, so a user is never asked to
+approve a transaction that can only fail:
+
+| Code | Status | When |
+|---|---|---|
+| `validation_error` | 400 | A field is missing or malformed (a non-base58 address, a non-positive amount, an oversized memo, an unknown network). `issues[]` names the field. |
+| `invalid_mint` | 400 | `token` is not on-chain, or is not an SPL mint. |
+| `invalid_owner` | 400 | `sender` or `recipient` is a program-derived address, which has no associated token account and no key to sign with. |
+| `insufficient_balance` | 400 | The sender holds less of the token than requested. |
+| `invalid_amount` | 400 | The amount rounds to zero at the mint's precision, or exceeds the lamport ceiling. |
+| `upstream_error` | 502 | Solana RPC would not answer. |
+
+```bash
+curl -s -X POST https://three.ws/api/tx/solana/build-transfer \
+ -H 'content-type: application/json' -b cookies.txt \
+ -d '{"sender":"<wallet>","recipient":"<wallet>","amount":0.1,"memo":"gm"}' | jq -r .blockhash
+```
+
+### Build a Solana swap
+
+```
+POST /api/tx/solana/build-swap
+```
+
+Session cookie required. Quotes and builds an unsigned Jupiter swap through the
+shared lite-api client ([api/_lib/token/jupiter.js](../api/_lib/token/jupiter.js)).
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `sender` | string | required | Base58 wallet address; the swap's `userPublicKey`. |
+| `inputMint` | string | required | Base58 mint to spend. Must differ from `outputMint`. |
+| `outputMint` | string | required | Base58 mint to receive. |
+| `amount` | number | required | UI amount of `inputMint`, > 0. Scaled by that mint's decimals. |
+| `slippageBps` | integer | `50` | 1 to 5000. |
+| `network` | string | `mainnet` | `mainnet` only. |
+
+```json
+{
+ "transaction": "AQAAAAAA...",
+ "network": "mainnet",
+ "inputAmount": 0.01,
+ "outputAmount": 123.456789,
+ "outputMint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
+ "priceImpactPct": "0.12"
+}
+```
+
+`transaction` is a base64 `VersionedTransaction`. `no_route` (422) means Jupiter
+found no route for the pair and size, `swap_failed` (422) that it quoted but could
+not build, `invalid_route` (400) that both mints are the same, and `upstream_error`
+(502) that Jupiter was unreachable.
+
+### Explain a transaction
+
+```
+POST /api/tx/explain
+```
+
+No auth; IP rate-limited. Reads a confirmed transaction on Solana or Ethereum
+mainnet and returns its transfers plus, when an LLM lane is configured, a one
+paragraph plain-English `summary`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `chain` | string | `solana` or `evm`. |
+| `sig` | string | Solana: a base58 signature that decodes to exactly 64 bytes. EVM: a `0x`-prefixed 32-byte tx hash. |
+
+Solana reads go to the Helius enhanced-transaction API and fall back to
+`getParsedTransaction` over the rotating RPC chain, reconstructing transfers from
+balance deltas. EVM reads walk a failover chain of Alchemy, any configured RPC, then
+keyless public nodes, and decode ERC-20 `Transfer` logs.
+
+```json
+{
+ "tokenTransfers": [],
+ "nativeTransfers": [{ "account": "<pubkey>", "amount": -5000 }],
+ "description": "",
+ "type": "",
+ "feePayer": "<pubkey>",
+ "source": "rpc-fallback",
+ "summary": "The account paid a 5,000 lamport fee ..."
+}
+```
+
+A finished explanation is cached for 24 hours per `chain:sig`, so re-explaining the
+same transaction costs nothing upstream. A malformed `chain` or `sig` is
+`400 bad_request` and never reaches a billed upstream; an unknown transaction is
+`404 not_found`; an RPC outage is `502 upstream_error`; exhausting the shared
+enhanced-API cost ceiling is `429`.
+
+```bash
+curl -s -X POST https://three.ws/api/tx/explain \
+ -H 'content-type: application/json' \
+ -d '{"chain":"solana","sig":"<base58 signature>"}' | jq -r .summary
+```
+
+---
+
## Solana Actions API (Blinks)
three.ws publishes a Solana Action so "Claim Your 3D Avatar" unfurls as a Blink
@@ -27367,6 +28243,312 @@ partial answer is still a partial answer.
---
+## Subscriptions API
+
+Recurring creator subscriptions. A creator publishes one or more **plans**
+(tiers); a subscriber joins one either through the x402 renewal-intent path
+(`POST /api/subscriptions`) or the Solana USDC checkout
+(`/api/subscriptions/subscribe` then `/api/subscriptions/verify`).
+
+All ids are UUIDs. A malformed id answers `400 validation_error`, never a `5xx`.
+Session-cookie mutations require an `X-CSRF-Token` header (see
+[Authentication](#authentication)); bearer-token callers are exempt.
+
+### List plans
+
+```
+GET /api/subscriptions/plans?creator_id=<uuid>
+GET /api/subscriptions/plans?agent_id=<uuid>
+```
+
+Public. Exactly one of `creator_id` or `agent_id` is required. Only active plans
+are returned; the plan's own creator may add `include_inactive=1` to also receive
+their drafts.
+
+```json
+{
+ "plans": [
+ {
+ "id": "735977d9-289d-4517-8ac4-68e97c649de8",
+ "creator_id": "f23703c0-9d75-4e60-9a4c-349da5d7a2f2",
+ "agent_id": null,
+ "name": "Supporter",
+ "price_usd": "9.99",
+ "interval": "monthly",
+ "perks": ["priority support"],
+ "included_skills": [],
+ "active": true,
+ "created_at": "2026-08-16T06:16:24.604Z"
+ }
+ ]
+}
+```
+
+**Errors:** `400` (`validation_error`: neither id given, or a non-UUID),
+`429` (`rate_limited`).
+
+---
+
+### Get one plan
+
+```
+GET /api/subscriptions/plans/:id
+```
+
+Public for an active plan. A deactivated plan (draft) is served only to its
+creator; everyone else gets `404`, so a draft's existence never leaks.
+
+**Response:** `{ "plan": { … } }`, same shape as a list entry.
+
+**Errors:** `400` (`validation_error`), `404` (`not_found`), `429`.
+
+---
+
+### Create a plan
+
+```
+POST /api/subscriptions/plans
+```
+
+Requires auth. A creator may hold at most 3 **active** plans; drafts
+(`active: false`) do not consume a slot.
+
+**Request body**
+
+```json
+{
+ "agent_id": "717e68f1-e0c2-41ee-8ff7-6801a83206c9",
+ "name": "Supporter",
+ "price_usd": 9.99,
+ "interval": "monthly",
+ "perks": ["priority support"],
+ "included_skills": [],
+ "active": true
+}
+```
+
+`name` is 2 to 80 characters, `price_usd` is 0.99 to 999, `interval` is
+`weekly` or `monthly` (default `monthly`), `perks` is up to 10 strings,
+`included_skills` up to 50. `agent_id` is optional and must be an agent you own.
+
+**Response** (`201`): `{ "plan": { … } }`
+
+**Errors:** `400` (`validation_error`), `401` (`unauthorized`), `403`
+(`csrf_missing` / `csrf_invalid`, or `forbidden` when `agent_id` is not yours),
+`409` (`conflict`: the 3-active-plan cap), `429`.
+
+---
+
+### Update a plan
+
+```
+PATCH /api/subscriptions/plans/:id
+PUT /api/subscriptions/plans/:id
+```
+
+Requires auth, creator only. Both verbs behave identically: the body is a
+partial update, and any field left out is untouched. `PUT` is accepted because
+the dashboard plan editor saves with it.
+
+**Request body:** any subset of `name`, `price_usd`, `interval`, `perks`,
+`included_skills`, `active`.
+
+**Response:** `{ "plan": { … } }`
+
+**Errors:** `400` (`validation_error`, including an empty body: "nothing to
+update"), `401`, `403`, `404` (`not_found`: unknown plan, or not yours), `409`
+(reactivating past the 3-active cap).
+
+---
+
+### Deactivate a plan
+
+```
+DELETE /api/subscriptions/plans/:id
+```
+
+Requires auth, creator only. A soft delete: the row stays and `active` flips to
+`false`, so existing subscribers keep their record and the plan can be
+reactivated with `PATCH { "active": true }`.
+
+**Response:** `{ "ok": true }`
+
+**Errors:** `400`, `401`, `403`, `404`.
+
+---
+
+### Subscribe (x402 renewal intent)
+
+```
+POST /api/subscriptions
+```
+
+Requires auth. Creates or reactivates the subscription immediately and then
+raises a payable intent for the first period. Payment is request-based (x402):
+the server never pulls funds, it hands back what the subscriber owes.
+
+**Request body**
+
+```json
+{ "plan_id": "735977d9-289d-4517-8ac4-68e97c649de8", "wallet_address": "<solana pubkey>" }
+```
+
+**Response** (`201`)
+
+```json
+{
+ "subscription": {
+ "id": "7c8e0051-0279-484a-b7d5-a19d821ade61",
+ "plan_id": "735977d9-289d-4517-8ac4-68e97c649de8",
+ "status": "active",
+ "current_period_end": "2026-09-15T06:16:50.257Z",
+ "payment_method": "x402"
+ },
+ "payment": { "pending": true, "paymentId": "…", "payUrl": "https://three.ws/pay/…" }
+}
+```
+
+`payment` reports the first charge attempt and is informational: a plan whose
+creator has no payout wallet answers `{ "success": false, "error":
+"creator_payout_wallet_missing" }` while the subscription itself is still
+created.
+
+**Errors:** `400`, `401`, `403`, `404` (`not_found`: unknown plan), `409`
+(`conflict`: plan deactivated, your own plan, or already subscribed), `429`.
+
+---
+
+### My subscriptions
+
+```
+GET /api/subscriptions/mine
+```
+
+Requires auth. Every subscription the caller holds, newest first, joined with
+the plan name/price/interval and the creator's display name.
+
+```json
+{ "subscriptions": [ { "id": "…", "status": "active", "plan_name": "Supporter", "price_usd": "9.99", "creator_name": "…" } ] }
+```
+
+---
+
+### Subscription detail
+
+```
+GET /api/subscriptions/:id
+```
+
+Requires auth. Readable by the subscriber **or** the plan's creator; anyone else
+gets `404`.
+
+---
+
+### Cancel a subscription
+
+```
+DELETE /api/subscriptions/:id
+```
+
+Requires auth, subscriber only. Sets `status = 'cancelled'` and stamps
+`cancelled_at`; the record is kept so the period already paid for stays
+auditable. Re-subscribing to the same plan reactivates this row.
+
+**Response:** `{ "ok": true, "subscription": { "id": "…", "status": "cancelled" } }`
+
+---
+
+### Solana USDC checkout: quote
+
+```
+POST /api/subscriptions/subscribe
+```
+
+Requires auth. Quotes the exact USDC split for one period, persists a pending
+checkout with a Solana-Pay reference, and returns a base64
+`VersionedTransaction` for the buyer's wallet to sign and broadcast. The
+platform pre-signs as fee payer when a payer keypair is configured, so the
+subscriber needs no SOL.
+
+**Request body**
+
+```json
+{ "tierId": "735977d9-289d-4517-8ac4-68e97c649de8", "buyerPublicKey": "<solana pubkey>" }
+```
+
+**Response** (`200`)
+
+```json
+{
+ "data": {
+ "transaction": "<base64 VersionedTransaction>",
+ "reference": "7qhfZb3yGi93qw3gp7KhbEwbmiXCQYdS5w3iCgG8azYs",
+ "recipient": "<creator payout address>",
+ "amount": "9990000",
+ "creator_amount": "9990000",
+ "currency_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+ "mint_decimals": 6,
+ "gasless": false,
+ "label": "Subscribe: Supporter",
+ "message": "Subscribe to 'Supporter' (monthly)",
+ "tier": { "id": "…", "name": "Supporter", "price_usd": 9.99, "interval": "monthly" }
+ }
+}
+```
+
+Amounts are USDC atomic units (6 decimals). When a platform fee applies, a
+`fee` block carries its recipient, amount and bps, and `creator_amount` is the
+remainder. Calling twice inside the 30-minute window reuses the same pending
+checkout rather than minting a second one.
+
+**Errors:** `400` (`validation_error`), `401`, `403`, `404` (`not_found`),
+`409` (`conflict`: tier inactive or your own; `already_subscribed`), `412`
+(`creator_wallet_missing`), `429`.
+
+---
+
+### Solana USDC checkout: verify
+
+```
+POST /api/subscriptions/verify
+```
+
+Requires auth. Validates the broadcast transaction against the **persisted**
+quote (never the client's numbers) and, on success, activates the subscription,
+writes the first-period payment row, and opens the skill-access gate.
+
+**Request body**
+
+```json
+{ "tierId": "735977d9-289d-4517-8ac4-68e97c649de8", "transactionSignature": "<base58 signature>" }
+```
+
+`transactionSignature` is optional: without it the chain is scanned by the
+checkout's reference key.
+
+**Response** (`200`)
+
+```json
+{
+ "data": {
+ "success": true,
+ "status": "active",
+ "subscription": { "id": "…", "current_period_end": "2026-09-15T06:16:50.257Z" },
+ "tx_signature": "…"
+ }
+}
+```
+
+While the transaction is not yet visible on chain the response is
+`200 { "data": { "status": "pending" } }`; poll until it settles. Verifying an
+already-confirmed checkout is idempotent and returns the live subscription.
+
+**Errors:** `400`, `401`, `403`, `404` (`no_pending_checkout`), `409`
+(`checkout_closed`, or `transfer_mismatch` when the on-chain transfer does not
+match the quote), `410` (`checkout_expired`), `429`.
+
+---
+
## Pagination
Paginated list endpoints use `limit`/`offset` query parameters unless noted otherwise (each endpoint's own parameter table is authoritative; some small per-user lists, like `/api/agents` and `/api/widgets`, return everything with no pagination).
@@ -27375,7 +28557,7 @@ Paginated list endpoints use `limit`/`offset` query parameters unless noted othe
GET /api/v1/pump/launches?limit=24&offset=24
```
-`/api/explore` and `/api/showcase` use keyset (cursor-based) pagination for stability: pass the returned `cursor` value as the `cursor` query parameter on the next request. `/api/agent-actions` and `/api/users/me/feed` are cursor-based too (`cursor` / `before` timestamps).
+`/api/explore` and `/api/showcase` use keyset (cursor-based) pagination for stability: pass the value the previous page returned (`cursor` on explore, `next_cursor` on showcase) as the `cursor` query parameter on the next request. `/api/agent-actions` and `/api/users/me/feed` are cursor-based too (`cursor` / `before` timestamps).
---
@@ -27400,7 +28582,7 @@ Endpoint-specific codes (e.g. `quota_exceeded`, `invalid_avatar`, `no_client_id`
## SDK
-For building on the platform from JavaScript, the official npm package is [`@three-ws/sdk`](https://www.npmjs.com/package/@three-ws/sdk). It is not a thin wrapper over every REST route above; it ships the higher-level building blocks: `AgentKit` (chat panel + ERC-8004 registration + `.well-known` manifest generation), `AgentClient` (x402 agent-to-agent paid skill calls), `PermissionsClient` (ERC-7710 delegations), and the Solana identity/attestation helpers. Full docs: [SDK & Library](#sec-369).
+For building on the platform from JavaScript, the official npm package is [`@three-ws/sdk`](https://www.npmjs.com/package/@three-ws/sdk). It is not a thin wrapper over every REST route above; it ships the higher-level building blocks: `AgentKit` (chat panel + ERC-8004 registration + `.well-known` manifest generation), `AgentClient` (x402 agent-to-agent paid skill calls), `PermissionsClient` (ERC-7710 delegations), and the Solana identity/attestation helpers. Full docs: [SDK & Library](#sec-374).
For the endpoints on this page, call them directly with `fetch`/`curl` and a Bearer API key:
@@ -27756,7 +28938,7 @@ Solscan-linked "x402" provenance badge. Inline-done lanes publish immediately;
async lanes are completed server-side by `api/cron/forge-finalize`, so the
artifact lands even if you never poll. Recording happens after your response is
sent and never affects your result. See
-[x402 endpoints](#sec-514) and
+[x402 endpoints](#sec-539) and
[the autonomous economy](#sec-105).
Treat prompts as public. If you need a private lane, use the account-scoped
@@ -27802,13 +28984,13 @@ const glb = Buffer.from(await (await fetch(glbUrl)).arrayBuffer());
- [3D API](#sec-001): the free draft lane, inspection, validation, and the
full Forge Pro walkthrough.
-- [Forge pipeline](#sec-223): how the lanes, tiers, and failovers fit
+- [Forge pipeline](#sec-224): how the lanes, tiers, and failovers fit
together internally.
-- [3D Studio MCP server](#sec-270): the same generation as
+- [3D Studio MCP server](#sec-271): the same generation as
`text_to_3d` / `image_to_3d` tools for in-conversation use, priced from the
same tier table. This REST endpoint is the pay-per-call surface for autonomous
agents.
-- [x402 endpoints](#sec-514): every paid endpoint on the platform.
+- [x402 endpoints](#sec-539): every paid endpoint on the platform.
---
@@ -27821,7 +29003,7 @@ const glb = Buffer.from(await (await fetch(glbUrl)).arrayBuffer());
AR Studio turns your camera view into an infinite canvas. Place as many 3D models and avatars as you like into the room around you, drawn from your own forges, the community gallery, a pasted GLB link, or brand-new ones forged from a text prompt without leaving the scene. It scales from full WebXR immersive AR down to camera passthrough down to a desktop 3D preview, and it can go multiplayer: open a shared room and everyone in it builds the same scene live. Share an arrangement with a link, or hand it to your phone with a QR code.
Page: [/ar/studio](https://three.ws/ar/studio)
-API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your and community models). Multiplayer runs on a Colyseus room, `studio_world`.
+API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your and community models) · `GET /api/objects/library` (the CC0 prop library). Multiplayer runs on a Colyseus room, `studio_world`.
## Why it exists
@@ -27835,14 +29017,15 @@ The page ([`pages/ar-studio.html`](../pages/ar-studio.html)) only imports [`src/
### Model sources
-`addModel({ src, title })` normalizes the URL (https or site-relative only), enforces a 20-model cap, clones the loaded template (using SkeletonUtils for skinned rigs), and drops it on the floor in front of the camera. The "Add models" tray has four tabs:
+`addModel({ src, title })` normalizes the URL (https or site-relative only), enforces a 20-model cap, clones the loaded template (using SkeletonUtils for skinned rigs), and drops it on the floor in front of the camera. The "Add models" tray has five tabs:
- **Recent forges**: read from local storage (`twx_ar_forge_recent`), shared with `/ar` so one forge history opens in two doors.
- **Yours**: `GET /api/forge-gallery?limit=24` with an `x-forge-client` header (your anonymous browser id).
- **Community**: `GET /api/forge-gallery?scope=community&limit=24`.
+- **Objects**: `GET /api/objects/library`, the CC0 prop library behind [/objects](https://three.ws/objects). The whole manifest is fetched once, so the tab's search box filters name and category client-side with no further requests, and renders matches 60 at a time.
- **GLB link**: paste any https `.glb`: a forge result, a viewer share link's `src`, or your own hosting.
-A fifth source is the **in-view forge**: the dock form calls `POST /api/forge` with `{ prompt, backend: 'nvidia' }` (the free NVIDIA NIM / TRELLIS lane), polls `GET /api/forge?job=<id>` until the GLB is ready, remembers it, and drops it into the scene. A sixth is deep links: repeatable `?src=` (paired with `?title=`) and `?forge=<prompt>` boot content on open.
+A sixth source is the **in-view forge**: the dock form calls `POST /api/forge` with `{ prompt, backend: 'nvidia' }` (the free NVIDIA NIM / TRELLIS lane), polls `GET /api/forge?job=<id>` until the GLB is ready, remembers it, and drops it into the scene. A seventh is deep links: repeatable `?src=` (paired with `?title=`) and `?forge=<prompt>` boot content on open.
### Device-capability ladder
@@ -27860,7 +29043,7 @@ Tap to select (tap empty space to deselect), drag to move a model you own along
### Shared live rooms
-Rooms run on the same Colyseus server as the other multiplayer surfaces, in a room named `studio_world` ([`multiplayer/src/rooms/StudioRoom.js`](../multiplayer/src/rooms/StudioRoom.js)), filtered by a 6-character room code. "Create a room" seeds the current scene as the starting point; joining via a `?room=CODE` link does not seed. Model transforms travel in a shared logical frame (east/north metres, yaw degrees) so every device maps them onto its own floor. Clients send `model:spawn`, `model:update` (throttled ~12 Hz), and `model:remove`; the server syncs a `StudioState` of models and viewers. Edits are owner-gated (you can only move your own models), models stay when their author leaves, and the server enforces per-room and per-owner caps plus a rate limit. A presence pill shows "N here, M models."
+Rooms run on the same Colyseus server as the other multiplayer surfaces, in a room named `studio_world` ([`multiplayer/src/rooms/StudioRoom.js`](../multiplayer/src/rooms/StudioRoom.js)), filtered by a 6-character room code. The page points at that server with `<meta name="studio-server" content="wss://…">` in [`pages/ar-studio.html`](../pages/ar-studio.html), the same way `/irl` and `/agora` declare theirs; [`src/ar/studio-net.js`](../src/ar/studio-net.js) reads it (falling back to the `irl-server` / `walk-server` tags, then `localhost:2567` in dev). Drop the tag and every room reports "offline" on the live site, because there is no host to infer from `three.ws` itself. The server's WebSocket upgrade is origin-gated, so a room joined from a local dev origin against the production server is refused with a 403 by design. "Create a room" seeds the current scene as the starting point; joining via a `?room=CODE` link does not seed. Model transforms travel in a shared logical frame (east/north metres, yaw degrees) so every device maps them onto its own floor. Clients send `model:spawn`, `model:update` (throttled ~12 Hz), and `model:remove`; the server syncs a `StudioState` of models and viewers. Edits are owner-gated (you can only move your own models), models stay when their author leaves, and the server enforces per-room and per-owner caps plus a rate limit. A presence pill shows "N here, M models."
### Share via `#s=` hash
@@ -27869,7 +29052,7 @@ The full arrangement (every model's source and transform) is serialized to JSON,
## Walkthrough
1. Open [/ar/studio](https://three.ws/ar/studio). On the empty card, choose Start camera, Browse models, or Forge one.
-2. Add models: open the tray and pick from Recent, Yours, or Community, or paste a GLB link. Or type a prompt in the dock ("a neon bonsai tree") and press Forge to generate one in place.
+2. Add models: open the tray and pick from Recent, Yours, Community, or the CC0 Objects library, or paste a GLB link. Or type a prompt in the dock ("a neon bonsai tree") and press Forge to generate one in place.
3. Arrange: drag to move, pinch to resize, twist to rotate. On a phone, tap Start camera to see them in your room; on a headset, tap the Immersive button for full AR.
4. Go multiplayer: create a room and share the code (or the link). Others join and see and place models live.
5. Share: use the QR button to continue on your phone, or copy the scene URL (it carries the arrangement in `#s=`).
@@ -27904,14 +29087,20 @@ You can also hand-build a share link: append `?src=<https glb url>&title=<name>`
- **Placement caps.** 20 models per local scene; the shared room enforces its own per-room and per-owner caps and a per-client rate limit.
- **Camera and motion.** Camera denial (`NotAllowedError`) shows "Camera permission is blocked... then try again"; no `getUserMedia` disables the camera button but keeps the 3D preview. Denied motion falls back to drag-look.
- **XR unsupported.** The Immersive button simply never appears; a failed XR start shows "Camera mode still works." Lost tracking prompts you to move to a brighter, more textured spot.
-- **Rooms offline.** With no multiplayer server configured (production default when unset), the studio stays single-player: "Shared rooms are offline right now, you can still build solo." Departing authors' models remain until the room empties.
+- **Rooms offline.** If the multiplayer server is unreachable or refuses the handshake, the studio drops back to single-player with "Shared rooms are offline right now, you can still build solo." and the room modal stays on its create/join panel. Departing authors' models remain until the room empties.
- **Persistence.** Your own placed models are saved to local storage (`twx_ar_studio_scene_v1`); `#s=` links replace the working scene. Photo capture composites the camera and WebGL layers to a PNG.
- **Forge failures.** `503`/unconfigured shows "The generator is offline"; `429` shows a busy message with a retry hint.
+## Running it locally
+
+`npm run dev` serves the page at `http://localhost:3000/ar/studio` and proxies `/api/*` to production. Every model URL in the tray points at the public R2 bucket, which answers `Access-Control-Allow-Origin: https://three.ws` and nothing else, so a raw bucket URL fails CORS from localhost and no model can be placed. The dev server rewrites those URLs to its own `/r2-proxy/*` path for the endpoints that carry them (`/api/avatars/*`, `/api/objects/*`, `/api/forge-gallery`, `/api/forge`), which is what makes the tray work off-production. If you add an endpoint that returns an R2 URL, add its prefix to `R2_URL_PREFIXES` in [`vite.config.js`](../vite.config.js) or that feature will work in production and be dead in dev.
+
+Append `?e2e=1` to expose `window.__arsDebug` (`count()`, `netStatus()`, `netIds()`, `remoteX()`), a read-only hook for driving the page from a browser test. It is absent without the flag.
+
## Related
- [AR and WebXR](#sec-099): the single-model "View in AR" system, `/ar` AR Forge, the `POST /api/forge` free lane in depth, the USDZ/Quick Look pipeline, and model-optimization limits.
-- [Selfie to Avatar](#sec-372) and [Avatar pipeline](#sec-112): where the models you place come from.
+- [Selfie to Avatar](#sec-377) and [Avatar pipeline](#sec-113): where the models you place come from.
- Pages: [/ar/studio](https://three.ws/ar/studio), [/ar](https://three.ws/ar), [/viewer](https://three.ws/viewer).
---
@@ -28381,6 +29570,36 @@ How this link ships through ChatGPT end to end (the app connector, the custom GP
---
+## Put this AR studio on your own site
+
+The multi-model studio at [/ar/studio](/ar/studio) is published as a standalone open-source
+package, so any site can embed the same thing:
+
+```html
+<script type="module" src="https://unpkg.com/3d-ar-studio/dist/ar-studio.min.js"></script>
+<ar-studio></ar-studio>
+```
+
+- npm: [`3d-ar-studio`](https://www.npmjs.com/package/3d-ar-studio)
+- Source and docs: [github.com/nirholas/3D-AR-Studio](https://github.com/nirholas/3D-AR-Studio)
+- Hosted demo: [nirholas.github.io/3D-AR-Studio](https://nirholas.github.io/3D-AR-Studio/)
+- MCP server: `npx 3d-ar-studio-mcp` (registry name `io.github.nirholas/3d-ar-studio`)
+
+With no configuration it pulls models from our CC0 object library and generates new ones
+through the free, keyless `/api/mcp-studio` connector documented above, so an embedder needs
+no key and no account. One option repoints it at their own catalogue:
+
+```js
+createArStudio('#stage', { assets: 'https://their.cdn/models.json' })
+```
+
+Those surfaces answer open CORS on purpose: `/cdn/<key>` (models and thumbnails),
+`/cdn/objects/library/manifest.json`, `/api/mcp-studio`, `/animations/manifest.json`,
+`/hdri/*.hdr`, and `GET /api/ar`. Changing any of them changes what every embedded studio in
+the wild can load.
+
+---
+
## See also
- [AR on the homepage](https://three.ws/#home-ar) — live demo with real Forge models
@@ -28399,7 +29618,7 @@ How this link ships through ChatGPT end to end (the app connector, the custom GP
# Architecture Overview
-three.ws is the platform you see at [three.ws](https://three.ws): 3D avatars with AI brains that you can chat with, embed on any site, and register on-chain. This page is the engineering map of how that is built. If you just want to use the product, start with [How three.ws works](#sec-239) instead.
+three.ws is the platform you see at [three.ws](https://three.ws): 3D avatars with AI brains that you can chat with, embed on any site, and register on-chain. This page is the engineering map of how that is built. If you just want to use the product, start with [How three.ws works](#sec-240) instead.
This document describes how three.ws is put together, how data moves through it, and where the seams are if you want to extend, self-host, or integrate it with another stack. It assumes familiarity with modern JavaScript, WebGL/three.js at a high level, and the basics of EVM blockchains and content-addressed storage.
@@ -28625,7 +29844,7 @@ Per-chain registry addresses, ABIs, and helpers live in `src/erc8004/`. RPC endp
## 9. Security model
- **Client-side processing.** GLB files never leave the browser unless the user explicitly pins them. Drag-and-drop uses the File API and blob URLs — no upload.
-- **Skill sandbox.** Skills are arbitrary JS. The registry has three trust modes: `any` (dev only), `owned-only` (skill author must match agent owner), and `whitelist`. Combined with **ERC-7710 delegation** for wallet-touching capabilities, a skill can only sign or transact with permissions the user has explicitly delegated.
+- **Skill sandbox.** Skills are arbitrary JS. The registry has three trust modes: `any` (dev only), `owned-only` (the default: skill author must match agent owner), and `whitelist` (reserved, the allowlist consultation is still a hook in `src/skills/index.js`). Combined with **ERC-7710 delegation** for wallet-touching capabilities, a skill can only sign or transact with permissions the user has explicitly delegated.
- **CSP compatibility.** The embed bundle has no inline scripts; host pages can set strict CSP.
- **Embed policy.** The manifest can declare `embed.origins` as an allowlist or denylist. Enforced client-side by the element and server-side via referrer checks.
- **SIWE.** Sign-In With Ethereum for backend mutations: signed typed message with server nonce → session cookie. No passwords.
@@ -28670,9 +29889,9 @@ The assistant widget puts a full-body, animated three.ws avatar on any website b
Configure everything and copy your snippet at [three.ws/assistant](https://three.ws/assistant). The builder page runs the real widget, so what you see in the corner is exactly what your visitors get.
-Looking for a support-chat panel grounded in your page's content instead of a full-body avatar? That is the sibling [Concierge widget](#sec-149). Use Concierge for "answer questions about this page"; use the assistant widget when you want a character who stands on your site, speaks, and can run on a visitor's own model key.
+Looking for a support-chat panel grounded in your page's content instead of a full-body avatar? That is the sibling [Concierge widget](#sec-152). Use Concierge for "answer questions about this page"; use the assistant widget when you want a character who stands on your site, speaks, and can run on a visitor's own model key.
-There are three ways to add it: a one-tag script, the [`@three-ws/assistant`](https://www.npmjs.com/package/@three-ws/assistant) npm package, or let an AI agent generate the embed for you through the [assistant-widget MCP server](#generate-a-widget-from-an-ai-agent-mcp). New to it? The [step-by-step tutorial](#sec-412) builds one from scratch.
+There are three ways to add it: a one-tag script, the [`@three-ws/assistant`](https://www.npmjs.com/package/@three-ws/assistant) npm package, or let an AI agent generate the embed for you through the [assistant-widget MCP server](#generate-a-widget-from-an-ai-agent-mcp). New to it? The [step-by-step tutorial](#sec-418) builds one from scratch.
## Install
@@ -28781,22 +30000,22 @@ Two tools:
- **`list_assistant_options`** returns everything you can configure: the built-in avatars, the background presets and grammar, the modes, the chat lanes, and the full `data-*` attribute reference.
- **`build_assistant_widget`** turns a config (avatar, background, mode, name, greeting, context, accent, position) into a paste-ready `<script>` snippet, a standalone frame URL, an equivalent `ThreeAssistant.init({...})` call, and the builder link. Every field is validated and clamped, so a bad value falls back to a safe default and the generated HTML is always well-formed.
-Ask your agent something like "build a 3D assistant widget named Aria with an ocean background for my site" and paste the snippet it returns. The server is one of the [three.ws MCP servers](#sec-276); find it in the registry at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/?q=io.github.nirholas).
+Ask your agent something like "build a 3D assistant widget named Aria with an ocean background for my site" and paste the snippet it returns. The server is one of the [three.ws MCP servers](#sec-277); find it in the registry at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/?q=io.github.nirholas).
## How it works
- The launcher and panel are plain DOM injected by [`public/assistant/v1.js`](https://github.com/nirholas/three.ws/blob/main/public/assistant/v1.js), the minified build of the [`@three-ws/assistant`](https://github.com/nirholas/three.ws/tree/main/assistant-sdk) loader (no dependencies, idempotent). The avatar, chat, and speech run inside an iframe on `https://three.ws/assistant-frame`, so your page never sees model keys and the frame never sees your DOM.
- The frame ([`src/assistant-frame.js`](https://github.com/nirholas/three.ws/blob/main/src/assistant-frame.js)) renders the avatar with Three.js, retargets the platform's canonical animation clips onto it (idle, wave greeting, a talking loop while speaking), and anchors the speech bubble to the avatar's head projection every frame.
-- Free-lane chat posts to `POST /api/chat` (SSE stream, anonymous access, server-side rate limits; three.ws applies no content filter of its own, so any refusal is the serving model's). BYOK chat streams directly from the visitor's browser to Groq or OpenRouter with their key; the key lives in `localStorage` on the three.ws origin and is never sent to three.ws servers or the host page.
+- Free-lane chat posts to `POST /api/chat` (SSE stream, anonymous access, server-side rate limits; three.ws applies no content filter of its own, so any refusal is the serving model's). BYOK chat streams directly from the visitor's browser to Groq or OpenRouter with their key; the key lives in `localStorage` on the three.ws origin and is never sent to three.ws servers or the host page. When every free provider is throttled at once, the route answers `503 rate_limited` with a `retry_after`, and the widget shows that wait in the bubble alongside the settings panel as the way out (a visitor's own key is never subject to the platform's capacity).
- Speak mode and spoken chat replies use the Web Speech API (`speechSynthesis`). Voice pick persists per browser. When the browser has no TTS or voice is muted, the bubble and talking animation still run for the estimated duration, so the widget never silently stalls.
- Every config param is re-validated inside the frame by [`src/assistant-widget-core.js`](https://github.com/nirholas/three.ws/blob/main/src/assistant-widget-core.js) (strict background/color grammars, length clamps, avatar host allow-list), so a hostile embedding page cannot inject CSS or URLs into the frame.
## Related surfaces
-- [Build a 3D assistant, step by step](#sec-412), the tutorial
-- [Concierge](#sec-149), the page-grounded support-chat widget with a lipsyncing face
-- [three.ws MCP servers](#sec-276), the full free and paid tool catalog
-- [Share and embed](#sec-373), the `<three-d>` model embeds
+- [Build a 3D assistant, step by step](#sec-418), the tutorial
+- [Concierge](#sec-152), the page-grounded support-chat widget with a lipsyncing face
+- [three.ws MCP servers](#sec-277), the full free and paid tool catalog
+- [Share and embed](#sec-378), the `<three-d>` model embeds
- [/walk-embed](https://three.ws/walk-embed), the walking-avatar iframe embed
- [/forge](https://three.ws/forge), generate an avatar to use in the widget
@@ -29680,8 +30899,8 @@ and the platform **scans its own wallets for leaks every few minutes**.
This page explains the whole loop in plain language: which wallet does what, how money
can and cannot move, and how you can verify there's no leak yourself.
-Companion docs: [Money map](#sec-286) (which wallet receives each *payment*),
-[Economy master](#sec-179) (the funding-root subsystem in depth), and the
+Companion docs: [Money map](#sec-287) (which wallet receives each *payment*),
+[Economy master](#sec-182) (the funding-root subsystem in depth), and the
[Solana signers runbook](../api/_lib/solana-signers.js) (every signer, its floor, and
how to fund it).
@@ -29820,11 +31039,11 @@ zero.
## Related
-- [Money map](#sec-286) — which wallet receives each kind of payment, and the
+- [Money map](#sec-287) — which wallet receives each kind of payment, and the
platform's cut.
-- [Economy master](#sec-179) — the funding-root subsystem, its ledger, and the
+- [Economy master](#sec-182) — the funding-root subsystem, its ledger, and the
topup/sweepback crons in depth.
-- [x402 ring economy](#sec-516) — how the autonomous payment ring settles
+- [x402 ring economy](#sec-541) — how the autonomous payment ring settles
USDC between agents.
---
@@ -29856,7 +31075,7 @@ the sniper oracle gate.
The loop runs from the `x402-autonomous-loop` cron endpoint, invoked every
**minute** by the `economy-tick` dispatcher (see the
-[economy heartbeat](#sec-178)) rather than by its own schedule
+[economy heartbeat](#sec-181)) rather than by its own schedule
entry; per-entry Redis cooldowns decide what actually fires on any given tick.
Each tick:
@@ -29906,7 +31125,7 @@ master holds funds.
| `X402_ASSET_MINT_SOLANA` | USDC mint | The asset paid with (Solana USDC). |
| `SOLANA_RPC_URL` | — | RPC used to build and submit the payment. |
-This loop's treasury is **separate** from the [circulation engine](#sec-139)
+This loop's treasury is **separate** from the [circulation engine](#sec-141)
treasury (`CIRCULATION_TREASURY_SECRET`). Circulation funds agent-to-agent SOL /
$THREE activity; this loop funds USDC intel purchases. They do not fund each
other.
@@ -29992,7 +31211,7 @@ automatically (and `tests/x402-ring-catalog.test.js` fails until it is cataloged
> reasoning lives in
> [x402 revenue → Synthetic vs organic](x402-revenue.md#proof-of-volume--x402_volume_metrics).
> Drive *real* volume through external demand (the
-> [Circulation engine](#sec-139), real `agent_hire` commerce,
+> [Circulation engine](#sec-141), real `agent_hire` commerce,
> discovery), not a heavier self-paid sweep.
## The Datapoint Fabric Volume Sweep
@@ -30045,17 +31264,17 @@ corroborate — the ops financial-integrity surface alerts on those. Detail:
| `x402_autonomous_log` | Every call (success or failure), with `signal_data` / `value_extracted`. `error_msg` is reserved for calls that actually failed: the external uptime monitor probes third-party services for free and records an alive-but-unexpected status (a templated path answering 400, a verb-picky route answering 405) in `value_extracted.status` only, so a liveness observation never lands in the loop's failure stats. |
| `oracle_intel_signals` | `oracle` / `sniper` entries, keyed by source + topic; consumed by the sniper oracle gate. Each row carries `tx_signature`, the settle signature of the paid call that bought it, so a gate decision can cite its receipt (surfaced as `signal_receipts` on gate results). |
| `forge_creations` | Every settled `POST /api/x402/forge` generation (any buyer, not just this loop). The row lands in the public community gallery with `x402_payer` / `x402_tx_sig` / `x402_price_atomic` provenance; the gallery renders a Solscan-linked "x402 · $price" badge. Inline-done lanes materialize immediately; async lanes store the full job token and `api/cron/forge-finalize` completes them server-side. |
-| `agent_custody_events` | The USDC spend, with `category: 'x402'` (see [Money feed](#sec-284)). |
+| `agent_custody_events` | The USDC spend, with `category: 'x402'` (see [Money feed](#sec-285)). |
| `x402_volume_metrics` | Per-endpoint proof-of-volume + liveness ledger from the Volume Bootstrap Loop (see [x402 revenue](x402-revenue.md#proof-of-volume--x402_volume_metrics)). |
| `payment_reconciliation` | One verdict per settlement claim from the daily reconciliation job (see [x402 revenue](x402-revenue.md#reconciliation--payment_reconciliation)). |
| Dedicated stores | Pipeline-specific tables (pricing tracker, reputation snapshots, leaderboard, sniper analytics, …). |
## Related
-- [x402 endpoints](#sec-514) — the paid endpoints this loop calls.
-- [x402 revenue & receipts](#sec-515) — where settlements land, the proof-of-volume ledger, and the reconciliation job.
-- [x402 buyer client](#sec-511) — the client wrappers it pays with.
-- [Circulation engine](#sec-139) — the separate SOL/$THREE activity loop.
+- [x402 endpoints](#sec-539) — the paid endpoints this loop calls.
+- [x402 revenue & receipts](#sec-540) — where settlements land, the proof-of-volume ledger, and the reconciliation job.
+- [x402 buyer client](#sec-536) — the client wrappers it pays with.
+- [Circulation engine](#sec-141) — the separate SOL/$THREE activity loop.
---
@@ -30102,7 +31321,7 @@ Auth is a session cookie or a bearer token. Every read and write is rate-limited
3. Use the master switch on a card to turn Autopilot on or off for that coin. "Autopilot on" means its rules run; "Paused" means the crons skip it.
4. Set the **Buyback and burn** rule: toggle it on, set a minimum USDC floor, and choose whether fees are swapped into the token before burning or burned directly.
5. Set the **Distribute to holders** rule: toggle it on and set its minimum USDC floor. Enable "Narrate this coin's actions on the live feed" to have the agent speak its moves.
-6. Every change autosaves (checkboxes immediately, number fields after a short debounce). A toast confirms "Autopilot updated".
+6. Every change autosaves: checkboxes the moment you flip one, number fields a short debounce after you stop typing (you do not have to leave the field, and a value typed right before you navigate away is still sent). The card itself reports the write as `Saving` then `Saved`, and a toast confirms "Autopilot updated". If the write fails, the card keeps a `Not saved` marker with the reason and a **Retry** button until it lands, so a rule you believe you set is never silently missing from the database.
7. Watch the activity feed and the narrator. As fees accumulate past your thresholds, the crons act, and each buyback or distribution appears with its status and a Solscan link to the on-chain transaction.
## Examples
@@ -30144,19 +31363,19 @@ A confirmed buyback narrates as: "Bought back and burned $120 of $YOURCOIN. Supp
- **Ownership scoped.** Every read and write is filtered to coins whose `user_id` is yours. Posting a policy for a mint you do not own returns `404 not_found`.
- **Floors are the safety valve.** A buyback or distribution only fires once the relevant vault clears the USDC floor you set. Set a floor to zero and it acts whenever the vault is non-empty; raise it to batch actions.
-- **Merge semantics.** Partial POSTs only change the fields present. A missing policy row reports legacy defaults (everything enabled, zero floors, narrate on) with `configured: false`.
+- **Merge semantics.** Partial POSTs only change the fields present. A missing policy row reports legacy defaults (everything enabled, zero floors, narrate on) with `configured: false`. The card marks that coin **Defaults** so an inherited "Autopilot on" is never mistaken for a rule you chose; the badge clears as soon as your first change saves.
- **Signed out** renders a "Sign in to manage autopilot" state; `GET` returns `401` and the page routes you to the dashboard.
- **Empty state** appears when you own no coins, pointing you to the launcher rather than showing a blank void.
-- **Error and retry.** A network or server error renders an inline "Couldn't load" card with a Retry button; a transient poll failure keeps the last good render and retries on the next tick.
-- **Live refresh** polls every 20 seconds and only refreshes the activity feed and narrator, never the control inputs you may be editing, so a poll can never overwrite your keystrokes.
-- **Atomics are integers.** Thresholds are clamped to non-negative integer atomic strings server-side; a decimal is truncated, a negative or non-numeric value falls back to zero.
+- **Error and retry.** A network or server error renders an inline "Couldn't load your coins" card with a Retry button, and the activity column says why it is empty instead of leaving loading skeletons on screen. You do not have to press Retry: the poll re-runs the full load while the page is in that state, so it restores itself the moment the API is reachable again.
+- **Live refresh** polls every 20 seconds. Once your cards are on screen it refreshes only the activity feed and narrator, never the control inputs you may be editing, so a poll can never overwrite your keystrokes. A session that expires under the page swaps in the signed-out state rather than leaving controls that can no longer save. Signed out, the poll stops entirely instead of retrying an endpoint that will keep refusing.
+- **Atomics are integers.** Thresholds are clamped to non-negative integer atomic strings server-side; a decimal is truncated, a negative or non-numeric value falls back to zero. The field shows you that clamp when you leave it, so what you see is what was stored.
- **On-chain actions are the crons', not the page's.** The console never signs a transaction. It only writes policy rows; the buyback and distribute crons are what move funds, on their own schedule, within the vault floors you set.
## Related
-- [Custody you can verify](#sec-167) - the spend limits, freeze switch, and audit trail every agent wallet runs under
-- [Financial controls](#sec-219) - plain-English spend rules layered on the same enforcement point
-- [Oracle](#sec-310) - the conviction engine and the agent action loop that arms an agent to trade autonomously
+- [Custody you can verify](#sec-170) - the spend limits, freeze switch, and audit trail every agent wallet runs under
+- [Financial controls](#sec-221) - plain-English spend rules layered on the same enforcement point
+- [Oracle](#sec-315) - the conviction engine and the agent action loop that arms an agent to trade autonomously
- [/dashboard](https://three.ws/dashboard) - launch a coin for an agent, the prerequisite for Autopilot
- [/launches](https://three.ws/launches) - the public feed of coins launched through three.ws
@@ -30164,6 +31383,139 @@ A confirmed buyback narrates as: "Bought back and burned $120 of $YOURCOIN. Supp
<a id="sec-107"></a>
+> **Source:** `docs/avatar-artifact.md` · [↑ table of contents](#table-of-contents)
+
+# Avatar Artifact: the standalone viewer
+
+[three.ws/avatar-artifact](https://three.ws/avatar-artifact) is one page that renders one avatar and nothing else. No app shell, no sign-in, no navigation to get lost in: a URL you can paste into an `<iframe>` on any site, or send to someone who has never heard of three.ws, and it renders a live 3D avatar in their browser.
+
+It is deliberately the smallest viewer we ship. [The full 3D viewer](#sec-505) is the engine behind `/app` and every `<agent-3d>` embed, with camera rigs, material editing and a clip panel. This page has one job: show the artifact, beautifully, from a link.
+
+---
+
+## The three modes
+
+| URL | What renders |
+| --- | --- |
+| `/avatar-artifact` | The house portrait: a procedural figure that follows your cursor. The page's own identity, and what a bare link shows. |
+| `/avatar-artifact?agent=<uuid>` | That agent's avatar, resolved live from `GET /api/agents/<uuid>`. |
+| `/avatar-artifact?model=<glb url>` | Any GLB served from an allowed host. No agent, no persona, just the model. |
+
+Passing both `agent` and `model` is an error, the same rule [the Claude artifact endpoint](../specs/CLAUDE_ARTIFACT.md) applies. The page says so and offers a way out rather than guessing.
+
+### Viewing an agent
+
+```
+https://three.ws/avatar-artifact?agent=27a0f649-3b59-4552-bb0b-faf616ac448b
+```
+
+The page fetches the agent's public record, reads `avatar_model_url`, and renders it. The agent's name becomes the page heading and the document title, and an **Open profile** link appears next to the controls so the viewer is never a dead end.
+
+Only avatars whose visibility is `public` or `unlisted` carry a model URL in the public API. An agent whose avatar is private renders a designed message saying so and links to the profile, which stays public.
+
+### Viewing a raw model
+
+```
+https://three.ws/avatar-artifact?model=https://three.ws/avatars/michelle.glb
+```
+
+The model URL must be `https:` on one of these hosts, or same-origin:
+
+- `*.r2.dev`, `*.r2.cloudflarestorage.com`
+- `*.amazonaws.com`, `*.cloudfront.net`
+- `storage.googleapis.com`
+- `*.blob.core.windows.net`
+- `three.ws`, `*.vercel.app`
+
+Anything else is refused with an explanation instead of rendered. This is the same allowlist `/api/artifact` enforces server-side, for the same reason: an indexed page on our origin must not become a renderer for arbitrary third-party payloads.
+
+---
+
+## Embedding it
+
+Click **Copy embed** on the page and you get an iframe pointed at exactly what you are looking at, artifact parameters included:
+
+```html
+<iframe
+ src="https://three.ws/avatar-artifact?agent=27a0f649-3b59-4552-bb0b-faf616ac448b"
+ width="100%"
+ height="600"
+ style="border:0"
+ loading="lazy"
+ title="Avatar Artifact"
+></iframe>
+```
+
+If the clipboard is unavailable (a cross-origin frame, or Safari) the page reveals the snippet in a text field instead of failing silently.
+
+Two properties make this safe to drop on someone else's page:
+
+- **No third-party CDN.** three.js ships with the bundle. An embed host never picks up a cross-origin script tag it did not agree to.
+- **It stops when it is not visible.** A hidden tab suspends the render loop, so an embedded viewer never burns a host page's GPU in the background.
+
+For a full chat widget or a token-gated embed, use [Share and embed](#sec-378) instead. This page is the plain viewer.
+
+---
+
+## Interaction
+
+Every input drives one look-target, so the page works with a mouse, a finger or a keyboard alone:
+
+| Input | Effect |
+| --- | --- |
+| Move the cursor | Turn the subject |
+| Drag (touch) | Same, on a phone |
+| Arrow keys, or `WASD` | Same, without a pointer |
+| `+` / `-`, or the wheel | Zoom (artifact modes only) |
+
+`prefers-reduced-motion` removes the idle sway, breathing and drift; the avatar still responds to input.
+
+---
+
+## Animation
+
+If the GLB carries its own animation clips, the page plays one: whichever is named for an idle, or the first clip. The author's intent wins.
+
+Most three.ws avatars carry no baked clips, because motion lives in the [shared clip library](#sec-093) and is retargeted onto whatever skeleton the rig uses. The page does exactly that: it attaches an `AnimationManager`, loads the `idle` clip and retargets it. Any humanoid rig the canonicalizer recognises comes to life; a rig that genuinely cannot be skeleton-driven (a static prop, a non-humanoid mesh) simply stands still. Nothing renders in a bind-pose T-pose.
+
+---
+
+## When something goes wrong
+
+Every failure has its own sentence and its own next move. There is no blank screen and no raw exception:
+
+| What happened | What the page says |
+| --- | --- |
+| The 3D runtime never loaded | Network hiccup, offers a retry |
+| The browser has no WebGL | Names the cause, suggests another browser |
+| No agent with that id | The link may be old, offers **Browse agents** |
+| The agent lookup failed | Network hiccup, offers a retry |
+| The agent has no avatar yet | Explains, links to the profile |
+| The agent's avatar is private | Explains, links to the (public) profile |
+| The model host is not allowed | Names the rule |
+| The model failed to load | Moved, or a compression format this viewer does not carry |
+
+A large model on a slow connection is not a failure: the loading overlay reports byte progress, and the watchdog re-arms on every progress tick so a download that is genuinely still running is never called dead.
+
+---
+
+## Where the code lives
+
+- Page markup and copy: [pages/avatar-artifact.html](../pages/avatar-artifact.html)
+- Scene, artifact resolution and loading: [src/avatar-artifact.js](../src/avatar-artifact.js)
+- Clip retargeting: [src/animation-manager.js](../src/animation-manager.js)
+
+## Related
+
+- [The 3D viewer](#sec-505): the full engine behind `/app` and `<agent-3d>`
+- [Share and embed](#sec-378): widgets, web components and embed policy
+- [Claude artifact contract](../specs/CLAUDE_ARTIFACT.md): the self-contained HTML lane for Claude.ai, which shares this page's parameter shape
+- [Animations](#sec-093): the clip library this page retargets from
+
+---
+
+<a id="sec-108"></a>
+
> **Source:** `docs/avatar-cli.md` · [↑ table of contents](#table-of-contents)
# Avatar CLI
@@ -30174,7 +31526,7 @@ It is the piece that lets avatars live in a build pipeline instead of a browser
**On this page:** [Install](#install) · [Quick start](#quick-start) · [Commands](#commands) · [The manifest](#the-manifest) · [Exit codes](#exit-codes-and-scripting) · [Release gate](#gate-a-release-on-the-manifest)
-Related: [`@three-ws/avatar-schema`](../packages/avatar-schema/README.md) is the wire format this validates against. The [web component reference](#sec-502) covers the `<agent-3d>` element the CLI emits.
+Related: [`@three-ws/avatar-schema`](../packages/avatar-schema/README.md) is the wire format this validates against. The [web component reference](#sec-508) covers the `<agent-3d>` element the CLI emits.
---
@@ -30368,7 +31720,7 @@ https://three.ws/a/eip155%3A1%3A0x742d35Cc6634C0532925a3b844Bc454e4438f44e
<iframe src="https://three.ws/a/eip155%3A1%3A0x742d35Cc6634C0532925a3b844Bc454e4438f44e" width="480" height="640" frameborder="0" allow="camera; microphone; xr-spatial-tracking"></iframe>
```
-The web-component block is emitted with its loader on purpose. `<agent-3d>` is an ordinary unknown element until that script registers it, so the snippet is only complete with both lines. See the [web component reference](#sec-502) for the full attribute surface.
+The web-component block is emitted with its loader on purpose. `<agent-3d>` is an ordinary unknown element until that script registers it, so the snippet is only complete with both lines. See the [web component reference](#sec-508) for the full attribute surface.
When `mesh.uri` is still a local path, `preview` says so rather than handing you a snippet that renders nothing:
@@ -30465,14 +31817,14 @@ three-ws-avatar validate manifest.json --json | jq -e '.valid'
## Where to go next
-- **[Ship an avatar manifest](#sec-462)** walks the whole path end to end, from a raw GLB to a live embed, and explains the decision at each step.
-- **[Web component reference](#sec-502)** documents every attribute on the `<agent-3d>` element `preview` emits.
+- **[Ship an avatar manifest](#sec-468)** walks the whole path end to end, from a raw GLB to a live embed, and explains the decision at each step.
+- **[Web component reference](#sec-508)** documents every attribute on the `<agent-3d>` element `preview` emits.
- **[`@three-ws/avatar-schema`](../packages/avatar-schema/README.md)** is the normative format if you are writing your own tooling.
- The package source lives in [`packages/avatar-cli`](https://github.com/nirholas/three.ws/tree/main/packages/avatar-cli).
---
-<a id="sec-108"></a>
+<a id="sec-109"></a>
> **Source:** `docs/avatar-creation.md` · [↑ table of contents](#table-of-contents)
@@ -30511,7 +31863,7 @@ Good lighting and a plain background give the best results. Photos can be JPEG o
1. Go to **https://three.ws/create** and pick the selfie path (or open **https://three.ws/create/selfie** directly)
2. Choose **Camera** (to take live photos in-browser) or **Upload** (to pick files from your device)
3. Fill the frontal slot; add left/right photos if you have them
-4. Select your preferred **body type** (male / female) and **avatar style** (v1 = Photoreal, v2 = Stylized)
+4. Select your **avatar style** (v1 = Photoreal, v2 = Stylized). There is deliberately no body-type picker: reconstruction fits your face onto one shared template body today, so a masc/femme toggle would change nothing. Body choice returns when reconstruction moves onto the parametric base, tracked in [avatar-fidelity-program.md](#sec-111) under Track 5
5. Click **Submit**
The photos are downscaled in the browser and sent to the native avatar reconstruction backend. A build view shows progress while the rigged GLB renders (typically a minute or two); when the job finishes, the avatar is saved to your three.ws account automatically and opens for review.
@@ -30524,8 +31876,8 @@ If your browser or device doesn't support `getUserMedia`, the Camera option is d
For developers who want to understand what happens under the hood:
-1. [selfie-capture.js](../src/selfie-capture.js) manages the two-step UI: method choice (camera vs upload) and the photo slots (frontal required, sides optional). On submit it dispatches a `selfie:submit` CustomEvent with `{ files, bodyType, avatarType }`.
-2. [selfie-pipeline.js](../src/selfie-pipeline.js) handles that event: it runs an on-device photo check and refinement pass ([selfie-refine.js](../src/selfie-refine.js)), downscales each photo to a max of 1024px as JPEG, then POSTs to `/api/avatars/reconstruct` with the photos and body/style preferences.
+1. [selfie-capture.js](../src/selfie-capture.js) manages the two-step UI: method choice (camera vs upload) and the photo slots (frontal required, sides optional). On submit it dispatches a `selfie:submit` CustomEvent with `{ files, avatarType, method }`.
+2. [selfie-pipeline.js](../src/selfie-pipeline.js) handles that event: it runs an on-device photo check and refinement pass ([selfie-refine.js](../src/selfie-refine.js)), downscales each photo to a max of 1024px as JPEG, then POSTs to `/api/avatars/reconstruct` with the photos and the chosen style.
3. The endpoint returns a `jobId`. The pipeline dispatches `selfie:building` and polls `/api/avatars/regenerate-status?jobId=...` every 3 seconds, dispatching `selfie:progress` ticks the build view renders.
4. On `{ status: 'done', resultAvatarId }` it dispatches `selfie:done { avatarId }`. The avatar record and its GLB in R2 storage were created server-side, so nothing else needs to be uploaded. Failures dispatch `selfie:build-error` with a message and, when detectable, the photo slot that caused it.
@@ -30562,7 +31914,7 @@ Avatar Studio communicates with the parent app via `postMessage`. The message sh
[avatar-creator.js](../src/avatar-creator.js) listens for this, wraps the `ArrayBuffer` in a `Blob`, and passes it to `saveRemoteGlbToAccount()`.
-The avatar builder is served **same-origin** under `/avatar-studio` — the Vite dev middleware serves the character-studio build there in development, and the same build ships to that path in production, so the iframe resolves correctly on every deployment. Set the `VITE_CHARACTER_STUDIO_URL` environment variable to point the iframe at a standalone studio dev server (e.g. `http://localhost:5173`) instead.
+The avatar builder is served **same-origin** from `/avatar-studio/index.html`: the Vite dev middleware serves the character-studio build under that path in development, and the same build ships there in production, so the iframe resolves correctly on every deployment. The index file is named explicitly because the bare `/avatar-studio` path is routed to the native sculpting page. Set the `VITE_CHARACTER_STUDIO_URL` environment variable to point the iframe at a standalone studio dev server (e.g. `http://localhost:5173/avatar-studio/`) instead.
---
@@ -30744,7 +32096,7 @@ On success, you receive:
### 3. Register on-chain (optional)
-For permanent, verifiable identity, you can register the agent on-chain under ERC-8004. This creates a blockchain record linked to a wallet address. Gas fees apply. See the [ERC-8004 documentation](#sec-185) for details.
+For permanent, verifiable identity, you can register the agent on-chain under ERC-8004. This creates a blockchain record linked to a wallet address. Gas fees apply. See the [ERC-8004 documentation](#sec-188) for details.
---
@@ -30808,7 +32160,7 @@ No regeneration provider is configured on this deployment. Set `AVATAR_REGEN_PRO
---
-<a id="sec-109"></a>
+<a id="sec-110"></a>
> **Source:** `docs/avatar-engines.md` · [↑ table of contents](#table-of-contents)
@@ -30870,7 +32222,7 @@ Mesh and glTF output can be animated by the skinned-mesh pipeline. Gaussian and
| --- | --- | --- |
| `live` | Live on three.ws | Already wired into a three.ws product surface you can use right now. |
| `forge` | Generate in Forge | Commercially licensed and reachable through the live text and image to GLB pipeline at [/forge](https://three.ws/forge). |
-| `splat` | View in Splat Viewer | Produces Gaussian-splat or radiance-field output you can drop into the three.ws [splat viewer](#sec-391). |
+| `splat` | View in Splat Viewer | Produces Gaussian-splat or radiance-field output you can drop into the three.ws [splat viewer](#sec-397). |
| `interop` | Interop | Emits a standard rigged format (glTF, VRM, FBX) that the three.ws viewer and animation pipeline already understand. |
| `reference` | Reference / self-host | Run it yourself. Its license or its compute profile keeps it out of the commercial pipeline. It is listed here for builders. |
@@ -30977,16 +32329,16 @@ To add an engine, append an entry to `ENGINES` in [`src/avatar-engines-data.js`]
## Related
-- [Splat Viewer](#sec-391): where the Gaussian-splat output of the `splat` engines actually renders in the browser.
-- [Scene Capture](#sec-132): the three.ws side of reconstruction, turning real video into 3D, adjacent to the photoreal-head family here.
-- [Forge](#sec-224): the live commercial generation pipeline, which the one `live` text-to-avatar engine powers.
+- [Splat Viewer](#sec-397): where the Gaussian-splat output of the `splat` engines actually renders in the browser.
+- [Scene Capture](#sec-134): the three.ws side of reconstruction, turning real video into 3D, adjacent to the photoreal-head family here.
+- [Forge](#sec-225): the live commercial generation pipeline, which the one `live` text-to-avatar engine powers.
- [Agent Identity Studio](#sec-053): that pipeline applied end to end, brand brief to rigged avatar plus studio renders.
- [Animations](#sec-093): the retargeting and clip library that drives the production rigs in the last family.
-- [Avatar pipeline](#sec-112) and [avatar creation](#sec-108): how three.ws produces and processes its own mesh avatars.
+- [Avatar pipeline](#sec-113) and [avatar creation](#sec-109): how three.ws produces and processes its own mesh avatars.
---
-<a id="sec-110"></a>
+<a id="sec-111"></a>
> **Source:** `docs/avatar-fidelity-program.md` · [↑ table of contents](#table-of-contents)
@@ -30998,7 +32350,7 @@ own, and costs nothing per avatar. Not "good enough to avoid a bill" — better
than the thing we would have paid for.
This is the program plan. The subsystem it improves is documented in
-[avatar-reconstruction.md](#sec-113); the worker lives in
+[avatar-reconstruction.md](#sec-114); the worker lives in
[`workers/avatar-reconstruction/`](../workers/avatar-reconstruction).
## Why we are not buying this
@@ -31444,7 +32796,7 @@ items do not:
---
-<a id="sec-111"></a>
+<a id="sec-112"></a>
> **Source:** `docs/avatar-inspector.md` · [↑ table of contents](#table-of-contents)
@@ -31549,7 +32901,7 @@ Related reading: [agent reputation](#sec-056) · [Agora](#sec-075).
---
-<a id="sec-112"></a>
+<a id="sec-113"></a>
> **Source:** `docs/avatar-pipeline.md` · [↑ table of contents](#table-of-contents)
@@ -31558,8 +32910,8 @@ Related reading: [agent reputation](#sec-056) · [Agora](#sec-075).
This is the end-to-end view of how a text prompt or image becomes a rigged,
animated 3D avatar on three.ws — from generation, through auto-rigging, to the
universal animation system that drives any humanoid skeleton. It ties together the
-individual tool docs ([Avatar creation](#sec-108),
-[Avatar Studio](#sec-135), [Animations](#sec-093),
+individual tool docs ([Avatar creation](#sec-109),
+[Avatar Studio](#sec-137), [Animations](#sec-093),
[3D asset pipeline](#sec-002)) into one map.
---
@@ -31586,7 +32938,7 @@ prompt / image
Generation quality is a **tier** ([api/_lib/forge-tiers.js](../api/_lib/forge-tiers.js)): `draft`, `standard`
(default), or `high` — more geometric budget at higher tiers. The tier sets the
price identically across REST and MCP transports (see
-[MCP tools](#sec-274), [x402 endpoints](#sec-514)).
+[MCP tools](#sec-275), [x402 endpoints](#sec-539)).
### ② Auto-rig
@@ -31663,22 +33015,22 @@ an avatar still animates.
A finished avatar is a GLB (plus optional rig + clips) viewable in the three.ws
viewer, embeddable as a web component, and attachable to an agent. Paid
generation/editing is metered per call over x402; the free studio lane requires no
-account. See [Avatar creation](#sec-108) and
-[Avatar Studio](#sec-135) for the authoring UIs, and
-[Mesh editing tools](#sec-274) for retexture / stylize / remesh / segment /
+account. See [Avatar creation](#sec-109) and
+[Avatar Studio](#sec-137) for the authoring UIs, and
+[Mesh editing tools](#sec-275) for retexture / stylize / remesh / segment /
pose operations.
## Related
-- [Selfie → Avatar reconstruction](#sec-113) — the separate lane that fits a *person's photo* onto a rigged template (face texture + geometry morph), rather than generating a mesh from a prompt.
+- [Selfie → Avatar reconstruction](#sec-114) — the separate lane that fits a *person's photo* onto a rigged template (face texture + geometry morph), rather than generating a mesh from a prompt.
- [Animations](#sec-093) — the clip library and retargeting in depth.
- [3D asset pipeline](#sec-002) — formats, optimization, validation.
-- [NVIDIA free models](#sec-296) — the free generation backend.
-- [MCP tools](#sec-274) — every generation/editing tool and its price.
+- [NVIDIA free models](#sec-297) — the free generation backend.
+- [MCP tools](#sec-275) — every generation/editing tool and its price.
---
-<a id="sec-113"></a>
+<a id="sec-114"></a>
> **Source:** `docs/avatar-reconstruction.md` · [↑ table of contents](#table-of-contents)
@@ -31686,7 +33038,7 @@ pose operations.
This is the subsystem that turns a **user's photo** (or a text→image reference)
into a rigged, animation-ready 3D avatar. It is distinct from the Forge
-generation lane in the [Avatar Pipeline](#sec-112): the Forge generates
+generation lane in the [Avatar Pipeline](#sec-113): the Forge generates
an *arbitrary* mesh from a prompt, whereas reconstruction fits a *specific
person* onto a fixed, pre-rigged template — the same architecture Avaturn and
Ready Player Me use, and the reason the output is born-rigged with facial
@@ -31725,6 +33077,36 @@ poll would have, so an abandoned job still lands in the library. Design notes:
- A provider 404 (`gcp_task_missing`) is terminal here, so a job whose worker
record is genuinely gone resolves instead of being retried forever.
+## Plan quotas are checked twice, on purpose
+
+A reconstruction only meets the caller's plan quota at the very end, inside
+`createAvatar` → `enforceQuotas`. That is roughly ninety seconds of GPU time
+after the button was pressed (plus a Flux reference image on the text→avatar
+lane), and a refusal there used to leave the job at `done` with no
+`resultAvatarId`: a state no recovery cron looks at (they filter on
+`queued`/`running`), which re-ran the same doomed materialization on every poll
+and reported the generic engine-fault copy to the browser. The user was told the
+engine had a problem, and every retry burned the same spend to land in the same
+place.
+
+Two checks now bracket the job:
+
+1. **Pre-flight, at submit.** `POST /api/avatars/reconstruct` calls
+ `assertAvatarSlotAvailable(userId)` ([`api/_lib/avatars.js`](../api/_lib/avatars.js))
+ before it resolves a provider or generates a reference image. A full library
+ is refused in milliseconds with `402 plan_limit` and an actionable
+ `error_description`. This is the check that fires in practice.
+2. **At materialization, for the race.** If another avatar lands while the mesh
+ is generating, the finalize stage still throws. `failJobOnPlanLimit` then
+ ends the job as `failed` with `error_kind = 'input'`, so
+ `/api/avatars/regenerate-status` relays the plan copy verbatim (see
+ [REGENERATE.md](../api/avatars/REGENERATE.md)) instead of masking it as an
+ engine fault.
+
+Only the per-plan avatar count and the total-bytes ceiling can be pre-flighted:
+per-file size is unknowable until the mesh exists, so `plan_limit_size` remains a
+materialization-time refusal.
+
## How it works
The avatar is a fixed-topology Wolf3D/RPM template that ships **pre-rigged** with
@@ -31760,11 +33142,14 @@ closes that gap:
freely, so a Gaussian locality mask fades the field to zero off the face and
the scalp, ears and neck stay put.
-`strength` and `max_displacement_frac` default to **0.6 / 0.45**, chosen by an
-ISE sweep over the 40-face reference set (`python -m eval.tune_morph`), not by
-eye. They cut mean ISE 43% against the original 0.75 / 0.18, whose ~1.9 cm
-displacement ceiling was throttling genuine facial variation rather than
-rejecting outliers. See [avatar-fidelity-program.md](#sec-110)
+`strength` and `max_displacement_frac` default to **0.6 / 0.55**, chosen by two
+sweeps over the 40-face reference set, not by eye: `python -m eval.tune_morph`
+(mean ISE, is the shape right?) and `python -m eval.robustness` (does a degraded
+photo of the same person still give the same head?). 0.55 sits at the knee of
+that fidelity-vs-robustness curve, cutting mean ISE 46% against the original
+0.75 / 0.18, whose ~1.9 cm displacement ceiling was throttling genuine facial
+variation rather than rejecting outliers; past 0.65 fidelity flatlines while
+instability keeps rising. See [avatar-fidelity-program.md](#sec-111)
for why the sweep's own looser optimum was deliberately not shipped.
Because vertex count and order never change, `glb_ops.set_head_geometry` writes
@@ -31858,7 +33243,7 @@ is unencumbered.
## Roadmap — beating Avaturn on fidelity
> The active plan built on this roadmap — tracks, owners, capacity and credit
-> allocation — is [avatar-fidelity-program.md](#sec-110).
+> allocation — is [avatar-fidelity-program.md](#sec-111).
> Fidelity claims are scored with the ISE metric in
> [`workers/avatar-reconstruction/eval/`](../workers/avatar-reconstruction/eval/README.md).
@@ -31907,7 +33292,7 @@ Full runbook: [`docs/ops/gcp-production.md`](ops/gcp-production.md).
---
-<a id="sec-114"></a>
+<a id="sec-115"></a>
> **Source:** `docs/avatar-studio.md` · [↑ table of contents](#table-of-contents)
@@ -31981,15 +33366,15 @@ curl 'https://three.ws/api/avatars/<avatarId>' -H 'cookie: <session>'
## Related
- [Animation Studio](#sec-092): pose and keyframe the avatar you build here.
-- [Scene Composer](#sec-148): forge props and attach them to the avatar's bones as a saved outfit.
-- [Mocap Studio](#sec-283): drive the avatar's face live from your webcam.
-- [Restyle Studio](#sec-363): shares the same GLB optimize-and-validate path.
-- [Trait-based avatar builder](#sec-135): the separate VRM studio embedded in the agent editor; a deep dive into its internals.
+- [Scene Composer](#sec-151): forge props and attach them to the avatar's bones as a saved outfit.
+- [Mocap Studio](#sec-284): drive the avatar's face live from your webcam.
+- [Restyle Studio](#sec-368): shares the same GLB optimize-and-validate path.
+- [Trait-based avatar builder](#sec-137): the separate VRM studio embedded in the agent editor; a deep dive into its internals.
- [/create](https://three.ws/create): the hub for every avatar-creation path, including selfie-to-avatar.
---
-<a id="sec-115"></a>
+<a id="sec-116"></a>
> **Source:** `docs/avatar-thumbnails.md` · [↑ table of contents](#table-of-contents)
@@ -32040,8 +33425,17 @@ import { thumbnailUrl } from './_lib/r2.js';
thumbnailUrl(null) // → null
thumbnailUrl('https://three.ws/avatars/x_og.png') // → null (legacy, always 404s)
thumbnailUrl('thumb/abc.png') // → https://<cdn>/thumb/abc.png
+thumbnailUrl('thumb/abc.png') // → null (S3_PUBLIC_DOMAIN unset)
```
+That last case is why the helper is built on `publicUrlOrNull()` rather than bare
+`publicUrl()`: reading `env.S3_PUBLIC_DOMAIN` throws on a deployment without object
+storage, and a single un-renderable key must not take down a whole list response.
+It did: `/api/pulse` answered `502 pulse_failed` and `/api/search` answered
+`503 not_configured` for every caller until both were pointed at the read-path
+helper. Upload paths keep calling `publicUrl()`, where the throw is the correct
+signal that there is nowhere to put the bytes.
+
Return `null` and let the surface render its designed placeholder. There were 43
bare `publicUrl(<thumbnail key>)` call sites across 32 files — agent cards, the
marketplace, explore, user profiles, leaderboards, and the image baked into on-chain
@@ -32238,7 +33632,7 @@ that adoption HEAD-checks the preview object before persisting it.
---
-<a id="sec-116"></a>
+<a id="sec-117"></a>
> **Source:** `docs/avatar-wardrobe.md` · [↑ table of contents](#table-of-contents)
@@ -32357,6 +33751,20 @@ measured against the canonical body before publish, so a generated garment
can never be a tile the closet then refuses to wear. Offline proof harness:
`node scripts/verify-garment.mjs <manifest url> [avatar.glb]`.
+Seven minutes is longer than most people keep a tab open, so `/wardrobe` saves
+the job id in `localStorage` under `twx_wardrobe_job` and resumes polling on
+the next visit. That resume is deliberately bounded, because a saved id that
+can never resolve would otherwise leave the generator disabled forever:
+
+- a `404` (or `job_not_found`) is **terminal**, not a blip. The saved id is
+ dropped, the form unlocks, and the page says the job is no longer on the
+ forge. Finished jobs are cleared upstream, so this is the normal end state
+ for a resume that arrives too late;
+- any other poll failure is treated as transient and retried on a longer
+ interval, up to six consecutive failures. After that the form unlocks and
+ the page says the job is still saved and a reload will pick it back up. The
+ id survives, so a genuine outage never destroys a running generation.
+
## Persistence shape
```json
@@ -32385,13 +33793,13 @@ bricking the avatar.
## Related
-- [`docs/avatar-reconstruction.md`](#sec-113) — selfie → avatar
-- [`docs/avatar-fidelity-program.md`](#sec-110) — identity fidelity program
+- [`docs/avatar-reconstruction.md`](#sec-114) — selfie → avatar
+- [`docs/avatar-fidelity-program.md`](#sec-111) — identity fidelity program
- [`specs/GARMENT_MANIFEST.md`](../specs/GARMENT_MANIFEST.md) — the wearable contract
---
-<a id="sec-117"></a>
+<a id="sec-118"></a>
> **Source:** `docs/aws-builder-center-agent-payment-sessions.md` · [↑ table of contents](#table-of-contents)
@@ -32876,7 +34284,7 @@ An autonomous agent with a private key is a liability you cannot bound. An auton
---
-<a id="sec-118"></a>
+<a id="sec-119"></a>
> **Source:** `docs/aws-builder-center-marketplace-x402.md` · [↑ table of contents](#table-of-contents)
@@ -32895,7 +34303,7 @@ tags: [aws, marketplace, saas, serverless, api]
# One paywall, two economies: putting AWS Marketplace metering in front of an x402 API
-> **Editor's note (2026-08-15).** This is the repo copy of an article published on the AWS Builder Center on 30 May 2026, kept as it was published. One thing has moved since: the AWS Marketplace listing is still awaiting publication, and the pricing decision landed on a **free** listing with no AWS pricing dimensions, so the AWS-metered path described below is built and deployed but not yet billing anyone. Every code sample is still the code that ships. For the current status see [aws-marketplace.md](#sec-122).
+> **Editor's note (2026-08-15).** This is the repo copy of an article published on the AWS Builder Center on 30 May 2026, kept as it was published. One thing has moved since: the AWS Marketplace listing is still awaiting publication, and the pricing decision landed on a **free** listing with no AWS pricing dimensions, so the AWS-metered path described below is built and deployed but not yet billing anyone. Every code sample is still the code that ships. For the current status see [aws-marketplace.md](#sec-123).
We run [three.ws](https://three.ws), an open-source platform for 3D AI agents and on-chain communities. Our paid API already had a billing system: **x402**, the HTTP-native pay-per-call protocol where a request to a metered endpoint either carries a subscription key or gets a `402 Payment Required`. That works great for developers who pay in stablecoins.
@@ -33142,7 +34550,7 @@ The product on the other side of all this plumbing is the platform: three.ws age
---
-<a id="sec-119"></a>
+<a id="sec-120"></a>
> **Source:** `docs/aws-builder-center-mcp-agents.md` · [↑ table of contents](#table-of-contents)
@@ -33258,7 +34666,7 @@ If you wire it into something, or you want to list a paid tool of your own, the
---
-<a id="sec-120"></a>
+<a id="sec-121"></a>
> **Source:** `docs/aws-builder-center.md` · [↑ table of contents](#table-of-contents)
@@ -33270,7 +34678,7 @@ This page is the index of that writing: what is published, where it lives, and w
- **Profile:** [builder.aws.com/community/@threews](https://builder.aws.com/community/@threews)
- **Account:** organization account, byline "three.ws"
-- **Related surfaces:** [three.ws/aws](https://three.ws/aws) (AWS Partner page), [AWS Marketplace listing](#sec-122), [AWS partner spotlight](#sec-123)
+- **Related surfaces:** [three.ws/aws](https://three.ws/aws) (AWS Partner page), [AWS Marketplace listing](#sec-123), [AWS partner spotlight](#sec-124)
## Published articles
@@ -33282,7 +34690,7 @@ Published 30 May 2026. Tags: `aws-payment-cryptography`, `blockchain`, `metadata
The full AWS Marketplace SaaS usage-based integration, end to end: `ResolveCustomer` on the fulfillment URL, `MeterUsage` and `BatchMeterUsage` for consumption reporting, `GetEntitlements` for tiered feature gating, and SNS lifecycle webhooks with real signature verification. It closes on the part nobody else writes about: bridging an AWS `CustomerIdentifier` into the same access check that already served an on-chain [x402](#sec-105) paywall, so one authorization path bills two economies.
-- **Source draft in this repo:** [aws-builder-center-marketplace-x402.md](#sec-118)
+- **Source draft in this repo:** [aws-builder-center-marketplace-x402.md](#sec-119)
- **Code it documents:** [`api/aws-marketplace/`](https://github.com/nirholas/three.ws/tree/main/api/aws-marketplace), [`api/_lib/aws-marketplace.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/aws-marketplace.js), [`api/_lib/aws-marketplace-bridge.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/aws-marketplace-bridge.js)
- **Announcement:** [three.ws Publishes on the AWS Builder Center Blog](https://three.ws/news/aws-builder-center-blog)
@@ -33294,7 +34702,7 @@ Published 27 June 2026. Tags: `ai`, `agent-toolkit`, `blockchain`, `aws-partners
The platform-level piece: browser-native 3D AI agents with memory, on-chain wallets, and autonomous payments, available on AWS Marketplace, embeddable in one line of HTML, and governed before they act. Written for AWS builders evaluating three.ws as an agent runtime rather than as a 3D asset tool.
-- **Surfaces it covers:** [the `<agent-3d>` web component](#sec-502), [agent wallets](#sec-072), [the agent system](#sec-064), [AWS Marketplace procurement](#sec-122)
+- **Surfaces it covers:** [the `<agent-3d>` web component](#sec-508), [agent wallets](#sec-072), [the agent system](#sec-064), [AWS Marketplace procurement](#sec-123)
## Published by AWS about three.ws
@@ -33308,7 +34716,7 @@ Published 26 June 2026 by Kelly Wu (AWS). Part of the AWS-run series "AWS Partne
A builder's guide to the agentic economy that uses the three.ws stack as its worked example throughout: the x402 handshake and its three layers, MCP as the distribution layer for agent capabilities, agent-to-agent payments, on-chain agent identity (ERC-8004 and the SPL skill licenses), agent tokens on the bonding curve, and 3D embodiment. It walks the hosted MCP servers, the `@three-ws/*` payment SDKs, and the FSI use cases for per-call data access, and closes on the open problems: payment streaming, automatic cross-chain routing, agent reputation as a credit primitive, and org-scale spend governance.
-- **Surfaces it covers:** [the MCP servers](#sec-276), [x402](#sec-105), [agent wallets](#sec-072), [the `<agent-3d>` web component](#sec-502)
+- **Surfaces it covers:** [the MCP servers](#sec-277), [x402](#sec-105), [agent wallets](#sec-072), [the `<agent-3d>` web component](#sec-508)
- **Canonical URL note:** the Builder Center strips digits from slugs, so `x402` becomes `x` and `3d` becomes `d` in the path. The URL above is the one AWS publishes in its own [sitemap](https://builder.aws.com/sitemaps/articles/2026-6.xml); a slug containing the digits also resolves, because the content ID is what routes.
## In draft
@@ -33317,8 +34725,8 @@ Written and reviewed in this repo, not yet submitted:
| Draft | Subject |
|---|---|
-| [aws-builder-center-agent-payment-sessions.md](#sec-117) | Agent Payment Sessions: giving an agent a budget instead of a private key, and enforcing it atomically in Postgres |
-| [aws-builder-center-mcp-agents.md](#sec-119) | An MCP server whose paid tools settle per call in USDC over HTTP 402 |
+| [aws-builder-center-agent-payment-sessions.md](#sec-118) | Agent Payment Sessions: giving an agent a budget instead of a private key, and enforcing it atomically in Postgres |
+| [aws-builder-center-mcp-agents.md](#sec-120) | An MCP server whose paid tools settle per call in USDC over HTTP 402 |
## Publishing checklist
@@ -33338,7 +34746,7 @@ The Builder Center is where AWS customers evaluating a partner product go lookin
---
-<a id="sec-121"></a>
+<a id="sec-122"></a>
> **Source:** `docs/aws-marketplace-listing-kit.md` · [↑ table of contents](#table-of-contents)
@@ -33347,16 +34755,17 @@ The Builder Center is where AWS customers evaluating a partner product go lookin
Paste-ready content and the exact step sequence to create the **AI agents & tools**
product in the AWS Marketplace Management Portal (AMMP). The backend integration
(register URL, SNS webhook, key issuance, account linking) is already built and
-deployed — see [aws-marketplace.md](#sec-122). This doc covers the
+deployed — see [aws-marketplace.md](#sec-123). This doc covers the
listing itself, which has not yet been created (the AMMP "AI agents & tools
products" page shows "No products to display").
-> **BLOCKER, verified 2026-08-02: the integration in this repo cannot serve a new
-> listing as written.** AWS stopped populating `CustomerIdentifier` for new SaaS
-> integrations, and all 51 references across 7 files key on it. Read
-> "Verified against AWS docs" and "Confirmed defects" at the bottom of this file
-> before touching the listing. Do not create the product expecting the backend to
-> work; it will fail the subscribe round-trip.
+> **Backend blockers cleared 2026-08-17.** The four defects that would have failed
+> the subscribe round-trip (identity keyed on the retired `CustomerIdentifier`,
+> the orphan SNS topic pin, hardcoded SHA1 SNS verification, and the missing
+> EventBridge transport) are fixed and covered by tests. The listing is now
+> gated only on AWS-console work and Seller Operations review. The evidence
+> behind each fix is in "Verified against AWS docs" and "Defects and their
+> fixes" at the bottom of this file.
- **Seller account:** three-ws @ 155407237916
- **Delivery method:** API-based (SaaS fulfillment) — **not** container/Bedrock
@@ -33371,11 +34780,10 @@ products" page shows "No products to display").
current EULA ("offered free of charge through AWS Marketplace") and clears AWS review
fastest (no tax/bank/dimension interview).
-> Note: `docs/aws-marketplace.md` and the unused `AWS_MP_METERING_DIMENSION` /
-> `AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE` env references describe an earlier
-> AWS-metered-billing plan. That is superseded: billing is x402-per-call, not AWS-metered.
-> Reconcile `docs/aws-marketplace.md` so it stops promising per-call/per-agent-minute AWS
-> billing.
+> `AWS_MP_METERING_DIMENSION` and `AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE` remain in
+> the code for a future usage-priced listing. Both are inert while the dimension
+> is unset, which is the correct state for a free listing. [aws-marketplace.md](#sec-123)
+> documents them as optional rather than as the billing model.
---
@@ -33384,30 +34792,38 @@ products" page shows "No products to display").
This codespace has no AWS credentials, so these must be run on a machine with
admin creds on account 155407237916.
-### 1. Provision the IAM user (the SNS half of the script is dead weight)
+### 1. Provision the IAM user and the EventBridge relay
```bash
./scripts/aws-marketplace-provision.sh
```
-**The SNS topic this script creates is NOT the topic AMMP wants, and there is no
-field in the SaaS wizard to paste it into.** AWS Marketplace creates and owns the
-notification topics and hands you the ARN *during product creation*, in the form
-`arn:aws:sns:us-east-1:<aws-owned-account>:aws-mp-subscription-notification-<PRODUCTCODE>`.
-You subscribe to that topic afterwards; you never supply your own. Ignore the
-script's `AWS_MP_SNS_TOPIC_ARN` output. See
-[Amazon SNS notifications for SaaS products](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-notification.html).
+It creates, idempotently:
-What the script is genuinely needed for is the IAM user: `resolveCustomer()` in
-`api/_lib/aws-marketplace.js` calls `aws-marketplace:ResolveCustomer`, and without
-those keys every subscribe redirect dies at `/aws-marketplace/error?reason=token_expired`.
+- the IAM user `three-ws-marketplace` plus the four marketplace actions and an
+ access key. `resolveCustomer()` in `api/_lib/aws-marketplace.js` calls
+ `aws-marketplace:ResolveCustomer`; without those keys every subscribe redirect
+ dies at `/aws-marketplace/error?reason=token_expired`.
+- an EventBridge **connection** holding a generated shared secret, an **API
+ destination** pointing at `https://three.ws/api/aws-marketplace/subscription`,
+ an IAM role EventBridge assumes to invoke it, an SQS dead-letter queue, and a
+ **rule** on the default event bus matching `source: aws.agreement-marketplace`.
+
+The relay is required because lifecycle events for a new listing arrive on
+EventBridge, which cannot POST to an external HTTPS endpoint directly. **The
+seller never supplies an SNS topic ARN**, and there is no field in the SaaS
+wizard for one: AWS creates and owns the notification topics and hands them over
+on the product overview page *after* product creation, in the form
+`arn:aws:sns:us-east-1:<aws-owned-account>:aws-mp-subscription-notification-<PRODUCTCODE>`.
+See [Amazon SNS notifications for SaaS products](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-notification.html).
-Take `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`, and `AWS_MP_REGION` and set
-them on the Cloud Run service (production env lives there, not Vercel):
+Take `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`, `AWS_MP_REGION`, and
+`AWS_MP_EVENT_SECRET` and set them on the Cloud Run service (production env lives
+there, not Vercel):
```bash
gcloud run services update three-ws-api --region us-central1 \
- --update-env-vars AWS_MP_ACCESS_KEY_ID=…,AWS_MP_SECRET_ACCESS_KEY=…,AWS_MP_REGION=…
+ --update-env-vars AWS_MP_ACCESS_KEY_ID=…,AWS_MP_SECRET_ACCESS_KEY=…,AWS_MP_REGION=us-east-1,AWS_MP_EVENT_SECRET=…
```
(`--update-env-vars` merges. Never use `--set-env-vars` here: it replaces the entire
@@ -33415,6 +34831,14 @@ env set and would wipe every other production variable.)
`AWS_MP_PRODUCT_CODE` is assigned by AMMP after the product is created — add it last.
+### 1b. Apply the schema migration
+
+The Concurrent Agreements re-key ships as
+`api/_lib/migrations/20260817120000_aws_marketplace_concurrent_agreements.sql`.
+Preview with `npm run db:status`, then `npm run db:migrate` (which applies every
+pending migration immediately, with no dry run). `npm run deploy:gcp:submit`
+refuses to submit while it is pending, so this cannot be skipped by accident.
+
### 2. EULA: pick Standard Contract and skip this entirely (recommended)
The AMMP wizard accepts either the **Standard Contract for AWS Marketplace (SCMP)**
@@ -33539,44 +34963,47 @@ The free AWS subscription only grants the x402 access key.
| AMMP field | Value |
|---|---|
| Fulfillment / SaaS URL (Registration URL) | `https://three.ws/api/aws-marketplace/register` |
-| SNS notification topic ARN | Not a field you fill in. AWS hands you `aws-mp-subscription-notification-<PRODUCTCODE>` after the product is created; subscribe to it then. |
+| SNS notification topic ARN | Not a field you fill in. AWS hands you the notification configuration on the product overview page after the product is created. |
| EULA | **Standard Contract (SCMP)**: recommended, zero setup. Custom EULA only if the S3 copy returns 200 (see prereq #2). |
| Post-subscribe redirect | `https://three.ws/aws-marketplace/welcome` (handled by register.js) |
-Lifecycle events land on `POST /api/aws-marketplace/subscription` (SNS webhook —
-already deployed; handles subscribe-success, unsubscribe-success, subscribe-fail,
-entitlement-updated, and the SubscriptionConfirmation handshake).
+Lifecycle events land on `POST /api/aws-marketplace/subscription`, which is
+deployed and accepts both transports: EventBridge agreement/license events
+relayed through the API destination (the path a new listing uses), and legacy
+signed SNS notifications with the SubscriptionConfirmation handshake.
---
## Step sequence in AMMP
-Nothing in steps 2-7 depends on the IAM keys, so if creds are slow to arrive, start
-the wizard anyway and backfill the env vars before the round-trip test in step 9.
+Nothing in steps 3-8 depends on the IAM keys, so if creds are slow to arrive, start
+the wizard anyway and backfill the env vars before the round-trip test in step 10.
-1. Run prereq #1; set `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`, and
- `AWS_MP_REGION` on the Cloud Run service.
-2. AMMP → **AI agents & tools products** → **Create AI agents & tools product**.
-3. Delivery method: **API-based** (SaaS). (Until you finish the wizard the draft may
+1. Run prereq #1; set `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`,
+ `AWS_MP_REGION`, and `AWS_MP_EVENT_SECRET` on the Cloud Run service.
+2. Run prereq #1b (`npm run db:status`, then `npm run db:migrate`) and deploy, so
+ production is serving the re-keyed schema before any buyer can reach it.
+3. AMMP → **AI agents & tools products** → **Create AI agents & tools product**.
+4. Delivery method: **API-based** (SaaS). (Until you finish the wizard the draft may
appear under **SaaS products**, per AMMP's own note — that's expected.)
-4. Fill product detail fields from the "Listing fields" section above; upload the logo.
-5. Pricing: choose **Free**.
-6. Fulfillment: paste the Registration URL from the table. There is no SNS field here.
-7. EULA: select **Standard Contract**.
-8. Save → AMMP assigns a **Product Code** and gives you the two `aws-mp-*` SNS topic
- ARNs. Set `AWS_MP_PRODUCT_CODE` on the Cloud Run service. No rebuild is needed:
- `gcloud run services update three-ws-api --region us-central1 --update-env-vars
- AWS_MP_PRODUCT_CODE=…` cuts a new revision on its own.
-9. Wire notifications per what the product overview page actually shows. For a new
- listing expect **EventBridge**, not SNS (see Defect 4 below): create a rule on the
- default event bus in seller account 155407237916 matching
- `source: aws.agreement-marketplace`, with an API destination targeting
- `https://three.ws/api/aws-marketplace/subscription`, and make that handler parse
- EventBridge event JSON. Only if AWS also issues the legacy
- `aws-mp-subscription-notification-<PRODUCTCODE>` topic, add an HTTPS subscription
- to it as a secondary leg. Then run one end-to-end
- subscribe → redirect → welcome → issue-key test while the product is **limited**.
-10. Once the private round-trip works, **Request changes → Update visibility →
+5. Fill product detail fields from the "Listing fields" section above; upload the logo.
+6. Pricing: choose **Free**.
+7. Fulfillment: paste the Registration URL from the table. There is no SNS field here.
+8. EULA: select **Standard Contract**.
+9. Save → AMMP assigns a **Product Code** and shows the notification configuration
+ on the product overview page. Set `AWS_MP_PRODUCT_CODE` on the Cloud Run service.
+ No rebuild is needed: `gcloud run services update three-ws-api --region
+ us-central1 --update-env-vars AWS_MP_PRODUCT_CODE=…` cuts a new revision on its own.
+10. Confirm the notification wiring against what that page actually shows. The
+ EventBridge rule from prereq #1 already matches every
+ `source: aws.agreement-marketplace` event, so a new listing needs nothing
+ further. Only if AWS also issues the legacy
+ `aws-mp-subscription-notification-<PRODUCTCODE>` topic, set
+ `AWS_MP_SNS_TOPIC_ARN` to **that** ARN and add an HTTPS subscription to
+ `https://three.ws/api/aws-marketplace/subscription` as a secondary leg. Then
+ run one end-to-end subscribe → redirect → welcome → issue-key test from a test
+ AWS account while the product is **limited**.
+11. Once the private round-trip works, **Request changes → Update visibility →
Public**. This one needs AWS Marketplace Seller Operations approval, so it is the
step with real calendar time on it. Everything before it is same-day.
@@ -33585,16 +35012,34 @@ the wizard anyway and backfill the env vars before the round-trip test in step 9
## What is and isn't done
Done (in repo, deployed):
-- Registration URL, SNS webhook, key issuance, account linking endpoints.
-- `aws_marketplace_customers` schema + x402 bridge.
-- EULA HTML, S3 publish script, SNS/IAM provision script.
+- Registration URL, lifecycle webhook (EventBridge + legacy SNS), key issuance,
+ account linking endpoints.
+- `aws_marketplace_customers` schema, re-keyed onto `LicenseArn` for Concurrent
+ Agreements, plus the x402 bridge.
+- EULA HTML, S3 publish script, IAM + EventBridge provision script.
- Welcome onboarding page.
+- Test coverage for the event mapping, the relay secret, the ambiguity guard, the
+ metering call shape, and SNS SignatureVersion 1 and 2.
Not done (requires AWS console / seller creds — cannot be done from this repo):
- Running the provision + EULA-publish scripts (no AWS CLI/creds in codespace).
-- Publishing the S3 EULA (currently 404 — never uploaded).
+- Publishing the S3 EULA (currently 404, never uploaded; unnecessary if you pick
+ the Standard Contract).
- Creating the product in the AMMP wizard (manual web UI).
- Obtaining and wiring `AWS_MP_PRODUCT_CODE`.
+- The limited-visibility round-trip test and the public-visibility request.
+
+## Calendar
+
+There is no same-day path to a public AWS Marketplace URL. Plan against this:
+
+| Day | Step | Owner |
+|---|---|---|
+| 1 | Prereqs 1 + 1b, deploy, create the product, save the draft | us |
+| 1 | Product code lands, env var set, revision cuts | us |
+| 1-2 | Limited-visibility round-trip test from a test AWS account | us |
+| 2 | Request public visibility | us |
+| +7-10 business days | Seller Operations review and publish | AWS |
---
@@ -33658,36 +35103,44 @@ and [saas-eventbridge-integration](https://docs.aws.amazon.com/marketplace/lates
events are delivered to the seller's **default event bus** in their own AWS account
with `source: aws.agreement-marketplace`. Targets are AWS resources (Lambda, Step
Functions, API Gateway). An external HTTPS webhook needs an EventBridge rule plus an
-API destination to relay to it. `api/aws-marketplace/subscription.js` is an SNS HTTPS
-webhook and cannot be an EventBridge target as written.
+API destination to relay to it. That relay is what
+`scripts/aws-marketplace-provision.sh` now creates, and
+`api/aws-marketplace/subscription.js` parses both envelope shapes.
---
-## Confirmed defects (fix before the listing goes anywhere)
+## Defects and their fixes (all four closed 2026-08-17)
+
+**Defect 1 (critical, listing-breaking): the identity model was keyed on a field AWS
+no longer sends.** `resolveCustomer()` read `result.CustomerIdentifier` and discarded
+`LicenseArn` entirely; `register.js` used it as the `ON CONFLICT` key; `subscription.js`
+returned 400 `missing_customer_identifier` without it. On a new listing every subscribe
+died at the first insert.
+
+*Fixed:* `resolveCustomer()` returns `licenseArn` and `customerAWSAccountId` alongside
+the legacy field. `api/_lib/aws-marketplace-store.js` is the single place that knows how
+a buyer is identified, keying on `license_arn` (unique) with `agreement_id` as a
+correlation key and `customer_identifier` kept nullable for a legacy row. Migration
+`20260817120000_aws_marketplace_concurrent_agreements.sql` carries the schema, including
+re-pointing the metering audit table's foreign key off the now-nullable column. The
+browser handle became the row id, so no license ARN reaches a URL.
-**Defect 1 (critical, listing-breaking): the identity model is keyed on a field AWS
-no longer sends.** `resolveCustomer()` in `api/_lib/aws-marketplace.js` reads
-`result.CustomerIdentifier` and discards `LicenseArn` entirely. `register.js` uses it
-as the `ON CONFLICT` key. `subscription.js` returns 400 `missing_customer_identifier`
-without it. 51 references across 7 files: `aws-marketplace.js`,
-`aws-marketplace-bridge.js`, `x402-subscriptions.js`, `issue-key.js`, `register.js`,
-`subscription.js`, `link.js`. On a new listing every subscribe dies at the first
-insert. Fix: return and persist `LicenseArn` + `CustomerAWSAccountId`, key on those,
-keep `customer_identifier` nullable for any legacy row.
+**Defect 2 (critical, silent): the SNS topic guard rejected every real notification.**
+The old provision script emitted a *self-created* topic ARN for `AWS_MP_SNS_TOPIC_ARN`.
+Set as the old docs instructed, every genuine AWS notification failed the pin and
+returned 403, visible only in logs.
-**Defect 2 (critical, silent): the SNS topic guard rejects every real notification.**
-`verifySnsMessage()` compares `msg.TopicArn` against `env.AWS_MP_SNS_TOPIC_ARN`. The
-provision script emits the *self-created* topic ARN for that variable. Set it as the
-old docs instructed and every genuine AWS notification fails the check and returns 403,
-with the cause visible only in logs. Fix: set that var to the AWS-issued
-`aws-mp-subscription-notification-<PRODUCTCODE>` ARN, or leave it unset (the guard is
-skipped when empty) until the real ARN is known.
+*Fixed:* the script no longer creates that topic, and both this file and
+[aws-marketplace.md](#sec-123) state that the variable takes the AWS-issued
+`aws-mp-subscription-notification-<PRODUCTCODE>` ARN or nothing at all.
-**Defect 3 (latent): SNS signature verification hardcodes SHA1.**
-`verifySnsMessage()` always does `createVerify('SHA1')` and never reads
-`msg.SignatureVersion`. AWS SNS SignatureVersion 2 signs with SHA256. On a
-SignatureVersion 2 topic every message fails verification and returns 403. Fix: branch
-on `msg.SignatureVersion` (`'2'` implies SHA256, otherwise SHA1).
+**Defect 3 (latent): SNS signature verification hardcoded SHA1.**
+`verifySnsMessage()` always did `createVerify('SHA1')` and never read
+`msg.SignatureVersion`, so every message from a SignatureVersion 2 topic (SHA256)
+failed verification with an error that reads exactly like a forgery.
+
+*Fixed:* the digest follows `msg.SignatureVersion`. Both versions are covered in
+`tests/api/aws-marketplace-sns.test.js`, including a tampered version 2 message.
**Defect 4 (critical, transport-level): the SNS webhook is the wrong transport for a
new listing.** The [Concurrent Agreements upgrade guide](https://aws.amazon.com/blogs/awsmarketplace/complete-guide-to-upgrading-your-saas-product-to-aws-marketplace-concurrent-agreements/)
@@ -33699,16 +35152,37 @@ of the seller AWS account** (155407237916), not on an HTTPS URL. Reaching
resources: an EventBridge rule matching `source: aws.agreement-marketplace` plus an
API destination (connection + auth) targeting our endpoint, and the endpoint must
parse EventBridge event JSON, not SNS envelopes. `subscription.js` as written
-(SNS envelope parse, SNS signature verify, SubscribeURL handshake) never fires on a
-new listing. Defects 2 and 3 (topic-ARN guard, SHA1) remain real but only matter for
-the legacy SNS path; the primary fix is the EventBridge leg.
-`scripts/aws-marketplace-provision.sh` should provision the rule + API destination
-instead of the orphan SNS topic. Still verify against the product overview page at
-creation time (`saas-create-product` says the EventBridge configuration appears there).
+(SNS envelope parse, SNS signature verify, SubscribeURL handshake) would never have
+fired on a new listing.
+
+*Fixed:* `subscription.js` detects the envelope shape and routes to the right handler,
+so the same URL serves either transport and a listing migrated between them needs no
+code change. `parseMarketplaceEvent()` maps every documented detail-type onto the
+action the listing takes, stripping the `- Manufacturer` / `- Proposer` role suffix
+(we are both). `scripts/aws-marketplace-provision.sh` provisions the connection, API
+destination, IAM role, dead-letter queue, and rule instead of the orphan SNS topic.
+
+Two things the relay forced, both worth knowing:
+
+- **The relay needs its own authentication.** An API destination delivery is an
+ ordinary HTTPS POST with no AWS signature on it. The connection attaches
+ `x-three-ws-marketplace-secret`, checked in constant time against
+ `AWS_MP_EVENT_SECRET`; an unset secret refuses EventBridge deliveries outright.
+ Without it, anyone who found the URL could revoke a paying buyer's key with a
+ forged `Purchase Agreement Ended`.
+- **An end event can be ambiguous, and guessing is worse than doing nothing.**
+ Agreement events carry no license ARN, and under Concurrent Agreements one AWS
+ account can hold several live agreements for the same product. When resolution
+ falls back to the acceptor's account id and matches more than one row, the handler
+ logs and revokes nothing. Retrying cannot add information, so it answers 200 rather
+ than looping the relay into the dead-letter queue.
+
+Still verify against the product overview page at creation time
+(`saas-create-product` says the EventBridge configuration appears there).
---
-<a id="sec-122"></a>
+<a id="sec-123"></a>
> **Source:** `docs/aws-marketplace.md` · [↑ table of contents](#table-of-contents)
@@ -33716,7 +35190,7 @@ creation time (`saas-create-product` says the EventBridge configuration appears
three.ws is a verified AWS Partner. The AWS Marketplace product is an API-based (SaaS) listing, and the AWS subscription is a **free front door**: subscribing links your AWS account to a three.ws account and issues an x402 access key. Actual usage is then paid per-call in USDC over the x402 / HTTP 402 protocol, the same as every other x402 endpoint. AWS Marketplace itself does not meter or bill usage.
-> **Listing status (checked 2026-08-15): not yet public.** Every endpoint described below is built and deployed, but the product has not been created in the AWS Marketplace Management Portal, so there is nothing to subscribe to on the AWS side yet. The Marketplace credentials (`AWS_MP_*`) are correspondingly unset in production, so `POST /api/aws-marketplace/subscription` answers `503 not_configured` today. The remaining steps are AWS-console work and Seller Operations approval, tracked in [aws-marketplace-listing-kit.md](#sec-121). Until then, use x402 directly: no AWS subscription is required to call `/api/x402/*`.
+> **Listing status (checked 2026-08-17): not yet public.** The integration is built, deployed, and now conforms to the Concurrent Agreements requirements AWS made mandatory for new SaaS products on 2026-06-01, but the product has not been created in the AWS Marketplace Management Portal, so there is nothing to subscribe to on the AWS side yet. The Marketplace credentials (`AWS_MP_*`) are correspondingly unset in production, so `POST /api/aws-marketplace/subscription` answers `503 not_configured` today. The remaining steps are AWS-console work and Seller Operations approval, tracked in [aws-marketplace-listing-kit.md](#sec-122). Until then, use x402 directly: no AWS subscription is required to call `/api/x402/*`.
## Subscribing via AWS Marketplace
@@ -33724,7 +35198,7 @@ This is the flow once the listing is public.
1. Find the three.ws listing on [AWS Marketplace](https://aws.amazon.com/marketplace).
2. Choose **Subscribe** — the AWS Marketplace subscription is free.
-3. After confirming in AWS, you are redirected to `https://three.ws/aws-marketplace/welcome` to complete account setup.
+3. Choose **Set up your account**. AWS POSTs a short-lived registration token to `https://three.ws/api/aws-marketplace/register`, which exchanges it for your license and redirects you to `https://three.ws/aws-marketplace/welcome`.
4. If you already have a three.ws account, sign in and your AWS subscription is linked automatically.
5. Once linked, the welcome page issues your x402 access key so you can start calling `/api/x402/*` immediately.
@@ -33732,50 +35206,76 @@ This is the flow once the listing is public.
The AWS Marketplace subscription is free: there are no AWS pricing dimensions, no contract, and no AWS-side metering. Usage is paid per-call in USDC via x402 (HTTP 402): every call returns a structured 402 challenge, your wallet or facilitator pays in USDC, and the request retries automatically. This is identical to how a non-AWS caller pays, so there is nothing to reconcile on your AWS invoice.
+## How a buyer is identified
+
+This matters if you are reading the code, because AWS changed the answer and the old answer is still all over the internet.
+
+For a **new** SaaS integration, `ResolveCustomer` no longer populates `CustomerIdentifier`. It returns `LicenseArn` and `CustomerAWSAccountId`, and the license ARN is the per-grant identity ([ResolveCustomer API reference](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_ResolveCustomer.html)). Under **Concurrent Agreements** one AWS account can hold several simultaneous agreements for the same product, so the buyer's AWS account id alone does not identify a subscription and is never used as a key.
+
+The record in `aws_marketplace_customers` therefore carries all of `license_arn` (unique), `agreement_id`, `customer_aws_account_id`, and a nullable legacy `customer_identifier`. The handle passed to the browser on `/aws-marketplace/welcome?customer=…` is the row's own id, not the license ARN: a grant identifier does not belong in a URL that lands in browser history, referrer headers, and access logs.
+
## AWS account
-The AWS Marketplace seller account for three.ws is `155407237916` (`us-east-1`), which hosts the Marketplace integration — the SNS subscription topic, the ResolveCustomer/entitlement bridge, and the EULA. The platform's own production runtime runs on Google Cloud Run (service `three-ws-api`, region `us-central1`); see [ops/gcp-production.md](ops/gcp-production.md) for the hosting runbook.
+The AWS Marketplace seller account for three.ws is `155407237916` (`us-east-1`), which hosts the Marketplace integration: the IAM user for the metering APIs, the EventBridge relay for lifecycle events, and the EULA. The platform's own production runtime runs on Google Cloud Run (service `three-ws-api`, region `us-central1`); see [ops/gcp-production.md](ops/gcp-production.md) for the hosting runbook.
-## For Developers: Marketplace Integration Endpoints
+## For developers: Marketplace integration endpoints
If you are integrating three.ws programmatically after subscribing via AWS Marketplace, the relevant API endpoints are:
| Endpoint | Purpose |
|---|---|
-| `POST /api/aws-marketplace/register` | Registration URL — receives the Marketplace token, resolves the customer, and starts onboarding |
-| `POST /api/aws-marketplace/subscription` | SNS webhook — receives subscription lifecycle events from AWS |
-| `POST /api/aws-marketplace/link` | Attaches your resolved AWS customer record to your signed-in three.ws account. Called by the welcome page; requires a session cookie. |
+| `POST /api/aws-marketplace/register` | Registration URL. Receives the Marketplace token, resolves the license, and starts onboarding |
+| `POST /api/aws-marketplace/subscription` | Lifecycle webhook. Receives EventBridge agreement/license events (and legacy SNS notifications) |
+| `POST /api/aws-marketplace/link` | Attaches your resolved AWS subscription record to your signed-in three.ws account. Called by the welcome page; requires a session cookie. |
| `POST /api/aws-marketplace/issue-key` | Mints (or returns) the x402 API key for your linked subscription. The plaintext key is returned once, on first issue. |
-`register` and `subscription` are called automatically by AWS during the subscription flow; you do not need to call them directly. `link` and `issue-key` are called by the welcome page on your behalf once you sign in.
+`register` and `subscription` are called by AWS during and after the subscription flow; you do not call them directly. `link` and `issue-key` are called by the welcome page on your behalf once you sign in.
-Both `link` and `issue-key` require an active session and refuse a subscription that belongs to someone else, so a given AWS customer record can only ever be attached to one three.ws account:
+Both `link` and `issue-key` require an active session and refuse a subscription that belongs to someone else, so a given AWS subscription can only ever be attached to one three.ws account:
| Status | Meaning |
|---|---|
| `401 unauthenticated` | No valid session cookie. Sign in, then retry. |
| `403 customer_linked_to_other_account` | This AWS subscription is already attached to a different three.ws account. |
-| `404 customer_not_found` | The customer identifier is unknown. Re-open the setup link from AWS Marketplace. |
+| `404 customer_not_found` | The subscription record is unknown. Re-open the setup link from AWS Marketplace. |
| `409 subscription_inactive` | The AWS subscription is cancelled or expired. Re-subscribe in AWS Marketplace first. |
+## Lifecycle notifications
+
+New listings receive lifecycle events on **Amazon EventBridge**, not SNS. AWS Marketplace delivers agreement and license events to the seller account's default event bus with `source: aws.agreement-marketplace`, and SNS does not carry the `LicenseArn` these events are keyed on. EventBridge cannot POST to an external HTTPS endpoint on its own, so an EventBridge rule targets an **API destination** that relays to `https://three.ws/api/aws-marketplace/subscription`. `scripts/aws-marketplace-provision.sh` creates the connection, destination, IAM role, dead-letter queue, and rule.
+
+| Event | Effect |
+|---|---|
+| `Purchase Agreement Created` / `Amended` | Record the agreement; open a pending record if the buyer has not registered yet |
+| `License Updated` | Attach the license ARN to the buyer's record |
+| `Purchase Agreement Ended` | Revoke the x402 key and mark the record cancelled |
+| `License Deprovisioned` | Revoke the x402 key and mark the record cancelled |
+
+The webhook **refuses to guess**. If an end event only identifies the buyer's AWS account and that account holds more than one live agreement for the product, it logs the ambiguity and revokes nothing, because revoking the wrong one cuts off access a buyer is still paying for. Retrying cannot add information, so it answers `200` rather than looping the relay.
+
+The legacy SNS transport is still accepted for an existing integration: `subscribe-success`, `unsubscribe-success`, `subscribe-fail`, and `entitlement-updated`, with full signature verification against the AWS-issued topic.
+
### Operator configuration
The integration reads its AWS credentials from the environment and ships inert without them: nothing fabricates an entitlement AWS did not grant.
| Variable | Required | Purpose |
|---|---|---|
-| `AWS_MP_ACCESS_KEY_ID` | Yes | Credentials for ResolveCustomer, MeterUsage, and GetEntitlements. |
+| `AWS_MP_ACCESS_KEY_ID` | Yes | Credentials for ResolveCustomer, BatchMeterUsage, and GetEntitlements. |
| `AWS_MP_SECRET_ACCESS_KEY` | Yes | Paired secret for the above. |
| `AWS_MP_PRODUCT_CODE` | Yes | Product code from the Marketplace listing. |
-| `AWS_MP_SNS_TOPIC_ARN` | Yes, for the webhook | The Marketplace SNS topic. `POST /api/aws-marketplace/subscription` answers `503 not_configured` until it is set. |
+| `AWS_MP_EVENT_SECRET` | Yes, for the webhook | Shared secret the EventBridge API destination attaches as `x-three-ws-marketplace-secret`. `POST /api/aws-marketplace/subscription` answers `503 not_configured` for EventBridge deliveries until it is set. |
+| `AWS_MP_SNS_TOPIC_ARN` | Only for the legacy SNS leg | The AWS-issued `aws-mp-subscription-notification-<PRODUCTCODE>` topic. Never a self-created topic. |
| `AWS_MP_REGION` | No (default `us-east-1`) | Region for the Marketplace API clients. |
-| `AWS_MP_METERING_DIMENSION` | No | Set for a usage-based listing to report MeterUsage per granted call. Leave unset for a contract listing. |
+| `AWS_MP_METERING_DIMENSION` | No | Set for a usage-based listing to report BatchMeterUsage per granted call. Leave unset for a free or contract listing. |
| `AWS_MP_ENTITLEMENT_REQUIRED` | No | Set truthy on a contract listing to gate key issuance on a live GetEntitlements check. |
| `AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE` | No (default `600`) | Rate limit stamped on issued keys. Override per offer with `AWS_MP_RATE_LIMIT_<OFFER_ID>`. |
-**`AWS_MP_SNS_TOPIC_ARN` is not optional in practice.** A valid SNS signature only proves that some AWS account signed the message: anyone can create an SNS topic in their own account and have AWS sign a notification for it. The topic ARN is what binds the webhook to this listing, so without it a forged `subscribe-success` could mint a free API key and a forged `unsubscribe-success` could revoke a paying customer's. The handler therefore refuses delivery outright rather than trusting an unpinned topic. SNS retries with backoff, so notifications that arrive during a misconfiguration are redelivered once the variable is set.
+**`AWS_MP_EVENT_SECRET` is what authenticates the EventBridge relay.** An API destination delivery is an ordinary HTTPS POST; the header the connection attaches is the only thing distinguishing it from an anonymous caller who found the URL. Without that check a forged `Purchase Agreement Ended` could revoke a paying buyer's key. The handler therefore refuses EventBridge deliveries outright while the secret is unset, and compares it in constant time when it is. EventBridge retries with backoff and dead-letters to SQS, so deliveries that arrive during a misconfiguration are recoverable.
+
+**`AWS_MP_SNS_TOPIC_ARN` plays the same role for the legacy leg.** A valid SNS signature only proves that some AWS account signed the message: anyone can create an SNS topic in their own account and have AWS sign a notification for it. The topic ARN is what binds the webhook to this listing, so the handler refuses SNS delivery outright rather than trusting an unpinned topic. Signature verification follows the message's `SignatureVersion` (version 2 topics sign with SHA256, version 1 with SHA1).
-If the registration URL is hit while the AWS credentials are missing, the customer is redirected to `/aws-marketplace/error?reason=not_configured` (not `token_expired`) and the missing variables are named in the server log.
+If the registration URL is hit while the AWS credentials are missing, the customer is redirected to `/aws-marketplace/error?reason=not_configured` (not `token_expired`) and the missing variables are named in the server log. If AWS resolves the token but returns no usable identity at all, the redirect reason is `unresolved_customer` and no record is written: an unkeyed record would grant access we could never revoke.
## Support
@@ -33785,7 +35285,7 @@ For platform support, open an issue at [github.com/nirholas/three.ws/issues](htt
---
-<a id="sec-123"></a>
+<a id="sec-124"></a>
> **Source:** `docs/aws-partner-spotlight.md` · [↑ table of contents](#table-of-contents)
@@ -33876,12 +35376,350 @@ One product. Two ways in. One authorization path.
**Learn more**
- Platform: [three.ws](https://three.ws)
-- AWS Marketplace and procurement: [three.ws/docs/aws-marketplace](#sec-122)
-- How agents reach and pay for tools: [three.ws/docs/x402](#sec-519), [three.ws/docs/mcp](#sec-276)
+- AWS Marketplace and procurement: [three.ws/docs/aws-marketplace](#sec-123)
+- How agents reach and pay for tools: [three.ws/docs/x402](#sec-544), [three.ws/docs/mcp](#sec-277)
---
-<a id="sec-124"></a>
+<a id="sec-125"></a>
+
+> **Source:** `docs/big-tech-recognition-week.md` · [↑ table of contents](#table-of-contents)
+
+# Big-tech recognition: the dispatch week of 2026-08-17
+
+The goal for this week is a published mention of three.ws by a major technology
+company: on their own website, in their own directory, or from their own social
+account.
+
+This doc is the cross-vendor dispatch board. Every other outreach doc in `docs/`
+is one vendor deep ([nvidia-visibility-map.md](#sec-300),
+[partners.md](#sec-318), [listings.md](#sec-265),
+[aws-marketplace.md](#sec-123), [ibm.md](#sec-250)). This one is the
+only place that ranks all of them against each other by the single question that
+matters this week: **what is the probability of a published big-tech mention
+within seven days, and what exactly is standing in the way?**
+
+Compiled 2026-08-17 (Monday). Statuses were read from the source of truth for
+each surface, not restated from memory. See [Verification log](#verification-log).
+
+---
+
+## The finding that should reorder the week
+
+**Nothing on this board is blocked on strategy, research, capability, or
+approval from a big tech company. Six surfaces are sitting at
+`ready-to-submit`, and each one is blocked on a single human action that takes
+minutes.**
+
+The submission tracker
+([`prompts/store-submissions/_generated/TRACKER.md`](../prompts/store-submissions/_generated/TRACKER.md))
+carries the OpenAI App Directory at `ready-to-submit` with exactly one open item:
+`[HUMAN: final submit in the partner portal / App Directory flow]`. The package is
+finalized, the OpenAI Partner Network accepted us on 2026-07-14, the organization
+is identity-verified, the GPT Store listing is already live and public, and the
+free connector was re-verified against production. The Official MCP Registry is in
+the same shape: the `mcp-publisher` commands are staged and the only blocker
+recorded is operator approval. The NVIDIA Inception request email is written,
+addressed, and its own doc says `**Sent:** not yet sent`.
+
+This is not a pipeline problem. It is a dispatch problem. The company has been
+building and researching the surfaces instead of firing them.
+
+The second finding, which follows from the first:
+
+**Big tech does not discover you on X. They reshare you on X after you are
+already on their property.** Every big-tech relationship three.ws holds came from
+joining the program and then publishing on the company's own developer surface.
+There are four such publications live right now (one AWS Builder Center article,
+one IBM Community blog post, two NVIDIA Developer Forums posts), and all four were
+self-serve. That is a proven, repeatable, gatekeeper-free channel that the company
+stopped using. Treat the X mention as the downstream effect, not the campaign.
+
+---
+
+## Tier 1: dispatch this week
+
+Ranked by expected value, which is payoff multiplied by the honest probability of
+landing inside seven days. Every row here is self-serve or already accepted, and
+none of them waits on a decision from the other company.
+
+| # | Surface | What a win looks like | Blocked on | Effort |
+|---|---|---|---|---|
+| 1 | **OpenAI App Directory** | three.ws listed inside ChatGPT, on OpenAI's own surface | One portal submit. Package finalized. | Minutes |
+| 2 | **NVIDIA Developer Forums, post 3** | Published on `forums.developer.nvidia.com`, NVIDIA's domain, same day | The post is not written. See [The one asset to write](#the-one-asset-to-write). | Half a day |
+| 3 | **AWS Builder Center, article 2** | Published on `builder.aws.com`, 5M monthly visitors | Draft exists but is the wrong genre. See note below. | Hours |
+| 4 | **Official MCP Registry** | Listed in Anthropic's registry | Operator approval to run the staged publish | Minutes |
+| 5 | **IBM Community blog, post 2** | Published on `community.ibm.com` under the existing author account | No post drafted | Hours |
+| 6 | **Claude plugin marketplace** | Listed in Anthropic's plugin directory | One submit at `platform.claude.com/plugins/submit` | Minutes |
+
+### 1. OpenAI App Directory (highest payoff on the board)
+
+This is the single most valuable item in this document and it is one action away.
+
+An App Directory listing puts three.ws in front of ChatGPT's user base on OpenAI's
+own product surface. Nothing else on this board reaches that audience. The
+submission target is the free keyless connector at
+`https://three.ws/api/mcp-studio` plus its inline widget and the custom-GPT
+Actions surface, all of which are live and re-verified.
+
+- **Package:** [`prompts/store-submissions/_generated/openai-submission.md`](../prompts/store-submissions/_generated/openai-submission.md) (7/7 policy PASS, real screenshots, real captured tool responses)
+- **Pre-submission verification pack:** [`docs/openai-pr/00-START-HERE.md`](#sec-306), with task 07 as the go/no-go gate
+- **Standing status:** Partner Network accepted 2026-07-14; organization verified; GPT Store listing live and public
+- **Open item:** the final submit in the partner portal
+
+Before the submit, run [`docs/openai-pr/07-final-verification-and-submit.md`](#sec-313) against the currently deployed
+revision. Its checklist exists precisely because the answer sheet asserts
+"verified live" facts dated 2026-07-14 and deployments move. That is a
+one-session job, not a blocker.
+
+### 2. NVIDIA Developer Forums, post 3
+
+The only NVIDIA channel with a proven track record, self-serve, and it publishes
+on NVIDIA's own domain. Two posts, both live, both landed:
+
+- [How Nemotron made three.ws text-to-3D pipeline usable](https://forums.developer.nvidia.com/t/how-nemotron-made-three-ws-text-to-3d-pipeline-usable/376445)
+- [How three.ws translates a web app into 100 languages with NVIDIA NIM](https://forums.developer.nvidia.com/t/how-three-ws-translates-a-web-app-into-100-languages-with-nvidia-nim-an-llm-powered-i18n-pipeline/377379)
+
+Post 3 should be the browser-native digital human, because it is the piece nobody
+else has written and it maps exactly onto what NVIDIA's ACE team promotes. See
+[The one asset to write](#the-one-asset-to-write) for why this specific topic and
+what backs it.
+
+### 3. AWS Builder Center, article 2 (read this before publishing the existing draft)
+
+three.ws has a live Builder Center profile at
+[builder.aws.com/community/@threews](https://builder.aws.com/community/@threews)
+and one published article, [How we metered a SaaS product through AWS Marketplace
+with the AWS SDK for JavaScript v3](https://builder.aws.com/content/3ESpll50BdSp9eiCEIxcfG9pGUN/how-we-metered-a-saas-product-through-aws-marketplace-with-the-aws-sdk-for-javascript-v3)
+(2026-05-30). Publishing is self-serve. This is a repeatable win, and
+[aws-builder-center.md](#sec-121) already carries the checklist for
+publishing the next one.
+
+**The caveat.** The obvious candidate for article 2 is
+[aws-partner-spotlight.md](#sec-124), which is written and
+unpublished. It is a company profile, not a technical article. The one that
+landed was technical: real code, real API calls, and "the five things that bit
+us." Builder Center rewards the second genre and the audience there is builders,
+not buyers. Publishing the spotlight piece as-is risks a flat result on the one
+AWS channel that is currently working.
+
+Recommended: publish a technical article and keep the spotlight for a venue that
+wants a company profile (the APN partner surface, or a pitch to an AWS partner
+marketing contact). If the spotlight goes up on Builder Center anyway, that is a
+defensible call, just make it knowingly.
+
+### 4 and 6. The Anthropic surfaces, and the gap nobody has named
+
+Two Anthropic surfaces are `ready-to-submit` (Official MCP Registry, Claude plugin
+marketplace) and a third, the Claude Connectors Directory, is blocked only on
+provisioning an `MCP_REVIEW_SECRET` and a reviewer-credential decision.
+
+Worth naming plainly: **[partners.md](#sec-318) lists eight partners and
+Anthropic is not one of them**, even though the platform's agent brain defaults to
+Claude models and there are three Anthropic-surface submissions sitting ready.
+That is the most underdeveloped big-tech relationship on the board relative to how
+much the product already depends on it. Filing the two ready submissions is the
+cheapest possible first move, and it costs one approval each.
+
+---
+
+## Tier 2: the one email, sent this week, answered later
+
+The NVIDIA Inception membership carries benefits that have never been requested.
+From NVIDIA's own [program page](https://www.nvidia.com/en-us/startups/):
+co-marketing assets ("official badges, co-branded social content, and customizable
+assets for events") and a Startup Showcase feature ("member spotlights and story
+opportunities").
+
+These are entitlements, not favors. They have never been asked for.
+
+**The co-marketing kit is the specific unlock for the X goal.** NVIDIA's social
+team can only reshare a post that uses the official badge, tags the right account,
+and carries `#NVIDIAInception`. A post that merely names NVIDIA in prose is not
+resharable by them. Without the kit, the X ambition has no mechanism behind it.
+
+Send one email to `[email protected]` carrying all five asks. The
+existing [Apps Catalog request](#sec-295) is already
+written and already addressed there; extend that draft rather than opening a
+second thread. A program manager who receives one clear email with five asks
+answers it. Five separate emails read as noise.
+
+The five asks:
+
+1. Accelerated Apps Catalog inclusion (the existing body of the email)
+2. Inception Startup Showcase nomination
+3. The co-marketing kit, including the official badge
+4. A redirect to the ACE / digital-human team
+5. Whether the GTC Inception Startup Pavilion has a slot, and which other events carry startup slots
+
+**One dependency, and it gates the whole email.** The Inception portal product
+record currently describes three.ws as a CUDA consumer, which is wrong and which
+gates both the Showcase and the Apps Catalog. Correct it at
+`programs.nvidia.com/phoenix/application` first. The correction is already
+specified in step 1 of [nvidia-apps-catalog-listing.md](#sec-294).
+Nothing in this email lands well while the record misdescribes the product.
+
+---
+
+## Tier 3: ours to drive, no gatekeeper
+
+### The membership post that never happened
+
+[announcement-coverage.md](#sec-095) tracks an "announced on X"
+column per surface. `/openai` has a real post behind it. **`/nvidia`, added
+2026-07-30, has that column empty.** The single biggest NVIDIA credential the
+company holds has never been posted on its own channel.
+
+Post it with the official badge (Tier 2 ask #3), `#NVIDIAInception`, and the right
+handle for the topic. Handle routing, verified from NVIDIA's
+[social directory](https://www.nvidia.com/en-us/contact/social/):
+
+| Topic | Account | Platform |
+|---|---|---|
+| Digital humans, Audio2Face, Riva, avatars | `@NVIDIAAIDev`, `@NVIDIADeveloper` | X |
+| Inception membership, founder story, milestones | NVIDIA for Startups | LinkedIn |
+| Nemotron, NIM, inference pipeline | `@NVIDIAAI`, `@NVIDIAAIDev` | X |
+| 3D, OpenUSD, scene work | `@NVIDIAOmniverse` | X, LinkedIn, Discord |
+
+Sequence one per week rather than four in a day. Each post is a separate chance
+for a reshare, and four in a day collapses four chances into one.
+
+### Recover the Jensen Huang receipt
+
+[`data/timeline.json`](../data/timeline.json) carries event
+`2026-07-18-jensen-huang`: NVIDIA's CEO interacted with three.ws content. Its
+`source_url` is `null`. Four other NVIDIA timeline events are also nulled,
+including the Inception acceptance itself.
+
+An engagement from NVIDIA's CEO is the first line of any Showcase pitch, podcast
+nomination, or press approach, and right now it cannot be shown to anyone. This is
+the highest-value social proof the company owns and it is currently unciteable.
+Recovering the link is a five-minute job for whoever has the account history.
+Archive it to `web.archive.org` the same minute it is found, because a deleted
+post takes the proof with it.
+
+---
+
+## The one asset to write
+
+**Browser-native Audio2Face-3D is the most differentiated technical story three.ws
+has, the demo is already live, and it has never been pointed at NVIDIA.**
+
+The capability is real and deep. [`api/_lib/a2f-nvidia.js`](../api/_lib/a2f-nvidia.js)
+implements NVIDIA's ACE `A2FControllerService` as a bidirectional gRPC stream
+against `grpc.nvcf.nvidia.com`, with the protos vendored and loaded from a
+generated descriptor, audio resampled to the 16 kHz mono PCM the model is trained
+on, and the returned blendshape time codes sampled against the original Magpie
+audio so the lips track the real voice rather than a resampled copy.
+[`src/voice/a2f-player.js`](../src/voice/a2f-player.js) drives it in the browser.
+It is wired into the live avatar embed ([`src/avatar-embed.js`](../src/avatar-embed.js))
+and the screen anchor, and shipped as the `@three-ws/voice` package.
+
+Most Audio2Face work in the world lives in Unreal or Omniverse. A face lip-syncing
+in a browser tab with no install is rare, and it is exactly what NVIDIA's ACE team
+promotes.
+
+**There is nothing to build.** The demo is live and public at
+[three.ws/demos/audio2face](https://three.ws/demos/audio2face) (and the
+`/audio2face` alias), served from
+[`public/demos/audio2face.html`](../public/demos/audio2face.html) and documented in
+[demo-routes.md](#sec-173). Both routes returned 200 on 2026-08-17. You
+type text, hear it in NVIDIA Magpie's voice, and watch the face animate through
+ARKit blendshapes, in a browser tab, with no install.
+
+Note for anyone auditing this surface: the demo lives under `public/demos/` rather
+than `data/pages.json` or `pages/`, so a grep of the page manifest will report it
+missing. It is not missing. Check `docs/demo-routes.md` before concluding
+otherwise.
+
+So the dependency under four separate items (the forum post, the ACE team
+conversation, the X clip, and next year's GTC abstract) is already satisfied. What
+is missing is not the artifact. It is that the artifact has never been pointed at
+NVIDIA: no forum post, no clip, no tag to `@NVIDIAAIDev`. A 15-second screen
+capture of that page is the most resharable asset the company owns and it costs
+one recording.
+
+Write the forum post against the two files named above so every claim has code
+behind it, and follow the house style the existing two posts follow: real numbers,
+real latencies, no marketing voice. The substance is streaming Audio2Face-3D
+blendshape tracks over gRPC into a WebGL avatar, mapping ARKit-52 onto whatever
+morph convention the visitor's model ships (ARKit, VRM vowels, Oculus visemes),
+with Riva ASR in and Magpie TTS out.
+
+Do not overclaim: three.ws consumes ACE microservices and does not self-host NIM.
+
+---
+
+## Do not chase these this week
+
+Recorded so nobody spends the week on a closed door.
+
+| Surface | Why not |
+|---|---|
+| **IBM TechXchange 2026** | The call for sessions closed 2026-05-22 and acceptances ran through July. The event is 2026-10-26 to 10-29 in Atlanta. Attendance and hallway conversations are a Q4 play, not a this-week one. |
+| **NVIDIA GTC** | The GTC 2026 call for submissions is closed. NVIDIA's own FAQ is already titled for GTC San Jose 2027. Put the [call for submissions](https://www.nvidia.com/gtc/call-for-submissions/) page on a weekly watch, because for a March event recent cycles opened in summer and closed in early fall, which is this month. Missing that window costs a full year. |
+| **NVIDIA Technical Blog** | No public guest-submission process. It is editorially controlled. The realistic path is a forum post that performs, then a pitch, which is why Tier 1 #2 comes first. |
+| **Omniverse Exchange** | Correctly blocked. OpenUSD interop is roadmap, not shipping. |
+| **NVIDIA Connect for ISVs** | Retired. The page 301-redirects to `developer.nvidia.com`; the program folded into the Developer Program. |
+| **A self-serve NVIDIA "list my product" form** | None exists on any NVIDIA surface. Every listing runs through the portal record plus a human at `[email protected]`. Stop looking for a form. |
+| **AWS Community Builders** | A different program from Builder Center publishing, and its application window opens in January. Publishing on Builder Center needs no membership. |
+
+---
+
+## The week
+
+Ordered so that the items with the longest external latency go out first.
+
+| Day | Action | Owner |
+|---|---|---|
+| Mon 08-17 | Run [openai-pr task 07](#sec-313) against the live revision, then **submit the OpenAI App Directory package** | Owner (portal) |
+| Mon 08-17 | Approve and run the staged **MCP Registry** publish; submit **`three-ws-3d`** to the Claude plugin marketplace | Owner (approval), agent (commands) |
+| Tue 08-18 | Correct the **NVIDIA Inception portal product record** | Owner |
+| Tue 08-18 | Send the **five-ask Inception email** to `[email protected]` | Owner |
+| Tue 08-18 | Recover and archive the **Jensen Huang receipt** | Whoever has account history |
+| Wed 08-19 | Record a 15-second capture of the **live Audio2Face demo**; write **NVIDIA Developer Forums post 3** against it | Agent |
+| Thu 08-20 | Publish **forums post 3**; post the clip on X tagging `@NVIDIAAIDev` | Owner posts |
+| Thu 08-20 | Post the **Inception membership** on X with the official badge and `#NVIDIAInception` | Owner |
+| Fri 08-21 | Publish **AWS Builder Center article 2** (technical genre) | Agent writes, owner posts |
+| Fri 08-21 | Draft **IBM Community post 2** for the existing author account | Agent |
+
+Publishing, posting, and sending are owner-gated under stop-and-ask gate 2 in
+[`CLAUDE.md`](../CLAUDE.md). Everything upstream of the send is an agent task.
+
+---
+
+## Verification log
+
+| Claim | Checked how | Result |
+|---|---|---|
+| OpenAI App Directory is one action from submission | Read `prompts/store-submissions/_generated/TRACKER.md` | `ready-to-submit`; sole open item is `[HUMAN: final submit in the partner portal / App Directory flow]`; Partner Network accepted 2026-07-14; org verified |
+| GPT Store listing is live | TRACKER row, published 2026-07-14 | Live and public at `chatgpt.com/g/g-6a563a3b49a88191abf346245491a444-three-ws-3d-studio` |
+| MCP Registry and Claude plugin marketplace are ready | TRACKER submission-status table | Both `ready-to-submit`, each blocked on one human/operator action |
+| Anthropic absent from the partners page | Read `docs/partners.md` | Eight cards: OpenAI, IBM, AWS, Google Cloud, Alibaba Cloud, NVIDIA, HackerNoon, Quicknode. No Anthropic. |
+| three.ws publishes on AWS's own domain | Web search plus `docs/aws-builder-center-marketplace-x402.md` frontmatter | Profile at `builder.aws.com/community/@threews`; article `status: published`, 2026-05-30, URL recorded |
+| IBM Community post is live | `docs/listings.md` Media and Content Partners table | Live at `community.ibm.com/.../nich8/2026/06/08/...` |
+| Both NVIDIA forum posts live | Verified in `docs/nvidia-visibility-map.md` the same day via HTTP status check | Both 200 |
+| Inception email never sent | Read `docs/nvidia-apps-catalog-request.md` | `**Sent:** not yet sent.` |
+| `/nvidia` never announced on X | Read `docs/announcement-coverage.md` | Column empty for `/nvidia`, populated for `/openai` |
+| Jensen Huang engagement is unciteable | `data/timeline.json`, event `2026-07-18-jensen-huang` | `source_url: null`, as are four other NVIDIA events |
+| Audio2Face is implemented and its demo is live | Read `api/_lib/a2f-nvidia.js`, `src/voice/a2f-player.js`, `docs/demo-routes.md`; `curl` on both routes | Implementation real and wired into `src/avatar-embed.js`. Demo served from `public/demos/audio2face.html`; `/demos/audio2face` and `/audio2face` both returned 200 |
+| IBM TechXchange 2026 CFP closed | Web search | Closed 2026-05-22; event 2026-10-26 to 10-29, Atlanta |
+| AWS Builder Center is self-serve publishing | Web search | `builder.aws.com`, launched July 2025 consolidating community.aws; ~5M monthly visitors; builders publish to a public profile |
+
+---
+
+## Related
+
+- [NVIDIA visibility map](#sec-300): every NVIDIA surface in depth, and the dead ends
+- [Partners](#sec-318): the eight programs, and the independence language that must survive any rewrite
+- [Listings and distribution](#sec-265): the canonical program and directory inventory
+- [Announcement coverage](#sec-095): which surfaces have been announced on X and which have not
+- [Press kit](#sec-333): marks, boilerplate, and the rules governing co-branded graphics
+- [OpenAI submission handoff pack](#sec-306): the pre-submission task briefs
+
+---
+
+<a id="sec-126"></a>
> **Source:** `docs/bnb-babt-findings.md` · [↑ table of contents](#table-of-contents)
@@ -34077,7 +35915,7 @@ shipped:
---
-<a id="sec-125"></a>
+<a id="sec-127"></a>
> **Source:** `docs/bnb-payments.md` · [↑ table of contents](#table-of-contents)
@@ -34250,7 +36088,7 @@ full verified-facts list.
---
-<a id="sec-126"></a>
+<a id="sec-128"></a>
> **Source:** `docs/bnb-vault.md` · [↑ table of contents](#table-of-contents)
@@ -34337,6 +36175,31 @@ Greenfield…" for that window rather than faking an instant unlock.
and renders the plaintext GLB in `<model-viewer>` from a `Blob` URL — the
decrypted bytes never touch the network again.
+### Managing the session key from the page
+
+The strip above the grid is the whole surface for the buyer identity, and
+every control on it is in-page (no browser `alert`/`prompt`):
+
+- **Copy address** puts the session address on the clipboard so it can be
+ funded from a faucet or any other BSC testnet wallet. Where the Clipboard
+ API is unavailable or denied (plain http, permission refused), it falls
+ back to printing the full address for manual selection.
+- **Fund from wallet** expands an inline amount field. The amount is
+ validated before any wallet is touched, so a bad value reads as a bad
+ value even with no injected wallet present. On submit it opens the
+ visitor's wallet for one plain tBNB transfer to the session address, then
+ reports the tx hash, the confirmation, and the refreshed balance in place.
+- **New session key** discards the stored key
+ (`resetVaultSession`). It is destructive (a fresh key cannot unlock
+ anything the old one bought, nor spend the tBNB left in it), so it is a
+ two-step control: the first click arms it and prints that warning, and only
+ a second click within 8 seconds rotates the key.
+
+The detail drawer is a real modal: `role="dialog" aria-modal="true"`, Tab is
+trapped inside it, Escape closes it, and closing returns focus to the card
+that opened it. While closed it is `visibility: hidden`, so its controls are
+not tabbable behind an `aria-hidden` wrapper.
+
## 4. Reproducing the proof
The public BSC testnet deploy is blocked on a funded deployer key (same wall
@@ -34398,7 +36261,7 @@ this campaign, not a bug in this code path.
---
-<a id="sec-127"></a>
+<a id="sec-129"></a>
> **Source:** `docs/bnb-world.md` · [↑ table of contents](#table-of-contents)
@@ -34634,7 +36497,7 @@ reproduction commands are recorded in `contracts/DEPLOYMENTS.md`'s "Prompt
## Related
-- [BNB Chain payments](#sec-125) — the MPP/x402 payment rail this
+- [BNB Chain payments](#sec-127) — the MPP/x402 payment rail this
campaign also shipped, same `api/_lib/bnb/` namespace.
- `contracts/src/WorldMoves.sol` — the contract itself, full NatSpec.
- `contracts/DEPLOYMENTS.md` — deploy status, bytecode, and every real
@@ -34645,7 +36508,7 @@ reproduction commands are recorded in `contracts/DEPLOYMENTS.md`'s "Prompt
---
-<a id="sec-128"></a>
+<a id="sec-130"></a>
> **Source:** `docs/brain.md` · [↑ table of contents](#table-of-contents)
@@ -34777,13 +36640,13 @@ done; wait
- [Agent Studio](#sec-062): the Brain tab uses this same backend
- [Agent System](#sec-064): how a chosen brain fits the agent model
-- [Persona Hub](#sec-318): synthesizing the system prompt a brain runs
+- [Persona Hub](#sec-323): synthesizing the system prompt a brain runs
- [API reference](#sec-096) and [Authentication](#sec-103)
- Pages: [/brain](https://three.ws/brain), [/agent-studio](https://three.ws/agent-studio)
---
-<a id="sec-129"></a>
+<a id="sec-131"></a>
> **Source:** `docs/btn-pill-migration.md` · [↑ table of contents](#table-of-contents)
@@ -34907,7 +36770,7 @@ These classes are defined across the codebase. Follow-up agents should replace t
---
-<a id="sec-130"></a>
+<a id="sec-132"></a>
> **Source:** `docs/build.md` · [↑ table of contents](#table-of-contents)
@@ -35074,13 +36937,13 @@ grep -l 'vite-plugin-pwa:register-sw' dist/widget.html dist/embed.html # expec
---
-<a id="sec-131"></a>
+<a id="sec-133"></a>
> **Source:** `docs/ca2x402.md` · [↑ table of contents](#table-of-contents)
# CA to x402
-Paste a token contract address, get back a live, agent-payable [x402](#sec-519)
+Paste a token contract address, get back a live, agent-payable [x402](#sec-544)
market-intel endpoint for that exact token. The generated endpoint costs a small
USDC payment per call, is discoverable in the x402 bazaar, and needs no keys, no
backend, and no deploy from the person who generated it.
@@ -35230,7 +37093,7 @@ actually settles against.
Operators can retune the price at deploy time with
`X402_PRICE_TOKEN_INTEL=<atomics>`; a non-integer value logs a warning and falls
-back to the default. See [x402 paid endpoints](#sec-514) for the full
+back to the default. See [x402 paid endpoints](#sec-539) for the full
price-override scheme.
---
@@ -35246,7 +37109,7 @@ A standard three.ws paid endpoint built on the shared handler
`X-PAYMENT` header gets a `402` challenge carrying the accepted networks, asset,
price, and pay-to address; the buyer retries with a signed payment and receives
the intel. Settlement is recorded like any other endpoint payment (see
-[x402 revenue and receipts](#sec-515)).
+[x402 revenue and receipts](#sec-540)).
The paid response body is the token block computed fresh at call time:
@@ -35389,16 +37252,16 @@ right now. If the endpoint is unreachable the page says so and offers a retry.
## Related
-- [x402 on three.ws](#sec-519): the protocol, the wire format, and how the
+- [x402 on three.ws](#sec-544): the protocol, the wire format, and how the
platform settles.
-- [x402 paid endpoints](#sec-514): the full catalog of our paid
+- [x402 paid endpoints](#sec-539): the full catalog of our paid
endpoints, their prices, and the `X402_PRICE_*` override scheme.
-- [x402 revenue and receipts](#sec-515): where a settled payment for this
+- [x402 revenue and receipts](#sec-540): where a settled payment for this
endpoint is recorded and how the buyer's receipt is issued.
---
-<a id="sec-132"></a>
+<a id="sec-134"></a>
> **Source:** `docs/capture.md` · [↑ table of contents](#table-of-contents)
@@ -35486,22 +37349,23 @@ console.log(job.result_url, job.num_points); // coloured .ply + point count
- **Input** is a public https URL to an mp4, mov, or webm. Private, loopback, and metadata hosts are rejected before the worker sees the URL.
- **Processing**: a real elapsed timer with stage hints, driven by the poll lifecycle, not a fake bar.
-- **Unconfigured (503)**: when the video2scene worker env is absent, the page falls back to a sample room cloud so the renderer still works end-to-end. No fabricated reconstruction is ever shown.
-- **Error**: an invalid `.ply` reports "that isn't a valid point cloud"; a blocked fetch explains the CORS limit.
+- **Unconfigured (503)**: when the video2scene worker env is absent, the page falls back to a sample room cloud so the renderer still works end-to-end. No fabricated reconstruction is ever shown. The 503 body splits its audience: `message` is what `/capture` renders for a visitor, `hint` carries the env-var instructions for whoever runs the deployment.
+- **Error**: an invalid `.ply` reports "that isn't a valid point cloud" (including a file that decodes to zero vertices, which is what a non-PLY does rather than throwing); a blocked fetch explains the CORS limit; a job that stops answering gives up after eight consecutive unreadable polls or twenty minutes, whichever comes first, and says how to restart it.
+- **Truncated clips**: when the poll returns `frames_truncated: true`, the viewer's HUD label says the clip was cut to the frame budget, so a partial scene is never presented as the whole video.
- **Point cap** defaults to 1.5M and tops out at 3M; `voxel_size` and `conf_percentile` trade density for cleanliness.
- **Client-side rendering**: the `.ply` is decoded and displayed in the browser with WebGL; very large clouds are bounded by your device's GPU and memory.
- Rate limits are per client IP on the shared 3D generation buckets.
## Related
-- [Splat Viewer](#sec-391) renders Gaussian-splat radiance fields, the photoreal cousin of point clouds.
+- [Splat Viewer](#sec-397) renders Gaussian-splat radiance fields, the photoreal cousin of point clouds.
- [/avatar-engines](https://three.ws/avatar-engines) covers the Geometric Context Transformer and related capture engines.
-- [Forge](#sec-224) and [Image to 3D](#sec-250) for generating meshes from prompts and photos.
+- [Forge](#sec-225) and [Image to 3D](#sec-251) for generating meshes from prompts and photos.
- Pages: [/scene](https://three.ws/scene) (Scene Studio), [/create](https://three.ws/create).
---
-<a id="sec-133"></a>
+<a id="sec-135"></a>
> **Source:** `docs/changelog.md` · [↑ table of contents](#table-of-contents)
@@ -35837,7 +37701,7 @@ cd sdk && npm publish
---
-<a id="sec-134"></a>
+<a id="sec-136"></a>
> **Source:** `docs/character-library.md` · [↑ table of contents](#table-of-contents)
@@ -35848,7 +37712,7 @@ The Character Library is a free, curated gallery of professionally rigged humano
Page: [/character-library](https://three.ws/character-library) · API: `GET /api/avatars/library`
Source: [`pages/character-library.html`](../pages/character-library.html) · [`src/character-library.js`](../src/character-library.js) · [`api/avatars/library.js`](../api/avatars/library.js)
-> This page covers the character gallery and its API. For the motion clips these characters play, see [Animations](#sec-093). For the free prop counterpart to this library, see the [Object Library](#sec-298).
+> This page covers the character gallery and its API. For the motion clips these characters play, see [Animations](#sec-093). For the free prop counterpart to this library, see the [Object Library](#sec-301).
---
@@ -35864,8 +37728,8 @@ Each card renders the character live in an auto-rotating `<model-viewer>` (with
| Button | Destination | What you get |
|---|---|---|
-| **Preview** | `/app#model=<glb-url>` | The full three.js [3D viewer](#sec-499) |
-| **Use** | `/studio?model=<glb-url>` | [Widget Studio](#sec-504): configure and publish an embeddable widget of this character (see the [Embedding Guide](#sec-183)) |
+| **Preview** | `/app#model=<glb-url>` | The full three.js [3D viewer](#sec-505) |
+| **Use** | `/studio?model=<glb-url>` | [Widget Studio](#sec-510): configure and publish an embeddable widget of this character (see the [Embedding Guide](#sec-186)) |
| **Animate** | `/pose?src=<glb-url>&title=<name>` | [Animation Studio](#sec-092): pose, keyframe, and export motion on this character |
Gallery controls:
@@ -35877,7 +37741,7 @@ Gallery controls:
## API: `GET /api/avatars/library`
-Public, no authentication, `GET` and `OPTIONS` only (`HEAD` is answered like `GET`). Browser `fetch` from a third-party origin is not enabled: the endpoint sends `Access-Control-Allow-Origin` only for three.ws and its partner origins, exactly like the [Object Library API](#sec-298). Call it server-side, or from a three.ws page. The endpoint proxies a small manifest JSON from the R2 CDN (`avatars/library/manifest.json`) with an edge cache (`Cache-Control: public, s-maxage=300, stale-while-revalidate=3600`). The GLB and thumbnail bytes never pass through the API: every entry carries absolute CDN URLs the browser loads directly.
+Public, no authentication, `GET` and `OPTIONS` only (`HEAD` is answered like `GET`). Browser `fetch` from a third-party origin is not enabled: the endpoint sends `Access-Control-Allow-Origin` only for three.ws and its partner origins, exactly like the [Object Library API](#sec-301). Call it server-side, or from a three.ws page. The endpoint proxies a small manifest JSON from the R2 CDN (`avatars/library/manifest.json`) with an edge cache (`Cache-Control: public, s-maxage=300, stale-while-revalidate=3600`). The GLB and thumbnail bytes never pass through the API: every entry carries absolute CDN URLs the browser loads directly.
### Query parameters
@@ -35952,19 +37816,19 @@ The gallery and API are read-only consumers of a manifest built by a local pipel
3. `scripts/fetch-mixamo-avatar-thumbnails.mjs` stages the PNG thumbnails.
4. `scripts/build-mixamo-avatar-library.mjs` reads `public/avatars/mixamo/catalog.json`, merges the extra CC0 characters from `public/avatars/extra/characters.json`, and PUTs `avatars/library/manifest.json` to R2 (`--dry-run` prints without uploading).
-R2 CORS is configured by `scripts/set-r2-cors.mjs` so browsers can GET the GLBs cross-origin. The live bucket policy is an origin allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`) that predates the world-open read rule now in that script, so a GLB loaded straight from the CDN on any other origin fails with no `access-control-allow-origin` header. Measure the live policy with `node scripts/set-r2-cors.mjs --probe`; until it is corrected, embeds on third-party origins should route the GLB through [`/api/glb`](media-api.md#same-origin-glb-proxy), as [the embed tutorial](#sec-422) does.
+R2 CORS is configured by `scripts/set-r2-cors.mjs` so browsers can GET the GLBs cross-origin. The live bucket policy is an origin allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`) that predates the world-open read rule now in that script, so a GLB loaded straight from the CDN on any other origin fails with no `access-control-allow-origin` header. Measure the live policy with `node scripts/set-r2-cors.mjs --probe`; until it is corrected, embeds on third-party origins should route the GLB through [`/api/glb`](media-api.md#same-origin-glb-proxy), as [the embed tutorial](#sec-428) does.
## Related
- [Animations](#sec-093): the clip library every character drives, and how retargeting works.
- [Animation Studio](#sec-092): the `/pose` surface the Animate button opens.
-- [Widget Studio](#sec-504) and the [Embedding Guide](#sec-183): turn a library character into a live embed on any site.
-- [Object Library](#sec-298): the same free-library pattern for CC0 props and scene objects.
-- [Marketplace](#sec-269): library characters are free; the marketplace is where priced avatars, agents, and skills are bought and sold.
+- [Widget Studio](#sec-510) and the [Embedding Guide](#sec-186): turn a library character into a live embed on any site.
+- [Object Library](#sec-301): the same free-library pattern for CC0 props and scene objects.
+- [Marketplace](#sec-270): library characters are free; the marketplace is where priced avatars, agents, and skills are bought and sold.
---
-<a id="sec-135"></a>
+<a id="sec-137"></a>
> **Source:** `docs/character-studio.md` · [↑ table of contents](#table-of-contents)
@@ -36109,9 +37973,11 @@ For developers who want to understand the internals or self-host:
The core of the system is `CharacterManager` in `character-studio/src/library/characterManager.js`. It orchestrates trait loading, mesh combining, animation playback, and VRM export. The UI layer communicates with it through React context (`SceneContext`, `ViewContext`).
-**Integration with the main app:** The `AvatarCreator` class in `src/avatar-creator.js` opens the builder in an iframe (served same-origin under `/avatar-studio`; the production build is mirrored into `dist/avatar-studio/` by the `copy-avatar-studio` Vite plugin, and the dev server serves `character-studio/build` at the same path) and listens for the `characterstudio` `postMessage` export event. When the user clicks Save Avatar inside the builder, the GLB bytes are passed back to the parent app.
+**Integration with the main app:** The `AvatarCreator` class in `src/avatar-creator.js` opens the builder in an iframe at `/avatar-studio/index.html` and listens for the `characterstudio` `postMessage` export event, which the builder sends from `character-studio/src/library/embed-export.js`. When the user clicks Save Avatar inside the builder, the GLB bytes are passed back to the parent app.
+
+The index file is addressed explicitly because the bare `/avatar-studio` path is routed to the native sculpting page; the trait builder is the static bundle beside it, mirrored into `dist/avatar-studio/` by the `copy-avatar-studio` Vite plugin and served from `character-studio/build` by the dev middleware.
-**Build:** `npm run dev` inside `character-studio/` starts the dev server. `npm run build` outputs to `./build/`, which the main repo build copies into `dist/avatar-studio/`. Run `npm run get-assets` first to clone the required loot-assets into the public directory.
+**Build:** `npm run dev` inside `character-studio/` starts the dev server on port 5173 at `/avatar-studio/`. `npm run build` outputs to `./build/`, which the main repo build copies into `dist/avatar-studio/`. `npm run test:run` runs the vitest suite once. In production the trait assets are mirrored same-origin through `GET /api/studio-assets/<path>`; `npm run get-assets` clones the same loot-assets library into the public directory for offline work.
---
@@ -36239,13 +38105,13 @@ For cases that need more control than the studio provides, create your avatar in
---
-<a id="sec-136"></a>
+<a id="sec-138"></a>
> **Source:** `docs/chatgpt-3d-studio-gpt.md` · [↑ table of contents](#table-of-contents)
# The "three.ws 3D Studio" custom GPT: builder configuration
-This is the canonical configuration for the **three.ws 3D Studio** custom GPT in the ChatGPT GPT Store. The action contract it calls is served from [public/.well-known/3d-studio-openapi.yaml](../public/.well-known/3d-studio-openapi.yaml) (live at `https://three.ws/.well-known/3d-studio-openapi.yaml`) and documented in [AR in ChatGPT](#sec-137). The GPT itself is configured by hand in the ChatGPT builder UI, so this file is the source of truth to paste from. If you change the GPT in the builder, mirror the change here in the same commit.
+This is the canonical configuration for the **three.ws 3D Studio** custom GPT in the ChatGPT GPT Store. The action contract it calls is served from [public/.well-known/3d-studio-openapi.yaml](../public/.well-known/3d-studio-openapi.yaml) (live at `https://three.ws/.well-known/3d-studio-openapi.yaml`) and documented in [AR in ChatGPT](#sec-139). The GPT itself is configured by hand in the ChatGPT builder UI, so this file is the source of truth to paste from. If you change the GPT in the builder, mirror the change here in the same commit.
## Why this file exists
@@ -36408,7 +38274,7 @@ Run the four suggested prompts in a fresh chat. Pass criteria:
---
-<a id="sec-137"></a>
+<a id="sec-139"></a>
> **Source:** `docs/chatgpt-ar.md` · [↑ table of contents](#table-of-contents)
@@ -36445,13 +38311,13 @@ The same free lane ships into ChatGPT twice, because ChatGPT has two integration
### 1. The ChatGPT app (Apps SDK / MCP connector)
-The MCP connector at `https://three.ws/api/mcp-studio` (no authentication) exposes ten free tools: six generation tools (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`, `forge_avatar`, `refine_model`), the `check_job` collector that picks up a generation which outran the tool call, and three persona/embodiment tools (`create_agent_persona`, `get_agent_persona`, `persona_say`). Full server documentation: [3D Studio MCP](#sec-273).
+The MCP connector at `https://three.ws/api/mcp-studio` (no authentication) exposes ten free tools: six generation tools (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`, `forge_avatar`, `refine_model`), the `check_job` collector that picks up a generation which outran the tool call, and three persona/embodiment tools (`create_agent_persona`, `get_agent_persona`, `persona_say`). Full server documentation: [3D Studio MCP](#sec-274).
Every successful tool result carries `arUrl` in its `structuredContent`, and the inline 3D widget renders it as a **View in your space** button next to the rotatable model. When the result is a rigged avatar the response additionally carries `irlUrl` and the button becomes **Bring it to life**. Refined versions (`refine_model`) each carry their own `arUrl`, so any point in the version lineage can be placed in the room.
### 2. The "three.ws 3D Studio" custom GPT (Actions)
-Not every ChatGPT plan supports connectors, so the same lane also ships as a plain REST Actions surface for the custom GPT in the GPT Store. The GPT's builder settings and instruction text live in [chatgpt-3d-studio-gpt.md](#sec-136); the REST contract it calls:
+Not every ChatGPT plan supports connectors, so the same lane also ships as a plain REST Actions surface for the custom GPT in the GPT Store. The GPT's builder settings and instruction text live in [chatgpt-3d-studio-gpt.md](#sec-138); the REST contract it calls:
```bash
curl -s -X POST https://three.ws/api/3d/studio \
@@ -36507,7 +38373,7 @@ The pure routing logic (`detectArTarget`, `buildSceneViewerUrl`, `planArLaunch`)
AR on three.ws is not a prop viewer; it is how agents cross into physical space. When the generated model is a rigged avatar (an agent's body), the pipeline appends `kind=avatar` to the `arUrl`, and the launcher changes behavior:
-- The launch page leads with a **Bring it to life** handoff into [`/irl?avatar=<glbUrl>`](/irl), where the avatar walks, animates, and talks with the user through the camera, standing in their real room. See [IRL](#sec-255).
+- The launch page leads with a **Bring it to life** handoff into [`/irl?avatar=<glbUrl>`](/irl), where the avatar walks, animates, and talks with the user through the camera, standing in their real room. See [IRL](#sec-256).
- Android is NOT blind-redirected into Scene Viewer, because that would hide the living path. It gets the launch page too, with static placement still one tap away.
In ChatGPT this happens automatically: the avatar-producing tools (`text_to_avatar`, `rig_mesh`, `forge_avatar`) set the flag and return `irlUrl` alongside `arUrl`, and the inline widget swaps its button label accordingly.
@@ -36530,7 +38396,7 @@ A place-in-your-room link is built to be forwarded. When it is pasted into a cha
Everything above is public plumbing:
- **Plain HTTP, free:** `POST /api/3d/generate` is the keyless agent-facing twin of the studio endpoint, same lane, same `arUrl`. Contract, states, and per-IP limits: [the free 3D API](#sec-001).
-- **Any MCP client:** the connector at `/api/mcp-studio` works in Claude and every other MCP host, not just ChatGPT. Every generation it returns already carries `arUrl` (and `irlUrl` for rigged avatars) plus a [Spatial MCP](#sec-389) artifact, so no extra tool call is needed to get the AR link. To build that link set for a GLB the connector did **not** generate, use the read-only `export_ar` tool on the separate [`/api/mcp-3d` server](#sec-270), which returns `arLaunchUrl`, `sceneViewerUrl`, `viewerUrl`, and `irlUrl`. That server is account- or payment-gated and is not part of the free connector.
+- **Any MCP client:** the connector at `/api/mcp-studio` works in Claude and every other MCP host, not just ChatGPT. Every generation it returns already carries `arUrl` (and `irlUrl` for rigged avatars) plus a [Spatial MCP](#sec-395) artifact, so no extra tool call is needed to get the AR link. To build that link set for a GLB the connector did **not** generate, use the read-only `export_ar` tool on the separate [`/api/mcp-3d` server](#sec-271), which returns `arLaunchUrl`, `sceneViewerUrl`, `viewerUrl`, and `irlUrl`. That server is account- or payment-gated and is not part of the free connector.
- **By hand:** the `arUrl` format is stable. If you have a public GLB, you can construct `https://three.ws/api/ar?src=<encoded GLB>&title=<name>` yourself and it will route correctly on every device.
The generation lane is operator-funded (NVIDIA NIM running Microsoft TRELLIS for text-to-3D), so the end user pays nothing and needs no account; real per-IP rate limits apply and are documented per endpoint.
@@ -36556,14 +38422,14 @@ The generation lane is operator-funded (NVIDIA NIM running Microsoft TRELLIS for
- [Your first prompt to 3D in ChatGPT](/tutorials/first-prompt-to-3d): the user-facing walkthrough of this whole flow
- [Place your 3D model in AR](/tutorials/view-in-ar): the on-site AR tutorial
-- [3D Studio MCP](#sec-273): the free MCP server behind the ChatGPT app
+- [3D Studio MCP](#sec-274): the free MCP server behind the ChatGPT app
- [The free 3D API](#sec-001): the keyless HTTP contract with `arUrl`
- [AR and WebXR reference](#sec-099): Quick Look, Scene Viewer, WebXR, and the USDZ pipeline in depth
-- [IRL](#sec-255): the living-agent experience behind Bring it to life
+- [IRL](#sec-256): the living-agent experience behind Bring it to life
---
-<a id="sec-138"></a>
+<a id="sec-140"></a>
> **Source:** `docs/choreography.md` · [↑ table of contents](#table-of-contents)
@@ -36678,7 +38544,7 @@ Rules worth knowing before you call it:
### From an embed
-Any page already rendering an [`<agent-3d>`](#sec-183) element can perform the agent's saved routines by name:
+Any page already rendering an [`<agent-3d>`](#sec-186) element can perform the agent's saved routines by name:
```html
<agent-3d agent="YOUR_AGENT_ID"></agent-3d>
@@ -36756,9 +38622,11 @@ player.update(deltaSeconds);
Routines round-trip through the URL, so a link is the routine. The studio keeps `?r=` in sync as you edit:
```
-https://three.ws/choreograph?r=Welcome%7Cwave%3A2%2Cnod%3A1.2%2Cidle%3A1.6
+https://three.ws/choreograph?r=Welcome|wave:2,nod:1.2,idle:1.6
```
+The studio writes that query itself rather than through `URLSearchParams`, because the encoding below already escapes everything it needs to and a second pass would turn a routine called `The pitch` into `?r=The%2520pitch|…`. Links written the older way still load: the page retries a value that will not parse after one `decodeURIComponent`.
+
The encoding is deliberately legible rather than base64, so you can read a link before you click it and hand-write one when that is easier:
```
@@ -36768,7 +38636,7 @@ Name|slot:hold[*speed][@clip],slot:hold,…
- `Welcome|wave:2,nod:1.2` gives two beats
- `Slow%20clap|celebrate:3*0.5` plays at half speed
- `Encore|dance:4@av-offabean-dance` pins a specific clip (naming the slot's default instead, `@rumba`, stores `null` and leaves the slot resolving)
-- `Waiting~loop|patience:3,fidget:2.4` sets `loop` via the `~loop` suffix on the name
+- `Waiting~loop|patience:3,fidget:2.4` sets `loop` via the `~loop` suffix on the name (a `~` inside the name itself is escaped to `%7E`, so a routine really called `Encore~loop` stays one)
`encodeRoutine()` and `decodeRoutine()` in the runtime module are the canonical implementations. A malformed link throws with the reason rather than dropping steps quietly, and the studio shows that reason instead of silently loading something else.
@@ -36805,13 +38673,13 @@ Coming from [/gestures](https://three.ws/gestures), the **Use in a routine** but
## Related
- [Animations](#sec-093): clips, collections, and the slot vocabulary underneath every routine
-- [Procedural animation](#sec-328): the IK layers that run on top of whatever clip is playing
+- [Procedural animation](#sec-334): the IK layers that run on top of whatever clip is playing
- [Agent manifest](#sec-055): the public document that carries `choreographies` to embeds
-- [Embedding an agent](#sec-183): the `<agent-3d>` element these methods live on
+- [Embedding an agent](#sec-186): the `<agent-3d>` element these methods live on
---
-<a id="sec-139"></a>
+<a id="sec-141"></a>
> **Source:** `docs/circulation-engine.md` · [↑ table of contents](#table-of-contents)
@@ -36973,7 +38841,7 @@ covered by [tests/circulation-three-topup.test.js](../tests/circulation-three-to
The engine runs from the `pulse-tick` cron
([api/cron/pulse-tick.js](../api/cron/pulse-tick.js)), which is fanned out every
**minute** by the `economy-tick` dispatcher (see the
-[economy heartbeat](#sec-178)) rather than scheduled on its own.
+[economy heartbeat](#sec-181)) rather than scheduled on its own.
Each tick grows the pool by up to `CIRCULATION_GROWTH_PER_TICK` agents and runs
`CIRCULATION_ACTIONS_PER_TICK` everyday actions (plus any heavyweight action that
wins first refusal). The `pulse-tick` function is bounded to a 120-second
@@ -37006,9 +38874,9 @@ loop as a payout.
| Sink | What it holds |
|---|---|
| `circulation_actions` | One row per action the engine ran (kind, actors, signature, amount). |
-| `agent_custody_events` | The canonical wallet ledger entry for every real spend/transfer (see [Money feed](#sec-284)). |
+| `agent_custody_events` | The canonical wallet ledger entry for every real spend/transfer (see [Money feed](#sec-285)). |
| `pump_agent_trades` / `pump_agent_mints` | Trade and launch records, surfaced in the pump feed and `/launches`. |
-| `skill_purchases` / `asset_purchases` | Marketplace settlement records (see [Marketplace](#sec-269)). |
+| `skill_purchases` / `asset_purchases` | Marketplace settlement records (see [Marketplace](#sec-270)). |
Real spends are written to `agent_custody_events`, which powers per-agent
portfolio balances and the agent-to-agent economy volume dashboard (all-time and
@@ -37043,15 +38911,15 @@ budget, so raise gradually and watch tick runtime and treasury balance.
## Related
-- [Money feed](#sec-284): where circulation activity surfaces.
+- [Money feed](#sec-285): where circulation activity surfaces.
- [Autonomous x402 loop](#sec-105): the separate treasury-paid loop
that buys polling intel from our own x402 endpoints.
- [Agent wallets](#sec-072): the custodial key model every action uses.
-- [Marketplace](#sec-269), [Coin launches](#sec-142).
+- [Marketplace](#sec-270), [Coin launches](#sec-144).
---
-<a id="sec-140"></a>
+<a id="sec-142"></a>
> **Source:** `docs/clash.md` · [↑ table of contents](#table-of-contents)
@@ -37065,7 +38933,7 @@ API: `/api/clash/[action]` with `action` one of `state`, `enlist`, `enlist-verif
## Why it exists
-Coin communities already behave like tribes. Coin Clash gives that tribalism a game loop with real stakes of identity: you can only fight for a coin you actually hold, so rallying is a public act of conviction, and a community's showing on the board is a live measure of how many holders will show up. The token gate is a real balance read, not a client-side check, which makes it a working demonstration of the same "hold, do not just claim" primitive used across the platform (see [token-gated 3D embeds](#sec-401) and [hold to access](#sec-237)). Effort wins, not market cap: a battle is decided by summed taps, so a smaller, more active army can beat a larger, quieter one.
+Coin communities already behave like tribes. Coin Clash gives that tribalism a game loop with real stakes of identity: you can only fight for a coin you actually hold, so rallying is a public act of conviction, and a community's showing on the board is a live measure of how many holders will show up. The token gate is a real balance read, not a client-side check, which makes it a working demonstration of the same "hold, do not just claim" primitive used across the platform (see [token-gated 3D embeds](#sec-407) and [hold to access](#sec-238)). Effort wins, not market cap: a battle is decided by summed taps, so a smaller, more active army can beat a larger, quieter one.
## How it works
@@ -37129,15 +38997,15 @@ The Coin Clash state and leaderboard are also exposed read-only over MCP through
## Related
-- [Token-gated 3D embeds](#sec-401): the same real on-chain balance gate, applied to embeds
-- [Hold to access](#sec-237): the platform's broader hold-do-not-spend membership thesis
-- [The social layer](#sec-385): platform-wide feed, follows, and leaderboards
-- [MCP tools](#sec-276): the read-only Clash MCP server
+- [Token-gated 3D embeds](#sec-407): the same real on-chain balance gate, applied to embeds
+- [Hold to access](#sec-238): the platform's broader hold-do-not-spend membership thesis
+- [The social layer](#sec-391): platform-wide feed, follows, and leaderboards
+- [MCP tools](#sec-277): the read-only Clash MCP server
- Pages: [/clash](https://three.ws/clash) · [/communities](https://three.ws/communities)
---
-<a id="sec-141"></a>
+<a id="sec-143"></a>
> **Source:** `docs/clip-director.md` · [↑ table of contents](#table-of-contents)
@@ -37167,9 +39035,35 @@ loss) and directs one card per surface:
- **alt_text** (an accessibility description of the card).
Honest by design: a losing trade still gets a card (radical downside-transparency is the
-brand), with a "live to trade again" tone, always with a verifiable on-chain angle. No
-number is invented; every stat traces to the closed position it was handed. When no LLM
-provider is available a deterministic director produces the same-shaped artifact.
+brand), with a "live to trade again" tone, always with a verifiable on-chain angle. When
+no LLM provider is available a deterministic director produces the same-shaped artifact.
+
+## The grounding guard
+
+"The real number, never a screenshot" is the only thing this surface sells, and the LLM
+lane writes the prose, so nothing downstream can tell a fluent invention from a fact. It
+is not a hypothetical risk. During the July route audit a provider in the free chain
+answered a real **+1.89x win on $NIBZ** with *"-8.2% realized loss"* on *"$THREE"*,
+gesture `celebrate`: every word fluent, every fact invented, rendered next to a solscan
+link proving the opposite.
+
+So a generated card is checked against the trade it claims to describe before it ships
+(`isGrounded` in [api/_lib/clip-director.js](../api/_lib/clip-director.js)):
+
+- **Every `$TICKER` in the copy must be the traded coin.** No other ticker, $THREE
+ included: the card is about this trade.
+- **Every figure in the copy must trace to the trade** (multiple, P&L %, entry/exit SOL,
+ realized SOL, hold time read in minutes, hours, or days) or to the follower count. The
+ agent's own name is stripped first, so a trader called "Swarm 2" costs it nothing.
+- **The check runs on the finalized card, not the raw model output**, because the length
+ clamp landing mid-number is its own way of stating a figure the trade never contained.
+- **The avatar reaction has to point the way the trade went.** `celebrate` / `point` /
+ `wave` on a win, `sweat` / `shrug` on a loss. A stop-out cannot be celebrated.
+
+A card that fails any of these is discarded and the deterministic director answers
+instead, so the response carries `"source": "deterministic"`. The endpoint never fails
+and never ships an unverifiable number. [tests/clip-director-grounding.test.js](../tests/clip-director-grounding.test.js)
+pins the behaviour with the exact captured hallucination.
## Where the numbers come from
@@ -37218,16 +39112,31 @@ Response shape (GET):
When the agent has no closed trades yet the response returns `clips: []` with an `empty`
message instead of an error, so a card is only ever minted from a real closed round-trip.
+## The page
+
+[/clip-director](https://three.ws/clip-director) fills its trader picker from
+`GET /api/mirror/leaderboard?settled_min=1`, the [copy-trading](#sec-165)
+ranking narrowed to agents that actually have a closed round-trip. That parameter is
+load-bearing: the page used to ask for the top agents by composite score and filter for
+a track record client side, and because score does not correlate with having settled
+trades, the only eligible agent ranked below the window and every visitor was told that
+no agent had ever closed a trade.
+
+`?agent_id=<uuid>` deep-links a specific trader, including one outside the ranking (a
+shared link, or a private agent that never ranks); the picker labels it once the clip
+comes back. Each card's CTA is a real link: `copy-the-agent` and `fork-this-trade` go to
+[/mirror](https://three.ws/mirror), `view-track-record` to that agent's profile.
+
## Related
-- [Trader Card & the claim-your-wallet wedge](#sec-403)
-- [Meta-Allocator: the ETF of degens](#sec-280)
-- [The trading surfaces](#sec-409) · [The Arena](https://three.ws/arena)
+- [Trader Card & the claim-your-wallet wedge](#sec-409)
+- [Meta-Allocator: the ETF of degens](#sec-281)
+- [The trading surfaces](#sec-415) · [The Arena](https://three.ws/arena)
- [Animations & gestures](#sec-093)
---
-<a id="sec-142"></a>
+<a id="sec-144"></a>
> **Source:** `docs/coin-launches.md` · [↑ table of contents](#table-of-contents)
@@ -37261,12 +39170,12 @@ The user holds the keys; the platform never signs for them.
The agent launcher signs and submits with the agent's **custodial** Solana keypair
server-side (`launch-agent`), through the protected execution path
(`submitProtected()`). Spend caps are checked before signing (see
-[Agent wallets](#sec-167)), and the mint is registered in
+[Agent wallets](#sec-170)), and the mint is registered in
`pump_agent_mints`. The `launcher-tick` cron (every minute) drives the
autonomous launcher engine (`api/_lib/launcher-engine.js`), bounded by
per-launch and daily SOL caps, an hourly ceiling, a cadence gate, and a circuit
breaker from its `launcher_config` row; a scope whose row is disabled stays
-inert. The [circulation engine](#sec-139) also runs its own
+inert. The [circulation engine](#sec-141) also runs its own
`launch` action with separate hourly/daily caps.
## What a launch carries
@@ -37277,7 +39186,7 @@ inert. The [circulation engine](#sec-139) also runs its own
| Quote mint | Resolved to the network-correct pairing (USDC mint or SOL-paired). |
| Dev buy | A small initial buy can accompany the create (the `LAUNCH_FLOOR` covers create + tiny dev buy + fees). |
| Buyback authority | A buyback basis-points configuration can be attached to the agent mint. |
-| Mint mark | When `THREE_WS_MARK_ENFORCE` is on (the default; set `0`/`false` to disable), the mint address is vanity-ground to carry the three.ws mark (see [Mint mark](#sec-281), [Vanity protocol](#sec-005)). |
+| Mint mark | When `THREE_WS_MARK_ENFORCE` is on (the default; set `0`/`false` to disable), the mint address is vanity-ground to carry the three.ws mark (see [Mint mark](#sec-282), [Vanity protocol](#sec-005)). |
## Recording and surfacing
@@ -37286,7 +39195,7 @@ inert. The [circulation engine](#sec-139) also runs its own
| `pump_agent_mints` (mint + network keyed) | `/launches` feed, agent-profile launch history. |
| `pump_agent_trades` | Trade history for the mint. |
| `agent_custody_events` | The on-chain spend (create + dev buy). |
-| Live ticker | `coin-buy` / `agent-deploy` events (see [Money feed](#sec-284)). |
+| Live ticker | `coin-buy` / `agent-deploy` events (see [Money feed](#sec-285)). |
The `launches`, `by-agent`, and `quote` actions on `api/pump/[action].js` read
these back for the directory and detail pages. Coin detail pages render a live
@@ -37310,14 +39219,14 @@ hardcode or surface any other specific mint as a recommendation.
## Related
-- [Solana pump.fun signals](#sec-386) — reputation/intel from pump.fun activity.
-- [Agent wallets](#sec-167) — custodial signing and spend caps.
-- [Circulation engine](#sec-139) — autonomous launch cadence and caps.
-- [Mint mark](#sec-281), [Vanity protocol](#sec-005).
+- [Solana pump.fun signals](#sec-392) — reputation/intel from pump.fun activity.
+- [Agent wallets](#sec-170) — custodial signing and spend caps.
+- [Circulation engine](#sec-141) — autonomous launch cadence and caps.
+- [Mint mark](#sec-282), [Vanity protocol](#sec-005).
---
-<a id="sec-143"></a>
+<a id="sec-145"></a>
> **Source:** `docs/coin-pages.md` · [↑ table of contents](#table-of-contents)
@@ -37601,7 +39510,8 @@ one-click reset.
Files: [`pages/screener.html`](../pages/screener.html) (shell, controls, SEO),
[`src/screener.js`](../src/screener.js) (state, filtering, sorting,
-rendering), [`src/screener.css`](../src/screener.css), with shared formatters
+rendering), [`src/filter-controls.css`](../src/filter-controls.css) (the
+labelled filter row, shared with `/yields`), with shared formatters
from [`src/shared/coin-format.js`](../src/shared/coin-format.js) and the table
pattern from [`src/coins-index.js`](../src/coins-index.js).
@@ -37627,7 +39537,12 @@ data" rule:
- **`/categories`** — every crypto sector ranked by market cap with 24h change,
volume, and the top coins in each. New `/api/coin/categories` (CoinGecko
`/coins/categories`). Each row opens a [category detail
- page](#categoryid--category-detail).
+ page](#categoryid--category-detail). CoinGecko reports 750+ categories, so the
+ table opens with the top 50 and pages in 50 more per click, and the search box
+ filters the full set by name or slug before you page. Every column sorts, and
+ the three no-rows outcomes read differently: a failed fetch offers a retry that
+ refetches, an upstream reporting nothing says so, and a search with no match
+ offers to clear itself.
- **`/exchanges`** — top exchanges by trust score and 24h volume (USD, derived
from the live BTC price). New `/api/coin/exchanges`. Each row opens an
[exchange detail page](#exchangeid--exchange-detail).
@@ -37873,7 +39788,7 @@ text before they reach the client.
| Exchange detail | [`pages/exchange.html`](../pages/exchange.html) + `src/exchange-page.js` + `src/exchange-page.css`, API [`api/coin/exchange.js`](../api/coin/exchange.js) |
| Converter | `pages/converter.html` + `src/converter.js` + `src/converter.css` |
| DeFi / Chains / Stablecoins | `pages/{defi,chains,stablecoins}.html` (+ `src/*.js`, `src/*.css`), APIs in [`api/defi/`](../api/defi) |
-| DeFi Yields | [`pages/yields.html`](../pages/yields.html) + `src/yields.js` + `src/yields.css`, API [`api/defi/yields.js`](../api/defi/yields.js) |
+| DeFi Yields | [`pages/yields.html`](../pages/yields.html) + `src/yields.js` + `src/yields.css` + [`src/filter-controls.css`](../src/filter-controls.css), API [`api/defi/yields.js`](../api/defi/yields.js) |
| Protocol detail | [`pages/protocol.html`](../pages/protocol.html) + `src/protocol-page.js` + `src/protocol-page.css`, API [`api/defi/protocol.js`](../api/defi/protocol.js) |
| Chain detail | [`pages/chain.html`](../pages/chain.html) + `src/chain-page.js` + `src/chain-page.css`, API [`api/defi/chain.js`](../api/defi/chain.js) |
| Stablecoin detail | [`pages/stablecoin.html`](../pages/stablecoin.html) + `src/stablecoin-page.js` + `src/stablecoin-page.css`, API [`api/defi/stablecoin.js`](../api/defi/stablecoin.js) |
@@ -37899,7 +39814,7 @@ server mirrors each (including the dynamic `/coin/:id` path). The pre-existing
---
-<a id="sec-144"></a>
+<a id="sec-146"></a>
> **Source:** `docs/coin-wars.md` · [↑ table of contents](#table-of-contents)
@@ -38123,11 +40038,279 @@ battlefield. `return` is only ever honoured as a same-origin path.
| The endpoint + store | [`api/wars.js`](../api/wars.js), [`api/_lib/wars-store.js`](../api/_lib/wars-store.js) |
| Tests | [`tests/war-matchmaking.test.js`](../tests/war-matchmaking.test.js), [`tests/clash-match.test.js`](../tests/clash-match.test.js) |
-Related: [the in-game economy](#sec-251), [play hardening](#sec-322).
+Related: [the in-game economy](#sec-252), [play hardening](#sec-327).
---
-<a id="sec-145"></a>
+<a id="sec-147"></a>
+
+> **Source:** `docs/coingecko-listing-update-2026-08.md` · [↑ table of contents](#table-of-contents)
+
+# CoinGecko listing update: $THREE market additions (August 2026)
+
+Working notes and post drafts for the CoinGecko "New Listings on Exchanges/New Market Addition"
+form for $THREE (`FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`, CoinGecko id `three-ws`).
+
+## The headline
+
+Of every venue $THREE is live on, **only MEXC can actually go on this form.** CoinGecko's exchange
+registry holds 1,488 entries and not one of them is an Alpha venue: no Bybit Alpha, no KuCoin Alpha,
+no Binance Alpha. Jupiter and Phantom are not in it either. The form says so itself: "If you can't
+find your exchange in the list, it might not be on CoinGecko yet, and we're unable to proceed."
+
+## What CoinGecko already tracks
+
+Pulled live from `api.coingecko.com/api/v3/coins/three-ws/tickers` on 2026-08-16:
+
+| Market | Pair | 24h volume (USD) |
+| --- | --- | --- |
+| LBank | THREE / USDT | 600,824 |
+| PumpSwap | three / SOL | 48,861 |
+| Meteora | three / SOL | 18,130 |
+| Orca | three / SOL | 13,445 |
+| KCEX | THREE / USDT | 4,621 |
+| Meteora (second pool) | three / SOL | 39 |
+
+## Venue matrix
+
+| Venue | Real? | On CoinGecko's exchange list? | Submit on this form? |
+| --- | --- | --- | --- |
+| MEXC spot THREE/USDT | Yes, verified via MEXC API | Yes, `MEXC [mxc]` | **Yes** |
+| LBank THREE/USDT | Yes | Yes | Already tracked |
+| KCEX THREE/USDT | Yes | Yes | Already tracked |
+| Bybit Alpha | Yes, official announcement | No Alpha venue exists | No |
+| KuCoin Alpha | Yes, official announcement | No Alpha venue exists | No |
+| Binance Web3 (web3.binance.com) | Yes | No, and it is a wallet aggregator | No |
+| Jupiter (Verified) | Yes | Not on CoinGecko at all | No |
+| Phantom (Verified) | Yes | Not on CoinGecko at all | No |
+| derp.trade | Yes, Solana leverage venue | No (CoinGecko's "DerpDEX" is a different project on zkSync/Base/opBnb) | No, and perps go through the derivatives process |
+
+### 1. MEXC, spot THREE/USDT (the one to submit)
+
+Confirmed the same asset from MEXC's own `exchangeInfo`:
+`contractAddress: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`, `fullName: three.ws`,
+`isSpotTradingAllowed: true`. Live since 2026-06-02T01:45Z, roughly 56.5k USD of 24h quote volume.
+
+Form values:
+
+- Exchange Name: `MEXC`
+- Exchange Trade URL: `https://www.mexc.com/exchange/THREE_USDT`
+
+### 2. The Alpha venues
+
+Both are real and both carry our exact mint in their trade URLs:
+
+- Bybit Alpha: <https://announcements.bybit.com/en/article/three-is-now-live-on-bybit-alpha-bltc04fc471efada919/>
+- KuCoin Alpha: <https://www.kucoin.com/announcement/ph-kucoin-alpha-new-listed-token-three-percolator>
+
+CoinGecko carries `Bybit [bybit_spot]`, `Bybit (Futures) [bybit]` and `KuCoin [kucoin]`, but Alpha is
+a separate product with separate liquidity and CoinGecko does not carry it as a venue. Submitting
+Alpha markets under the parent exchange would misstate where the liquidity sits and is likely to be
+rejected.
+
+The route that does work is CoinGecko's **New Exchange Listing** request, asking them to add Bybit
+Alpha and KuCoin Alpha as venues. That is a separate form and a slower process, driven by the
+exchange more than by us. Worth filing, but do not let it hold up the MEXC submission.
+
+### 3. Jupiter and Phantom "Verified"
+
+These are token-list trust badges, not markets. Jupiter routes through the same PumpSwap, Meteora and
+Orca pools CoinGecko already tracks, so there is no separate market to add, and neither is in
+CoinGecko's exchange registry. They are still strong credibility signals and belong in the X post
+even though they do not belong on the form.
+
+### Ruled out
+
+Swept the full public market lists of Gate.io, Bitget, BitMart, KuCoin spot, CoinEx, BingX, XT.com,
+Toobit, Poloniex, Bitrue, LATOKEN, Phemex, CoinW, Biconomy, DigiFinex, Hotcoin, Pionex, BTSE and
+Ourbit. No THREE market on any of them.
+
+WEEX claims trace only to `weex.com/wiki/article/...` SEO pages, not to WEEX's official channel at
+`weex.com/help/articles/...`. The main article 404s and their API is unreachable. Not submitted.
+
+## Link check
+
+Every link below was resolved on 2026-08-16 before being put in a post:
+
+| Link | HTTP |
+| --- | --- |
+| jup.ag token page | 200 |
+| trade.phantom.com token page | 200 |
+| web3.binance.com token page | 202 |
+| lbank.com support article | 200 |
+| kucoin.com announcement (`en-` locale) | 200 |
+| derp.trade market page | 200 |
+| bybit.com alpha (tracking params stripped) | 200 |
+| kcex.com/exchange/THREE_USDT | 403 |
+
+Two notes. Use the `en-` KuCoin announcement locale, not `ph-`; both resolve but `en-` is the right
+one for this audience. The KCEX 403 is their CDN blocking automated requests, not a dead link:
+CoinGecko shows trades on that pair minutes old, so the market is live and the URL is fine in a post.
+
+The Bybit trade URL is given with its affiliate and campaign tracking parameters stripped. The bare
+`?address=...&chain=SOL` form resolves 200 on its own.
+
+## Post 1: main announcement (all links)
+
+Goes up first, from [@trythreews](https://x.com/trythreews). Its URL fills "Link (1)" in section 2
+of the form, so MEXC has to be named in it.
+
+This runs 542 characters by X's counting rules, where every URL costs 23 characters regardless of
+length. It needs a Premium long post. The thread version below is the fallback if the account is on
+the 280-character limit.
+
+```
+$THREE is live everywhere.
+
+CEX
+MEXC https://www.mexc.com/exchange/THREE_USDT
+LBank https://www.lbank.com/trade/three_usdt
+KCEX https://www.kcex.com/exchange/THREE_USDT
+
+Alpha
+Bybit https://www.bybit.com/en/alpha/?address=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&chain=SOL
+KuCoin https://www.kucoin.com/trade/alpha/solana/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+Verified
+Jupiter https://jup.ag/tokens/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+Phantom https://trade.phantom.com/token/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+Binance Web3 https://web3.binance.com/en/token/sol/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+Perps
+derp.trade https://derp.trade/market/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+Announcements
+https://announcements.bybit.com/en/article/three-is-now-live-on-bybit-alpha-bltc04fc471efada919/
+https://www.kucoin.com/announcement/en-kucoin-alpha-new-listed-token-three-percolator
+https://www.lbank.com/support/articles/2062382639494463488
+
+Charts
+https://www.coingecko.com/en/coins/three-ws
+https://www.geckoterminal.com/solana/pools/5ByL7MZoLABYnwMPZKPKjf4MGkZ7FeBzrAnos19Pre2z
+
+CA FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+three.ws
+```
+
+The KuCoin announcement covers two tokens and its URL slug carries the other one's name. If keeping
+the feed purely $THREE matters more than the citation, drop that single line; the KuCoin Alpha trade
+link in the Alpha block already proves the listing.
+
+## Post 1b: thread version (fits the 280-character limit)
+
+Six tweets, measured at 231 / 110 / 75 / 125 / 162 / 138 characters.
+
+```
+1/ $THREE is live everywhere.
+
+Listed on MEXC, LBank, KCEX.
+Live on Bybit Alpha and KuCoin Alpha.
+Verified on Jupiter, Phantom and Binance Web3.
+Perps on derp.trade.
+
+Every link below.
+
+CA: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+```
+
+```
+2/ Centralized exchanges
+
+MEXC https://www.mexc.com/exchange/THREE_USDT
+LBank https://www.lbank.com/trade/three_usdt
+KCEX https://www.kcex.com/exchange/THREE_USDT
+```
+
+```
+3/ Alpha venues
+
+Bybit https://www.bybit.com/en/alpha/?address=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&chain=SOL
+
+KuCoin https://www.kucoin.com/trade/alpha/solana/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+```
+
+```
+4/ Verified token status
+
+Jupiter https://jup.ag/tokens/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+Phantom https://trade.phantom.com/token/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+Binance Web3 https://web3.binance.com/en/token/sol/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+```
+
+```
+5/ Perps and official announcements
+
+derp.trade https://derp.trade/market/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+Bybit https://announcements.bybit.com/en/article/three-is-now-live-on-bybit-alpha-bltc04fc471efada919/
+
+KuCoin https://www.kucoin.com/announcement/en-kucoin-alpha-new-listed-token-three-percolator
+
+LBank https://www.lbank.com/support/articles/2062382639494463488
+```
+
+```
+6/ Charts
+
+CoinGecko https://www.coingecko.com/en/coins/three-ws
+GeckoTerminal https://www.geckoterminal.com/solana/pools/5ByL7MZoLABYnwMPZKPKjf4MGkZ7FeBzrAnos19Pre2z
+
+CA FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+three.ws
+```
+
+## Post 2: public verification
+
+Goes up after submitting, once the request ID exists. Both the request ID and the GeckoTerminal URL
+have to be in the post body, not in a reply or quote tweet.
+
+Keep this one lean. CoinGecko's reviewer is looking for two things, the request ID and the
+GeckoTerminal URL, and a wall of links buries them. Request ID `CU1608260002`, filed 2026-08-16.
+275 characters, fits the free tier.
+
+```
+Verifying our CoinGecko market addition request for $THREE.
+
+Request ID: CU1608260002
+GeckoTerminal: https://www.geckoterminal.com/solana/tokens/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+CA: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+Telegram: @three_ws
+
+MEXC market: https://www.mexc.com/exchange/THREE_USDT
+
+Posted from the official three.ws account.
+```
+
+Three deliberate choices in that text:
+
+- **The GeckoTerminal token URL, not a pool URL.** CoinGecko states the purpose of this step is to
+ safeguard against fraudulent contract addresses. The token URL carries the contract address in its
+ own path, so it does that job directly; a pool URL does not.
+- **Telegram `@three_ws` included.** CoinGecko offers this as optional extra verification and it
+ costs nothing. Verified on 2026-08-16 that three.ws links out to `https://t.me/three_ws`.
+- **Posted from @trythreews.** Verified the same day that the live three.ws homepage links to
+ `https://x.com/trythreews`, which is what satisfies "an account linked to the project's official
+ website". Both social links are present on the homepage.
+
+Paste that post's URL into the form's Remarks field. Quote-tweet the main announcement from it so the
+full link set is one click away without cluttering the verification post itself.
+
+## Checks before submitting
+
+- three.ws must link out to @trythreews, since that link is how CoinGecko ties the account to the
+ project.
+- The MEXC pair URL in the announcement post and in section 3 must match exactly.
+- Regular Pass (5-day) is enough for a single market addition. Fast Pass is 200 USD.
+- In Remarks, note that Bybit Alpha and KuCoin Alpha markets exist but their venues are absent from
+ CoinGecko's exchange list. That tells the reviewer the coverage gap is on their side, not ours.
+
+---
+
+<a id="sec-148"></a>
> **Source:** `docs/coinmarketcap-article-play.md` · [↑ table of contents](#table-of-contents)
@@ -38273,7 +40456,7 @@ The chart has always told you *what* a coin is doing. /play lets you go stand wh
---
-<a id="sec-146"></a>
+<a id="sec-149"></a>
> **Source:** `docs/coinmarketcap-article.md` · [↑ table of contents](#table-of-contents)
@@ -38476,7 +40659,7 @@ If you've been waiting for the moment AI and crypto stop talking past each other
---
-<a id="sec-147"></a>
+<a id="sec-150"></a>
> **Source:** `docs/coinmarketcap-live-article.md` · [↑ table of contents](#table-of-contents)
@@ -38600,7 +40783,7 @@ at [community.ibm.com](https://community.ibm.com/community/user/usergroup?Commun
---
-<a id="sec-148"></a>
+<a id="sec-151"></a>
> **Source:** `docs/compose.md` · [↑ table of contents](#table-of-contents)
@@ -38621,16 +40804,18 @@ The page is a Three.js scene with PMREM image-based lighting, soft shadows, expo
- **Forge from text.** The prompt box posts to `/api/forge` with an optional intent (accessory, item, scene, creature, vehicle) that becomes the model's category. The studio polls the job to completion, streaming staged progress, then loads the resulting GLB into the scene. Meshopt-compressed models are decoded on load. Generation runs on the platform's real text-to-3D lanes; a queued job restarts the timeout window so waiting for a GPU never counts against the run budget.
- **Transform gizmos.** Select any object and translate, rotate, or scale it with `TransformControls`. Toggle world/local space, turn on 0.25-unit grid snapping, and lock proportional scale. Every drag and every numeric-field edit is one undoable step in a 50-deep undo/redo stack.
- **Bone attachment.** When a rigged avatar is in the scene, any non-avatar item's inspector gains an "Attach to Bone" control. The avatar's bones are grouped into readable regions (Head, Torso, Left/Right Arm, Left/Right Leg, Fingers L/R) with the raw bone names cleaned of rig prefixes (`mixamorig:`, `CC_Base_`, `rig_`). Attaching parents the item to that bone at the origin, so it rides the bone; detaching returns it to world space.
-- **Scene tooling.** Click-to-select raycasting, a hierarchy panel with per-object visibility and rename (double-click), camera presets (front/back/left/right/top/isometric, plus Blender-style numpad keys), F to frame the selection, Ctrl+D to duplicate, a live triangle-and-object counter, screenshot export, and toast notifications for every action. Geometry, materials, and textures are disposed on removal, so long sessions do not leak memory.
-- **Bring your own avatar.** Load an avatar by URL, browse your gallery through `/api/explore`, or arrive with `?avatar=<id>` (resolved via `/api/avatars/<id>`) or `?glb=<url>`. If the avatar ships animations, its first clip (typically idle) plays automatically through an `AnimationMixer`.
+- **Scene tooling.** Click-to-select raycasting, a hierarchy panel with per-object visibility and rename (double-click), camera presets (front/back/left/right/top/isometric, plus Blender-style numpad keys), F to frame the selection, Ctrl+D to duplicate, a live triangle-and-object counter, screenshot export, and toast notifications for every action. Geometry, materials, and textures are disposed once the step that removed them can no longer be undone (it falls off the 50-deep history), so long sessions do not leak memory and undo still restores the real object.
+- **Bring your own avatar.** Load an avatar by pasting a GLB URL *or* a three.ws avatar id (both go through the same `/api/avatars/<id>` lookup), browse the public 3D avatars through `/api/explore?source=avatar&only3d=1`, or arrive with `?avatar=<id>` or `?glb=<url>`. If the avatar ships animations, its first clip (typically idle) plays automatically through an `AnimationMixer`. A model that cannot be loaded leaves a persistent inline explanation on the start panel, not a toast that vanishes before you can read it.
+- **A gallery that is never empty.** The Recent Creations strip shows the models this browser has forged. A first-time visitor has none, so the strip falls back to the live community showcase (`/api/forge-gallery?scope=community`) under the heading "Fresh from the Forge": real, public models you can click straight into the scene without waiting on a generation. Both reads go out together, so the fallback costs nothing in time.
+- **Works on a phone.** Below 900px the scene panel (hierarchy, inspector, bone attachment) becomes a drawer behind the ☰ button in the toolbar rather than disappearing, and the toolbar scrolls horizontally instead of pushing the canvas off screen. Every control is a real button with a focus state; the camera menu, avatar picker and shortcuts panel trap focus and return it to their trigger on Escape.
### Export vs. save outfit
-There are two ways out. **Export GLB** bakes every visible, non-bone-attached object into one downloadable `scene-compose.glb`. **Save outfit** takes a different path: for an avatar loaded from your three.ws library (a `?avatar=<id>` deep link or the Browse picker), it PATCHes the bone-attached items onto that avatar's record as `appearance.attachments`, each entry a `{ bone, url, name }`, so the outfit rides the avatar everywhere its appearance is applied. Save outfit needs at least one item attached to a bone (up to 8) and an avatar that came from a record; otherwise it points you to Export GLB. The save extends the avatar's existing appearance rather than replacing it, so colors, morphs and layers set in [Avatar Studio](#sec-114) survive it.
+There are two ways out. **Export GLB** bakes every visible, non-bone-attached object into one downloadable `scene-compose.glb`. **Save outfit** takes a different path: for an avatar loaded from your three.ws library (a `?avatar=<id>` deep link or the Browse picker), it PATCHes the bone-attached items onto that avatar's record as `appearance.attachments`, each entry a `{ bone, url, name }`, so the outfit rides the avatar everywhere its appearance is applied. Save outfit needs at least one item attached to a bone (up to 8) and an avatar that came from a record; otherwise it points you to Export GLB. The save extends the avatar's existing appearance rather than replacing it, so colors, morphs and layers set in [Avatar Studio](#sec-115) survive it.
## Walkthrough
-1. Open [/compose](https://three.ws/compose). Load an avatar: paste a model URL, click "Browse" to pick from your gallery, or skip and compose props only.
+1. Open [/compose](https://three.ws/compose). Load an avatar: paste a model URL or an avatar id, click "Browse my avatars" to pick from the public 3D avatars, or skip and compose props only.
2. Choose an intent chip (for example, Accessory), pick a suggested prompt or type your own ("neon visor"), and forge it. Watch the progress bar; the item drops into the scene when it is done.
3. Select the item. In the inspector, open "Attach to Bone", choose Head from the region-grouped list, and click Attach. The visor snaps onto the head.
4. Switch the gizmo to scale (press R) and size it to fit. Use grid snap and proportional lock as needed.
@@ -38674,19 +40859,20 @@ curl -X PATCH 'https://three.ws/api/avatars/<avatarId>' \
- **Bone-attached items are excluded from Export GLB.** Export bakes visible, world-space objects; items parented to a bone belong to the avatar and are saved through Save outfit instead.
- **Generation can take minutes.** Full-quality bakes legitimately run past ten minutes; the studio's ceiling sits above the slowest real generation, and a queued job restarts the wait window. A genuinely failed or timed-out job surfaces an actionable error.
- **Undo is 50 deep.** Transforms, adds, and removes are undoable (Ctrl+Z / Ctrl+Y); a full scene wipe is not a single undo step.
-- **Ownership is client-keyed.** Forge creations and the gallery are scoped to a per-browser client key stored in local storage, so your generations follow the browser without an account.
+- **Ownership is client-keyed.** Forge creations and the gallery are scoped to a per-browser client key stored in local storage, so your generations follow the browser without an account. Until you have forged anything, the strip shows the public community showcase instead.
+- **A locally dropped GLB cannot be saved as an outfit.** A file dragged onto the drop zone lives at a `blob:` URL that dies with the tab, so Save outfit refuses it by name and points you at Export GLB (or uploading it through [/forge](https://three.ws/forge)) rather than persisting a link that breaks on reload.
## Related
-- [Avatar Studio](#sec-114): build the avatar you dress here.
+- [Avatar Studio](#sec-115): build the avatar you dress here.
- [Animation Studio](#sec-092): pose and animate the dressed avatar.
-- [Scene Studio](#sec-368): the full three.js editor for heavier scene authoring.
-- [Restyle Studio](#sec-363): re-skin the forged props before attaching them.
+- [Scene Studio](#sec-373): the full three.js editor for heavier scene authoring.
+- [Restyle Studio](#sec-368): re-skin the forged props before attaching them.
- [/forge](https://three.ws/forge): the text-to-3D generator behind the prompt box.
---
-<a id="sec-149"></a>
+<a id="sec-152"></a>
> **Source:** `docs/concierge.md` · [↑ table of contents](#table-of-contents)
@@ -38794,12 +40980,12 @@ Runnable examples ship with the SDK ([concierge-sdk/examples/](https://github.co
## Related surfaces
- [/walk](/walk): the walking page companion the avatar engine grew from
-- [Share and embed](#sec-373): every other way to put a three.ws creation on your site
-- [MCP](#sec-276): the full catalog of three.ws MCP servers, including this one
+- [Share and embed](#sec-378): every other way to put a three.ws creation on your site
+- [MCP](#sec-277): the full catalog of three.ws MCP servers, including this one
---
-<a id="sec-150"></a>
+<a id="sec-153"></a>
> **Source:** `docs/configuration.md` · [↑ table of contents](#table-of-contents)
@@ -38855,7 +41041,7 @@ After setting this, provision the schema:
npm run db:bootstrap
```
-This runs all four provisioning steps (core schema + indexer + delegations + migrations) and is idempotent — safe to re-run. Do not apply `api/_lib/schema.sql` alone: the base schema does not create the migration-defined tables and leaves a half-provisioned database (see [deployment.md](#sec-171)).
+This runs all four provisioning steps (core schema + indexer + delegations + migrations) and is idempotent — safe to re-run. Do not apply `api/_lib/schema.sql` alone: the base schema does not create the migration-defined tables and leaves a half-provisioned database (see [deployment.md](#sec-174)).
#### `JWT_SECRET`
**Required.** Long random secret used for two purposes: signing session JWTs and (via HKDF) deriving the AES-256-GCM key that encrypts agent wallet private keys.
@@ -39353,7 +41539,7 @@ Before going live, verify the following:
---
-<a id="sec-151"></a>
+<a id="sec-154"></a>
> **Source:** `docs/content/use-cases/README.md` · [↑ table of contents](#table-of-contents)
@@ -39365,11 +41551,11 @@ Five "here's how three.ws solves *your* problem" narratives, one per audience. E
| Audience | File | The job-to-be-done |
| --- | --- | --- |
-| Indie creator | [indie-creator.md](#sec-156) | Turn a selfie or a text prompt into a 3D agent and embed it anywhere. |
-| Game studio | [game-studio.md](#sec-155) | Drop a GLB pipeline, an LLM-driven NPC runtime, and a live multiplayer world into a game. |
-| AI-agent developer | [ai-agent-developer.md](#sec-152) | Give an agent a body, paid endpoints (x402), an MCP/A2A interface, and on-chain identity. |
-| Brand / marketer | [brand-marketer.md](#sec-153) | Put an embeddable, verifiable talking agent on a site, distributed through cloud marketplaces. |
-| Crypto community | [crypto-community.md](#sec-154) | Give a token community a live 3D world, an agent economy, and on-chain reputation. |
+| Indie creator | [indie-creator.md](#sec-159) | Turn a selfie or a text prompt into a 3D agent and embed it anywhere. |
+| Game studio | [game-studio.md](#sec-158) | Drop a GLB pipeline, an LLM-driven NPC runtime, and a live multiplayer world into a game. |
+| AI-agent developer | [ai-agent-developer.md](#sec-155) | Give an agent a body, paid endpoints (x402), an MCP/A2A interface, and on-chain identity. |
+| Brand / marketer | [brand-marketer.md](#sec-156) | Put an embeddable, verifiable talking agent on a site, distributed through cloud marketplaces. |
+| Crypto community | [crypto-community.md](#sec-157) | Give a token community a live 3D world, an agent economy, and on-chain reputation. |
## How to read these (the honesty frame)
@@ -39398,7 +41584,7 @@ Every scenario on these pages is an **example workflow** — clearly labeled "Im
---
-<a id="sec-152"></a>
+<a id="sec-155"></a>
> **Source:** `docs/content/use-cases/ai-agent-developer.md` · [↑ table of contents](#table-of-contents)
@@ -39418,8 +41604,8 @@ A headless agent is a black box. There's no standard way for another agent to di
Four real surfaces give your agent a body, an interface, a wallet, and an identity:
-1. **MCP server** — [`@three-ws/mcp-server`](#sec-276) exposes three.ws tools over MCP (JSON-RPC 2.0 over HTTP) so Claude Desktop, Cursor, Claude Code, or any MCP host can drive an avatar and its tools programmatically.
-2. **x402 paid endpoints** — [native x402](#sec-519) paid endpoints on Base, BSC, and Solana let agents pay each other in USDC for API calls, asset downloads, and skill royalties. Discover and transact via the [bazaar](https://three.ws/x402); **pay-by-name** resolves `@username` / `*.sol` to a recipient so the payer verifies a human-readable name before signing.
+1. **MCP server** — [`@three-ws/mcp-server`](#sec-277) exposes three.ws tools over MCP (JSON-RPC 2.0 over HTTP) so Claude Desktop, Cursor, Claude Code, or any MCP host can drive an avatar and its tools programmatically.
+2. **x402 paid endpoints** — [native x402](#sec-544) paid endpoints on Base, BSC, and Solana let agents pay each other in USDC for API calls, asset downloads, and skill royalties. Discover and transact via the [bazaar](https://three.ws/x402); **pay-by-name** resolves `@username` / `*.sol` to a recipient so the payer verifies a human-readable name before signing.
3. **A2A — agent-to-agent protocol** — an [A2A client + server, MCP bridge, DID resolution, and spending ledger](../README.md#a2a--agent-to-agent-protocol) so agents transact autonomously through delegated signer wallets and EIP-7710 permissions.
4. **On-chain identity** — register the agent as an [ERC-8004 token on any EVM chain or a Metaplex Core asset on Solana](../README.md#on-chain-identity-erc-8004--metaplex-core). Each agent gets a stable ID, an owner wallet, a delegated signer, an IPFS-pinned manifest, and a signed action log. SDKs live in [`sdk/`](../sdk) (`@three-ws/sdk`), with EVM payments in `agent-payments-sdk/` and Solana in `solana-agent-sdk/`.
@@ -39427,8 +41613,8 @@ Four real surfaces give your agent a body, an interface, a wallet, and an identi
> **Imagine a developer, "Vega," who built a market-intelligence agent** and wants it to (a) be callable by other agents, (b) charge for premium queries, and (c) have an identity its callers can trust. Here's the path they'd take.
-1. Vega wires the [`@three-ws/mcp-server`](#sec-276) into their MCP host config (`npx -y @three-ws/mcp-server`) so their agent's tools are reachable over MCP.
-2. They expose the premium "deep snapshot" query as an [x402 paid endpoint](#sec-519): callers hit it, receive a `402` with a price manifest, pay USDC on Base (or Solana), and retry to get the data. The endpoint advertises a `recipient_name` so payers see a readable identity before signing.
+1. Vega wires the [`@three-ws/mcp-server`](#sec-277) into their MCP host config (`npx -y @three-ws/mcp-server`) so their agent's tools are reachable over MCP.
+2. They expose the premium "deep snapshot" query as an [x402 paid endpoint](#sec-544): callers hit it, receive a `402` with a price manifest, pay USDC on Base (or Solana), and retry to get the data. The endpoint advertises a `recipient_name` so payers see a readable identity before signing.
3. They register the agent on-chain with the SDK in [`sdk/`](../sdk) — ERC-8004 on an EVM chain or a Metaplex Core asset on Solana — giving it a stable ID, a delegated signer wallet, and a signed action log. Its [on-chain passport](https://three.ws/a/sol/EXAMPLE_ASSET) renders at `/a/[chain]/[id]`.
4. Another agent discovers Vega's service in the [bazaar](https://three.ws/x402), pays via x402, and consumes it over A2A — agents paying agents, settled in USDC, with both identities verifiable on-chain.
5. **Deliverable:** an embodied, MCP-callable agent with a paid endpoint and a forgery-proof on-chain identity — a real economic actor other agents can find, trust, and pay.
@@ -39439,14 +41625,14 @@ A standards-based interface (MCP + A2A), a working USDC payment rail (x402 on Ba
## Next step / CTA
-- Start: [MCP setup](#sec-276) · [x402 docs](#sec-519) · [SDK docs](#sec-369) · register via [Register On-Chain](#sec-456).
+- Start: [MCP setup](#sec-277) · [x402 docs](#sec-544) · [SDK docs](#sec-374) · register via [Register On-Chain](#sec-462).
- Browse: the [x402 bazaar](https://three.ws/x402) and [MCP Registry listing](https://registry.modelcontextprotocol.io/?q=three.ws).
- **Social spotlight angle (G03):** "Your headless agent → MCP-callable, x402-payable, and on-chain in an afternoon."
- `[REAL CASE STUDY — fill on consent: a developer whose agent earned or paid via x402 in production.]`
---
-<a id="sec-153"></a>
+<a id="sec-156"></a>
> **Source:** `docs/content/use-cases/brand-marketer.md` · [↑ table of contents](#table-of-contents)
@@ -39468,7 +41654,7 @@ Four real capabilities cover embodiment, reach, and trust:
1. **Embeddable talking agent widget** — the [`<agent-3d>` web component](../README.md#web-component--embedding) and the [talking-agent widget](https://three.ws/studio) put a conversational 3D brand character on any page with one snippet. Pin it as a floating bubble (`mode="floating"`) so it persists as visitors scroll. Open Graph + oEmbed mean shared links get rich previews.
2. **On-chain verifiable identity** — register the brand agent as an [ERC-8004 token or Metaplex Core asset](../README.md#on-chain-identity-erc-8004--metaplex-core) with a stable ID, owner wallet, and signed action log. Its [passport](https://three.ws/a/sol/EXAMPLE_ASSET) is a public proof that *this* is the official agent. Bind a [`*.threews.sol` name](../README.md#sns--threewssol-subdomains) so every surface shows a human-readable identity instead of a raw wallet.
-3. **Cloud marketplace distribution** — three.ws is an **AWS Partner** with an **AWS Marketplace SaaS listing** (in review; see [docs/aws-marketplace.md](#sec-122) and [three.ws/aws](https://three.ws/aws)) and is **live on Alibaba Cloud Marketplace**. That's a procurement path for enterprise buyers — a marketplace listing, not a cloud-vendor endorsement.
+3. **Cloud marketplace distribution** — three.ws is an **AWS Partner** with an **AWS Marketplace SaaS listing** (in review; see [docs/aws-marketplace.md](#sec-123) and [three.ws/aws](https://three.ws/aws)) and is **live on Alibaba Cloud Marketplace**. That's a procurement path for enterprise buyers — a marketplace listing, not a cloud-vendor endorsement.
4. **IBM watsonx Granite demos** — the [`/ibm/*` showcase](https://three.ws/ibm) demonstrates brand-relevant AI surfaces (semantic agent maps, forecasting, a Guardian governance "trust layer") **built on IBM watsonx.ai** running IBM Granite. three.ws is an IBM Business Partner; the public `/ibm` demos are independent developer tools, **not** official IBM products or endorsements.
## Example workflow (hypothetical)
@@ -39488,7 +41674,7 @@ Four real capabilities cover embodiment, reach, and trust:
width="340px" height="440px"
></agent-3d>
```
-3. She [registers the agent on-chain](#sec-456) (Metaplex Core on Solana), binds `brand.threews.sol`, and links the public [passport](https://three.ws/a/sol/EXAMPLE_ASSET) from the site footer as a "verified official agent" badge — so look-alikes can't credibly impersonate it.
+3. She [registers the agent on-chain](#sec-462) (Metaplex Core on Solana), binds `brand.threews.sol`, and links the public [passport](https://three.ws/a/sol/EXAMPLE_ASSET) from the site footer as a "verified official agent" badge — so look-alikes can't credibly impersonate it.
4. For enterprise procurement, she points buyers at the [AWS Marketplace listing](https://three.ws/aws) (a listing, not an endorsement).
5. **Deliverable:** a premium, on-brand talking agent on every page, provably the official one via its on-chain passport, with an enterprise procurement path.
@@ -39498,14 +41684,14 @@ A conversational 3D brand presence that's easy to embed and share, plus a public
## Next step / CTA
-- Start: [Widget Studio](https://three.ws/studio) → [Register On-Chain](#sec-456) → claim a name at [`/threews/claim`](https://three.ws/threews/claim).
-- Enterprise: [AWS Marketplace listing](#sec-122) · [Alibaba Cloud listing](https://marketplace.alibabacloud.com/products/56724001/sgcmfw00036800.html) · explore Granite on watsonx.ai at [/ibm](https://three.ws/ibm).
+- Start: [Widget Studio](https://three.ws/studio) → [Register On-Chain](#sec-462) → claim a name at [`/threews/claim`](https://three.ws/threews/claim).
+- Enterprise: [AWS Marketplace listing](#sec-123) · [Alibaba Cloud listing](https://marketplace.alibabacloud.com/products/56724001/sgcmfw00036800.html) · explore Granite on watsonx.ai at [/ibm](https://three.ws/ibm).
- **Social spotlight angle (G03):** "A talking brand agent you can *prove* is official — embedded everywhere, verifiable on-chain."
- `[REAL CASE STUDY — fill on consent: a brand that deployed a verified on-site agent and what it changed.]`
---
-<a id="sec-154"></a>
+<a id="sec-157"></a>
> **Source:** `docs/content/use-cases/crypto-community.md` · [↑ table of contents](#table-of-contents)
@@ -39526,7 +41712,7 @@ A token's community lives in scattered chat apps and a price chart. There's no s
Three real surfaces turn a token into a living world with its own economy:
1. **Coin Communities — a live 3D world per token** — [`/communities`](https://three.ws/communities) and [`/play`](https://three.ws/play) give every Solana token its own shared 3D world. Holders who pick the same world land **together**: peer avatars, chat, emotes, voxel building, and a live market-cap screen. The [`$THREE` home town](https://three.ws/play) is the flagship world.
-2. **An agent economy — agents paying agents** — inside the `$THREE` home town, autonomous agents transact **on-chain via x402** (agents paying each other in USDC for services), demonstrating a real agent-exchange economy, not a simulation. This builds on the platform's [native x402 rails](#sec-519) (Base, BSC, Solana).
+2. **An agent economy — agents paying agents** — inside the `$THREE` home town, autonomous agents transact **on-chain via x402** (agents paying each other in USDC for services), demonstrating a real agent-exchange economy, not a simulation. This builds on the platform's [native x402 rails](#sec-544) (Base, BSC, Solana).
3. **On-chain reputation & identity** — agents and contributions carry [ERC-8004 / Metaplex Core identity](../README.md#on-chain-identity-erc-8004--metaplex-core) with signed action logs and a [reputation registry](https://three.ws/reputation), plus a pump.fun-native launch/visualize toolset at [`/pumpfun`](https://three.ws/pumpfun) and [`/pump-visualizer`](https://three.ws/pump-visualizer).
## Example workflow (hypothetical)
@@ -39535,7 +41721,7 @@ Three real surfaces turn a token into a living world with its own economy:
1. A community lead opens [`/communities`](https://three.ws/communities), finds the `$THREE` world, and shares the direct link. Holders open it and land in the same [3D `$THREE` home town](https://three.ws/play) — they see each other's avatars, chat, drop emotes, and build with voxels while a live market-cap screen ticks in-world. (`$THREE` CA: `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`.)
2. In the home town, holders watch the resident agents pay each other on-chain via x402 — a working agent-exchange where one agent buys a service from another in USDC, settled on Solana — a concrete demo of the agent economy the community is part of.
-3. Active contributors register agents with [on-chain identity](#sec-456), accruing a signed action history and a [reputation](https://three.ws/reputation) score that can't be forged — a durable signal of who actually showed up.
+3. Active contributors register agents with [on-chain identity](#sec-462), accruing a signed action history and a [reputation](https://three.ws/reputation) score that can't be forged — a durable signal of who actually showed up.
4. The community uses [`/pump-visualizer`](https://three.ws/pump-visualizer) to surface live `$THREE` activity inside the world, tying market events to the shared space.
5. **Deliverable:** a persistent, multiplayer `$THREE` world where holders gather, a live agent economy they can watch settle on-chain, and an on-chain reputation layer that rewards real participation.
@@ -39546,13 +41732,13 @@ A shared 3D home for the token's holders, a real (not mocked) on-chain agent-exc
## Next step / CTA
- Start: [`/communities`](https://three.ws/communities) → the [`$THREE` home town](https://three.ws/play) → [`/pumpfun`](https://three.ws/pumpfun) and [`/pump-visualizer`](https://three.ws/pump-visualizer).
-- Build: [x402 docs](#sec-519) for the agent-economy rails · [Register On-Chain](#sec-456) for reputation.
+- Build: [x402 docs](#sec-544) for the agent-economy rails · [Register On-Chain](#sec-462) for reputation.
- **Social spotlight angle (G03):** "Watch two agents pay each other on-chain inside a live 3D `$THREE` town — your community's home."
- `[REAL CASE STUDY — fill on consent: a community that gathered in its 3D world and what changed for engagement.]`
---
-<a id="sec-155"></a>
+<a id="sec-158"></a>
> **Source:** `docs/content/use-cases/game-studio.md` · [↑ table of contents](#table-of-contents)
@@ -39593,13 +41779,13 @@ A character that renders with production-grade glTF handling, converses through
## Next step / CTA
- Start: [`/app`](https://three.ws/app) to render a GLB, then [`/walk`](https://three.ws/walk) for the shared world. The Colyseus server lives in `multiplayer/`.
-- Learn: [Write a Custom Skill](#sec-426) · [Agent System docs](#sec-064) · [Skill spec](../specs/SKILL_SPEC.md).
+- Learn: [Write a Custom Skill](#sec-432) · [Agent System docs](#sec-064) · [Skill spec](../specs/SKILL_SPEC.md).
- **Social spotlight angle (G03):** "An NPC that emotes and hands out quests through a real tool-loop — plus a shared world players walk into together."
- `[REAL CASE STUDY — fill on consent: a studio that shipped a three.ws-powered NPC or multiplayer hub.]`
---
-<a id="sec-156"></a>
+<a id="sec-159"></a>
> **Source:** `docs/content/use-cases/indie-creator.md` · [↑ table of contents](#table-of-contents)
@@ -39653,13 +41839,13 @@ A real, embedded, conversational 3D avatar that loads in any modern browser. The
## Next step / CTA
- Start: [`/scan`](https://three.ws/scan) (selfie) or `/forge` (text) → [Embed Editor](https://three.ws/embed).
-- Learn: [Build Your First Agent](#sec-435) · [Embed on Your Website](#sec-431).
+- Learn: [Build Your First Agent](#sec-441) · [Embed on Your Website](#sec-437).
- **Social spotlight angle (G03):** "From one selfie to a talking 3D you, embedded in your bio — no Blender."
- `[REAL CASE STUDY — fill on consent: an indie creator who shipped an embedded agent and the response it got.]`
---
-<a id="sec-157"></a>
+<a id="sec-160"></a>
> **Source:** `docs/contributing.md` · [↑ table of contents](#table-of-contents)
@@ -39734,7 +41920,7 @@ npm run dev
Most features work without the optional services. The app degrades gracefully, so basic 3D viewer work, skill development, and UI changes don't require any backend credentials.
-For full backend setup — R2 storage, environment variables, and how the app is deployed — see the [Configuration Reference](#sec-150) and the [Deployment & Self-Hosting](#sec-171) guide.
+For full backend setup — R2 storage, environment variables, and how the app is deployed — see the [Configuration Reference](#sec-153) and the [Deployment & Self-Hosting](#sec-174) guide.
---
@@ -39768,7 +41954,7 @@ src/
└── components/ — vhtml JSX components (string-based, no virtual DOM)
```
-See the [Architecture Overview](#sec-254) for a deeper understanding of how these pieces connect.
+See the [Architecture Overview](#sec-255) for a deeper understanding of how these pieces connect.
---
@@ -39936,7 +42122,7 @@ Skills are the best way to extend three.ws without touching core code. A skill i
1. **Use the template.** Copy `examples/skills/solana-wallet/` as your starting point — its `manifest.json`, `tools.json`, `handlers.js`, and `SKILL.md` demonstrate the minimal structure a skill needs.
-2. **Build your skill.** See the [Skills documentation](#sec-381) for the full format, lifecycle hooks, and message API.
+2. **Build your skill.** See the [Skills documentation](#sec-387) for the full format, lifecycle hooks, and message API.
3. **Host it.** GitHub Pages, Vercel, Netlify, or any static CDN works. The URL just needs to be publicly accessible over HTTPS.
@@ -39972,7 +42158,7 @@ Open a [GitHub issue](https://github.com/nirholas/three.ws/issues/new) and inclu
Check [existing issues](https://github.com/nirholas/three.ws/issues) before opening a new one to avoid duplicates.
-**Security vulnerabilities:** Do NOT open a public issue. Follow the responsible disclosure process described in the [Security documentation](#sec-370). Public disclosure of an unpatched vulnerability puts all users at risk.
+**Security vulnerabilities:** Do NOT open a public issue. Follow the responsible disclosure process described in the [Security documentation](#sec-375). Public disclosure of an unpatched vulnerability puts all users at risk.
---
@@ -39999,7 +42185,7 @@ By contributing, you agree that your contributions are provided under the terms
---
-<a id="sec-158"></a>
+<a id="sec-161"></a>
> **Source:** `docs/cookbook/asset-quality-gate.md` · [↑ table of contents](#table-of-contents)
@@ -40166,7 +42352,7 @@ build on any of them. They are a good backlog for whatever ships the assets.
---
-<a id="sec-159"></a>
+<a id="sec-162"></a>
> **Source:** `docs/cookbook/mcp-3d-tool.md` · [↑ table of contents](#table-of-contents)
@@ -40305,7 +42491,7 @@ endpoints.
---
-<a id="sec-160"></a>
+<a id="sec-163"></a>
> **Source:** `docs/cookbook/parallel-asset-pack.md` · [↑ table of contents](#table-of-contents)
@@ -40474,7 +42660,7 @@ machine. Useful for picking a triangle budget before you commit to one.
---
-<a id="sec-161"></a>
+<a id="sec-164"></a>
> **Source:** `docs/cookbook/text-to-3d-cli.md` · [↑ table of contents](#table-of-contents)
@@ -40623,7 +42809,7 @@ the lane is queued, which is exactly when `retryAfter` starts mattering.
---
-<a id="sec-162"></a>
+<a id="sec-165"></a>
> **Source:** `docs/copy-trading.md` · [↑ table of contents](#table-of-contents)
@@ -40638,9 +42824,9 @@ Copy trading on three.ws lets one wallet follow another wallet's real trades. Th
Both are Solana-native. Both run on `mainnet` and `devnet`. Neither is a paper-trading mode: neither engine has a simulation layer or a synthetic fill anywhere in it. Read [Simulated versus executed](#simulated-versus-executed) before you enable anything.
-If you want to feel a leader's edge before committing money, that is a *separate* surface: [Ghost-copy](#sec-232) replays a leader's real closed trades against a wallet that does not exist. It never touches either engine below and never produces an intent.
+If you want to feel a leader's edge before committing money, that is a *separate* surface: [Ghost-copy](#sec-233) replays a leader's real closed trades against a wallet that does not exist. It never touches either engine below and never produces an intent.
-Related reading: [Smart Money Radar](#sec-383) for the first-party wallet reputation graph, [the trading surfaces](#sec-409) for the screeners and the trading cockpit these leaders trade from, [agent wallets](#sec-072) for the custody and spend-policy model, and [signal marketplace](#sec-377) for the paid-feed variant that reuses the same guarded executor.
+Related reading: [Smart Money Radar](#sec-389) for the first-party wallet reputation graph, [the trading surfaces](#sec-415) for the screeners and the trading cockpit these leaders trade from, [agent wallets](#sec-072) for the custody and spend-policy model, and [signal marketplace](#sec-382) for the paid-feed variant that reuses the same guarded executor.
---
@@ -40650,7 +42836,7 @@ State this to yourself before you touch a control:
- **The agent mirror executes with real funds.** When a leader agent's trade confirms on-chain, `api/_lib/agent-mirror.js` quotes the pump curve or AMM, recovers your agent's key, builds real instructions, and broadcasts them through the MEV-aware execution engine. The resulting signature is a real Solana transaction. There is no dry-run flag, no shadow mode, and no "test" sizing.
- **Copier subscriptions never execute.** `api/cron/copy-fanout.js` writes a row into `copy_executions` with a planned size and a reason. That is the whole action. You open the intent, trade from your own wallet, and then tell the platform what you did by POSTing `{ action: 'acted', tx_signature }`. Marking an intent `acted` records history. It moves no funds, and the platform never holds your keys on this path.
-- **Ghost-copy is explicitly paper, and lives outside both engines.** [/ghost-copy](https://three.ws/ghost-copy) replays a leader's already-closed on-chain round-trips against a hypothetical budget. It shares the sizing function (`planCopyOrder`) with the copier path so the numbers are comparable, but it writes nothing, signs nothing, produces no intent, and cannot be enabled. Every response is labelled `paper: true` and carries an `honesty` block. See [ghost-copy](#sec-232).
+- **Ghost-copy is explicitly paper, and lives outside both engines.** [/ghost-copy](https://three.ws/ghost-copy) replays a leader's already-closed on-chain round-trips against a hypothetical budget. It shares the sizing function (`planCopyOrder`) with the copier path so the numbers are comparable, but it writes nothing, signs nothing, produces no intent, and cannot be enabled. Every response is labelled `paper: true` and carries an `honesty` block. See [ghost-copy](#sec-233).
- **The leaderboard and track records are computed from real fills only.** `api/_lib/mirror-stats.js` and `api/mirror/leaderboard.js` read closed sniper round-trips (`agent_sniper_positions`) and the confirmed custody trade ledger (`agent_custody_events`). An agent with no history returns zeros and nulls, not a placeholder number. Losing agents appear with their losses.
- **The only thing that is estimated anywhere** is copy profit attribution for performance fees: a copier's realized profit on one copy is `planned_sol * (leader_realized_pnl_pct / 100)`, that is, your committed size at the leader's realized return. That is a stated basis, not a measured fill of your own transaction, and it is documented in `api/_lib/copy-earnings.js`.
@@ -40669,11 +42855,19 @@ Money-moving actions are yours to confirm. Nothing on these pages spends without
| `network` | `mainnet`, `devnet` | `mainnet` |
| `sort` | `score`, `pnl`, `followers`, `volume`, `winrate` | `score` |
| `limit` | 1 to 50 | 25 |
+| `settled_min` | 0 to 1000 | 0 |
### Who is eligible
An agent appears if it is public (`is_public <> false`), not deleted, and has **either** at least one closed sniper position **or** at least one confirmed discretionary trade on that network. An agent that only trades discretionarily still ranks, with volume and no realized P&L. The candidate scan is capped at 500 rows before scoring.
+`settled_min` narrows that to agents with at least that many **closed** round-trips, before the ranking is windowed by `limit`. Ask for it when your surface cannot use an agent without a realized track record. [The Clip Director](#sec-143) is the case in point: it mints a card from a closed trade, so an agent with none is useless to it. Filtering client side instead is a trap, and it bit us: the composite score does not correlate with having settled trades, so the only eligible agent ranked below the caller's window and the page reported that nobody had ever closed a trade.
+
+```bash
+# Only agents with a realized track record, best composite score first
+curl -s 'https://three.ws/api/mirror/leaderboard?settled_min=1&limit=50'
+```
+
### The weighting, exactly as coded
```
@@ -40714,6 +42908,7 @@ Response shape:
"data": {
"network": "mainnet",
"sort": "score",
+ "settled_min": 0,
"leaders": [
{
"rank": 1,
@@ -41016,7 +43211,7 @@ Response:
The directory is a static, deduplicated snapshot shipped with the API (`api/_lib/copy/smart-wallets.json`) and regenerated by `scripts/build-smart-wallets.mjs`. Wallet identity and 30-day performance only, never token holdings. If the snapshot file is missing the endpoint returns an empty list rather than failing.
-For first-party wallet reputation earned from three.ws's own outcome ledger rather than an external taxonomy, use [Smart Money Radar](#sec-383).
+For first-party wallet reputation earned from three.ws's own outcome ledger rather than an external taxonomy, use [Smart Money Radar](#sec-389).
---
@@ -41050,7 +43245,7 @@ Both engines are reachable without a browser:
- `packages/strategies` wraps `POST /api/copy/subscriptions` and `/api/copy/executions` for programmatic strategy clients. See [its README](../packages/strategies/README.md).
- Bearer tokens work on every authenticated route above and are not CSRF-gated, which is what makes an autonomous agent a first-class copier here.
-See [the MCP reference](#sec-276) for wiring these into a client.
+See [the MCP reference](#sec-277) for wiring these into a client.
---
@@ -41065,7 +43260,7 @@ See [the MCP reference](#sec-276) for wiring these into a client.
---
-<a id="sec-163"></a>
+<a id="sec-166"></a>
> **Source:** `docs/cosmos.md` · [↑ table of contents](#table-of-contents)
@@ -41085,6 +43280,10 @@ Cosmos runs on NVIDIA's Cosmos World Foundation Model family. The endpoint (`api
The lane reuses the platform `NVIDIA_API_KEY` (the free NIM tier). When that key is absent, the lane reports itself unconfigured (503) and the page degrades gracefully: the avatar still stands on a designed, slowly shifting aurora backdrop instead of a blank void.
+NVIDIA retires a hosted preview model without retiring its gateway path: the route keeps answering, and only an authenticated submit reveals that the function behind it is gone for your account. So the submit walks the published `cosmos-predict` routes in order and only gives up when every rung is gone, at which point it answers `503 {"error":"lane_unavailable"}` and the page shows the same designed offline state as an unconfigured deployment. Setting `NVIDIA_COSMOS_INVOKE_URL` opts out of the chain and pins one endpoint (a specific model, or a self-hosted Cosmos NIM), which is the lever for pointing the lane at a live function without a code change. Confirm what an account can actually reach with `node scripts/verify-nvidia-cosmos.mjs`.
+
+Upstream detail never reaches the browser. The gateway phrases a retired model as `Function '<uuid>': Not found for account '<id>'`; that is operator diagnostics (it carries the account id), so it is logged server-side and the caller gets a sentence it can act on instead.
+
On the page (`src/cosmos.js`), the avatar is a Google `<model-viewer>` with a transparent background. Five humanoid avatars ship bundled for instant selection (Aria, Kai, Michelle, X-Bot, Mona), and you can bring your own. The generate flow is real async with no fake timers: submit to `POST /api/cosmos`, then poll `GET /api/cosmos?job=<id>` every four seconds (with a five-minute ceiling), driving a real elapsed-based progress state. When the clip is ready it plays on canplay as a looping backdrop behind the avatar, a regenerate control appears, and the clip is available to download.
## Walkthrough
@@ -41095,6 +43294,7 @@ On the page (`src/cosmos.js`), the avatar is a Google `<model-viewer>` with a tr
4. Optionally set a seed for a reproducible render.
5. Click Generate. A real progress state runs while the NVCF job renders; expect roughly 60 to 120 seconds on the free tier.
6. When the world lands it plays behind your avatar. Preview it, regenerate with a new prompt or seed, or download the clip.
+7. Share copies a link that carries the finished clip, the avatar, the prompt, and the seed (`?world=…&avatar=…&prompt=…&seed=…`), so whoever opens it lands on the world already playing rather than an empty stage.
## Examples
@@ -41143,19 +43343,21 @@ else {
- **Prompt** must be 3 to 300 characters; an optional integer `seed` makes a render reproducible.
- **Render time** is roughly 60 to 120 seconds on the shared free tier; the client shows a real elapsed progress state and gives up after five minutes with a "try a simpler prompt" message.
- **Unconfigured (503)**: when `NVIDIA_API_KEY` is absent, the page keeps the avatar on a designed aurora backdrop and tells you generation is offline. No mock clip is ever shown.
+- **Lane unavailable (503, `lane_unavailable`)**: the key is present but NVIDIA has retired every hosted `cosmos-predict` route this account can reach. Same designed offline state, and deliberately no Retry button: the request cannot succeed until an operator points `NVIDIA_COSMOS_INVOKE_URL` at a live function.
- **Rate limited (429)** and **invalid key (401)** surface with honest messages and, where provided, a retry-after hint.
+- **Unplayable clip**: a durable URL that will not decode drops the stage out of its finished state and offers a retry, rather than leaving a "done" stage with nothing in it.
- Output is a durable MP4; the avatar is a standard GLB rendered with `<model-viewer>`.
- Rate limits are per client IP on the shared 3D generation buckets.
## Related
-- [Forge](#sec-224) makes the 3D avatars and objects you place in a Cosmos world.
-- [Avatar creation](#sec-108) and [the trait-based avatar builder](#sec-135) for building and dressing avatars.
+- [Forge](#sec-225) makes the 3D avatars and objects you place in a Cosmos world.
+- [Avatar creation](#sec-109) and [the trait-based avatar builder](#sec-137) for building and dressing avatars.
- Pages: [/create](https://three.ws/create), [/gallery](https://three.ws/gallery), [/scene](https://three.ws/scene).
---
-<a id="sec-164"></a>
+<a id="sec-167"></a>
> **Source:** `docs/creator-portfolio.md` · [↑ table of contents](#table-of-contents)
@@ -41303,7 +43505,7 @@ Two card-level actions let a visitor take a copy of what they find:
handler [api/avatars/fork.js](../api/avatars/fork.js)): clones the GLB,
its agent, and a fresh wallet into the viewer's account. Downstream, forks
of a paid avatar are what produce the `royalty_paid` notifications
- documented in [Notifications](#sec-292).
+ documented in [Notifications](#sec-293).
- **Fork an agent** (`POST /api/marketplace/agents/:id/fork`, handler
[api/marketplace/[action].js](../api/marketplace/[action].js)): clones
a *published* agent into the viewer's account; unpublished agents render
@@ -41342,19 +43544,19 @@ unfurls with the creator's actual name and stats.
## Related pages
-- [The social layer](#sec-385): the follow graph, feed, and
+- [The social layer](#sec-391): the follow graph, feed, and
rankings this page plugs into.
-- [Notifications](#sec-292): the follow, remix, sale, and royalty
+- [Notifications](#sec-293): the follow, remix, sale, and royalty
events a portfolio generates for its owner.
-- [Remix economy](#sec-360): what happens when someone remixes a creation
+- [Remix economy](#sec-365): what happens when someone remixes a creation
they found here.
-- [Forge](#sec-224), [Widgets](#sec-505),
- [Marketplace](#sec-269): the creation surfaces whose output the
+- [Forge](#sec-225), [Widgets](#sec-511),
+ [Marketplace](#sec-270): the creation surfaces whose output the
portfolio aggregates.
---
-<a id="sec-165"></a>
+<a id="sec-168"></a>
> **Source:** `docs/crews.md` · [↑ table of contents](#table-of-contents)
@@ -41536,7 +43738,7 @@ player who is already social in the world finds the group surface.
---
-<a id="sec-166"></a>
+<a id="sec-169"></a>
> **Source:** `docs/crypto-api.md` · [↑ table of contents](#table-of-contents)
@@ -42583,7 +44785,7 @@ curl -s "https://three.ws/api/crypto/airdrops?address=<wallet>" \
---
-<a id="sec-167"></a>
+<a id="sec-170"></a>
> **Source:** `docs/custody.md` · [↑ table of contents](#table-of-contents)
@@ -42609,7 +44811,7 @@ Limits live per agent and are owner-configurable from the wallet hub (API: `GET/
Enforcement is uniform: the same policy module gates **every** outbound path — withdrawals, x402 payments, sniper buys, trades. A transaction that would breach a cap is refused with a structured `403` before signing; no funds move. Limits are opt-in (`null` means uncapped) — but they're hard once set. SPL tokens that can't be priced in USD are governed by the allowlist instead, so a price-feed outage can never strand your own withdrawal.
-You can also write these rules in plain English — see [financial-controls](#sec-219) for the natural-language rules layer and the real-time defense behaviors built on top of this same enforcement point.
+You can also write these rules in plain English — see [financial-controls](#sec-221) for the natural-language rules layer and the real-time defense behaviors built on top of this same enforcement point.
## Freeze: the kill switch that can't trap you
@@ -42668,14 +44870,14 @@ Every step of recovery and inheritance writes to the custody trail and the audit
## Related
-- [Financial controls](#sec-219) — plain-English spend rules and real-time wallet defense on these rails
-- [Trading surfaces](#sec-409) — Mission Control executes through this same guarded path
-- [The trading experiment](#sec-407) — an autonomous agent operating inside these limits, journaled
-- [x402](#sec-519) — the payment protocol these wallets spend over
+- [Financial controls](#sec-221) — plain-English spend rules and real-time wallet defense on these rails
+- [Trading surfaces](#sec-415) — Mission Control executes through this same guarded path
+- [The trading experiment](#sec-413) — an autonomous agent operating inside these limits, journaled
+- [x402](#sec-544) — the payment protocol these wallets spend over
---
-<a id="sec-168"></a>
+<a id="sec-171"></a>
> **Source:** `docs/daily-forge.md` · [↑ table of contents](#table-of-contents)
@@ -42774,14 +44976,14 @@ console.log(themeIndex(new Date().toISOString().slice(0, 10), 24));
## Related
- [The 3D pipeline](#sec-003) and [3D API](#sec-001): the text-to-3D forge the free lane rides
-- [Forge background generation](#sec-221): the job and polling model
+- [Forge background generation](#sec-222): the job and polling model
- [AR and WebXR](#sec-099): the Scene Viewer and Quick Look handoff
-- [Quick start](#sec-356): the general free-forge onboarding
+- [Quick start](#sec-361): the general free-forge onboarding
- Pages: [/daily](https://three.ws/daily) · [/forge](https://three.ws/forge) · [/ar/studio](https://three.ws/ar/studio)
---
-<a id="sec-169"></a>
+<a id="sec-172"></a>
> **Source:** `docs/daily-match.md` · [↑ table of contents](#table-of-contents)
@@ -42914,11 +45116,11 @@ falls back to `type`.
Related docs: [agent-sniper.md](#sec-061) (where the trade and P&L
columns come from), [agent-skills.md](#sec-060) (skill sales),
-[pump-launcher.md](#sec-333) (launches).
+[pump-launcher.md](#sec-339) (launches).
---
-<a id="sec-170"></a>
+<a id="sec-173"></a>
> **Source:** `docs/demo-routes.md` · [↑ table of contents](#table-of-contents)
@@ -43145,7 +45347,7 @@ the 200s above still come from the 2026-08-05 curl sweep.
---
-<a id="sec-171"></a>
+<a id="sec-174"></a>
> **Source:** `docs/deployment.md` · [↑ table of contents](#table-of-contents)
@@ -43516,7 +45718,7 @@ The `crons` array in `vercel.json` declares every scheduled job (economy tick, o
| `/api/cron/run-dca` | Every hour | Execute scheduled DCA strategies |
| `/api/cron/run-subscriptions` | Every hour | Process recurring subscriptions |
-The container does **not** schedule these itself — you need an external scheduler hitting the endpoints. On Cloud Run that is Cloud Scheduler; self-hosters can point any HTTP cron (Cloud Scheduler, cron-job.org, Upstash QStash) at `/api/cron/*` with the `CRON_SECRET` bearer, or run `scripts/economy-heartbeat.mjs` as a long-lived pinger that reads `vercel.json` and fires every due cron each minute. See the [economy heartbeat](#sec-178) guide for the driver patterns.
+The container does **not** schedule these itself — you need an external scheduler hitting the endpoints. On Cloud Run that is Cloud Scheduler; self-hosters can point any HTTP cron (Cloud Scheduler, cron-job.org, Upstash QStash) at `/api/cron/*` with the `CRON_SECRET` bearer, or run `scripts/economy-heartbeat.mjs` as a long-lived pinger that reads `vercel.json` and fires every due cron each minute. See the [economy heartbeat](#sec-181) guide for the driver patterns.
### Static asset caching
@@ -43581,7 +45783,7 @@ does not use them: it reads and writes the ERC-8004 reference
`ValidationRegistryUpgradeable`, which has no validator allow-list. A validator is
authorized per agent by the agent's owner opening a request that names it (or by
the owner approving it as an operator). See
-[erc8004/validation-attestation.md](#sec-186), and verify
+[erc8004/validation-attestation.md](#sec-189), and verify
any configured registry address with `npm run verify:erc8004-validation`.
---
@@ -43643,7 +45845,7 @@ docker run -p 8080:8080 \
- **Logs:** on Cloud Run, `gcloud run services logs read three-ws-api --region us-central1` or Cloud Logging; on any other host, that platform's log stream.
- **Request duration / timeout:** the Cloud Run service runs with a 900s request timeout; set the equivalent on your host so long renders (avatar thumbnails, 3D generation) don't get cut off.
-- **Uptime:** the `uptime-check` cron ([api/cron/uptime-check.js](../api/cron/uptime-check.js)) watches the economy and subsystems and escalates to the ops Telegram channel — see the [economy heartbeat](#sec-178) guide.
+- **Uptime:** the `uptime-check` cron ([api/cron/uptime-check.js](../api/cron/uptime-check.js)) watches the economy and subsystems and escalates to the ops Telegram channel — see the [economy heartbeat](#sec-181) guide.
### Database monitoring
@@ -43738,7 +45940,7 @@ Upstash REST API uses HTTPS — no ports to open. If you see connection errors,
---
-<a id="sec-172"></a>
+<a id="sec-175"></a>
> **Source:** `docs/deployments.md` · [↑ table of contents](#table-of-contents)
@@ -43750,7 +45952,7 @@ It answers three questions at a glance: how big is the on-chain agent population
Every row is a real on-chain registration. There are no synthetic entries and no seeded demo rows. When a network is quiet the feed is honestly empty, and when a signal was never measured the UI says so rather than rendering a zero.
-Related reading: [ERC-8004 blockchain identity](#sec-185) for the standard, the registry contracts, and how to register; [deploying agents on-chain](#sec-301) for the Solana Metaplex Core path; [agent reputation on Solana](#sec-387) for the trust layer built on top of a Solana identity.
+Related reading: [ERC-8004 blockchain identity](#sec-188) for the standard, the registry contracts, and how to register; [deploying agents on-chain](#sec-304) for the Solana Metaplex Core path; [agent reputation on Solana](#sec-393) for the trust layer built on top of a Solana identity.
---
@@ -43765,7 +45967,7 @@ This surface is **not EVM-only**. Solana is folded into the same feed as a first
Two Solana upstreams feed it: three.ws's own Metaplex Core mints, and the external Metaplex Agent Registry. Details in [where the data comes from](#where-the-data-comes-from).
-What lives elsewhere: the *creation* path for a Solana identity is documented in [deploying agents on-chain](#sec-301) (the single-agent, user-signed flow is in [Solana agents](#sec-388)), and Solana reputation and attestations are in [agent reputation on Solana](#sec-387). This page is only the index and the feed.
+What lives elsewhere: the *creation* path for a Solana identity is documented in [deploying agents on-chain](#sec-304) (the single-agent, user-signed flow is in [Solana agents](#sec-394)), and Solana reputation and attestations are in [agent reputation on Solana](#sec-393). This page is only the index and the feed.
---
@@ -43825,7 +46027,7 @@ A second stage, **metadata enrichment**, takes up to 25 rows per run whose metad
Metadata is attacker-controlled: it is whatever the agent's owner published on-chain. Two consequences are load-bearing. Enrichment refuses to let `meta.active` alone decide visibility, and a name or description containing a slur sets `active = false` so the row is withheld from every public feed (this page included). A failed fetch records `metadata_error` and moves on rather than retrying in a loop.
-The Identity Registry is deployed deterministically via CREATE2, so it has one address per network class, the same on every chain. See [ERC-8004](#sec-185) for the addresses and the contract surface.
+The Identity Registry is deployed deterministically via CREATE2, so it has one address per network class, the same on every chain. See [ERC-8004](#sec-188) for the addresses and the contract surface.
### 2. Solana: three.ws's own Metaplex Core mints
@@ -43975,7 +46177,7 @@ The network toggle derives its chain-id sets from that table at import time, so
---
-<a id="sec-173"></a>
+<a id="sec-176"></a>
> **Source:** `docs/developer-platform.md` · [↑ table of contents](#table-of-contents)
@@ -43995,8 +46197,8 @@ The browser UI for all of this lives in the dashboard:
Base URL: `https://three.ws`
-Related docs: [MCP integration](#sec-276), [API reference](#sec-096),
-[Authentication](#sec-103), [x402 developer tools](#sec-512).
+Related docs: [MCP integration](#sec-277), [API reference](#sec-096),
+[Authentication](#sec-103), [x402 developer tools](#sec-537).
---
@@ -44036,7 +46238,7 @@ key, no CSRF.
## API keys
API keys are bearer credentials for machine clients: the MCP server at
-`/api/mcp` (see [MCP integration](#sec-276)) and the account-scoped REST
+`/api/mcp` (see [MCP integration](#sec-277)) and the account-scoped REST
endpoints that accept `Authorization: Bearer` (see the
[API reference](#sec-096)). Each key carries a set of scopes:
@@ -44450,7 +46652,7 @@ Errors: `400 bad_request` (`keyId` missing or not a string),
`404 not_found` (key does not exist, is not yours, or is not a well-formed
UUID), `400 revoked`, `400 expired`, `401`, `403` (CSRF), `429`.
-See [MCP integration](#sec-276) for configuring a real client against
+See [MCP integration](#sec-277) for configuring a real client against
`/api/mcp`.
---
@@ -44529,7 +46731,7 @@ omitted from the manifest.
---
-<a id="sec-174"></a>
+<a id="sec-177"></a>
> **Source:** `docs/diorama.md` · [↑ table of contents](#table-of-contents)
@@ -44631,13 +46833,13 @@ until the world is saved:
## Related
-- [Forge](#sec-224) is the single-object generator every diorama object is forged on.
-- [Image to 3D](#sec-250) for photo-based objects; [AR](#sec-099) for viewing worlds in augmented reality.
+- [Forge](#sec-225) is the single-object generator every diorama object is forged on.
+- [Image to 3D](#sec-251) for photo-based objects; [AR](#sec-099) for viewing worlds in augmented reality.
- Pages: [/scene](https://three.ws/scene) (Scene Studio, where an exported diorama opens), [/gallery](https://three.ws/gallery), [/create](https://three.ws/create).
---
-<a id="sec-175"></a>
+<a id="sec-178"></a>
> **Source:** `docs/do-i-need-crypto.md` · [↑ table of contents](#table-of-contents)
@@ -44717,14 +46919,14 @@ When you do interact with on-chain features, the platform's native token is **$T
## What's next
-- **Create your first agent** → [Make your first agent](#sec-267)
-- **Put it on your site** → [Share & embed](#sec-373)
-- **Optional: register on-chain** → [Register on-chain](#sec-456)
+- **Create your first agent** → [Make your first agent](#sec-268)
+- **Put it on your site** → [Share & embed](#sec-378)
+- **Optional: register on-chain** → [Register on-chain](#sec-462)
- **Technical auth details** → [Authentication](#sec-103)
---
-<a id="sec-176"></a>
+<a id="sec-179"></a>
> **Source:** `docs/docs-world.md` · [↑ table of contents](#table-of-contents)
@@ -44811,7 +47013,7 @@ Adding a section is the same edit: append to `sections` and a new pavilion appea
---
-<a id="sec-177"></a>
+<a id="sec-180"></a>
> **Source:** `docs/draft-agent-mint.md` · [↑ table of contents](#table-of-contents)
@@ -44984,6 +47186,45 @@ MinIO is started with `MINIO_DOMAIN=localhost`; add
`127.0.0.1 <bucket>.localhost` to `/etc/hosts` and give the bucket a
public-read policy so the script's read-back check can fetch the object.
+### When the faucet says no
+
+The public devnet faucet rate-limits per source IP, so a shared machine (a
+Codespace, a CI runner, an office network) can find it already exhausted by
+someone else, and every airdrop in the endpoint chain comes back 429. The proof
+does not have to stop there: point the whole devnet chain at your own validator
+with the real Metaplex programs cloned off devnet, and it airdrops without
+limit.
+
+```bash
+solana-test-validator --reset --ledger /tmp/dm-ledger \
+ --url https://api.devnet.solana.com \
+ --clone-upgradeable-program CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d \
+ --clone-upgradeable-program 1DREGFgysWYxLnRnKQnwrxnJQeSMk2HmGaC6whw2B2p &
+
+solana-keygen new --no-bip39-passphrase --silent --outfile /tmp/dm-authority.json
+solana airdrop 20 "$(solana-keygen pubkey /tmp/dm-authority.json)" --url http://127.0.0.1:8899
+```
+
+The two programs are Metaplex Core (the asset) and the Metaplex Agent Registry
+(the identity PDA). Clone both, or the registry enrolment fails and the proof
+covers only half the mint.
+
+One wrinkle: the platform derives a connection's websocket endpoint by swapping
+the scheme on its HTTP URL, same host and same port, which is what every hosted
+RPC provider serves. A test validator instead puts its websocket on
+`rpcPort + 1`, so the derived `ws://127.0.0.1:8899` never connects, transaction
+confirmation falls back to block-height polling, and the mint reports an expired
+blockhash for a transaction that in fact landed. Front the validator with
+anything that serves HTTP and the websocket upgrade on one port, and point
+`SOLANA_RPC_URL_DEVNET` at that port instead.
+
+`SOLANA_RPC_URL_DEVNET` takes priority over every other devnet lane, so the run
+uses your node. The signature it produces is a real signature from a real
+Solana runtime executing the real programs, but it lives on your ledger, not on
+public devnet: it will not resolve on Solscan. The script reports which node
+served the run and, off the public cluster, prints the endpoint instead of an
+explorer link, so the evidence file never overstates what was proven.
+
## Failure semantics
| Situation | Result |
@@ -44997,14 +47238,14 @@ public-read policy so the script's read-back check can fetch the object.
## Related
-- [Selfie to Avatar](#sec-372): the pipeline whose tail calls this
+- [Selfie to Avatar](#sec-377): the pipeline whose tail calls this
- [Agent identities](#sec-053): what an agent identity is and how it is generated
- [Agent tokens](#sec-070): what happens after a draft identity goes live
- [The agent index](#sec-054): the cross-chain index that surfaces these registrations
---
-<a id="sec-178"></a>
+<a id="sec-181"></a>
> **Source:** `docs/economy-heartbeat.md` · [↑ table of contents](#table-of-contents)
@@ -45159,13 +47400,13 @@ CRON_SECRET=… DURATION_MINUTES=10 node scripts/economy-heartbeat.mjs
- **Undeployed endpoints are tolerated.** A target missing from the deployed
build reports `status: 404` and never stops the others.
-Related: [circulation engine](#sec-139) ·
-[x402 ring economy](#sec-516) ·
-[economy funding root](#sec-179) · [money map](#sec-286)
+Related: [circulation engine](#sec-141) ·
+[x402 ring economy](#sec-541) ·
+[economy funding root](#sec-182) · [money map](#sec-287)
---
-<a id="sec-179"></a>
+<a id="sec-182"></a>
> **Source:** `docs/economy-master.md` · [↑ table of contents](#table-of-contents)
@@ -45185,6 +47426,10 @@ platform-wide.
> [`api/cron/treasury-topup.js`](../api/cron/treasury-topup.js), registry
> [`api/_lib/solana-signers.js`](../api/_lib/solana-signers.js) — the registry is
> the source of truth for every engine signer and its funding floor.
+>
+> Rotating this wallet (or any other economy signer) goes through the wallet
+> registry: [`docs/ops/economy-wallet-rotation.md`](ops/economy-wallet-rotation.md),
+> which keeps a permanent log of every address each role has ever held.
**Address (mainnet vanity):** `WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW`
@@ -45628,7 +47873,7 @@ The JSON response reports `configured`, `master_sol`, `funded`, `failed`,
off-registry target reached the sweep and was blocked — investigate the caller.
If the Cloud Scheduler job never fires, the
-[economy heartbeat](#sec-178) dispatcher (and any external HTTP cron
+[economy heartbeat](#sec-181) dispatcher (and any external HTTP cron
pointed at `/api/cron/economy-tick`) keeps it — and every other cron — ticking.
## Audit, accounting & breach monitoring
@@ -45743,26 +47988,26 @@ of the tree the master feeds:
sponsor settle floor) and `x402-ring-payer` (`X402_SEED_SOLANA_SECRET_BASE58`,
fallback `X402_AGENT_SOLANA_SECRET_BASE58`, floor 0.03 SOL, `holdsTokens` so
sweepback leaves its USDC float alone) are topped up by this master like every
- other engine (see [x402 ring economy](#sec-516) /
+ other engine (see [x402 ring economy](#sec-541) /
[autonomous x402](#sec-105)).
## Related
- [`api/_lib/solana-signers.js`](../api/_lib/solana-signers.js) — every
engine signer, its encoding, and how to fund/consolidate the economy wallets.
-- [Circulation engine](#sec-139) — the autonomous agent-to-agent
+- [Circulation engine](#sec-141) — the autonomous agent-to-agent
activity loop the funded engines drive.
-- [x402 ring economy](#sec-516) — closed-loop in-house x402 settlement.
+- [x402 ring economy](#sec-541) — closed-loop in-house x402 settlement.
---
-<a id="sec-180"></a>
+<a id="sec-183"></a>
> **Source:** `docs/economy-solver.md` · [↑ table of contents](#table-of-contents)
# The economy solver
-The [in-game economy reference](#sec-251) publishes **what** the `/play`
+The [in-game economy reference](#sec-252) publishes **what** the `/play`
world charges. The solver publishes **what those numbers mean**: the exact expected
cash, XP and goods per hour of every action in the world, at every skill level.
@@ -45988,16 +48233,16 @@ deploy.
## Next
-- **[The in-game economy](#sec-251)** is the raw reference: every catalog,
+- **[The in-game economy](#sec-252)** is the raw reference: every catalog,
gate, settlement path and the JSON wire format.
-- **[Earn and spend in /play](#sec-429)** walks the loop
+- **[Earn and spend in /play](#sec-435)** walks the loop
by hand, in the world.
- **[three.ws/play/solver](https://three.ws/play/solver)** is the interactive version
of everything above.
---
-<a id="sec-181"></a>
+<a id="sec-184"></a>
> **Source:** `docs/editor.md` · [↑ table of contents](#table-of-contents)
@@ -46346,7 +48591,7 @@ The full contract lives in [specs/EDITOR_SPEC.md](https://github.com/nirholas/th
---
-<a id="sec-182"></a>
+<a id="sec-185"></a>
> **Source:** `docs/education-pilot-bucharest.md` · [↑ table of contents](#table-of-contents)
@@ -46417,7 +48662,7 @@ Status: exploratory. A contact has offered a local connection to the office of t
---
-<a id="sec-183"></a>
+<a id="sec-186"></a>
> **Source:** `docs/embedding.md` · [↑ table of contents](#table-of-contents)
@@ -47156,14 +49401,14 @@ The platform records anonymous embed impressions (country, referrer hostname) vi
- [Architecture Overview](#sec-100)
- [Agent System Overview](#sec-064)
-- [Web Component reference](#sec-502) — full attribute list
-- [Widgets](#sec-505) — Widget Studio and widget types
+- [Web Component reference](#sec-508) — full attribute list
+- [Widgets](#sec-511) — Widget Studio and widget types
- [specs/EMBED_SPEC.md](../specs/EMBED_SPEC.md) — authoritative web component spec
- [specs/EMBED_HOST_PROTOCOL.md](../specs/EMBED_HOST_PROTOCOL.md) — versioned postMessage protocol
---
-<a id="sec-184"></a>
+<a id="sec-187"></a>
> **Source:** `docs/embody.md` · [↑ table of contents](#table-of-contents)
@@ -47266,14 +49511,14 @@ Embody is a thin, honest wire over pieces that already exist — no new pipeline
## Related
-- [Live embodiment](#sec-273) — the 3D Studio tools that persist and drive a body in chat.
-- [x402 Paid Endpoints](#sec-514) — the full paid catalog and pricing.
-- [x402 Buyer Client](#sec-511) — how to settle a 402 challenge from code.
-- [Avatar creation](#sec-108) — generate a rigged avatar in the web UI.
+- [Live embodiment](#sec-274) — the 3D Studio tools that persist and drive a body in chat.
+- [x402 Paid Endpoints](#sec-539) — the full paid catalog and pricing.
+- [x402 Buyer Client](#sec-536) — how to settle a 402 challenge from code.
+- [Avatar creation](#sec-109) — generate a rigged avatar in the web UI.
---
-<a id="sec-185"></a>
+<a id="sec-188"></a>
> **Source:** `docs/erc8004.md` · [↑ table of contents](#table-of-contents)
@@ -47982,7 +50227,7 @@ The same MAINNET addresses apply to all 15 mainnets. The same TESTNET addresses
---
-<a id="sec-186"></a>
+<a id="sec-189"></a>
> **Source:** `docs/erc8004/validation-attestation.md` · [↑ table of contents](#table-of-contents)
@@ -48135,7 +50380,7 @@ reported the reverts as "no attestation yet".
---
-<a id="sec-187"></a>
+<a id="sec-190"></a>
> **Source:** `docs/event-readiness/01-play-first-impression.md` · [↑ table of contents](#table-of-contents)
@@ -48179,7 +50424,7 @@ What you changed (files + one line each), what you verified in-browser, anything
---
-<a id="sec-188"></a>
+<a id="sec-191"></a>
> **Source:** `docs/event-readiness/02-play-mobile.md` · [↑ table of contents](#table-of-contents)
@@ -48215,7 +50460,7 @@ Root cause of any crash found (with the harness evidence), fixes applied, remain
---
-<a id="sec-189"></a>
+<a id="sec-192"></a>
> **Source:** `docs/event-readiness/03-play-performance.md` · [↑ table of contents](#table-of-contents)
@@ -48257,7 +50502,7 @@ Numbers table (before/after), each fix in one line, anything intentionally skipp
---
-<a id="sec-190"></a>
+<a id="sec-193"></a>
> **Source:** `docs/event-readiness/04-play-multiplayer-net.md` · [↑ table of contents](#table-of-contents)
@@ -48297,7 +50542,7 @@ Each failure mode tested and its result (pass / fixed / cannot-fix-with-reason).
---
-<a id="sec-191"></a>
+<a id="sec-194"></a>
> **Source:** `docs/event-readiness/05-play-economy-loops.md` · [↑ table of contents](#table-of-contents)
@@ -48338,7 +50583,7 @@ Loop-by-loop pass/fixed table, every price mismatch found and which side you cor
---
-<a id="sec-192"></a>
+<a id="sec-195"></a>
> **Source:** `docs/event-readiness/06-play-auth-errors.md` · [↑ table of contents](#table-of-contents)
@@ -48374,7 +50619,7 @@ A failure-mode table: scenario, what happened before, what happens now. Call out
---
-<a id="sec-193"></a>
+<a id="sec-196"></a>
> **Source:** `docs/event-readiness/07-platform-smoke-sweep.md` · [↑ table of contents](#table-of-contents)
@@ -48425,7 +50670,7 @@ Battery results before and after, fixes grouped by page, the manual event-funnel
---
-<a id="sec-194"></a>
+<a id="sec-197"></a>
> **Source:** `docs/event-readiness/08-api-production-health.md` · [↑ table of contents](#table-of-contents)
@@ -48456,7 +50701,7 @@ Solana-first status summary, then the 8 items with their binary states, then log
---
-<a id="sec-195"></a>
+<a id="sec-198"></a>
> **Source:** `docs/event-readiness/09-accessibility-i18n.md` · [↑ table of contents](#table-of-contents)
@@ -48492,7 +50737,7 @@ Per-category pass/fixed list, the keyboard-only session result, locales verified
---
-<a id="sec-196"></a>
+<a id="sec-199"></a>
> **Source:** `docs/event-readiness/10-event-day-runbook.md` · [↑ table of contents](#table-of-contents)
@@ -48530,7 +50775,7 @@ Old/new scaling values, capacity smoke numbers, rollback rehearsal result, and t
---
-<a id="sec-197"></a>
+<a id="sec-200"></a>
> **Source:** `docs/event-readiness/11-event-live-ops.md` · [↑ table of contents](#table-of-contents)
@@ -48565,7 +50810,7 @@ What shipped (files + one line each), the exact operator commands for event day,
---
-<a id="sec-198"></a>
+<a id="sec-201"></a>
> **Source:** `docs/event-readiness/12-photo-mode-share.md` · [↑ table of contents](#table-of-contents)
@@ -48601,7 +50846,7 @@ Files shipped, a saved sample capture path, what the share flow does per platfor
---
-<a id="sec-199"></a>
+<a id="sec-202"></a>
> **Source:** `docs/event-readiness/13-event-quests-leaderboard.md` · [↑ table of contents](#table-of-contents)
@@ -48637,7 +50882,7 @@ The quest list as players will see it, files shipped, the leaderboard endpoint U
---
-<a id="sec-200"></a>
+<a id="sec-203"></a>
> **Source:** `docs/event-readiness/14-welcome-concierge.md` · [↑ table of contents](#table-of-contents)
@@ -48672,7 +50917,7 @@ Files shipped, the persona prompt location, the tour stops, what the concierge s
---
-<a id="sec-201"></a>
+<a id="sec-204"></a>
> **Source:** `docs/event-readiness/15-live-hype-feed.md` · [↑ table of contents](#table-of-contents)
@@ -48706,7 +50951,7 @@ Files shipped, the threshold logic in two sentences, measured DOM/node behavior
---
-<a id="sec-202"></a>
+<a id="sec-205"></a>
> **Source:** `docs/event-readiness/16-invite-flow.md` · [↑ table of contents](#table-of-contents)
@@ -48740,7 +50985,7 @@ Files shipped, any dependency added (name, weekly downloads, license, why), a re
---
-<a id="sec-203"></a>
+<a id="sec-206"></a>
> **Source:** `docs/event-readiness/17-plaza-live-show.md` · [↑ table of contents](#table-of-contents)
@@ -48777,7 +51022,7 @@ Files shipped, how `stageId` is derived, the join and teardown lifecycle in thre
---
-<a id="sec-204"></a>
+<a id="sec-207"></a>
> **Source:** `docs/event-readiness/18-coin-wars-portal.md` · [↑ table of contents](#table-of-contents)
@@ -48814,7 +51059,7 @@ Files shipped, the standings read path (existing or the one endpoint you added),
---
-<a id="sec-205"></a>
+<a id="sec-208"></a>
> **Source:** `docs/event-readiness/19-forge-props-live.md` · [↑ table of contents](#table-of-contents)
@@ -48851,7 +51096,7 @@ Files shipped, the size ceiling values and where they are enforced, the rate-lim
---
-<a id="sec-206"></a>
+<a id="sec-209"></a>
> **Source:** `docs/event-readiness/20-world-chat-scrollback.md` · [↑ table of contents](#table-of-contents)
@@ -48888,7 +51133,7 @@ Files shipped, the cap and TTL chosen, the bridge decision and why, join-time pa
---
-<a id="sec-207"></a>
+<a id="sec-210"></a>
> **Source:** `docs/event-readiness/21-party-system.md` · [↑ table of contents](#table-of-contents)
@@ -48924,7 +51169,7 @@ Files shipped, where party state lives and its TTL, the teleport validation rule
---
-<a id="sec-208"></a>
+<a id="sec-211"></a>
> **Source:** `docs/event-readiness/22-venue-projector-mode.md` · [↑ table of contents](#table-of-contents)
@@ -48960,7 +51205,7 @@ Files shipped, the exact URL to put on the venue machine, the spectator join con
---
-<a id="sec-209"></a>
+<a id="sec-212"></a>
> **Source:** `docs/event-readiness/23-signature-wall.md` · [↑ table of contents](#table-of-contents)
@@ -48997,7 +51242,7 @@ Files shipped, the store chosen and why, the overflow design in two sentences, t
---
-<a id="sec-210"></a>
+<a id="sec-213"></a>
> **Source:** `docs/event-readiness/24-dance-off.md` · [↑ table of contents](#table-of-contents)
@@ -49033,7 +51278,7 @@ Files shipped, the round timings chosen, the vote targeting rule, the reward and
---
-<a id="sec-211"></a>
+<a id="sec-214"></a>
> **Source:** `docs/event-readiness/LIVE-OPS.md` · [↑ table of contents](#table-of-contents)
@@ -49046,7 +51291,7 @@ Prepared 2026-08-08. Project `aerial-vehicle-466722-p5`, region `us-central1`.
## The link and the release
-**Event URL** (the canonical $THREE world, from [README.md](#sec-212)):
+**Event URL** (the canonical $THREE world, from [README.md](#sec-215)):
```
https://three.ws/play?coin=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&name=three.ws&symbol=three&image=%2Fapi%2Fimg%3Furl%3Dhttps%253A%252F%252Fipfs.io%252Fipfs%252Fbafybeihe22b5sxr3ihnxt7pregfieyteqvubqhik3j3y4bbx243xlqjw3q%26seed%3DFeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
@@ -49333,7 +51578,7 @@ page.
---
-<a id="sec-212"></a>
+<a id="sec-215"></a>
> **Source:** `docs/event-readiness/README.md` · [↑ table of contents](#table-of-contents)
@@ -49345,40 +51590,40 @@ Suggested order and parallelism (audits):
| # | Prompt | Surface | Can run in parallel with |
|---|--------|---------|--------------------------|
-| 1 | [01-play-first-impression.md](#sec-187) | /play load, intro, onboarding UX | 4, 5, 7, 8 |
-| 2 | [02-play-mobile.md](#sec-188) | /play on phones (stability + touch) | 7, 8 |
-| 3 | [03-play-performance.md](#sec-189) | /play load weight, FPS, memory | 7, 8 |
-| 4 | [04-play-multiplayer-net.md](#sec-190) | WebSocket, reconnects, voice, crowd | 1, 5 |
-| 5 | [05-play-economy-loops.md](#sec-191) | Store, bank, wheel, combat, quests, cosmetics | 1, 4 |
-| 6 | [06-play-auth-errors.md](#sec-192) | Sign-in, gates, error/empty states, console | after 1 |
-| 7 | [07-platform-smoke-sweep.md](#sec-193) | Every page on the live site | 1, 2, 3 |
-| 8 | [08-api-production-health.md](#sec-194) | Cloud Run, crons, logs, DB, x402 | 1, 2, 3 |
-| 9 | [09-accessibility-i18n.md](#sec-195) | Keyboard, ARIA, contrast, translations | after 1 |
-| 10 | [10-event-day-runbook.md](#sec-196) | Pre-scale, monitoring loop, rollback | last, after all fixes deploy |
+| 1 | [01-play-first-impression.md](#sec-190) | /play load, intro, onboarding UX | 4, 5, 7, 8 |
+| 2 | [02-play-mobile.md](#sec-191) | /play on phones (stability + touch) | 7, 8 |
+| 3 | [03-play-performance.md](#sec-192) | /play load weight, FPS, memory | 7, 8 |
+| 4 | [04-play-multiplayer-net.md](#sec-193) | WebSocket, reconnects, voice, crowd | 1, 5 |
+| 5 | [05-play-economy-loops.md](#sec-194) | Store, bank, wheel, combat, quests, cosmetics | 1, 4 |
+| 6 | [06-play-auth-errors.md](#sec-195) | Sign-in, gates, error/empty states, console | after 1 |
+| 7 | [07-platform-smoke-sweep.md](#sec-196) | Every page on the live site | 1, 2, 3 |
+| 8 | [08-api-production-health.md](#sec-197) | Cloud Run, crons, logs, DB, x402 | 1, 2, 3 |
+| 9 | [09-accessibility-i18n.md](#sec-198) | Keyboard, ARIA, contrast, translations | after 1 |
+| 10 | [10-event-day-runbook.md](#sec-199) | Pre-scale, monitoring loop, rollback | last, after all fixes deploy |
Feature builds (run after audits 1-3 land, or in parallel if staffed; 12, 14, and 16 interlink but each stands alone):
| # | Prompt | Builds | Depends on |
|---|--------|--------|------------|
-| 11 | [11-event-live-ops.md](#sec-197) | Operator broadcast, go-live moment, live event config | nothing |
-| 12 | [12-photo-mode-share.md](#sec-198) | Photo mode with branded one-tap share | nothing |
-| 13 | [13-event-quests-leaderboard.md](#sec-199) | Time-boxed quest line + live leaderboard + cosmetic reward | nothing (better with 12) |
-| 14 | [14-welcome-concierge.md](#sec-200) | Greeter NPC, guided tour, event-aware opening line | nothing |
-| 15 | [15-live-hype-feed.md](#sec-201) | Activity ticker + market hype moments | nothing (better with 13) |
-| 16 | [16-invite-flow.md](#sec-202) | Invite sheet, QR, OG card truth, arrival continuity | nothing (better with 14) |
+| 11 | [11-event-live-ops.md](#sec-200) | Operator broadcast, go-live moment, live event config | nothing |
+| 12 | [12-photo-mode-share.md](#sec-201) | Photo mode with branded one-tap share | nothing |
+| 13 | [13-event-quests-leaderboard.md](#sec-202) | Time-boxed quest line + live leaderboard + cosmetic reward | nothing (better with 12) |
+| 14 | [14-welcome-concierge.md](#sec-203) | Greeter NPC, guided tour, event-aware opening line | nothing |
+| 15 | [15-live-hype-feed.md](#sec-204) | Activity ticker + market hype moments | nothing (better with 13) |
+| 16 | [16-invite-flow.md](#sec-205) | Invite sheet, QR, OG card truth, arrival continuity | nothing (better with 14) |
Capability builds (17-24): each wires an existing, finished subsystem into the world or adds a missing social primitive. All stand alone; the noted pairings just make them better together.
| # | Prompt | Builds | Wires in / pairs with |
|---|--------|--------|-----------------------|
-| 17 | [17-plaza-live-show.md](#sec-203) | Live hosted show on a plaza stage, with $THREE tips | StageRoom + ShowDirector (built, unreachable from /play) |
-| 18 | [18-coin-wars-portal.md](#sec-204) | In-world Coin Wars portal: standings, queue, spectate | ClashRoom + war standings (built, arena-page only) |
-| 19 | [19-forge-props-live.md](#sec-205) | Text-to-3D prop generation inside build mode | Forge lane + the networked prop pipeline |
-| 20 | [20-world-chat-scrollback.md](#sec-206) | Chat scrollback for late joiners + community-feed bridge | the WalkRoom relay + api/community/messages |
-| 21 | [21-party-system.md](#sec-207) | Parties: form, see, reach, and talk to your crew | friends/presence stack; pairs with 13, 16 |
-| 22 | [22-venue-projector-mode.md](#sec-208) | Broadcast spectator view for the venue big screen | camera rig + event.json; pairs with 15, 16, 17 |
-| 23 | [23-signature-wall.md](#sec-209) | Persistent signature wall, the event's artifact | world-persist patterns + name safety |
-| 24 | [24-dance-off.md](#sec-210) | Judged dance-off rounds with crowd voting and tips | dance floor beat + King of the Totem round machine |
+| 17 | [17-plaza-live-show.md](#sec-206) | Live hosted show on a plaza stage, with $THREE tips | StageRoom + ShowDirector (built, unreachable from /play) |
+| 18 | [18-coin-wars-portal.md](#sec-207) | In-world Coin Wars portal: standings, queue, spectate | ClashRoom + war standings (built, arena-page only) |
+| 19 | [19-forge-props-live.md](#sec-208) | Text-to-3D prop generation inside build mode | Forge lane + the networked prop pipeline |
+| 20 | [20-world-chat-scrollback.md](#sec-209) | Chat scrollback for late joiners + community-feed bridge | the WalkRoom relay + api/community/messages |
+| 21 | [21-party-system.md](#sec-210) | Parties: form, see, reach, and talk to your crew | friends/presence stack; pairs with 13, 16 |
+| 22 | [22-venue-projector-mode.md](#sec-211) | Broadcast spectator view for the venue big screen | camera rig + event.json; pairs with 15, 16, 17 |
+| 23 | [23-signature-wall.md](#sec-212) | Persistent signature wall, the event's artifact | world-persist patterns + name safety |
+| 24 | [24-dance-off.md](#sec-213) | Judged dance-off rounds with crowd voting and tips | dance floor beat + King of the Totem round machine |
Rules that apply to every prompt in this pack:
@@ -49390,7 +51635,7 @@ Rules that apply to every prompt in this pack:
---
-<a id="sec-213"></a>
+<a id="sec-216"></a>
> **Source:** `docs/event-souvenirs.md` · [↑ table of contents](#table-of-contents)
@@ -49411,7 +51656,7 @@ walks past you.
The first one is the **Meetup Laurel**: a gold laurel circlet, open at the
front, with three pearl berries in the gap. It was granted at the
-[`$THREE` First Holders Meetup](#sec-323). That window has closed, so
+[`$THREE` First Holders Meetup](#sec-328). That window has closed, so
the laurel is now exactly what this page promises: owned only by the players who
were in the world that day, and never granted again.
@@ -49641,329 +51886,15 @@ machine prefer the two above, which cover the same ground between them.
## Related
-- **[Live events in /play](#sec-323)** covers the rest of what that
+- **[Live events in /play](#sec-328)** covers the rest of what that
config file drives: the countdown, the agenda drawer, the fireworks.
-- **[The in-game economy](#sec-251)** covers the two currencies and
+- **[The in-game economy](#sec-252)** covers the two currencies and
the `$THREE` boutique the souvenir deliberately stays out of.
-- **[Coin communities](#sec-143)** covers the worlds the events happen in.
+- **[Coin communities](#sec-145)** covers the worlds the events happen in.
---
-<a id="sec-214"></a>
-
-> **Source:** `docs/event-x-posts.md` · [↑ table of contents](#table-of-contents)
-
-# X posts: Three.ws User Group first in-world meetup (IBM Community)
-
-Copy for the launch-day X push. **The IBM angle is the point of this event**, so IBM leads every
-post: this is the first in-world meetup of the [Three.ws User Group on IBM
-Community](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016),
-an official IBM Community user group, held inside three.ws itself rather than on a call.
-
-**Event:** three.ws Community Meetup: Live on the $THREE Server
-**When:** Friday, August 7, 2026, 8:00 AM Pacific / 11:00 AM Eastern / 4 PM London / 5 PM Berlin
-**Where:** [three.ws/play](https://three.ws/play), the $THREE world pinned at the top of the lobby
-**Cost:** free, no download, no install, no account, no wallet
-
-**IBM event listing (the link every post points at):**
-`https://community.ibm.com/community/user/events/event-description?CalendarEventKey=25d71799-16b5-4342-b2e5-019fcf9622ca&CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016`
-
-Two rules for every post here:
-
-1. **Never state hours-until.** Say "today" and give the absolute clock time. A post that says
- "in 4 hours" is wrong the moment it is reposted, quoted, or found late.
-2. **IBM in the first line.** The user group is the reason this event exists. Do not bury it under
- the game features.
-
----
-
-## 1. Main teaser (post this first, with video)
-
-> Today: the first in-world meetup of the Three.ws User Group on IBM Community.
->
-> Not a webinar. Open three.ws/play in a browser, become a 3D avatar, and walk around the $THREE
-> world with the team. Spatial voice, live demos, open Q&A.
->
-> 8 AM PT / 11 AM ET. Free, no install, no account.
->
-> [IBM event link]
-
-**Media:** the strongest 20 to 40 seconds you have of `/play`. Lead with movement (a crowd in the
-plaza, avatars walking) rather than a static wide shot. First frame matters more than the last.
-
----
-
-## 2. The IBM technical post (this is the one that earns the user group its members)
-
-Post this second, roughly an hour after the teaser. It is the reason an IBM developer should care.
-
-> Why an IBM Community user group is meeting inside a 3D world:
->
-> three.ws is an IBM Business Partner. Our agents think on IBM Granite served through watsonx.ai,
-> and two of our MCP servers are IBM-native:
->
-> @three-ws/ibm-watsonx-mcp, watsonx.ai on your own IBM Cloud account
-> @three-ws/ibm-x402-mcp, pay-per-use Granite billed in USDC, no IBM account needed
->
-> Come ask us about any of it, in person: [IBM event link]
-
----
-
-## 3. Alternates for the main slot
-
-Pick one. Do not post all three.
-
-**Short and blunt**
-
-> The Three.ws User Group on IBM Community meets today, inside three.ws.
->
-> A browser tab, a 3D avatar, spatial voice, live demos, and the team answering anything.
->
-> 8 AM PT / 11 AM ET. Free: [IBM event link]
-
-**Contrast-led**
-
-> Most user groups meet on a video call.
->
-> Ours meets in a 3D world you open in a browser tab. You walk up to someone and you hear them,
-> from the direction they are standing.
->
-> First Three.ws User Group meetup on IBM Community is today, 8 AM PT: [IBM event link]
-
-**Builder-led**
-
-> If you build AI agents that need a body, spatial reasoning, or generative 3D, the Three.ws User
-> Group on IBM Community is your room. It meets today, and it meets inside the product.
->
-> 8 AM PT / 11 AM ET, free, browser only: [IBM event link]
-
----
-
-## 4. Thread version (if you want the reach)
-
-**1/**
-> Today: the first in-world meetup of the Three.ws User Group on IBM Community.
->
-> Not a Space, not a webinar. An actual 3D world you walk into from a link, with the team standing
-> in it.
->
-> 8 AM PT / 11 AM ET: [IBM event link]
-
-**2/** (attach the best plaza / crowd clip)
-> How you join, in full: open three.ws/play, click the $THREE world pinned at the top, you are in.
-> Guests get an avatar automatically. No download, no account, no wallet.
-
-**3/** (attach voice or group-conversation footage)
-> Voice is spatial. You hear the people near you, from the direction they are standing, fading as
-> you walk away. Three conversations can happen twenty meters apart without talking over each
-> other, exactly like a conference hallway.
-
-**4/** (attach `/create` footage, or an avatar generation clip)
-> Want to show up as yourself? Build a custom 3D agent first at three.ws/create from a text prompt
-> or a selfie. Rigged and animation-ready in about a minute, and it follows you into the world.
-
-**5/** (attach the strongest world / demo footage)
-> Why IBM Community: three.ws is an IBM Business Partner, our agents run on IBM Granite through
-> watsonx.ai, and we ship @three-ws/ibm-watsonx-mcp and @three-ws/ibm-x402-mcp for anyone building
-> on watsonx.
->
-> Live demos and open Q&A on all of it today: [IBM event link]
-
-**6/**
-> Every community can do this, not just ours. Every pump.fun coin already has a world at
-> three.ws/play?coin=<mint>. No booking, no whitelist, no fee. The venue layer is a URL scheme.
->
-> Come see it working: [IBM event link]
-
----
-
-## 5. Follow-ups for the rest of the day
-
-**Shortly before doors** (quote your own main post)
-> Doors open shortly. New to 3D worlds? Come 10 minutes early and we will walk you through the
-> controls personally. three.ws/play
-
-**The moment it goes live**
-> We are live. The Three.ws User Group on IBM Community is meeting inside three.ws right now.
->
-> Open three.ws/play, click the pinned $THREE world, walk over and say hi.
-
-**Mid-event, with a screenshot of the actual crowd**
-> This is an IBM Community user group meeting, happening right now. Still time to walk in:
-> three.ws/play
-
-**After it ends** (this is the one that recruits for the next event)
-> That was the first Three.ws User Group meetup on IBM Community.
->
-> [attach the group shot or the best clip from the day]
->
-> The group is open and the world stays open. Join the group: [IBM user group link]
-
----
-
-## 5b. Sharing Jessica's IBM Community blog
-
-Jessica's post on the user group ("Join the Three.ws User Group's First In-World Meetup This
-Friday") is the single best asset in this campaign, because it is IBM's own voice saying the thing
-we have been saying all week. Our posts are marketing; hers is a user group organizer telling her
-own members not to skip this. Lead with who wrote it, let the quote carry the argument, and keep
-our own commentary to one line.
-
-Two accounts, two jobs. `@trythreews` posts the institutional version: IBM wrote this, here it is.
-`@nichxbt` posts the human version: working with her has been great. Do not put the warm personal
-note on the brand account, and do not post both within a few minutes of each other.
-
-### From @trythreews (recommended, tight quote). This is the posted version.
-
-> The official @IBM blog for today's meetup is up, written by Jessica, a core member of the @IBM
-> team behind the Three.ws User Group and the one who made all of this possible.
->
-> "It is not a video call. The three.ws team is hosting the group's first community meetup inside
-> the platform itself, in the flagship world at three.ws/play. You attend as an avatar, you hear
-> the people standing near you through spatial voice chat, and the product tour happens by
-> literally walking through the product."
->
-> [blog link]
-
-That cut is deliberate. The second paragraph of her post is the whole argument in four sentences
-and it ends on the best line she wrote ("the product tour happens by literally walking through the
-product"). Ending a quote on the strongest sentence is worth more than including every sentence.
-
-### From @trythreews (full quote, if you want her framing of why the group exists)
-
-> The official blog for today's meetup is up on IBM Community, written by Jessica, a core member of
-> the @IBM Community team behind the Three.ws User Group.
->
-> "When this user group launched in July, the promise was more than threads and blog posts: it was
-> live sessions with the people actually building AI agents with 3D capabilities. This Friday we
-> get the first one, and I want to make sure nobody misses it because they assumed it was another
-> webinar link.
->
-> It is not a video call. You attend as an avatar, you hear the people standing near you through
-> spatial voice chat, and the product tour happens by literally walking through the product."
->
-> [blog link]
-
-### From @nichxbt (the human one, quote-tweeting the @trythreews post above)
-
-> Jessica has been helping us with this from the start, and honestly it has been a pleasure working
-> with her. IBM Community got a real organizer on this group.
->
-> Read her post, then come meet her in-world. She built her own 3D agent from a selfie for today.
-
-**Media for the @trythreews post:** Jessica's custom 3D agent, in-world, is the single best image
-you can attach. It closes the loop: the person who wrote the IBM blog is standing in the product,
-as an avatar she generated from a selfie. Second choice is a clean screenshot of the blog header on
-community.ibm.com so the IBM domain is visible in the frame.
-
-**Rules for this one:**
-
-- Name her and her role in the first line. "Jessica from IBM wrote this" is the headline, not the
- blog title.
-- Quote verbatim inside quotation marks. Do not paraphrase her into our voice. The credibility of
- the post comes entirely from it being her words, not ours.
-- One link, hers, at the end. Do not stack the event listing and the user group link on this post;
- every other post in the campaign already carries those.
-- Do not add our own "and here is why that matters" paragraph. Her post already argues it.
-
----
-
-## 5c. Sharing Jessica's recap (published)
-
-Jessica's recap, ["The First Three.ws User Group Meetup: How It
-Went"](https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm),
-is up on IBM Community. Same two-account split as the announcement post in 5b: `@trythreews` posts
-the institutional version, `@nichxbt` quote-tweets it with the human one. Do not post both within a
-few minutes of each other.
-
-### From @trythreews (recommended, leads with the concurrency stat). This is the posted version.
-
-The stat is the hook: it's the single number in her post a reader has no way to guess, and it lands
-harder on X than the framing sentence does. This excerpt is contiguous, verbatim, straight out of
-her post, just the framing clause and the number, without the full paragraph's extra sentence.
-
-> Jessica, the @IBM Community organizer behind the Three.ws User Group, just published her own recap
-> of Friday's meetup.
->
-> "This group is still small, but the open world we held it in is not gated to members: anyone with
-> the link could walk in, and a lot of people did. Peak concurrency in the world hit 3,145 avatars at
-> once over the course of the day, well past anything a call could have seated."
->
-> https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm
-
-### From @trythreews (alternate, tight quote without the stat)
-
-> Jessica, the @IBM Community organizer behind the Three.ws User Group, just published her own recap
-> of Friday's meetup.
->
-> "Neither IBM nor three.ws is the slow, boring-enterprise thing people assume from the outside. We
-> both like trying things that are actually new, and a nine-hour user-group meetup held entirely
-> inside a 3D world, instead of on a call, is exactly that kind of thing. It held up."
->
-> https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm
-
-### From @trythreews (full quote, if you want both the framing and the number)
-
-> Jessica, the @IBM Community organizer behind the Three.ws User Group, just published her own recap
-> of Friday's meetup.
->
-> "Neither IBM nor three.ws is the slow, boring-enterprise thing people assume from the outside. We
-> both like trying things that are actually new, and a nine-hour user-group meetup held entirely
-> inside a 3D world, instead of on a call, is exactly that kind of thing. It held up. This group is
-> still small, but the open world we held it in is not gated to members: anyone with the link could
-> walk in, and a lot of people did. Peak concurrency in the world hit 3,145 avatars at once over the
-> course of the day, well past anything a call could have seated, even though most of that crowd
-> came for the open world itself rather than being User Group members."
->
-> https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm
-
-### From @nichxbt (the human one, quote-tweeting the @trythreews post above)
-
-> Jessica called it exactly right: this was never going to be the slow, boring-enterprise version of
-> a partnership. Proud of what we built together and even more proud she felt like writing that.
->
-> Read the whole thing, then go stand in the world she's describing: three.ws/play
-
-**Media for the @trythreews post:** a clean screenshot of the recap's header on community.ibm.com,
-so the IBM domain and Jessica's byline are visible in the frame. Second choice: the in-world plaza
-shot from the day, if you have one with a visibly dense crowd, since the post is making a
-concurrency claim.
-
-**Rules for this one, same as 5b:**
-
-- Name her and her role in the first line. "Jessica wrote a recap" is the headline, not the blog
- title.
-- Quote verbatim inside quotation marks. Do not paraphrase her into our voice.
-- One link, hers, at the end. Do not stack the event listing or the user group link on this post.
-- Do not add our own "and here is why that matters" paragraph. Her post already argues it.
-
----
-
-## 6. Recycling the existing `/play` footage
-
-Map what you already have to the beats above, so each post carries a clip that matches its copy:
-
-| Post | Best clip to use |
-| --- | --- |
-| Main teaser | Crowd or plaza movement. Motion in frame one, no menus, no cursor. |
-| IBM technical post | Screen-recording of an agent responding, or the world at its best. Text carries this one. |
-| Thread 2 | The lobby, then landing in the world. Shows the zero-friction claim rather than asserting it. |
-| Thread 3 | Avatars standing in a group, chat bubbles, people walking up to each other. |
-| Thread 4 | An avatar generation on `/create`, then that avatar in-world. |
-| Thread 5 and 6 | Widest good-looking shot you own, or any world other than $THREE. |
-
-Practical notes for reused footage:
-
-- Trim anything showing a debug overlay, a localhost URL, an empty world, or an FPS counter.
-- Assume muted autoplay. If a clip only works with sound, it does not work.
-- Native upload, never a link to a video elsewhere. X suppresses off-platform video reach.
-- Square or 4:5 outperforms 16:9 in the timeline. Crop toward the avatars.
-- One link per post, at the end. The IBM event listing before and during; the IBM user group page
- after it ends.
-
----
-
-<a id="sec-215"></a>
+<a id="sec-217"></a>
> **Source:** `docs/examples.md` · [↑ table of contents](#table-of-contents)
@@ -50704,7 +52635,7 @@ genuinely invested in the user's progress.
## Every runnable example in the repo
-The repo ships 43 examples: 11 web component demos, 10 end-to-end projects, and 22 package example sets. This table is generated from what is on disk, so it cannot list one that was deleted or miss one that was added. The machine-readable version is [data/examples.json](../data/examples.json).
+The repo ships 45 examples: 11 web component demos, 10 end-to-end projects, and 24 package example sets. This table is generated from what is on disk, so it cannot list one that was deleted or miss one that was added. The machine-readable version is [data/examples.json](../data/examples.json).
### Example projects
@@ -50730,6 +52661,8 @@ The repo ships 43 examples: 11 web component demos, 10 end-to-end projects, and
| [`avatar-sdk/examples`](../avatar-sdk/examples) | A self-contained page, no build step. It loads the SDK's @three-ws/avatar/agent entry from a CDN, awaits ensureAgent3D() to register the <agent-3d> element, and renders the real three.ws default avatar using the documented src and kiosk attributes. | `npm run dev, then open /avatar-sdk/examples/index.html` |
| [`packages/avatar-schema/examples`](../packages/avatar-schema/examples) | JSON Schema and validator for three.ws on-chain avatar manifests - the canonical, hash-anchored format any cross-chain client can use to resolve an avatar. | Reference files, nothing to execute |
| [`concierge-sdk/examples`](../concierge-sdk/examples) | Runnable examples for every way to use the concierge. The HTML files load the SDK from ../dist, build it first (npm run build in the package root), then serve this folder (npx serve .) and open each file. | `npm run dev, then open /concierge-sdk/examples/custom-avatar.html` |
+| [`packages/kol-mcp/examples`](../packages/kol-mcp/examples) | Two runnable examples. Both spawn this package's own MCP server over stdio (the same node src/index.js entry point the README documents), speak real MCP JSON-RPC to it, and read the live public KOL API. | `node packages/kol-mcp/examples/list-tools.mjs` |
+| [`packages/loom-mcp/examples`](../packages/loom-mcp/examples) | Two runnable examples. Both spawn this package's own MCP server over stdio (the same node src/index.js entry point the README documents), speak real MCP JSON-RPC to it, and read the live public Loom gallery. | `node packages/loom-mcp/examples/browse-loom.mjs` |
| [`packages/marketplace-mcp/examples`](../packages/marketplace-mcp/examples) | Two runnable examples. Both spawn this package's own MCP server over stdio (the same node src/index.js entry point the README documents), speak real MCP JSON-RPC to it, and read the live public marketplace. | `node packages/marketplace-mcp/examples/browse-marketplace.mjs` |
| [`mcp-server/examples`](../mcp-server/examples) | Two zero-dependency walkthroughs of the MCP Streamable HTTP lifecycle against the live three.ws server at https://three.ws/api/mcp (MCP 2025-06-18, JSON-RPC 2.0). | `node mcp-server/examples/client.mjs` |
| [`page-agent-sdk/examples`](../page-agent-sdk/examples) | Run these from the package root with any static server so the import map can resolve the unbundled source from ../src: | `npm run dev, then open /page-agent-sdk/examples/custom-avatar.html` |
@@ -50770,7 +52703,7 @@ Run any command from the repo root after `npm install`. The web component demos
---
-<a id="sec-216"></a>
+<a id="sec-218"></a>
> **Source:** `docs/exit-lab.md` · [↑ table of contents](#table-of-contents)
@@ -50792,7 +52725,7 @@ recorded number from a position that cost real money.
## Why this is not the backtester
three.ws already ships a backtester ([`api/_lib/strategy-backtest.js`](../api/_lib/strategy-backtest.js),
-documented in [trading-experiment.md](#sec-407)). The two answer
+documented in [trading-experiment.md](#sec-413)). The two answer
different questions and neither replaces the other.
| | Backtester (`/api/sniper/backtest`) | Exit Lab (`/exit-lab`) |
@@ -50909,7 +52842,7 @@ Public and IP rate-limited, like the leaderboard. The tx signatures are the
proof, so anyone can check the fleet's homework.
`network` is `mainnet` (default) or `devnet`. `window` is `7`, `30`, `90`
-(default) or `all` days. `limit` caps at 500.
+(default) or `all` days. `limit` defaults to 400 and caps at 500.
```bash
curl -s 'https://three.ws/api/sniper/exit-lab?window=all&limit=500' | jq '{replayable, scanned, excluded, first: .trades[0]}'
@@ -51002,14 +52935,14 @@ to the nearest legal one rather than throwing.
## Related
- [Agent Sniper](#sec-061), the worker whose positions this replays
-- [Autonomous Trading hub](#sec-408), the front door to every trading surface
-- [Trading experiment](#sec-407), the policy this fleet runs and why
-- [Read the trading fleet](#sec-455), how to interpret fleet vitals
-- Tutorial: [Find a better exit policy](#sec-434)
+- [Autonomous Trading hub](#sec-414), the front door to every trading surface
+- [Trading experiment](#sec-413), the policy this fleet runs and why
+- [Read the trading fleet](#sec-461), how to interpret fleet vitals
+- Tutorial: [Find a better exit policy](#sec-440)
---
-<a id="sec-217"></a>
+<a id="sec-219"></a>
> **Source:** `docs/fact-check.md` · [↑ table of contents](#table-of-contents)
@@ -51046,7 +52979,7 @@ The fact-check pipeline (`runFactCheck`):
The LLM routes through the platform's shared free-first policy (Groq and OpenRouter as funded defaults). Results are cached in Redis for 7 days keyed by a hash of the claim, strictness, and any image URL, so an identical claim (on either lane) never re-runs the live chain.
-**The attestation** is a tamper-evident content digest: `sha256:` followed by the SHA-256 of a JSON object of `{ verdict, confidence, claim, source URLs }`. It is returned as a string field you can recompute to confirm the verdict was not altered. Note that this is a content hash, not an on-chain record; it is distinct from the platform's [SAS credentialed attestations](#sec-367) and [3D provenance anchoring](#sec-329), which do write to Solana.
+**The attestation** is a tamper-evident content digest: `sha256:` followed by the SHA-256 of a JSON object of `{ verdict, confidence, claim, source URLs }`. It is returned as a string field you can recompute to confirm the verdict was not altered. Note that this is a content hash, not an on-chain record; it is distinct from the platform's [SAS credentialed attestations](#sec-372) and [3D provenance anchoring](#sec-335), which do write to Solana.
**The benchmark** (`GET /api/fact-check-benchmark`) scores a 40-claim fixture (10 per verdict class, deliberately time-stable and non-partisan) against the real chain. The API never fabricates a score: with no run available, `ran` is false and `report` is null, and the page renders a designed "not yet run" empty state. Both the claim set and the scoring runner are linked from the page for inspection. See [Running the benchmark](#running-the-benchmark) for how a run is produced and published.
@@ -51091,7 +53024,7 @@ Read the published benchmark:
curl 'https://three.ws/api/fact-check-benchmark'
```
-Once the free quota is spent, the same POST returns `402` with an x402 challenge; pay it with any x402 client (for example `@three-ws/x402-fetch`) and retry. See [x402](#sec-519).
+Once the free quota is spent, the same POST returns `402` with an x402 challenge; pay it with any x402 client (for example `@three-ws/x402-fetch`) and retry. See [x402](#sec-544).
## Running the benchmark
@@ -51154,14 +53087,14 @@ Two guards keep a bad run from becoming a published number:
## Related
-- [x402: paid agent skills](#sec-519): the payment rail the $0.10 lane rides
+- [x402: paid agent skills](#sec-544): the payment rail the $0.10 lane rides
- [API reference: Fact Check API](#sec-096): the endpoint's full request and response reference
-- [SAS credentialed attestations](#sec-367) and [3D provenance](#sec-329): the platform's on-chain attestation primitives (distinct from this content-hash attestation)
+- [SAS credentialed attestations](#sec-372) and [3D provenance](#sec-335): the platform's on-chain attestation primitives (distinct from this content-hash attestation)
- Pages: [/fact-check](https://three.ws/fact-check) · [/x402](https://three.ws/x402)
---
-<a id="sec-218"></a>
+<a id="sec-220"></a>
> **Source:** `docs/farcaster-memory-seeding.md` · [↑ table of contents](#table-of-contents)
@@ -51180,7 +53113,7 @@ own verification records.
- **Surface**: the Farcaster panel in the agent persona editor at [/dashboard/agents](https://three.ws/dashboard/agents)
- **API**: `/api/agents/:id/memory/seed/farcaster`
-- **Related**: [Memory system](#sec-279), [`@three-ws/agent-memory`](https://www.npmjs.com/package/@three-ws/agent-memory)
+- **Related**: [Memory system](#sec-280), [`@three-ws/agent-memory`](https://www.npmjs.com/package/@three-ws/agent-memory)
---
@@ -51411,7 +53344,7 @@ only its own rows and a revoke deletes exactly what was granted.
---
-<a id="sec-219"></a>
+<a id="sec-221"></a>
> **Source:** `docs/financial-controls.md` · [↑ table of contents](#table-of-contents)
@@ -51424,7 +53357,7 @@ on-chain transaction is captured, whether it is reconciled against the chain, an
how long it is retained** — plus the monitoring/breach controls around it and the
open gaps ranked by accounting/regulatory risk.
-It is a companion to the [money map](#sec-286) (who receives what) and the
+It is a companion to the [money map](#sec-287) (who receives what) and the
[Solana signers runbook](../api/_lib/solana-signers.js) (the
wallets). Keep it in sync with the code — every row cites its source.
@@ -51702,114 +53635,20 @@ Ranked by accounting/regulatory risk. Each is a tracked remediation item.
re-run `check-relayer-balances.mjs` to confirm balances.
- **Before adding a paid flow:** it is not done until it writes an append-only
ledger row with the on-chain signature and a `UNIQUE` idempotency key, and is
- added to this register and the [money map](#sec-286).
+ added to this register and the [money map](#sec-287).
---
## Related
-- [Money map](#sec-286) — who receives each payment.
-- [x402 revenue & receipts](#sec-515) — the x402 recording detail.
-- [x402 endpoints](#sec-514) — the paid endpoint catalog.
+- [Money map](#sec-287) — who receives each payment.
+- [x402 revenue & receipts](#sec-540) — the x402 recording detail.
+- [x402 endpoints](#sec-539) — the paid endpoint catalog.
- [Solana signers runbook](../api/_lib/solana-signers.js) — the wallets + funding.
---
-<a id="sec-220"></a>
-
-> **Source:** `docs/fomo-verified-x-post.md` · [↑ table of contents](#table-of-contents)
-
-# X post: $THREE verified on fomo
-
-Copy for announcing that **$THREE (the token) is verified on [fomo](https://fomo.family)** (@fomo
-on X), the social-first crypto trading app from ex-Uniswap / Opensea / dYdX builders. fomo is
-self-custodial, onramps with Apple Pay, and trades Solana assets in-app.
-
-**What this announcement is:** a safety note. Holders and new users get one more vetted,
-verifiable venue to acquire $THREE, where the app itself marks the real listing so nobody is
-guessing between lookalike mints.
-
-**What it is not:** a price post. No moon language, no "don't miss out", no predictions, no
-telling anyone to buy. State the verification, state why verification matters, stop.
-
-**Media for every option:** [fomo-verified-x.png](media/fomo-verified-x.png) (2400x1350, 16:9,
-dark mode: $THREE cube mark x fomo mark, "verified" badge). Built from fomo's own 1024px mark and
-`public/brand/three-ws-mark.png` on fomo's `#0B091F` navy.
-
-Rules:
-
-1. Tag @fomo so their team sees it and can repost.
-2. Claim only what happened: $THREE is verified in the fomo app. three.ws does not trade on fomo
- and no post should imply it does.
-3. Including the contract address is encouraged. Repeating the real mint is anti-scam hygiene,
- not shilling: `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`
-
----
-
-## 1. Main post
-
-> $THREE is now verified on @fomo.
->
-> What that means in practice: search $THREE in the fomo app and the verified badge marks the
-> real listing. No guessing between lookalike mints.
->
-> We want acquiring $THREE to be safe and verifiable, wherever you do it. fomo is now one of
-> those places: self-custodial, on Solana.
->
-> fomo.family
-
----
-
-## 2. Short alternate
-
-> $THREE now carries the verified badge on @fomo.
->
-> If you pick up $THREE, use a venue that verifies the mint, and always check the CA yourself:
->
-> FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
-
----
-
-## 3. Safety-PSA alternate
-
-> A note for anyone acquiring $THREE: it is now verified on @fomo.
->
-> Verified listings exist because copycat mints exist. Whatever venue you use, buy the marked,
-> vetted listing and confirm the contract address:
->
-> FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
->
-> Self-custody the rest.
-
-Pick one. Do not post all three.
-
----
-
-## 4. Thread closer (reply to the main post)
-
-Post this as a reply to whichever option ran, to cap the thread. The graphic carries the
-disclaimer, so the reply text stays short.
-
-**Media:** [fomo-thread-end.png](media/fomo-thread-end.png) (2400x1350, 16:9). Same visual
-system as the main graphic, "/ end of thread" as the headline, and the fine print baked in:
-the not-financial-advice / do-your-own-research statement plus the full contract address.
-
-> That is the whole update. $THREE is verified on @fomo.
->
-> Verify the mint yourself, wherever you trade:
-> FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
->
-> / end
-
-Shorter alternate:
-
-> / end of thread
->
-> Verify before you act: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
-
----
-
-<a id="sec-221"></a>
+<a id="sec-222"></a>
> **Source:** `docs/forge-background-generation.md` · [↑ table of contents](#table-of-contents)
@@ -51929,7 +53768,7 @@ and the notification preference model in
---
-<a id="sec-222"></a>
+<a id="sec-223"></a>
> **Source:** `docs/forge-off.md` · [↑ table of contents](#table-of-contents)
@@ -52046,7 +53885,7 @@ Backfill a past week's winner (owner): `GET /api/cron/forge-off-crown?week=YYYY-
---
-<a id="sec-223"></a>
+<a id="sec-224"></a>
> **Source:** `docs/forge-pipeline.md` · [↑ table of contents](#table-of-contents)
@@ -52054,7 +53893,7 @@ Backfill a past week's winner (owner): `GET /api/cron/forge-off-crown?week=YYYY-
This is the engineering guide to the Forge, the text/image/sketch to 3D generation system behind [/forge](https://three.ws/forge), the free MCP tools, and every agent-facing 3D endpoint. It maps the whole path a generation takes: entry points, the engine grid, free-first routing, the job lifecycle, failover, persistence, GPU workers, post-processing, and payments.
-If you want the product-level overview, read [Forge](#sec-224). If you want the plain-language version, read [How the Forge works](#sec-238). This document is for people changing the pipeline.
+If you want the product-level overview, read [Forge](#sec-225). If you want the plain-language version, read [How the Forge works](#sec-239). This document is for people changing the pipeline.
## Bird's-eye view
@@ -52191,7 +54030,7 @@ Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forg
### Poll
-`GET /api/forge?job=<id>` returns `status`: `queued`, `running`, `done` (with `glb_url`, `viewer_url`, and the `path`/`tier`/`backend` that actually produced it), or `failed`. Polling is free and unauthenticated. The in-flight job id is also written to `localStorage`, so an interrupted browser session resumes polling for up to 30 minutes; background completion persists the result to the user's gallery either way (see [Background generation](#sec-221)).
+`GET /api/forge?job=<id>` returns `status`: `queued`, `running`, `done` (with `glb_url`, `viewer_url`, and the `path`/`tier`/`backend` that actually produced it), or `failed`. Polling is free and unauthenticated. The in-flight job id is also written to `localStorage`, so an interrupted browser session resumes polling for up to 30 minutes; background completion persists the result to the user's gallery either way (see [Background generation](#sec-222)).
**Poll-time failover** (`api/_lib/forge-failover.js`) closes the nastier gap: a self-host worker can accept a task and fail it minutes later, in a poll handled by a different instance that no longer holds the request. On a failed poll the module recovers the original inputs (prompt plus reference image) from the creation row, resubmits to the next configured lane, and binds old handle to new handle in Redis (2 hour TTL). The client keeps polling the same job id and simply sees `status: running` with a new `backend`. Hops are capped by `MAX_FAILOVER_HOPS = 3` (one primary plus up to three backups). The redispatch order is `trellis_selfhost`, `hunyuan3d`, `trellis`: HuggingFace is excluded because its provider blocks through the whole generation (cannot be ridden from a poll), and NVIDIA is excluded because poll-time redispatch always reconstructs from a stored reference image, which NIM rejects.
@@ -52296,17 +54135,17 @@ Fast diagnostics: `forge_creations` carries per-generation backend, status, erro
## Related
-- [Forge](#sec-224), the product-level doc for the /forge surface.
-- [How the Forge works](#sec-238), the plain-language explainer.
+- [Forge](#sec-225), the product-level doc for the /forge surface.
+- [How the Forge works](#sec-239), the plain-language explainer.
- [3D pipeline](#sec-003), the pay-per-stage x402 pipeline (rig, remesh, gameready, stylize, rembg).
- [3D asset pipeline](#sec-002), formats and the animation/conversion flow.
-- [Avatar pipeline](#sec-112), the selfie-to-avatar reconstruction flow.
-- [Background generation](#sec-221), job resume and gallery persistence.
+- [Avatar pipeline](#sec-113), the selfie-to-avatar reconstruction flow.
+- [Background generation](#sec-222), job resume and gallery persistence.
- `workers/README.md`, the worker-by-worker operational reference.
---
-<a id="sec-224"></a>
+<a id="sec-225"></a>
> **Source:** `docs/forge.md` · [↑ table of contents](#table-of-contents)
@@ -52515,16 +54354,16 @@ dashboard at [/quality-bench](https://three.ws/quality-bench) (internal).
## Related
-- [The Forge pipeline](#sec-223) is the architecture deep dive: the engine grid, routing, failover, job lifecycle, workers, and payments, end to end. [How the Forge works](#sec-238) is the same story in plain language.
-- [Image to 3D](#sec-250) is the photo lane opened directly at [/image-to-3d](https://three.ws/image-to-3d).
+- [The Forge pipeline](#sec-224) is the architecture deep dive: the engine grid, routing, failover, job lifecycle, workers, and payments, end to end. [How the Forge works](#sec-239) is the same story in plain language.
+- [Image to 3D](#sec-251) is the photo lane opened directly at [/image-to-3d](https://three.ws/image-to-3d).
- [/forge-max](https://three.ws/forge-max) is the maximum-quality lane opened directly: the same Forge with the High tier pinned on arrival (200k-poly target, 4K PBR and HD textures, subject-aware engine routing). `?tier=draft|standard|high` presets the quality selector on any Forge URL the same way. The High tier's $THREE hold-or-pay gate applies unchanged; BYOK engines (your own Meshy, Tripo, or Rodin key) are exempt as always. For DamagedHelmet-class artist benchmarks, remember the ceiling is the current state of generative 3D, not the routing: this lane maxes every budget the engines expose, and [Measuring realism](#measuring-realism) is how we track that ceiling moving.
-- [Diorama](#sec-174) forges a whole scene of Forge objects into one explorable world.
+- [Diorama](#sec-177) forges a whole scene of Forge objects into one explorable world.
- The 3D generation architecture: [3D pipeline](#sec-003), [3D asset pipeline](#sec-002), [3D API](#sec-001).
- Pages: [/create](https://three.ws/create) (the avatar creator), [/scene](https://three.ws/scene) (Scene Studio), [/restyle](https://three.ws/restyle) (re-skin a GLB), [/gallery](https://three.ws/gallery).
---
-<a id="sec-225"></a>
+<a id="sec-226"></a>
> **Source:** `docs/forged.md` · [↑ table of contents](#table-of-contents)
@@ -52532,7 +54371,7 @@ dashboard at [/quality-bench](https://three.ws/quality-bench) (internal).
[three.ws/forged](https://three.ws/forged) is a public gallery of 3D props that
the platform's own autonomous agents bought with real USDC over the
-[x402 payment protocol](#sec-519). Nothing on the page is curated or seeded by
+[x402 payment protocol](#sec-544). Nothing on the page is curated or seeded by
hand: an agent wallet paid the Forge, the Forge generated the prop, the payment
settled on Solana mainnet, and the finished asset landed in the gallery carrying
its receipt. Every card shows the price paid, the paying agent wallet, and a
@@ -52582,7 +54421,7 @@ runs as a registry entry inside that loop, and on each run it:
is a real on-chain USDC transfer from the loop's seeder wallet, settled by
the platform's self-hosted facilitator on Solana mainnet. The same seeder
wallet is the `x402-ring-payer` signer in the
- [x402 ring economy](#sec-516), and the loop's daily spend cap
+ [x402 ring economy](#sec-541), and the loop's daily spend cap
applies to these calls like every other.
3. **Scores diversity.** The prompt is embedded (a configured provider when
available, a deterministic local feature-hash space otherwise) and scored
@@ -52660,21 +54499,21 @@ The endpoint is also listed in the [API reference](#sec-096).
- [Autonomous x402 loop](#sec-105): the engine that buys these
assets, its spend caps, and where every call is logged.
-- [x402 ring economy](#sec-516): the wider self-paid endpoint
+- [x402 ring economy](#sec-541): the wider self-paid endpoint
economy the seeder wallet participates in.
-- [How the Forge works](#sec-238): the generation pipeline the
+- [How the Forge works](#sec-239): the generation pipeline the
agents are paying for.
-- [x402 on three.ws](#sec-519): the payment protocol itself.
+- [x402 on three.ws](#sec-544): the payment protocol itself.
---
-<a id="sec-226"></a>
+<a id="sec-227"></a>
> **Source:** `docs/free-crypto-apis.md` · [↑ table of contents](#table-of-contents)
# Free crypto APIs we have not integrated yet
-Research catalog, 2026-08-05. Companion to [free-llm-providers.md](#sec-227).
+Research catalog, 2026-08-05. Companion to [free-llm-providers.md](#sec-228).
**Status update 2026-08-06: every keyless provider in this catalog is now integrated.** Shipped in eight workstreams: the seven CEX public-data venues (Binance, OKX, Bybit, KuCoin, Gate.io, MEXC, Bitget) as market/chart fallback rungs; RedStone and Switchboard as SOL price oracle rungs; RugCheck fused with GoPlus and Honeypot.is wired into EVM token risk; Deribit options/perp data beside Hyperliquid plus Jupiter's unused lite endpoints; a keyless EVM swap-quote chain (ParaSwap, KyberSwap, LI.FI) at `/api/v1/evm/swap-quote`; Coin Metrics fundamentals, Blockchair chain stats, and Blockstream Esplora Bitcoin reads; six subreddits in the news pipeline (JSON with Atom fallback, since Reddit 403s datacenter JSON traffic); and a gas oracle chain (Blocknative, Owlracle, Etherscan) at `/api/v1/gas`. Deliberately skipped: CoinMarketCap's keyless trial endpoints (evaluation-only under their terms). Everything still listed as needing a key below remains open.
@@ -52823,7 +54662,7 @@ Adoption rules that still apply: these are all free tiers, so no owner approval
---
-<a id="sec-227"></a>
+<a id="sec-228"></a>
> **Source:** `docs/free-llm-providers.md` · [↑ table of contents](#table-of-contents)
@@ -52885,11 +54724,11 @@ All of these rungs are zero-marginal-cost, and the accounting knows it:
6. If the provider should be user-selectable in chat: register it in `api/chat.js` (`PROVIDERS`, the provider enum, `FALLBACK_SIBLINGS`) and `api/_lib/chat-models.js` (`MODEL_CATALOG`, `PROVIDER_MODEL_DEFAULTS`, `DEFAULT_PROVIDER_ORDER`, `ANON_PROVIDER_LIST`).
7. `.env.example` and the env tables in [`ARCHITECTURE.md`](../ARCHITECTURE.md).
-Related: [nvidia-models.md](#sec-296) for the full NVIDIA NIM surface map.
+Related: [nvidia-models.md](#sec-297) for the full NVIDIA NIM surface map.
---
-<a id="sec-228"></a>
+<a id="sec-229"></a>
> **Source:** `docs/galaxy.md` · [↑ table of contents](#table-of-contents)
@@ -52967,13 +54806,13 @@ curl -X POST 'https://three.ws/api/galaxy' \
## Related
-- [IBM Granite suite](#sec-249): the full set of watsonx-powered features on three.ws, including the Granite embeddings that position this galaxy.
+- [IBM Granite suite](#sec-250): the full set of watsonx-powered features on three.ws, including the Granite embeddings that position this galaxy.
- [Agent system](#sec-064) and [Agent reputation](#sec-056): what a "star" is and how agents earn standing.
- Pages: [/galaxy](https://three.ws/galaxy), [/create](https://three.ws/create), [/agents](https://three.ws/agents).
---
-<a id="sec-229"></a>
+<a id="sec-230"></a>
> **Source:** `docs/generation-watch.md` · [↑ table of contents](#table-of-contents)
@@ -52994,7 +54833,7 @@ The page is a single self-contained file,
Watch links are minted by the 3D Studio Actions surface, `POST /api/3d/studio`
([api/3d/studio.js](../api/3d/studio.js)), the REST contract behind the
-[three.ws 3D Studio custom GPT](#sec-136). Fast generations
+[three.ws 3D Studio custom GPT](#sec-138). Fast generations
return `status: "done"` with the model URLs directly and never need a watch
page. When a job cannot finish inside the request window, the response is
`status: "pending"` and carries three handles:
@@ -53015,7 +54854,7 @@ does) lands on the designed empty state, which points to
## What the page shows
-The page polls `GET /api/3d/studio?job=<id>` and moves through four states:
+The page polls `GET /api/3d/studio?job=<id>` and moves through five states:
- **Waiting.** A countdown ring with the estimated time remaining, updated
locally at 4 Hz between polls so the timer never freezes. Until the API
@@ -53029,7 +54868,7 @@ The page polls `GET /api/3d/studio?job=<id>` and moves through four states:
painted reference image, the first step of the text-to-3D pipeline), it fades
in with the caption "Concept art, now being sculpted into 3D". This is the
same paint-then-reconstruct flow described in
- [How the Forge works](#sec-238).
+ [How the Forge works](#sec-239).
- **Ready.** When the poll returns `status: "done"`, the page shows "opening
the viewer" and redirects itself into the interactive viewer after a short
beat, using the API's `viewerUrl` (or building a `/viewer?src=<glb>` link
@@ -53038,6 +54877,13 @@ The page polls `GET /api/3d/studio?job=<id>` and moves through four states:
link (HTTP 400), or a job that produces no viewer link shows an honest error
with a one-click "Forge it again" path. Generation is free, so retrying
costs nothing.
+- **Offline.** Four consecutive failed polls (a dropped connection, a captive
+ portal, a tab woken on a dead network) stop the countdown and say so, rather
+ than animating a timer against a server nobody is talking to. This state is
+ resumable, not terminal: it offers a "Keep watching" button that picks the
+ poll loop back up where it left off, and the page resumes on its own as soon
+ as the browser fires `online`. The copy is explicit that the generation is
+ still running server-side, because it is.
Polling is adaptive: the interval scales with the remaining estimate (clamped
between 4 and 10 seconds), a 429 respects the server's `retry_after`, and a
@@ -53045,6 +54891,22 @@ network blip just retries after 6 seconds. If nothing has finished after 40
minutes the page stops itself and says so, rather than spinning forever in a
forgotten tab.
+The redirect target is checked before it is followed: `viewerUrl` is honoured
+only when it resolves to this origin or to `three.ws`, so the hand-off can
+never be pointed off-platform.
+
+## Accessibility and presentation
+
+The page carries one `<h1>` (the generation's title, or "Watching your 3D
+generation" when the link has no `title`), and each state's heading is an
+`<h2>` beneath it. State changes are announced through a single visually
+hidden `role="status"` region rather than by wrapping the countdown in a live
+region, which would otherwise read the 4 Hz timer aloud continuously. It
+follows the site theme in both light and dark, and reserves its footer bar's
+height with the shared corner stack
+([public/corner-stack.js](../public/corner-stack.js)) so the site-wide Cmd+K
+hint and language switcher stack above the CTA row instead of covering it.
+
## Relation to background generation
The watch page is a viewport, not the tracker. All job state lives
@@ -53052,23 +54914,23 @@ server-side: the platform tracks every generation to completion whether or not
any tab is watching, finished models land in the creator's gallery, and
unattended completions notify through the bell, push, and email channels. That
machinery is documented in
-[Background generation and completion notifications](#sec-221).
+[Background generation and completion notifications](#sec-222).
Closing the watch tab mid-job therefore loses nothing; reopening the same
`?job=` link resumes exactly where the generation actually is.
## Related
-- [How the Forge works](#sec-238): the pipeline behind the
+- [How the Forge works](#sec-239): the pipeline behind the
countdown.
-- [Background generation](#sec-221): server-side
+- [Background generation](#sec-222): server-side
tracking, resume, and notifications.
-- [The 3D Studio GPT](#sec-136): the main surface that hands
+- [The 3D Studio GPT](#sec-138): the main surface that hands
out watch links.
- [API reference](#sec-096): the full `/api/3d/studio` contract.
---
-<a id="sec-230"></a>
+<a id="sec-231"></a>
> **Source:** `docs/genesis.md` · [↑ table of contents](#table-of-contents)
@@ -53094,7 +54956,7 @@ real job state, so a first-time visitor goes from an idea to a wallet-holding,
animation-ready agent they fully own in under a minute of active work. It is the
front door: the artifact it produces is a first-class agent that plugs straight
into [Agent Studio](#sec-062), the [economy](#sec-104),
-[breeding](#sec-231), and every embed surface.
+[breeding](#sec-232), and every embed surface.
## How it works
@@ -53115,7 +54977,7 @@ never invents a shortcut path; it orchestrates the real ones.
Genesis resolves it via `GET /api/agents?avatar_id=...`, then calls
`POST /api/agents/:id/wallet/provision` to guarantee both a custodial Solana
address and a custodial EVM address exist. These are real custodial keys held for
- the agent (see [Agent Wallets](#sec-072) and [Custody](#sec-167)),
+ the agent (see [Agent Wallets](#sec-072) and [Custody](#sec-170)),
Solana first because Solana is the home chain.
- **Persona and voice.** `POST /api/persona/extract` synthesizes a structured
in-character system prompt from your description, running through the shared LLM
@@ -53128,7 +54990,7 @@ never invents a shortcut path; it orchestrates the real ones.
`/api/tts/voices`. Your chosen name, persona, and voice are persisted with
`PATCH /api/agents/:id`.
- **On-chain identity (optional).** The final step mints a real
- [ERC-8004](#sec-185) identity record for the agent and returns a real tx
+ [ERC-8004](#sec-188) identity record for the agent and returns a real tx
hash, defaulting to Base (chain id 8453) to match the rest of the platform's EVM
identity layer. This step is optional: the agent is fully functional without it.
@@ -53150,8 +55012,8 @@ never invents a shortcut path; it orchestrates the real ones.
6. **Optionally bind an on-chain identity.** One click registers the ERC-8004 record
and shows the returned transaction hash.
7. **You now own a complete agent.** Open it in [Agent Studio](#sec-062) to
- keep authoring, drop it on a site via [Integrations](#sec-253), or breed
- it in [Agent Genome](#sec-231).
+ keep authoring, drop it on a site via [Integrations](#sec-254), or breed
+ it in [Agent Genome](#sec-232).
## Examples
@@ -53209,16 +55071,16 @@ curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/wallet/provision" \
## Related
- [Agent Studio](#sec-062): keep authoring the agent Genesis created
-- [Agent Genome](#sec-231): breed two agents into an inherited child
-- [Avatar Reconstruction](#sec-113): the selfie-to-3D pipeline
-- [Agent Wallets](#sec-072) and [Custody](#sec-167): the custodial keys
-- [ERC-8004](#sec-185): the on-chain identity record
-- [Persona Hub](#sec-318): how personas are synthesized
+- [Agent Genome](#sec-232): breed two agents into an inherited child
+- [Avatar Reconstruction](#sec-114): the selfie-to-3D pipeline
+- [Agent Wallets](#sec-072) and [Custody](#sec-170): the custodial keys
+- [ERC-8004](#sec-188): the on-chain identity record
+- [Persona Hub](#sec-323): how personas are synthesized
- Pages: [/genesis](https://three.ws/genesis), [/create](https://three.ws/create), [/agent-studio](https://three.ws/agent-studio)
---
-<a id="sec-231"></a>
+<a id="sec-232"></a>
> **Source:** `docs/genome.md` · [↑ table of contents](#table-of-contents)
@@ -53351,16 +55213,16 @@ curl -s "https://three.ws/api/genome/lineage?agentId=<child-uuid>&verify=1"
## Related
-- [Instant Agent Genesis](#sec-230): mint the parents in under a minute
+- [Instant Agent Genesis](#sec-231): mint the parents in under a minute
- [Agent Skills](#sec-060): the skill licenses that recombine
- [Agent Wallets](#sec-072): the fresh child wallet
- [Agent Reputation](#sec-056): how pedigree feeds standing
-- [ERC-8004](#sec-185): on-chain identity for bred agents
+- [ERC-8004](#sec-188): on-chain identity for bred agents
- Pages: [/genome](https://three.ws/genome), [/agent-studio](https://three.ws/agent-studio)
---
-<a id="sec-232"></a>
+<a id="sec-233"></a>
> **Source:** `docs/ghost-copy.md` · [↑ table of contents](#table-of-contents)
@@ -53520,7 +55382,7 @@ renders the summary without it is misrepresenting the result.
cautious question with a basket instead of a single leader.
- Downstream: [/vaults](https://three.ws/vaults) is where a convinced visitor
copies with real money, under segregated custody and hard spend limits. See
- [docs/copy-trading.md](#sec-162) for that engine.
+ [docs/copy-trading.md](#sec-165) for that engine.
- A leader's underlying record: `/trader/<agent_id>`, one click from every result.
## Source
@@ -53535,7 +55397,7 @@ renders the summary without it is misrepresenting the result.
---
-<a id="sec-233"></a>
+<a id="sec-234"></a>
> **Source:** `docs/github-memory-seeding.md` · [↑ table of contents](#table-of-contents)
@@ -53546,24 +55408,32 @@ READMEs you pick, distilled and written into the agent's long-term memory, so
it can speak concretely about what you build instead of guessing.
This lane is built around one constraint. Connecting your GitHub account is
-permission to read it. It is **not** permission to read all of it. The OAuth
+permission to read it. It is **not** permission to read all of it. The
connection unlocks the consent screen, and the consent screen is a per-item
catalog: your profile, your pinned repositories, your recent public
repositories, and a separate README tick per repository. **A seed reads exactly
the items you ticked and nothing else**, and the server enforces that by
refusing any selection that names an item the catalog never showed you.
+There are two ways to connect and they meet immediately: OAuth, one click,
+available when the deployment has a GitHub OAuth app registered; or a personal
+access token you mint yourself, available always, which is the way in when no
+OAuth app exists and which is refused outright if it carries more access than
+seeding can use. Both write the same encrypted connection record and lead to
+the same consent screen.
+
- **Surface**: Settings, Connected accounts, GitHub card at [/settings#connected-accounts](https://three.ws/settings#connected-accounts)
-- **API**: `/api/agents/:id/memory/seed/github`
-- **Related**: [Memory system](#sec-279), [X memory seeding](#sec-510), [Farcaster memory seeding](#sec-218)
+- **API**: `/api/agents/:id/memory/seed/github`, `/api/auth/github/token`
+- **Related**: [Memory system](#sec-280), [X memory seeding](#sec-515), [Farcaster memory seeding](#sec-220)
---
## How it fits together
```
- Connect GitHub (OAuth, read:user + public_repo, token stored encrypted)
- │ the connection alone reads and stores nothing
+ Connect GitHub (OAuth, or a personal access token you paste)
+ │ either way the token is stored encrypted, and the
+ │ connection alone reads and stores nothing
▼
GET /api/agents/:id/memory/seed/github
│ builds the consent catalog live from GitHub:
@@ -53644,11 +55514,62 @@ behind a broken replacement.
---
+## Connecting with a personal access token
+
+OAuth needs an operator to register a GitHub OAuth app (see Configuration
+below). Until that exists, `/api/auth/github/connect` can only answer `501`, so
+the Settings card offers the token path instead, and offers it as a secondary
+option even where OAuth works.
+
+You mint the token on GitHub, which is where consent happens exactly as it does
+on the OAuth screen. Tick **`read:user`** and nothing else: seeding reads a
+public profile, public repositories, and their READMEs, none of which needs
+more than that.
+
+```bash
+curl -s https://three.ws/api/auth/github/token --cookie "$JAR" \
+ -H 'content-type: application/json' -H "x-csrf-token: $CSRF" \
+ -d '{"token":"ghp_your_token_here"}'
+```
+
+```json
+{
+ "connected": true,
+ "connect_method": "token",
+ "token_kind": "classic",
+ "username": "you",
+ "connected_at": "2026-08-16T16:53:49.030Z",
+ "scopes": ["read:user"]
+}
+```
+
+**An over-privileged token is refused, not stored.** The endpoint reads the
+token's grants from GitHub's `x-oauth-scopes` response header and checks them
+against an allowlist (`ALLOWED_TOKEN_SCOPES` in
+[api/_lib/github-token.js](../api/_lib/github-token.js)): `read:user`,
+`user:email`, `user:follow`, `user`, `public_repo`, `repo:status`, `read:org`.
+Anything else, `repo` and `delete_repo` and every `admin:` scope included, comes
+back as `400 token_scope_refused` naming the offending scopes, and nothing is
+written. It is an allowlist rather than a denylist so a scope GitHub invents
+later is refused by default. `repo` is excluded deliberately: it reaches private
+repositories, and the catalog is public-only by construction, so it is strictly
+more access than the feature can ever use.
+
+Fine-grained tokens (`github_pat_…`) and GitHub App user tokens omit the scope
+header entirely; their permissions were already narrowed by whoever minted them,
+so they are accepted as they are and reported as `token_kind: "fine_grained"`.
+
+Disconnecting destroys our encrypted copy and deletes every seeded memory, the
+same as OAuth. It cannot revoke the token on GitHub's side, because GitHub
+exposes no way to delete a personal access token using that same token, so the
+response says so plainly (`grant_revoked: false`) and returns
+`revoke_url: "https://github.com/settings/tokens"` for you to finish the job.
+
## Configuration
-The consent catalog, the seed, and the revoke all run off a user's own OAuth
-token, so a deployment needs a GitHub OAuth app before the Connect button can
-do anything. Register one at
+OAuth is optional. Without it the token path above still works, and the whole
+lane (catalog, seed, revoke) behaves identically. To offer the one-click
+button, register an OAuth app at
[github.com/settings/developers](https://github.com/settings/developers) with
the authorization callback URL set to `<your origin>/api/auth/github/callback`
(production: `https://three.ws/api/auth/github/callback`), then set two
@@ -53665,9 +55586,11 @@ rotating `JWT_SECRET` invalidates stored tokens (users reconnect) rather than
decrypting them into garbage.
Until both variables are present, `GET /api/auth/github/status` answers
-`configured: false`, `/api/auth/github/connect` answers `501 not_configured`,
-and the Settings card renders an explicit "unavailable on this deployment"
-state instead of a button that cannot work. Everything else on the lane is
+`configured: false` and `/api/auth/github/connect` answers `501 not_configured`.
+The Settings card then leads with the token form rather than a button that
+cannot work. `status` always reports `token_connect.available: true` alongside
+the `create_url` that pre-selects the right scopes, which is how the card knows
+an unconfigured deployment is not a dead end. Everything else on the lane is
unaffected: no other feature depends on these variables.
---
@@ -53732,7 +55655,8 @@ curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/github --cookie "$JAR"
```
Rate-limited to one seed per agent per 6 hours, matching the X and Farcaster
-lanes.
+lanes. A run that stores nothing does not spend the window: see the two
+refunding errors below.
### `DELETE /api/agents/:id/memory/seed/github`
@@ -53745,8 +55669,10 @@ the count. Idempotent.
Disconnecting GitHub from Settings (`DELETE /api/auth/github/disconnect`)
performs the same deletion across **all** of your agents in one transaction
-with the connection row itself, and then asks GitHub to revoke the OAuth grant
-(best effort; the local deletion does not wait on GitHub).
+with the connection row itself. For an OAuth connection it then asks GitHub to
+revoke the grant (best effort; the local deletion does not wait on GitHub). For
+a token connection it reports `grant_revoked: false` with a `revoke_url`,
+because no API can delete a personal access token using that token.
## Errors
@@ -53756,10 +55682,12 @@ with the connection row itself, and then asks GitHub to revoke the OAuth grant
| `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_token` | 400 | GitHub rejected the pasted token (mistyped, truncated, or expired) |
+| `token_scope_refused` | 400 | The pasted token carries scopes outside the allowlist; `refused_scopes` names them |
| `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` |
+| `distill_error` | 502 | The selected material yielded no usable facts; add a README or another repository. Carries `window_refunded` |
+| `distill_unavailable` | 503 | Every model provider was busy, so nothing was read into memory and the existing memories are untouched. Carries `window_refunded`, `providers_tried`, and `retry_at` (null when the window was refunded) |
| rate limited | 429 | One seed per agent per 6 hours |
Only `distill_error` and `distill_unavailable` are reachable after the seed
@@ -53768,6 +55696,16 @@ 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.
+Both of those two also hand the window back. Neither one read anything into
+memory or changed a single stored fact, and in the provider-outage case the
+failure is the platform's, not yours, so the charge is reversed and the next
+attempt is allowed immediately (`window_refunded: true`). Refunding is only
+safe because this is a single-use window: see `refundLimit` in
+[api/_lib/rate-limit.js](../api/_lib/rate-limit.js), which refuses any bucket
+with a ceiling above one. If the refund itself cannot reach the limiter store,
+the reply says so (`window_refunded: false`) and carries the real `retry_at`
+rather than inviting a retry that would only earn a 429.
+
## Source
| Piece | File |
@@ -53775,14 +55713,16 @@ mistyped or stale pick costs you nothing but the retry.
| HTTP surface (status, consent catalog, seed, revoke) | [api/agents/[id]/memory-seed-github.js](../api/agents/[id]/memory-seed-github.js) |
| Catalog, selection narrowing, seed document, memory rows (pure, tested) | [api/_lib/github-seed.js](../api/_lib/github-seed.js) |
| GitHub REST/GraphQL client (profile, repos, pins, README, grant revoke) | [api/_lib/github-api.js](../api/_lib/github-api.js) |
-| HKDF token encryption shared by callback, seeding, and disconnect | [api/_lib/github-token.js](../api/_lib/github-token.js) |
-| OAuth connect, callback, status, disconnect | [api/auth/github/[action].js](../api/auth/github/[action].js) |
+| HKDF token encryption and the personal-access-token scope policy | [api/_lib/github-token.js](../api/_lib/github-token.js) |
+| Connect (OAuth and token), callback, status, disconnect | [api/auth/github/[action].js](../api/auth/github/[action].js) |
| Consent screen (renders the catalog with per-item checkboxes) | [public/settings/index.html](../public/settings/index.html) |
| Transform tests | [tests/github-memory-seed.test.js](../tests/github-memory-seed.test.js) |
+| Route tests for the seed endpoint | [tests/github-memory-seed-endpoint.test.js](../tests/github-memory-seed-endpoint.test.js) |
+| Scope policy and token-connect tests | [tests/github-token-connect.test.js](../tests/github-token-connect.test.js) |
---
-<a id="sec-234"></a>
+<a id="sec-235"></a>
> **Source:** `docs/google-x-accounts.md` · [↑ table of contents](#table-of-contents)
@@ -53894,7 +55834,7 @@ Google also operates many country and regional accounts (for example @GoogleIndi
---
-<a id="sec-235"></a>
+<a id="sec-236"></a>
> **Source:** `docs/guardian.md` · [↑ table of contents](#table-of-contents)
@@ -53920,7 +55860,7 @@ The owner sets this up from their own wallet hub (naming guardians, an approval
The response sorts agents that need your action first, then those with an open process, then the rest, and reports how many need you.
-**The safety rails** (detailed in [custody](#sec-167)) are enforced by the recovery API, not the console:
+**The safety rails** (detailed in [custody](#sec-170)) are enforced by the recovery API, not the console:
- The requester cannot approve their own takeover; at least one other guardian must approve.
- The wallet auto-freezes for autonomous spend the moment a request opens (the real owner's own withdrawal stays open).
@@ -53973,14 +55913,14 @@ The console reads this on load, resolves your viewer id (so it can tell whether
## Related
-- [Custody you can verify](#sec-167) - the full recovery and inheritance model, the freeze switch, spend limits, and proof-of-custody
-- [Financial controls](#sec-219) - the plain-English spend rules on the same wallet rails
+- [Custody you can verify](#sec-170) - the full recovery and inheritance model, the freeze switch, spend limits, and proof-of-custody
+- [Financial controls](#sec-221) - the plain-English spend rules on the same wallet rails
- `GET /api/custody/integrity` - the public Merkle attestation of every custodial wallet, as JSON (the page that rendered it is switched off while on-chain anchoring is unavailable)
- [/proof](https://three.ws/proof) - verify your own wallet's inclusion in the attestation, in your browser
---
-<a id="sec-236"></a>
+<a id="sec-237"></a>
> **Source:** `docs/guards.md` · [↑ table of contents](#table-of-contents)
@@ -54117,6 +56057,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Guard | Command | Protects |
|---|---|---|
| Browser bundle purity | `npm run check:browser-graph` | No Node-only module leaks into the browser bundle. |
+| Bootstrap ordering | `npm run check:tdz-bootstrap` | No page calls its own entry point above the state that entry point writes, which renders fine in Chrome and throws in every Safari. |
| Build output shape | `npm run check:dist` | `dist/` contains every artifact the deploy expects. |
| Deploy artifact preflight | `npm run audit:deploy` | The artifact failure classes that have taken production down. |
| Cloud Build upload | `npm run check:gcloudignore` | What `gcloud builds submit` would actually upload. |
@@ -54228,7 +56169,7 @@ The short version:
---
-<a id="sec-237"></a>
+<a id="sec-238"></a>
> **Source:** `docs/hold-to-access.md` · [↑ table of contents](#table-of-contents)
@@ -54530,19 +56471,19 @@ worlds unaffected.
## Related
-- [Validation](#sec-495) — the quality gate every model passes before publish.
+- [Validation](#sec-501) — the quality gate every model passes before publish.
- [Pricing catalog](../api/_lib/pricing/catalog.js) — fixed-price actions the discount applies to.
- [`/three`](../pages/three.html) — the holder-facing tier page that surfaces this ladder.
---
-<a id="sec-238"></a>
+<a id="sec-239"></a>
> **Source:** `docs/how-forge-works.md` · [↑ table of contents](#table-of-contents)
# How the Forge works, in plain language
-You type "a weathered brass diving helmet" at [three.ws/forge](https://three.ws/forge), and about half a minute later you are orbiting a real, textured 3D model you can download, view in AR, or drop into a scene. No account, no key, no cost. This page explains what actually happens in between, without the engineering detail. (If you want that, read the [architecture deep dive](#sec-223).)
+You type "a weathered brass diving helmet" at [three.ws/forge](https://three.ws/forge), and about half a minute later you are orbiting a real, textured 3D model you can download, view in AR, or drop into a scene. No account, no key, no cost. This page explains what actually happens in between, without the engineering detail. (If you want that, read the [architecture deep dive](#sec-224).)
## The five steps every generation takes
@@ -54576,17 +56517,17 @@ A finished model is a starting point, not a dead end:
## Agents use the exact same machinery
-Everything above is also a tool call. AI agents (Claude, ChatGPT, or your own) generate models through our [free MCP server](#sec-273) or plain HTTP, and other agents pay per call with USDC over [x402](#sec-519), no account needed. The page you use and the API an agent uses are the same pipeline underneath.
+Everything above is also a tool call. AI agents (Claude, ChatGPT, or your own) generate models through our [free MCP server](#sec-274) or plain HTTP, and other agents pay per call with USDC over [x402](#sec-544), no account needed. The page you use and the API an agent uses are the same pipeline underneath.
## Try it
- Type a prompt: [three.ws/forge](https://three.ws/forge)
- Turn photos into a model: [three.ws/image-to-3d](https://three.ws/image-to-3d)
-- The full technical breakdown: [the Forge pipeline deep dive](#sec-223)
+- The full technical breakdown: [the Forge pipeline deep dive](#sec-224)
---
-<a id="sec-239"></a>
+<a id="sec-240"></a>
> **Source:** `docs/how-it-works.md` · [↑ table of contents](#table-of-contents)
@@ -54594,7 +56535,7 @@ Everything above is also a tool call. AI agents (Claude, ChatGPT, or your own) g
This page is the load-bearing mental model. If you're trying to figure out where a feature lives, how a request flows, or which layer to extend — start here.
-For the full deep dive on internals, see [Architecture overview](#sec-100). For the actual JS API, see [JavaScript API](#sec-257) and [REST API](#sec-096). This document zooms out to *how it all fits together*.
+For the full deep dive on internals, see [Architecture overview](#sec-100). For the actual JS API, see [JavaScript API](#sec-258) and [REST API](#sec-096). This document zooms out to *how it all fits together*.
---
@@ -54641,10 +56582,10 @@ The whole stack is split into four horizontal strata. Each layer can run on its
└──────────────────────────────────────────────┘
```
-- **Viewer layer** — pure three.js. Knows nothing about agents, brains, or wallets. Useful on its own as a glTF inspector and as the rendering engine for Turntable / Animation Gallery widgets. See [Layers](#sec-261) for the contract.
+- **Viewer layer** — pure three.js. Knows nothing about agents, brains, or wallets. Useful on its own as a glTF inspector and as the rendering engine for Turntable / Animation Gallery widgets. See [Layers](#sec-262) for the contract.
- **Agent layer** — turns a static GLB into a presence. LLM tool-loop, skill registry, memory, and a continuous emotion blend that drives morphs and gaze. See [Agent system](#sec-064).
-- **Identity layer** — durability across sessions, devices, and embed hosts. Wallet auth, on-chain registration, IPFS-pinned manifest bundles, signed action diary. Entirely optional. See [ERC-8004](#sec-185) and [Solana agents](#sec-388).
-- **Embed layer**: the public face. The `<agent-3d>` custom element, ten widget variants, iframe embeds, the CDN bundle, the SPA, and the route table in `vercel.json` (read at runtime by the Cloud Run server). See [Embedding](#sec-183).
+- **Identity layer** — durability across sessions, devices, and embed hosts. Wallet auth, on-chain registration, IPFS-pinned manifest bundles, signed action diary. Entirely optional. See [ERC-8004](#sec-188) and [Solana agents](#sec-394).
+- **Embed layer**: the public face. The `<agent-3d>` custom element, ten widget variants, iframe embeds, the CDN bundle, the SPA, and the route table in `vercel.json` (read at runtime by the Cloud Run server). See [Embedding](#sec-186).
The four layers communicate through one event bus (`agent-protocol`). Every meaningful action is a `CustomEvent` on a singleton. That single design choice is why you can swap the avatar for a 2D sprite, the runtime for a different LLM, or memory for a vector store — and nothing else changes.
@@ -54685,8 +56626,8 @@ The platform's own chat surfaces run on the multi-model brain router at [`/api/b
Three production paths. Pick whichever fits your use case:
-- **Character Builder** — full-body character builder for stylised humanoids. Pick a base mesh, swap clothing/accessories/hairstyles, save. The output is a rigged GLB. See [character-studio.md](#sec-135).
-- **Selfie capture** — upload a photo, get a rigged 3D version of yourself in ~60 seconds. See [avatar-creation.md](#sec-108).
+- **Character Builder** — full-body character builder for stylised humanoids. Pick a base mesh, swap clothing/accessories/hairstyles, save. The output is a rigged GLB. See [character-studio.md](#sec-137).
+- **Selfie capture** — upload a photo, get a rigged 3D version of yourself in ~60 seconds. See [avatar-creation.md](#sec-109).
- **Upload your own** — any glTF 2.0 / GLB with a humanoid rig works. Drop the file into the editor at [three.ws/create](https://three.ws/create) or POST to `/api/avatars`.
Every avatar ends up as a hosted GLB URL (served from the first-party asset CDN at `three.ws/cdn/<key>`) plus a database record. When you wire one into an agent, the agent's manifest references it under `body.uri`.
@@ -54714,7 +56655,7 @@ On-chain identity is optional. Most agents work fine without it. You'd want it w
- **You want delegated wallet permissions.** ERC-7710 lets you sign once per session and grant the agent scoped, time-bound permission to act on-chain — no per-transaction prompts.
- **You want a portable address.** `agent://base/42` is a stable, resolver-agnostic URI. Any client that speaks the protocol can load it.
-See [erc8004.md](#sec-185) and [solana.md](#sec-388) for the registration flows.
+See [erc8004.md](#sec-188) and [solana.md](#sec-394) for the registration flows.
---
@@ -54724,7 +56665,7 @@ Three independent mechanisms, used as needed:
- **x402** — pay-per-call USDC for paid API endpoints. Every paid endpoint declares itself in [`/.well-known/x402.json`](https://three.ws/.well-known/x402.json). Other agents (or humans with a wallet) can call paid endpoints with a single signed payment header.
- **pump.fun** — launch a Solana SPL token tied to your agent. The platform handles the bonding curve, the token metadata, and the embed.
-- **AWS Marketplace** — enterprise subscriptions billable through AWS. See [aws-marketplace.md](#sec-122). Subscriptions auto-issue an x402 API key via the marketplace entitlement service.
+- **AWS Marketplace** — enterprise subscriptions billable through AWS. See [aws-marketplace.md](#sec-123). Subscriptions auto-issue an x402 API key via the marketplace entitlement service.
You can mix these per agent. A common pattern: an agent has a free public persona on the platform, exposes one paid x402 skill for power users, and accepts donations via a pump.fun token.
@@ -54737,14 +56678,14 @@ Quick lookup for "I want to ship X":
| You want… | Reach for… |
|---|---|
| A 3D character on a marketing page | The CDN script + `<agent-3d>` |
-| A character in Notion / Webflow / Framer | An iframe widget from [Widget Studio](#sec-504) |
+| A character in Notion / Webflow / Framer | An iframe widget from [Widget Studio](#sec-510) |
| A talking AI sidekick that follows visitors | `<agent-3d mode="floating">` |
-| A character that controls a scene from page events | The JS API (`agent.say()`, `agent.ask()`) — see [js-api.md](#sec-257) |
+| A character that controls a scene from page events | The JS API (`agent.say()`, `agent.ask()`) — see [js-api.md](#sec-258) |
| Programmatic avatar viewing/creation in your own app | `@three-ws/avatar` |
-| An on-chain identity for your AI | [ERC-8004](#sec-185) or [Solana](#sec-388) |
-| A paid API anyone (including agents) can call | [x402 monetization](#sec-519) |
-| Multiple agents in one scene | `<agent-stage>` — see [multi-agent.md](#sec-289) |
-| To register a domain (e.g. ENS) as agent identity | [register-onchain.md tutorial](#sec-456) |
+| An on-chain identity for your AI | [ERC-8004](#sec-188) or [Solana](#sec-394) |
+| A paid API anyone (including agents) can call | [x402 monetization](#sec-544) |
+| Multiple agents in one scene | `<agent-stage>` — see [multi-agent.md](#sec-290) |
+| To register a domain (e.g. ENS) as agent identity | [register-onchain.md tutorial](#sec-462) |
---
@@ -54752,12 +56693,12 @@ Quick lookup for "I want to ship X":
- **[Architecture overview](#sec-100)** — full internals
- **[Agent system](#sec-064)** — runtime, skills, memory, emotion
-- **[Layers](#sec-261)** — the four-layer contract in detail
-- **[Quick start](#sec-356)** — go from zero to a living embed in under 10 minutes
+- **[Layers](#sec-262)** — the four-layer contract in detail
+- **[Quick start](#sec-361)** — go from zero to a living embed in under 10 minutes
---
-<a id="sec-240"></a>
+<a id="sec-241"></a>
> **Source:** `docs/i18n.md` · [↑ table of contents](#table-of-contents)
@@ -55161,7 +57102,7 @@ clearing silently-English values out of a shipped catalog.
---
-<a id="sec-241"></a>
+<a id="sec-242"></a>
> **Source:** `docs/ibm-community-article.md` · [↑ table of contents](#table-of-contents)
@@ -55281,7 +57222,7 @@ The platform repository is public at [github.com/nirholas/three.ws](https://gith
---
-<a id="sec-242"></a>
+<a id="sec-243"></a>
> **Source:** `docs/ibm-community-blog-meetup-jessica.md` · [↑ table of contents](#table-of-contents)
@@ -55342,7 +57283,7 @@ See you Friday at 8 AM Pacific. I will be the one asking the skeptical questions
---
-<a id="sec-243"></a>
+<a id="sec-244"></a>
> **Source:** `docs/ibm-community-live-reaction-jessica.md` · [↑ table of contents](#table-of-contents)
@@ -55353,7 +57294,7 @@ This is a discussion post for the [Three.ws User Group on IBM
Community](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016),
not a polished announcement, just my honest reaction while the day is happening. My earlier post,
[Join the Three.ws User Group's First In-World Meetup This
-Friday](#sec-242), has the event details if you have not joined yet;
+Friday](#sec-243), has the event details if you have not joined yet;
the world is still open._
I'm posting this in the middle of the day, not after, because I want the group to have my honest
@@ -55394,7 +57335,7 @@ Full recap once the day wraps.
follow-up, not a replacement for the original event post.
- **Do not post an X/Twitter version of this.** This content is for the IBM Community group only;
the group is the audience that gets the personal, honest register. The `@trythreews` and
- `@nichxbt` X copy in [event-x-posts.md](#sec-214) is a separate, distinct campaign and
+ `@nichxbt` X copy in [event-x-posts.md](#sec-519) is a separate, distinct campaign and
stays in its organizer voice.
- **Let Jessica edit freely.** This is a starting draft in her established voice (see the section
"Why I think this format is worth your hour" in her earlier blog post), not a final script.
@@ -55408,13 +57349,13 @@ Full recap once the day wraps.
any mentions resolve correctly.
- "Pilled" is her own word; keep it if it still feels true when she posts, or soften to "changed my
mind about it" if she wants a more IBM-official register for her own profile.
-- Once posted, add it to the catalog in [ibm-community.md](#sec-247) as a new discussion
+- Once posted, add it to the catalog in [ibm-community.md](#sec-248) as a new discussion
thread entry, following the same fields (author, posted date, activity, URL, summary) as the
existing entries, and note it links back to the pinned meetup thread.
---
-<a id="sec-244"></a>
+<a id="sec-245"></a>
> **Source:** `docs/ibm-community-recap-jessica.md` · [↑ table of contents](#table-of-contents)
@@ -55423,8 +57364,8 @@ Full recap once the day wraps.
_By Jessica Swanson, posted as a follow-up blog in the [Three.ws User Group on IBM
Community](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016),
closing out the arc that started with [Join the Three.ws User Group's First In-World Meetup This
-Friday](#sec-242) and continued mid-day with [LIVE at the Meetup: My
-Honest Take So Far](#sec-243). Header image: reuse
+Friday](#sec-243) and continued mid-day with [LIVE at the Meetup: My
+Honest Take So Far](#sec-244). Header image: reuse
[media/ibm-x-threews-lockup.png](media/ibm-x-threews-lockup.png), or swap in a real photo from
the day once one is ready; do not paste this note into the published post._
@@ -55553,14 +57494,14 @@ closest thing to having been there, and the world itself never closes.
script; she should change anything that doesn't match how the day actually felt to her.
- Confirm how Broke Boi and bigB actually go by on IBM Community today before posting, so any
mentions or tags resolve correctly.
-- Once posted, add it to the catalog in [ibm-community.md](#sec-247) as the group's next
+- Once posted, add it to the catalog in [ibm-community.md](#sec-248) as the group's next
blog entry, following the same fields (author, published date, activity, URL, summary) as the
existing three entries, and cross-link it from the live-reaction catalog entry if that post was
published too.
---
-<a id="sec-245"></a>
+<a id="sec-246"></a>
> **Source:** `docs/ibm-community-recap-nichxbt.md` · [↑ table of contents](#table-of-contents)
@@ -55569,7 +57510,7 @@ closest thing to having been there, and the world itself never closes.
_By nich (nich8), posted as a blog entry in the [Three.ws User Group on IBM
Community](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016),
the team's own side of the meetup recap, alongside Jessica's [live
-reaction](#sec-243) and [recap](#sec-244)
+reaction](#sec-244) and [recap](#sec-245)
on the same group. Two different people, two honest accounts of the same day; this one is mine,
written the way I wrote the [Forge walkthrough](https://community.ibm.com/community/user/discussion/type-a-sentence-get-a-3d-model-a-hands-on-walkthrough-of-the-threews-forge-user-perspective)
and the [10 features post](https://community.ibm.com/community/user/blogs/nich8/2026/07/16/threews-the-free-ai-3d-model-generators-10-best),
@@ -55708,13 +57649,13 @@ than implying a date that does not exist yet.]
[ibm-user-group-first-in-world-meetup-recap.html](../blog/ibm-user-group-first-in-world-meetup-recap.html)
is actually deployed, its link in this draft resolves live; until then it is a same-repo link that
works once shipped, not before.
-- Once posted, add it to the catalog in [ibm-community.md](#sec-247) as the group's next
+- Once posted, add it to the catalog in [ibm-community.md](#sec-248) as the group's next
blog entry, following the same fields (author, published date, activity, URL, summary) as the
existing entries, and cross-link it against Jessica's recap entry.
---
-<a id="sec-246"></a>
+<a id="sec-247"></a>
> **Source:** `docs/ibm-community-thread.md` · [↑ table of contents](#table-of-contents)
@@ -55833,13 +57774,13 @@ _Questions, skepticism, and feature requests all welcome below. The skeptical on
---
-<a id="sec-247"></a>
+<a id="sec-248"></a>
> **Source:** `docs/ibm-community.md` · [↑ table of contents](#table-of-contents)
# IBM Community: Three.ws User Group post catalog
-This is the running catalog of everything published in the [Three.ws User Group](https://community.ibm.com/community/user/groups/community-home?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) on IBM Community: every discussion thread, every blog post, who wrote it, when, what it says, and what activity it got. It exists so the team can track the group's content without re-crawling the site. For what the group is, the framing rules that govern what gets posted there, and the wider IBM relationship, read [IBM watsonx & Granite](#sec-249) first.
+This is the running catalog of everything published in the [Three.ws User Group](https://community.ibm.com/community/user/groups/community-home?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) on IBM Community: every discussion thread, every blog post, who wrote it, when, what it says, and what activity it got. It exists so the team can track the group's content without re-crawling the site. For what the group is, the framing rules that govern what gets posted there, and the wider IBM relationship, read [IBM watsonx & Granite](#sec-250) first.
Dates marked "approx." are derived from the site's relative timestamps ("17 days ago") on the snapshot date; blog dates come from their URLs and are exact.
@@ -55885,7 +57826,7 @@ A feature tour structured as "ten features, in the order I would demo them": (1)
- **Featured image:** the IBM x three.ws lockup ([media/ibm-x-threews-lockup.png](media/ibm-x-threews-lockup.png))
- **URL:** [community.ibm.com/.../join-the-threews-user-groups-first-in-world-meetup](https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/04/join-the-threews-user-groups-first-in-world-meetup)
-Jessica's companion piece to the meetup thread, written in her own voice as a member telling the group not to mistake the event for another webinar link. Carries the event table (Friday, August 7, 8 to 9 AM Pacific, 11 AM Eastern, free, browser only), the three-step join flow (open three.ws/play, bring a custom avatar made at three.ws/create beforehand, talk via spatial voice), and the agenda: live in-world platform tour, community demos, open Q&A ("the skeptical questions are the most useful ones"), and a first look at what is next. Her framing argument: the venue is the demo, so the hour doubles as hands-on evaluation of the technology the group exists to discuss, and since every world is a shareable URL, attending teaches you how to run your own events there. Points readers at the pinned meetup thread for the deep technical background and closes with the full platform link list. The draft lives in [ibm-community-blog-meetup-jessica.md](#sec-242).
+Jessica's companion piece to the meetup thread, written in her own voice as a member telling the group not to mistake the event for another webinar link. Carries the event table (Friday, August 7, 8 to 9 AM Pacific, 11 AM Eastern, free, browser only), the three-step join flow (open three.ws/play, bring a custom avatar made at three.ws/create beforehand, talk via spatial voice), and the agenda: live in-world platform tour, community demos, open Q&A ("the skeptical questions are the most useful ones"), and a first look at what is next. Her framing argument: the venue is the demo, so the hour doubles as hands-on evaluation of the technology the group exists to discuss, and since every world is a shareable URL, attending teaches you how to run your own events there. Points readers at the pinned meetup thread for the deep technical background and closes with the full platform link list. The draft lives in [ibm-community-blog-meetup-jessica.md](#sec-243).
### 4. The First Three.ws User Group Meetup: How It Actually Went
@@ -55936,7 +57877,7 @@ Newest first, matching the digest viewer's order.
- **Activity:** 1 reply (Jessica Swanson, whose profile lists Operational Decision Manager, AI & Data Science at IBM, 2026-08-05: links her blog post "Join the Three.ws User Group's First In-World Meetup")
- **URL:** [community.ibm.com/.../community-meetup-inside-threews-join-us-on-the-three-server-at-threewsplay](https://community.ibm.com/community/user/discussion/community-meetup-inside-threews-join-us-on-the-three-server-at-threewsplay)
-The announcement for the group's first community meetup: Friday, August 7, 2026, 8 to 9 AM Pacific (11 AM Eastern), held inside the platform itself in the $THREE home town at three.ws/play rather than on a video call. Free, browser-only, no download or account. Agenda: a live tour from inside the world, community demos, open Q&A, and a first look at what is next. Explains the three-step join flow (open /play, pick or bring an avatar, walk up and talk via spatial voice chat), then makes the venue case: every world is a URL, every pump.fun coin already has a world derived from its mint, and worlds persist, so any community can run its own meetup the same way. The back half is the long read: a surface-by-surface platform tour (creation, distribution, agent economy, developer platform including the two IBM-specific MCP servers), the technology stack (Three.js/Rapier frontend, GPU worker fleet on Cloud Run, authoritative Colyseus multiplayer at 15 Hz, Solana as home chain), the roadmap led by event infrastructure for /play, and a seven-point growth thesis explicitly framed as a thesis, not a promise. The draft lives in [ibm-community-thread.md](#sec-246).
+The announcement for the group's first community meetup: Friday, August 7, 2026, 8 to 9 AM Pacific (11 AM Eastern), held inside the platform itself in the $THREE home town at three.ws/play rather than on a video call. Free, browser-only, no download or account. Agenda: a live tour from inside the world, community demos, open Q&A, and a first look at what is next. Explains the three-step join flow (open /play, pick or bring an avatar, walk up and talk via spatial voice chat), then makes the venue case: every world is a URL, every pump.fun coin already has a world derived from its mint, and worlds persist, so any community can run its own meetup the same way. The back half is the long read: a surface-by-surface platform tour (creation, distribution, agent economy, developer platform including the two IBM-specific MCP servers), the technology stack (Three.js/Rapier frontend, GPU worker fleet on Cloud Run, authoritative Colyseus multiplayer at 15 Hz, Solana as home chain), the roadmap led by event infrastructure for /play, and a seven-point growth thesis explicitly framed as a thesis, not a promise. The draft lives in [ibm-community-thread.md](#sec-247).
### 2. Community Friday August 7,2026 - Inside three.ws: Join Us on the $THREE Server at three.ws/play
@@ -56005,11 +57946,11 @@ A first-run walkthrough of the Forge from a user's perspective, no account, wall
## Keeping this catalog current
-When a new post lands in the group, add it here in digest order with the same fields (author, date, activity, URL, faithful summary) and refresh the snapshot table's date and counts. The sources of truth are the [digest viewer](https://community.ibm.com/community/user/groups/community-home/digestviewer?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) for threads and the [recent blogs page](https://community.ibm.com/community/user/groups/community-home/recent-community-blogs?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) for blogs. The posting cadence and topic rules for the group itself live in the [SEO keyword plan](ops/seo-keyword-plan.md) and in [ibm.md](#sec-249).
+When a new post lands in the group, add it here in digest order with the same fields (author, date, activity, URL, faithful summary) and refresh the snapshot table's date and counts. The sources of truth are the [digest viewer](https://community.ibm.com/community/user/groups/community-home/digestviewer?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) for threads and the [recent blogs page](https://community.ibm.com/community/user/groups/community-home/recent-community-blogs?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016) for blogs. The posting cadence and topic rules for the group itself live in the [SEO keyword plan](ops/seo-keyword-plan.md) and in [ibm.md](#sec-250).
---
-<a id="sec-248"></a>
+<a id="sec-249"></a>
> **Source:** `docs/ibm-x402-mcp.md` · [↑ table of contents](#table-of-contents)
@@ -56031,9 +57972,9 @@ bill itself, in USDC, over [x402](https://x402.org).
This is the developer guide for the `@three-ws/ibm-x402-mcp` tool suite. For the
broader IBM integration (the platform showcase, Guardian Trust Layer, the
-credentials-based `@three-ws/ibm-watsonx-mcp` connector) see **[docs/ibm.md](#sec-249)**.
+credentials-based `@three-ws/ibm-watsonx-mcp` connector) see **[docs/ibm.md](#sec-250)**.
For the x402 protocol primitives used elsewhere on the platform see
-**[docs/x402.md](#sec-519)**.
+**[docs/x402.md](#sec-544)**.
---
@@ -56351,7 +58292,7 @@ HTTP `status`), `internal_error` (unexpected).
## Discovery (x402 Bazaar)
Each tool declares an x402 discovery extension, so the suite is browsable in the
-[x402 Bazaar](#sec-275) alongside its schema, example input, and
+[x402 Bazaar](#sec-276) alongside its schema, example input, and
example output. Agents can find Granite tools by capability and price without
knowing the server up front.
@@ -56372,16 +58313,16 @@ Catalog/listing copy is maintained in
## See also
-- [docs/ibm.md](#sec-249) — the full IBM Granite / watsonx integration and showcase
-- [docs/x402.md](#sec-519) — the x402 payment protocol on three.ws
-- [docs/mcp.md](#sec-276) — wiring MCP servers into a client
-- [docs/mcp-x402-bazaar.md](#sec-275) — x402 service discovery
+- [docs/ibm.md](#sec-250) — the full IBM Granite / watsonx integration and showcase
+- [docs/x402.md](#sec-544) — the x402 payment protocol on three.ws
+- [docs/mcp.md](#sec-277) — wiring MCP servers into a client
+- [docs/mcp-x402-bazaar.md](#sec-276) — x402 service discovery
- [packages/ibm-x402-mcp](../packages/ibm-x402-mcp) — the npm package source
- npm: [`@three-ws/ibm-x402-mcp`](https://www.npmjs.com/package/@three-ws/ibm-x402-mcp)
---
-<a id="sec-249"></a>
+<a id="sec-250"></a>
> **Source:** `docs/ibm.md` · [↑ table of contents](#table-of-contents)
@@ -56389,7 +58330,7 @@ Catalog/listing copy is maintained in
three.ws agents can think on **IBM Granite** foundation models, served through **IBM watsonx.ai**. This page documents the whole integration for developers and operators: which Granite models run where, how the watsonx client is wired, how to configure it, and the Granite-powered API surfaces (from a Granite avatar brain to on-chain, Guardian-governed forecasts). The live IBM pages on the product are [three.ws/ibm/hello](https://three.ws/ibm/hello) (the partnership page) and [three.ws/ibm/x402-demo](https://three.ws/ibm/x402-demo) (the x402 live demo).
-For the broader platform model see [How it works](#sec-239); for the agent brain abstraction see [Agent system](#sec-064); for the standalone connector see [the MCP server](#mcp-server-three-wsibm-watsonx-mcp) below.
+For the broader platform model see [How it works](#sec-240); for the agent brain abstraction see [Agent system](#sec-064); for the standalone connector see [the MCP server](#mcp-server-three-wsibm-watsonx-mcp) below.
---
@@ -56434,7 +58375,7 @@ three.ws runs a public user group on IBM Community for developers and engineers
| Library | [Files and assets](https://community.ibm.com/community/user/groups/community-home/librarydocuments?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016&LibraryFolderKey=&DefaultView=) |
| Members | [Member list](https://community.ibm.com/community/user/groups/community-home/community-members?communitykey=e71510cc-d953-408f-9a1c-019f5c0a7016&Execute=1) |
-Every thread and blog published in the group is cataloged, with authors, dates, activity, and a faithful per-post summary, in the [IBM Community post catalog](#sec-247). Update the catalog whenever a new post lands.
+Every thread and blog published in the group is cataloged, with authors, dates, activity, and a faithful per-post summary, in the [IBM Community post catalog](#sec-248). Update the catalog whenever a new post lands.
What belongs there, and what does not, is set by the [SEO keyword plan](ops/seo-keyword-plan.md): one post per week maximum, tutorials that stand on their own for an IBM developer who never clicks through, and no crypto-cluster content (that goes on [three.ws/blog](https://three.ws/blog) instead). The user group is also linked from the site's [Community page](https://three.ws/community) and the global footer.
@@ -56598,7 +58539,25 @@ curl -s https://three.ws/api/watsonx/embed \
-d '{"texts":["a witty Solana trading assistant","a calm meditation guide"]}'
```
-It returns one vector per input (the response reports the model and its native `dimensions`), plus a `cachedHits` count — a warm process-local LRU and CDN cache-control headers keep repeat embeddings free, and per-IP + global rate limits cap watsonx spend.
+It returns one vector per input (the response reports the model and its native `dimensions`), plus a `cachedHits` count: a warm process-local LRU keeps repeat embeddings free, and per-IP + global rate limits cap watsonx spend. The response itself is sent `cache-control: no-store`, because a POST body varies per request and must never be shared-cached.
+
+**Always read `model` from the response.** The endpoint leads with Granite on watsonx.ai and falls through to the platform's free-first embedding chain (NVIDIA NIM, then Vertex, then OpenAI) when watsonx cannot serve a full batch, so a 200 does not by itself mean Granite answered. Every vector in one response comes from one provider, so `dimensions` is uniform. Only when no provider at all is configured does it answer `503 embed_unconfigured`, which is what lets a caller show an honest "not configured" state instead of inventing vectors.
+
+## watsonx Constellation
+
+**Page:** [`/constellation`](https://three.ws/constellation)
+
+The Constellation applies the same Granite embedding space to live market data instead of agents. It pulls trending Solana tokens from `GET /api/pump/trending`, embeds each token's name and ticker through `POST /api/watsonx/embed`, projects the vectors to three axes with classical MDS in the browser, and renders each token as a star, so tokens that mean similar things sit near each other. Picking a star opens its detail panel and streams an IBM Granite analysis of that token from `POST /api/brain/chat` with `provider: ibm-granite`.
+
+Three behaviours matter if you are reading the page or building on it:
+
+- **It names what actually served.** Both backing endpoints have failover chains, so the status line reports the embedder that really placed the stars and the analysis panel reports the model that really wrote the text, saying so plainly when watsonx Granite could not serve the request. It never credits Granite for another model's output.
+- **It never fabricates a layout.** Tokens first render in a deterministic by-rank layout and animate into their semantic positions once the vectors land. If embeddings are unavailable the by-rank layout stays and the status line says the semantic layout is off.
+- **The analysis needs a signed-in account.** `/api/brain/chat` restricts anonymous callers to its free-tier providers, so the panel links to sign-in rather than failing. The galaxy itself, its live market data and the semantic layout are open to everyone.
+
+The page is keyboard operable: the canvas takes focus, arrow keys walk the stars in trending order, Enter opens the focused star, and Escape closes the panel and returns focus to the galaxy.
+
+A batch is 1 to 96 texts, each truncated to 512 characters. When watsonx is not configured on a deployment (or is failing), the endpoint falls through to the platform's free-first embedding chain (NVIDIA NIM, then Vertex `text-embedding-005`, then OpenAI `text-embedding-3-small`) and reports whichever `model` actually served, so `dimensions` is uniform within a response but can differ between them. A provider that covers only part of a batch counts as a failure and the next provider takes over: the response never carries a null where a vector belongs. With no provider configured at all you get a `503 embed_unconfigured` naming the env vars to set, never invented vectors.
---
@@ -56664,18 +58623,19 @@ Source: [`packages/ibm-watsonx-mcp`](../packages/ibm-watsonx-mcp). Five tools:
WATSONX_API_KEY=… WATSONX_PROJECT_ID=… npx @three-ws/ibm-watsonx-mcp
```
-It reads the same `WATSONX_*` environment variables documented above. See the [MCP guide](#sec-276) for wiring MCP servers into a client.
+It reads the same `WATSONX_*` environment variables documented above. See the [MCP guide](#sec-277) for wiring MCP servers into a client.
---
## Live pages and API surfaces
-The two live IBM pages on the product:
+The live IBM pages on the product:
| Route | What it is |
| -------------------------------------------------------- | ---------------------------------------------------------------- |
| [`/ibm/hello`](https://three.ws/ibm/hello) | The IBM and three.ws partnership page |
| [`/ibm/x402-demo`](https://three.ws/ibm/x402-demo) | Live x402 micropayment demo built with IBM |
+| [`/constellation`](https://three.ws/constellation) | watsonx Constellation: trending Solana tokens in embedding space |
The Granite demo pages that used to live under `/ibm/*` (galaxy, oracle, twin, trust-layer, identity, proof, vision) were retired from navigation and removed. Their API endpoints remain live and callable:
@@ -56710,16 +58670,16 @@ Unit tests for the same paths live in [`tests/`](../tests) (`granite-oracle`, `a
## See also
-- [How it works](#sec-239) — the platform mental model
+- [How it works](#sec-240) — the platform mental model
- [Agent system](#sec-064) — the brain abstraction Granite plugs into
-- [IBM Granite x402 MCP](#sec-248) — pay-per-call Granite for agents (USDC, no IBM account)
-- [MCP](#sec-276) — wiring MCP servers into a client
+- [IBM Granite x402 MCP](#sec-249) — pay-per-call Granite for agents (USDC, no IBM account)
+- [MCP](#sec-277) — wiring MCP servers into a client
- [REST API](#sec-096) — the full endpoint reference
-- [Configuration](#sec-150) — all environment variables
+- [Configuration](#sec-153) — all environment variables
---
-<a id="sec-250"></a>
+<a id="sec-251"></a>
> **Source:** `docs/image-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -56814,14 +58774,14 @@ console.log(job.glb_url);
## Related
-- [Forge](#sec-224) is the full text-and-image-to-3D surface with every mode and engine.
-- [Avatar reconstruction](#sec-113) and [avatar creation](#sec-108) cover the face-to-avatar pipeline behind [/create/selfie](https://three.ws/create/selfie).
+- [Forge](#sec-225) is the full text-and-image-to-3D surface with every mode and engine.
+- [Avatar reconstruction](#sec-114) and [avatar creation](#sec-109) cover the face-to-avatar pipeline behind [/create/selfie](https://three.ws/create/selfie).
- The pipeline internals: [3D asset pipeline](#sec-002), [3D pipeline](#sec-003), [3D API](#sec-001).
- Pages: [/create](https://three.ws/create), [/scene](https://three.ws/scene) (Scene Studio), [/gallery](https://three.ws/gallery).
---
-<a id="sec-251"></a>
+<a id="sec-252"></a>
> **Source:** `docs/in-game-economy.md` · [↑ table of contents](#table-of-contents)
@@ -56950,11 +58910,11 @@ primitives.
This is **not** the same rail as the USDC cosmetics shop for the standalone
character creator, which sells a different catalog through
-[x402](#sec-519) and is surfaced publicly at [/fits](https://three.ws/fits).
+[x402](#sec-544) and is surfaced publicly at [/fits](https://three.ws/fits).
Two catalogs, two currencies, two rails. Do not confuse them.
It is also not the only way to own a wardrobe item. A third tier exists that the
-boutique deliberately cannot see: **[event souvenirs](#sec-213)** are
+boutique deliberately cannot see: **[event souvenirs](#sec-216)** are
granted to everyone present in the world during a live event and are never sold,
before, during, or after. They carry no price, so the boutique's listing filter
(`tier === 'premium'` **and** `price > 0`) excludes them by construction, and the
@@ -57080,16 +59040,16 @@ every number in this system.
## Next
-- **[Earn and spend in /play](#sec-429)** walks the
+- **[Earn and spend in /play](#sec-435)** walks the
whole loop end to end, from your first gathered log to a cosmetic unlock.
- **[three.ws/play/economy](https://three.ws/play/economy)** is the live reference
with the current catalogs and odds.
-- **[Coin communities](#sec-143)** covers the worlds themselves: how a coin
+- **[Coin communities](#sec-145)** covers the worlds themselves: how a coin
becomes a walkable 3D space.
---
-<a id="sec-252"></a>
+<a id="sec-253"></a>
> **Source:** `docs/inference-node-operator.md` · [↑ table of contents](#table-of-contents)
@@ -57363,7 +59323,7 @@ signature, and the artifact hash all check out.
---
-<a id="sec-253"></a>
+<a id="sec-254"></a>
> **Source:** `docs/integrations.md` · [↑ table of contents](#table-of-contents)
@@ -57383,7 +59343,7 @@ The platform's agents are only as useful as the places they can appear. Integrat
is the distribution layer: it turns an agent, a saved widget, or a live token feed
into something a marketer can paste into a CMS, a developer can wire into a framework,
or an AI assistant can call as a tool. It is the front page of embedding; the deep
-per-method references live in [Embedding](#sec-183) and [Widgets](#sec-505),
+per-method references live in [Embedding](#sec-186) and [Widgets](#sec-511),
and this doc is the map that points you to the right one.
## How it works
@@ -57409,7 +59369,7 @@ The catalog covers six integration types:
driven by a `data-widget` id and the `pumpfun-feed` type.
- **MCP Integration**: the `@three-ws/avatar-agent` server (from the
`packages/avatar-agent-mcp` workspace), so Claude, Cursor, or any MCP-compatible
- assistant can render, speak, gesture, and emote your agents. See [MCP](#sec-276).
+ assistant can render, speak, gesture, and emote your agents. See [MCP](#sec-277).
## Walkthrough
@@ -57527,15 +59487,15 @@ for the full table.
## Related
-- [Embedding Guide](#sec-183): the full per-method reference (web component, iframe, oEmbed)
-- [Widget Types](#sec-505): every widget type and how to configure one
-- [Embody](#sec-184): giving an agent a body in more contexts
-- [MCP](#sec-276): the avatar MCP server for AI assistants
+- [Embedding Guide](#sec-186): the full per-method reference (web component, iframe, oEmbed)
+- [Widget Types](#sec-511): every widget type and how to configure one
+- [Embody](#sec-187): giving an agent a body in more contexts
+- [MCP](#sec-277): the avatar MCP server for AI assistants
- Pages: [/integrations](https://three.ws/integrations), [/widgets](https://three.ws/widgets)
---
-<a id="sec-254"></a>
+<a id="sec-255"></a>
> **Source:** `docs/introduction.md` · [↑ table of contents](#table-of-contents)
@@ -57746,7 +59706,7 @@ To add an AI brain:
The `key-proxy` attribute points to a serverless function that injects your API key — the key never touches the client. The `voice` attribute enables microphone input and TTS output.
-For a full step-by-step walkthrough, see the [Quick Start guide](#sec-356).
+For a full step-by-step walkthrough, see the [Quick Start guide](#sec-361).
---
@@ -57754,19 +59714,19 @@ For a full step-by-step walkthrough, see the [Quick Start guide](#sec-356).
Once you have the basics working, the following guides go deeper:
-- **[Quick Start](#sec-356)** — step-by-step from zero to a talking agent
-- **[Embedding Guide](#sec-183)** — all attributes, modes, events, and the JS API
-- **[Widget Types](#sec-505)**, the five general-purpose widgets in depth (the other five live in [Widget Studio](https://three.ws/studio))
+- **[Quick Start](#sec-361)** — step-by-step from zero to a talking agent
+- **[Embedding Guide](#sec-186)** — all attributes, modes, events, and the JS API
+- **[Widget Types](#sec-511)**, the five general-purpose widgets in depth (the other five live in [Widget Studio](https://three.ws/studio))
- **[Agent System Overview](#sec-064)** — runtime, skill registry, memory, emotion system
- **[Manifest Reference](#sec-055)** — full JSON schema with examples
-- **[REST API](#sec-096)** and **[JavaScript API](#sec-257)** — backend and in-browser surfaces
+- **[REST API](#sec-096)** and **[JavaScript API](#sec-258)** — backend and in-browser surfaces
- **[Agents vs. avatars](#sec-073)** — the difference, and when to care
If you want to look at what's already in the hosted platform — browsing agents, using Widget Studio, or registering on-chain — visit [https://three.ws](https://three.ws).
---
-<a id="sec-255"></a>
+<a id="sec-256"></a>
> **Source:** `docs/irl.md` · [↑ table of contents](#table-of-contents)
@@ -57889,7 +59849,7 @@ The rollup is served at `GET /api/irl/analytics` (admin-gated via `x-ops-secret`
---
-<a id="sec-256"></a>
+<a id="sec-257"></a>
> **Source:** `docs/irl/THREAT-MODEL.md` · [↑ table of contents](#table-of-contents)
@@ -58043,15 +60003,15 @@ in a way that drops legitimate discovery, update this file in the same change.
---
-<a id="sec-257"></a>
+<a id="sec-258"></a>
> **Source:** `docs/js-api.md` · [↑ table of contents](#table-of-contents)
# JavaScript API Reference
-This page documents the internal JavaScript classes behind the three.ws viewer: the `App` controller, the Three.js `Viewer`, the glTF `Validator`, and the small components that render around them. It is aimed at developers reading or extending the source (`src/`), and at anyone driving the viewer from the browser console via `window.VIEWER`. If you just want a 3D agent on your page, use the [`<agent-3d>` element](#sec-502) instead.
+This page documents the internal JavaScript classes behind the three.ws viewer: the `App` controller, the Three.js `Viewer`, the glTF `Validator`, and the small components that render around them. It is aimed at developers reading or extending the source (`src/`), and at anyone driving the viewer from the browser console via `window.VIEWER`. If you just want a 3D agent on your page, use the [`<agent-3d>` element](#sec-508) instead.
-> For the HTTP/REST surface, see [api-reference.md](#sec-096). For the high-level npm SDK, see [sdk.md](#sec-369). For the `<agent-3d>` element attributes, see [web-component.md](#sec-502).
+> For the HTTP/REST surface, see [api-reference.md](#sec-096). For the high-level npm SDK, see [sdk.md](#sec-374). For the `<agent-3d>` element attributes, see [web-component.md](#sec-508).
---
@@ -58677,7 +60637,7 @@ window.VIEWER.app.viewer.updateDisplay();
---
-<a id="sec-258"></a>
+<a id="sec-259"></a>
> **Source:** `docs/kol-tracker.md` · [↑ table of contents](#table-of-contents)
@@ -58813,8 +60773,8 @@ Writes the curated tracked-wallet list that the tracker merges in. Accepts `{ ra
The tracker answers "who is making money"; the reputation surfaces answer "should this wallet's record earn trust". They meet at the wallet address:
- **`GET /api/intel/wallet/<WALLET_ADDRESS>`** returns one wallet's realized track record from the Smart-Money graph: a 0 to 100 realized score, win rate, average ATH multiple, winners and losers, labels (`smart_money`, `sybil`, `fresh`, and others), and its funder cluster. `computed: false` means no track record exists yet for that address; that is an honest zero, not an error. A string that is not a base58 Solana address is a different case and returns `400 bad_request`, so a typo never reads as a wallet with no history. Any wallet you see on the tracker can be fed straight into it. The same card is served by `GET /api/intel/smart-money?wallet=<WALLET_ADDRESS>`, which applies the identical validation.
-- **[Smart Money Radar](#sec-383)** is the sibling leaderboard built from graduation outcomes rather than a KOL universe: reputation earned per wallet from which coins actually graduated. The tracker's footer links to it, and the two boards frequently disagree in instructive ways.
-- **[Trust primitives](#sec-411)** wrap the same question for autonomous agents: a paid endpoint that scores any counterparty wallet from real on-chain evidence before an agent transacts with it.
+- **[Smart Money Radar](#sec-389)** is the sibling leaderboard built from graduation outcomes rather than a KOL universe: reputation earned per wallet from which coins actually graduated. The tracker's footer links to it, and the two boards frequently disagree in instructive ways.
+- **[Trust primitives](#sec-417)** wrap the same question for autonomous agents: a paid endpoint that scores any counterparty wallet from real on-chain evidence before an agent transacts with it.
```bash
# Take a wallet from the tracker and pull its reputation record
@@ -58832,13 +60792,13 @@ curl 'https://three.ws/api/intel/wallet/<WALLET_ADDRESS>?network=mainnet'
## Related
-- [Smart Money Radar](#sec-383): reputation earned from graduation outcomes, wallet by wallet
-- [Trust primitives](#sec-411): the paid cross-chain reputation read for autonomous agents
+- [Smart Money Radar](#sec-389): reputation earned from graduation outcomes, wallet by wallet
+- [Trust primitives](#sec-417): the paid cross-chain reputation read for autonomous agents
- Pages: [/tracker](https://three.ws/tracker) · [/smart-money](https://three.ws/smart-money) · [/leaderboard](https://three.ws/leaderboard)
---
-<a id="sec-259"></a>
+<a id="sec-260"></a>
> **Source:** `docs/labor-market.md` · [↑ table of contents](#table-of-contents)
@@ -58973,7 +60933,7 @@ economy move:
---
-<a id="sec-260"></a>
+<a id="sec-261"></a>
> **Source:** `docs/launch-usecases.md` · [↑ table of contents](#table-of-contents)
@@ -59103,13 +61063,13 @@ GET /api/pump/launch-studio?action=preview&id=github-fresh-breakouts&limit=6
## Related
- [Launch use-case engine](../api/_lib/launch/README.md) — internals + how to add a recipe.
-- [Coin Launches](#sec-142) — the underlying launch mechanism.
+- [Coin Launches](#sec-144) — the underlying launch mechanism.
- [Launch a Coin](https://three.ws/launch) — the wizard each recipe hands off to.
- Fee sharing & GitHub reward routing — [`public/studio/fees-panel.js`](../public/studio/fees-panel.js).
---
-<a id="sec-261"></a>
+<a id="sec-262"></a>
> **Source:** `docs/layers.md` · [↑ table of contents](#table-of-contents)
@@ -59117,7 +61077,7 @@ GET /api/pump/launch-studio?action=preview&id=github-fresh-breakouts&limit=6
three.ws is split into four horizontal layers. Each layer can be used on its own. Each layer is independently replaceable as long as its contract with the rest of the system holds. This document describes what each layer owns, what it exports, and where to extend it.
-For the overall request flow, see [How three.ws works](#sec-239). For internal module names and paths, see [Architecture overview](#sec-100).
+For the overall request flow, see [How three.ws works](#sec-240). For internal module names and paths, see [Architecture overview](#sec-100).
---
@@ -59207,10 +61167,10 @@ Modules:
- **`agent-identity.js`** — the passport + diary. Stable agent ID, owner address, signed action history. Backed by `localStorage` (cache) and `/api/agents/<id>` (canonical). Listens on the protocol bus and POSTs `speak` / `skill-done` / `validate` / `sign` events to `/api/agent-actions`.
- **`memory/`** — `local`, `ipfs`, `encrypted-ipfs`, or `none`. Declared on the manifest.
- **`erc8004/`** — on-chain registries. `IdentityRegistry` (mints agent token with `tokenURI`), `ReputationRegistry` (signed feedback), `ValidationRegistry` (validation report hashes). Per-chain addresses in `erc8004/abi.js`.
-- **`erc8004/solana-deploy.js`**: Solana counterpart. Metaplex Core asset mint; SPL Memo attestations and reputation live server-side (see [Agent Reputation on Solana](#sec-387)).
+- **`erc8004/solana-deploy.js`**: Solana counterpart. Metaplex Core asset mint; SPL Memo attestations and reputation live server-side (see [Agent Reputation on Solana](#sec-393)).
- **`auth/` + `wallet/`** — SIWE / SIWS for backend mutations; Privy for email/social → embedded wallet onboarding; session cookies after wallet proof.
-Per-chain registry addresses, ABIs, and helpers ship as `@three-ws/sdk`. ENS attestations are also handled here — see [register-onchain.md](#sec-456).
+Per-chain registry addresses, ABIs, and helpers ship as `@three-ws/sdk`. ENS attestations are also handled here — see [register-onchain.md](#sec-462).
---
@@ -59223,7 +61183,7 @@ Per-chain registry addresses, ABIs, and helpers ship as `@three-ws/sdk`. ENS att
Modules:
- **`element.js`**: `<agent-3d>` custom element. Lazy-boots via `IntersectionObserver` (unless `eager`). Enforces origin allowlist. Exposes attributes for `body`, `brain`, `agent-id`, `manifest`, `mode` (`inline` / `floating` / `section` / `fullscreen`), `voice`, and more. Public methods: `say()`, `ask()`, `installSkill()`, `expressEmotion()`, `play()`, `lookAt()`, `pause()`, `destroy()`.
-- **`stage-element.js`**: `<agent-stage>` for hosting multiple agents in one shared scene. See [multi-agent.md](#sec-289).
+- **`stage-element.js`**: `<agent-stage>` for hosting multiple agents in one shared scene. See [multi-agent.md](#sec-290).
- **`widget-types.js`**: the ten widget variants: Turntable, Animation Gallery, Talking Agent, ERC-8004 Passport, Hotspot Tour, Pump.fun Live Feed, Smart Money Feed, Live Trades Canvas, Bonding Curve, Walking Avatar.
- **`lib.js`** — the CDN entry. Imports the element, registers it, re-exports the public surface (`defineElement`, `Agent3DElement`, `AgentStageElement`, helpers).
- **`embed-action-bridge.js`** — the `postMessage` protocol. Iframe widgets and the web component speak the same dialect, so host pages can drive either with the same code.
@@ -59258,7 +61218,7 @@ The same source tree produces three independent builds:
- **Library**: `npm run build:lib`. `src/lib.js` → `dist-lib/agent-3d.js` (ES module). Add the UMD build (`dist-lib/agent-3d.umd.cjs`) with `npm run build:lib:full`, which is what the production deploy chain runs. Three.js and ethers stay bundled, so the file is intentionally self-contained: a single `<script type="module">` is the only thing a third party needs.
- **Artifact** — `vite.config.artifact.js`. A zero-dependency bundle for Claude artifact embeds. Inlined everything, no external script tags, no dynamic imports.
-Versioned CDN bundles are published at `/agent-3d/<version>/agent-3d.js`. Use `latest` for auto-updates or pin to a version for stability. See [changelog.md](#sec-133) for release history.
+Versioned CDN bundles are published at `/agent-3d/<version>/agent-3d.js`. Use `latest` for auto-updates or pin to a version for stability. See [changelog.md](#sec-135) for release history.
---
@@ -59266,12 +61226,12 @@ Versioned CDN bundles are published at `/agent-3d/<version>/agent-3d.js`. Use `l
- **[Architecture overview](#sec-100)** — module-by-module deep dive
- **[Agent system](#sec-064)** — runtime, skills, memory in detail
-- **[Embedding](#sec-183)** — the public face of the embed layer
-- **[SDK reference](#sec-369)** — `@three-ws/sdk` and friends
+- **[Embedding](#sec-186)** — the public face of the embed layer
+- **[SDK reference](#sec-374)** — `@three-ws/sdk` and friends
---
-<a id="sec-262"></a>
+<a id="sec-263"></a>
> **Source:** `docs/likeness-eval.md` · [↑ table of contents](#table-of-contents)
@@ -59469,7 +61429,7 @@ at mean cosine 0.776 while different avatars sat at 0.443, a separation of 0.33
rather than 0.035. The production reconstruction lane transfers a face texture
onto a fixed template head, and by its own measurement only about 10% of the
head's texels come from the photograph
-([avatar fidelity program](#sec-110)). A near-noise-floor
+([avatar fidelity program](#sec-111)). A near-noise-floor
identity reading is the number that shape of pipeline should produce, and it is
consistent with the geometry-side ISE result.
@@ -59511,8 +61471,8 @@ and reason only.
## Related
-- [Selfie to avatar](#sec-372): the capture flow being measured
-- [Avatar fidelity program](#sec-110): the tracks this
+- [Selfie to avatar](#sec-377): the capture flow being measured
+- [Avatar fidelity program](#sec-111): the tracks this
metric scores
- [Realism quality bench](../data/quality-bench/README.md): the sibling harness
for photorealism
@@ -59520,7 +61480,7 @@ and reason only.
---
-<a id="sec-263"></a>
+<a id="sec-264"></a>
> **Source:** `docs/lipsync.md` · [↑ table of contents](#table-of-contents)
@@ -59615,15 +61575,15 @@ tick();
## Related
-- [Voice Lab](#sec-500): clone a voice and synthesize it, the audio these demos animate.
-- [Voice and lipsync tutorial](#sec-475): the full walkthrough, including wiring visemes to an agent body.
-- [Talking Avatar Video](#sec-397): the server-rendered alternative for exporting a talking-head clip.
+- [Voice Lab](#sec-506): clone a voice and synthesize it, the audio these demos animate.
+- [Voice and lipsync tutorial](#sec-481): the full walkthrough, including wiring visemes to an agent body.
+- [Talking Avatar Video](#sec-403): the server-rendered alternative for exporting a talking-head clip.
- [Animations](#sec-093): the runtime clip registry that plays alongside lipsync.
- Pages: [/lipsync](https://three.ws/lipsync), [/lipsync/mic](https://three.ws/lipsync/mic).
---
-<a id="sec-264"></a>
+<a id="sec-265"></a>
> **Source:** `docs/listings.md` · [↑ table of contents](#table-of-contents)
@@ -59641,7 +61601,7 @@ Cloud marketplaces are the procurement flow enterprises use to acquire software
| Cloud | Status | Links |
|---|---|---|
-| **AWS** Marketplace | Live | three.ws is an AWS Partner. Subscribe via AWS Marketplace to consolidate billing on your AWS account; subscriptions auto-issue an x402 API key via the marketplace entitlement service. See [aws-marketplace.md](#sec-122). |
+| **AWS** Marketplace | Integration ready, listing not yet created | three.ws is an AWS Partner and the SaaS integration is built, deployed, and conformant with the Concurrent Agreements requirements AWS made mandatory for new products on 2026-06-01. The product itself has not been created in the AWS Marketplace Management Portal yet, so there is nothing to subscribe to on the AWS side: use [x402](/docs/x402) directly in the meantime, which needs no AWS account. Once the listing is public, subscribing consolidates procurement on your AWS account and auto-issues an x402 API key. See [aws-marketplace.md](#sec-123) and the [listing kit](#sec-122). |
| **Alibaba Cloud** International Marketplace | Live | [Product listing](https://marketplace.alibabacloud.com/products/56724001/sgcmfw00036800.html) · [Storefront](https://marketplace.alibabacloud.com/store/3247293.html) · [Announcement](/blog/three-ws-on-alibaba-cloud-marketplace.html) · [Marketplace blog feature](https://marketplace.alibabacloud.com/doc/blog/detail/mplace-sgcmfw00036800.html) |
| **Google Cloud** Marketplace | Open to partnership | three.ws already runs its production stack on Google Cloud Run (`three-ws-api`, us-central1) — a natural fit for Vertex AI and GCP's global CDN. Reach out for co-listing, credits, and joint GTM. |
| **Microsoft Azure** Marketplace | On roadmap | Targeted alongside the AWS/Alibaba rollout. |
@@ -59656,6 +61616,7 @@ Infrastructure programs that back three.ws with credits, tooling, and founder ne
|---|---|---|
| **Quicknode** Startup Program | Accepted (2026-07) | three.ws is accepted into the Quicknode Startup Program and approved for free infrastructure credits. Quicknode's globally distributed RPC endpoints (Solana first, plus the EVM chains x402 settles on) add capacity and redundancy behind agent wallets, settlement verification, and live market data. Announcement: [three.ws Joins the Quicknode Startup Program](/blog/three-ws-quicknode-startup-program). |
| **Google Cloud** for Web3 Startups | Member | Production runs on Google Cloud Run; the program backs compute and Vertex AI usage. Announcement: [three.ws Joins Google Cloud for Web3 Startups](/blog/three-ws-google-cloud-partnership). |
+| **NVIDIA Inception** | Member (2026-07) | NVIDIA's program for startups building on accelerated computing. Every generation lane runs on NVIDIA: a self-hosted Cloud Run GPU fleet (L4 plus one RTX PRO 6000 Blackwell) behind text-to-3D, rigging, and motion, and a free hosted lane behind chat, vision, embeddings, safety, and speech. Surface: [/nvidia](/nvidia). Docs: [NVIDIA Inception](#sec-296), [NVIDIA models](#sec-297). Membership is a startup program, not a partnership, an investment, or an endorsement. |
---
@@ -59667,7 +61628,19 @@ Ecosystem directories are the discovery surfaces that L1/L2 communities, chain f
|---|---|---|
| **BNB Chain · Dappbay** | Live | [dappbay.bnbchain.org/detail/three](https://dappbay.bnbchain.org/detail/three) — categories: *AI Agent Launchpad · AI Data · AI Infra*. Announcement: [three.ws Listed on BNB Chain's Dappbay Directory](/blog/three-ws-on-bnb-chain-dappbay.html). |
-Dappbay is BNB Chain's official dApp directory. The listing is about distribution and discovery into BNB Chain's AI dApp audience — three.ws still settles agent payments on Solana, Base, and Polygon via the chain-agnostic [x402 protocol](#sec-519).
+Dappbay is BNB Chain's official dApp directory. The listing is about distribution and discovery into BNB Chain's AI dApp audience — three.ws still settles agent payments on Solana, Base, and Polygon via the chain-agnostic [x402 protocol](#sec-544).
+
+---
+
+## AI Platform Directories
+
+The discovery surfaces owned by the AI platforms themselves, where an MCP server can be listed as an installable product rather than a documentation page.
+
+| Directory | Status | Listing details |
+|---|---|---|
+| **OpenAI** Plugin Directory (ChatGPT + Codex) | Open to submission | The universal directory shared by ChatGPT and Codex since 2026-07-09, superseding the former App directory. three.ws already meets the gating requirement: a public OAuth 2.1 MCP server at `https://three.ws/api/mcp` ([mcp.md](#sec-277)). Full submission kit, prerequisites, and rejection criteria: [openai-listing-channels.md](#sec-305). |
+| **OpenAI** Showcase Gallery | Open to submission | Editorial feature on openai.com for apps, demos, and open-source projects built with OpenAI models, APIs, or Codex. Open web form, no repo gate. See [openai-listing-channels.md](#sec-305). |
+| **OpenAI** Cookbook | Submitted, not merged | [PR #2874](https://github.com/openai/openai-cookbook/pull/2874) (a self-correcting 3D collectible pipeline using text-to-3D, function calling, and vision) has been open since 2026-07-21. Root-cause analysis and the revival steps are in [openai-listing-channels.md](#sec-305). |
---
@@ -59715,7 +61688,7 @@ Subscribe via RSS to track new listings, integrations, and protocol updates.
---
-<a id="sec-265"></a>
+<a id="sec-266"></a>
> **Source:** `docs/live-docs.md` · [↑ table of contents](#table-of-contents)
@@ -59735,7 +61708,7 @@ Press **Edit**, change something, and press <kbd>⌘</kbd>/<kbd>Ctrl</kbd> +
## Try it: a live avatar
-This is the same embed snippet from the [`<agent-3d>` reference](#sec-502).
+This is the same embed snippet from the [`<agent-3d>` reference](#sec-508).
Press **Run preview** and it renders. Then press **Edit**, swap `michelle.glb`
for `xbot.glb`, and run it again.
@@ -59897,14 +61870,14 @@ cached module.
## Related
-- [`<agent-3d>` Web Component API Reference](#sec-502) — the element most previews render
+- [`<agent-3d>` Web Component API Reference](#sec-508) — the element most previews render
- [API reference](#sec-096) — the endpoints most `curl` samples call
-- [Embed and share](#sec-183) — putting an avatar on your own site
-- [MCP tool safety](#sec-272) — the same read/write/irreversible split, applied to agent tools
+- [Embed and share](#sec-186) — putting an avatar on your own site
+- [MCP tool safety](#sec-273) — the same read/write/irreversible split, applied to agent tools
---
-<a id="sec-266"></a>
+<a id="sec-267"></a>
> **Source:** `docs/live-steps.md` · [↑ table of contents](#table-of-contents)
@@ -60087,7 +62060,7 @@ Run `npx vitest run tests/live-steps.test.js` after editing the registry; the su
---
-<a id="sec-267"></a>
+<a id="sec-268"></a>
> **Source:** `docs/make-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -60104,7 +62077,7 @@ This guide walks you through creating a 3D AI agent in the browser — no code,
Go to [three.ws/start](/start). This is the new-agent wizard.
-You'll be asked to sign in if you haven't already. See [Do I need crypto?](#sec-175) if you're not sure which sign-in option to choose.
+You'll be asked to sign in if you haven't already. See [Do I need crypto?](#sec-178) if you're not sure which sign-in option to choose.
---
@@ -60154,7 +62127,7 @@ Once you hit **Publish**, your agent gets a live URL: something like `three.ws/a
The wizard also gives you an **embed snippet**: a few lines of HTML you can paste into any webpage to make the agent appear there. You don't need to know HTML to do this — just copy and paste.
-For more on where and how to embed, continue to [Share & embed →](#sec-373)
+For more on where and how to embed, continue to [Share & embed →](#sec-378)
---
@@ -60173,14 +62146,14 @@ Changes take effect immediately — no republishing needed for most settings.
## What's next
-- **Put it on your website** → [Share & embed](#sec-373)
-- **Understand how it all works** → [How it works](#sec-239)
-- **Give the agent a custom skill** → [Create a custom skill](#sec-426)
-- **Make it yours permanently (on-chain)** → [Register on-chain](#sec-456)
+- **Put it on your website** → [Share & embed](#sec-378)
+- **Understand how it all works** → [How it works](#sec-240)
+- **Give the agent a custom skill** → [Create a custom skill](#sec-432)
+- **Make it yours permanently (on-chain)** → [Register on-chain](#sec-462)
---
-<a id="sec-268"></a>
+<a id="sec-269"></a>
> **Source:** `docs/market-data-api.md` · [↑ table of contents](#table-of-contents)
@@ -60305,7 +62278,7 @@ as the single retryable class.
---
-<a id="sec-269"></a>
+<a id="sec-270"></a>
> **Source:** `docs/marketplace.md` · [↑ table of contents](#table-of-contents)
@@ -60412,6 +62385,13 @@ purchase from an unauthenticated wallet. The seller leg is always the **last**
instruction and carries the reference, because `validateTransfer` in step 3
inspects only the last instruction; a fee leg is placed before it.
+Before composing anything, the POST reads the buyer's token account for the
+purchase mint. A wallet that has never held the mint, or holds less than the
+price plus fee, gets a `409 insufficient_funds` naming the shortfall
+(`"this wallet is 0.35 short of …"`) instead of a transaction that can only fail
+in-wallet. If the RPC cannot answer, the transaction is built anyway and the
+chain decides, so a throttled node never blocks a payable purchase.
+
The payment modal shows the sponsored QR first and offers a one-click swap to the
direct-transfer QR for wallets that do not implement transaction requests.
@@ -60423,7 +62403,7 @@ direct-transfer QR for wallets that do not implement transaction requests.
and applied at settlement.
- Seller proceeds route to the seller's configured payout wallet
(`agent_payout_wallets`). A confirmed sale surfaces to the seller as a `sale` /
- `payment-earned` notification (see [Money feed](#sec-284)).
+ `payment-earned` notification (see [Money feed](#sec-285)).
## Access checks
@@ -60473,7 +62453,7 @@ sales and zero exhausted trials before it was found. See
endpoints are complete, but there is not yet a free, paginated "browse all
skills for sale" HTTP endpoint with sort/filter; discovery today is per-agent
(agents themselves are browsable at `GET /api/marketplace/agents`), and the
- paid [`/api/x402/skill-marketplace`](#sec-514) endpoint returns the
+ paid [`/api/x402/skill-marketplace`](#sec-539) endpoint returns the
live skill listing catalog with pricing for $0.001 USDC.
- **Auto-grant.** A confirmed skill purchase is recorded and the license NFT is
minted, but the purchased skill is not automatically attached to the buyer's
@@ -60492,12 +62472,12 @@ their chosen `currency_mint`; the platform promotes no coin other than $THREE.
## Related
- [Agent wallets](#sec-072) — how agent-side purchases are funded and gated.
-- [Circulation engine](#sec-139) — manufactured marketplace demand.
-- [Skills system](#sec-381), [Coin launches](#sec-142).
+- [Circulation engine](#sec-141) — manufactured marketplace demand.
+- [Skills system](#sec-387), [Coin launches](#sec-144).
---
-<a id="sec-270"></a>
+<a id="sec-271"></a>
> **Source:** `docs/mcp-3d-studio.md` · [↑ table of contents](#table-of-contents)
@@ -60569,7 +62549,7 @@ analyze: inspect_model · optimize_model preview: preview_3d
| `inspect_model(url)` | Structural stats: meshes, triangles, materials, textures, animations, extensions. |
| `optimize_model(url)` | Actionable size/perf suggestions: Draco/Meshopt, KTX2, triangle budget. |
| `preview_3d(glb_url, …)` | Render any public GLB as an interactive `<model-viewer>` artifact (orbit, AR, auto-rotate). |
-| `export_ar(glb_url, title?, kind?)` | Read-only: turn any public GLB into the device-aware AR link set (`arLaunchUrl`, `sceneViewerUrl`, `viewerUrl`, plus `irlUrl` when `kind: "avatar"`) and a [Spatial MCP](#sec-389) artifact. Free. See [AR & WebXR](ar.md#one-tap-ar-for-any-glb--get-apiar--export_ar). |
+| `export_ar(glb_url, title?, kind?)` | Read-only: turn any public GLB into the device-aware AR link set (`arLaunchUrl`, `sceneViewerUrl`, `viewerUrl`, plus `irlUrl` when `kind: "avatar"`) and a [Spatial MCP](#sec-395) artifact. Free. See [AR & WebXR](ar.md#one-tap-ar-for-any-glb--get-apiar--export_ar). |
Generation, rigging, and most mesh ops are **asynchronous**: the tool returns a
`job_id` immediately, then you poll `generation_status` (reconstruction is
@@ -60738,7 +62718,7 @@ npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-3d
---
-<a id="sec-271"></a>
+<a id="sec-272"></a>
> **Source:** `docs/mcp-agent.md` · [↑ table of contents](#table-of-contents)
@@ -60783,6 +62763,17 @@ may be requested by any client (including dynamically-registered ones), and are
approved by name on the consent screen. Ask for them in the `scope` parameter of
the authorization request; re-authorize an existing connection to add one.
+## Calling it without an account (x402)
+
+A client with no OAuth token can still reach the priced tools by paying per
+call. The 402 challenge this endpoint issues is scoped to itself: `resource.url`
+and every `accepts[].resource` read `https://three.ws/api/mcp-agent`, under the
+service name `three.ws Agent MCP`. Facilitators (CDP Bazaar, agentic.market,
+x402scan) index it from that same envelope, whose `extensions.bazaar` example is
+the read-only `find_services` call, so a crawler probing the documented shape can
+never move a caller's funds. `initialize`, `tools/list`, `ping`, and
+`getting_started` stay free for plain clients and crawlers.
+
## How payment works
`pay_and_call` reuses the audited SDK payment path — it does **not** hand-roll
@@ -60834,13 +62825,13 @@ npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-agent
---
-<a id="sec-272"></a>
+<a id="sec-273"></a>
> **Source:** `docs/mcp-safety.md` · [↑ table of contents](#table-of-contents)
# MCP tool safety
-Every tool three.ws publishes over the [Model Context Protocol](#sec-276) carries an
+Every tool three.ws publishes over the [Model Context Protocol](#sec-277) carries an
`annotations` block. Those hints are not decoration: an MCP client reads them to
decide whether a tool can run **without stopping to ask the user**. A tool marked
read-only gets executed silently; a tool marked destructive gets a confirmation
@@ -61169,7 +63160,7 @@ All four run in `npm run gate`.
---
-<a id="sec-273"></a>
+<a id="sec-274"></a>
> **Source:** `docs/mcp-studio.md` · [↑ table of contents](#table-of-contents)
@@ -61228,7 +63219,7 @@ want inline 3D widgets; the custom GPT covers plans without connector support.
How AR rides both ChatGPT surfaces (the `arUrl` contract, the device-aware
launcher, living avatars, link unfurls) is documented end to end in
-[AR in ChatGPT](#sec-137).
+[AR in ChatGPT](#sec-139).
## Tools
@@ -61282,7 +63273,7 @@ tool call at any tier; see [Pending generations](#pending-generations-check_job)
for how it is collected rather than lost.
One naming collision worth knowing: the npm package `@three-ws/mcp-server`
-([docs](#sec-276)) also ships a tool called `forge_free`. That is a different
+([docs](#sec-277)) also ships a tool called `forge_free`. That is a different
server with its own default (`draft`, stated in its own tool schema). The
default described here is the one for `https://three.ws/api/mcp-studio`.
@@ -61308,9 +63299,9 @@ sculpts into 3D (the forge's image-generation step). The inline widget uses it
as the model-viewer poster so the painted view shows while the GLB streams in,
and the result narration links it for non-widget clients.
-`arUrl` is the one-tap place-in-your-room link (see [AR in ChatGPT](#sec-137)).
+`arUrl` is the one-tap place-in-your-room link (see [AR in ChatGPT](#sec-139)).
Rigged avatars additionally carry `irlUrl`, the living-agent handoff into
-[IRL](#sec-255), and the inline widget's AR button becomes **Bring it to life**.
+[IRL](#sec-256), and the inline widget's AR button becomes **Bring it to life**.
Every result also includes a `spatial` field, the open Spatial MCP artifact
(`specs/SPATIAL_MCP.md`) so any Spatial-MCP renderer can display the model.
@@ -61531,15 +63522,15 @@ CSP entry cannot drift apart.
---
-<a id="sec-274"></a>
+<a id="sec-275"></a>
> **Source:** `docs/mcp-tools.md` · [↑ table of contents](#table-of-contents)
# MCP Tools Catalog
-three.ws ships several [MCP](#sec-276) servers: tool servers that AI assistants
+three.ws ships several [MCP](#sec-277) servers: tool servers that AI assistants
(Claude, ChatGPT, any MCP client) can call directly. One is free and 3D-only; the
-others expose paid tools that settle per call in USDC over [x402](#sec-519). This
+others expose paid tools that settle per call in USDC over [x402](#sec-544). This
page explains how the servers are grouped and how the paid ones charge.
> **Looking for a specific tool?** The complete, always-current list lives at
@@ -61578,7 +63569,7 @@ the read-only studio helpers below.
A free, non-crypto MCP server for the ChatGPT App Directory and any MCP client. It
exposes **only** 3D generation/inspection — no account, no payment, no token. See
-[3D Studio MCP](#sec-273).
+[3D Studio MCP](#sec-274).
## Material Studio (hosted, free) — `/api/material-studio`
@@ -61621,7 +63612,7 @@ and direction tools are flat per call.
Free studio helpers (no charge): `getting_started`, `generation_status`,
`preview_3d`, `list_animations`, `inspect_model`, `optimize_model`, `save_avatar`,
-`validate_spatial_response` (the [Spatial MCP](#sec-389) conformance gate).
+`validate_spatial_response` (the [Spatial MCP](#sec-395) conformance gate).
## Agent & commerce tools — `3d-agent-local`
@@ -61664,9 +63655,9 @@ generation lane**; the rest are paid and quote their price in the
| Server | File | Surface |
|---|---|---|
| Agent MCP | `api/mcp-agent.js` | Agent build/control tools. |
-| Bazaar MCP | `api/mcp-bazaar.js` | x402 service discovery — see [x402 bazaar](#sec-275). |
-| IBM MCP | `api/ibm-mcp.js` | watsonx / Granite integration — see [IBM](#sec-249). |
-| pump.fun MCP | `api/pump-fun-mcp.js` | Launch/trade tools — see [Solana pump.fun](#sec-386). |
+| Bazaar MCP | `api/mcp-bazaar.js` | x402 service discovery — see [x402 bazaar](#sec-276). |
+| IBM MCP | `api/ibm-mcp.js` | watsonx / Granite integration — see [IBM](#sec-250). |
+| pump.fun MCP | `api/pump-fun-mcp.js` | Launch/trade tools — see [Solana pump.fun](#sec-392). |
## $THREE only
@@ -61677,16 +63668,16 @@ promote no specific token.
## Related
-- [MCP](#sec-276) overview · [3D Studio MCP](#sec-273) ·
- [3D Studio (paid)](#sec-270) · [x402 bazaar](#sec-275)
-- [x402 paid endpoints](#sec-514) — the same capabilities over REST.
-- [MCP tool safety](#sec-272) - what each tool's safety annotations mean,
+- [MCP](#sec-277) overview · [3D Studio MCP](#sec-274) ·
+ [3D Studio (paid)](#sec-271) · [x402 bazaar](#sec-276)
+- [x402 paid endpoints](#sec-539) — the same capabilities over REST.
+- [MCP tool safety](#sec-273) - what each tool's safety annotations mean,
and the build check that verifies them against the code.
- [The full catalog](/mcp-tools) - every tool, searchable by safety and price.
---
-<a id="sec-275"></a>
+<a id="sec-276"></a>
> **Source:** `docs/mcp-x402-bazaar.md` · [↑ table of contents](#table-of-contents)
@@ -61798,7 +63789,7 @@ npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-bazaar
---
-<a id="sec-276"></a>
+<a id="sec-277"></a>
> **Source:** `docs/mcp.md` · [↑ table of contents](#table-of-contents)
@@ -61865,7 +63856,7 @@ There are two kinds. **Hosted remote servers** run over Streamable HTTP with not
| pump.fun | `/api/pump-fun-mcp` | Free pump.fun + Solana token tools; `pumpfun_upload_metadata` needs a key |
| IBM x402 | `/api/ibm-mcp` | Pay-per-use IBM Granite AI |
-**Thirty-seven install-and-run servers** on npm under the `@three-ws` scope — each runs over stdio with one command:
+**Thirty-eight install-and-run servers** on npm under the `@three-ws` scope, each running over stdio with one command:
```bash
# 3D & avatars
@@ -61883,6 +63874,9 @@ npx -y @three-ws/mcp-bridge # bridge that pays any x402 endpoint on the op
npx -y @three-ws/ibm-x402-mcp # pay-per-use IBM Granite AI
npx -y @three-ws/agentcore-payments-mcp # pay x402 endpoints from a governed budget, no private key
+# On-chain identity
+npx -y @three-ws/metaplex-agent-mcp # mint + register on-chain agents in the Metaplex Agent Registry (deploy fee funds $THREE buybacks, waived for holders)
+
# Market data, intel & discovery
npx -y @three-ws/intel-mcp # smart-money, signal feeds, KOL & copy-trade intel
npx -y @three-ws/pumpfun-mcp # free pump.fun + Solana token discovery
@@ -61945,8 +63939,8 @@ Ready-to-submit listing packages for each directory, plus the canonical metadata
Deep dives — every tool, argument, env var, and example:
-- **Hosted remote:** [3D Studio (free)](#sec-273) · [3D Studio (paid)](#sec-270) · [Agent wallet](#sec-271) · [x402 Bazaar](#sec-275) · [IBM x402](#sec-248)
-- **Install-and-run:** each npm server ships its usage guide (tools, arguments, env vars, examples) in its package README on [npmjs.com/org/three-ws](https://www.npmjs.com/org/three-ws). The [MCP Tools Catalog](#sec-274) maps every tool to its server and price.
+- **Hosted remote:** [3D Studio (free)](#sec-274) · [3D Studio (paid)](#sec-271) · [Agent wallet](#sec-272) · [x402 Bazaar](#sec-276) · [IBM x402](#sec-249)
+- **Install-and-run:** each npm server ships its usage guide (tools, arguments, env vars, examples) in its package README on [npmjs.com/org/three-ws](https://www.npmjs.com/org/three-ws). The [MCP Tools Catalog](#sec-275) maps every tool to its server and price.
---
@@ -62334,7 +64328,7 @@ Turn an avatar or on-chain agent **you own** into a holder-only interactive 3D e
}
```
-The `structuredContent` returns `gate_id`, `asset_id`, `gate` (`mint`, `min_amount`, `chain`), and `embed_snippet` — a ready-to-paste `<script>` + `<three-d>` tag. See [Token-gated 3D embeds](#sec-401) for the full verification flow, the anti-abuse token/rate-limit design, and how visitors unlock the embed.
+The `structuredContent` returns `gate_id`, `asset_id`, `gate` (`mint`, `min_amount`, `chain`), and `embed_snippet` — a ready-to-paste `<script>` + `<three-d>` tag. See [Token-gated 3D embeds](#sec-407) for the full verification flow, the anti-abuse token/rate-limit design, and how visitors unlock the embed.
---
@@ -62355,7 +64349,7 @@ Call any endpoint in the free [Crypto Data API](#sec-096) (the same aggregator b
}
```
-An unknown `provider`/`endpoint` pair returns an error result listing every valid pair. A registered endpoint marked free runs within the same per-IP quota the REST free lane enforces — no wallet needed. An endpoint with no free tier, or a free quota you've exhausted, returns a JSON-RPC `-32402` error naming the exact REST URL and USDC price to pay via [x402](#sec-519) — never a second, MCP-only payment flow.
+An unknown `provider`/`endpoint` pair returns an error result listing every valid pair. A registered endpoint marked free runs within the same per-IP quota the REST free lane enforces — no wallet needed. An endpoint with no free tier, or a free quota you've exhausted, returns a JSON-RPC `-32402` error naming the exact REST URL and USDC price to pay via [x402](#sec-544) — never a second, MCP-only payment flow.
```bash
# Equivalent to: GET /api/v1/x/dexscreener/token?addresses=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
@@ -62623,7 +64617,7 @@ Contributors: `npm run audit:mcp-safety` enforces this. It parses each tool's ha
---
-<a id="sec-277"></a>
+<a id="sec-278"></a>
> **Source:** `docs/media-api.md` · [↑ table of contents](#table-of-contents)
@@ -63161,7 +65155,7 @@ staged as web-ready GLBs. Same pagination (`?limit=1..1000`, `?offset=`),
same empty-until-staged behavior, no auth. One difference from the character
library: this endpoint validates the cursors strictly, so a malformed
`?limit`/`?offset` returns `400 invalid_limit` / `400 invalid_offset` instead
-of being coerced into a page. See [the object library doc](#sec-298)
+of being coerced into a page. See [the object library doc](#sec-301)
for the full parameter table.
### Response
@@ -63436,8 +65430,13 @@ Fields are `null` until the stage that produces them completes; on failure
| Malformed `?job=` | `400 invalid_job` (missing entirely: `400 missing_job`) |
| Worker not deployed on this environment | `503 unconfigured` |
| Worker rejected the job | `502 segment_failed` |
+| Worker unreachable while polling | `502 segment_status_failed` |
| Rate limit | `429` with `Retry-After` |
+A poll that answers `502 segment_status_failed` carries no `status` field, so a
+polling client should keep polling: the worker was briefly unreachable, which is
+not the same as the job dying.
+
### curl
```bash
@@ -63484,8 +65483,13 @@ auth; rate-limited per IP.
| Malformed `?job=` | `400 invalid_job` (missing entirely: `400 missing_job`) |
| Worker not deployed on this environment | `503 unconfigured` |
| Worker rejected the job | `502 rembg_failed` |
+| Worker unreachable while polling | `502 rembg_status_failed` |
| Rate limit | `429` with `Retry-After` |
+A poll that answers `502 rembg_status_failed` carries no `status` field, so a
+polling client should keep polling: the worker was briefly unreachable, which is
+not the same as the job dying.
+
### curl
```bash
@@ -63503,13 +65507,13 @@ curl -s 'https://three.ws/api/forge-rembg?job=JOB_ID'
## Related
- [3D API](#sec-001) - the core free text-to-3D lane, model inspection, and the paid Forge Pro tiers
-- [Image to 3D](#sec-250) - the photo-input reconstruction product these front doors feed
-- [Voice Lab](#sec-500) - voice cloning and synthesis, the other half of the avatar voice loop
+- [Image to 3D](#sec-251) - the photo-input reconstruction product these front doors feed
+- [Voice Lab](#sec-506) - voice cloning and synthesis, the other half of the avatar voice loop
- [API Reference](#sec-096) - the full three.ws HTTP API surface
---
-<a id="sec-278"></a>
+<a id="sec-279"></a>
> **Source:** `docs/memetic-launcher.md` · [↑ table of contents](#table-of-contents)
@@ -63614,12 +65618,12 @@ A POST with no body at all is valid and reads back as an empty patch, so
## Related surfaces
- [/launches](https://three.ws/launches) — every coin launched through three.ws, including yours.
-- [docs/pump-launcher.md](#sec-333) — the x402 paid one-shot launcher (`/api/x402/pump-launch`), a different surface: one coin per paid call, platform-fronted.
+- [docs/pump-launcher.md](#sec-339) — the x402 paid one-shot launcher (`/api/x402/pump-launch`), a different surface: one coin per paid call, platform-fronted.
- `api/_lib/launcher-engine.js` — the shared engine both scopes run on (cron: `/api/cron/launcher-tick`).
---
-<a id="sec-279"></a>
+<a id="sec-280"></a>
> **Source:** `docs/memory.md` · [↑ table of contents](#table-of-contents)
@@ -64031,7 +66035,7 @@ store described above and each revocable by deleting exactly what it wrote:
---
-<a id="sec-280"></a>
+<a id="sec-281"></a>
> **Source:** `docs/meta-allocator.md` · [↑ table of contents](#table-of-contents)
@@ -64125,14 +66129,14 @@ plan `source` is `"empty"` with a helpful message instead of an error.
## Related
-- [Trader Card & the claim-your-wallet wedge](#sec-403)
-- [The trading surfaces](#sec-409) · [/vaults](https://three.ws/vaults) (copy-trade with custody guardrails)
-- [Clip Director: every trade becomes content](#sec-141)
-- [Financial controls & custody guardrails](#sec-219)
+- [Trader Card & the claim-your-wallet wedge](#sec-409)
+- [The trading surfaces](#sec-415) · [/vaults](https://three.ws/vaults) (copy-trade with custody guardrails)
+- [Clip Director: every trade becomes content](#sec-143)
+- [Financial controls & custody guardrails](#sec-221)
---
-<a id="sec-281"></a>
+<a id="sec-282"></a>
> **Source:** `docs/mint-mark.md` · [↑ table of contents](#table-of-contents)
@@ -64258,13 +66262,13 @@ No other mint should appear in tests, fixtures, or documentation.
## Related
-- [Solana agents](#sec-388) — agent wallet management and on-chain interactions
-- [Solana pump.fun signals](#sec-386) — pump.fun live feed integration
-- [ERC-8004](#sec-185) — on-chain agent registry (uses the same brand metadata builder)
+- [Solana agents](#sec-394) — agent wallet management and on-chain interactions
+- [Solana pump.fun signals](#sec-392) — pump.fun live feed integration
+- [ERC-8004](#sec-188) — on-chain agent registry (uses the same brand metadata builder)
---
-<a id="sec-282"></a>
+<a id="sec-283"></a>
> **Source:** `docs/minted.md` · [↑ table of contents](#table-of-contents)
@@ -64272,7 +66276,7 @@ No other mint should appear in tests, fixtures, or documentation.
[three.ws/minted](https://three.ws/minted) is the live, public gallery of every generated or owned avatar that a creator chose to mint as a **Metaplex Core NFT** through three.ws. It is the NFT counterpart of the `/launches` coin directory: real on-chain property, listed the moment it mints. Every card renders the actual model in a live, auto-rotating 3D viewer (not a flat thumbnail), and every asset carries baked provenance and an enforced, capped creator royalty. Minting is always opt-in: the free text-to-3D lane never mints anything on its own.
-This doc covers the gallery surface and the mint flow as a user-facing feature. The provenance internals live in their own docs: [content credentials for AI-generated models](#sec-329) (signed credentials, Solana anchoring, the free verify endpoint) and [the three.ws mint mark](#sec-281) (the `3ws` address branding on coin launches).
+This doc covers the gallery surface and the mint flow as a user-facing feature. The provenance internals live in their own docs: [content credentials for AI-generated models](#sec-335) (signed credentials, Solana anchoring, the free verify endpoint) and [the three.ws mint mark](#sec-282) (the `3ws` address branding on coin launches).
## The gallery
@@ -64304,7 +66308,7 @@ curl "https://three.ws/api/v1/tokenized/launches?network=mainnet&offset=0&limit=
## How a mint works
-Minting runs through the `mint_3d_asset` tool on the [3D Studio MCP server](#sec-276). It is priced per call via x402 (USDC); an OAuth bearer token bypasses payment. A creator supplies:
+Minting runs through the `mint_3d_asset` tool on the [3D Studio MCP server](#sec-277). It is priced per call via x402 (USDC); an OAuth bearer token bypasses payment. A creator supplies:
- **The model:** an owned `avatar_id`, or any absolute `glb_url`.
- **The recipient:** an explicit `owner_wallet` (base58), or the OAuth-linked Solana wallet by default.
@@ -64327,7 +66331,7 @@ Every mint carries its provenance twice:
- **In the NFT metadata itself:** creator, prompt, generation model and provider, parent lineage, and timestamp travel with the asset wherever it goes.
- **As a signed record on the platform's append-only agent-actions ledger** (when the source avatar has a provisioned agent to sign as): an independently verifiable entry, referenced in the mint response and queryable via the MCP action tools. This write is best-effort and never blocks a mint that already succeeded on-chain.
-For how signed credentials, canonical hashing, and on-chain anchoring work under the hood, read [provenance.md](#sec-329). For the `3ws` address mark that brands coin launches, read [mint-mark.md](#sec-281).
+For how signed credentials, canonical hashing, and on-chain anchoring work under the hood, read [provenance.md](#sec-335). For the `3ws` address mark that brands coin launches, read [mint-mark.md](#sec-282).
### Remix royalties: paid the moment a remix mints
@@ -64341,14 +66345,14 @@ The companion MCP tool `get_3d_asset_onchain` resolves any Core mint address to
## Related
-- [Verifiable 3D provenance](#sec-329): signed content credentials and free verification for generated models
-- [The three.ws mint mark](#sec-281): the `3ws` address brand on coin launches
-- [MCP servers](#sec-276): the `mint_3d_asset` and `get_3d_asset_onchain` tools
-- [Custody you can verify](#sec-167): the wallet rails behind agent-held assets
+- [Verifiable 3D provenance](#sec-335): signed content credentials and free verification for generated models
+- [The three.ws mint mark](#sec-282): the `3ws` address brand on coin launches
+- [MCP servers](#sec-277): the `mint_3d_asset` and `get_3d_asset_onchain` tools
+- [Custody you can verify](#sec-170): the wallet rails behind agent-held assets
---
-<a id="sec-283"></a>
+<a id="sec-284"></a>
> **Source:** `docs/mocap-studio.md` · [↑ table of contents](#table-of-contents)
@@ -64440,14 +66444,14 @@ what the page itself sends.
## Related
-- [Avatar Studio](#sec-114): build the avatar you drive here.
+- [Avatar Studio](#sec-115): build the avatar you drive here.
- [Animation Studio](#sec-092): body posing and keyframed motion, the complement to facial capture.
- [Animations reference](#sec-093): how captured and authored motion fit the platform's clip registry.
- [/create](https://three.ws/create): make or import the avatar to perform with.
---
-<a id="sec-284"></a>
+<a id="sec-285"></a>
> **Source:** `docs/money-feed.md` · [↑ table of contents](#table-of-contents)
@@ -64461,7 +66465,7 @@ event lives.
> Not to be confused with the **personal activity feed** on `/feed`
> (`GET /api/users/me/feed`) — that one shows who created what and who followed
-> whom, and is documented in [The social layer](#sec-385). This page is
+> whom, and is documented in [The social layer](#sec-391). This page is
> about value movement only. The two share a URL word ("feed") and nothing else.
---
@@ -64537,9 +66541,9 @@ spend-cap and policy engine before they are recorded (see
| Producer | Ledger? | Ticker? | Domain record |
|---|---|---|---|
-| [Circulation engine](#sec-139) tips/payments/trades/buys | Yes | Trades/launches via pump feed | `circulation_actions` + domain table |
-| [Marketplace](#sec-269) skill/asset purchase | Yes | `payment` / `sale` | `skill_purchases` / `asset_purchases` |
-| [Coin launches](#sec-142) | Yes | `coin-buy` / `agent-deploy` | `pump_agent_mints` |
+| [Circulation engine](#sec-141) tips/payments/trades/buys | Yes | Trades/launches via pump feed | `circulation_actions` + domain table |
+| [Marketplace](#sec-270) skill/asset purchase | Yes | `payment` / `sale` | `skill_purchases` / `asset_purchases` |
+| [Coin launches](#sec-144) | Yes | `coin-buy` / `agent-deploy` | `pump_agent_mints` |
| Sniper trades | Yes (`category: 'snipe'`) | — | `agent_sniper_positions` |
| [Autonomous x402 loop](#sec-105) | Yes (`category: 'x402'`) | — | `x402_autonomous_log` |
| x402 service payments | Yes | `payment` | — |
@@ -64575,14 +66579,14 @@ The same bus powers surfaces that are not tickers at all:
## Related
-- [Circulation engine](#sec-139) — the largest producer of activity.
+- [Circulation engine](#sec-141) — the largest producer of activity.
- [Autonomous x402 loop](#sec-105) — treasury-paid intel purchases.
- [Agent wallets](#sec-072) — how spends are gated before they're recorded.
-- [x402 revenue & receipts](#sec-515) — the *other* direction: money paid **to** our endpoints (`x402_audit_log`), not agent spend.
+- [x402 revenue & receipts](#sec-540) — the *other* direction: money paid **to** our endpoints (`x402_audit_log`), not agent spend.
---
-<a id="sec-285"></a>
+<a id="sec-286"></a>
> **Source:** `docs/money-flow-map.md` · [↑ table of contents](#table-of-contents)
@@ -64757,6 +66761,14 @@ Two fields worth reading before you trust a number:
Cached for 60s server-side; the page refreshes every 60s and stops polling
entirely in a hidden tab.
+That background refresh never covers the drawn map. The timestamp beside the
+controls reports the re-read while it is out, and if it fails, the last good
+graph stays on screen with the failure named there rather than being replaced by
+an error panel. Switching window is the opposite case, because it throws the
+drawn topology away: that one takes the loading state, and it cancels any read
+still in flight, so a slow earlier window can never land on top of a newer one
+and draw a graph the buttons disagree with.
+
---
## Reading the page
@@ -64813,14 +66825,14 @@ covering it there. Keep the ordering discipline in `classifyRole`: a rule goes
## Related
-- [Money Pulse](#sec-284): the event stream these edges are aggregated from.
-- [Circulation engine](#sec-139): what generates most of this
+- [Money Pulse](#sec-285): the event stream these edges are aggregated from.
+- [Circulation engine](#sec-141): what generates most of this
activity.
- [Agent economy volume](#sec-052): the per-agent totals, ranked.
---
-<a id="sec-286"></a>
+<a id="sec-287"></a>
> **Source:** `docs/money-map.md` · [↑ table of contents](#table-of-contents)
@@ -64831,8 +66843,8 @@ wallet receives each kind of payment, what share the platform keeps, and which
treasury pays it forward. If you're adding a paid surface or auditing revenue,
start here.
-Companion docs: [x402 endpoints](#sec-514) (the paid endpoint catalog),
-[x402 revenue & receipts](#sec-515) (how settlements are recorded),
+Companion docs: [x402 endpoints](#sec-539) (the paid endpoint catalog),
+[x402 revenue & receipts](#sec-540) (how settlements are recorded),
[Solana signers runbook](../api/_lib/solana-signers.js) (the
signer/funder wallets and how to fund them).
@@ -64872,7 +66884,7 @@ Every engine signs from its **own** keypair; a single **funding root** tops thos
signers up with SOL when they run low, and does nothing else. Documented in full —
encodings, minimum balances, guards, funding tool — in the
[Solana signers runbook](../api/_lib/solana-signers.js) and the
-[economy master](#sec-179) subsystem doc.
+[economy master](#sec-182) subsystem doc.
| Wallet | Role |
| ------ | ---- |
@@ -64932,7 +66944,7 @@ unit economics.
[ring catalog](../api/_lib/x402/ring-catalog.js), the single source of truth)
across intel/oracle, agent/reputation, generation/3D, launch/naming/utility,
club, avatar shop, and bazaars. Full list and prices:
- [x402 endpoints](#sec-514).
+ [x402 endpoints](#sec-539).
- **Paid MCP tools** —
- Main MCP ([api/mcp.js](../api/mcp.js), pricing `api/_lib/pump-pricing.js`):
`mint_3d_asset` $0.25, `retexture_model` $0.10, `optimize_model` $0.05,
@@ -64952,9 +66964,9 @@ unit economics.
in the on-chain ASP record, not in repo code** — update it here if the ASP
registration changes.
- **Marketplace skills** — agent skill marketplace over Solana Pay
- ([api/marketplace/](../api/marketplace)); see [marketplace skills](#sec-488).
+ ([api/marketplace/](../api/marketplace)); see [marketplace skills](#sec-494).
- **Labor market** — bounty/escrow jobs with worker + author-royalty settlement; see
- [labor market](#sec-259).
+ [labor market](#sec-260).
- **Other** — vanity bounties, forge REST ([api/x402/forge.js](../api/x402/forge.js)),
subscriptions, credit deposits.
@@ -64964,7 +66976,7 @@ unit economics.
Engines that move money on their own (cron/worker driven) draw from the signer
wallets, not the receivers — and each signer is kept funded by the
-[economy master](#sec-179) via the `treasury-topup` cron (every 30 min,
+[economy master](#sec-182) via the `treasury-topup` cron (every 30 min,
allowlist-guarded, reserve/per-engine/per-run caps). Which wallet funds which
engine and minimum balances are in the
[Solana signers runbook](../api/_lib/solana-signers.js). The
@@ -65000,23 +67012,23 @@ Guardrails on outflow: the economy master is funder-only with reserve/per-transf
per-run caps and a registry allowlist; the ring can only settle to allowlisted
wallets (anti-drain gate); the sniper auto-funder moves money only for strategies
that set `auto_fund_enabled = true` (default off). See
-[financial-controls.md](#sec-219) for the full register.
+[financial-controls.md](#sec-221) for the full register.
## Related
-- [Financial controls & audit register](#sec-219) — every ledger's integrity, reconciliation, retention, monitoring, and the ranked gap list.
-- [x402 endpoints](#sec-514) — the paid endpoint catalog and price overrides.
-- [x402 revenue & receipts](#sec-515) — where settlements are recorded.
-- [x402 ring economy](#sec-516) — the internal recirculation loop.
-- [Pump platform fee](#sec-334) — the pump trade fee detail.
-- [Coin-launch wallets](#sec-490) — launch-time wallet flow.
+- [Financial controls & audit register](#sec-221) — every ledger's integrity, reconciliation, retention, monitoring, and the ranked gap list.
+- [x402 endpoints](#sec-539) — the paid endpoint catalog and price overrides.
+- [x402 revenue & receipts](#sec-540) — where settlements are recorded.
+- [x402 ring economy](#sec-541) — the internal recirculation loop.
+- [Pump platform fee](#sec-340) — the pump trade fee detail.
+- [Coin-launch wallets](#sec-496) — launch-time wallet flow.
- [Creator revenue splits](../api/_lib/cosmetics-economy.js) — `recordSaleAndSplit`: the cosmetic split math and its real USDC payout.
- [Agent wallet custody](#sec-072) — how custodial keys are held.
- [Solana signers runbook](../api/_lib/solana-signers.js) — signer/funder wallets + funding.
---
-<a id="sec-287"></a>
+<a id="sec-288"></a>
> **Source:** `docs/monitor.md` · [↑ table of contents](#table-of-contents)
@@ -65144,7 +67156,7 @@ board a lie.
avatar cam while it works
- [Money Pulse](https://three.ws/pulse): the full event feed with filters and
per-agent views
-- [Money Flow Map](#sec-285): the topology behind the totals, who
+- [Money Flow Map](#sec-286): the topology behind the totals, who
pays whom
- [Agent Economy Volume](https://three.ws/agent-economy-volume): the long-window
agent-to-agent hire ledger
@@ -65152,7 +67164,7 @@ board a lie.
---
-<a id="sec-288"></a>
+<a id="sec-289"></a>
> **Source:** `docs/motion-swap.md` · [↑ table of contents](#table-of-contents)
@@ -65212,7 +67224,8 @@ only), and processing artifacts live under an unguessable job id.
```
POST /api/motion-swap { action: "upload", content_type, size_bytes }
- → { upload_url, public_url, ... } # presigned direct-to-storage PUT
+ → { upload_url, public_url, method, headers, expires_in }
+ # presigned direct-to-storage PUT
POST /api/motion-swap { video_url, fps?, max_seconds? }
→ 202 { job_id, status, eta_seconds }
@@ -65221,6 +67234,11 @@ GET /api/motion-swap?job=<id>
→ { status, clip_url, meta_url, video_url, mask_url, frames, fps }
```
+`content_type` must be `video/mp4`, `video/quicktime`, or `video/webm`, and
+`size_bytes` must be between 1 byte and 256 MB. Start the PUT within
+`expires_in` seconds of getting the URL: the signature is minted for exactly
+that window, and storage rejects a late upload with a bare 403.
+
`clip_url` is a three.js `AnimationClip.toJSON()` document you can use
anywhere the platform accepts a clip. `meta_url` carries `fps`, dimensions,
and per-frame `anchors` (`{x, y, h, v}`: hip centre in normalized image
@@ -65238,11 +67256,11 @@ its error state.
- [/capture](https://three.ws/capture) — video → 3D point cloud (scene, not person)
- [/animations](https://three.ws/animations) — the clip library the output format matches
-- [docs/animations.md](#sec-093) · [docs/avatar-reconstruction.md](#sec-113)
+- [docs/animations.md](#sec-093) · [docs/avatar-reconstruction.md](#sec-114)
---
-<a id="sec-289"></a>
+<a id="sec-290"></a>
> **Source:** `docs/multi-agent.md` · [↑ table of contents](#table-of-contents)
@@ -65585,7 +67603,7 @@ To extend this into a full turn-based scene, add a `brain` attribute to Mira wit
---
-<a id="sec-290"></a>
+<a id="sec-291"></a>
> **Source:** `docs/native-launchpad.md` · [↑ table of contents](#table-of-contents)
@@ -65780,7 +67798,7 @@ Stated plainly, because a half-built feature that claims to be finished is worse
---
-<a id="sec-291"></a>
+<a id="sec-292"></a>
> **Source:** `docs/news-rights.md` · [↑ table of contents](#table-of-contents)
@@ -65874,11 +67892,11 @@ Three rules, in order of importance:
- [`api/_lib/news-rights.js`](../api/_lib/news-rights.js) — the implementation
- [`scripts/news-takedown-purge.mjs`](../scripts/news-takedown-purge.mjs) — the purge tool
-- [Market Data API](#sec-268) — the paid market endpoints, including archive search
+- [Market Data API](#sec-269) — the paid market endpoints, including archive search
---
-<a id="sec-292"></a>
+<a id="sec-293"></a>
> **Source:** `docs/notifications.md` · [↑ table of contents](#table-of-contents)
@@ -66159,7 +68177,7 @@ one click from the gear icon in both notification surfaces.
## Related pages
-- [The social layer](#sec-385): where notification events come from
+- [The social layer](#sec-391): where notification events come from
and how they connect to the feed, follows, and portfolios.
- [api/notifications/README.md](../api/notifications/README.md): the
endpoint directory's own reference.
@@ -66168,7 +68186,7 @@ one click from the gear icon in both notification surfaces.
---
-<a id="sec-293"></a>
+<a id="sec-294"></a>
> **Source:** `docs/nvidia-apps-catalog-listing.md` · [↑ table of contents](#table-of-contents)
@@ -66176,7 +68194,7 @@ one click from the gear icon in both notification surfaces.
Everything needed to submit three.ws to the NVIDIA Inception Accelerated Apps Catalog. The form lives behind the Inception portal login (Portal > Profile > Add product), so this doc holds the copy, categories, links, and assets ready to paste. Submissions are reviewed by NVIDIA on a rolling basis; approval is subject to fit.
-Related docs: [nvidia-inception.md](#sec-295) (membership overview), [nvidia-models.md](#sec-296) (full model map, the source of truth for every NVIDIA claim below).
+Related docs: [nvidia-inception.md](#sec-296) (membership overview), [nvidia-models.md](#sec-297) (full model map, the source of truth for every NVIDIA claim below), [nvidia-visibility-map.md](#sec-300) (every other NVIDIA surface, and the asks to batch into the request email below).
---
@@ -66209,7 +68227,7 @@ Remove and leave unchecked:
### 2. Ask for the catalog listing
-The portal has no "publish to catalog" button, so the request goes to the program team. Send the email in [nvidia-apps-catalog-request.md](#sec-294) to `[email protected]` after the record corrections above are saved, and note the send date there.
+The portal has no "publish to catalog" button, so the request goes to the program team. Send the email in [nvidia-apps-catalog-request.md](#sec-295) to `[email protected]` after the record corrections above are saved, and note the send date there.
---
@@ -66251,10 +68269,11 @@ Pick the closest available options in the form; the taxonomy varies.
Every item below is live in production unless marked otherwise. Do not claim TensorRT, Triton, or self-hosted NIM microservices; the GPU workers are PyTorch + CUDA today (TensorRT-LLM is an Inception roadmap item).
-- **NVIDIA L4 GPUs** (Google Cloud Run GPU) running the entire self-hosted 3D generation fleet: image-to-3D, sketch-to-3D, auto-rigging, text-to-motion, video-to-scene
+Also do not claim the **video-to-scene world scanner** or the **texture worker**, and do not re-add **FlashInfer** on their behalf. Both have a GPU `cloudbuild.yaml` in the tree but neither is deployed in any region (verified 2026-08-17 with the recount command below), so they are built code, not a running lane. Deploy them and they belong here; until then a curator who checks would find nothing behind the claim.
+
+- **NVIDIA L4 GPUs** (Google Cloud Run GPU) running the entire self-hosted 3D generation fleet: image-to-3D, sketch-to-3D, auto-rigging, text-to-motion. Eight GPU workers, twelve deployments across `us-central1` and `us-east4` (eleven L4, one RTX PRO 6000). Recount before submitting: `gcloud run services list --project aerial-vehicle-466722-p5 --format="csv[no-heading](metadata.name,region,spec.template.spec.nodeSelector)" | grep -i accelerator`
- **CUDA** with custom-compiled extensions (nvdiffrast, diffoctreerast, diff-gaussian-rasterization, torchmcubes)
- **NVIDIA Kaolin** (TRELLIS worker)
-- **FlashInfer** paged-KV-cache attention (video-to-scene worker)
- **NIM APIs** (integrate.api.nvidia.com): Nemotron Super and Nano LLMs, Nemotron Nano VL vision, NV-EmbedQA-E5-v5 embeddings, Mistral 4B reranking, NemoGuard 8B content safety
- **NVCF**: microsoft/trellis text-to-3D (the free default forge lane) and FLUX.1-schnell text-to-image
- **NVIDIA Riva**: Magpie multilingual TTS and Riva ASR over NVCF gRPC
@@ -66330,33 +68349,52 @@ Nothing else checked. TensorRT/Triton/Omniverse stay unchecked here too.
6. Submit. Listings are reviewed on a rolling basis; note the submission date in this doc when done.
7. Correct the existing record per the Status section (move Riva/Audio2Face/NIM to Used, drop DeepVariant NIM) BEFORE adding anything new.
8. Add the `<agent-3d>` embed as a second product using its section above. Do not file more records than these two: duplicates read as noise to the curator.
-9. Send the inclusion-request email in [nvidia-apps-catalog-request.md](#sec-294) to [email protected] and record the send date there.
+9. Send the inclusion-request email in [nvidia-apps-catalog-request.md](#sec-295) to [email protected] and record the send date there.
---
-<a id="sec-294"></a>
+<a id="sec-295"></a>
> **Source:** `docs/nvidia-apps-catalog-request.md` · [↑ table of contents](#table-of-contents)
-# Catalog inclusion request: email to NVIDIA Inception
+# The NVIDIA Inception email: five asks, one thread
+
+The Inception portal has no "publish to the catalog" control. A product record makes the company eligible; the public [Accelerated Apps Catalog](https://marketplace.nvidia.com/en-us/enterprise/applications/) is curated and published by NVIDIA. This is the request that asks for the listing, sent after the portal record is corrected per [nvidia-apps-catalog-listing.md](#sec-294).
-The Inception portal has no "publish to the catalog" control. A product record makes the company eligible; the public [Accelerated Apps Catalog](https://marketplace.nvidia.com/en-us/enterprise/applications/) is curated and published by NVIDIA. This is the request that asks for the listing, sent after the portal record is corrected per [nvidia-apps-catalog-listing.md](#sec-293).
+It also carries four other asks that have never been made. Per [nvidia-visibility-map.md](#sec-300), every Tier 1 ask routes to the same inbox, so they are batched here deliberately. **Do not split these into separate emails.** A program manager who receives one clear email with five asks answers it. Five separate emails read as noise.
-- **Subject:** three.ws (Inception member): request for Accelerated Apps Catalog listing
+- **Subject:** three.ws (Inception member): catalog listing, Showcase, and co-marketing
- **Sent:** not yet sent. Record the date here when it goes out.
+- **Blocked on:** the portal record correction, [nvidia-apps-catalog-listing.md](#sec-294) step 1. As filed the record reads as a CUDA consumer rather than a digital-human app, which undercuts asks 1 and 2. Correct it, save it, then send.
+
+### The five asks, and why each one is here
+
+| # | Ask | Basis |
+|---|---|---|
+| 1 | Accelerated Apps Catalog listing | Curated by NVIDIA; no self-serve route exists |
+| 2 | Inception Startup Showcase feature | Member benefit: "member spotlights and story opportunities" |
+| 3 | Co-marketing kit and official badge | Member benefit: "official badges, co-branded social content, and customizable assets for events" |
+| 4 | Redirect to the ACE / digital-human team | No public intake form found for ACE |
+| 5 | GTC Startup Pavilion and other event slots | Pavilion placement is negotiated with the program team, not a CFP submission |
+
+Asks 2 and 3 are entitlements listed on NVIDIA's own [program page](https://www.nvidia.com/en-us/startups/), not favors. Ask 3 is the specific unlock for social amplification: NVIDIA's social team can only reshare a post carrying the official badge and `#NVIDIAInception`. Without the kit there is no mechanism for them to amplify anything.
---
Hello,
-three.ws is an NVIDIA Inception member (accepted July 2026). Our product record is filed in the portal as Shipping / GPU Accelerated, and I would like to request consideration for the Accelerated Apps Catalog.
+three.ws is an NVIDIA Inception member (accepted July 2026). Our product record is filed in the portal as Shipping / GPU Accelerated. I have five requests, batched into one email rather than five.
+
+## 1. Accelerated Apps Catalog
+
+I would like to request consideration for the Accelerated Apps Catalog.
**What it is:** three.ws is a browser-native platform for generating 3D avatars and AI agents from a prompt. Text, image, or sketch input becomes a textured, auto-rigged GLB in seconds, and the resulting agent can talk, lip-sync, and be embedded on any site with one script tag. Free text-to-3D at https://three.ws/forge, no signup.
**Why it belongs in the catalog:** the whole product is NVIDIA accelerated computing end to end, in two layers.
-Self-hosted: ten GPU workers on Google Cloud Run NVIDIA L4s, built on `nvidia/cuda` 12.1 to 12.8 images with custom-compiled CUDA extensions (nvdiffrast, diffoctreerast, diff-gaussian-rasterization, torchmcubes) and NVIDIA Kaolin. These run Hunyuan3D 2.1 and TRELLIS for image-to-3D, TripoSG for sketch-to-3D, TripoSR for fast drafts, Make-It-Animatable for auto-rigging, Motion Diffusion Model for text-to-motion, and a video-to-scene world scanner. The heavy image-to-3D lane is validated on RTX PRO 6000 Blackwell with `sm_120` kernel builds.
+Self-hosted: eight GPU workers on Google Cloud Run, twelve service deployments across two regions, eleven on NVIDIA L4 and one on RTX PRO 6000 Blackwell. They are built on `nvidia/cuda` 12.1 to 12.8 images with custom-compiled CUDA extensions (nvdiffrast, diffoctreerast, diff-gaussian-rasterization, torchmcubes) and NVIDIA Kaolin, and they run Hunyuan3D 2.1 and TRELLIS for image-to-3D, TripoSG for sketch-to-3D, TripoSR for fast drafts, Make-It-Animatable for auto-rigging, and Motion Diffusion Model for text-to-motion. The heavy image-to-3D lane is validated on RTX PRO 6000 Blackwell with `sm_120` kernel builds.
NVIDIA-hosted: Nemotron Super and Nano power agent reasoning, Nemotron Nano VL handles vision, NV-EmbedQA-E5-v5 and Mistral reranking power agent memory, NemoGuard 8B gates every public publish, Riva Magpie TTS and Riva ASR give agents a voice, and Audio2Face-3D drives real-time ARKit blendshape facial animation in the browser (live demo: https://three.ws/demos/audio2face).
@@ -66370,6 +68408,35 @@ Suggested categorization: Industry, Media and Entertainment. Workload, Generativ
If anything else is needed for the listing (logo, screenshots, a longer description, a specific form), tell me the format and I will send it the same day. Press kit and brand assets are ready at https://three.ws and I can supply 1920x1080 captures of the generation flow on request.
+## 2. Inception Startup Showcase
+
+The program page describes member spotlights and story opportunities through the Inception Startup Showcase. I would like to put three.ws forward for consideration.
+
+The story we would tell is the one in the engineering posts above: a small team running a self-hosted NVIDIA GPU fleet plus NVIDIA-hosted models to make 3D agent generation fast enough and cheap enough to give away for free in a browser, with no signup. If a written profile, a founder interview, or a specific template is the format you need, tell me which and I will turn it around the same week.
+
+## 3. Co-marketing assets
+
+The program page lists official badges, co-branded social content, and customizable event assets as a member benefit. We have never requested the kit, and as a result our Inception membership has never been announced on our own channels, because we would rather announce it correctly the first time.
+
+Please send the current co-marketing kit and the badge usage guidelines. I want to confirm the correct badge lockup, the required attribution wording, and which handle to tag for digital-human content before we post anything.
+
+## 4. A redirect to the ACE / digital-human team
+
+I could not find a public intake route for the ACE team, so I am asking here for a redirect.
+
+We are running Audio2Face-3D in a browser tab. The client streams 16 kHz mono PCM into the ACE `A2FControllerService` over NVCF gRPC and renders the returned ARKit blendshape track against a WebGL avatar, mapping ARKit-52 onto whatever morph convention the user's own model ships, alongside Riva ASR in and Magpie TTS out. Live and public, no install and no signup: https://three.ws/demos/audio2face
+
+To be precise about what we are claiming: we consume ACE microservices as hosted APIs. We do not self-host NIM. Most A2F work we have seen lives in Unreal or Omniverse, so a browser-native implementation seemed worth putting in front of the team that owns it, whether that is useful as a reference integration, a feedback channel, or neither.
+
+## 5. GTC Startup Pavilion and other events
+
+I understand the GTC 2026 call for submissions has closed and that Pavilion placement is arranged with the program team rather than through the CFP. Two questions:
+
+- Is there a route to the Inception Startup Pavilion for the next GTC, and when does that conversation normally start?
+- The program materials mention Inception exposure at Oracle AI World, KubeCon, Supercomputing, Microsoft Ignite, AWS re:Invent, and NeurIPS. Which of those carry startup slots we would be eligible for, and what are their lead times?
+
+I would rather ask now and plan around the real dates than miss a window by a month.
+
Thank you,
Nicholas
@@ -66378,7 +68445,7 @@ https://three.ws
---
-<a id="sec-295"></a>
+<a id="sec-296"></a>
> **Source:** `docs/nvidia-inception.md` · [↑ table of contents](#table-of-contents)
@@ -66416,6 +68483,7 @@ Membership is a startup program, not a partnership or an investment: NVIDIA revi
## Related
+- [NVIDIA visibility map](#sec-300): every NVIDIA surface where three.ws can earn recognition, what each one requires, and which membership benefits are still unclaimed
- [NVIDIA models on three.ws](/docs/nvidia-models) — the free inference layer, model by model
- [The generator was never the hard part](/docs/nvidia-nemotron-spotlight): our Nemotron Nano write-up, published on the NVIDIA Developer Forums
- [Image-to-3D on NVIDIA L4 and Blackwell](https://three.ws/blog/image-to-3d-on-nvidia-l4-and-blackwell): the engineering post on the GPU fleet itself: memory ceilings, `sm_120` kernels, and regional quota
@@ -66423,7 +68491,7 @@ Membership is a startup program, not a partnership or an investment: NVIDIA revi
---
-<a id="sec-296"></a>
+<a id="sec-297"></a>
> **Source:** `docs/nvidia-models.md` · [↑ table of contents](#table-of-contents)
@@ -66536,7 +68604,7 @@ This lane powers the platform's built-in AI surfaces — chat, embedded site wid
| Llama 4 Maverick | `meta/llama-4-maverick-17b-128e-instruct` | balanced | Meta's 128-expert MoE — fast, multimodal-capable |
| MiniMax M2.7 | `minimaxai/minimax-m2.7` | balanced | General reasoning and chat |
-For anonymous (signed-out) callers, only the genuinely free tiers — the OpenRouter open-weight default plus these NVIDIA NIM models — are selectable. Each shows "unavailable" until the key is set, and `meta/llama-3.3-nemotron-super-49b-v1.5` also appears in the routing catalog as a tool-capable fallback model.
+For anonymous (signed-out) callers, only the genuinely free tiers (the OpenRouter open-weight default plus these NVIDIA NIM models) are selectable. Each shows "unavailable" until the key is set, and `nvidia/llama-3.3-nemotron-super-49b-v1.5` also appears in the routing catalog as a tool-capable fallback model.
> **Where the line is:** Nemotron and the `nvidia/…`-prefixed models are NVIDIA's own. The others in this table (DeepSeek, Kimi, Llama 4, MiniMax) are third-party open weights that NVIDIA *hosts and serves free* on NIM — so they ride the same key, but the model itself isn't NVIDIA's. The point of NIM is exactly this: one free key, a whole model garden.
@@ -66630,7 +68698,202 @@ The free NVIDIA TTS lane: **Magpie multilingual on Riva**, selected by an NVCF `
---
-<a id="sec-297"></a>
+<a id="sec-298"></a>
+
+> **Source:** `docs/nvidia-nemotron-ask-the-experts-questions.md` · [↑ table of contents](#table-of-contents)
+
+# Ask the Experts: Nemotron Open Family (Nemotron Labs, YouTube livestream)
+
+Two messages to post into the YouTube live chat of NVIDIA's "Ask the Experts: What's New
+in the Nemotron Open Family" stream: one from the official account, one from the founder
+account. YouTube live chat hard-caps a message at 200 characters, so every quote below is
+counted and fits.
+Both are built on things we can prove, so a panelist can check us mid-stream and find a
+real deployment, a published write-up on NVIDIA's own forums, and Inception membership.
+
+Nothing on a live stream is literally guaranteed. What follows maximizes the odds, and
+the reason is simple: these are not "what is Nemotron" questions from a stranger. They
+are production questions from a company already shipping on the models, carrying a
+number the panel will want to repeat.
+
+## Post 1: three.ws (official)
+
+Send this one first. It carries the Inception credential and the one product ask we
+actually want answered.
+
+> NVIDIA Inception startup here: nemotron-nano-12b-v2-vl gates every generation in our
+> text-to-3D pipeline. Any plans for guaranteed JSON / structured output decoding on the
+> NIM chat models?
+
+188 characters.
+
+Why this gets answered:
+
+- It is a **roadmap question a panel can answer**, not an opinion prompt. Guided decoding
+ is a real feature area with a real status.
+- It is **framed as a user who already shipped**, which is the framing NVIDIA's own
+ developer-relations people are on the stream to find.
+- The Inception line is one clause, up front, not a pitch. It qualifies us and then gets
+ out of the way.
+- It contains no link, so it is not filtered and it is easy to read aloud.
+
+Backup, if post 1 gets skipped and the chat moves on:
+
+> Inception member here: Nemotron Nano VL gates every generation on our text-to-3D
+> platform for its image-token footprint. Does Nemotron 3 Nano keep that footprint, or
+> does hybrid MoE change the math? (198 chars)
+
+## Post 2: nichxbt (founder)
+
+Send this five to ten minutes after post 1, never simultaneously. Different account,
+different angle, no repetition of the Inception line: this one is engineer to engineer.
+
+> 281 vs 1600: prompt tokens for the same image on nemotron-nano-12b-v2-vl vs a
+> 90B-class vision model. That number is why we shipped Nano. Was token efficiency a
+> deliberate design target?
+
+186 characters, and it opens with the number, which is what a host scanning a moving
+chat stops on.
+
+Why this gets answered:
+
+- It hands the panel a **compliment with a measurement attached**. Teams love hearing
+ their model won on an axis they were not benchmarked on, and it is the kind of line a
+ host repeats on air.
+- It is answerable in one sentence by anyone who worked on the model.
+- It reads as a person, not a brand, which is what a founder account is for.
+
+Backup for the founder account:
+
+> What is the smallest Nemotron you would trust as the input guardrail in front of an
+> expensive GPU job? Ours answers in 1-2s and saves a 20s generation. Does Nemotron 3
+> Nano move that floor? (189 chars)
+
+## The Super Chat play (if enabled)
+
+Super Chat is the closest thing this format has to a guaranteed reply: a paid message
+pins in the ticker above the chat, and hosts clear the Super Chat queue before free
+messages. Send it from the official account at the $10-20 tier, which buys the character
+room and keeps it in the ticker longer:
+
+> Inception startup: nemotron-nano-12b-v2-vl gates our text-to-3D pipeline. Any plans
+> for guaranteed JSON / structured decoding on NIM chat models?
+
+145 characters, so it fits every paid tier. If you Super Chat this one, keep the founder
+account in free chat with the token-efficiency question so the two lanes stay distinct.
+
+## The closer, once either gets answered
+
+YouTube holds or hides live-chat links from non-moderator accounts, so the closer moves
+off-chat:
+
+- In chat, the moment a panelist engages, say it in words: "Full write-up is on the
+ NVIDIA Developer Forums, search Nemotron three.ws." That survives the filter, and a
+ curious panelist finds the thread in one search.
+- After the stream, put the real link in the video's comment section:
+ https://forums.developer.nvidia.com/t/how-nemotron-made-three-ws-text-to-3d-pipeline-usable/376445
+- The link is still the closer. A published Nemotron case study on NVIDIA's own property
+ converts "someone in the chat" into "a member with a citable story", and gives the
+ channel something safe to amplify afterwards.
+
+## What we can prove if asked
+
+Every claim in the two posts is sourced, so a follow-up question cannot catch us out:
+
+| Claim | Source |
+|---|---|
+| NVIDIA Inception member, accepted July 2026 | [nvidia-inception.md](#sec-296) |
+| `nvidia/nemotron-nano-12b-v2-vl` gates every photo-to-3D generation, 1-2s | [nvidia-nemotron-spotlight.md](#sec-299), `api/_lib/forge-image-validate.js` |
+| ~281 image prompt tokens vs ~1,600 for a 90B-class VLM | [nvidia-nemotron-spotlight.md](#sec-299) |
+| Published Nemotron write-up on the NVIDIA Developer Forums | [forums.developer.nvidia.com](https://forums.developer.nvidia.com/t/how-nemotron-made-three-ws-text-to-3d-pipeline-usable/376445) |
+| `nvidia-nemotron-nano-9b-v2` used for reasoning turns, NemoGuard at ~340 ms median | [nvidia-nemotron-spotlight.md](#sec-299) |
+
+The two other standing asks from that write-up (the hosted TRELLIS image-input
+restriction and the 77-character TRELLIS prompt cap) are TRELLIS questions, not Nemotron
+questions. Do not spend a Nemotron panel's attention on them; they belong in the NIM or
+TRELLIS channel.
+
+## Posting rules for YouTube live chat
+
+- 200 characters is a hard cap, not a guideline: the chat box stops accepting input at
+ 200. Every quote in this doc is counted to fit.
+- One question per message. Two questions in one line get half-answered.
+- Lead with the constraint or the number, never with what we sell.
+- No links in live chat. YouTube holds URL messages from non-moderator accounts, and a
+ held message is invisible. Name the forum thread in words instead.
+- If the host asks for a prefix (NVIDIA streams often take questions as "Q: ..."), use
+ it exactly; moderators filter the chat on it.
+- The spam filter eats repeats. Never paste the same text twice from one account; if you
+ re-ask, change the wording.
+- Slow mode may allow one message per interval per account, so the first message from
+ each account has to be the good one.
+- Check display names before posting: the official account should show "three.ws" and
+ the founder account "nichxbt". The display name is what gets read aloud on stream.
+- Do not post the same question from both accounts. It reads as brigading and both get
+ ignored.
+- If a panelist answers, one thanks message, then stop. No stacked follow-ups.
+- Post early. Read-out-loud questions get picked in the first third, while the queue is
+ short enough to skim.
+- If neither post is answered on air, ask the same question in our existing forum thread.
+ The Nemotron team reads the developer forums, and a written answer there outlives a
+ live mention.
+
+## If the panel is on architecture and design
+
+Segment-matched questions. A question that lands on the topic already on screen gets read
+far more often than a good question that arrives out of order, so switch to these while
+architecture is up and hold the roadmap questions for later.
+
+### Official account, architecture segment
+
+> At 3.6B active of 31.6B, batch-1 latency still pays to read every expert. For a
+> single-call guardrail sitting in front of an expensive GPU job, is Nano MoE or a dense
+> small model the better design?
+
+197 characters. This is the sharpest architecture question we can ask honestly, because it
+is our actual deployment shape: the input gate runs one call per generation, concurrency
+one, latency-bound rather than throughput-bound. Sparse MoE pays off on batched serving
+and buys much less at batch 1, and an architecture panel knows that. Asking it as a design
+tradeoff rather than a complaint is what makes it answerable on air.
+
+### Founder account, architecture segment
+
+> On the hybrid Mamba-Transformer split: how many attention layers do you keep in
+> Nemotron 3 Nano, and was that ratio tuned for 1M-context KV cost or for recall quality?
+
+167 characters. The hybrid backbone is the family's signature design choice and the reason
+the 1M context fits in 24.6 GB at all. Asking which objective set the ratio invites the
+architecture answer they came to give.
+
+### Two more, if the segment runs long
+
+> What in the VL design gets a small reference image down to ~281 prompt tokens: patch
+> tiling, a token compressor, or the projector? We picked the model on that axis.
+
+Pairs with the founder post already drafted above, and turns our measurement into a
+design question about the vision tower rather than a repeat of the same compliment.
+
+> Does expert routing stay stable under constrained JSON decoding, or does forcing a
+> grammar push tokens to experts the router would not have picked? We run rigid JSON on
+> every call.
+
+This one bridges architecture and the structured-decoding ask in post 1, so it works as
+the follow-up if the official post gets answered while architecture is still on screen.
+
+## Background on the family, for the follow-up
+
+If they engage and there is room for a second question, these are grounded in the family
+as it stands: Nemotron 3 Nano at 31.6B total / 3.6B active with 1M context in 24.6 GB,
+Super at 120.6B / 12.7B, Ultra at 550B / 55B, all with open weights, data, and recipes,
+plus a reported trillion-parameter Nemotron 4 in training.
+
+- Time-to-first-token for Nano on an L4 when the same GPU is also feeding a render loop.
+- KV cache cost at full 1M context on a 24 GB card, and retrieval accuracy at 1M vs 128k.
+- Whether the openness bar (weights plus data plus recipes) holds at Nemotron 4 scale.
+
+---
+
+<a id="sec-299"></a>
> **Source:** `docs/nvidia-nemotron-spotlight.md` · [↑ table of contents](#table-of-contents)
@@ -66791,11 +69054,283 @@ Build the small stuff. Put it in front. The generator was never the hard part.
---
-*three.ws is a browser-native platform for generating 3D avatars, worlds, and agents from a sentence. The text-to-3D lane described here is free and open: no key, no account. Our full NVIDIA model map lives in [`docs/nvidia-models.md`](#sec-296), and the pipeline internals are in [`docs/3d-asset-pipeline.md`](#sec-002). three.ws joined the [NVIDIA Inception program](#sec-295) in July 2026; the companion engineering post on our own GPU fleet is [Image-to-3D on NVIDIA L4 and Blackwell](https://three.ws/blog/image-to-3d-on-nvidia-l4-and-blackwell).*
+*three.ws is a browser-native platform for generating 3D avatars, worlds, and agents from a sentence. The text-to-3D lane described here is free and open: no key, no account. Our full NVIDIA model map lives in [`docs/nvidia-models.md`](#sec-297), and the pipeline internals are in [`docs/3d-asset-pipeline.md`](#sec-002). three.ws joined the [NVIDIA Inception program](#sec-296) in July 2026; the companion engineering post on our own GPU fleet is [Image-to-3D on NVIDIA L4 and Blackwell](https://three.ws/blog/image-to-3d-on-nvidia-l4-and-blackwell).*
---
-<a id="sec-298"></a>
+<a id="sec-300"></a>
+
+> **Source:** `docs/nvidia-visibility-map.md` · [↑ table of contents](#table-of-contents)
+
+# NVIDIA visibility map: every surface, and how to get on it
+
+Inception membership is the door, not the result. This doc is the complete map of
+every NVIDIA surface where three.ws can earn recognition, what each one actually
+requires, and the honest status of each today.
+
+Scope note: the **Accelerated Apps Catalog** already has its own two docs and is
+not re-litigated here. See [nvidia-apps-catalog-listing.md](#sec-294)
+for the listing kit and [nvidia-apps-catalog-request.md](#sec-295)
+for the inclusion email. This doc covers everything else and links to them where
+they overlap.
+
+Researched and verified 2026-08-17. Every intake URL and email below was fetched
+or searched the same day; the ones that turned out to be dead are recorded in
+[Dead ends](#dead-ends-do-not-spend-time-here) so nobody re-chases them.
+
+---
+
+## The two facts that should reorder priorities
+
+Before any new outreach, two things about our existing position:
+
+**1. The Inception membership was never announced on X.** [announcement-coverage.md](#sec-095)
+tracks an "announced on X" column per surface. `/nvidia` (added 2026-07-30) has
+that column empty, while `/openai` has a real post behind it. The single biggest
+NVIDIA credential we hold has had no social push on our own channels. Everything
+in the [Social](#social-surfaces-ours-to-drive) section is blocked on nothing and
+costs nothing.
+
+**2. Jensen Huang already interacted with three.ws content, and we have no
+receipt.** [data/timeline.json](../data/timeline.json) carries
+`2026-07-18-jensen-huang`: "NVIDIA CEO Jensen Huang interacts with three.ws
+content, amplifying the NVIDIA Inception announcement." Its `source_url` is
+`null`. Five of the seven NVIDIA timeline events have a null `source_url`,
+including the Inception acceptance and its public announcement.
+
+That is the highest-value social proof this company has and it is currently
+unciteable. An engagement from NVIDIA's CEO is the first line of any Showcase
+pitch, podcast nomination, or press approach, and right now it cannot be shown to
+anyone. **Recovering that link is the highest-leverage single action on this
+page**, and it is a five-minute job for whoever has the account history. Archive
+it to `web.archive.org` the moment it is found, because a deleted post takes the
+proof with it.
+
+---
+
+## Tier 1: act now, no dependencies
+
+Everything here can be done today. Nothing waits on NVIDIA, a build, or a date.
+
+| # | Surface | Intake | Why it is Tier 1 |
+|---|---|---|---|
+| 1 | **Our own X, LinkedIn, and Telegram** | Ours | The membership post that never happened. See [Social](#social-surfaces-ours-to-drive). |
+| 2 | **Inception co-marketing kit** | Portal benefit request, or `[email protected]` | An entitlement we have never claimed. See [Benefits we are owed](#benefits-we-are-entitled-to-and-have-never-requested). |
+| 3 | **Portal product record correction** | `programs.nvidia.com/phoenix/application` | Gates the Showcase AND the Apps Catalog. Already specified in [nvidia-apps-catalog-listing.md](#sec-294) step 1. Nothing else in this doc lands well while the record says "CUDA consumer". |
+| 4 | **Inception Startup Showcase** | `[email protected]` | NVIDIA's own wording is "member spotlights and story opportunities". Curated from the portal record, so do #3 first. |
+| 5 | **AI Podcast guest nomination** | Embedded form at [ai-podcast.nvidia.com](https://ai-podcast.nvidia.com) | Free, one form, and a founder-shaped story. Fields: name, business email, organization, industry, job title, location, preferred language, and a description of the proposal. |
+| 6 | **NVIDIA Developer Forums, post 3** | [forums.developer.nvidia.com](https://forums.developer.nvidia.com) | We are 2 for 2 on posts that landed. This is the one channel with a proven track record, and it is self-serve. See [Technical publishing](#technical-publishing-the-proven-channel). |
+| 7 | **NVIDIA Developer Discord** | [discord.com/invite/nvidiadeveloper](https://discord.com/invite/nvidiadeveloper) | NVIDIA engineers and product staff are in there. The browser Audio2Face demo is a conversation starter with the actual ACE team, not a marketing ask. |
+| 8 | **Fix `docs/listings.md`** | Ours | The "Startup & Credit Programs" table lists Quicknode and Google Cloud and has **no NVIDIA row at all**, which is the one canonical place a reader looks for our program memberships. Fixed in this change. |
+
+## Tier 2: needs a build first
+
+Real listings, real effort, honest gates. Do not pitch these before the code exists.
+
+| Surface | Intake | The gate |
+|---|---|---|
+| **NGC Catalog** (via the [NGC Software Partner program](https://www.nvidia.com/en-us/gpu-cloud/ngc-software-partners/)) | Partner legal agreement, then push to an NGC private staging repo, pass security scanning and QA, final sign-off | **The closest Tier 2 surface to reachable.** Prerequisites are a CUDA 9+ base image, GPU acceleration, Pascal or newer, an EULA, and no personal-data collection. Our GPU workers are already `nvidia/cuda` 12.1 to 12.8 containers, so the technical bar is met; what is missing is the EULA and the legal agreement. This converts work we have already done into a permanent NVIDIA-hosted listing. |
+| **ACE / digital-human ecosystem** | No public form found. Ask for the redirect in the Showcase email | Genuinely strong: Riva, Magpie, and Audio2Face-3D are shipping, and a **browser-native** A2F demo is rare (most A2F work lives in Unreal or Omniverse). This is our most differentiated technical story. Do not overclaim: we consume ACE microservices, we do not self-host NIM. |
+| **NVIDIA Technical Blog** ([developer.nvidia.com/blog](https://developer.nvidia.com/blog/)) | No public guest-submission process. Route via the forum Technical Blog category and the program team | Editorially controlled by NVIDIA. The realistic path is a forum post that performs, then a pitch. Our two live forum posts are the audition tape. |
+| **Omniverse Exchange** | [Omniverse Exchange Publishing Portal](https://developer.nvidia.com/omniverse-exchange-publishing-portal) (early access), plus a GitHub repo tagged with the `omniverse-kit-extension` topic | **Blocked and should stay blocked.** OpenUSD interop is roadmap, not shipping, and [nvidia-apps-catalog-listing.md](#sec-294) already rules that Omniverse Kit stays under "Considering". Note the Omniverse Launcher was deprecated 2025-10-01, so old guides mislead. |
+
+## Tier 3: time-gated, and the clock is running
+
+**GTC is the single largest recognition surface NVIDIA operates, and the window
+for the next one is open approximately now.**
+
+GTC 2026 (San Jose, March 16 to 19) ran an Inception Startup Pavilion with 55+
+startups, "NVIDIA Inception Presents: Startup Pitches" sessions, and 25 Startup
+Spotlight sessions. NVIDIA's own startup page for the event is
+[nvidia.com/gtc/startups](https://www.nvidia.com/gtc/startups).
+
+Status as of 2026-08-17: the [call for submissions](https://www.nvidia.com/gtc/call-for-submissions/)
+page reads "The Poster Call for Submissions and Content Interest Survey are now
+closed" for GTC 2026. NVIDIA's own FAQ page is already titled for **GTC San Jose
+2027**, and third-party event trackers report 2027-03-14 to 2027-03-18. Treat the
+dates as unconfirmed until NVIDIA states them, but treat the **submission window
+as imminent**: for a March event, recent cycles opened submissions in the summer
+and closed in early fall, which is the month we are in.
+
+Actions, in order:
+
+1. **Put [nvidia.com/gtc/call-for-submissions](https://www.nvidia.com/gtc/call-for-submissions/)
+ on a weekly watch.** Missing this window costs a full year. It is the one item
+ on this page with a hard, externally-set deadline.
+2. **Write the poster and session abstracts before the form opens.** The strongest
+ submission we have is the browser-native digital human: Audio2Face-3D plus Riva
+ plus Nemotron driving a rigged avatar in a tab with no install, on a fleet of
+ L4s and one Blackwell. Second-strongest is the L4-and-Blackwell engineering
+ material already published on our blog.
+3. **Ask about the Inception Startup Pavilion separately.** Pavilion placement is
+ an Inception benefit negotiated with the program team, not a CFP submission.
+ Fold the question into the Showcase email so it costs no extra round trip.
+4. **Do not forget the Content Interest Survey.** It closes alongside the CFP and
+ is a low-effort way to signal topic fit before sessions are locked.
+
+Also date-driven, lower stakes: NVIDIA lists Inception exposure at Oracle AI
+World, KubeCon, Supercomputing, Microsoft Ignite, AWS re:Invent, and NeurIPS.
+Worth asking which of those have startup slots we qualify for.
+
+---
+
+## Social surfaces (ours to drive)
+
+This is the section with no gatekeeper, and it is the one we have used least.
+
+**The mechanics that actually get amplified:** NVIDIA's Inception co-marketing
+benefit is explicitly "official badges, co-branded social content, and
+customizable assets for events". Posts that use the official badge, tag the right
+account, and carry `#NVIDIAInception` are the ones NVIDIA's social team can
+reshare. A generic post naming NVIDIA in prose is not resharable.
+
+Pick the account by topic rather than blasting the main handle. Verified from
+[NVIDIA's official social directory](https://www.nvidia.com/en-us/contact/social/):
+
+| Our content | Account to tag | Platform |
+|---|---|---|
+| Digital humans, Audio2Face, Riva, avatars | `@NVIDIAAIDev`, `@NVIDIADeveloper` | X |
+| Inception membership, founder story, milestones | **NVIDIA for Startups** (82k+ followers) | LinkedIn |
+| Nemotron, NIM, inference pipeline | `@NVIDIAAI`, `@NVIDIAAIDev` | X |
+| 3D, OpenUSD, scene work | `@NVIDIAOmniverse` | X, LinkedIn, Discord |
+| GTC submissions and attendance | `@NVIDIAGTC` | X |
+| General company news | `@NVIDIA`, `@NVIDIANewsroom` | X |
+
+Also live and worth using: NVIDIA Developer on YouTube, Instagram, and Threads,
+plus the two Discords (NVIDIA Developer, NVIDIA Omniverse).
+
+**The content we already have and have never posted:**
+
+- The membership itself, with the official badge. Never posted.
+- The browser Audio2Face demo at `/demos/audio2face`. A 15-second screen capture
+ of a face lip-syncing in a browser tab with no install is the most
+ screenshot-friendly asset on the platform, and it maps exactly to what the ACE
+ team promotes.
+- The two NVIDIA Developer Forums posts. Published on NVIDIA's own property and
+ never amplified from ours.
+- The L4-and-Blackwell engineering post, including the `sm_120` kernel and
+ regional-quota material that GPU engineers actually reply to.
+- [readme-3d](../packages/readme-3d): an interactive 3D model rendered natively
+ in a GitHub README. Genuinely novel, and the model in it was generated on the
+ NVIDIA lane.
+
+Sequence it: badge post, then demo clip, then the forum posts, then the
+engineering deep dive. One per week beats four in a day, and each one is a
+separate chance for a reshare.
+
+## Technical publishing (the proven channel)
+
+Two forum posts, both live, both landed:
+
+- [How Nemotron made three.ws text-to-3D pipeline usable](https://forums.developer.nvidia.com/t/how-nemotron-made-three-ws-text-to-3d-pipeline-usable/376445)
+- [How three.ws translates a web app into 100 languages with NVIDIA NIM](https://forums.developer.nvidia.com/t/how-three-ws-translates-a-web-app-into-100-languages-with-nvidia-nim-an-llm-powered-i18n-pipeline/377379)
+
+This is the only NVIDIA channel where we have a track record, it is self-serve,
+and it feeds everything else: forum posts are what a Technical Blog pitch and a
+GTC abstract are built on.
+
+Post 3 should be the browser digital human, because it is the piece nobody else
+has written: streaming Audio2Face-3D blendshape tracks over gRPC into a WebGL
+avatar, mapping ARKit-52 onto whatever morph convention the visitor's model
+ships (ARKit, VRM vowels, Oculus visemes), with Riva ASR in and Magpie TTS out.
+Write it against [api/_lib/a2f-nvidia.js](../api/_lib/a2f-nvidia.js) and
+[src/voice/a2f-player.js](../src/voice/a2f-player.js) so every claim has code
+behind it, and follow the house rule the existing two follow: real numbers,
+real latencies, no marketing voice.
+
+## Benefits we are entitled to and have never requested
+
+Straight from NVIDIA's [Inception program page](https://www.nvidia.com/en-us/startups/).
+These are membership benefits, not favors, and they are requested through the
+portal or the program email.
+
+| Benefit | NVIDIA's wording | Status |
+|---|---|---|
+| Co-marketing assets | "Amplify your brand with official badges, co-branded social content, and customizable assets for events." | **Never requested.** Ask for the kit. |
+| Startup Showcase feature | "Feature in the NVIDIA Inception Startup Showcase with member spotlights and story opportunities." | Never requested. Tier 1 #4. |
+| Member-only newsletter | Product releases and offers | Confirm we are subscribed. Also the likeliest place a member spotlight surfaces. |
+| Event exposure | GTC, Oracle AI World, KubeCon, Supercomputing, Microsoft Ignite, AWS re:Invent, NeurIPS | Never asked which have startup slots. |
+| Capital Connect / VC Alliance | Eligibility-based investor introductions | [Program page](https://www.nvidia.com/en-us/startups/venture-capital/). Owner's call, not an engineering task. |
+| Cloud credits and preferred pricing | Free credits from NVIDIA and partners | Separate from the GCP credits already in use. Worth auditing against [ops/gcp-credits-plan.md](ops/gcp-credits-plan.md). |
+
+On tiers: third-party write-ups describe a **Premier** tier above entry with a
+larger DGX allocation and more co-marketing, promoted on usage and traction
+signals. NVIDIA does not document this publicly, so treat it as unconfirmed and
+never claim a tier. It is a fair question to ask the program team, and the answer
+is worth having, because "more co-marketing" is exactly what this page is about.
+
+## Dead ends: do not spend time here
+
+Recorded so the next person does not repeat the search.
+
+- **NVIDIA Connect for ISVs.** `nvidia.com/en-us/programs/isv/` 301-redirects to
+ `developer.nvidia.com`. The standalone ISV program has been folded into the
+ Developer Program. There is no separate ISV listing to apply for.
+- **A self-serve "list my product" form.** None exists on any NVIDIA surface
+ reviewed here. Every listing runs through the portal record plus a human at
+ `[email protected]`. Stop looking for a form.
+- **Omniverse Launcher guides.** Deprecated 2025-10-01. Any tutorial routing
+ through it is stale.
+- **build.nvidia.com as a publishing target.** It is where we *get* our
+ `nvapi-` key and consume hosted models. Publishing goes through NGC, not there.
+
+---
+
+## Contacts, in one place
+
+| Purpose | Address |
+|---|---|
+| All Inception matters, Showcase, co-marketing, GTC pavilion | `[email protected]` |
+| China-based startups (not us, recorded for completeness) | `[email protected]` |
+| Member portal | `programs.nvidia.com/phoenix/application` |
+
+One thread, one address. Every ask in Tier 1 goes to the same inbox, so batch
+them into a single email rather than sending four.
+
+**Done: the batched email is written.** [nvidia-apps-catalog-request.md](#sec-295)
+now carries all five asks (catalog listing, Showcase nomination, co-marketing kit,
+ACE redirect, GTC pavilion and event slots) in one thread. Do not start a second
+one. It is still gated on the portal record correction, which is step 1 of
+[nvidia-apps-catalog-listing.md](#sec-294): as filed the
+record reads as a CUDA consumer, which undercuts the first two asks. Correct the
+record, save it, then send and stamp the date in the request doc.
+
+## Verification log
+
+| Claim | Checked how | Result |
+|---|---|---|
+| GTC 2026 CFP closed; 2027 is next | Fetched [call-for-submissions](https://www.nvidia.com/gtc/call-for-submissions/) | "now closed" for GTC 2026; NVIDIA's FAQ page already titled GTC San Jose 2027 |
+| Inception benefit wording | Fetched [nvidia.com/en-us/startups](https://www.nvidia.com/en-us/startups/) | Quoted verbatim above |
+| Social handles | Fetched [NVIDIA social directory](https://www.nvidia.com/en-us/contact/social/) | Full list; the table above is the topic-relevant subset |
+| AI Podcast guest form | Fetched [ai-podcast.nvidia.com](https://ai-podcast.nvidia.com) | Embedded "Submit Guest Ideas" form, fields recorded above |
+| NGC publishing prerequisites | Searched the [NGC Software Partner page](https://www.nvidia.com/en-us/gpu-cloud/ngc-software-partners/) | Legal agreement, staging repo, security scan, QA, sign-off |
+| ISV program retired | `WebFetch` on `nvidia.com/en-us/programs/isv/` | HTTP 301 to `developer.nvidia.com` |
+| Both forum posts live | `curl -o /dev/null -w '%{http_code}'` | Both 200 |
+| `/nvidia` never announced on X | Read [announcement-coverage.md](#sec-095) inventory | Column empty for `/nvidia`, populated for `/openai` |
+| Jensen Huang engagement has no source | `data/timeline.json`, event `2026-07-18-jensen-huang` | `source_url: null`, as are 4 other NVIDIA events |
+| GPU fleet shape | `gcloud run services list` across all regions, filtered to accelerator node selectors | 8 workers, 12 deployments, 11 L4 + 1 RTX PRO 6000 |
+
+Recount the fleet before quoting it anywhere:
+
+```bash
+gcloud run services list --project aerial-vehicle-466722-p5 \
+ --format="csv[no-heading](metadata.name,region,spec.template.spec.nodeSelector)" \
+ | grep -i accelerator
+```
+
+## Related
+
+- [Big-tech recognition dispatch board](#sec-125): this map ranked against every other big-tech surface (OpenAI, Anthropic, AWS, IBM) by the odds of a published mention this week. Read that first if you are deciding where a week goes, and this one once NVIDIA is the answer.
+- [NVIDIA Inception membership](#sec-296): what membership is, and the rule that it is a program and not a partnership or an endorsement
+- [Apps Catalog listing kit](#sec-294) and [inclusion request](#sec-295): the one surface with its own dedicated docs
+- [NVIDIA models on three.ws](#sec-297): the source of truth for every NVIDIA technical claim made in any pitch
+- [Listings and distribution](#sec-265): the canonical program and directory inventory
+- [Announcement coverage](#sec-095): which surfaces have been announced and which have not
+- [Partners](#sec-318): the independence and no-endorsement language that must survive any rewrite
+
+---
+
+<a id="sec-301"></a>
> **Source:** `docs/object-library.md` · [↑ table of contents](#table-of-contents)
@@ -66806,7 +69341,7 @@ The Object Library is a free, curated gallery of CC0 3D objects and props: furni
Page: [/objects](https://three.ws/objects) · API: `GET /api/objects/library`
Source: [`pages/objects.html`](../pages/objects.html) · [`src/objects-library.js`](../src/objects-library.js) · [`api/objects/library.js`](../api/objects/library.js)
-> This page covers the object gallery and its API. For rigged, animation-ready characters, see the [Character Library](#sec-134). For how AR placement works on phones and desktops, see [AR & WebXR](#sec-099).
+> This page covers the object gallery and its API. For rigged, animation-ready characters, see the [Character Library](#sec-136). For how AR placement works on phones and desktops, see [AR & WebXR](#sec-099).
---
@@ -66822,7 +69357,7 @@ Each card renders the object live in an auto-rotating `<model-viewer>` (with the
| Button | Destination | What you get |
|---|---|---|
-| **Preview** | `/app#model=<glb-url>&kind=object&title=<name>` | The full three.js [3D viewer](#sec-499) in object mode (no agent chat; Restyle, AR, and Download affordances instead) |
+| **Preview** | `/app#model=<glb-url>&kind=object&title=<name>` | The full three.js [3D viewer](#sec-505) in object mode (no agent chat; Restyle, AR, and Download affordances instead) |
| **AR** | `/ar/studio?src=<glb-url>&title=<name>` | [AR Studio](#sec-098): place the prop in your real space through the camera (see [AR & WebXR](#sec-099) for how the AR handoff works per device) |
| **Download** | The GLB URL directly | The raw GLB file, CC0, yours to use anywhere |
@@ -66836,7 +69371,7 @@ Gallery controls:
## API: `GET /api/objects/library`
-Public, no authentication, `GET` and `OPTIONS` only (`HEAD` is answered like `GET`). Browser `fetch` from a third-party origin is not enabled: like the [Character Library API](#sec-134), the endpoint sends `Access-Control-Allow-Origin` only for three.ws and its partner origins, and the R2 CDN holding the GLBs is scoped the same way. Call it server-side, or from a three.ws page, and the assets it points at are still yours to download and redistribute anywhere (a download or a server-side fetch is not CORS-gated; only in-browser cross-origin reads are). The endpoint proxies a small manifest JSON from the R2 CDN (`objects/library/manifest.json`) with an edge cache (`Cache-Control: public, s-maxage=300, stale-while-revalidate=3600`). The GLB and thumbnail bytes never pass through the API: every entry carries absolute CDN URLs the browser loads directly. It mirrors the [Character Library API](#sec-134) exactly, with `objects` in place of `avatars`.
+Public, no authentication, `GET` and `OPTIONS` only (`HEAD` is answered like `GET`). Browser `fetch` from a third-party origin is not enabled: like the [Character Library API](#sec-136), the endpoint sends `Access-Control-Allow-Origin` only for three.ws and its partner origins, and the R2 CDN holding the GLBs is scoped the same way. Call it server-side, or from a three.ws page, and the assets it points at are still yours to download and redistribute anywhere (a download or a server-side fetch is not CORS-gated; only in-browser cross-origin reads are). The endpoint proxies a small manifest JSON from the R2 CDN (`objects/library/manifest.json`) with an edge cache (`Cache-Control: public, s-maxage=300, stale-while-revalidate=3600`). The GLB and thumbnail bytes never pass through the API: every entry carries absolute CDN URLs the browser loads directly. It mirrors the [Character Library API](#sec-136) exactly, with `objects` in place of `avatars`.
### Query parameters
@@ -66903,14 +69438,14 @@ The gallery and API are read-only consumers of a manifest built by a local pipel
## Related
-- [Character Library](#sec-134): the rigged, animation-ready counterpart to this library.
+- [Character Library](#sec-136): the rigged, animation-ready counterpart to this library.
- [AR & WebXR](#sec-099): the device-by-device AR methods behind the AR button.
- [AR Studio](#sec-098): the `/ar/studio` surface the AR button opens, including multi-object rooms.
-- [3D Viewer](#sec-499): the `/app` engine the Preview button opens in object mode.
+- [3D Viewer](#sec-505): the `/app` engine the Preview button opens in object mode.
---
-<a id="sec-299"></a>
+<a id="sec-302"></a>
> **Source:** `docs/okx-marketplace.md` · [↑ table of contents](#table-of-contents)
@@ -66924,8 +69459,8 @@ not live yet: it was rejected in review and a resubmission is pending, so the se
are reachable directly at the endpoints documented here rather than through the marketplace.
Current listing state is tracked in [`prompts/okx-ai/PROGRESS.md`](../prompts/okx-ai/PROGRESS.md).
-> Related: [REST API Reference](#sec-096) · [MCP servers](#sec-276) ·
-> [x402 payments](#sec-519) · seller-side protocol spec: [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md)
+> Related: [REST API Reference](#sec-096) · [MCP servers](#sec-277) ·
+> [x402 payments](#sec-544) · seller-side protocol spec: [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md)
The **single source of truth** for every service (names, 2-part OKX descriptions, prices,
endpoints, input schemas) is [`api/_lib/okx-catalog.js`](../api/_lib/okx-catalog.js), the
@@ -67047,7 +69582,7 @@ tests.
## Decomposed 3D studio services
Micro-priced, single-capability REST endpoints, plain JSON `POST`, one price each, all
-backed by the same engines the [MCP 3D studio](#sec-276) runs (no separate pipeline).
+backed by the same engines the [MCP 3D studio](#sec-277) runs (no separate pipeline).
`GET` on any of them returns its free descriptor (price, description, input schema).
| Service | Price (USDT) | Endpoint | You send |
@@ -67181,7 +69716,7 @@ USDC rails. The wire format OKX buyers use (headers `PAYMENT-REQUIRED` /
---
-<a id="sec-300"></a>
+<a id="sec-303"></a>
> **Source:** `docs/onboarding-tier.md` · [↑ table of contents](#table-of-contents)
@@ -67328,17 +69863,17 @@ drift silently, since the four files involved have no import edge between them:
- [`public/nav-data.js`](../public/nav-data.js) — the single source of truth for every menu
- [`STRUCTURE.md`](../STRUCTURE.md) — where every product surface lives
-- [`docs/start-here.md`](#sec-393) — the same journey, written for a human rather than a maintainer
+- [`docs/start-here.md`](#sec-399) — the same journey, written for a human rather than a maintainer
---
-<a id="sec-301"></a>
+<a id="sec-304"></a>
> **Source:** `docs/onchain-agents.md` · [↑ table of contents](#table-of-contents)
# Deploying Agents On-Chain (Bulk)
-Give every three.ws agent a real on-chain identity: a **Metaplex Core NFT** minted into the **three.ws Agents collection** on Solana. This page is for platform admins and self-hosters; regular users register a single agent through the wallet-signed flow instead. It is the bulk/admin counterpart to the single-agent, user-signed flow in [Solana agents](#sec-388): it deploys many agents server-side through a CLI runner that reports every mint as it lands.
+Give every three.ws agent a real on-chain identity: a **Metaplex Core NFT** minted into the **three.ws Agents collection** on Solana. This page is for platform admins and self-hosters; regular users register a single agent through the wallet-signed flow instead. It is the bulk/admin counterpart to the single-agent, user-signed flow in [Solana agents](#sec-394): it deploys many agents server-side through a CLI runner that reports every mint as it lands.
> Not pump.fun. These are NFTs (on-chain identity), not tokens. The only coin three.ws ever references is `$THREE`; it appears in each asset's metadata as a link, nothing more.
@@ -67401,7 +69936,7 @@ Every agent is minted **into** a single Metaplex Core *collection* account, "thr
2. **DB** — the `app_settings` table, key `solana_agent_collection_<network>`.
3. **Deploy** — first run with neither set deploys the collection (funded + signed by the authority), then persists its address to `app_settings`.
-> After the first run, set `SOLANA_AGENT_COLLECTION_MAINNET=<address>` in your environment so the single-agent flow in [Solana agents](#sec-388) mints into the *same* collection.
+> After the first run, set `SOLANA_AGENT_COLLECTION_MAINNET=<address>` in your environment so the single-agent flow in [Solana agents](#sec-394) mints into the *same* collection.
---
@@ -67608,14 +70143,160 @@ A confirmed canary asset shows `inCollection=true`, `royalty=500bps`, `attrs=11`
## See also
-- [Solana agents](#sec-388) — the single-agent, user-signed registration flow.
-- [ERC-8004](#sec-185) — the EVM on-chain identity path.
+- [Solana agents](#sec-394) — the single-agent, user-signed registration flow.
+- [ERC-8004](#sec-188) — the EVM on-chain identity path.
- [Agent manifest](#sec-055) — the metadata schema.
-- [Mint mark ("3ws")](#sec-281) — vanity marking for three.ws launches.
+- [Mint mark ("3ws")](#sec-282) — vanity marking for three.ws launches.
---
-<a id="sec-302"></a>
+<a id="sec-305"></a>
+
+> **Source:** `docs/openai-listing-channels.md` · [↑ table of contents](#table-of-contents)
+
+# OpenAI listing channels: every surface three.ws can be listed on
+
+Every route to getting three.ws published on an OpenAI-owned surface, ranked by leverage, with the concrete blocker on each. Written 2026-08-17 after auditing the stalled Cookbook PR.
+
+Related docs: [listings.md](#sec-265) (every listing across all vendors), [mcp.md](#sec-277) (the hosted MCP server a plugin submission depends on), [nvidia-apps-catalog-listing.md](#sec-294) (the same kind of kit for NVIDIA).
+
+---
+
+## Summary: the Cookbook was the weakest of five channels, and we led with it
+
+The Cookbook is a docs repo with no distribution guarantee. The **plugin directory** is a product listing inside ChatGPT and Codex with real installs. We have 37 MCP packages and a hosted OAuth 2.1 MCP server already shipping, which is the exact hard requirement most plugin submitters fail. That is the channel to lead with.
+
+| Channel | Owner | Effort | What it gets us | Status |
+|---|---|---|---|---|
+| **Plugin directory** (ChatGPT + Codex) | OpenAI | Medium | A listed, installable product inside ChatGPT and Codex | Not submitted. We already meet the MCP prerequisite. |
+| **Showcase Gallery** | OpenAI | Low | Editorial feature on openai.com | Not submitted. Open web form. |
+| **Cookbook** | OpenAI | Done, then stalled | A docs page on cookbook.openai.com | PR [#2874](https://github.com/openai/openai-cookbook/pull/2874) open since 2026-07-21, currently unmergeable. |
+| **Customer stories** | OpenAI | High | Case study on openai.com/stories | Sales-led. Needs usage numbers, not a form. |
+| **Grove** | OpenAI | Low | $50k API credits, SF cohort | Wrong stage. Program is pre-idea to pre-seed. |
+
+---
+
+## 1. Plugin directory (the real opportunity)
+
+On **2026-07-09 OpenAI migrated the App directory into the Plugin directory**, a single universal directory shared by ChatGPT and Codex. You publish once and appear in both. This replaced the app-submission flow OpenAI opened to third-party developers on 2025-12-17.
+
+Docs: [developers.openai.com/plugins](https://developers.openai.com/plugins) · [submission guide](https://developers.openai.com/plugins/deploy/submission.md) · [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review.md) · [plugin guidelines](https://developers.openai.com/plugins/app-guidelines.md) · [submission errors](https://developers.openai.com/plugins/deploy/submission-errors.md)
+
+### Why we are unusually well positioned
+
+The gating requirement is a public, production MCP server. Most submitters have to build one. We already run it:
+
+| Requirement | What we already have |
+|---|---|
+| Public MCP server | `https://three.ws/api/mcp`, Streamable HTTP, MCP `2025-06-18` ([mcp.md](#sec-277)) |
+| Auth | OAuth 2.1 end-user flow, with `api/mcp/.well-known/oauth-protected-resource` discovery already routed in `vercel.json` |
+| Verified website | three.ws, live on Cloud Run behind the production LB |
+| Privacy policy and terms | Live pages, already declared in `data/pages.json` |
+| Well-scoped tools | 37 MCP packages under `packages/*-mcp`, plus `mcp-server/` and `mcp-bridge/` |
+| Screenshots and UI | The avatar viewer and studio surfaces render inline already |
+
+### Prerequisites before the form opens
+
+1. **"Apps Management" write access** on the OpenAI Platform organization role. Without it the submission portal will not let you create a draft.
+2. **Verified developer or business identity.** Every public submission requires it. Complete individual or business verification in organization settings first, because verification is its own review and will otherwise become the long pole.
+
+### What the form asks for
+
+Six sections: **Info** (name, short and long description, logo, category, URLs, publisher fields), **MCP** (server URL, authentication, domain verification, tool scanning), **Skills** (upload a bundle or import from the MCP server), **Prompts** (starter examples), **Testing**, **Global** (country availability). Plus release notes.
+
+**The testing section is the one to budget for: at least five positive test cases and three negative ones.** Positive cases need a user prompt, expected behavior, result shape, and any required test data. Negative cases have to demonstrate an appropriate refusal or a safe fallback.
+
+### Scoping decision: submit one plugin, not thirty-seven
+
+The guidelines reject "overly generic single-word names unlinked to your brand" and reward apps that are "tightly scoped." Thirty-seven separate MCP servers submitted individually reads as directory spam and most would fail the tightly-scoped test on their own. Submit **one three.ws plugin whose tools are the text-to-3D and avatar pipeline**, which is the thing no one else in the directory does. The rest stay available as direct MCP connections documented in [mcp.md](#sec-277).
+
+### Known rejection reasons to design against
+
+Trial or demo versions and incomplete functionality; missing or misleading tool annotations (`readOnlyHint`, `destructiveHint`, `openWorldHint` must be set and accurate); unauthorized third-party integrations or API circumvention; deceptive commerce, which includes digital goods, subscriptions, and upsells; unauthorized data collection. Content must suit users 13 to 17.
+
+Two of those need real attention in our case. **Tool annotations** must be audited across the submitted server, because generation tools that spend credits are not `readOnlyHint`. And **deceptive commerce**: the x402 payment path has to be transparently disclosed, never presented as free and then charged.
+
+### Review flow
+
+Submit, OpenAI reviews, they approve, then **you** publish, then it appears in the directory. It does not go live on approval. OpenAI's own wording is that "review timelines may vary as OpenAI builds and scales the review process," so treat the date as unknown and do not build a launch announcement around a specific week.
+
+---
+
+## 2. Showcase Gallery (lowest effort, do it this week)
+
+Form: [openai.com/form/showcase-submission/](https://openai.com/form/showcase-submission/)
+
+OpenAI's Showcase Gallery takes submissions of apps, demos, and **open-source projects** built with OpenAI models, APIs, or Codex, to be featured as inspiration for the developer community. three.ws qualifies on all three counts: it is open source, it is a live app, and `api/chat.js`, `api/vision.js`, `api/concierge.js`, `api/agent-ask.js`, and the TTS lanes all call OpenAI in production.
+
+It is a plain web form with no repo gate, no CODEOWNERS review, and no merge conflict to lose to. Curation is still OpenAI's call, but the cost of asking is fifteen minutes. There is no reason this was not submitted before the Cookbook PR.
+
+---
+
+## 3. Cookbook: PR #2874 is fixable, but it is not the channel to bet on
+
+[PR #2874](https://github.com/openai/openai-cookbook/pull/2874), "Add example: build a self-correcting 3D collectible set with three.ws text-to-3D, function calling, and vision," opened 2026-07-21. 1,903 additions across a notebook, six images, an SVG diagram, `registry.yaml`, and `authors.yaml`.
+
+### Why it never landed
+
+Four independent reasons, and the first is decisive:
+
+1. **It has merge conflicts right now.** GitHub reports the PR as `CONFLICTING` / `DIRTY`. Nobody can merge it in this state regardless of how much they like it. The conflicts are in `registry.yaml` and `authors.yaml`, the two shared metadata files that **every** Cookbook PR touches, so any PR left open for weeks conflicts by default. This was self-inflicted by waiting rather than rebasing.
+
+2. **No OpenAI reviewer has ever formally reviewed it.** `reviewDecision` is `REVIEW_REQUIRED` with zero reviews. The repo's `.github/CODEOWNERS` is one line: `* @openai/developer-experience`. Every file needs Developer Experience team approval. That gate landed in PR #2920 on 2026-08-05, and a mandatory `docs-editor` review gate landed in PR #2862 on 2026-07-17, four days before we opened. We submitted into a review regime that had just tightened.
+
+3. **The `docs-editor` gate was not visibly satisfied.** `AGENTS.md` requires running the repo's `docs-editor` skill on every changed notebook markdown cell before merge, and resolving or explicitly documenting all remaining P0 and P1 findings in the PR. The thread resolves the Codex bot's findings thoroughly, and the bot's final verdict was clean, but the Codex bot is not the `docs-editor` gate. A reviewer scanning for that checklist does not find it.
+
+4. **The repo does not promise merges.** `CONTRIBUTING.md` says, verbatim: "Contributions are reviewed on a best-effort basis - we can't provide guarantees around when or if content contributions will be reviewed or merged." There are 165 open PRs and the oldest dates to 2024-07-06. Of the last 60 merges, 35 came from OpenAI staff accounts, and most of the external ones are affiliated partners shipping vendor integrations.
+
+### To revive it
+
+In order: rebase onto `main` and resolve `registry.yaml` and `authors.yaml` by hand, taking both sides; re-run `python .github/scripts/check_notebooks.py`; run the `docs-editor` skill over every markdown cell and post the P0/P1 resolution list as a comment so the gate is visibly met; then leave it alone.
+
+**One thing to stop doing.** The thread contains repeated @-mentions of individual OpenAI staff, an "I guess this will just fade into the abyss" comment, asking `@codex` to merge the PR three times, and a signoff of "Well i tried. GGWP OpenAI." That is a permanent public record on OpenAI's repo attached to our project name, and it is now the most visible three.ws artifact in OpenAI's GitHub org. It does not read as a maintainer's problem, it reads as ours. Rebase, post one clean status comment, and let the work carry it.
+
+---
+
+## 4. Customer stories: real, but not a form
+
+[openai.com/business/customer-stories/](https://openai.com/business/customer-stories/) and [openai.com/stories/](https://openai.com/stories/) are editorial, sales-led, and curated. There is no self-serve submission. The path is a relationship with OpenAI's go-to-market team, and the currency is usage numbers plus a named outcome. Park this until the plugin listing is live and producing install and call volume worth citing, then it becomes a natural follow-on ask rather than a cold one.
+
+The nearest self-serve adjacent surface is the [OpenAI Developer Community](https://community.openai.com) "Use cases and examples" category. No gate, indexed by search, and legitimate to post a build writeup to.
+
+---
+
+## 5. Grove: wrong stage, note it and move on
+
+[Apply to OpenAI Grove](https://openai.com/index/openai-grove/). Five-week program at OpenAI's SF HQ, roughly fifteen participants per cohort, $50k in API credits, in-person sessions in the first and last week. Cohort 2 ran 2026-01-22 to 2026-02-27.
+
+Explicitly aimed at "technical talent at the very start of their company-building journey" and "pre-idea individuals." three.ws is a shipping production platform with cloud marketplace listings, which is past the target stage. Worth watching for a cohort-3 call in case the criteria widen, but it is not a listing channel and should not consume effort.
+
+---
+
+## Non-OpenAI registries that actually merge
+
+Not OpenAI-owned, so they do not answer the original question, but they are where MCP discovery genuinely happens and unlike the Cookbook they merge in days:
+
+| Registry | Scale | Notes |
+|---|---|---|
+| [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | 89.6k stars | The reference MCP server list. The single highest-traffic MCP index. |
+| [hashgraph-online/awesome-codex-plugins](https://github.com/hashgraph-online/awesome-codex-plugins) | 818 stars | Curated Codex and ChatGPT plugin list. Directly downstream of the plugin directory. |
+| mcp.so | ~20k servers | Self-registration. |
+| smithery.ai, glama.ai/mcp | Large | Form or self-registration. |
+
+---
+
+## Order of operations
+
+1. Submit the **Showcase Gallery** form. Lowest cost, no gate, do it first.
+2. Start **developer or business identity verification** on the OpenAI Platform, because it is a review that blocks the plugin submission and nothing else depends on us.
+3. Audit tool annotations and x402 payment disclosure on the MCP server we intend to submit, then write the five positive and three negative test cases.
+4. Submit the **plugin**.
+5. **Rebase #2874**, post one clean status comment, stop pinging.
+6. List on the MCP registries above in parallel. They cost minutes and do not depend on any OpenAI review.
+
+---
+
+<a id="sec-306"></a>
> **Source:** `docs/openai-pr/00-START-HERE.md` · [↑ table of contents](#table-of-contents)
@@ -67658,13 +70339,13 @@ the specific gaps that would fail review or embarrass us in front of OpenAI.
| # | Brief | Priority | Blocks submit? |
| --- | --- | --- | --- |
-| 01 | [Resolve the orphaned studio-viewer widget](#sec-303) | P0 | Done 2026-07-18 (Option A: deleted) |
-| 02 | [Reconcile the served `.well-known` manifests with the zero-payment claim](#sec-304) | P0 | Yes (reviewer-discoverable crypto surface) |
-| 03 | [Make the `forge_free` tier story true everywhere](#sec-305) | P1 | Yes (submission doc contradicts code) |
-| 04 | [Close the test gaps on the ChatGPT-facing surface](#sec-306) | P1 | No, but required for "done" |
-| 05 | [Serve the custom-GPT OpenAPI and align legal URLs](#sec-307) | P1 | Partial |
-| 06 | [Fix doc accuracy and reconcile the tool-count story](#sec-308) | P1 | No |
-| 07 | [Final live verification and submit checklist](#sec-309) | P2 (runs last) | Yes (the actual go/no-go) |
+| 01 | [Resolve the orphaned studio-viewer widget](#sec-307) | P0 | Done 2026-07-18 (Option A: deleted) |
+| 02 | [Reconcile the served `.well-known` manifests with the zero-payment claim](#sec-308) | P0 | Yes (reviewer-discoverable crypto surface) |
+| 03 | [Make the `forge_free` tier story true everywhere](#sec-309) | P1 | Yes (submission doc contradicts code) |
+| 04 | [Close the test gaps on the ChatGPT-facing surface](#sec-310) | P1 | No, but required for "done" |
+| 05 | [Serve the custom-GPT OpenAPI and align legal URLs](#sec-311) | P1 | Partial |
+| 06 | [Fix doc accuracy and reconcile the tool-count story](#sec-312) | P1 | No |
+| 07 | [Final live verification and submit checklist](#sec-313) | P2 (runs last) | Yes (the actual go/no-go) |
Run 02 and 03 first of what remains (01 is already done; they change code and docs the later tasks depend on). 04, 05,
06 can run in parallel after. 07 runs last, after everything else is merged.
@@ -67712,7 +70393,7 @@ These are non-negotiable and OVERRIDE any default behavior:
---
-<a id="sec-303"></a>
+<a id="sec-307"></a>
> **Source:** `docs/openai-pr/01-orphan-widget-resolution.md` · [↑ table of contents](#table-of-contents)
@@ -67720,7 +70401,7 @@ These are non-negotiable and OVERRIDE any default behavior:
> **Resolved 2026-07-18 via Option A** in commit `19c379125` ("Refactor apps-sdk studio viewer and update OpenAI store submission"): `apps-sdk/studio-viewer/src.js`, `scripts/build-apps-sdk-viewer.mjs`, the `build:apps-sdk-viewer` entry in `package.json`, and both generated artifacts under `public/apps-sdk/` were deleted, and `apps-sdk/README.md` plus `ARCHITECTURE.md` were rewritten to point at the real widget (`api/_mcp-studio/component.js`, resource `ui://widget/three-studio-model.html`). `STRUCTURE.md` never referenced the orphan, so it needed no change. Kept as the record of the finding; the file links below point at the now-deleted paths and are left as plain code references.
-Read [`00-START-HERE.md`](#sec-302) first for the shared rules and the map.
+Read [`00-START-HERE.md`](#sec-306) first for the shared rules and the map.
## The problem (verified, with evidence)
@@ -67840,13 +70521,13 @@ fetches from** (three.ws, the R2 storage origin, and the CDN if used). Match wha
---
-<a id="sec-304"></a>
+<a id="sec-308"></a>
> **Source:** `docs/openai-pr/02-wellknown-manifest-conflict.md` · [↑ table of contents](#table-of-contents)
# Task 02 — Reconcile the served `.well-known` manifests with the zero-payment claim (P0)
-Read [`00-START-HERE.md`](#sec-302) first. **This task touches a manifest
+Read [`00-START-HERE.md`](#sec-306) first. **This task touches a manifest
that references crypto/x402. The commit gate in `00-START-HERE.md` rule 7 applies:
do the work, but do NOT commit anything that references a non-$THREE crypto project
without explicit owner approval. Flag it in your report instead.**
@@ -67961,13 +70642,13 @@ manifest layer. Recommended approach (implement this unless you find it wrong):
---
-<a id="sec-305"></a>
+<a id="sec-309"></a>
> **Source:** `docs/openai-pr/03-forge-free-tier-truth.md` · [↑ table of contents](#table-of-contents)
# Task 03 — Make the `forge_free` tier story true everywhere (P1, blocks submit)
-Read [`00-START-HERE.md`](#sec-302) first.
+Read [`00-START-HERE.md`](#sec-306) first.
## The problem (verified, with evidence)
@@ -68009,8 +70690,8 @@ metadata surface say "standard by default, higher tiers available on request."
description matches the code: standard default, `tier` param lets the caller ask
for draft or high, high may take longer or degrade under load.
2. Grep every doc for the "highest quality"/"high tier by default" claim and fix each:
- [`docs/mcp-studio.md`](#sec-273),
- [`docs/mcp-3d-studio.md`](#sec-270), the tool descriptions the
+ [`docs/mcp-studio.md`](#sec-274),
+ [`docs/mcp-3d-studio.md`](#sec-271), the tool descriptions the
MCP server itself returns in `tools/list` (check `tools.js` tool metadata strings),
and `apps-sdk/README.md`.
3. Make sure the tool's own `description` string returned to ChatGPT is accurate, so
@@ -68063,13 +70744,13 @@ and a doc claiming it works.
---
-<a id="sec-306"></a>
+<a id="sec-310"></a>
> **Source:** `docs/openai-pr/04-openai-surface-test-coverage.md` · [↑ table of contents](#table-of-contents)
# Task 04 — Close the test gaps on the ChatGPT-facing surface (P1)
-Read [`00-START-HERE.md`](#sec-302) first.
+Read [`00-START-HERE.md`](#sec-306) first.
## The problem
@@ -68149,13 +70830,13 @@ exported per the file). Use an existing JSON-schema/OpenAPI validator already in
---
-<a id="sec-307"></a>
+<a id="sec-311"></a>
> **Source:** `docs/openai-pr/05-custom-gpt-openapi-serving.md` · [↑ table of contents](#table-of-contents)
# Task 05 — Serve the custom-GPT OpenAPI and align legal URLs (P1)
-Read [`00-START-HERE.md`](#sec-302) first. Coordinate with Task 02 (the
+Read [`00-START-HERE.md`](#sec-306) first. Coordinate with Task 02 (the
served schema must be payment-free) and Task 04 (a contract test binds to it).
## The problem (verified, with evidence)
@@ -68238,13 +70919,13 @@ be normalized to one canonical form.
---
-<a id="sec-308"></a>
+<a id="sec-312"></a>
> **Source:** `docs/openai-pr/06-docs-accuracy-reconciliation.md` · [↑ table of contents](#table-of-contents)
# Task 06 — Fix doc accuracy and reconcile the tool-count story (P1)
-Read [`00-START-HERE.md`](#sec-302) first. This task cleans up the
+Read [`00-START-HERE.md`](#sec-306) first. This task cleans up the
documentation drift the audit found, EXCEPT the two docs owned by other tasks
(`apps-sdk/README.md` was Task 01, already landed on 2026-07-18; the `forge_free` tier
claim is Task 03). Do not fight those tasks for those specific edits; coordinate.
@@ -68320,13 +71001,13 @@ claim is Task 03). Do not fight those tasks for those specific edits; coordinate
---
-<a id="sec-309"></a>
+<a id="sec-313"></a>
> **Source:** `docs/openai-pr/07-final-verification-and-submit.md` · [↑ table of contents](#table-of-contents)
# Task 07 — Final live verification and submit checklist (P2, runs last)
-Read [`00-START-HERE.md`](#sec-302) first. **Run this only after tasks
+Read [`00-START-HERE.md`](#sec-306) first. **Run this only after tasks
01-06 are merged.** This is the go/no-go gate before the app is submitted to OpenAI.
## Purpose
@@ -68414,7 +71095,261 @@ go/no-go report. Do not submit; prepare so the human's final submit is one actio
---
-<a id="sec-310"></a>
+<a id="sec-314"></a>
+
+> **Source:** `docs/oracle-trading-mcp-plan.md` · [↑ table of contents](#table-of-contents)
+
+# Plan: ship Oracle and the autonomous trading agents as MCP servers
+
+**Status:** planned, not started. Written 2026-08-19.
+**Goal:** make [Oracle](https://three.ws/oracle) and the autonomous trading agents first-class,
+discoverable MCP servers, publish them to the official MCP registry
+(`registry.modelcontextprotocol.io`), document them, and announce them in one plain-language X post.
+
+This document is the build order. Everything in "What already exists" was verified against the
+tree and the live registry on 2026-08-19, so the plan starts from facts, not assumptions.
+
+---
+
+## Why this is worth doing
+
+Oracle is the best thing we run and almost nobody can find it from an agent client.
+
+Its four MCP tools (`oracle_top_plays`, `oracle_coin`, `oracle_arm_watch`, `oracle_watch_status`)
+live inside the main `https://three.ws/api/mcp` server, buried among 40+ avatar, model, animation,
+sign-language, memory, and market tools. In the registry that server is listed as
+"3D avatars, embeds, glTF tools, agent memory, and on-chain agent identity". An agent looking for
+a conviction signal on a new launch has no way to find it, and a human browsing the registry has
+no reason to click.
+
+The same is true of the autonomous side. `oracle_arm_watch` is the single most interesting write
+tool on the platform (it arms an agent to trade a live conviction stream inside a spend leash), and
+it is discoverable only by reading a 40-tool list on an avatar server.
+
+The fix is not new capability. It is **packaging**: two focused servers, named for what they do,
+listed under their own registry entries.
+
+---
+
+## What already exists (verified 2026-08-19)
+
+### Oracle
+
+| Layer | Location | State |
+|---|---|---|
+| Conviction engine | `api/_lib/oracle/` + `conviction-model.json` | Live, fitted model, AUC 0.879 on holdout |
+| Public API | `api/oracle/*.js` (26 endpoints) | Live: `feed`, `coin`, `signal`, `stats`, `backtest`, `calibration`, `leaderboard`, `wins`, `movers`, `categories`, `search`, `history`, `market`, `social`, `trades`, `wallet`, `watch`, `agent-stats`, `action-stream`, `activity`, `follow`, `batch`, `stream`, and more |
+| Pages | `/oracle`, `/oracle/docs`, `/oracle/arm` (in `data/pages.json`) | Live |
+| Reference doc | `docs/oracle.md` | Complete, long-form |
+| MCP tools | `api/_mcp/tools/oracle.js`, 4 tools | Live, but only inside the main server |
+| Dedicated MCP server | none | **This is the gap** |
+
+### Autonomous trading agents
+
+| Surface | Location | Registry state |
+|---|---|---|
+| Sniper engine (library + CLI + MCP + x402 API) | `packages/agent-sniper`, `workers/agent-sniper` | `io.github.nirholas/agent-sniper` @ 0.1.5 published; local `server.json` is 0.1.6, so a bump is pending |
+| Autopilot control plane | `packages/autopilot-mcp` | `io.github.nirholas/autopilot-mcp` @ 0.2.0 published |
+| Copy-trade follows | `packages/copy-mcp` | published @ 0.1.1 |
+| Signal marketplace | `packages/signals-mcp` | published @ 0.1.1 |
+| Portfolio + PnL | `packages/portfolio-mcp` | published @ 0.1.1 |
+| Market intel | `packages/intel-mcp`, `packages/kol-mcp` | published |
+| Oracle-armed agent loop | `api/oracle/watch.js`, `api/oracle/action-stream.js`, `api/oracle/agent-stats.js` | **No dedicated server. Only the two tools inside `/api/mcp`.** |
+
+61 distinct servers are already published under the `io.github.nirholas` namespace, so the
+publishing path is proven and boring. `scripts/publish-mcp-servers.mjs` (`npm run publish:mcp`)
+handles npm plus registry, idempotently, and skips anything already at the target version.
+
+### The publishing machinery (already built, do not rebuild)
+
+- `scripts/publish-mcp-servers.mjs`: npm publish, then registry publish, per server. Auth resolves
+ `MCP_REGISTRY_TOKEN`, then the owner's GitHub PAT from git config or `~/.git-credentials`, then
+ `GITHUB_TOKEN`.
+- `npm run audit:mcp` / `audit:mcp-golden` / `audit:mcp-safety` / `audit:mcp-catalog`: manifest,
+ golden-transcript, safety-annotation, and catalog checks. All four are in `npm run gate`.
+- `npm run smoke:mcp`: hits the hosted remotes for real.
+- `public/.well-known/mcp.json`: the hand-maintained hosted-server directory (7 entries today).
+- `public/mcp-catalog.json` + `/mcp-tools` page: the human-facing catalog, built by
+ `scripts/build-mcp-catalog.mjs`.
+
+---
+
+## The plan
+
+Five phases. Phases 1 and 2 are independent and can run in parallel; 3 depends on both; 4 and 5
+close it out.
+
+### Phase 1: `@three-ws/oracle-mcp` and the hosted Oracle remote
+
+Two faces of one server, mirroring the pattern already used for 3D Studio
+(`packages/*` stdio package plus `api/mcp-3d.js` remote plus `server-3d.json`).
+
+**1a. Hosted remote: `api/mcp-oracle.js` + `server-oracle.json`**
+
+Copy the structure of `api/mcp-3d.js` exactly: Streamable HTTP, shared OAuth/x402 plumbing from
+`api/_mcp/auth.js` and `api/_mcp/payments.js`, per-IP rate limits, SSE on GET, terminate on DELETE.
+Registry name `io.github.nirholas/threews-oracle`, URL `https://three.ws/api/mcp-oracle`.
+
+Route it in `vercel.json` (both the handler entry and the
+`/api/mcp-oracle/.well-known/oauth-protected-resource` route, matching the `/api/mcp` precedent at
+`vercel.json:525`), and add the entry to `public/.well-known/mcp.json`.
+
+**1b. stdio package: `packages/oracle-mcp`**
+
+Read-only, public, no key, no signer, no payment, over the live public API. This is the one people
+will actually install, so it has to be free and instant. Model it on `packages/intel-mcp`, which is
+already exactly this shape.
+
+**Tool surface (both faces).** The four existing tools stay, and the rest are thin wrappers over
+endpoints that are already live and public:
+
+| Tool | Backing endpoint | Auth |
+|---|---|---|
+| `oracle_getting_started` | local, static | free |
+| `oracle_top_plays` | `/api/oracle/signal` | free |
+| `oracle_coin` | `/api/oracle/coin`, `/api/oracle/signal?mint=` | free |
+| `oracle_feed` | `/api/oracle/feed` | free |
+| `oracle_search` | `/api/oracle/search` | free |
+| `oracle_movers` | `/api/oracle/movers` | free |
+| `oracle_wins` | `/api/oracle/wins` | free |
+| `oracle_backtest` | `/api/oracle/backtest` | free |
+| `oracle_calibration` | `/api/oracle/calibration` | free |
+| `oracle_leaderboard` | `/api/oracle/leaderboard` | free |
+| `oracle_wallet` | `/api/oracle/wallet` | free |
+| `oracle_stats` | `/api/oracle/stats` | free |
+| `oracle_arm_watch` | `POST /api/oracle/watch` | account-scoped (hosted remote only) |
+| `oracle_watch_status` | `GET /api/oracle/watch` | account-scoped (hosted remote only) |
+
+The two write tools ship on the hosted remote only. The stdio package advertises them as
+"available on the hosted server" in its getting-started text rather than shipping a half-wired
+auth path locally.
+
+**Honesty requirements, non-negotiable, already enforced by the existing tests in
+`tests/api/mcp-oracle-tools.test.js`:** a degraded feed or intel store reports as transient, never
+as an empty market, and an unknown coin is distinguished from an outage. Any new tool inherits
+that rule and gets a case in that test file.
+
+**Backwards compatibility:** the four tools stay in the main `/api/mcp` catalog. Nothing that works
+today stops working. `api/_mcp/tools/oracle.js` becomes the shared definition both catalogs import.
+
+### Phase 2: `@three-ws/agent-trader-mcp`, the autonomous trading control plane
+
+One server that answers "arm my agent on Oracle, then show me what it did and let me stop it."
+Today that story is split across `oracle_arm_watch`, the sniper package, autopilot, and the
+portfolio server, so no single entry in the registry tells it.
+
+Registry name `io.github.nirholas/threews-agent-trader`, npm `@three-ws/agent-trader-mcp`, stdio,
+authenticated with a three.ws API key. Model it on `packages/autopilot-mcp`, which already has the
+right posture for a write-heavy, real-money server.
+
+| Tool | Backing surface | Kind |
+|---|---|---|
+| `trader_getting_started` | local, static | free |
+| `agent_arm` | `POST /api/oracle/watch` | write, guarded |
+| `agent_disarm` | `POST /api/oracle/watch` (`armed:false`) | write, the kill switch |
+| `agent_status` | `GET /api/oracle/watch` | read |
+| `agent_actions` | `/api/oracle/action-stream`, `/api/oracle/activity` | read |
+| `agent_performance` | `/api/oracle/agent-stats` | read |
+| `agent_positions` | portfolio API | read |
+| `agent_guardrails` | agent guards / spend-envelope API | write, guarded |
+
+**Safety posture, copied from `packages/autopilot-mcp` because it is correct:**
+
+- `mode` defaults to `simulate`. Live spend is opt-in, per call, never sticky by accident.
+- Every boundary (scopes, per-trade SOL, daily SOL cap, max open positions) is enforced
+ server-side. The MCP server cannot widen a leash the backend refuses.
+- `agent_disarm` is documented as the kill switch and must work with only an agent id, no other
+ arguments, because that is what someone types when something is going wrong.
+- The `README` and `server.json` description both say, in the first two lines, that this server can
+ move real SOL.
+- Arming live still routes through the platform's existing owner-confirmation path. This server
+ does not become a way around the spend gate in `CLAUDE.md`.
+
+### Phase 3: publish to the registry
+
+Nothing new to build here. In order:
+
+```bash
+npm run audit:mcp # manifest validation
+npm run audit:mcp-safety # tool annotation / safety audit
+npm run audit:mcp-golden # golden transcripts
+npm run audit:mcp-catalog # catalog is in sync
+npm run test:mcp # every MCP server's own tests
+npm run publish:mcp:dry # report exactly what would publish, publish nothing
+npm run publish:mcp # npm, then registry, idempotent
+npm run smoke:mcp # hit the hosted remotes for real
+```
+
+Also in this phase, because they are one-line fixes that are currently drifted:
+
+- Bump `packages/agent-sniper` to publish 0.1.6 (registry has 0.1.5, the tree has 0.1.6).
+- Add both new remotes to `public/.well-known/mcp.json` (7 entries today, 8 after Phase 1).
+- Add both new server keys to the `SERVERS` array in `scripts/publish-mcp-servers.mjs`. A server
+ that is not in that array is invisible to the publisher, which is the single easiest way for
+ this whole plan to silently ship nothing.
+
+Verify after publishing:
+
+```bash
+curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=threews-oracle" | jq '.servers[].server.name'
+```
+
+### Phase 4: documentation
+
+Per the documentation rules in `CLAUDE.md`, all of these apply and none are optional:
+
+- `packages/oracle-mcp/README.md` and `packages/agent-trader-mcp/README.md`: what it does, install,
+ full tool table, one runnable example each. Package README coverage is currently 100% and this
+ plan must not be what breaks it.
+- `docs/mcp.md`: update the server count (it currently says 44) and add both servers to the hosted
+ and install-and-run lists.
+- `docs/oracle.md`: expand the existing "the MCP path" section into a real quickstart with the new
+ server name and a copy-pasteable client config.
+- `docs/agent-trading-mcp.md`: new. The autonomous trading story end to end, linked from
+ `docs/start-here.md`.
+- `STRUCTURE.md`: rows for both new package directories.
+- `data/pages.json`: only if a new public page lands. No new page is planned.
+- `data/changelog.json`: one entry, tags `feature` and `sdk`. Holder-readable, no commit jargon.
+ Something like "Oracle is now its own MCP server: any AI agent can pull live conviction scores,
+ and arm a trading agent, without touching the website."
+
+### Phase 5: the X post
+
+Draft lives at [`docs/oracle-trading-mcp-x-post.md`](#sec-530). Written before
+the work ships so the announcement shapes the scope rather than the reverse: if a claim in that
+post is not true when the phases are done, the phases are not done.
+
+Post it only after `npm run smoke:mcp` passes against the live remotes and both registry entries
+resolve. Announcing an MCP server nobody can connect to is the one failure mode that costs more
+than shipping late.
+
+---
+
+## Definition of done
+
+- [ ] `https://three.ws/api/mcp-oracle` responds to `initialize` and `tools/list` unauthenticated.
+- [ ] `npx @three-ws/oracle-mcp` connects from a clean machine with no key and returns a live score.
+- [ ] `npx @three-ws/agent-trader-mcp` arms an agent in simulate mode and disarms it.
+- [ ] Both servers resolve in `registry.modelcontextprotocol.io`.
+- [ ] `npm run gate` passes (all four MCP audits are inside it).
+- [ ] `npm run smoke:mcp` passes.
+- [ ] Every doc in Phase 4 is written, and `npm run audit:docs` is clean.
+- [ ] The changelog entry is in and `npm run build:pages` accepts it.
+- [ ] The X post claims nothing that is not live.
+
+## Risks and how they get handled
+
+| Risk | Handling |
+|---|---|
+| Registry publish 403s on the wrong account | Known trap, documented in the publish script: the git PAT outranks `GITHUB_TOKEN` because a Codespace token can belong to a different account. If it 403s, check `npm whoami` and the PAT source before touching anything else. |
+| Tool sprawl makes the new servers as unfindable as the old one | Hard cap: Oracle ships at most 14 tools, agent-trader at most 8. A tool that does not earn its place in the getting-started text does not ship. |
+| Someone arms live spend from an MCP client by accident | `simulate` default, server-side leash, per-call opt-in, kill switch that takes one argument. Same posture as `packages/autopilot-mcp`. |
+| The X post outruns the deploy | Post gated on `smoke:mcp` plus both registry lookups resolving. |
+| The main `/api/mcp` server loses the Oracle tools in the refactor | The four tool definitions stay in `api/_mcp/tools/oracle.js` and both catalogs import them. `tests/api/mcp-oracle-tools.test.js` already covers them and must stay green. |
+
+---
+
+<a id="sec-315"></a>
> **Source:** `docs/oracle.md` · [↑ table of contents](#table-of-contents)
@@ -68818,7 +71753,7 @@ The more data we watch, the sharper every score. Oracle is live now.
---
-<a id="sec-311"></a>
+<a id="sec-316"></a>
> **Source:** `docs/overlay-audit.md` · [↑ table of contents](#table-of-contents)
@@ -68950,17 +71885,46 @@ If the corner stack has not booted yet when your widget mounts, listen once for
`tws-corner-stack:ready` and claim then. Load order between these modules is not
guaranteed.
+### The page's own bottom chrome
+
+Reservations only cover widgets that know the stack exists. They do nothing for
+the chrome a *page* owns: the `/app` chat composer and its action row, a
+viewer's toolbar, an editor's dock. Nobody declares those, and on a phone the
+helper widgets used to sit right on them, so the language control rendered
+inside the "Ask the agent…" field and the Getting started pill covered the save
+button.
+
+The stack measures those instead of waiting to be told. On every resize, DOM
+change and orientation change (throttled), it probes the bottom band of the
+viewport with `elementsFromPoint`, keeps the hits that resolve to a
+bottom-anchored `fixed`/`sticky` box which is not part of the stack, and lifts
+itself above the tallest one via `--tws-corner-dock`. Docks that stack (a bar
+under a composer) are climbed one band at a time, and the lift is capped at 45%
+of the viewport height so a misdetection can never park the stack mid-screen.
+
+Nothing to wire up: a page that grows a bottom dock is handled the moment it
+renders one. A fixed element that should be ignored (a decorative bar the stack
+may sit over) opts out with `data-corner-ignore`.
+
+```html
+<div class="my-decorative-bar" data-corner-ignore>…</div>
+```
+
+`window.twsCornerStack.remeasure()` forces the measurement immediately, which is
+only worth calling from a test.
+
## Related
- [`public/corner-stack.js`](../public/corner-stack.js): the shared container and the reservation API
- [`tests/corner-stack.test.js`](../tests/corner-stack.test.js): the contract, exercised in JSDOM
+- [`tests/e2e/mobile-helper-overlays.spec.js`](../tests/e2e/mobile-helper-overlays.spec.js): the phone-width geometry, measured in a real browser
- `npm run audit:mobile-touch`: touch-target sizes, the other half of "can I actually hit this"
- `npm run audit:a11y`: keyboard and screen-reader coverage on the top pages
- `npm run snapshot`: the daily full-page visual record of every route
---
-<a id="sec-312"></a>
+<a id="sec-317"></a>
> **Source:** `docs/package-extraction.md` · [↑ table of contents](#table-of-contents)
@@ -69089,7 +72053,7 @@ part of the extraction itself: extract and publish first, swap the import later.
---
-<a id="sec-313"></a>
+<a id="sec-318"></a>
> **Source:** `docs/partners.md` · [↑ table of contents](#table-of-contents)
@@ -69097,7 +72061,7 @@ part of the extraction itself: extract and publish first, swap the import later.
`three.ws/partners` is the public map of the cloud, AI, hardware, infrastructure, and media programmes three.ws takes part in. This doc is the developer-facing companion to that page: for each surface it says what the integration actually **is**, at the status the page and the per-partner docs claim, and links the doc that goes deeper.
-Page source: [`pages/partners.html`](../pages/partners.html). Partnership enquiries go to **[email protected]** (the page's "Become a partner" call to action). Press and brand requests go to **[email protected]**, covered in [Press kit](#sec-327).
+Page source: [`pages/partners.html`](../pages/partners.html). Partnership enquiries go to **[email protected]** (the page's "Become a partner" call to action). Press and brand requests go to **[email protected]**, covered in [Press kit](#sec-333).
**Read the status labels literally.** Each card carries a one-word tier chip that is a category, not a rank: Select Partner, Strategic, Cloud, Inception, Media, Infrastructure. Nothing on the page grants an endorsement, and several of the docs below carry explicit "this is not an endorsement" language that must survive any rewrite.
@@ -69107,14 +72071,14 @@ Page source: [`pages/partners.html`](../pages/partners.html). Partnership enquir
| Partner | Chip on the card | Card links to | Deeper docs |
|---|---|---|---|
-| OpenAI | Select Partner | `/openai` | [MCP 3D Studio (free)](#sec-273), [3D Studio (paid)](#sec-270), [Custom GPT config](#sec-136), [AR in ChatGPT](#sec-137), [Spatial MCP](#sec-389) |
-| IBM | Strategic | `/blog/three-ws-ibm-business-partner` | [IBM watsonx and Granite](#sec-249), [IBM Granite x402 MCP](#sec-248) |
-| Amazon Web Services | Cloud | `/aws` | [AWS Marketplace](#sec-122), [listing kit](#sec-121), [partner spotlight](#sec-123) |
+| OpenAI | Select Partner | `/openai` | [MCP 3D Studio (free)](#sec-274), [3D Studio (paid)](#sec-271), [Custom GPT config](#sec-138), [AR in ChatGPT](#sec-139), [Spatial MCP](#sec-395) |
+| IBM | Strategic | `/blog/three-ws-ibm-business-partner` | [IBM watsonx and Granite](#sec-250), [IBM Granite x402 MCP](#sec-249) |
+| Amazon Web Services | Cloud | `/aws` | [AWS Marketplace](#sec-123), [listing kit](#sec-122), [partner spotlight](#sec-124) |
| Google Cloud | Cloud | `/blog/three-ws-google-cloud-partnership` | [Production runbook](ops/gcp-production.md), [credits plan](ops/gcp-credits-plan.md), [model workers](ops/gcp-model-workers.md) |
-| Alibaba Cloud | Cloud | `/blog/three-ws-alibaba-cloud-partnership` | [Listings and distribution](#sec-264), [the model router](#sec-128) |
-| NVIDIA | Inception | `/nvidia` | [NVIDIA Inception](#sec-295), [NVIDIA models](#sec-296), [Nemotron spotlight](#sec-297) |
-| HackerNoon | Media | `/blog/three-ws-hackernoon-partnership` | [Syndication](#sec-396), [Listings and distribution](#sec-264) |
-| Quicknode | Infrastructure | `/blog/three-ws-quicknode-startup-program` | [Solana integration](#sec-388), [Listings and distribution](#sec-264) |
+| Alibaba Cloud | Cloud | `/blog/three-ws-alibaba-cloud-partnership` | [Listings and distribution](#sec-265), [the model router](#sec-130) |
+| NVIDIA | Inception | `/nvidia` | [NVIDIA Inception](#sec-296), [NVIDIA models](#sec-297), [Nemotron spotlight](#sec-299) |
+| HackerNoon | Media | `/blog/three-ws-hackernoon-partnership` | [Syndication](#sec-402), [Listings and distribution](#sec-265) |
+| Quicknode | Infrastructure | `/blog/three-ws-quicknode-startup-program` | [Solana integration](#sec-394), [Listings and distribution](#sec-265) |
The page's stat bar reads 8 partners, 22 chains, and an infinity glyph for scale. It is marked `aria-hidden` and is decorative framing, not a metric to quote.
@@ -69126,13 +72090,13 @@ The page's stat bar reads 8 partners, 22 chains, and an infinity glyph for scale
**What the integration is.**
-- **The keyless connector** at `https://three.ws/api/mcp-studio` is a free MCP server exposing only 3D generation tools: no account, no payment, no API key, no wallet, no token. That is the surface submitted to the ChatGPT App Directory. See [MCP 3D Studio](#sec-273).
-- **The paid sibling** at `https://three.ws/api/mcp-3d` is a separate server with rigging, animation, retexturing, and analysis, authenticated by OAuth 2.1 or paid per call over x402. It shares none of the keyless server's surface. See [3D Studio MCP](#sec-270).
-- **The custom GPT** in the GPT Store calls an Actions contract served from `/.well-known/3d-studio-openapi.yaml`. Its builder configuration is checked in, because the GPT itself is configured by hand: [Custom GPT config](#sec-136).
-- **AR handoff** works from any of these: every generation carries a place-in-your-room link, and the whole pipeline is public and keyless rather than ChatGPT-exclusive. See [AR in ChatGPT](#sec-137).
-- **Spatial MCP** is the open, CC0 response shape that makes a 3D scene a native MCP result instead of a URL in text. three.ws is the reference implementation; the shape is renderer-agnostic and carries no payment, wallet, or coin surface. See [Spatial MCP](#sec-389).
+- **The keyless connector** at `https://three.ws/api/mcp-studio` is a free MCP server exposing only 3D generation tools: no account, no payment, no API key, no wallet, no token. That is the surface submitted to the ChatGPT App Directory. See [MCP 3D Studio](#sec-274).
+- **The paid sibling** at `https://three.ws/api/mcp-3d` is a separate server with rigging, animation, retexturing, and analysis, authenticated by OAuth 2.1 or paid per call over x402. It shares none of the keyless server's surface. See [3D Studio MCP](#sec-271).
+- **The custom GPT** in the GPT Store calls an Actions contract served from `/.well-known/3d-studio-openapi.yaml`. Its builder configuration is checked in, because the GPT itself is configured by hand: [Custom GPT config](#sec-138).
+- **AR handoff** works from any of these: every generation carries a place-in-your-room link, and the whole pipeline is public and keyless rather than ChatGPT-exclusive. See [AR in ChatGPT](#sec-139).
+- **Spatial MCP** is the open, CC0 response shape that makes a 3D scene a native MCP result instead of a URL in text. three.ws is the reference implementation; the shape is renderer-agnostic and carries no payment, wallet, or coin surface. See [Spatial MCP](#sec-395).
-**Saying it correctly.** Write the status as "OpenAI Select Partner". three.ws is an independent member of the network at the Select tier: not an OpenAI product, and not endorsed by OpenAI beyond the partner designation. Badge rules, the required independence line, and every asset are in [`marketing/openai-select-partner/badge-usage.md`](../marketing/openai-select-partner/badge-usage.md); the graphics cleared for editorial use are in [Press kit](#sec-327). The pre-submission verification pack is [`docs/openai-pr/00-START-HERE.md`](#sec-302).
+**Saying it correctly.** Write the status as "OpenAI Select Partner". three.ws is an independent member of the network at the Select tier: not an OpenAI product, and not endorsed by OpenAI beyond the partner designation. Badge rules, the required independence line, and every asset are in [`marketing/openai-select-partner/badge-usage.md`](../marketing/openai-select-partner/badge-usage.md); the graphics cleared for editorial use are in [Press kit](#sec-333). The pre-submission verification pack is [`docs/openai-pr/00-START-HERE.md`](#sec-306).
---
@@ -69140,9 +72104,9 @@ The page's stat bar reads 8 partners, 22 chains, and an infinity glyph for scale
**What the page claims.** three.ws 3D agent identity and x402 payment rails integrate with IBM watsonx and IBM Granite. Agents run enterprise AI models while maintaining on-chain identity and executing real micropayments, all from a single agent profile. Card tags: watsonx.ai, Granite, x402, MCP.
-**What the integration is.** Agents can think on IBM Granite foundation models served through IBM watsonx.ai, using your own IBM Cloud credentials. On top of that runtime sit the Granite-backed API surfaces (avatar brain, Guardian trust layer, TimeSeries forecasting, digital twin, semantic discovery, vision) and an MCP server, all documented in [IBM watsonx and Granite](#sec-249). [IBM Granite x402 MCP](#sec-248) covers the pay-per-call path: an MCP client reaches Granite inference and settles per call in stablecoin from a wallet it already controls, with no IBM Cloud account of its own.
+**What the integration is.** Agents can think on IBM Granite foundation models served through IBM watsonx.ai, using your own IBM Cloud credentials. On top of that runtime sit the Granite-backed API surfaces (avatar brain, Guardian trust layer, TimeSeries forecasting, digital twin, semantic discovery, vision) and an MCP server, all documented in [IBM watsonx and Granite](#sec-250). [IBM Granite x402 MCP](#sec-249) covers the pay-per-call path: an MCP client reaches Granite inference and settles per call in stablecoin from a wallet it already controls, with no IBM Cloud account of its own.
-**The caveat that must not be dropped.** [`docs/ibm.md`](#sec-249) states it plainly: three.ws is an IBM Business Partner, but the public showcase is not the partnership. The `/api/ibm/*` tools are an independent set of developer tools built on IBM's publicly available Granite models. They are not official IBM partnership deliverables, not IBM products, and not endorsed by IBM. The formal partnership work is being built on the IBM platform and is not yet public. Never present the public demos as that work.
+**The caveat that must not be dropped.** [`docs/ibm.md`](#sec-250) states it plainly: three.ws is an IBM Business Partner, but the public showcase is not the partnership. The `/api/ibm/*` tools are an independent set of developer tools built on IBM's publicly available Granite models. They are not official IBM partnership deliverables, not IBM products, and not endorsed by IBM. The formal partnership work is being built on the IBM platform and is not yet public. Never present the public demos as that work.
Live product surfaces: `three.ws/ibm/hello` (the partnership page) and `three.ws/ibm/x402-demo` (the x402 live demo).
@@ -69152,16 +72116,16 @@ Live product surfaces: `three.ws/ibm/hello` (the partnership page) and `three.ws
**What the page claims.** Deployed on AWS infrastructure with Marketplace availability. Enterprises can provision three.ws agent capabilities directly through their existing AWS billing, with support for VPC deployment and IAM-integrated access control. Card tags: Marketplace, EC2, IAM. The card's link label reads "View on AWS Marketplace" and points at `/aws`.
-**What the integration is.** The AWS Marketplace SaaS contract is implemented and deployed: a fulfillment endpoint that exchanges the marketplace token for a customer identifier via `ResolveCustomer`, a signature-verified SNS webhook for subscribe and unsubscribe lifecycle events, account linking after the post-subscribe redirect, and daily metering plus entitlement checks. The subscription itself is a free front door: it links an AWS account to a three.ws account and issues an x402 access key, and usage is then paid per call in stablecoin over x402. AWS Marketplace does not meter or bill the usage. Code lives in `api/aws-marketplace/` and `api/_lib/aws-marketplace.js`; the reference is [AWS Marketplace](#sec-122).
+**What the integration is.** The AWS Marketplace SaaS contract is implemented and deployed: a fulfillment endpoint that exchanges the marketplace token for a customer identifier via `ResolveCustomer`, a signature-verified SNS webhook for subscribe and unsubscribe lifecycle events, account linking after the post-subscribe redirect, and daily metering plus entitlement checks. The subscription itself is a free front door: it links an AWS account to a three.ws account and issues an x402 access key, and usage is then paid per call in stablecoin over x402. AWS Marketplace does not meter or bill the usage. Code lives in `api/aws-marketplace/` and `api/_lib/aws-marketplace.js`; the reference is [AWS Marketplace](#sec-123).
**Status wording differs across surfaces, so quote the surface you are on.**
- The `/partners` card says "Marketplace availability".
- The `/aws` page badge says "AWS Partner, Software Path" and its hero says "Marketplace listing coming soon".
-- [`docs/listings.md`](#sec-264) records AWS Marketplace as Live and three.ws as an AWS Partner.
-- [`docs/aws-marketplace-listing-kit.md`](#sec-121) says the backend integration is built and deployed but the listing itself has not yet been created in the AWS Marketplace Management Portal.
+- [`docs/listings.md`](#sec-265) records AWS Marketplace as Live and three.ws as an AWS Partner.
+- [`docs/aws-marketplace-listing-kit.md`](#sec-122) says the backend integration is built and deployed but the listing itself has not yet been created in the AWS Marketplace Management Portal.
-Do not resolve that spread by picking the strongest claim. If you need one sentence, the safe one is the one the product page uses: three.ws is an AWS Partner, and the Marketplace listing is coming. Longer-form pieces written for AWS channels are [partner spotlight](#sec-123), [MCP agents](#sec-119), and [Marketplace metering in front of x402](#sec-118).
+Do not resolve that spread by picking the strongest claim. If you need one sentence, the safe one is the one the product page uses: three.ws is an AWS Partner, and the Marketplace listing is coming. Longer-form pieces written for AWS channels are [partner spotlight](#sec-124), [MCP agents](#sec-120), and [Marketplace metering in front of x402](#sec-119).
---
@@ -69171,7 +72135,7 @@ Do not resolve that spread by picking the strongest claim. If you need one sente
**What the integration is.** Production runs on Google Cloud: one Cloud Run service serves the static frontend, the route table, and every API handler, with the crons on Cloud Scheduler and the GPU model workers on their own services. Vertex AI provides the Gemini and image lanes. The operational detail is in [production runbook](ops/gcp-production.md), [fleet and quota plan](ops/gcp-credits-plan.md), and [model workers](ops/gcp-model-workers.md).
-**Programme status.** [`docs/listings.md`](#sec-264) records three.ws as a **member of Google Cloud for Web3 Startups**, with the programme backing compute and Vertex AI usage, and records Google Cloud Marketplace separately as **open to partnership** (no listing yet). The page card describes the technical dependency, not a marketplace listing; keep those two apart.
+**Programme status.** [`docs/listings.md`](#sec-265) records three.ws as a **member of Google Cloud for Web3 Startups**, with the programme backing compute and Vertex AI usage, and records Google Cloud Marketplace separately as **open to partnership** (no listing yet). The page card describes the technical dependency, not a marketplace listing; keep those two apart.
---
@@ -69179,9 +72143,9 @@ Do not resolve that spread by picking the strongest claim. If you need one sente
**What the page claims.** Alibaba Cloud extends three.ws into APAC markets with Qwen model integration and regional MCP server deployment. three.ws agents reach global audiences with low-latency inference close to users in Asia. Card tags: Qwen, MCP, APAC.
-**What the integration is.** Qwen models are first-class lanes in the platform's multi-model brain router (`/api/brain/chat`), reached through DashScope alongside the other providers, so an agent can be pointed at a Qwen model the same way it is pointed at any other. See [the agent brain](#sec-128) for the router and the model ids.
+**What the integration is.** Qwen models are first-class lanes in the platform's multi-model brain router (`/api/brain/chat`), reached through DashScope alongside the other providers, so an agent can be pointed at a Qwen model the same way it is pointed at any other. See [the agent brain](#sec-130) for the router and the model ids.
-**Listing status.** [`docs/listings.md`](#sec-264) records the Alibaba Cloud International Marketplace listing as **Live**, with a product listing, a storefront, and an editorial feature published on the Alibaba Cloud Marketplace blog. That doc holds the canonical links; treat it as the source of truth rather than restating URLs here.
+**Listing status.** [`docs/listings.md`](#sec-265) records the Alibaba Cloud International Marketplace listing as **Live**, with a product listing, a storefront, and an editorial feature published on the Alibaba Cloud Marketplace blog. That doc holds the canonical links; treat it as the source of truth rather than restating URLs here.
---
@@ -69191,10 +72155,10 @@ Do not resolve that spread by picking the strongest claim. If you need one sente
**What the integration is.** Two distinct things, and the docs keep them distinct:
-- **Inception membership**, accepted July 2026. [NVIDIA Inception](#sec-295) states what membership adds (GPU credits, hardware access, engineering support) and where it shows up in the product.
-- **The free hosted inference lane.** A large share of platform AI runs on NVIDIA-hosted models unlocked by a single `NVIDIA_API_KEY`, a rate-limited free tier with no per-model billing and no SLA, which is why the platform always keeps a fallback behind it. [NVIDIA models](#sec-296) is the canonical map of which model does what and where it is wired. Membership does not change that lane; it is how the platform scales past free-tier limits without giving up the free-first design.
+- **Inception membership**, accepted July 2026. [NVIDIA Inception](#sec-296) states what membership adds (GPU credits, hardware access, engineering support) and where it shows up in the product.
+- **The free hosted inference lane.** A large share of platform AI runs on NVIDIA-hosted models unlocked by a single `NVIDIA_API_KEY`, a rate-limited free tier with no per-model billing and no SLA, which is why the platform always keeps a fallback behind it. [NVIDIA models](#sec-297) is the canonical map of which model does what and where it is wired. Membership does not change that lane; it is how the platform scales past free-tier limits without giving up the free-first design.
-[Nemotron spotlight](#sec-297) is a published community piece on building the text-to-3D pipeline on NIM. It is a developer-blog showcase, not a partnership document.
+[Nemotron spotlight](#sec-299) is a published community piece on building the text-to-3D pipeline on NIM. It is a developer-blog showcase, not a partnership document.
---
@@ -69202,15 +72166,15 @@ Do not resolve that spread by picking the strongest claim. If you need one sente
**What the page claims.** A builder-focused publishing partnership: feature articles, tutorials, and developer guides for people shipping with AI, published to HackerNoon's developer audience. Card tags: Publishing, Developer content.
-**What the integration is.** Mechanical, and worth knowing if you write posts here: HackerNoon auto-imports from `https://three.ws/rss/announcements.xml`, polls roughly hourly, pulls every new item into the drafts queue, and publishes with canonical URLs pointing back to three.ws. There is no per-post action. Setup steps and the author-profile claim flow are in [Syndication](#sec-396); the listing row is in [Listings and distribution](#sec-264).
+**What the integration is.** Mechanical, and worth knowing if you write posts here: HackerNoon auto-imports from `https://three.ws/rss/announcements.xml`, polls roughly hourly, pulls every new item into the drafts queue, and publishes with canonical URLs pointing back to three.ws. There is no per-post action. Setup steps and the author-profile claim flow are in [Syndication](#sec-402); the listing row is in [Listings and distribution](#sec-265).
---
## Quicknode
-**What the page claims.** three.ws is a member of the Quicknode Startup Program with approved infrastructure credits. Quicknode's globally distributed RPC endpoints add capacity and redundancy to the chain access behind agent wallets, x402 settlement verification, and live Solana market data. Card tags: Solana RPC, Streams, Multi-chain. [`docs/listings.md`](#sec-264) records the programme as **accepted (2026-07)** with approved free infrastructure credits.
+**What the page claims.** three.ws is a member of the Quicknode Startup Program with approved infrastructure credits. Quicknode's globally distributed RPC endpoints add capacity and redundancy to the chain access behind agent wallets, x402 settlement verification, and live Solana market data. Card tags: Solana RPC, Streams, Multi-chain. [`docs/listings.md`](#sec-265) records the programme as **accepted (2026-07)** with approved free infrastructure credits.
-**What the integration is.** A rung in the Solana RPC failover chain, not the whole chain. Server-side calls build a chain across an explicit primary, keyed providers, operator-supplied fallbacks, keyless public endpoints, and a paid reserve tried last, rotating past anything rate-limited. [Solana integration](#sec-388) documents it, including the trap that matters operationally: never name the same endpoint as both the primary and the last-resort reserve, because the chain dedupes by URL and keeps the first occurrence, so the "reserve" silently absorbs all traffic.
+**What the integration is.** A rung in the Solana RPC failover chain, not the whole chain. Server-side calls build a chain across an explicit primary, keyed providers, operator-supplied fallbacks, keyless public endpoints, and a paid reserve tried last, rotating past anything rate-limited. [Solana integration](#sec-394) documents it, including the trap that matters operationally: never name the same endpoint as both the primary and the last-resort reserve, because the chain dedupes by URL and keeps the first occurrence, so the "reserve" silently absorbs all traffic.
---
@@ -69218,7 +72182,7 @@ Do not resolve that spread by picking the strongest claim. If you need one sente
Worth stating, because partner claims drift upward when nobody writes the boundary down:
-- **No Intel, Microsoft, or Oracle programme appears on `/partners`.** [`docs/listings.md`](#sec-264) records Microsoft Azure Marketplace as **on roadmap**. Third-party model or component names that appear in the stack (for example the image-to-3D backends listed in [3D Studio MCP](#sec-270)) are technical dependencies, not partnerships.
+- **No Intel, Microsoft, or Oracle programme appears on `/partners`.** [`docs/listings.md`](#sec-265) records Microsoft Azure Marketplace as **on roadmap**. Third-party model or component names that appear in the stack (for example the image-to-3D backends listed in [3D Studio MCP](#sec-271)) are technical dependencies, not partnerships.
- **No tier is claimed beyond the chips on the cards.** "Strategic", "Cloud", "Media", and "Infrastructure" are groupings three.ws chose for its own page. Only two named programme statuses come from the partner: OpenAI Select Partner, and NVIDIA Inception member.
- **No endorsement is claimed anywhere.** OpenAI, IBM, and NVIDIA all carry explicit independence language in their docs. Reproduce it.
@@ -69232,14 +72196,14 @@ The page closes with four reasons, useful as the short pitch when someone asks:
## Related
-- [Press kit](#sec-327): marks, announcement graphics, boilerplate, and the rules for all of it
-- [Listings and distribution](#sec-264): marketplaces, ecosystem directories, and media partners with per-listing status
-- [Integrations](#sec-253): the catalog of ways to put an agent on a site you do not control
-- [x402](#sec-519): the payment rail behind the agent-to-agent micropayments every partner surface references
+- [Press kit](#sec-333): marks, announcement graphics, boilerplate, and the rules for all of it
+- [Listings and distribution](#sec-265): marketplaces, ecosystem directories, and media partners with per-listing status
+- [Integrations](#sec-254): the catalog of ways to put an agent on a site you do not control
+- [x402](#sec-544): the payment rail behind the agent-to-agent micropayments every partner surface references
---
-<a id="sec-314"></a>
+<a id="sec-319"></a>
> **Source:** `docs/partners/sperax-proposal.md` · [↑ table of contents](#table-of-contents)
@@ -69287,7 +72251,7 @@ Both sides already ship for a living — this proposal only asks each of us to d
---
-<a id="sec-315"></a>
+<a id="sec-320"></a>
> **Source:** `docs/pay-skills-listing.md` · [↑ table of contents](#table-of-contents)
@@ -69388,7 +72352,7 @@ are supported.
---
-<a id="sec-316"></a>
+<a id="sec-321"></a>
> **Source:** `docs/payment-sessions.md` · [↑ table of contents](#table-of-contents)
@@ -69840,13 +72804,13 @@ curl -s $BASE/api/credits -H "$AUTH" | jq .balance_usd
## Related
-- [x402 Protocol](#sec-519): the challenge / verify / settle mechanics behind every paid call.
-- [x402 Buyer Client](#sec-511): paying x402 endpoints from your own wallet instead of a session.
-- [x402 Developer Tools](#sec-512): free echo / debug / receipt-verification tools for debugging a paid call.
+- [x402 Protocol](#sec-544): the challenge / verify / settle mechanics behind every paid call.
+- [x402 Buyer Client](#sec-536): paying x402 endpoints from your own wallet instead of a session.
+- [x402 Developer Tools](#sec-537): free echo / debug / receipt-verification tools for debugging a paid call.
---
-<a id="sec-317"></a>
+<a id="sec-322"></a>
> **Source:** `docs/permissions.md` · [↑ table of contents](#table-of-contents)
@@ -70244,15 +73208,15 @@ Set `SMOKE_SKIP_REVOKE=1` to skip the on-chain revocation step if the test walle
- [Architecture Overview](#sec-100)
- [Agent System](#sec-064)
-- [ERC-8004 Blockchain Identity](#sec-185)
-- [Skill System](#sec-381)
+- [ERC-8004 Blockchain Identity](#sec-188)
+- [Skill System](#sec-387)
- [EIP-7710](https://eips.ethereum.org/EIPS/eip-7710) — delegation envelope format
- [EIP-7715](https://eips.ethereum.org/EIPS/eip-7715) — `wallet_grantPermissions` JSON-RPC method
- [MetaMask Delegation Toolkit](https://docs.metamask.io/delegation-toolkit/)
---
-<a id="sec-318"></a>
+<a id="sec-323"></a>
> **Source:** `docs/persona-hub.md` · [↑ table of contents](#table-of-contents)
@@ -70649,7 +73613,7 @@ JWT claims:
---
-<a id="sec-319"></a>
+<a id="sec-324"></a>
> **Source:** `docs/plan-checkout.md` · [↑ table of contents](#table-of-contents)
@@ -70665,7 +73629,7 @@ three.ws has a self-serve paid tier. Upgrading to **Pro** (or Team / Enterprise)
Where to use it: the Pro card on [three.ws/pricing](https://three.ws/pricing) opens the checkout when you're signed in. Confirmed payments set `users.plan`, light up the Pro badge everywhere ([api/_lib/account-tier.js](../api/_lib/account-tier.js)), and grant 30 days per payment.
-This is separate from (and complementary to) [hold-to-access](#sec-237), which derives holder tiers from $THREE you *hold*; the plan checkout is $THREE you *spend*.
+This is separate from (and complementary to) [hold-to-access](#sec-238), which derives holder tiers from $THREE you *hold*; the plan checkout is $THREE you *spend*.
---
@@ -70778,7 +73742,7 @@ Plan prices live in [api/payments/_config.js](../api/payments/_config.js) (`PLAN
---
-<a id="sec-320"></a>
+<a id="sec-325"></a>
> **Source:** `docs/play-boot-performance.md` · [↑ table of contents](#table-of-contents)
@@ -70788,7 +73752,7 @@ Plan prices live in [api/payments/_config.js](../api/payments/_config.js) (`PLAN
That work is unavoidable. What *is* avoidable is paying for it at the wrong moment. This document records the boot-cost invariants that keep the first ten seconds fast, so a future change does not quietly undo one of them. Each section names the regression it prevents, because each of them actually shipped once and was measured on the live site.
-Related docs: [how /play stays safe, honest, and light](#sec-322), [architecture](#sec-100).
+Related docs: [how /play stays safe, honest, and light](#sec-327), [architecture](#sec-100).
## How to measure before you claim anything
@@ -70881,7 +73845,7 @@ Before shipping anything that touches `/play` boot:
---
-<a id="sec-321"></a>
+<a id="sec-326"></a>
> **Source:** `docs/play-forge-in-world.md` · [↑ table of contents](#table-of-contents)
@@ -70983,12 +73947,12 @@ layer, ownership checks, and the per-player object cap all apply without modific
## Related
- [3D asset pipeline](#sec-002): what the forge lanes are and how they differ
-- [In-game economy](#sec-251): the rest of what you can do inside a `/play` world
+- [In-game economy](#sec-252): the rest of what you can do inside a `/play` world
- [/forge](https://three.ws/forge): the full studio, with paid tiers, rigging, and game-ready export
---
-<a id="sec-322"></a>
+<a id="sec-327"></a>
> **Source:** `docs/play-hardening.md` · [↑ table of contents](#table-of-contents)
@@ -71004,7 +73968,7 @@ It is also the surface with the least trusted input. Its entry URL is a link str
Every part of that URL, every display name a peer picks, and every field of the pump.fun coin metadata is text an attacker chose. This document records the invariants that keep the world safe and honest, so that a future change does not quietly undo one of them. Each section names the failure it prevents, because each of these actually shipped once.
-Related docs: [in-game economy](#sec-251), [architecture](#sec-100), [security](#sec-370).
+Related docs: [in-game economy](#sec-252), [architecture](#sec-100), [security](#sec-375).
---
@@ -71254,7 +74218,7 @@ The mobile harness is the one that catches memory regressions. It reports total
---
-<a id="sec-323"></a>
+<a id="sec-328"></a>
> **Source:** `docs/play-live-events.md` · [↑ table of contents](#table-of-contents)
@@ -71325,7 +74289,7 @@ from the shape below:
| `startsAt` / `endsAt` | ISO-8601 UTC. A missing or inverted `endsAt` defaults to six hours after the start. |
| `agenda[].atMin` | Minutes after `startsAt`. Order does not matter; segments are sorted. Invalid or untitled entries are dropped rather than breaking the event. |
| `agenda[].icon` | One emoji. Used on the segment row and its moment banner. |
-| `souvenir.cosmeticId` | Optional. A free commemorative wearable granted once to everyone who joins the world named by `link` while the event is live, kept forever, never granted again after `endsAt`. Must be a `tier: 'event'` cosmetic; anything else grants nothing. See [Event souvenirs](#sec-213). |
+| `souvenir.cosmeticId` | Optional. A free commemorative wearable granted once to everyone who joins the world named by `link` while the event is live, kept forever, never granted again after `endsAt`. Must be a `tier: 'event'` cosmetic; anything else grants nothing. See [Event souvenirs](#sec-216). |
`id`, `agenda`, and `tagline` are optional: an event with none of them still runs
its countdown, its go-live moment, and its fireworks.
@@ -71424,7 +74388,119 @@ Point it at another origin with `--base https://three.ws`.
---
-<a id="sec-324"></a>
+<a id="sec-329"></a>
+
+> **Source:** `docs/play-vehicles.md` · [↑ table of contents](#table-of-contents)
+
+# Cars in `/play`: the Trench Car, ambient traffic, and the drivable fleet
+
+Every coin world in [`/play`](https://three.ws/play) has cars in it. They are not scenery
+you walk past: the same car that drives by you on the ring road is the car parked at the
+plaza that you can get into and drive across town.
+
+The car is the **Trench Car**, a community model published to the three.ws
+avatar gallery ([avatar `e702d59a-d29f-4f21-af8a-6400dd1a2c6f`](https://three.ws/avatars/e702d59a-d29f-4f21-af8a-6400dd1a2c6f),
+slug `trench-car`), and it is the *only* car in the world: it is what ambient traffic drives
+in every town (frontier ones included), what is parked in all six vehicle bays, and what an
+unknown vehicle type falls back to. There is no fleet of mismatched shapes; four procedural
+box cars (coupe, sedan, pickup, buggy) used to share the road with it and were retired on
+2026-08-17.
+
+## Driving one
+
+1. Walk up to a parked car. Inside 3.4 m a prompt appears over it: **Drive the Trench Car**.
+2. Press `F` to take the wheel. On a touch device, tap the car itself.
+3. `W` / `S` are throttle and brake (brake from a standstill reverses), `A` / `D` steer,
+ `Space` is the handbrake. On touch you get an on-screen pedal and steering cluster
+ instead, and the walking joystick steps aside while you drive.
+4. The speedometer sits bottom-right and reads real km/h off the simulation.
+5. Press `F` again (or tap **Exit**) to step out. You are dropped beside the driver's door.
+
+While you are driving, your avatar sits in the car's seat in a seated pose, and every other
+player in the world sees you sitting in it, because the server carries your position and
+your `drive` motion with the car.
+
+Roll it onto its roof and it rights itself after a couple of seconds. Drive it at a
+pedestrian and they are shoved out of the way rather than driven through.
+
+### Driving jobs
+
+Two of the world's jobs are real driving missions: `cross-town-delivery` (North depot to
+South) and `east-west-express`. Both legs only complete if you arrive **in a car**, checked
+server-side against the authoritative driver map, so walking to a depot never counts. The
+depots sit on the avenue vehicle spawns, so a car is always parked at the start of the run.
+
+## How a car is put together
+
+A car is three things that all have to agree, or it looks wrong or drives wrong:
+
+| Piece | Where it lives | What it owns |
+|---|---|---|
+| Handling spec | [multiplayer/src/vehicles.js](../multiplayer/src/vehicles.js) | Mass, forces, top speed, dimensions, wheel geometry, suspension, seat. Shared by client and server, so "feels fast" and "rejected as cheating" can never drift apart. |
+| Physics chassis | [src/physics/physics-world.js](../src/physics/physics-world.js) | A Rapier raycast vehicle controller built from that spec. |
+| The mesh | [src/game/vehicle-mesh.js](../src/game/vehicle-mesh.js), [src/game/vehicle-model.js](../src/game/vehicle-model.js) | What you look at: the GLB, plus the procedural stand-in silhouette that holds its place while the model downloads. |
+
+The mesh group's origin is the **chassis centre**, `+z` is forward, and the four wheels are
+pivot/spinner pairs the vehicle controller writes suspension, steering and roll into every
+frame. A GLB is authored with its contact patch on the road, so it is dropped into chassis
+space by `vehicleRestHeight()`.
+
+A car never blocks the world on a download. `buildVehicleMesh()` returns its
+procedural stand-in immediately and swaps the GLB body and wheels into the *same* group and
+the *same* wheel pivots when the model lands, so a car that upgrades mid-drive keeps its
+physics, its camera and its driver. If the model cannot be fetched at all, the stand-in
+stays and the car is still completely drivable.
+
+One template is downloaded and parsed per model for the whole world. Every car clones it,
+sharing geometry and textures, and clones only its own brake-light material so one car
+braking does not light up the rest.
+
+## Staging the model
+
+The gallery master is a 16 MB studio model: two oversized textures and 263k triangles. That
+is unusable on a page every visitor loads, so it is staged into the repo:
+
+```bash
+npm run build:trench-car # fetch from the avatar API, optimize, write public/vehicles/
+npm run build:trench-car -- --dry # report the sizes, write nothing
+```
+
+[scripts/build-trench-car.mjs](../scripts/build-trench-car.mjs) pulls the master through the
+live avatar API (so a re-upload of the same avatar re-stages cleanly, with no storage URL
+hardcoded anywhere), decimates the geometry to a game budget, caps the body wrap at 2048px
+and the metal-roughness map at 1024px, and writes
+`public/vehicles/trench-car.glb` at about 1.4 MB and 99k triangles.
+
+## Adding another car model
+
+1. Publish or pick a GLB whose wheels are four separate nodes named `wheel…` and whose body
+ sits with its contact patch at `y = 0`, facing `+z`. Stage it into `public/vehicles/`.
+2. Add a type to `VEHICLE_TYPES` with a `model` key, and measure `dims`, `wheel` and
+ `suspension` off the mesh. `dims.h` is road-to-roof, not the body's own bounding box.
+ Nothing spawns it until a `VEHICLE_SPAWNS` bay names it, and
+ `tests/vehicles-trench-car.test.js` pins the fleet as Trench-Car-only, so a second car in
+ the world is a deliberate change to that test, not an accident.
+3. Check the clearance rule: the chassis collider's underside sits `1.3 * (h / 2)` below the
+ body origin, so `vehicleRestHeight()` has to clear it. Too little and the hull rests on
+ the road and its own friction pins the car, whatever the engine force says.
+4. Map the model key to its URL in `MODEL_URLS` in
+ [src/game/vehicle-mesh.js](../src/game/vehicle-mesh.js).
+5. Prove it, do not eyeball it:
+ ```bash
+ node scripts/verify-w02-physics-core.mjs <type> # real Rapier: does it accelerate, steer, stop?
+ npx vitest run tests/vehicles-trench-car.test.js # spec vs. the staged asset
+ npx playwright test tests/e2e/play-vehicles.spec.js
+ ```
+
+## Related
+
+- [`/play` NPCs and world life](../src/game/npc/ambient-life.js) drives the ambient lane.
+- [The in-game economy](#sec-252) covers what you earn on those delivery runs.
+- [`/play` safety and lifecycle invariants](#sec-327).
+
+---
+
+<a id="sec-330"></a>
> **Source:** `docs/popular-3d-github-repos.md` · [↑ table of contents](#table-of-contents)
@@ -71687,7 +74763,7 @@ Apply a 3D-signal regex filter over `description + topics` and a denylist of non
---
-<a id="sec-325"></a>
+<a id="sec-331"></a>
> **Source:** `docs/portfolio.md` · [↑ table of contents](#table-of-contents)
@@ -71731,7 +74807,7 @@ GET /api/crypto/portfolio?address=<wallet>&chain=solana|ethereum
```
which builds on the same balance layer as
-[`/api/crypto/wallet`](#sec-166) ([`api/_lib/balances.js`](../api/_lib/balances.js)):
+[`/api/crypto/wallet`](#sec-169) ([`api/_lib/balances.js`](../api/_lib/balances.js)):
- **Solana** (fully keyless): Helius DAS when a key is configured, public RPC
otherwise; prices from Jupiter Lite with a pump.fun bonding-curve fallback;
@@ -71790,15 +74866,15 @@ responses are cached for about a minute per wallet.
## Related surfaces
-- [`/wallet`](#sec-482): your own custodial three.ws wallet.
+- [`/wallet`](#sec-488): your own custodial three.ws wallet.
- `/agent-wallet`: the agent wallet hub, whose Portfolio tab covers an agent's
holdings with FIFO cost basis and PnL attribution.
-- [`/api/crypto/wallet`](#sec-166): the raw balances endpoint this page
+- [`/api/crypto/wallet`](#sec-169): the raw balances endpoint this page
builds on, for agents and scripts.
---
-<a id="sec-326"></a>
+<a id="sec-332"></a>
> **Source:** `docs/premium.md` · [↑ table of contents](#table-of-contents)
@@ -71900,9 +74976,16 @@ at [/dashboard/billing](/dashboard/billing).
The dashboards ride two raw endpoints you can also call directly:
`POST /api/premium/keys` with `{ action: "rotate" | "revoke", id }`
-(session + CSRF; rotate returns the fresh plaintext exactly once) and
+(session + CSRF; rotate returns the fresh plaintext exactly once, and the
+route is metered at 20 key operations per account per hour) and
`GET /api/premium/mine` (session-authenticated; your passes and keys,
-including passes bought directly by your linked Solana wallet).
+including passes bought directly by any Solana wallet linked to your account).
+
+"Linked" means a wallet you have signed in with: connecting a Solana wallet
+once (SIWS) attaches it to the account, and every pass that wallet ever bought,
+including ones bought before you had an account, shows up on the billing page
+from then on. Nothing links by typing an address, so nobody else's purchases
+can be claimed.
## Rules and edge cases
@@ -71926,7 +75009,7 @@ tiers that remain free (news feed, digest, archive stats/trending).
---
-<a id="sec-327"></a>
+<a id="sec-333"></a>
> **Source:** `docs/press-kit.md` · [↑ table of contents](#table-of-contents)
@@ -72081,7 +75164,7 @@ Two rules that matter if you are laying out a story or a slide:
The two extra OpenAI files inside the zip need more care than the two above. The short-phrasing card exists for one specific post and is not the general-purpose announcement graphic. The two-mark lockup uses OpenAI's logomark rather than the partner badge, which their brand guidelines govern separately, so a co-branded lockup is normally something a partner clears first. The full rules for every OpenAI asset in this repo are in [`marketing/openai-select-partner/badge-usage.md`](../marketing/openai-select-partner/badge-usage.md), with the announcement pack itself at [`marketing/openai-select-partner/README.md`](../marketing/openai-select-partner/README.md).
-For the wider programme list and how to describe each one, see [Partner ecosystem](#sec-313).
+For the wider programme list and how to describe each one, see [Partner ecosystem](#sec-318).
---
@@ -72099,14 +75182,14 @@ Use that inbox for anything the page does not cover: a format that is not here (
## Related
-- [Partner ecosystem](#sec-313): every programme three.ws is in, at the status it actually claims
-- [Listings and distribution](#sec-264): marketplaces, directories, and media partners, with per-listing status
+- [Partner ecosystem](#sec-318): every programme three.ws is in, at the status it actually claims
+- [Listings and distribution](#sec-265): marketplaces, directories, and media partners, with per-listing status
- [Brand asset renderer](../marketing/brand/README.md): where the marks come from and how to regenerate them
- [Marketing campaigns](../marketing/README.md): announcement packs, social copy, and finished graphics
---
-<a id="sec-328"></a>
+<a id="sec-334"></a>
> **Source:** `docs/procedural-animation.md` · [↑ table of contents](#table-of-contents)
@@ -72277,12 +75360,12 @@ If you hit a rig whose bones do not resolve, the fix is a bone-name mapping in [
## Related
- [animations.md](#sec-093) — the pre-baked clip library these layers run on top of
-- [avatar-pipeline.md](#sec-112) — how avatars are generated and rigged
+- [avatar-pipeline.md](#sec-113) — how avatars are generated and rigged
- [agent-system.md](#sec-064) — `AgentAvatar`, the protocol, and the emotion layers
---
-<a id="sec-329"></a>
+<a id="sec-335"></a>
> **Source:** `docs/provenance.md` · [↑ table of contents](#table-of-contents)
@@ -72365,7 +75448,7 @@ Real hashing, real ed25519 signature, real on-chain write. Requires the issuer k
---
-<a id="sec-330"></a>
+<a id="sec-336"></a>
> **Source:** `docs/pump-claims-channel.md` · [↑ table of contents](#table-of-contents)
@@ -72522,7 +75605,7 @@ built yet.
---
-<a id="sec-331"></a>
+<a id="sec-337"></a>
> **Source:** `docs/pump-fun-mcp-edge.md` · [↑ table of contents](#table-of-contents)
@@ -72578,7 +75661,7 @@ Both runtimes import `TOOLS` from `src/pump/mcp-tools.js`, so the tool list expo
---
-<a id="sec-332"></a>
+<a id="sec-338"></a>
> **Source:** `docs/pump-launch-repos.md` · [↑ table of contents](#table-of-contents)
@@ -72677,7 +75760,7 @@ rate-limits under the ~450 txs a full run makes. Pass a dedicated `--rpc`
---
-<a id="sec-333"></a>
+<a id="sec-339"></a>
> **Source:** `docs/pump-launcher.md` · [↑ table of contents](#table-of-contents)
@@ -72686,7 +75769,7 @@ rate-limits under the ~450 txs a full run makes. Pass a dedicated `--rpc`
`POST /api/x402/pump-launch` launches a brand-new [pump.fun](https://pump.fun)
token for an autonomous agent in a single paid request. The agent needs **no
SOL, no wallet, and no three.ws account** — it pays a flat USDC fee over the
-[x402](#sec-519) rail and the platform does the rest:
+[x402](#sec-544) rail and the platform does the rest:
- fronts the ~0.022 SOL bonding-curve deploy cost from a funded launcher keypair,
- optionally grinds a **vanity mint address**,
@@ -72713,7 +75796,7 @@ current figure — read it, don't hardcode.
## The free → paid funnel
-The paid launch sits between two **free, keyless** [Crypto Data API](#sec-175)
+The paid launch sits between two **free, keyless** [Crypto Data API](#sec-178)
endpoints. Use them to make the launch land well:
1. **Before you launch — check the ticker.**
@@ -72778,7 +75861,7 @@ curl -X POST https://three.ws/api/x402/pump-launch \
curl "https://three.ws/api/crypto/launches"
```
-See [x402 buyer client](#sec-511) for how to satisfy the 402 challenge in
+See [x402 buyer client](#sec-536) for how to satisfy the 402 challenge in
code.
## Output
@@ -72828,16 +75911,16 @@ token itself always deploys on **Solana mainnet** — pump.fun is mainnet-only.
## Related
-- [x402 paid endpoints](#sec-514) — the full catalog and pricing.
-- [Crypto Data API](#sec-175) — the free `symbol` and `launches`
+- [x402 paid endpoints](#sec-539) — the full catalog and pricing.
+- [Crypto Data API](#sec-178) — the free `symbol` and `launches`
endpoints that bookend a launch.
-- [Repo → Coin Launcher](#sec-332) — the batch/CLI launcher that
+- [Repo → Coin Launcher](#sec-338) — the batch/CLI launcher that
routes 100% of creator rewards to a GitHub identity (shares the same engine).
-- [x402 protocol](#sec-519) — challenge/settle mechanics.
+- [x402 protocol](#sec-544) — challenge/settle mechanics.
---
-<a id="sec-334"></a>
+<a id="sec-340"></a>
> **Source:** `docs/pump-platform-fee.md` · [↑ table of contents](#table-of-contents)
@@ -72898,124 +75981,7 @@ The fee is **never** charged silently. When `platform_fee_bps > 0`:
---
-<a id="sec-335"></a>
-
-> **Source:** `docs/pumpfun-article-x-post.md` · [↑ table of contents](#table-of-contents)
-
-# X post: pump.fun wrote an article about three.ws
-
-Copy for announcing that **pump.fun's own editorial team published a feature story on three.ws**,
-titled "Three Builds With Tech Giants", live on the $THREE coin page:
-
-https://pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
-
-**What this announcement is:** recognition. pump.fun writes these for a small fraction of the
-coins on the platform, and they wrote ours off the back of shipped product: browser-native 3D AI
-agents with onchain identities, the Animations & Poses Studio, two MCP servers in Anthropic's
-registry, the AWS partnership, and IBM replying in public.
-
-**What it is not:** a price post. The article mentions a $16.6M peak market cap. Do not build the
-post around that number and do not add moon language, predictions, or "don't miss out". The story
-is that the platform itself decided our work was worth writing up. Let that be the whole flex.
-
-Rules:
-
-1. Tag @pumpdotfun so their team sees it and can repost.
-2. Claim only what happened: pump.fun published an article about three.ws. Do not call it an
- endorsement, a partnership, or a listing.
-3. Link the article directly. The URL carries the contract address, so the mint is verifiable
- from the link itself: `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`
-4. Credit the people who did the work in the replies, not the token.
-
----
-
-## 1. Main post (recommended)
-
-> @pumpdotfun wrote an article about us.
->
-> Not a listing, not a promo slot. Their editorial team looked at what shipped and wrote the
-> story: browser-native 3D AI agents with onchain identities, the Animations & Poses Studio,
-> two MCP servers, AWS, IBM.
->
-> Most projects never get one of these. We are grateful.
->
-> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
-
----
-
-## 2. Short alternate
-
-> pump.fun published a feature on three.ws: "Three Builds With Tech Giants".
->
-> Written by their team, about work we shipped in public. That is the whole post.
->
-> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
-
----
-
-## 3. Builder-voice alternate (post from @nichxbt)
-
-> I did not pitch this. @pumpdotfun wrote it themselves.
->
-> An article about three.ws, on the coin page, covering the 3D agents, the pose studio, the MCP
-> servers, AWS and IBM. They do not write many of these.
->
-> Head down. More shipping.
->
-> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
-
----
-
-## 4. Thread version
-
-Use if you want the full story rather than one post. Post 1 is the announcement, the rest are
-replies to it.
-
-**1/**
-
-> @pumpdotfun wrote an article about three.ws.
->
-> Their editorial team, their platform, their words. Most projects never get one.
->
-> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
-
-**2/**
-
-> What they covered, in their framing: browser-native 3D AI agents with onchain identities. AI
-> that lives on a website as an embodied, embeddable character instead of a chat box.
-
-**3/**
-
-> The products they picked out: the Animations & Poses Studio at three.ws/pose, and the two MCP
-> servers now in Anthropic's official registry, including 3D Studio MCP for text and image to 3D.
-
-**4/**
-
-> And the partners: AWS, where three.ws is an official partner available through AWS Marketplace,
-> and IBM, who replied "we're super excited about this" in public on June 1.
-
-**5/**
-
-> None of that was a marketing push. It was shipping, in the open, every week, until the platform
-> we launched on decided to write it up.
->
-> Same plan for the next six months.
->
-> three.ws
-
----
-
-## Media
-
-No custom graphic is required. X unfurls the pump.fun article link with its own card, which shows
-the article title and the coin. If you attach an image instead, the card is replaced, so pick one:
-either the link preview or a graphic, never both expecting both to render.
-
-Pick one option. Do not post all four.
-
----
-
-<a id="sec-336"></a>
+<a id="sec-341"></a>
> **Source:** `docs/pumpfun-program/README.md` · [↑ table of contents](#table-of-contents)
@@ -73074,7 +76040,7 @@ tracked in `tasks/pumpfun-upstream/01-v2-trade-instructions-usdc-audit.md`.
---
-<a id="sec-337"></a>
+<a id="sec-342"></a>
> **Source:** `docs/pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md` · [↑ table of contents](#table-of-contents)
@@ -73153,32 +76119,32 @@ Currently, no quote mint other than native SOL can be used to create or trade co
- RUST crate: https://crates.io/crates/pump-rust-client
## New docs
-- Fee recipients: [docs/FEE_RECIPIENTS.md](#sec-343)
-- Coin creation: [docs/instructions/COIN_CREATION.md](#sec-352)
-- Buy: [docs/instructions/BUY.md](#sec-350)
-- Sell: [docs/instructions/SELL.md](#sec-355)
-- Claim cashback: [docs/instructions/CLAIM_CASHBACK.md](#sec-351)
-- Collect creator fee: [docs/instructions/COLLECT_CREATOR_FEE.md](#sec-353)
-- Creator fee sharing: [docs/instructions/CREATOR_FEE_SHARING.md](#sec-354)
+- Fee recipients: [docs/FEE_RECIPIENTS.md](#sec-348)
+- Coin creation: [docs/instructions/COIN_CREATION.md](#sec-357)
+- Buy: [docs/instructions/BUY.md](#sec-355)
+- Sell: [docs/instructions/SELL.md](#sec-360)
+- Claim cashback: [docs/instructions/CLAIM_CASHBACK.md](#sec-356)
+- Collect creator fee: [docs/instructions/COLLECT_CREATOR_FEE.md](#sec-358)
+- Creator fee sharing: [docs/instructions/CREATOR_FEE_SHARING.md](#sec-359)
## Other documentation
-- [Pump Program](#sec-346)
-- [PumpSwap](#sec-348)
-- [PumpSwap SDK](#sec-349)
-- [Pump Program creator fee update](#sec-345)
-- [PumpSwap creator fee update](#sec-347)
-- [FAQ](#sec-341)
-- [Pump fee program docs](#sec-342)
+- [Pump Program](#sec-351)
+- [PumpSwap](#sec-353)
+- [PumpSwap SDK](#sec-354)
+- [Pump Program creator fee update](#sec-350)
+- [PumpSwap creator fee update](#sec-352)
+- [FAQ](#sec-346)
+- [Pump fee program docs](#sec-347)
---
---
-<a id="sec-338"></a>
+<a id="sec-343"></a>
> **Source:** `docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md` · [↑ table of contents](#table-of-contents)
@@ -73379,7 +76345,7 @@ Upstream: <https://github.com/pump-fun/pump-public-docs#pumpswap-update-virtual-
---
-<a id="sec-339"></a>
+<a id="sec-344"></a>
> **Source:** `docs/pumpfun-program/docs/BREAKING_FEE_RECIPIENT.md` · [↑ table of contents](#table-of-contents)
@@ -73453,7 +76419,7 @@ The new accounts can be passed before the program upgrade happens on Monday. The
---
-<a id="sec-340"></a>
+<a id="sec-345"></a>
> **Source:** `docs/pumpfun-program/docs/CPI_README.md` · [↑ table of contents](#table-of-contents)
@@ -73557,7 +76523,7 @@ pump-rust-client = { version = "...", path = "..." }
---
-<a id="sec-341"></a>
+<a id="sec-346"></a>
> **Source:** `docs/pumpfun-program/docs/FAQ.md` · [↑ table of contents](#table-of-contents)
@@ -73595,7 +76561,7 @@ is recommended to use a static big enough CU limit like `100_000`.
---
-<a id="sec-342"></a>
+<a id="sec-347"></a>
> **Source:** `docs/pumpfun-program/docs/FEE_PROGRAM_README.md` · [↑ table of contents](#table-of-contents)
@@ -73809,7 +76775,7 @@ If you implement the fee logic correctly, any future change to the fee tiers str
---
-<a id="sec-343"></a>
+<a id="sec-348"></a>
> **Source:** `docs/pumpfun-program/docs/FEE_RECIPIENTS.md` · [↑ table of contents](#table-of-contents)
@@ -73872,7 +76838,7 @@ Use one of these as `buybackFeeRecipient` for any coin.
---
-<a id="sec-344"></a>
+<a id="sec-349"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_CASHBACK_README.md` · [↑ table of contents](#table-of-contents)
@@ -73989,7 +76955,7 @@ To read unclaimed cashback for pump swap / Pump AMM program:
---
-<a id="sec-345"></a>
+<a id="sec-350"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_CREATOR_FEE_README.md` · [↑ table of contents](#table-of-contents)
@@ -74124,7 +77090,7 @@ we update the programs on Mainnet.
---
-<a id="sec-346"></a>
+<a id="sec-351"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_PROGRAM_README.md` · [↑ table of contents](#table-of-contents)
@@ -74325,7 +77291,7 @@ at https://solscan.io/account/EsmVk4MTsoT71JFaRM5DWFZboKpMQjfY6EYzAgUuksXw#accou
---
-<a id="sec-347"></a>
+<a id="sec-352"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_SWAP_CREATOR_FEE_README.md` · [↑ table of contents](#table-of-contents)
@@ -74434,7 +77400,7 @@ PumpSwap program on Mainnet to the coin creator fee update.
---
-<a id="sec-348"></a>
+<a id="sec-353"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_SWAP_README.md` · [↑ table of contents](#table-of-contents)
@@ -74668,7 +77634,7 @@ Each Anchor instruction has a set of corresponding autocomplete methods that can
---
-<a id="sec-349"></a>
+<a id="sec-354"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_SWAP_SDK_README.md` · [↑ table of contents](#table-of-contents)
@@ -74748,7 +77714,7 @@ to autocomplete the `base` and `quote` displayed amounts based on the `lpToken`
---
-<a id="sec-350"></a>
+<a id="sec-355"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/BUY.md` · [↑ table of contents](#table-of-contents)
@@ -74809,7 +77775,7 @@ All `buy_v2` calls need a `feeRecipient` and a `buybackFeeRecipient`.
- For mayhem mode coins, choose one of the 8 reserved fee recipients as `feeRecipient`.
- For all coins, choose one of the 8 buyback fee recipients as `buybackFeeRecipient`.
-See [Fee Recipients](#sec-343) for the full address lists.
+See [Fee Recipients](#sec-348) for the full address lists.
## TS SDK
@@ -74926,7 +77892,7 @@ ixs.extend(
---
-<a id="sec-351"></a>
+<a id="sec-356"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/CLAIM_CASHBACK.md` · [↑ table of contents](#table-of-contents)
@@ -75036,7 +78002,7 @@ let ix = sdk.claim_cashback_v2_instruction(
---
-<a id="sec-352"></a>
+<a id="sec-357"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/COIN_CREATION.md` · [↑ table of contents](#table-of-contents)
@@ -75191,7 +78157,7 @@ let ixs = sdk
---
-<a id="sec-353"></a>
+<a id="sec-358"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md` · [↑ table of contents](#table-of-contents)
@@ -75293,13 +78259,13 @@ ixs.extend(sdk.collect_creator_fee_v2_instructions(
---
-<a id="sec-354"></a>
+<a id="sec-359"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md` · [↑ table of contents](#table-of-contents)
# Creator Fee Sharing
-> **Note:** These instructions only apply to coins that **have** a `sharing_config` — i.e. coins whose creator vault has been migrated to the Pump Fees program for multi-recipient distribution. For single-creator-recipient coins (no `sharing_config`), use [`collect_creator_fee_v2` / `collect_coin_creator_fee`](#sec-353) instead.
+> **Note:** These instructions only apply to coins that **have** a `sharing_config` — i.e. coins whose creator vault has been migrated to the Pump Fees program for multi-recipient distribution. For single-creator-recipient coins (no `sharing_config`), use [`collect_creator_fee_v2` / `collect_coin_creator_fee`](#sec-358) instead.
The lifecycle is:
@@ -75647,7 +78613,7 @@ ixs.extend(sdk.distribute_creator_fees_v2_instructions(
---
-<a id="sec-355"></a>
+<a id="sec-360"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/SELL.md` · [↑ table of contents](#table-of-contents)
@@ -75707,7 +78673,7 @@ All `sell_v2` calls need a `feeRecipient` and a `buybackFeeRecipient`.
- For mayhem mode coins, choose one of the 8 reserved fee recipients as `feeRecipient`.
- For all coins, choose one of the 8 buyback fee recipients as `buybackFeeRecipient`.
-See [Fee Recipients](#sec-343) for the full address lists.
+See [Fee Recipients](#sec-348) for the full address lists.
## TS SDK
@@ -75824,7 +78790,7 @@ ixs.extend(
---
-<a id="sec-356"></a>
+<a id="sec-361"></a>
> **Source:** `docs/quick-start.md` · [↑ table of contents](#table-of-contents)
@@ -75970,7 +78936,7 @@ The `brain` attribute turns the 3D viewer into a conversational agent:
| `brain` | LLM model ID. Registered Claude IDs: `claude-sonnet-5`, `claude-opus-5`, `claude-sonnet-4-6`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`, `claude-fable-5`, `claude-mythos-5` (restricted access). Free models (no key, routed through the platform proxy) are also accepted, e.g. `meta-llama/llama-3.3-70b-instruct:free`. Omit for a viewer-only display with no AI (provider `none`). |
| `instructions` | System prompt for the agent's personality and role. |
| `mode` | Layout mode: `inline` (flows with page content), `floating` (fixed bubble in a corner), `fullscreen`, or `section`. Default: `inline`. |
-| `sign-language` | The avatar signs every reply in ASL fingerspelling plus its sign vocabulary (any value except `off`/`false` enables it; works at boot or toggled at runtime). See the [sign language guide](#sec-376). |
+| `sign-language` | The avatar signs every reply in ASL fingerspelling plus its sign vocabulary (any value except `off`/`false` enables it; works at boot or toggled at runtime). See the [sign language guide](#sec-381). |
The chat input and microphone button appear automatically when `brain` is set. The agent can play animations, look at the camera, and respond to voice input.
@@ -76011,7 +78977,7 @@ The fastest path to an embeddable 3D experience is an iframe widget. Build one i
| `passport` | On-chain identity card backed by ERC-8004. |
| `hotspot-tour` | Annotated 3D scenes with clickable points of interest. |
-For the full widget API including `postMessage` events, see the [Widget docs](#sec-505).
+For the full widget API including `postMessage` events, see the [Widget docs](#sec-511).
---
@@ -76041,7 +79007,7 @@ Copy `.env.example` to `.env` and fill in:
| `ANTHROPIC_API_KEY` | Required for AI chat | LLM backend. Without it, the agent falls back to pattern matching. |
| `VITE_PRIVY_APP_ID` | Optional | Wallet auth via [Privy](https://privy.io). Needed for on-chain identity. |
| `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` | Optional | Distributed rate limiting. Falls back to in-memory without it. |
-| `VITE_CHARACTER_STUDIO_URL` | Optional | Override for the origin hosting the [Avatar Studio](https://github.com/m3-org/CharacterStudio) avatar builder iframe. When unset, the app resolves it same-origin to `<origin>/avatar-studio` in both dev and production. Set it only to point at a standalone studio dev server (e.g. `http://localhost:5173`). See [Configuration](#sec-150). |
+| `VITE_CHARACTER_STUDIO_URL` | Optional | Override for the origin hosting the [Avatar Studio](https://github.com/m3-org/CharacterStudio) avatar builder iframe. When unset, the app resolves it same-origin to `<origin>/avatar-studio` in both dev and production. Set it only to point at a standalone studio dev server (e.g. `http://localhost:5173`). See [Configuration](#sec-153). |
| `AVATURN_API_KEY` | Optional | Photo-to-avatar pipeline via an external photo-to-avatar provider. |
| `PINATA_JWT` | Optional | IPFS pinning for on-chain agent registration. |
@@ -76112,15 +79078,15 @@ If you're embedding inside a sandboxed iframe, make sure the parent grants `allo
## Next Steps
-- [Embedding Guide](#sec-183) — deep dive on attributes, events, and the JS API
-- [Widget Types](#sec-505) — full reference for iframe embeds and postMessage
+- [Embedding Guide](#sec-186) — deep dive on attributes, events, and the JS API
+- [Widget Types](#sec-511) — full reference for iframe embeds and postMessage
- [Agent System](#sec-064) — how the brain, memory, and skills layers work
-- [REST API](#sec-096) and [JavaScript API](#sec-257) — backend and in-browser surfaces
-- [SDK Reference](#sec-369) — `@three-ws/sdk`, `@three-ws/agent-ui`, `@three-ws/avatar`, `@three-ws/solana-agent`
+- [REST API](#sec-096) and [JavaScript API](#sec-258) — backend and in-browser surfaces
+- [SDK Reference](#sec-374) — `@three-ws/sdk`, `@three-ws/agent-ui`, `@three-ws/avatar`, `@three-ws/solana-agent`
---
-<a id="sec-357"></a>
+<a id="sec-362"></a>
> **Source:** `docs/radar.md` · [↑ table of contents](#table-of-contents)
@@ -76136,7 +79102,7 @@ API: `/api/pump/coin-intel` (feed, market pulse, per-coin detail). The detail dr
## Why it exists
-The most dangerous moment on pump.fun is the first minute, when the tape is thin and a bundle of bot wallets can manufacture the look of organic demand. A human cannot audit funder graphs and timing entropy in real time. The Coin Intelligence Engine does, on the live firehose, and Radar is its screener: a scannable board that turns raw first-90-seconds behaviour into a quality score and a short list of named risks, so you can filter out the coordinated launches and focus on the ones with a real crowd. It is the top of the [trading surfaces](#sec-409) funnel: Radar surfaces a launch worth a look, you watch it, and if it earns conviction you open it in [Mission Control](#sec-398) to act.
+The most dangerous moment on pump.fun is the first minute, when the tape is thin and a bundle of bot wallets can manufacture the look of organic demand. A human cannot audit funder graphs and timing entropy in real time. The Coin Intelligence Engine does, on the live firehose, and Radar is its screener: a scannable board that turns raw first-90-seconds behaviour into a quality score and a short list of named risks, so you can filter out the coordinated launches and focus on the ones with a real crowd. It is the top of the [trading surfaces](#sec-415) funnel: Radar surfaces a launch worth a look, you watch it, and if it earns conviction you open it in [Mission Control](#sec-404) to act.
## How it works
@@ -76166,7 +79132,7 @@ The UI colors quality as Healthy at 70 and up, Mixed from 40 to 69, and High ris
3. Press `/` to focus search and type a name, ticker, or mint. Press `g` or `l` to switch grid and list, `r` to refresh.
4. Click any coin for the drawer: the full signal grid, the top-50 wallet ledger, the smart-money notable roster, the outcome (if labeled), and an asynchronously injected Oracle conviction section.
5. Every mainnet coin links to its full page at `/oracle/coin/<mint>`: the card's "Full intel →" button goes there directly, and the drawer carries an "Open full page →" link in its header. The full page renders in the markets-hub design (the same system as `/coin/:id`) with the live price chart, the complete Launch Intelligence read (this engine's signal grid, risk flags, and trader ledger), Oracle conviction, live market intel, agent transactions, and a live trade tape.
-6. On a coin worth tracking, use Watch to add it to your [Watchlist](https://three.ws/watchlist), then open it in [Mission Control](#sec-398) to trade.
+6. On a coin worth tracking, use Watch to add it to your [Watchlist](https://three.ws/watchlist), then open it in [Mission Control](#sec-404) to trade.
## Examples
@@ -76205,16 +79171,16 @@ console.log(clean.map((c) => `${c.symbol} q${c.quality_score}`));
## Related
-- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-409)
-- [Oracle: the conviction engine](#sec-310) fuses this intel into a single conviction score
-- [Smart Money Radar](#sec-383) is the pedigree layer Radar surfaces inline
-- [Mission Control](#sec-398) is where a Radar find gets traded
-- [Coin pages](#sec-143) cross-link the per-mint intel and conviction views
+- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-415)
+- [Oracle: the conviction engine](#sec-315) fuses this intel into a single conviction score
+- [Smart Money Radar](#sec-389) is the pedigree layer Radar surfaces inline
+- [Mission Control](#sec-404) is where a Radar find gets traded
+- [Coin pages](#sec-145) cross-link the per-mint intel and conviction views
- Pages: [/radar](https://three.ws/radar) · [/coin-intel](https://three.ws/coin-intel) · [/watchlist](https://three.ws/watchlist)
---
-<a id="sec-358"></a>
+<a id="sec-363"></a>
> **Source:** `docs/reasoning-ledger.md` · [↑ table of contents](#table-of-contents)
@@ -76304,17 +79270,17 @@ The headline score (0 to 100) is derived only from reconciled outcomes, and the
## Related
- [Agent Sniper](#sec-061): the pipeline that writes `snipe` entries, with a live case-study ledger
-- [Custody you can verify](#sec-167): the same provable-not-promised approach applied to the wallets these decisions spend from
+- [Custody you can verify](#sec-170): the same provable-not-promised approach applied to the wallets these decisions spend from
---
-<a id="sec-359"></a>
+<a id="sec-364"></a>
> **Source:** `docs/recurring-payments.md` · [↑ table of contents](#table-of-contents)
# Recurring payments
-A recurring payment moves a fixed amount of USDC out of your wallet on a schedule you choose, without you signing anything again. You sign one ERC-7710 permission (see [Permissions & Delegation](#sec-317)), the platform's hourly cron spends inside it, and every attempt it makes is written to a ledger you can read.
+A recurring payment moves a fixed amount of USDC out of your wallet on a schedule you choose, without you signing anything again. You sign one ERC-7710 permission (see [Permissions & Delegation](#sec-322)), the platform's hourly cron spends inside it, and every attempt it makes is written to a ledger you can read.
Two kinds of schedule ride the same rails:
@@ -76480,13 +79446,13 @@ Definitions live in [api/\_lib/schema.sql](../api/_lib/schema.sql); the lifecycl
## See also
-- [Permissions & Delegation](#sec-317) for granting, scoping and revoking the signed permission a schedule spends
-- [Payment sessions](#sec-316) for capped one-off agent spending that is not on a schedule
+- [Permissions & Delegation](#sec-322) for granting, scoping and revoking the signed permission a schedule spends
+- [Payment sessions](#sec-321) for capped one-off agent spending that is not on a schedule
- [Agent wallets](#sec-072) for the wallet a subscription pays into
---
-<a id="sec-360"></a>
+<a id="sec-365"></a>
> **Source:** `docs/remix.md` · [↑ table of contents](#table-of-contents)
@@ -76683,12 +79649,12 @@ still recorded — the royalty leg reports `payout_unconfigured` instead of payi
## Related
-- [3D Studio (free) MCP](#sec-273) — the `refine_model` iteration tool.
+- [3D Studio (free) MCP](#sec-274) — the `refine_model` iteration tool.
- [The 3D pipeline](#sec-003) — how generation itself works.
---
-<a id="sec-361"></a>
+<a id="sec-366"></a>
> **Source:** `docs/reputation-staking-market.md` · [↑ table of contents](#table-of-contents)
@@ -76709,7 +79675,7 @@ Live surface: [/reputation/market](/reputation/market).
## What the market pays for
Reputation is already attested on Solana as signed SPL-Memo envelopes indexed
-into `solana_attestations` (see [docs/solana-reputation](#sec-387)).
+into `solana_attestations` (see [docs/solana-reputation](#sec-393)).
An agent's `threews.accept.v1`, `threews.task.v1`, `threews.validation.v1`,
`threews.feedback.v1`, `threews.dispute.v1`, and `threews.revoke.v1` envelopes
are its attested action history: work it shipped, validations it passed or
@@ -76915,15 +79881,15 @@ Failure codes (`market_not_configured`, `mainnet_gated`, `tx_not_found`,
## Related
-- [Docs: Agent Reputation on Solana](#sec-387): the attestation
+- [Docs: Agent Reputation on Solana](#sec-393): the attestation
layer the market reads.
-- [Docs: Reputation System](#sec-362): the cross-chain reputation model.
+- [Docs: Reputation System](#sec-367): the cross-chain reputation model.
- [Reputation Explorer](/reputation): inspect any agent's score and
attestations.
---
-<a id="sec-362"></a>
+<a id="sec-367"></a>
> **Source:** `docs/reputation.md` · [↑ table of contents](#table-of-contents)
@@ -77132,7 +80098,7 @@ GET /api/explore
Separate from reputation scores, glTF validation results can also be recorded on-chain via the `ValidationRegistry`. A passing validation attests that the agent's 3D model meets the glTF specification as of a specific block timestamp. Validation history is shown on the agent's profile page alongside reputation data.
-See the [Validation](#sec-495) documentation for details.
+See the [Validation](#sec-501) documentation for details.
---
@@ -77145,7 +80111,7 @@ See the [Validation](#sec-495) documentation for details.
---
-<a id="sec-363"></a>
+<a id="sec-368"></a>
> **Source:** `docs/restyle.md` · [↑ table of contents](#table-of-contents)
@@ -77157,7 +80123,7 @@ Page: [/restyle](https://three.ws/restyle) · API: `/api/material-studio`
## Why it exists
-Generating a 3D model is the expensive step. Once you have a good mesh, wanting it in a different finish should not mean paying to regenerate the whole thing and risking a worse shape. Restyle Studio separates the two. Skin is cheap and reversible; geometry is precious and left alone. That makes iterating on look-and-feel a tight loop: try chrome, try worn copper, try glass, save the two you like as durable versions, export the winner. It also gives the rest of the platform one shared material vocabulary. Restyle Studio consumes the same PBR preset library (`@three-ws/viewer-presets`) and the same GLB optimize-and-validate path that [Avatar Studio](#sec-114) uses, instead of inventing a parallel one.
+Generating a 3D model is the expensive step. Once you have a good mesh, wanting it in a different finish should not mean paying to regenerate the whole thing and risking a worse shape. Restyle Studio separates the two. Skin is cheap and reversible; geometry is precious and left alone. That makes iterating on look-and-feel a tight loop: try chrome, try worn copper, try glass, save the two you like as durable versions, export the winner. It also gives the rest of the platform one shared material vocabulary. Restyle Studio consumes the same PBR preset library (`@three-ws/viewer-presets`) and the same GLB optimize-and-validate path that [Avatar Studio](#sec-115) uses, instead of inventing a parallel one.
## How it works
@@ -77238,14 +80204,14 @@ Pass the returned `lineage` array back as `parent_lineage` on the next call to e
## Related
-- [Avatar Studio](#sec-114): shares the same GLB optimize-and-validate path and material vocabulary.
-- [Scene Composer](#sec-148) and [Scene Studio](#sec-368): arrange and edit restyled models in a full scene.
-- [MCP tools reference](#sec-274): the paid `restyle_material` agent twin of this endpoint.
+- [Avatar Studio](#sec-115): shares the same GLB optimize-and-validate path and material vocabulary.
+- [Scene Composer](#sec-151) and [Scene Studio](#sec-373): arrange and edit restyled models in a full scene.
+- [MCP tools reference](#sec-275): the paid `restyle_material` agent twin of this endpoint.
- [/forge](https://three.ws/forge): generate the models you bring here.
---
-<a id="sec-364"></a>
+<a id="sec-369"></a>
> **Source:** `docs/rig-doctor.md` · [↑ table of contents](#table-of-contents)
@@ -77259,7 +80225,7 @@ Everything runs in your browser. The file is read with `FileReader` and analysed
**On this page:** [The problem](#the-problem-a-rig-that-loads-but-never-moves) · [Reading the verdict](#reading-the-verdict) · [Coverage](#coverage-which-limbs-will-move) · [The repair](#the-repair) · [Generated output](#generated-output) · [Conventions](#recognised-rig-conventions) · [The canonical skeleton](#the-canonical-skeleton) · [Programmatic use](#programmatic-use)
-Related: [Avatar CLI](#sec-107) turns the generated manifest into a validated, hash-anchored file. The [web component reference](#sec-502) covers the `<agent-3d>` element the embed tab emits. [Asset pipeline](#sec-002) covers FBX and GLB conversion upstream of all of this.
+Related: [Avatar CLI](#sec-108) turns the generated manifest into a validated, hash-anchored file. The [web component reference](#sec-508) covers the `<agent-3d>` element the embed tab emits. [Asset pipeline](#sec-002) covers FBX and GLB conversion upstream of all of this.
---
@@ -77343,7 +80309,7 @@ The **Ship it** panel writes three artefacts from the file you dropped.
**Embed** is the `<agent-3d>` loader and element, ready to paste into any page.
-**CLI** is the [`@three-ws/avatar-cli`](#sec-107) invocation that produces the same manifest with a real `sha256` over the mesh bytes, plus the validate call. Run it when you are ready to anchor the manifest for real:
+**CLI** is the [`@three-ws/avatar-cli`](#sec-108) invocation that produces the same manifest with a real `sha256` over the mesh bytes, plus the validate call. Run it when you are ready to anchor the manifest for real:
```bash
npx @three-ws/avatar-cli init \
@@ -77475,7 +80441,7 @@ Your own file cannot be shared this way, because it never leaves your machine.
---
-<a id="sec-365"></a>
+<a id="sec-370"></a>
> **Source:** `docs/risk-acknowledgment.md` · [↑ table of contents](#table-of-contents)
@@ -77589,12 +80555,12 @@ above.
## Related
- [Risk Disclosure](https://three.ws/legal/risk) — the full legal text users accept
-- [Custody you can verify](#sec-167) — the spend-limit and freeze controls that bound what agents can do after acceptance
+- [Custody you can verify](#sec-170) — the spend-limit and freeze controls that bound what agents can do after acceptance
- [Terms of Service](https://three.ws/legal/tos) — §8 Limitation of Liability, which this acknowledgment supplements
---
-<a id="sec-366"></a>
+<a id="sec-371"></a>
> **Source:** `docs/robinhood-chain-markets.md` · [↑ table of contents](#table-of-contents)
@@ -77686,16 +80652,16 @@ math; Chainlink feed prices are already multiplier-adjusted, so they're never re
## Related surfaces
-- [Market Data API](#sec-268) — the same paid-endpoint pattern (x402, `priceFor`,
+- [Market Data API](#sec-269) — the same paid-endpoint pattern (x402, `priceFor`,
service-catalog descriptor) applied to the rest of three.ws's market data.
-- [Trust primitives](#sec-411) — score a Robinhood Chain wallet's cross-chain
+- [Trust primitives](#sec-417) — score a Robinhood Chain wallet's cross-chain
reputation before transacting with it.
-- [x402 distribution](#sec-513) — how the paid portfolio endpoint gets discovered
+- [x402 distribution](#sec-538) — how the paid portfolio endpoint gets discovered
across the x402 ecosystem.
---
-<a id="sec-367"></a>
+<a id="sec-372"></a>
> **Source:** `docs/sas-attestations.md` · [↑ table of contents](#table-of-contents)
@@ -77705,7 +80671,7 @@ An attestation is a signed on-chain statement about a wallet or an agent (for ex
three.ws issues two kinds of on-chain attestations on Solana:
-- **Permissionless attestations** — general feedback, task lifecycle, dispute, and revoke events. Anyone can write them as SPL Memos (see [Solana reputation](#sec-387)).
+- **Permissionless attestations** — general feedback, task lifecycle, dispute, and revoke events. Anyone can write them as SPL Memos (see [Solana reputation](#sec-393)).
- **Credentialed attestations** — claims only three.ws or an authorized validator may make: that a wallet is verified, or that a validator audited an agent's task result. These use the [Solana Attestation Service (SAS)](https://attest.solana.com/) and are signed by the **three.ws authority wallet**.
This page covers the authority wallet, the `SAS_AUTHORITY_SECRET` environment variable, bootstrapping the credential + schemas, and the API that issues them.
@@ -77928,13 +80894,13 @@ Closing (revoking) an attestation is done server-side via `sasClose()` in [api/_
---
-<a id="sec-368"></a>
+<a id="sec-373"></a>
> **Source:** `docs/scene-studio.md` · [↑ table of contents](#table-of-contents)
# Scene Studio: the full three.js editor, in your browser
-Scene Studio is the complete [mrdoob/three.js](https://github.com/mrdoob/three.js) editor (release r184, MIT-licensed), vendored into three.ws and wrapped in the site chrome. It is the heavyweight scene tool: import GLBs and other assets, move and rotate and scale them with transform gizmos, edit materials and lights and cameras through a full property sidebar, script objects with live JavaScript, play the scene, and export it. Where [Scene Composer](#sec-148) is a focused avatar-plus-props arranger and [Animation Studio](#sec-092) is a posing and keyframing tool, Scene Studio is the general-purpose 3D authoring surface underneath them.
+Scene Studio is the complete [mrdoob/three.js](https://github.com/mrdoob/three.js) editor (release r184, MIT-licensed), vendored into three.ws and wrapped in the site chrome. It is the heavyweight scene tool: import GLBs and other assets, move and rotate and scale them with transform gizmos, edit materials and lights and cameras through a full property sidebar, script objects with live JavaScript, play the scene, and export it. Where [Scene Composer](#sec-151) is a focused avatar-plus-props arranger and [Animation Studio](#sec-092) is a posing and keyframing tool, Scene Studio is the general-purpose 3D authoring surface underneath them.
Page: [/scene](https://three.ws/scene)
@@ -77989,20 +80955,20 @@ A typical round trip from another studio:
## Related
-- [Scene Composer](#sec-148): the lighter avatar-plus-props arranger with Forge integration.
+- [Scene Composer](#sec-151): the lighter avatar-plus-props arranger with Forge integration.
- [Animation Studio](#sec-092): builds the animated GLBs Scene Studio records to video.
-- [Restyle Studio](#sec-363): re-skin the models before or after composing them.
+- [Restyle Studio](#sec-368): re-skin the models before or after composing them.
- [3D asset pipeline](#sec-002): how GLB, glTF, and clip formats relate across the platform.
---
-<a id="sec-369"></a>
+<a id="sec-374"></a>
> **Source:** `docs/sdk.md` · [↑ table of contents](#table-of-contents)
# SDK & Library
-This page is for developers who want to build with three.ws code in their own project, beyond pasting an embed snippet. If you just want a 3D agent on a page, start with the [web component](#sec-502); come here when you need to import classes, register agents on-chain, or build the bundles yourself. There are two distributable artifacts you can import:
+This page is for developers who want to build with three.ws code in their own project, beyond pasting an embed snippet. If you just want a 3D agent on a page, start with the [web component](#sec-508); come here when you need to import classes, register agents on-chain, or build the bundles yourself. There are two distributable artifacts you can import:
| Artifact | Package | Use case |
|---|---|---|
@@ -78095,7 +81061,7 @@ const viewer = new Viewer(document.getElementById('canvas-container'));
viewer.load('https://three.ws/avatars/default.glb');
```
-Full attribute and event API is documented in [Web Component reference](#sec-502).
+Full attribute and event API is documented in [Web Component reference](#sec-508).
### loadManifest and normalize
@@ -78438,7 +81404,7 @@ python3 -m http.server 8080
---
-<a id="sec-370"></a>
+<a id="sec-375"></a>
> **Source:** `docs/security.md` · [↑ table of contents](#table-of-contents)
@@ -78479,7 +81445,7 @@ Chat messages travel through `/api/chat`, which proxies to a configured LLM prov
- Does not log message content
- Returns the LLM stream directly to your browser
-Conversation history lives in `localStorage` by default. Cloud memory sync is opt-in (see [Memory](#sec-279)).
+Conversation history lives in `localStorage` by default. Cloud memory sync is opt-in (see [Memory](#sec-280)).
### Wallet data
@@ -78495,7 +81461,7 @@ The SIWE (Sign-In With Ethereum) flow signs a server-generated challenge — no
| Mode | Where data lives | Privacy |
|------|-----------------|---------|
| `local` (default) | Browser `localStorage` | Device-only |
-| `remote` | three.ws cloud storage, tied to your account | Opt-in cloud sync (see [Memory](#sec-279)) |
+| `remote` | three.ws cloud storage, tied to your account | Opt-in cloud sync (see [Memory](#sec-280)) |
| `ipfs` | Public IPFS network | Public — use only for non-sensitive data |
| `encrypted-ipfs` | IPFS, encrypted before leaving the browser | Encrypted with your key; IPFS only sees ciphertext |
| `none` | Not persisted | Cleared on page unload |
@@ -78647,7 +81613,7 @@ Every registered agent card requires a `model.sha256` field. The `<three-d-agent
Validator keys are dedicated signing keys, not personal wallets. The deployed `ValidationRegistry` has **no validator allowlist** (`removeValidator(address)` exists only on `contracts/src/ValidationRegistry.sol`, which is deployed nowhere), so revocation is not an on-chain call: any address can answer a request addressed to it. Containment for a compromised validator key is therefore to rotate it (`scripts/erc8004/provision-validator-key.mjs` reprovisions `VALIDATOR_PRIVATE_KEY` on the API service) and to have indexers and resolvers filter by validator address, treating attestations signed by the retired key as expired from the rotation block onward.
-That places the whole burden on key custody: see the platform-validator note in [contracts/DEPLOYMENTS.md](../contracts/DEPLOYMENTS.md) and [docs/erc8004/validation-attestation.md](#sec-186) for the operating rules.
+That places the whole burden on key custody: see the platform-validator note in [contracts/DEPLOYMENTS.md](../contracts/DEPLOYMENTS.md) and [docs/erc8004/validation-attestation.md](#sec-189) for the operating rules.
### Reputation gaming (V5)
@@ -78800,7 +81766,7 @@ For validator misconduct (biased or falsified on-chain attestations), open a pub
---
-<a id="sec-371"></a>
+<a id="sec-376"></a>
> **Source:** `docs/seed-quality.md` · [↑ table of contents](#table-of-contents)
@@ -79085,13 +82051,13 @@ ticks start timing out, lower `SEED_CRON_VISION_MS` before turning it back off.
- [Realism quality bench](../data/quality-bench/README.md): the regression
harness whose scorer this gate imports
-- [The 3D viewer](#sec-499): what a published catalog entry has to render in
+- [The 3D viewer](#sec-505): what a published catalog entry has to render in
- [Production log triage](ops/production-log-triage.md): the operator runbook
for the seeding pipeline
---
-<a id="sec-372"></a>
+<a id="sec-377"></a>
> **Source:** `docs/selfie-to-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -79119,10 +82085,10 @@ Two of those numbers are measured rather than reasoned about. The blur floor (`B
3. **Optional side angles.** Under an "Add side angles" disclosure you can capture two extra stills (`left`, `right`, turned ~45 degrees). They raise fidelity and the ETA, but only the frontal is required. Confirmed shots (and the style choice) are mirrored to `sessionStorage`, so a refresh or accidental back-swipe mid-capture restores every slot instead of starting over; the build phase has its own resume rail (`selfie:pendingJobId`).
4. **Refine, in the browser.** `assessPhoto` gates the frontal (no face is the only hard block; blur, illustration, or a distant subject are non-fatal warnings). `refineSelfie` isolates the subject from its background and reframes to a clean head-and-shoulders square, rendered at 1024x1024 with JPEG quality 0.92 ([`src/selfie-refine.js`](../src/selfie-refine.js)). The refined frontal is previewed so you see exactly what the engine sees.
5. **Submit.** The pipeline ([`src/selfie-pipeline.js`](../src/selfie-pipeline.js)) downscales each photo to a 1024px longest edge at JPEG quality 0.88, POSTs them as data URIs to `/api/avatars/reconstruct`, and gets back a `jobId`.
-6. **Reconstruct, server-side.** The reconstruct handler (`api/avatars/_actions.js`) selects a provider through [`api/_lib/regen-provider.js`](../api/_lib/regen-provider.js). The production lane is **GCP**: it POSTs `{ images, body_type }` to the Cloud Run service behind `GCP_RECONSTRUCTION_URL`, today the [`workers/avatar-reconstruction/`](../workers/avatar-reconstruction) FastAPI app deployed as `avatar-reconstruction`. (The multi-backend [`workers/avatar-pipeline-controller/`](../workers/avatar-pipeline-controller) speaks the identical contract and can take over that env var, but is not deployed today.) That pipeline (`face_texture_transfer_v2`) uses **MediaPipe FaceLandmarker** (468 landmarks, Apache-2.0) to transfer your face texture and geometry onto a fixed-topology, pre-rigged Wolf3D/Ready-Player-Me-style humanoid template carrying a Mixamo-compatible skeleton, 52 ARKit blendshapes, and 15 visemes. Full engine detail is in [avatar-reconstruction.md](#sec-113).
+6. **Reconstruct, server-side.** The reconstruct handler (`api/avatars/_actions.js`) selects a provider through [`api/_lib/regen-provider.js`](../api/_lib/regen-provider.js). The production lane is **GCP**: it POSTs `{ images, body_type }` to the Cloud Run service behind `GCP_RECONSTRUCTION_URL`, today the [`workers/avatar-reconstruction/`](../workers/avatar-reconstruction) FastAPI app deployed as `avatar-reconstruction`. (The multi-backend [`workers/avatar-pipeline-controller/`](../workers/avatar-pipeline-controller) speaks the identical contract and can take over that env var, but is not deployed today.) That pipeline (`face_texture_transfer_v2`) uses **MediaPipe FaceLandmarker** (468 landmarks, Apache-2.0) to transfer your face texture and geometry onto a fixed-topology, pre-rigged Wolf3D/Ready-Player-Me-style humanoid template carrying a Mixamo-compatible skeleton, 52 ARKit blendshapes, and 15 visemes. Full engine detail is in [avatar-reconstruction.md](#sec-114).
7. **Auto-rig fallback.** The template is born rigged. If a generic mesh comes back unrigged and a rig model is configured, `reconstruct-finalize.js` chains a `rerig` job (the `model-rig` worker, `workers/rig`) and moves the job through a `rigging` status before surfacing the avatar. If rigging is impossible it delivers the static mesh tagged `unrigged` rather than nothing.
8. **Poll and finish.** The client polls `GET /api/avatars/regenerate-status?jobId=...` every ~3 seconds (backing off on errors). On `status: 'done'` it fetches the finished avatar from `GET /api/avatars/:id` and shows it in a `<model-viewer>`. The poll uses the adapter for the provider recorded on the job row, not whichever provider currently leads the precedence order, because the stored job id is provider-shaped and only that backend can read it.
-9. **Register and mint.** Materializing the avatar also registers it in the Forge store (`forge_creations`, `path: 'reconstruct'`) so galleries, share and embed pages, and provenance treat a capture like any other creation, and fires a best-effort [draft agent identity mint](#sec-177): a Metaplex Core asset on Solana, with an ERC-8004 registration behind its own flag. Both are best-effort by design: the avatar is already delivered, so neither can fail the job.
+9. **Register and mint.** Materializing the avatar also registers it in the Forge store (`forge_creations`, `path: 'reconstruct'`) so galleries, share and embed pages, and provenance treat a capture like any other creation, and fires a best-effort [draft agent identity mint](#sec-180): a Metaplex Core asset on Solana, with an ERC-8004 registration behind its own flag. Both are best-effort by design: the avatar is already delivered, so neither can fail the job.
10. **Backstop for a closed tab.** The browser poll is what drives finalization, so closing the tab mid-build would otherwise strand the job even though the worker finished. [`api/cron/reconstruct-sweep.js`](../api/cron/reconstruct-sweep.js) runs the same finalize stages server-side every few minutes, so an abandoned capture still lands in your library. It rescues jobs up to 30 days old, and fails anything older with an honest reason rather than leaving it open forever.
### The text-to-avatar variant
@@ -79180,16 +82146,16 @@ Request body: `name` (1-120, required), `photos` (1-6 image URLs or data URIs) *
## Related
-- [Avatar reconstruction pipeline](#sec-113): the full engine: MediaPipe face-texture transfer, geometry morph, the fixed pre-rigged head template, and the Cloud Run worker.
-- [Avatar pipeline](#sec-112): the distinct Forge text-to-3D generation lane.
-- [Draft agent mint](#sec-177): the on-chain identity every finished reconstruction gets, the network flags, and the devnet proof script.
-- [Trait-based avatar builder](#sec-135): customize and dress the avatar after you scan it.
-- [Talking Avatar Video](#sec-397) and [Lipsync](#sec-263): drive the finished avatar's mouth.
+- [Avatar reconstruction pipeline](#sec-114): the full engine: MediaPipe face-texture transfer, geometry morph, the fixed pre-rigged head template, and the Cloud Run worker.
+- [Avatar pipeline](#sec-113): the distinct Forge text-to-3D generation lane.
+- [Draft agent mint](#sec-180): the on-chain identity every finished reconstruction gets, the network flags, and the devnet proof script.
+- [Trait-based avatar builder](#sec-137): customize and dress the avatar after you scan it.
+- [Talking Avatar Video](#sec-403) and [Lipsync](#sec-264): drive the finished avatar's mouth.
- Pages: [/create/selfie](https://three.ws/create/selfie), [/create](https://three.ws/create), [/features/scan](https://three.ws/features/scan).
---
-<a id="sec-373"></a>
+<a id="sec-378"></a>
> **Source:** `docs/share-and-embed.md` · [↑ table of contents](#table-of-contents)
@@ -79255,7 +82221,19 @@ If you manage the HTML of your page directly, the `<agent-3d>` custom element gi
<agent-3d agent-id="<your-agent-id>"></agent-3d>
```
-The element renders inline (no iframe boundary), supports keyboard navigation, and exposes a JavaScript API so you can drive the agent programmatically. See the [Embedding guide](#sec-183) for the full attribute reference and event list.
+The element renders inline (no iframe boundary), supports keyboard navigation, and exposes a JavaScript API so you can drive the agent programmatically. See the [Embedding guide](#sec-186) for the full attribute reference and event list.
+
+---
+
+## Just the avatar, nothing else
+
+If all you want on the page is the 3D avatar, without chat, voice, or any widget UI, [Avatar Artifact](#sec-107) is a one-line iframe:
+
+```html
+<iframe src="https://three.ws/avatar-artifact?agent=<your-agent-id>" width="100%" height="600" style="border:0" loading="lazy" title="Avatar Artifact"></iframe>
+```
+
+It renders your agent's avatar, follows the visitor's cursor, and links back to the profile. Open the page itself and click **Copy embed** to get the snippet already pointed at your agent.
---
@@ -79284,14 +82262,14 @@ To customize the preview image, change the agent's thumbnail in the editor.
## What's next
-- **Make your agent smarter** → [Skills system](#sec-381)
-- **Understand the technical embed options** → [Embedding guide](#sec-183)
-- **Payment and crypto questions** → [Do I need crypto?](#sec-175)
-- **Give it a permanent on-chain address** → [Register on-chain](#sec-456)
+- **Make your agent smarter** → [Skills system](#sec-387)
+- **Understand the technical embed options** → [Embedding guide](#sec-186)
+- **Payment and crypto questions** → [Do I need crypto?](#sec-178)
+- **Give it a permanent on-chain address** → [Register on-chain](#sec-462)
---
-<a id="sec-374"></a>
+<a id="sec-379"></a>
> **Source:** `docs/shared-utilities.md` · [↑ table of contents](#table-of-contents)
@@ -79511,7 +82489,7 @@ paused during an incident and never resumed, failed silently.
---
-<a id="sec-375"></a>
+<a id="sec-380"></a>
> **Source:** `docs/showcase.md` · [↑ table of contents](#table-of-contents)
@@ -79521,7 +82499,7 @@ paused during an incident and never resumed, failed silently.
That filter is the whole point of the surface. The ERC-8004 registries hold plenty of agents that are only an address and a URI. The showcase answers a narrower question: which of them can actually be seen and embedded.
-Live at [three.ws/showcase](https://three.ws/showcase). Related reading: [ERC-8004](#sec-185) for the identity standard itself, [on-chain deployments](#sec-172) for the live feed of every registration as it lands (with no avatar filter), and [on-chain agents](#sec-301) for registering one yourself.
+Live at [three.ws/showcase](https://three.ws/showcase). Related reading: [ERC-8004](#sec-188) for the identity standard itself, [on-chain deployments](#sec-175) for the live feed of every registration as it lands (with no avatar filter), and [on-chain agents](#sec-304) for registering one yourself.
Code: [api/showcase.js](../api/showcase.js). Data comes from `erc8004_agents_index`, populated by the `erc8004-crawl` cron.
@@ -79580,14 +82558,14 @@ Each agent carries its on-chain identity plus explorer links resolved from the c
## Related
-- [ERC-8004](#sec-185): the identity standard behind every row here.
-- [On-chain deployments](#sec-172): the same registration stream without the 3D filter, including Solana Metaplex Core mints.
-- [Deploy agents on-chain](#sec-301): how to register an agent so it can appear here.
+- [ERC-8004](#sec-188): the identity standard behind every row here.
+- [On-chain deployments](#sec-175): the same registration stream without the 3D filter, including Solana Metaplex Core mints.
+- [Deploy agents on-chain](#sec-304): how to register an agent so it can appear here.
- [Agent manifest](#sec-055): the metadata format whose 3D model field decides `has_3d`.
---
-<a id="sec-376"></a>
+<a id="sec-381"></a>
> **Source:** `docs/sign-language.md` · [↑ table of contents](#table-of-contents)
@@ -79697,9 +82675,9 @@ Another 41 everyday spellings route to those same signs, so ordinary sentences w
- **Click a key, or press it.** Typing `q` signs a Q. A single letter holds its pose so you can study it; a word settles back to rest the way a signer finishes.
- **Every letter is described**, with the letters it is confused with named explicitly (F against 9, M against N, K against V, G against Q). Look-alikes are where reading breaks down, so they are called out rather than left to be discovered.
-- **Spell any word** and each key lights up as the hand reaches it. The highlight comes from the clip builder itself, not from a timer guessed alongside it, so it stays in step at any speed.
+- **Spell any word** and each key lights up as the hand reaches it. The word is also laid out under the input, one cell per letter, lit in the same cadence, so a long word can be followed without scrolling back to the A-to-Z grid. The highlight comes from the clip builder itself, not from a timer guessed alongside it, so it stays in step at any speed.
- **Practice reading it**, which is the harder half. The avatar spells a letter or a word, you type what you read, and your streak is kept on the device.
-- Deep links: `?letter=W` opens a letter, `?spell=HELLO` spells a word.
+- Deep links: `?letter=W` opens a letter, `?spell=HELLO` spells a word. The link is read before the page builds anything, so the letter's description, its look-alike note and its pressed key are on screen immediately and the avatar catches up when the rig finishes loading.
Speed, signing hand, and avatar are the same settings as /sign-language, stored under the same key, so a left-handed signer sets that once for both pages. That includes [your own avatar](#sign-with-your-own-avatar): pick it on either page and it forms the letters on both.
@@ -79755,7 +82733,7 @@ Best results: good light, hand in frame, one letter at a time, and hold the last
## In your own site or app
-The [web component](#sec-502) exposes signing as an attribute. Present at boot, or toggled at runtime, it does the same thing:
+The [web component](#sec-508) exposes signing as an attribute. Present at boot, or toggled at runtime, it does the same thing:
```html
<script type="module" src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>
@@ -80100,13 +83078,13 @@ None of this replaces a human interpreter. It makes an avatar legible to signers
- [examples/sign-language.html](../examples/sign-language.html), a runnable page with both integration paths
- [Animation Studio](#sec-092), the Spell box, exports, and share links
- [docs/animations.md](#sec-093), clip formats and the retarget engine
-- [docs/web-component.md](#sec-502), every `<agent-3d>` attribute including `sign-language`
+- [docs/web-component.md](#sec-508), every `<agent-3d>` attribute including `sign-language`
- [workers/model-asl-recognition](../workers/model-asl-recognition/README.md), the recognition model and its licensing
- [Motion Swap](https://three.ws/motion-swap), video motion capture, including hands
---
-<a id="sec-377"></a>
+<a id="sec-382"></a>
> **Source:** `docs/signals.md` · [↑ table of contents](#table-of-contents)
@@ -80205,22 +83183,22 @@ curl -s https://three.ws/api/signals/subscribe -H 'authorization: Bearer YOUR_TO
## Related
-- [Custody you can verify](#sec-167) - the spend caps, freeze, and audit trail the subscriber wallet pays and trades under
-- [Financial controls](#sec-219) - the plain-English rules and firewall the mirror respects
-- [Oracle](#sec-310) - the conviction engine and its own follow/copy tier
-- [x402](#sec-519) - the USDC payment protocol every signal settles over
-- [Trader card](#sec-403) - the verified track record that regresses a feed's edge
+- [Custody you can verify](#sec-170) - the spend caps, freeze, and audit trail the subscriber wallet pays and trades under
+- [Financial controls](#sec-221) - the plain-English rules and firewall the mirror respects
+- [Oracle](#sec-315) - the conviction engine and its own follow/copy tier
+- [x402](#sec-544) - the USDC payment protocol every signal settles over
+- [Trader card](#sec-409) - the verified track record that regresses a feed's edge
- [/leaderboard](https://three.ws/leaderboard) - build a verified record, then publish a feed of your own
---
-<a id="sec-378"></a>
+<a id="sec-383"></a>
> **Source:** `docs/site-performance.md` · [↑ table of contents](#table-of-contents)
# What the site's load numbers are, and the four rules that keep them there
-`/play` has [its own boot-cost document](#sec-320) because a coin world is a special case: a WebGL renderer, a physics solver and a multiplayer room all have to start before anything is playable. This document covers everything else. Every ordinary page on three.ws is a static HTML document plus a module graph, and the cost of opening one is almost entirely decided by four questions:
+`/play` has [its own boot-cost document](#sec-325) because a coin world is a special case: a WebGL renderer, a physics solver and a multiplayer room all have to start before anything is playable. This document covers everything else. Every ordinary page on three.ws is a static HTML document plus a module graph, and the cost of opening one is almost entirely decided by four questions:
1. How many bytes of JavaScript run before the page is usable?
2. How much of the DOM does the browser lay out that nobody can see?
@@ -80249,25 +83227,39 @@ Two things to know before reading a report:
- **The score is not the byte count.** Performance is weighted Total Blocking Time 30%, Largest Contentful Paint 25%, Cumulative Layout Shift 25%, First Contentful Paint 10%, Speed Index 10%. A page can ship 4 MB and score well if none of it blocks; a page can ship 900 KB and score badly if all of it runs at once.
- **Lighthouse 13 removed the audits everyone quotes.** `offscreen-images`, `uses-responsive-images`, `modern-image-formats` and `dom-size` are gone, replaced by the insight family: `image-delivery-insight`, `render-blocking-insight`, `cache-insight`, `legacy-javascript-insight`, `cls-culprits-insight`. A script that reads the old audit names throws on `undefined`.
+- **Keep `--disable-gpu`. Do not "improve" it to software WebGL.** Swapping it for `--use-gl=angle --use-angle=swiftshader` looks more faithful, since the 3D pages then really run their renderers, and it does not survive contact with this site: in the 2026-08-15 sweep that flag set made `/` and `/marketplace` abort with `PAGE_HUNG`, `/play` report `NO_FCP`, and `/marketplace` still fail with `PROTOCOL_TIMEOUT` at a 90s `--max-wait-for-load` on a completely idle machine. The same pages complete in about two minutes each with `--disable-gpu`. Software rasterization of our own WebGL is slower than the throttling Lighthouse is trying to apply, so the run measures the rasterizer rather than the page.
+- **Check `environment.benchmarkIndex` in every report before quoting its score.** A shared build machine swings it wildly: the 2026-08-15 sweep saw 108 on one `/create` run and 2,398 on a `/` run twenty minutes later, and the low reading inflates every CPU-bound metric in that report. A run under roughly 800 is worth repeating on an idle machine rather than recording.
-## The 2026-08-14 baseline
+## Where the numbers are
-Every page named in this table was measured against `https://three.ws` with Lighthouse 13.4.1 on 2026-08-14. **This is the baseline, not the current state**: the live build at the time was commit `0496089f0`, stamped `2026-08-14T01:24:52Z`, which predates rules 1, 2, 3 and the model-viewer half of rule 4, plus the chip fix in `a789c2f90`. Every one of those is committed and none of them was deployed when these numbers were taken, so treat the table as the problem statement each rule below was written against.
+Two sweeps, same eight pages, same tool (Lighthouse 13.4.1), same flags, three weeks apart in build terms. The first is the problem statement the rules below were written against; the second is what the deployed rules are worth.
-| Page | Desktop | Mobile | Desktop TBT | Desktop CLS | Desktop bytes |
-|---|---|---|---|---|---|
-| `/` | 33 | 25 | 19,340ms | 0.009 | 3,715 KiB |
-| `/create` | 38 | 25 | 6,940ms | 0.013 | 1,892 KiB |
-| `/forge` | 32 | 20 | 12,560ms | 0.232 | 4,243 KiB |
-| `/marketplace` | 23 | 17 | 51,400ms | 0.178 | 4,748 KiB |
-| `/play` | 31 | 25 | 5,870ms | 0 | 2,317 KiB |
-| `/docs` | 39 | 35 | 4,490ms | 0.028 | 701 KiB |
-| `/discover` | 54 | 44 | 11,010ms | 0.022 | 10,952 KiB |
-| `/chat` | 28 | 25 | 6,390ms | 0.001 | 4,435 KiB |
+**2026-08-14**, against commit `0496089f0` (stamped `2026-08-14T01:24:52Z`), which predates rules 1, 2, 3 and the model-viewer half of rule 4.
+
+**2026-08-15**, against commit `7505b83ca` (stamped `2026-08-15T07:08:00Z`), which contains all of them.
+
+| Page | Desktop 08-14 | Desktop 08-15 | Mobile 08-14 | Mobile 08-15 | Desktop TBT 08-14 | Desktop TBT 08-15 |
+|---|---|---|---|---|---|---|
+| `/` | 33 | **91** | 25 | 48 | 19,340ms | 134ms |
+| `/create` | 38 | **94** | 25 | 51 | 6,940ms | 0ms |
+| `/forge` | 32 | **75** | 20 | 31 | 12,560ms | 55ms |
+| `/marketplace` | 23 | **58** | 17 | 20 | 51,400ms | 168ms |
+| `/play` | 31 | **83** | 25 | 41 | 5,870ms | 101ms |
+| `/docs` | 39 | **93** | 35 | 47 | 4,490ms | 107ms |
+| `/discover` | 54 | **88** | 44 | 58 | 11,010ms | 266ms |
+| `/chat` | 28 | **60** | 25 | 55 | 6,390ms | 0ms |
+
+Total blocking time was what held every score in the first column down, and it is 30% of the weighting on its own. It is now effectively gone from all eight pages. **Read a Lighthouse report by which metric is losing the points, not by the score**, because the answer changes once you fix something: on the three pages still under 80, blocking time now costs 4.2 points at worst and the loss has moved somewhere else entirely.
+
+| Page still under 80 | Losing | To |
+|---|---|---|
+| `/forge` 75 | 13.3 pts | CLS 0.260, of which 0.190 is one shift on the example-prompt row (rule 6) |
+| `/marketplace` 58 | 19.8 pts + 13.0 pts | LCP 3,649ms, and CLS 0.257 of which 0.178 is one shift on the podium (rule 5) |
+| `/chat` 60 | 21.0 + 9.9 + 9.0 pts | LCP, FCP and Speed Index, all of them one 4,277 KiB chunk (see the open items) |
-Total blocking time is what holds every one of these scores down, and it is 30% of the weighting on its own. Read the table by that column, not by the score.
+Full desktop detail for the 2026-08-15 run: CLS `/` 0.002, `/create` 0.014, `/forge` 0.260, `/marketplace` 0.257, `/play` 0.000, `/docs` 0.043, `/discover` 0.044, `/chat` 0.001. Transferred bytes `/` 3,272 KiB, `/create` 1,804 KiB, `/forge` 8,254 KiB, `/marketplace` 3,987 KiB, `/play` 2,265 KiB, `/docs` 706 KiB, `/discover` 4,885 KiB, `/chat` 4,627 KiB.
-Two caveats worth knowing when you compare a later run against this one. The runs were taken on a shared build machine with other work in flight, so single-page scores move a few points between runs: `/create` measured 50 in a quieter run earlier the same day and 38 here. And `/marketplace` is heavy enough that Lighthouse itself gave up with `PROTOCOL_TIMEOUT` on the first attempt and needed a 90s `--max-wait-for-load` to complete at all, which is a finding in its own right.
+Both sweeps were taken on a shared build machine, so single-page scores move a few points between runs; see the `benchmarkIndex` note above before quoting one.
---
@@ -80338,6 +83330,39 @@ Measured honestly, that last one is the smallest of the three: at 1350x940 the s
**A new `<model-viewer>` on a multi-viewer page ships `data-src`, or it is eager.** There is no third option, and the attribute that looks like it should handle this does not.
+### The site footer is the lowest thing on every page, so its 3D bot loads last
+
+The rule above was written about sections. The most expensive violation of it was not a section at all: it was the decorative robot in the site footer, and it was costing more than everything the rule had already caught.
+
+[public/footer.js](../public/footer.js) injects `/footer.html` into any page holding `<div id="footer-container">`, which is roughly 175 pages. That markup contains `#footer-bot-canvas`, and the injector booted its renderer immediately, at `DOMContentLoaded`, down one of two branches:
+
+- A page carrying `<meta name="has-three-bundle">` (every Vite-built page) loaded `/footer-bot.js`, which builds a `WebGLRenderer`, claims a context off the shared budget in [src/webgl-budget.js](../src/webgl-budget.js), and loads `robotexpressive.glb`.
+- A plain HTML page (login, register, the dashboard, `/docs`, `/discover`) instead pulled **`model-viewer` from `ajax.googleapis.com`, a second complete 3D engine**, plus the meshopt shim and the same GLB.
+
+Measured against production on 2026-08-15, that decoration was the single largest main-thread consumer on the page it landed on:
+
+| Page | Branch | Cost, eager |
+|---|---|---|
+| `/forge` | `footer-bot.js` | **19,654ms** of bootup, more than the page's own bundle (1,473ms) |
+| `/docs` | `model-viewer` | 839ms of bootup and 253 KiB transferred, on a 701 KiB page |
+| `/create` | `footer-bot.js` | 107 KiB GLB plus a WebGL context, on a page already running Three.js |
+
+`loading="lazy"` on the `<model-viewer>` element did not help, and could not: it defers the *model*, while the 253 KiB module that defines the element had already been fetched and evaluated.
+
+Both branches now sit behind `whenNearViewport()` in the same file, an `IntersectionObserver` on `.h-footer-avatar` at `rootMargin: '600px 0px'`, so the bot loads a screenful before the footer arrives and is rendered by the time it is on screen. Browsers without `IntersectionObserver` load it on the first scroll instead, so it still appears on the way down rather than never.
+
+Verified by loading the real production pages twice in the same browser, the second time with only `/footer.js` swapped for the working-tree file, then scrolling to the footer to confirm the bot still arrives:
+
+| Page | Transferred, before | after | Long tasks, before | after | Footer bot loaded on open | after scrolling |
+|---|---|---|---|---|---|---|
+| `/docs` | 675 KiB | **426 KiB** | 62ms | **17ms** | yes | yes |
+| `/forge` | 7,379 KiB | 7,283 KiB | 426ms | **138ms** | yes | yes |
+| `/create` | 2,215 KiB | **1,528 KiB** | 8,422ms | **2,510ms** | yes | yes |
+
+Deferring it also fixes an ordering bug nobody had filed. The footer bot reserved a WebGL context at `DOMContentLoaded`, ahead of the `<agent-3d>` instances the visitor came to look at; on a page near the browser's context limit the decoration could win and a real avatar lose. Now the content claims contexts first and the footer takes what is left, which is what `reserveWebGLContext()` was always for. The bot's own failure path already degrades to an empty canvas, so losing that race is silent and harmless.
+
+**Anything injected into a shared chrome partial follows this rule too.** A cost paid in the footer is a cost paid on every page on the site, which makes it the most expensive place on the platform to be careless.
+
**Before you gate something, check where it actually is.** Paste this into DevTools:
```js
@@ -80358,6 +83383,22 @@ The box is reserved by CSS rather than by `width`/`height` attributes, because t
**A reserved box is not optional.** If you add a thumbnail whose container has no `aspect-ratio` and no fixed height, add one, or the late image will shift everything under it.
+### A skeleton only reserves the box if it is the same size as the thing it replaces
+
+`/marketplace` had a skeleton, a comment saying it existed "so there's no layout jump when data arrives", and the largest layout shift on the page. Both halves of it were wrong, and each is worth recognising on sight.
+
+**A section that JavaScript reveals reserves nothing.** `#mkt-top-section` shipped `hidden`, and `loadTopPerformers()` in [src/marketplace.js](../src/marketplace.js) cleared that only once it ran. `hidden` is `display: none`, so until the page bundle executed, the section occupied zero pixels; then the whole 271px of it appeared and pushed the grid, the pulse strip and everything below them down. That single reveal measured **0.178 of the page's 0.257 desktop CLS**. The skeleton could not help, because the skeleton was inside the thing that did not exist yet.
+
+**A placeholder that is not the size of the real card is a second shift, not a fix.** Measured on production at six viewport widths, the skeleton podium was **190px against a loaded podium of 235px** on desktop, so the swap moved the page again by 45px.
+
+Both are fixed in the markup rather than the module. The section ships visible with its three placeholder cards in [pages/marketplace.html](../pages/marketplace.html), so the box exists in the first frame; `.mkt-top-card` carries a `min-height` (235px, and 72px in the 640px query) that the placeholder and the loaded card both obey, so the swap is a no-op for layout. `loadTopPerformers()` now only replaces the podium's contents, clears the `aria-busy` it ships with, or hides the section when the feed is empty.
+
+Below 640px the podium is a single column, which makes the placeholder *count* decide its height rather than just the card size, so the 640px query hides every placeholder after the first. Three placeholders there would have reserved three rows for a feed that currently returns one agent, and over-reserving shifts the page exactly as surely as under-reserving; that was a regression introduced and caught inside this change, not a pre-existing one.
+
+Two residuals are measured and left, both smaller than what they replace. If the leaderboard starts returning three agents, the mobile column grows from one row to three (a 160px shift, against the 268px the same load costs today). And a name long enough to wrap grows a loaded card past the 72px floor at 390px and narrower, by 14px to 32px. Reserving for a count you do not know yet is not solvable in CSS; reserving for the card you do know is.
+
+**A loading state is a size before it is a shimmer.** Build it out of the same element as the real thing, ship it in the HTML, and check both heights in the browser rather than assuming they match.
+
## 6. Whoever writes a node's text owns it, and i18n has to be told
**Invariant: JavaScript that replaces the text of an element carrying `data-i18n` removes the attribute in the same statement.**
@@ -80377,8 +83418,45 @@ function setChipPrompt(chip, text) {
**Any node whose text becomes dynamic loses its `data-i18n` at the point it becomes dynamic.** Not later, not in a cleanup pass. `src/i18n.js` uses the same guard for `data-auth-name` in the nav.
+### That fixed the revert. It did not fix the growth.
+
+The 2026-08-15 sweep ran against a build that already contained the fix above, and `/forge` still measured **CLS 0.256 desktop, 0.263 mobile, with `<div class="chips" id="examples">` still named as the largest single shift at 0.190**. Removing the revert removed one direction of a shift that had two.
+
+The remaining direction was the first one: static labels to seeded labels. The static markup shipped five short examples ("a potted monstera plant") totalling 132 characters, and `seedChips()` replaced them on every JS visit with generated prompts capped at 64 characters each. The generator's own distribution is the whole story: a prompt averages 53.5 characters and cannot go below 29, so the seeded row averaged 268 characters and could reach 320. **The row a visitor sees was always more than twice as wide as the row first paint reserved for it**, and `.chips` is `flex-wrap`, so the difference arrived as extra lines that pushed the composer and everything under it down.
+
+There is no way to generate a row narrow enough to fit the old markup. Only **three distinct prompts in the entire grammar** are 37 characters or shorter, so a per-label cap tight enough to match the static copy would leave the row with duplicates. The reservation has to move to meet the content, not the other way round:
+
+- The labels in [pages/forge.html](../pages/forge.html) are now written at the 64-character cap, so first paint reserves the row's worst case. Both rows carry `data-no-i18n`, which keeps `scripts/i18n-annotate.mjs` from re-adding the attribute the section above exists to remove. The generated replacements are English at every locale, so a translated label was only ever visible for the instant before it was overwritten.
+- `generateForgeChipSet()` in [src/forge-prompt-gen.js](../src/forge-prompt-gen.js) fits a rotation inside the character budget of the labels it replaces, so it can never exceed the reservation. It walks the candidate pool in generated order to keep the row varied, accepting a prompt only while the shortest remaining candidates could still fill the leftover slots.
+- `pinRowHeight()` holds the row at its measured height across the swap, so a rotation that wraps onto *fewer* lines cannot shift the page upward either. The pin is released on the first resize, which relayouts the page anyway.
+
+[tests/forge-prompt-gen.test.js](../tests/forge-prompt-gen.test.js) reads the labels out of `pages/forge.html` rather than copying them, so shortening the shipped copy fails the suite instead of silently restoring the shift.
+
+Verified against the live page's own CSS by replacing the row's contents and measuring its height, six viewport widths, sixty random rotations each. The growth column is what the page shifts by:
+
+| Viewport | Reserved, before | Seeded, before | Growth | Reserved, after | Seeded, after | Growth |
+|---|---|---|---|---|---|---|
+| 1440px | 99px | 202px | **103px** | 202px | 202px | **0px** |
+| 1350px | 99px | 202px | **103px** | 202px | 202px | **0px** |
+| 1024px | 63px | 99px | **36px** | 99px | 99px | **0px** |
+| 768px | 64px | 167px | **103px** | 133px | 133px | **0px** |
+| 390px | 194px | 295px | **101px** | 295px | 295px | **0px** |
+| 320px | 244px | 295px | **51px** | 295px | 295px | **0px** |
+
+**A static placeholder is a space reservation before it is copy.** If JavaScript is going to replace it, size the placeholder like the thing that replaces it, and make the replacement fit.
+
---
+## Open: three costs the 2026-08-15 sweep measured and did not fix
+
+Each of these is the largest remaining number on the page it belongs to, and each one lands in a surface the sweep that found it had no business rewriting. They are recorded here with the measurement so the next pass starts from a number rather than a hunch.
+
+**`/chat` is one 4,277 KiB JavaScript chunk.** The page makes 23 requests and `chat/assets/index-*.js` is 4,277 KiB of them; nothing renders until it has parsed, which is the entire story of its FCP (3,901ms desktop, 23,105ms mobile) and of an LCP that lands 140ms later. Blocking time is *one millisecond*, so no amount of deferring helps: the work is a single parse of a single chunk. [chat/vite.config.js](../chat/vite.config.js) sets no `manualChunks` and no `inlineDynamicImports`; the app simply imports everything statically from its entry, so Vite has nothing to split on. The fix is dynamic imports at the route and feature boundaries inside `chat/src`, which is a refactor of the sub-app rather than a build-config change.
+
+**`/forge` showcase thumbnails are full-size renders.** Twelve images from `pub-*.r2.dev` account for **6,273 KiB of the page's 8,339 KiB**, averaging 520 KB each. They are the 768x768 PNGs that [api/\_lib/forge-thumbs.js](../api/_lib/forge-thumbs.js) generates (`THUMB_SIZE = 768`), painted into a 200px-tall box. `loading="lazy"` and `decoding="async"` are already set per rule 5, so this is not a scheduling problem, it is a format and size problem: the same renders as WebP at a display-appropriate size are roughly a tenth of the bytes. The fix has to change the generator, re-run the backfill cron over existing rows, and handle the `forge/thumb/<id>.png` key extension that `forgeThumbKeyFor()` and the stored `preview_image_url` values both encode. One outlier in the same trace is a data-freshness artifact rather than a bug: a 2,358 KiB `forge/<clientKey>/<id>.png` is the untouched original for a row the backfill has not reached yet.
+
+**The brand mark is an 85 KB SVG rendered at 22 pixels.** `public/three.svg` and the byte-identical `public/favicon.svg` are 85,257-byte SVGs wrapping two 800x436 PNGs behind `feColorMatrix` filters. They are referenced from 171 files, cost 62 KiB over the wire per page, and no call site in the repo renders the mark above 64 CSS px. Re-encoding the embedded rasters at exactly half resolution (800 to 400, lanczos3, no palette quantization) takes the file to 36,913 bytes and is visually indistinguishable at every size the site uses, with a maximum channel delta of 4 at 22px and 10 at 64px. It is not free above that: at 192px, which some platforms use for an SVG favicon, the delta reaches 105. Fractional downscales are much worse than the exact half (320px wide measured a delta of 78 at 22px), so this is a brand-asset decision with a measured cost attached, not a mechanical resize, and it needs the owner rather than a sweep.
+
## Open: directory thumbnails are served with no cache headers at all
This one is measured, understood, and deliberately not fixed yet, because the safe fix is larger than it looks.
@@ -80403,7 +83481,7 @@ Two things in the numbers above are real and are not being fixed by tuning:
---
-<a id="sec-379"></a>
+<a id="sec-384"></a>
> **Source:** `docs/sketchfab.md` · [↑ table of contents](#table-of-contents)
@@ -80493,7 +83571,204 @@ and [`api/_lib/sketchfab.js`](https://github.com/nirholas/three.ws/blob/main/api
---
-<a id="sec-380"></a>
+<a id="sec-385"></a>
+
+> **Source:** `docs/skill-bundles.md` · [↑ table of contents](#table-of-contents)
+
+# Skill bundles
+
+A **skill bundle** sells several of one agent's skills as a single purchase. One
+payment, one confirmation, and every skill in the bundle unlocks at once.
+
+The hard part of a bundle was never grouping the skills. It was the price. The
+usual answer is "take 20% off the sum of the parts", which is a guess dressed as
+advice. three.ws answers it from the seller's own ledger instead: some buyers have
+already bought two or more of these skills separately, and what they actually paid
+is real evidence of what the combination is worth.
+
+Build one at **[three.ws/bundles](https://three.ws/bundles)**. The page is
+owner-only: it lists the agents you own, the skills on each that carry an active
+price, and a price panel that backtests any price you type against those buyers.
+
+> Source: [`pages/bundles.html`](../pages/bundles.html) (the builder),
+> [`api/agents/[id]/bundles.js`](../api/agents/[id]/bundles.js) (management and
+> pricing), [`api/_lib/bundle-pricing.js`](../api/_lib/bundle-pricing.js) (the
+> arithmetic), [`api/marketplace/purchase-bundle.js`](../api/marketplace/purchase-bundle.js)
+> (checkout and unlock).
+
+---
+
+## How the price is derived
+
+Two bases, and the API always says which one it used, so a default is never
+mistaken for a finding.
+
+| `history.basis` | When | What the suggested price is |
+|---|---|---|
+| `median_basket` | At least one buyer bought 2+ of the selected skills | The **median** of what those buyers really spent across them, capped at the sum of the parts |
+| `discount_off_list` | Nobody has bought 2+ of them yet | A flat **20% off** the sum of the parts, labelled as a starting point |
+
+Only confirmed, paid purchases count. Trials and access rows granted by an earlier
+bundle are excluded (`kind` is filtered to the paid kinds
+[`api/_lib/marketplace-kinds.js`](../api/_lib/marketplace-kinds.js) publishes), so
+nothing inflates the evidence a seller is shown.
+
+Every amount in and out of these endpoints is an **atomic integer as a string**
+(the currency's smallest unit). A 9-decimal mint puts real balances past
+`Number.MAX_SAFE_INTEGER`, so the server carries every amount as a BigInt and the
+browser scales through `BigInt` too. `mint_decimals` in the pricing response is
+how a client turns an atomic amount into a human one.
+
+---
+
+## Endpoints
+
+All four live under the agent. `:id` is the agent's UUID.
+
+| Method | Path | Auth | Does |
+|---|---|---|---|
+| `GET` | `/api/agents/:id/bundles` | public | List the agent's active bundles |
+| `GET` | `/api/agents/:id/bundles?include_inactive=1` | owner | The same list with paused bundles included |
+| `GET` | `/api/agents/:id/bundles?action=pricing&skills=a,b` | public | Price a candidate bundle against real sales |
+| `POST` | `/api/agents/:id/bundles` | owner | Publish a bundle |
+| `PATCH` | `/api/agents/:id/bundles/:bundleId` | owner | Rename, reprice, or change its skills |
+| `DELETE` | `/api/agents/:id/bundles/:bundleId` | owner | Deactivate it (nothing is deleted) |
+
+Owner calls need a session cookie (plus the `x-csrf-token` header that
+[`src/api.js`](../src/api.js) attaches automatically in the browser) or a bearer
+token. The two `GET`s are public on purpose: they read only aggregate counts and
+the agent's own list prices, both of which the marketplace already publishes per
+skill. No buyer identity and no row-level history ever leaves the handler.
+
+### Price a candidate bundle
+
+```bash
+curl -s "https://three.ws/api/agents/$AGENT_ID/bundles?action=pricing&skills=research,summarize"
+```
+
+```json
+{
+ "data": {
+ "agent_id": "00000000-0000-4000-8000-00000000a9e7",
+ "currency_mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
+ "chain": "solana",
+ "mint_decimals": 6,
+ "skills": [
+ { "skill": "research", "list_amount": "2000000", "units_sold": 0, "gross_atomic": "0", "buyers": 0 },
+ { "skill": "summarize", "list_amount": "1000000", "units_sold": 0, "gross_atomic": "0", "buyers": 0 }
+ ],
+ "unpriced_skills": [],
+ "sum_of_parts_atomic": "3000000",
+ "history": {
+ "multi_skill_buyers": 0,
+ "revenue_atomic": "0",
+ "median_basket_atomic": null,
+ "basis": "discount_off_list"
+ },
+ "suggested": {
+ "price": "2400000",
+ "discount_atomic": "600000",
+ "discount_percent": 20,
+ "backtest_revenue_atomic": "0",
+ "revenue_delta_atomic": "0",
+ "buyers_better_off": 0
+ },
+ "asked": null
+ }
+}
+```
+
+Add `&price=<atomic>` to backtest a specific price. The response's `asked` block
+then carries the same shape as `suggested` for that price: what the bundle would
+have collected from the same buyers (`backtest_revenue_atomic`), how that compares
+to what they really paid (`revenue_delta_atomic`, negative means the price left
+money on the table), and how many of them would have come out ahead
+(`buyers_better_off`). The builder page calls exactly this as you drag the price.
+
+A skill you named that has no active price is not silently dropped: it comes back
+in `unpriced_skills` and is left out of the sum. Skills priced in **different
+mints** are refused with `409 mixed_currency`, because adding two currencies
+produces a number that means nothing.
+
+### Publish
+
+```bash
+curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/bundles" \
+ -H "authorization: Bearer $THREE_WS_TOKEN" \
+ -H "content-type: application/json" \
+ -d '{
+ "name": "Research starter pack",
+ "description": "Research plus summarize, one payment.",
+ "price_amount": "2400000",
+ "currency_mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
+ "chain": "solana",
+ "skills": ["research", "summarize"]
+ }'
+```
+
+`price_amount` takes an atomic integer as a string or a number; a string is the
+safe form on a 9-decimal mint. `skills` needs at least two names and takes at most
+fifty. The response is `201` with the created bundle and its skills.
+
+`DELETE` sets `is_active = false`. Buyers who already paid keep their access,
+because access lives on their `skill_purchases` rows, not on the bundle.
+
+Pausing is reversible. `PATCH` with `{"is_active": true}` puts the bundle back on
+sale, and `include_inactive=1` is how you find it again: the plain `GET` is the
+buyer-facing list and stays active-only, so a paused bundle is returned only to a
+session that owns the agent. Anyone else passing the flag gets the public list
+unchanged. The builder page uses exactly this, which is why a paused bundle stays
+on screen, dimmed, with a **Reactivate** button.
+
+---
+
+## Checkout
+
+A bundle is bought through the marketplace, not through the bundle endpoints:
+
+```
+POST /api/marketplace/purchase-bundle { "bundle_id": "..." }
+POST /api/marketplace/purchase-bundle/:id/confirm { } # Solana
+POST /api/marketplace/purchase-bundle/:id/confirm { "tx_signature": "0x..." } # EVM
+```
+
+`create` writes a `pending` row in `bundle_purchases` and returns Solana Pay
+parameters: recipient (the creator's payout wallet), `price_amount`,
+`currency_mint`, `chain`, a freshly minted `reference`, and the platform fee split.
+`confirm` proves the payment on-chain **before** anything unlocks: Solana is
+located by the reference the server minted (no client-supplied signature is
+trusted), EVM by the submitted tx hash. On a confirmed verdict the handler writes
+one `skill_purchases` row per skill with `kind = 'bundle'` and `amount = 0`, which
+is what [`hasSkillAccess()`](../api/_lib/skill-access.js) reads, and records a
+single bundle-level revenue event so one bundle sale is never counted as N skill
+sales in GMV.
+
+**Reach today:** the builder, the two public `GET`s, and this checkout are live.
+The buyer-facing *browser* surface is not: no marketplace or agent-profile view
+renders a published bundle yet, so a human buyer reaches one through the API
+above, while the seller-side builder is fully wired. Rendering bundles on the
+agent's marketplace listing is the next step.
+
+---
+
+## Storage
+
+| Table | Holds |
+|---|---|
+| `skill_bundles` | One row per bundle: name, description, `price_amount`, `currency_mint`, `chain`, `is_active` |
+| `bundle_items` | The skill names in a bundle, one row each |
+| `bundle_purchases` | One row per checkout: status, reference, tx signature, platform fee |
+| `skill_purchases` | The unlock itself, one row per skill, `kind = 'bundle'` |
+
+## Related
+
+- [Marketplace](#sec-270): how skills and assets are listed, bought, and settled
+- [Agent skills](#sec-060): what a skill is in the first place
+- [Agent wallets](#sec-072): where a bundle's payment lands
+
+---
+
+<a id="sec-386"></a>
> **Source:** `docs/skill-royalties.md` · [↑ table of contents](#table-of-contents)
@@ -80699,14 +83974,14 @@ whose pending balance clears $0.01, so nobody pays gas to move dust.
## Related
-- [Skills marketplace](#sec-381): publishing, pricing, and installing skills
-- [x402 endpoints](#sec-514): every paid endpoint and who each one pays
-- [Money map](#sec-286): how value moves across the whole platform
-- [Remix royalties](#sec-360): the parallel royalty rail for 3D creations
+- [Skills marketplace](#sec-387): publishing, pricing, and installing skills
+- [x402 endpoints](#sec-539): every paid endpoint and who each one pays
+- [Money map](#sec-287): how value moves across the whole platform
+- [Remix royalties](#sec-365): the parallel royalty rail for 3D creations
---
-<a id="sec-381"></a>
+<a id="sec-387"></a>
> **Source:** `docs/skills.md` · [↑ table of contents](#table-of-contents)
@@ -81428,10 +84703,31 @@ Installing is free and instant (`POST /api/skills/:id/install`, sign-in required
- **Knowledge skills load into your chats.** `/api/chat` reads your installed skills at request time (`api/_lib/installed-skills.js`) and injects their playbooks into the system prompt, so your agent follows them anywhere you chat signed-in on three.ws (the `/app` workspace included). Budgets keep prompts sane: newest 8 installs, 6k chars per skill, 24k total. Each reply's SSE `done` event lists the slugs that were in context as `skills_applied`.
- **Your installed set is one API call away.** `GET /api/skills?installed=true` (authed) returns the full payload, `content` and `schema_json` included, so an external agent, MCP client, or script can hydrate itself from your library.
-Paid skills price per *call*, not per install: the detail page shows an x402 endpoint (`GET /api/x402/skill-call?skill=<slug>`) any wallet can pay in USDC, settling to the author. The 402 challenge names the author's own wallet as the payee, so their share moves at settlement rather than being forwarded later, and Solana is offered first whenever the author has a Solana wallet. What the author keeps, where they watch it land, and how to verify a payout on-chain: [Skill royalties](#sec-380).
+Paid skills price per *call*, not per install: the detail page shows an x402 endpoint (`GET /api/x402/skill-call?skill=<slug>`) any wallet can pay in USDC, settling to the author. The 402 challenge names the author's own wallet as the payee, so their share moves at settlement rather than being forwarded later, and Solana is offered first whenever the author has a Solana wallet. What the author keeps, where they watch it land, and how to verify a payout on-chain: [Skill royalties](#sec-386).
Publish your own from the marketplace ("Publish a Skill") or `POST /api/skills` with `{ name, slug, description, category, tags, content }` (or `schema_json`).
+### Browsing the catalog from code
+
+`GET /api/skills` is public and takes the same filters the marketplace UI uses, so a script can reproduce any view you can link to:
+
+| Param | Meaning |
+| --- | --- |
+| `q` | Substring match across name, description, and tags |
+| `category` | Exact category slug (`GET /api/skills/categories` lists them with counts) |
+| `tag` | Exact tag, case-insensitive, matched against the skill's `tags` array |
+| `sort` | `popular` (default), `new`, or `az` |
+| `limit` / `cursor` | Page size (max 50) and the keyset cursor returned as `next_cursor` |
+| `installed=true` | Authed only: your own installed set, with `content` and `schema_json` |
+
+```bash
+# Every free skill tagged "solana", newest first
+curl -s 'https://three.ws/api/skills?tag=solana&sort=new&limit=50' \
+ | jq '.skills[] | select(.price_per_call_usd == 0) | {name, slug, tags}'
+```
+
+Those filters are also the page URL, so [/marketplace?tab=skills&tag=solana&sort=new](https://three.ws/marketplace?tab=skills&tag=solana&sort=new) opens that exact view in a browser and can be shared as-is. The retired `/skills` path forwards there, carrying `q`, `category`, `tag`, and `sort` with it.
+
---
## Versioning
@@ -81447,13 +84743,13 @@ Publish your own from the marketplace ("Publish a Skill") or `POST /api/skills`
- [Architecture Overview](#sec-100) — how skills fit into the agent runtime
- [Agent System](#sec-064) — the protocol bus and built-in tool system
-- [Web Component](#sec-502) — embedding agents and passing skill attributes
+- [Web Component](#sec-508) — embedding agents and passing skill attributes
- `specs/SKILL_SPEC.md` — the authoritative skill bundle specification
- `specs/PERMISSIONS_SPEC.md` — ERC-7710/ERC-7715 delegation for fine-grained skill permissions
---
-<a id="sec-382"></a>
+<a id="sec-388"></a>
> **Source:** `docs/smart-contracts.md` · [↑ table of contents](#table-of-contents)
@@ -82111,7 +85407,7 @@ On Base at typical gas prices (~0.001 gwei base fee), an agent registration runs
---
-<a id="sec-383"></a>
+<a id="sec-389"></a>
> **Source:** `docs/smart-money.md` · [↑ table of contents](#table-of-contents)
@@ -82125,7 +85421,7 @@ API: `/api/pump/smart-money` (feed, leaderboard, per-coin, per-wallet). The coin
## Why it exists
-The single most predictive early signal on pump.fun is not the chart, it is who is buying. A wallet that has repeatedly entered coins that went on to graduate is worth watching; a wallet that dumps every launch it touches is worth avoiding. That information exists on chain, but nobody keeps a running scorecard in time. Smart Money Radar is that scorecard. It re-earns every wallet's reputation continuously from real outcomes, so a coin's "pedigree" is the buy-weighted track record of the wallets actually in it, and a wallet's rank is its own history of picking coins that graduated. This is the same proven-wallet ledger the WHO pillar of [Oracle](#sec-310) draws on, exposed as its own browsable surface.
+The single most predictive early signal on pump.fun is not the chart, it is who is buying. A wallet that has repeatedly entered coins that went on to graduate is worth watching; a wallet that dumps every launch it touches is worth avoiding. That information exists on chain, but nobody keeps a running scorecard in time. Smart Money Radar is that scorecard. It re-earns every wallet's reputation continuously from real outcomes, so a coin's "pedigree" is the buy-weighted track record of the wallets actually in it, and a wallet's rank is its own history of picking coins that graduated. This is the same proven-wallet ledger the WHO pillar of [Oracle](#sec-315) draws on, exposed as its own browsable surface.
## How it works
@@ -82210,14 +85506,14 @@ for (const c of conviction.slice(0, 5)) {
## Related
-- [Oracle: the conviction engine](#sec-310) uses this proven-wallet ledger as its WHO pillar
-- [The trading surfaces](#sec-409) map, including the Coin Intelligence cross-coin trader board
-- [Coin Radar](#sec-357) and [Mission Control](#sec-398) surface the same pedigree read inline
+- [Oracle: the conviction engine](#sec-315) uses this proven-wallet ledger as its WHO pillar
+- [The trading surfaces](#sec-415) map, including the Coin Intelligence cross-coin trader board
+- [Coin Radar](#sec-362) and [Mission Control](#sec-404) surface the same pedigree read inline
- Pages: [/smart-money](https://three.ws/smart-money) · [/radar](https://three.ws/radar) · [/oracle](https://three.ws/oracle)
---
-<a id="sec-384"></a>
+<a id="sec-390"></a>
> **Source:** `docs/sniper-autonomy.md` · [↑ table of contents](#table-of-contents)
@@ -82290,7 +85586,7 @@ and position size. Reaching `trusted` unlocks five more (`TIER_UNLOCKS` in
outward only. An arm with no band set is already unrestricted and nothing here
will restrict it.
- `initials_out_multiple` / `moonbag_min_pct`, the proactive
- [take-initials ladder](#sec-407): recover the stake as soon as
+ [take-initials ladder](#sec-413): recover the stake as soon as
the position hits 2x rather than waiting for an exit to trigger, and size the
moon bag that keeps riding. Turned on only for an arm whose winners
demonstrably run past its average exit. Note this is only the *early*
@@ -82391,7 +85687,7 @@ tighter rather than rewarded for the hit rate.
## Related
- [Agent Sniper](#sec-061): the trading pipeline the arms run on
-- [The 10 SOL trading experiment](#sec-407): the exit thesis the
+- [The 10 SOL trading experiment](#sec-413): the exit thesis the
ladder implements
- [`api/_lib/sniper-optimizer.js`](../api/_lib/sniper-optimizer.js): the tuning
rules, tier-scaled
@@ -82400,7 +85696,7 @@ tighter rather than rewarded for the hit rate.
---
-<a id="sec-385"></a>
+<a id="sec-391"></a>
> **Source:** `docs/social-layer.md` · [↑ table of contents](#table-of-contents)
@@ -82475,7 +85771,7 @@ a feed).
> Source: [api/users/me/feed.js](../api/users/me/feed.js). Not to be confused
> with `GET /api/feed`, the public Money Pulse ticker backed by Redis; see
-> [Money Feed](#sec-284) for that one.
+> [Money Feed](#sec-285) for that one.
## Follow graph
@@ -82626,16 +85922,16 @@ be replayed any time from the getting-started page.
## Related pages
-- [Money Feed](#sec-284): the value-movement ticker (`GET /api/feed`),
+- [Money Feed](#sec-285): the value-movement ticker (`GET /api/feed`),
a different feed from the activity feed documented here.
-- [Remix economy](#sec-360): what happens after someone finds your model in
+- [Remix economy](#sec-365): what happens after someone finds your model in
the feed or search.
- [API reference: Social & Community](api-reference.md#social--community-api)
for the full request/response contracts.
---
-<a id="sec-386"></a>
+<a id="sec-392"></a>
> **Source:** `docs/solana-pumpfun.md` · [↑ table of contents](#table-of-contents)
@@ -82798,7 +86094,7 @@ Studio config schema (validated in `widget-types.js`):
## What's intentionally not included
- **Long-lived SSE** — the feed handler runs a 90s bounded loop and lets the browser auto-reconnect; the Cloud Run request handlers aren't meant to hold a connection open indefinitely. For higher throughput, deploy the bot itself as a streaming service.
-- **On-chain signal attestations**: pump.fun signals are off-chain rows only. The platform's SPL Memo attestation layer exists (see [Solana reputation](#sec-387)), but these crawled signals are not promoted into it; that remains a future step.
+- **On-chain signal attestations**: pump.fun signals are off-chain rows only. The platform's SPL Memo attestation layer exists (see [Solana reputation](#sec-393)), but these crawled signals are not promoted into it; that remains a future step.
- **Agent-as-signer** — the watch skills are read-only; they never sign transactions. The existing `pumpfun-create / -buy / -sell` skills cover signing flows.
- **Anchor program for reputation** — still EVM-only on the on-chain path.
@@ -82822,7 +86118,7 @@ The MCP client and cron crawler are unit-tested with mocked `fetch` and `sql`. E
---
-<a id="sec-387"></a>
+<a id="sec-393"></a>
> **Source:** `docs/solana-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -82832,7 +86128,7 @@ How three.ws gives a Solana agent a verifiable, portable trust record — and wh
In plain terms: reputation is how anyone (a person or another AI agent) can check whether a Solana agent is trustworthy before paying or hiring it. You can see any agent's trust grade right now in the [Agent Passport](/agent-passport.html), and query the same data over the API described below. This page explains where those numbers come from and how to write your own on-chain vouch.
-This is the Solana companion to [Agent Reputation](#sec-056) (the why) and [ERC-8004](#sec-185) / [Reputation System](#sec-362) (the EVM how-to). If you haven't read those, start with [Agent Reputation](#sec-056) for the trust problem reputation solves. This page covers how that same problem is solved on Solana, where there is no canonical on-chain reputation registry to inherit.
+This is the Solana companion to [Agent Reputation](#sec-056) (the why) and [ERC-8004](#sec-188) / [Reputation System](#sec-367) (the EVM how-to). If you haven't read those, start with [Agent Reputation](#sec-056) for the trust problem reputation solves. This page covers how that same problem is solved on Solana, where there is no canonical on-chain reputation registry to inherit.
---
@@ -82908,7 +86204,7 @@ The crawler (`crawlAgentAttestations`) calls `getSignaturesForAddress(asset)` fr
### Staked conviction is reported net, not gross
-The `stake` block of the reputation response counts what is **still** staked. When a staker withdraws through the [Reputation Staking Market](#sec-361), the escrow writes a `threews.unstake.v1` memo naming that stake, and the conviction it expressed stops counting: withdrawn conviction is not conviction. Only the market escrow's own settlements retire anything, so a stranger cannot deflate an agent's standing with a memo naming somebody else's stake.
+The `stake` block of the reputation response counts what is **still** staked. When a staker withdraws through the [Reputation Staking Market](#sec-366), the escrow writes a `threews.unstake.v1` memo naming that stake, and the conviction it expressed stops counting: withdrawn conviction is not conviction. Only the market escrow's own settlements retire anything, so a stranger cannot deflate an agent's standing with a memo naming somebody else's stake.
The history is reported alongside the net figure rather than erased:
@@ -83001,7 +86297,7 @@ In the agent card, both registrations sit side by side as CAIP-style references
]
```
-**Reputation from the two chains is read separately, not mathematically merged.** A consumer that wants the full picture reads ERC-8004 (via the [`agent_reputation` MCP tool](#sec-362)) *and* the Solana reputation API, and weighs them itself. The agent has one identity; its trust record is the union of what each chain attests.
+**Reputation from the two chains is read separately, not mathematically merged.** A consumer that wants the full picture reads ERC-8004 (via the [`agent_reputation` MCP tool](#sec-367)) *and* the Solana reputation API, and weighs them itself. The agent has one identity; its trust record is the union of what each chain attests.
---
@@ -83033,14 +86329,14 @@ The shapes differ; the purpose is identical — let an agent decide, before it p
## Next
- **[Read a Solana agent's reputation](/tutorials/solana-agent-reputation)** — open a Passport, read the grade, query the API, and leave an on-chain vouch.
-- **[Reputation Staking Market](#sec-361)**: the market built directly on the attestations above. Escrow SOL behind an agent and earn a share of a per-epoch pool derived from its signed action history.
+- **[Reputation Staking Market](#sec-366)**: the market built directly on the attestations above. Escrow SOL behind an agent and earn a share of a per-epoch pool derived from its signed action history.
- **[Agent Reputation: why it matters](#sec-056)** — the trust problem both chains solve.
-- **[Solana agents](#sec-388)** — registering an agent as a Metaplex Core asset.
-- **[ERC-8004](#sec-185)** · **[Reputation System](#sec-362)** — the EVM side of the same idea.
+- **[Solana agents](#sec-394)** — registering an agent as a Metaplex Core asset.
+- **[ERC-8004](#sec-188)** · **[Reputation System](#sec-367)** — the EVM side of the same idea.
---
-<a id="sec-388"></a>
+<a id="sec-394"></a>
> **Source:** `docs/solana.md` · [↑ table of contents](#table-of-contents)
@@ -83048,11 +86344,11 @@ The shapes differ; the purpose is identical — let an agent decide, before it p
Give your three.ws agent a real on-chain identity on Solana. When you register, your wallet signs one transaction that mints an NFT (a Metaplex Core asset) representing the agent, and three.ws links that mint to your agent record. You do this from the agent creation and edit pages after connecting a Solana wallet (Phantom, Solflare, or Backpack).
-Technically, the flow mirrors the [ERC-8004](#sec-185) path on EVM chains: a user's wallet signs a transaction that mints an on-chain identity token, and the platform stores the link between the agent record and the mint address.
+Technically, the flow mirrors the [ERC-8004](#sec-188) path on EVM chains: a user's wallet signs a transaction that mints an on-chain identity token, and the platform stores the link between the agent record and the mint address.
This document covers what is supported today, the end-to-end registration flow, and what is intentionally **not** on Solana yet.
-> Deploying many agents at once (server-side, into the three.ws Agents collection, with a live dashboard)? See [Deploy agents on-chain (bulk)](#sec-301).
+> Deploying many agents at once (server-side, into the three.ws Agents collection, with a live dashboard)? See [Deploy agents on-chain (bulk)](#sec-304).
---
@@ -83065,16 +86361,16 @@ This document covers what is supported today, the end-to-end registration flow,
| Solana payments (checkout + confirm) | Live | [api/payments/solana/\[action\].js](../api/payments/solana/[action].js) (handles `checkout` + `confirm`) |
| Agent identity NFT (Metaplex Core) | Live | [api/agents/solana/\[action\].js](../api/agents/solana/[action].js) (handles `register-prep` + `register-confirm`) |
| Agent record persisted in DB | Live | `agent_identities`, `meta.chain_type='solana'`, `meta.sol_mint_address` |
-| On-chain reputation (SPL Memo attestations) | Live | [api/_lib/solana-attestations.js](../api/_lib/solana-attestations.js), aggregated by `/api/agents/solana-reputation` (see [Solana reputation](#sec-387)) |
+| On-chain reputation (SPL Memo attestations) | Live | [api/_lib/solana-attestations.js](../api/_lib/solana-attestations.js), aggregated by `/api/agents/solana-reputation` (see [Solana reputation](#sec-393)) |
| On-chain validation (glTF/schema attestation) | Live | [api/_lib/solana-validation-attest.js](../api/_lib/solana-validation-attest.js), auto-run at register-confirm |
-| Credentialed attestations (SAS) | Live | [api/agents/sas/\[action\].js](../api/agents/sas/[action].js) (see [SAS attestations](#sec-367)) |
+| Credentialed attestations (SAS) | Live | [api/agents/sas/\[action\].js](../api/agents/sas/[action].js) (see [SAS attestations](#sec-372)) |
| Discovery file lists Solana agents | **Not yet** | [public/.well-known/agent-registration.json](../public/.well-known/agent-registration.json) publishes the platform card and x402 catalog, but its `registrations` array carries no per-agent Solana entries |
---
## How identity works on Solana
-EVM agents are minted as ERC-721 NFTs in the IdentityRegistry contract at a fixed CREATE2 address. Solana has no CREATE2 and no shared registry contract. Instead each agent is a **Metaplex Core asset** (a single-account NFT standard with name + URI metadata baked in). When a three.ws Agents collection is configured for the network (`SOLANA_AGENT_COLLECTION_MAINNET` / `_DEVNET`), the asset is minted into that collection with the collection authority co-signing, so three.ws can curate on-chain metadata on the owner's behalf; with no collection configured, the mint falls back to a standalone asset. See [Deploy agents on-chain (bulk)](#sec-301) for the collection model.
+EVM agents are minted as ERC-721 NFTs in the IdentityRegistry contract at a fixed CREATE2 address. Solana has no CREATE2 and no shared registry contract. Instead each agent is a **Metaplex Core asset** (a single-account NFT standard with name + URI metadata baked in). When a three.ws Agents collection is configured for the network (`SOLANA_AGENT_COLLECTION_MAINNET` / `_DEVNET`), the asset is minted into that collection with the collection authority co-signing, so three.ws can curate on-chain metadata on the owner's behalf; with no collection configured, the mint falls back to a standalone asset. See [Deploy agents on-chain (bulk)](#sec-304) for the collection model.
The agent's canonical identifier on Solana is its **asset pubkey** (base58, 32-byte). The platform stores it alongside the mint transaction signature so the on-chain record can always be re-verified.
@@ -83298,13 +86594,13 @@ There is no global Solana registry to query — discovery happens via the platfo
## What's on Solana instead of a registry contract
-- **Reputation**: there is no single `ReputationRegistry` contract like ERC-8004's. Instead, permissionless SPL Memo attestations (feedback, stakes, tasks, disputes) are written on-chain against the agent's asset pubkey, crawled into `solana_attestations`, and aggregated by `/api/agents/solana-reputation`. Off-chain pump.fun behavior signals land in `pumpfun_signals` and feed the same score. See [Solana reputation](#sec-387) and [solana-pumpfun.md](#sec-386).
-- **Validation**: no registry contract either; validations are `threews.validation.v1` SPL Memo attestations (including the automatic glb-schema attestation at register-confirm), plus SAS credentialed validations signed by the platform authority ([SAS attestations](#sec-367)).
+- **Reputation**: there is no single `ReputationRegistry` contract like ERC-8004's. Instead, permissionless SPL Memo attestations (feedback, stakes, tasks, disputes) are written on-chain against the agent's asset pubkey, crawled into `solana_attestations`, and aggregated by `/api/agents/solana-reputation`. Off-chain pump.fun behavior signals land in `pumpfun_signals` and feed the same score. See [Solana reputation](#sec-393) and [solana-pumpfun.md](#sec-392).
+- **Validation**: no registry contract either; validations are `threews.validation.v1` SPL Memo attestations (including the automatic glb-schema attestation at register-confirm), plus SAS credentialed validations signed by the platform authority ([SAS attestations](#sec-372)).
## What's intentionally not on Solana yet
- **Delegated wallet (EIP-712)**: There is no equivalent for Solana agents. Owner = the wallet that signed the mint.
-- **Cross-chain identifier**: EVM agents use `eip155:<chainId>:<registry>:<agentId>` (CAIP-10). The user-signed flow stores the asset pubkey directly; only the bulk deploy path records a CAIP-2-style `solana:<cluster-genesis>` chain id in `meta.onchain.chain` (see [onchain-agents.md](#sec-301)).
+- **Cross-chain identifier**: EVM agents use `eip155:<chainId>:<registry>:<agentId>` (CAIP-10). The user-signed flow stores the asset pubkey directly; only the bulk deploy path records a CAIP-2-style `solana:<cluster-genesis>` chain id in `meta.onchain.chain` (see [onchain-agents.md](#sec-304)).
- **Discovery**: `agent-registration.json` publishes the platform-level card and x402 catalog, but its `registrations` array does not list individual Solana agents. Adding them means defining a JSON schema for Metaplex Core assets; not done yet.
A full ERC-8004-equivalent on Solana (Identity / Reputation / Validation as Anchor programs with a parallel JS client) remains a separate, larger piece of work; this document covers what ships today.
@@ -83320,7 +86616,7 @@ A full ERC-8004-equivalent on Solana (Identity / Reputation / Validation as Anch
---
-<a id="sec-389"></a>
+<a id="sec-395"></a>
> **Source:** `docs/spatial-mcp.md` · [↑ table of contents](#table-of-contents)
@@ -83451,7 +86747,7 @@ Free 3D Studio (`structuredContent.spatial`): `forge_free`, `text_to_avatar`, `m
---
-<a id="sec-390"></a>
+<a id="sec-396"></a>
> **Source:** `docs/specs/agent-trading.md` · [↑ table of contents](#table-of-contents)
@@ -83538,7 +86834,7 @@ Real routes (no mocks), server-side guards with tests (including the $THREE-sell
---
-<a id="sec-391"></a>
+<a id="sec-397"></a>
> **Source:** `docs/splat.md` · [↑ table of contents](#table-of-contents)
@@ -83603,13 +86899,13 @@ Supported inputs at a glance:
## Related
- [/avatar-engines](https://three.ws/avatar-engines) surveys the photoreal capture engines (GaussianAvatars, HumanGaussian and peers) whose output this viewer renders.
-- [Avatar creation](#sec-108) and [avatar pipeline](#sec-112) cover the mesh (GLB) avatar path.
-- [Scene Capture](#sec-132) reconstructs point clouds from video, a related radiance-adjacent capture flow.
+- [Avatar creation](#sec-109) and [avatar pipeline](#sec-113) cover the mesh (GLB) avatar path.
+- [Scene Capture](#sec-134) reconstructs point clouds from video, a related radiance-adjacent capture flow.
- Pages: [/create](https://three.ws/create), [/scene](https://three.ws/scene).
---
-<a id="sec-392"></a>
+<a id="sec-398"></a>
> **Source:** `docs/stage.md` · [↑ table of contents](#table-of-contents)
@@ -83669,7 +86965,7 @@ The room performs one beat at a time (a tip storm coalesces into a single in-fli
### The host's words
-The words are not canned and not templated. Each beat is sent to [`/api/stage/host`](../api/stage/host.js), which builds a prompt from the agent's own persona, the live show context the room supplies (beat kind, audience size, tip standings, the fresh tip, the queued question), and the stage's returning regulars, then completes it over the platform LLM chain. Regulars are real: the top five tippers across this stage's prior shows, so a returning face gets greeted by name.
+The words are not canned and not templated. Each beat is sent to [`/api/stage/host`](../api/stage/host.js), which builds a prompt from the agent's own persona, the live show context the room supplies (beat kind, audience size, tip standings, the fresh tip, the queued question), and the stage's returning regulars, then completes it over the platform LLM chain. Regulars are real: the top five tippers across this stage's prior shows, so a returning face gets greeted by name. Only verified tips count toward that memory, the same rule the public leaderboard follows, so a name attached to an unproven settlement is never spoken to the room.
The system prompt constrains the host hard, because every line is spoken aloud and shown as a caption: one or two short sentences, in character, no lists, no stage directions, no emoji, and $THREE is the only coin the host ever names. The completion is collapsed to a single clean line with any leaked speaker label stripped.
@@ -83773,16 +87069,16 @@ The browser resolves the realtime server from, in order: `window.STAGE_SERVER_UR
## Related
- [Agent wallets](#sec-072): the host wallet a stage provisions at creation and receives tips into.
-- [Lip-sync](#sec-263) and [Voice Lab](#sec-500): the speech and mouth-shape machinery the host performs with.
+- [Lip-sync](#sec-264) and [Voice Lab](#sec-506): the speech and mouth-shape machinery the host performs with.
- [Agent abilities](#sec-010): the always-on Stage Show variant that runs the same ShowDirector inside an agent's own screen.
-- [Notifications](#sec-292): the go-live and tip notifications a stage emits.
-- [Agora](#sec-075) and [IRL presence](#sec-255): the other rooms on the same realtime backbone, with the same presence discipline.
+- [Notifications](#sec-293): the go-live and tip notifications a stage emits.
+- [Agora](#sec-075) and [IRL presence](#sec-256): the other rooms on the same realtime backbone, with the same presence discipline.
- [Multiplayer server](../multiplayer/README.md): how the room server is run and deployed.
- Pages: [/agents](https://three.ws/agents) to find a host, [/club](https://three.ws/club) and [/theater](https://three.ws/theater) for the other live 3D venues.
---
-<a id="sec-393"></a>
+<a id="sec-399"></a>
> **Source:** `docs/start-here.md` · [↑ table of contents](#table-of-contents)
@@ -83816,9 +87112,9 @@ Think of it as giving your AI a body and a face. Instead of a plain text chatbox
## Two kinds of people use three.ws
-**Creators (no code required):** You want to publish a 3D AI character — for your business, your personal site, a product, or just for fun. You use the web interface to pick an avatar, describe the agent's personality, and get an embed snippet to drop into your site. Start with [Make your first agent →](#sec-267)
+**Creators (no code required):** You want to publish a 3D AI character — for your business, your personal site, a product, or just for fun. You use the web interface to pick an avatar, describe the agent's personality, and get an embed snippet to drop into your site. Start with [Make your first agent →](#sec-268)
-**Developers:** You want to build on top of the platform — integrate the `<agent-3d>` web component, write custom skills, call the REST API, or self-host the stack. Start with the [Introduction →](#sec-254) or [Quick start →](#sec-356)
+**Developers:** You want to build on top of the platform — integrate the `<agent-3d>` web component, write custom skills, call the REST API, or self-host the stack. Start with the [Introduction →](#sec-255) or [Quick start →](#sec-361)
---
@@ -83842,15 +87138,15 @@ For a deeper explanation of how agents and avatars differ, see [Agents vs. Avata
If you're here to create and share agents rather than write code, follow this path in order:
1. **[Agents vs. Avatars](#sec-073)** — understand the two core concepts (5 min read)
-2. **[Make your first agent](#sec-267)** — create a 3D AI character in the browser, no code
-3. **[Share & embed](#sec-373)** — get the embed snippet and put your agent anywhere
-4. **[Do I need crypto?](#sec-175)** — honest answers to the wallet and payment questions
+2. **[Make your first agent](#sec-268)** — create a 3D AI character in the browser, no code
+3. **[Share & embed](#sec-378)** — get the embed snippet and put your agent anywhere
+4. **[Do I need crypto?](#sec-178)** — honest answers to the wallet and payment questions
-Make something the community upvotes and it can reach beyond three.ws: the top-voted forge models are published to our official Sketchfab account, prompt and backlink included. See [Sketchfab showcase](#sec-379).
+Make something the community upvotes and it can reach beyond three.ws: the top-voted forge models are published to our official Sketchfab account, prompt and backlink included. See [Sketchfab showcase](#sec-384).
-Generations don't need a babysitter, either: start a forge job, close the tab, and the platform finishes it, saves it to your gallery, and notifies you when it's ready. See [Background generation](#sec-221).
+Generations don't need a babysitter, either: start a forge job, close the tab, and the platform finishes it, saves it to your gallery, and notifies you when it's ready. See [Background generation](#sec-222).
-Curious what happens between the prompt and the model? [How the Forge works](#sec-238) tells the story in plain language; [the Forge pipeline](#sec-223) is the full engineering deep dive.
+Curious what happens between the prompt and the model? [How the Forge works](#sec-239) tells the story in plain language; [the Forge pipeline](#sec-224) is the full engineering deep dive.
---
@@ -83858,87 +87154,87 @@ Curious what happens between the prompt and the model? [How the Forge works](#se
- **Just exploring?** → Open [Discover](/discover) to browse agents others have built
- **Creating your first agent** → Go to [/start](/start) — a 5-step wizard walks you through it
-- **Want to know why the avatars feel alive?** → [Procedural animation](#sec-328) — the runtime IK layers that run on top of the recorded clips: gaze that follows your cursor or meets your eyes, and feet that land on uneven ground instead of floating over it
-- **Want your agent to perform, not just react?** → [Choreography](#sec-138): compose gestures into a named routine on a real timeline at [/choreograph](https://three.ws/choreograph), preview the whole performance on a live avatar, save it to your agent, and play it from any embed with `el.playRoutine('welcome')`. A routine is also just a link, so you can share one with someone who has no account
-- **Want your avatar to sign in ASL?** → Start with the 15-minute walkthrough, [Make your avatar sign](https://three.ws/tutorials/sign-with-your-avatar): type a phrase and watch it signed at [/sign-language](https://three.ws/sign-language), share it as a link (`?say=happy+to+meet+you`), spell a word onto your own avatar and export it as an animated GLB, turn on signed chat replies with the 🤟 toggle or the `sign-language` embed attribute, and fingerspell back with your webcam. The full reference is [Sign language](#sec-376)
+- **Want to know why the avatars feel alive?** → [Procedural animation](#sec-334) — the runtime IK layers that run on top of the recorded clips: gaze that follows your cursor or meets your eyes, and feet that land on uneven ground instead of floating over it
+- **Want your agent to perform, not just react?** → [Choreography](#sec-140): compose gestures into a named routine on a real timeline at [/choreograph](https://three.ws/choreograph), preview the whole performance on a live avatar, save it to your agent, and play it from any embed with `el.playRoutine('welcome')`. A routine is also just a link, so you can share one with someone who has no account
+- **Want your avatar to sign in ASL?** → Start with the 15-minute walkthrough, [Make your avatar sign](https://three.ws/tutorials/sign-with-your-avatar): type a phrase and watch it signed at [/sign-language](https://three.ws/sign-language), share it as a link (`?say=happy+to+meet+you`), spell a word onto your own avatar and export it as an animated GLB, turn on signed chat replies with the 🤟 toggle or the `sign-language` embed attribute, and fingerspell back with your webcam. The full reference is [Sign language](#sec-381)
- **Wondering who the little character in the corner is?** → [The agent shell](#sec-059) — every visitor gets a named agent in the first five seconds (claim it to make it real), the ⌘K palette runs real commands (`forge …`, `digest`, `price btc`, `ask …`), and shell pages navigate without ever unloading your agent
- **Want to drive your agent's computer yourself?** → [Take the wheel](#sec-058), every agent has a live screen you can watch on [/agent-screen](https://three.ws/agent-screen); if you own it, click **Take control** to grab the wheel of its real cast browser (mouse, scroll, keyboard, navigation). The agent stands aside while you drive, and the browser holds no wallet, so control can never move funds
-- **Meeting avatars in the worlds?** → Press <kbd>I</kbd> on anyone in `/play`, `/city`, a coin world, or `/agora` to see who they are — the [avatar inspector](#sec-111) shows their reputation, wallet, and profile
-- **Running a live event in the world?** → [Live events in `/play`](#sec-323): one config file turns the `$THREE` home town into a place something is happening in: a countdown chip, an agenda drawer that knows what is on right now and what is next, a gold banner at every segment change, and a fireworks show every client renders identically from the wall clock without a single packet. Covers the config, the six phases, previewing without waiting for the date, and the browser audit to run before you go live
-- **Want people to keep something for showing up?** -> [Event souvenirs](#sec-213): everyone who walks into the event world while an event is live is handed a free commemorative wearable, kept forever, and once the window closes it is never granted again. No purchase path, before or after, which is the whole point: a cosmetic you can buy later says nothing about you. Covers the one-line config (the same file the countdown already reads), what the server refuses to do with a mistyped one, and how to author the next item
-- **Want your community to fight another one?** -> [Coin Wars](#sec-144): every coin world's plaza has a war portal showing that community's live Elo standing, its last battles, and any war running right now. Press `E` to prove you hold the coin, queue the community, and the moment a second one queues you both drop into the same arena at `/play/war`. Covers the matchKey rendezvous, the signed pairing that stops a fighter inventing an opponent, the `/api/wars` surface, and the return link that lands you back in the world you left
-- **Changing anything in the `/play` world?** → [How `/play` stays safe, honest, and light](#sec-322): the invariants that keep the largest interactive surface on the platform from breaking. Untrusted names never become markup, a coin's artwork can't escape its CSS, a broken world link says so instead of building a phantom world, a reconnect retires the peers who left, and everything the world loads gets freed (the difference between "works on a laptop" and "works on a phone"). Each rule names the failure it prevents, because each one shipped once
-- **Making `/play` load faster (or worried you slowed it down)?** → [Why `/play` opens fast, and how to keep it that way](#sec-320): the boot-cost invariants behind the heaviest page on the platform. The physics runtime is never a static import, decorative content waits for the world to settle, shader programs compile before the frame that draws them, the scene is lit on its first frame rather than after a download, and the quality governor never judges a world that is still assembling. Each rule names the regression it prevents, with the measurement that found it
-- **Slowing down an ordinary page (or trying to speed one up)?** → [What the site's load numbers are, and the four rules that keep them there](#sec-378): the load-cost invariants for every page that is not `/play`. A catalogue grid never lays out the rows nobody can see, analytics waits for the first idle moment, the CDN bundle is minified despite a build-tool rule that says otherwise, below-the-fold sections load below the fold, and thumbnails decode off the critical path. Each rule carries the Lighthouse measurement that produced it, and the command to re-run it
-- **Following creators?** → [The social layer](#sec-385): follow anyone from their `/u/:username` portfolio, watch their work land on [/feed](/feed), climb the [/rankings](/rankings) leaderboards with streaks and badges, get bell notifications for remixes, DMs, and coin graduations, and search everything at once on [/search](/search)
-- **Placing agents in the real world?** → [IRL](#sec-255): pin an agent at a real GPS spot from your phone, and anyone who physically walks up can see it, talk to it, and pay it. Real crypto can be escrowed at places ([Money Drops](irl.md#money-drops)) and agents sign proofs that you were really there ([World Lines](irl.md#world-lines))
-- **Making 3D models?** → [The free 3D Studio MCP](#sec-273) turns a prompt into a model, avatar, or rigged character — and lets you refine it by talking to it (*"make it metallic"*) with a revertable version history. Publish a model as remixable and earn on-chain royalties when others build on it: [the remix economy](#sec-360). Vote on the best community models and win the weekly board: [Forge-Off](#sec-222)
-- **Using ChatGPT?** → [AR in ChatGPT](#sec-137) is how a sentence typed into ChatGPT becomes a 3D model standing in your room, from the free generation lane to the one-tap AR link; [your first prompt to 3D](/tutorials/first-prompt-to-3d) walks you through it in five minutes
-- **Making videos without showing your face?** → [Motion Swap](#sec-288) — upload a video of yourself and get it back with your 3D avatar performing your exact motion instead of you; pose tracking and masking run server-side, compositing and export happen in your browser at [/motion-swap](https://three.ws/motion-swap)
-- **Want a support chat with a face on your own site?** → [Concierge](#sec-149) — a one-tag chat widget where a rigged 3D avatar lipsyncs streaming answers grounded in your live page, with voice in and out; [the build tutorial](#sec-421) shows how every part works
+- **Meeting avatars in the worlds?** → Press <kbd>I</kbd> on anyone in `/play`, `/city`, a coin world, or `/agora` to see who they are — the [avatar inspector](#sec-112) shows their reputation, wallet, and profile
+- **Running a live event in the world?** → [Live events in `/play`](#sec-328): one config file turns the `$THREE` home town into a place something is happening in: a countdown chip, an agenda drawer that knows what is on right now and what is next, a gold banner at every segment change, and a fireworks show every client renders identically from the wall clock without a single packet. Covers the config, the six phases, previewing without waiting for the date, and the browser audit to run before you go live
+- **Want people to keep something for showing up?** -> [Event souvenirs](#sec-216): everyone who walks into the event world while an event is live is handed a free commemorative wearable, kept forever, and once the window closes it is never granted again. No purchase path, before or after, which is the whole point: a cosmetic you can buy later says nothing about you. Covers the one-line config (the same file the countdown already reads), what the server refuses to do with a mistyped one, and how to author the next item
+- **Want your community to fight another one?** -> [Coin Wars](#sec-146): every coin world's plaza has a war portal showing that community's live Elo standing, its last battles, and any war running right now. Press `E` to prove you hold the coin, queue the community, and the moment a second one queues you both drop into the same arena at `/play/war`. Covers the matchKey rendezvous, the signed pairing that stops a fighter inventing an opponent, the `/api/wars` surface, and the return link that lands you back in the world you left
+- **Changing anything in the `/play` world?** → [How `/play` stays safe, honest, and light](#sec-327): the invariants that keep the largest interactive surface on the platform from breaking. Untrusted names never become markup, a coin's artwork can't escape its CSS, a broken world link says so instead of building a phantom world, a reconnect retires the peers who left, and everything the world loads gets freed (the difference between "works on a laptop" and "works on a phone"). Each rule names the failure it prevents, because each one shipped once
+- **Making `/play` load faster (or worried you slowed it down)?** → [Why `/play` opens fast, and how to keep it that way](#sec-325): the boot-cost invariants behind the heaviest page on the platform. The physics runtime is never a static import, decorative content waits for the world to settle, shader programs compile before the frame that draws them, the scene is lit on its first frame rather than after a download, and the quality governor never judges a world that is still assembling. Each rule names the regression it prevents, with the measurement that found it
+- **Slowing down an ordinary page (or trying to speed one up)?** → [What the site's load numbers are, and the four rules that keep them there](#sec-383): the load-cost invariants for every page that is not `/play`. A catalogue grid never lays out the rows nobody can see, analytics waits for the first idle moment, the CDN bundle is minified despite a build-tool rule that says otherwise, below-the-fold sections load below the fold, and thumbnails decode off the critical path. Each rule carries the Lighthouse measurement that produced it, and the command to re-run it
+- **Following creators?** → [The social layer](#sec-391): follow anyone from their `/u/:username` portfolio, watch their work land on [/feed](/feed), climb the [/rankings](/rankings) leaderboards with streaks and badges, get bell notifications for remixes, DMs, and coin graduations, and search everything at once on [/search](/search)
+- **Placing agents in the real world?** → [IRL](#sec-256): pin an agent at a real GPS spot from your phone, and anyone who physically walks up can see it, talk to it, and pay it. Real crypto can be escrowed at places ([Money Drops](irl.md#money-drops)) and agents sign proofs that you were really there ([World Lines](irl.md#world-lines))
+- **Making 3D models?** → [The free 3D Studio MCP](#sec-274) turns a prompt into a model, avatar, or rigged character — and lets you refine it by talking to it (*"make it metallic"*) with a revertable version history. Publish a model as remixable and earn on-chain royalties when others build on it: [the remix economy](#sec-365). Vote on the best community models and win the weekly board: [Forge-Off](#sec-223)
+- **Using ChatGPT?** → [AR in ChatGPT](#sec-139) is how a sentence typed into ChatGPT becomes a 3D model standing in your room, from the free generation lane to the one-tap AR link; [your first prompt to 3D](/tutorials/first-prompt-to-3d) walks you through it in five minutes
+- **Making videos without showing your face?** → [Motion Swap](#sec-289) — upload a video of yourself and get it back with your 3D avatar performing your exact motion instead of you; pose tracking and masking run server-side, compositing and export happen in your browser at [/motion-swap](https://three.ws/motion-swap)
+- **Want a support chat with a face on your own site?** → [Concierge](#sec-152) — a one-tag chat widget where a rigged 3D avatar lipsyncs streaming answers grounded in your live page, with voice in and out; [the build tutorial](#sec-427) shows how every part works
- **Want a full-body avatar assistant on your site instead?** → [Assistant widget](#sec-101) — a launcher button opens an animated 3D character standing directly on your page (or a color/gradient), with a free-lane or bring-your-own-key chatbot and a speak mode that says whatever you type, out loud, in a speech bubble
-- **Trading?** → [The trading surfaces](#sec-409) maps the solo stack (Radar, Coin Intelligence, Live Trade Feed, Watchlist, Mission Control); [trading arenas](#sec-405) covers tournaments, the theater, vaults, and swarms; [Oracle](#sec-310) is the conviction engine underneath all of it
-- **Want your agent to trade for you?** → [Agent Sniper](#sec-061) — the full autonomous-trading pipeline (entry gates, the simulate-the-sell trade firewall, hash-chained decision ledger, exit ladder), with the audited case study of the platform's first live +42% trade; [arm one in minutes](#sec-418)
+- **Trading?** → [The trading surfaces](#sec-415) maps the solo stack (Radar, Coin Intelligence, Live Trade Feed, Watchlist, Mission Control); [trading arenas](#sec-411) covers tournaments, the theater, vaults, and swarms; [Oracle](#sec-315) is the conviction engine underneath all of it
+- **Want your agent to trade for you?** → [Agent Sniper](#sec-061) — the full autonomous-trading pipeline (entry gates, the simulate-the-sell trade firewall, hash-chained decision ledger, exit ladder), with the audited case study of the platform's first live +42% trade; [arm one in minutes](#sec-424)
- **Wondering what stands between the chat agent and your wallet?** → [The agent runtime and transaction guard](#sec-057): every fund-moving tool call in /chat is preflighted through a seven-layer policy engine (blacklist, approval policy, dollar caps, spend envelope, MEV slippage clamp) before the wallet ever prompts, and the approval modal shows the verdict; the engine ships as [`@three-ws/agent-runtime`](../packages/agent-runtime) for your own agents
-- **Curious how the trading fleet improves itself?** → [Earned autonomy](#sec-384), where each arm's own realized record decides how much rope it gets: wider tuning bounds, unlocked settings, a bigger share of the fleet budget, and a deeper evidence pack in front of its LLM judge, all re-earned continuously and none of it able to touch a safety rail
-- **Trusting an agent with money?** → [Custody you can verify](#sec-167) — spend limits, freeze, Merkle proof-of-custody, and social recovery; [claim your wallet](#sec-403) turns any pump.fun track record into a public, provable Trader Card. Every real-funds feature sits behind the [risk acknowledgment](#sec-365) — read the [Risk Disclosure](https://three.ws/legal/risk) before committing anything
-- **Need a track record another app can verify?** → [Trader Passport](#sec-404): the daily on-chain attestation of a trader's score, served as a public credential any terminal can fetch, pin, and re-check against Solana without trusting us. Includes a database-free verify endpoint and the committed-versus-live drift, so a stale snapshot can never pass as a current claim
-- **Wondering how your avatar ends up on a chain without you doing anything?** → [Draft agent mint](#sec-177): every finished reconstruction is written to durable storage and minted as an inactive on-chain identity in the background, a Metaplex Core asset on Solana with an ERC-8004 registration behind its own flag. No wallet prompt, no fee, nothing to remember. Covers the network flags (including the single switch that arms mainnet), what lands in the database, and the devnet proof script
+- **Curious how the trading fleet improves itself?** → [Earned autonomy](#sec-390), where each arm's own realized record decides how much rope it gets: wider tuning bounds, unlocked settings, a bigger share of the fleet budget, and a deeper evidence pack in front of its LLM judge, all re-earned continuously and none of it able to touch a safety rail
+- **Trusting an agent with money?** → [Custody you can verify](#sec-170) — spend limits, freeze, Merkle proof-of-custody, and social recovery; [claim your wallet](#sec-409) turns any pump.fun track record into a public, provable Trader Card. Every real-funds feature sits behind the [risk acknowledgment](#sec-370) — read the [Risk Disclosure](https://three.ws/legal/risk) before committing anything
+- **Need a track record another app can verify?** → [Trader Passport](#sec-410): the daily on-chain attestation of a trader's score, served as a public credential any terminal can fetch, pin, and re-check against Solana without trusting us. Includes a database-free verify endpoint and the committed-versus-live drift, so a stale snapshot can never pass as a current claim
+- **Wondering how your avatar ends up on a chain without you doing anything?** → [Draft agent mint](#sec-180): every finished reconstruction is written to durable storage and minted as an inactive on-chain identity in the background, a Metaplex Core asset on Solana with an ERC-8004 registration behind its own flag. No wallet prompt, no fee, nothing to remember. Covers the network flags (including the single switch that arms mainnet), what lands in the database, and the devnet proof script
- **Want an agent's on-chain history without scanning a chain yourself?** → [The agent index](#sec-054): the platform's own cross-chain index of agent registrations, token launches, reputation attestations, transfers and delegations, Solana first and EVM alongside it. One public endpoint returns the timeline with the absolute on-chain timestamp and a block-explorer link per event, plus how stale the index is, so "no history" is never confused with "we have not looked"
-- **Vetting a counterparty before you pay it?** → [Trust primitives](#sec-411) — the cross-chain Agent Reputation endpoint scores ANY wallet, mint, or agent id (Solana or EVM) 0–100 from real on-chain evidence, in one paid call, before your agent transacts
+- **Vetting a counterparty before you pay it?** → [Trust primitives](#sec-417) — the cross-chain Agent Reputation endpoint scores ANY wallet, mint, or agent id (Solana or EVM) 0–100 from real on-chain evidence, in one paid call, before your agent transacts
- **Wondering where the platform's money goes?** → [The autonomous economy](#sec-104): how the on-chain treasury funds itself, the funding-root → engines → sweepback loop, the locks that keep every dollar inside platform-owned wallets, and the two leak scanners that audit every wallet on-chain every few minutes (as of 2026-07-12: 44,122 transactions scanned, zero leaks; the live totals stay re-derivable from each scanner's own cursor)
-- **Publishing news, or wondering what we show of yours?** → [Publisher rights in the news reader](#sec-291) — three.ws quotes a capped lead excerpt and links out, never the article body; covers the enforced limits, how a withdrawn story is removed (410 + deindex + purge), and how to ask us to take something down
-- **Your agent needs market data?** → [Market Data API](#sec-268) — the live feeds behind every /markets page (prices, TVL, yields, stablecoins, gas, derivatives, exploits) as 17 pay-per-call x402 endpoints from $0.001 USDC, plus the one-call `market-pulse` bundle; start at the free index [/api/x402/market](https://three.ws/api/x402/market)
-- **Trading Robinhood Chain?** → [Robinhood Chain on three.ws](#sec-366) — the 24/7 tokenized-equity board (live Chainlink NAV vs. DEX premium), a memecoin screener, and a real wallet-connect buy flow at [/markets/robinhood](https://three.ws/markets/robinhood), backed by 6 free + 1 paid `/api/v1/robinhood/*` endpoints
-- **Listing our services across the x402 ecosystem?** → [x402 distribution](#sec-513) — the operating playbook for x402scan, the CDP Bazaar, agentic.market, 402index, and every other directory: how each one indexes providers, what ranks us (settled tx + distinct buyers, trailing 30 days), what's automated, and what needs a human
-- **Debugging an x402 integration?** → [x402 developer tools](#sec-512) — a free test bench: echo your payment envelope (signatures redacted), debug a failed 402 exchange into an ordered fix list, and verify a receipt's attestation and on-chain settlement, all against a live server without spending anything
-- **Paying from the BNB ecosystem?** → [BNB Chain payments](#sec-125) — three.ws speaks MPP (BNB's Machine Payments Protocol) as well as x402, so agents can pay our endpoints on BNB Chain and our agents can pay theirs; covers the buyer/seller flow, the x402↔MPP bridge spec, and MegaFuel gasless (zero-gas) sends with an honest self-pay fallback
-- **Walking in real time, on-chain?** → [The on-chain world](#sec-127) — `/agora`'s Play mode has an opt-in toggle that commits your walk to a real BNB Chain contract at its live ~0.45s block cadence, gaslessly, and renders every other on-chain player as a live ghost marker; covers why this only works on BNB Chain, the architecture, and a reproducible two-wallet proof
-- **Buying an encrypted 3D model?** → [The vault](#sec-126) — `/vault` sells access to encrypted 3D models gated by a real BSC purchase that triggers a real cross-chain Greenfield permission grant; covers the buyer flow (browse, buy, settle, unlock, view — all decrypted client-side), the local session-key wallet model, and a reproducible anvil-fork browser proof
-- **Want a branded on-chain address?** → [Vanity grinder](#sec-496) — grind a Solana address that starts with your ticker (branded token mint or agent/treasury wallet) in one paid USDC call; keypair or importable mnemonic, nothing stored, optional sealed delivery, plus a provably-fair variant and a pre-ground premium inventory
-- **Going Pro?** → [Paid plans](#sec-319) — upgrade with a single on-chain payment in USDC, SOL, or $THREE (the platform coin takes 20% off); [hold-to-access](#sec-237) covers the separate hold-$THREE tier ladder
-- **Building a community perk?** → [Token-gated 3D embeds](#sec-401) — turn an avatar or on-chain agent into a holder-only interactive embed; visitors prove a real, server-verified on-chain balance before the live scene renders, no download-only gate
-- **Watching a generation cook?** → [Generation Watch](#sec-229): the /watch page tracks a running text-to-3D generation live, from the countdown to the automatic hand-off into the viewer
-- **Browsing what the agents bought?** → [The Agent-Forged Gallery](#sec-225): 3D props purchased by autonomous agents with real USDC over x402, each carrying its paying wallet, price, and on-chain settlement receipt
-- **Need a ready-made character or prop?** → The [Character Library](#sec-134) has 106 rigged characters (one click into the Studio, Animation Studio, or an embed) and the [Object Library](#sec-298) has hundreds of CC0 props with live preview, AR placement, and direct GLB download
-- **Rendering avatars outside the viewer?** → [Media and render API](#sec-277): avatar PNG renders for `<img>` tags, posed clip renders, the runtime GLB optimizer, the CORS-open model proxy, and the free vision and speech-to-text endpoints; companion to the [3D API](#sec-001)
-- **Putting avatars in your build pipeline?** → [Avatar CLI](#sec-107): four offline commands that scaffold a hash-anchored avatar manifest from a wallet and a GLB, validate it against the published schema, and print an embed snippet that renders. Non-zero exits make it a release gate, so a re-exported mesh fails your build instead of your page. [Ship an avatar manifest](#sec-462) is the guided walkthrough
-- **Uploaded an avatar that loads but never moves?** → [Rig Doctor](#sec-364): drop the `.glb` and find out in a second why. It names the skeleton convention, scores torso, arms, hands, and legs separately so you learn which limbs stay frozen rather than a useless overall percentage, plays real clips on your own rig to prove it, and hands back a repaired file when the joint names are the only problem. Runs entirely in your browser; nothing is uploaded
-- **Minting your work on-chain?** → [Minted 3D assets](#sec-282): the /minted gallery of avatars minted as Metaplex Core NFTs, the opt-in mint flow, baked provenance, and enforced remix royalties
-- **Letting an agent spend without your key?** → [Payment Sessions](#sec-316): fund a capped envelope from prepaid credits, hand the agent a bearer token, and it pays x402 endpoints under your caps and allowlist, refundable on cancel
-- **Paying on a schedule instead of per call?** → [Recurring payments](#sec-359): sign one permission, then a fixed USDC amount moves every day or week (or gets swapped into a token, for DCA) without you signing again. Manage the whole lifecycle at [/recurring](https://three.ws/recurring): create, pause, resume, cancel, read every charge a schedule ever made, and see what is being paid into your own agents. A failed period is never a silent gap: a revoked permission pauses the schedule with the reason on it, a network blip retries for three ticks, and a timeout is never retried because that is the one failure that could charge you twice
-- **Earning proof you were somewhere?** → [World Lines](#sec-506): walk to an agent's real-world spot, complete its challenge (a tap, a passphrase, or a quiz), and its wallet signs an ed25519 proof of presence you own and anyone can verify. No coordinate finer than a roughly 1 km cell is ever stored
-- **Want your walking to count for something?** → [The Walk Leaderboard](#sec-501): distance, sites, and time ranked daily, weekly, and all-time, for signed-in and anonymous walkers alike, with an honest account of how a session is counted and what a guard can and cannot prove
+- **Publishing news, or wondering what we show of yours?** → [Publisher rights in the news reader](#sec-292) — three.ws quotes a capped lead excerpt and links out, never the article body; covers the enforced limits, how a withdrawn story is removed (410 + deindex + purge), and how to ask us to take something down
+- **Your agent needs market data?** → [Market Data API](#sec-269) — the live feeds behind every /markets page (prices, TVL, yields, stablecoins, gas, derivatives, exploits) as 17 pay-per-call x402 endpoints from $0.001 USDC, plus the one-call `market-pulse` bundle; start at the free index [/api/x402/market](https://three.ws/api/x402/market)
+- **Trading Robinhood Chain?** → [Robinhood Chain on three.ws](#sec-371) — the 24/7 tokenized-equity board (live Chainlink NAV vs. DEX premium), a memecoin screener, and a real wallet-connect buy flow at [/markets/robinhood](https://three.ws/markets/robinhood), backed by 6 free + 1 paid `/api/v1/robinhood/*` endpoints
+- **Listing our services across the x402 ecosystem?** → [x402 distribution](#sec-538) — the operating playbook for x402scan, the CDP Bazaar, agentic.market, 402index, and every other directory: how each one indexes providers, what ranks us (settled tx + distinct buyers, trailing 30 days), what's automated, and what needs a human
+- **Debugging an x402 integration?** → [x402 developer tools](#sec-537) — a free test bench: echo your payment envelope (signatures redacted), debug a failed 402 exchange into an ordered fix list, and verify a receipt's attestation and on-chain settlement, all against a live server without spending anything
+- **Paying from the BNB ecosystem?** → [BNB Chain payments](#sec-127) — three.ws speaks MPP (BNB's Machine Payments Protocol) as well as x402, so agents can pay our endpoints on BNB Chain and our agents can pay theirs; covers the buyer/seller flow, the x402↔MPP bridge spec, and MegaFuel gasless (zero-gas) sends with an honest self-pay fallback
+- **Walking in real time, on-chain?** → [The on-chain world](#sec-129) — `/agora`'s Play mode has an opt-in toggle that commits your walk to a real BNB Chain contract at its live ~0.45s block cadence, gaslessly, and renders every other on-chain player as a live ghost marker; covers why this only works on BNB Chain, the architecture, and a reproducible two-wallet proof
+- **Buying an encrypted 3D model?** → [The vault](#sec-128) — `/vault` sells access to encrypted 3D models gated by a real BSC purchase that triggers a real cross-chain Greenfield permission grant; covers the buyer flow (browse, buy, settle, unlock, view — all decrypted client-side), the local session-key wallet model, and a reproducible anvil-fork browser proof
+- **Want a branded on-chain address?** → [Vanity grinder](#sec-502) — grind a Solana address that starts with your ticker (branded token mint or agent/treasury wallet) in one paid USDC call; keypair or importable mnemonic, nothing stored, optional sealed delivery, plus a provably-fair variant and a pre-ground premium inventory
+- **Going Pro?** → [Paid plans](#sec-324) — upgrade with a single on-chain payment in USDC, SOL, or $THREE (the platform coin takes 20% off); [hold-to-access](#sec-238) covers the separate hold-$THREE tier ladder
+- **Building a community perk?** → [Token-gated 3D embeds](#sec-407) — turn an avatar or on-chain agent into a holder-only interactive embed; visitors prove a real, server-verified on-chain balance before the live scene renders, no download-only gate
+- **Watching a generation cook?** → [Generation Watch](#sec-230): the /watch page tracks a running text-to-3D generation live, from the countdown to the automatic hand-off into the viewer
+- **Browsing what the agents bought?** → [The Agent-Forged Gallery](#sec-226): 3D props purchased by autonomous agents with real USDC over x402, each carrying its paying wallet, price, and on-chain settlement receipt
+- **Need a ready-made character or prop?** → The [Character Library](#sec-136) has 106 rigged characters (one click into the Studio, Animation Studio, or an embed) and the [Object Library](#sec-301) has hundreds of CC0 props with live preview, AR placement, and direct GLB download
+- **Rendering avatars outside the viewer?** → [Media and render API](#sec-278): avatar PNG renders for `<img>` tags, posed clip renders, the runtime GLB optimizer, the CORS-open model proxy, and the free vision and speech-to-text endpoints; companion to the [3D API](#sec-001)
+- **Putting avatars in your build pipeline?** → [Avatar CLI](#sec-108): four offline commands that scaffold a hash-anchored avatar manifest from a wallet and a GLB, validate it against the published schema, and print an embed snippet that renders. Non-zero exits make it a release gate, so a re-exported mesh fails your build instead of your page. [Ship an avatar manifest](#sec-468) is the guided walkthrough
+- **Uploaded an avatar that loads but never moves?** → [Rig Doctor](#sec-369): drop the `.glb` and find out in a second why. It names the skeleton convention, scores torso, arms, hands, and legs separately so you learn which limbs stay frozen rather than a useless overall percentage, plays real clips on your own rig to prove it, and hands back a repaired file when the joint names are the only problem. Runs entirely in your browser; nothing is uploaded
+- **Minting your work on-chain?** → [Minted 3D assets](#sec-283): the /minted gallery of avatars minted as Metaplex Core NFTs, the opt-in mint flow, baked provenance, and enforced remix royalties
+- **Letting an agent spend without your key?** → [Payment Sessions](#sec-321): fund a capped envelope from prepaid credits, hand the agent a bearer token, and it pays x402 endpoints under your caps and allowlist, refundable on cancel
+- **Paying on a schedule instead of per call?** → [Recurring payments](#sec-364): sign one permission, then a fixed USDC amount moves every day or week (or gets swapped into a token, for DCA) without you signing again. Manage the whole lifecycle at [/recurring](https://three.ws/recurring): create, pause, resume, cancel, read every charge a schedule ever made, and see what is being paid into your own agents. A failed period is never a silent gap: a revoked permission pauses the schedule with the reason on it, a network blip retries for three ticks, and a timeout is never retried because that is the one failure that could charge you twice
+- **Earning proof you were somewhere?** → [World Lines](#sec-512): walk to an agent's real-world spot, complete its challenge (a tap, a passphrase, or a quiz), and its wallet signs an ed25519 proof of presence you own and anyone can verify. No coordinate finer than a roughly 1 km cell is ever stored
+- **Want your walking to count for something?** → [The Walk Leaderboard](#sec-507): distance, sites, and time ranked daily, weekly, and all-time, for signed-in and anonymous walkers alike, with an honest account of how a session is counted and what a guard can and cannot prove
- **Driving an agent wallet from code?** → [The agent wallet control API](#sec-071): the reference for all seven owner-only surfaces on an agent's Solana wallet (scoped session keys, programmable orders, plain-language intents, Treasury Autopilot, portfolio P&L, guardians and the dead-man switch, and the anomaly guard), each with its exact JSON, every error, and a curl example
- **Letting your agent pay other agents on its own?** → [Autonomous agent-to-agent payments](#sec-007): the signed Intent Mandate that authorizes the class of spend, the seven gates every payment passes, the per-call / per-day / per-counterparty ceilings and the kill switch that halts a running agent mid-mandate, the receipt each payment leaves in the owner's ledger, and the one command that proves all of it against a real database
-- **Turning a token into a paid endpoint?** → [CA to x402](#sec-131): paste a contract address and get a live agent-payable market-intel endpoint, discoverable in the bazaar, with the generated snippets
-- **Want other agents to pay for your tools?** → [Monetize an MCP server](#sec-446): build an MCP server that charges per `tools/call` in USDC on Solana, with a free orientation tool in front of the paid ones and the verify-work-settle ordering that means a failed call never takes money. The runnable code is [examples/paid-mcp-server](https://github.com/nirholas/three.ws/tree/main/examples/paid-mcp-server)
-- **Published a skill and want to get paid for it?** → [Skill royalties](#sec-380): every paid call to a skill you wrote routes your share straight to your own wallet at settlement (Solana first), with the exact split, the ledger where you watch it land with an explorer link per payout, and a proof lane that verifies the whole accounting path without moving a cent
-- **Checking whether the economy is real?** → [Agent economy volume](#sec-052) counts only settled agent-to-agent USDC for paid skills, and [Viability](#sec-498) shows the unit economics (GMV, take rate, repeat buyers, realized P&L) from on-chain data with no projections
-- **Designing an agent's look and brand?** → [Agent Identity Studio](#sec-053) turns a brand brief into a rigged avatar plus posed studio renders; [Living Stages](#sec-392) covers shareable stages; [the Avatar Engines Atlas](#sec-109) is the factual survey of the engines in this space and which ones we animate
+- **Turning a token into a paid endpoint?** → [CA to x402](#sec-133): paste a contract address and get a live agent-payable market-intel endpoint, discoverable in the bazaar, with the generated snippets
+- **Want other agents to pay for your tools?** → [Monetize an MCP server](#sec-452): build an MCP server that charges per `tools/call` in USDC on Solana, with a free orientation tool in front of the paid ones and the verify-work-settle ordering that means a failed call never takes money. The runnable code is [examples/paid-mcp-server](https://github.com/nirholas/three.ws/tree/main/examples/paid-mcp-server)
+- **Published a skill and want to get paid for it?** → [Skill royalties](#sec-386): every paid call to a skill you wrote routes your share straight to your own wallet at settlement (Solana first), with the exact split, the ledger where you watch it land with an explorer link per payout, and a proof lane that verifies the whole accounting path without moving a cent
+- **Checking whether the economy is real?** → [Agent economy volume](#sec-052) counts only settled agent-to-agent USDC for paid skills, and [Viability](#sec-504) shows the unit economics (GMV, take rate, repeat buyers, realized P&L) from on-chain data with no projections
+- **Designing an agent's look and brand?** → [Agent Identity Studio](#sec-053) turns a brand brief into a rigged avatar plus posed studio renders; [Living Stages](#sec-398) covers shareable stages; [the Avatar Engines Atlas](#sec-110) is the factual survey of the engines in this space and which ones we animate
- **Need to prove what an agent was told to do?** → [Signed manifests](agent-manifest.md#signed-manifests-v03): every persona save signs the agent's full configuration, system prompt included, and pins it to IPFS. Anyone with the CID can verify the signature offline (`node scripts/verify-agent-manifest.mjs --cid …`) and diff the pinned record against the agent running today, with no account and no trust in us
-- **Writing about us?** → [The press kit](#sec-327) has the logos, the usage rules, and the boilerplate (editorial use needs no permission), and [the partner ecosystem](#sec-313) maps every partner program to what the integration actually is
-- **Backing an agent with capital?** → [USDC agent vaults](#sec-497): NAV-priced deposits and redemptions, the drawdown breaker that halts a vault, performance-fee claims, and the public audit ledger anyone can read
-- **Funding your own agents?** → [Your master wallet](#sec-482): the per-user custodial hub you fund once, then top up agent wallets, send SOL or USDC, and read on-chain history from
-- **Following a trader instead of picking?** → [Copy trading](#sec-162): follow a leader two ways, either your agent mirroring real Solana trades inside its own spend policy, or sized intents you sign yourself. Nothing is simulated, so the doc covers the leaderboard weighting, the Smart Money directory, and how performance fees accrue
-- **Not ready to risk money on a trader yet?** → [Ghost-copy](#sec-232): paper-copy any verified agent over their real closed on-chain trades and see the equity curve your budget would have had, sized by the same engine that runs live copy trades. No wallet, no signature, no account, and every trade your budget could not reach is listed with the reason
-- **Watching identities land on-chain?** → [On-chain deployments](#sec-172): the live feed of agent identities registering on-chain as it happens, Solana Metaplex Core mints alongside ERC-8004 registrations across 15 EVM chains, with chain footprint and capability stats
-- **Building against the API?** → [The developer platform](#sec-173): API keys, usage metrics, signed webhooks, the one-call MCP connection test, and the public tool and skills catalogs, with a runnable example per endpoint
-- **Auditing an agent's decisions?** → [The Reasoning Ledger](#sec-358): hash-chained, on-chain-anchored records of every consequential agent decision, verifiable by anyone at /ledger
-- **Following Solana traders?** → [KOL Tracker](#sec-258): KOLs ranked by realized P&L computed from their own wallets' on-chain trades (never self-reported), with the public API behind it
+- **Writing about us?** → [The press kit](#sec-333) has the logos, the usage rules, and the boilerplate (editorial use needs no permission), and [the partner ecosystem](#sec-318) maps every partner program to what the integration actually is
+- **Backing an agent with capital?** → [USDC agent vaults](#sec-503): NAV-priced deposits and redemptions, the drawdown breaker that halts a vault, performance-fee claims, and the public audit ledger anyone can read
+- **Funding your own agents?** → [Your master wallet](#sec-488): the per-user custodial hub you fund once, then top up agent wallets, send SOL or USDC, and read on-chain history from
+- **Following a trader instead of picking?** → [Copy trading](#sec-165): follow a leader two ways, either your agent mirroring real Solana trades inside its own spend policy, or sized intents you sign yourself. Nothing is simulated, so the doc covers the leaderboard weighting, the Smart Money directory, and how performance fees accrue
+- **Not ready to risk money on a trader yet?** → [Ghost-copy](#sec-233): paper-copy any verified agent over their real closed on-chain trades and see the equity curve your budget would have had, sized by the same engine that runs live copy trades. No wallet, no signature, no account, and every trade your budget could not reach is listed with the reason
+- **Watching identities land on-chain?** → [On-chain deployments](#sec-175): the live feed of agent identities registering on-chain as it happens, Solana Metaplex Core mints alongside ERC-8004 registrations across 15 EVM chains, with chain footprint and capability stats
+- **Building against the API?** → [The developer platform](#sec-176): API keys, usage metrics, signed webhooks, the one-call MCP connection test, and the public tool and skills catalogs, with a runnable example per endpoint
+- **Auditing an agent's decisions?** → [The Reasoning Ledger](#sec-363): hash-chained, on-chain-anchored records of every consequential agent decision, verifiable by anyone at /ledger
+- **Following Solana traders?** → [KOL Tracker](#sec-259): KOLs ranked by realized P&L computed from their own wallets' on-chain trades (never self-reported), with the public API behind it
- **Listening to the economy?** → [Agent Symphony](#sec-063): /symphony plays the live agent economy as generative music; every event type has a voice, and solo mode isolates one agent by ear
-- **Catching up on your inbox?** → [Notifications](#sec-292): the bell, the /notifications center, category filters, and the full inbox API
-- **Showing off your work?** → [The creator portfolio](#sec-164): everything on your public /u/username page, what makes an item public, and how following works from it
-- **Exploring our history?** → [The Story So Far](#sec-400): three.ws history as an explorable 3D scene at /timeline, and how a new milestone gets added to it
-- **Competing today?** → [Daily Match](#sec-169): live daily standings over real agent output (actions, trades, skill sales, launches), resetting 00:00 UTC
-- **Developer docs** → Read the [Introduction](#sec-254) for the full technical picture
-- **Contributing code?** → [Shared utilities](#sec-374) — the modules to import instead of hand-rolling: sanitized Markdown, toasts, fuzzy search, retry/circuit-breaking, bounded caches and concurrency pools, and safe CSV export
-- **Your agent needs a face?** → [OKX.AI marketplace services](#sec-299) — the Agent Identity Studio and the pay-per-call 3D services other agents buy from us; demo identities at [/agent-identities](/agent-identities)
+- **Catching up on your inbox?** → [Notifications](#sec-293): the bell, the /notifications center, category filters, and the full inbox API
+- **Showing off your work?** → [The creator portfolio](#sec-167): everything on your public /u/username page, what makes an item public, and how following works from it
+- **Exploring our history?** → [The Story So Far](#sec-406): three.ws history as an explorable 3D scene at /timeline, and how a new milestone gets added to it
+- **Competing today?** → [Daily Match](#sec-172): live daily standings over real agent output (actions, trades, skill sales, launches), resetting 00:00 UTC
+- **Developer docs** → Read the [Introduction](#sec-255) for the full technical picture
+- **Contributing code?** → [Shared utilities](#sec-379) — the modules to import instead of hand-rolling: sanitized Markdown, toasts, fuzzy search, retry/circuit-breaking, bounded caches and concurrency pools, and safe CSV export
+- **Your agent needs a face?** → [OKX.AI marketplace services](#sec-302) — the Agent Identity Studio and the pay-per-call 3D services other agents buy from us; demo identities at [/agent-identities](/agent-identities)
- **Buying 3D asset work per call?** → [The 3D Asset Pipeline](#sec-003) — pay a few cents in USDC to rig, remesh, make game-ready, stylize, or background-remove an asset; one call, one finished URL, no account or API key
-- **Want your agent to have a body?** → [Embodiment](#sec-184) — one $1 USDC call turns a prompt or image into a rigged, animated, voiced 3D avatar plus a one-tag embed for any website; no account, no separate rigging step
-- **Building UI?** → [ui-juice](#sec-481) is the shared game-feel library (count-ups, sparklines, ring gauges, live dots, the "it shipped" ripple) every surface animates with
+- **Want your agent to have a body?** → [Embodiment](#sec-187) — one $1 USDC call turns a prompt or image into a rigged, animated, voiced 3D avatar plus a one-tag embed for any website; no account, no separate rigging step
+- **Building UI?** → [ui-juice](#sec-487) is the shared game-feel library (count-ups, sparklines, ring gauges, live dots, the "it shipped" ripple) every surface animates with
- **Teaching another AI to use three.ws?** → [The Agent Skills pack](#sec-060) — portable `SKILL.md` folders that give any Claude surface (Claude Code, the Claude apps, the Agent SDK) three.ws's 3D-creation, wallet, and x402-economy skills; the 3D subset is cross-platform-safe
-- **Wondering why a gallery shows an initial instead of a picture?** → [Avatar thumbnails](#sec-115) — where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object doesn't exist), the two crons that keep coverage at 100%, and how to run the backfill
+- **Wondering why a gallery shows an initial instead of a picture?** → [Avatar thumbnails](#sec-116) — where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object doesn't exist), the two crons that keep coverage at 100%, and how to run the backfill
---
@@ -83946,50 +87242,54 @@ Curious what happens between the prompt and the model? [How the Forge works](#se
Deeper references that don't fit a track above but answer real questions:
-- [Docs World](#sec-176): these same docs as a walkable 3D world, where every section is a pavilion you can stroll up to and read inside the scene
-- [Agent Monitor](#sec-287): the ops room at [/monitor](https://three.ws/monitor), twelve live panels covering fleet activity, money, revenue, creations and uptime, plus how to add a panel
+- [Docs World](#sec-179): these same docs as a walkable 3D world, where every section is a pavilion you can stroll up to and read inside the scene
+- [Agent Monitor](#sec-288): the ops room at [/monitor](https://three.ws/monitor), twelve live panels covering fleet activity, money, revenue, creations and uptime, plus how to add a panel
- [Design tokens](#sec-004): the canonical design vocabulary (colors, spacing, type, motion) every surface builds from
-- [NVIDIA models on three.ws](#sec-296): the free hosted inference layer model by model, one key behind text-to-3D, chat, vision, embeddings, safety, and speech
-- [Run an inference node](#sec-252): join the supply side of the open inference network with your own hardware, from clone to a signed, verified result, on CPU or an NVIDIA GPU
-- [Free LLM providers](#sec-227): the failover chain of a dozen free AI providers behind every text completion, what each free tier gives, and how to add the next rung
-- [Tokens API on three.ws](#sec-402): the Solana Foundation asset layer that tells us which mints are the same asset, why it sits second in the market-data cascade, and the one env var that turns it on
-- [NVIDIA Inception membership](#sec-295): what the platform already runs on NVIDIA silicon and what the program adds on top
-- [The generator was never the hard part](#sec-297): our Nemotron Nano write-up, published on the NVIDIA Developer Forums
-- [three.ws on the AWS Builder Center](#sec-120): the index of our published AWS engineering writing, what code each article documents, and the checklist for publishing the next one
-- [The onboarding tier](#sec-300): why a first-time visitor sees ~20 nav destinations instead of ~100, how the Simple ⇄ Everything switch works, and which tier a new page belongs in
+- [NVIDIA models on three.ws](#sec-297): the free hosted inference layer model by model, one key behind text-to-3D, chat, vision, embeddings, safety, and speech
+- [Run an inference node](#sec-253): join the supply side of the open inference network with your own hardware, from clone to a signed, verified result, on CPU or an NVIDIA GPU
+- [Free LLM providers](#sec-228): the failover chain of a dozen free AI providers behind every text completion, what each free tier gives, and how to add the next rung
+- [Tokens API on three.ws](#sec-408): the Solana Foundation asset layer that tells us which mints are the same asset, why it sits second in the market-data cascade, and the one env var that turns it on
+- [NVIDIA Inception membership](#sec-296): what the platform already runs on NVIDIA silicon and what the program adds on top
+- [NVIDIA visibility map](#sec-300): every NVIDIA surface worth being on (Showcase, GTC, NGC, ACE, the forums, social), the verified intake route for each, and the member benefits nobody has claimed yet
+- [Big-tech recognition dispatch board](#sec-125): every big-tech surface ranked against every other by the odds of a published mention this week, which six are already one action from shipping, and what to stop chasing
+- [The generator was never the hard part](#sec-299): our Nemotron Nano write-up, published on the NVIDIA Developer Forums
+- [three.ws on the AWS Builder Center](#sec-121): the index of our published AWS engineering writing, what code each article documents, and the checklist for publishing the next one
+- [The onboarding tier](#sec-303): why a first-time visitor sees ~20 nav destinations instead of ~100, how the Simple ⇄ Everything switch works, and which tier a new page belongs in
- [What an agent can do](#sec-010): the full abilities dossier, generated from the source article
-- [Use cases and example workflows](#sec-151): five audience-specific walkthroughs tying shipped features to concrete outcomes
-- [UX Flow Atlas](#sec-483): screen-by-screen traces of the platform's core flows, starting with onboarding and creation
-- [Demo routes](#sec-170): the canonical map of every `/demo/*` and `/demos/*` route
-- [Agent trading spec](#sec-390): the proposed agent trading capability contract
-- [ERC-8004 validation attestation](#sec-186): the attestation written when an agent registers on-chain
-- [zauth](#sec-521): the vendored security infrastructure docs our agent auth builds on
+- [Use cases and example workflows](#sec-154): five audience-specific walkthroughs tying shipped features to concrete outcomes
+- [UX Flow Atlas](#sec-489): screen-by-screen traces of the platform's core flows, starting with onboarding and creation
+- [Demo routes](#sec-173): the canonical map of every `/demo/*` and `/demos/*` route
+- [Agent trading spec](#sec-396): the proposed agent trading capability contract
+- [ERC-8004 validation attestation](#sec-189): the attestation written when an agent registers on-chain
+- [zauth](#sec-546): the vendored security infrastructure docs our agent auth builds on
- [Agent tokens](#sec-070): configure the coin an agent will become, rehearse the launch for free against a real cluster, then launch it on Solana
-- [pump.fun program docs](#sec-336): the vendored on-chain program reference behind the launch surfaces
-- [pump-fun-mcp at the edge](#sec-331): the Cloudflare Workers mirror of the pump.fun MCP endpoint
-- [Package extraction](#sec-312): how reusable packages graduate out of the monorepo
+- [pump.fun program docs](#sec-341): the vendored on-chain program reference behind the launch surfaces
+- [pump-fun-mcp at the edge](#sec-337): the Cloudflare Workers mirror of the pump.fun MCP endpoint
+- [Package extraction](#sec-317): how reusable packages graduate out of the monorepo
- [Agent task briefs](#sec-065): self-contained task prompts for AI agents working on the platform
-- [Troubleshooting and FAQ](#sec-410): fixes organized by symptom
-- [The 3D viewer](#sec-499): the rendering layer reference (model loading, cameras, animation, lighting)
-- [Farcaster memory seeding](#sec-218): give an agent your Farcaster voice, proved with a wallet the account already verified, and revoke it in one click
-- [X memory seeding](#sec-510): seed an agent from your public X posts behind an explicit, versioned consent you can revoke (revocation deletes what the seed wrote)
-- [GitHub memory seeding](#sec-233): tick the profile, repositories, and READMEs your agent may read, and nothing outside that list is ever fetched or stored (disconnecting deletes every fact it wrote)
-- [The catalog quality gate](#sec-371): how a platform-seeded model earns its slot in the public catalog, the two stages it must pass, and why a rejected asset is kept rather than deleted
-- [Likeness evaluation](#sec-262): the Phase 1 verification metric, measured rather than asserted. Every reconstruction is rendered at three yaws and compared to the photos it was built from with an open-source face-recognition embedding, so "4 out of 5" means one fixed, calibrated thing
-- [Examples gallery](#sec-215): copy-paste-ready code for common use cases
+- [Troubleshooting and FAQ](#sec-416): fixes organized by symptom
+- [The 3D viewer](#sec-505): the rendering layer reference (model loading, cameras, animation, lighting)
+- [Avatar Artifact](#sec-107): the standalone viewer page, its ?agent= and ?model= parameters, and the iframe you paste anywhere
+- [Farcaster memory seeding](#sec-220): give an agent your Farcaster voice, proved with a wallet the account already verified, and revoke it in one click
+- [X memory seeding](#sec-515): seed an agent from your public X posts behind an explicit, versioned consent you can revoke (revocation deletes what the seed wrote)
+- [GitHub memory seeding](#sec-234): tick the profile, repositories, and READMEs your agent may read, and nothing outside that list is ever fetched or stored (disconnecting deletes every fact it wrote)
+- [Memory seed connectors](api-reference.md#memory-seed-connectors-api): the public read-only lane behind the seeding demo. Turn a GitHub, X, or Farcaster handle into a footprint payload, then synthesize a memory seed from any subset of them
+- [The catalog quality gate](#sec-376): how a platform-seeded model earns its slot in the public catalog, the two stages it must pass, and why a rejected asset is kept rather than deleted
+- [Likeness evaluation](#sec-263): the Phase 1 verification metric, measured rather than asserted. Every reconstruction is rendered at three yaws and compared to the photos it was built from with an open-source face-recognition embedding, so "4 out of 5" means one fixed, calibrated thing
+- [Examples gallery](#sec-217): copy-paste-ready code for common use cases
- [Cookbook](/cookbook): recipes you download and run, each one a real file executed against the live API, with the prose explaining why it is shaped that way
-- [Premium](#sec-326): the monthly Data API pass, one on-chain payment replacing per-call micropayments for 30 days
-- [Guardian console](#sec-235): the inbox for the other side of social recovery and inheritance of agent wallets
-- [Coin Clash](#sec-140): token-gated community battles between coin factions
-- [Daily Forge](#sec-168): a new deterministic 3D creative challenge every day
-- [x402 Studio](#sec-518): the merchant console for running a paid x402 business on three.ws
-- [Contributing](#sec-157): local environment setup through a mergeable pull request
-- [ERC-8004 smart contracts](#sec-382): contract interfaces, deployed addresses, and how to read and write each registry
-- [Internationalization](#sec-240): how the UI translation catalog works and how to add a locale
+- [Premium](#sec-332): the monthly Data API pass, one on-chain payment replacing per-call micropayments for 30 days
+- [Guardian console](#sec-236): the inbox for the other side of social recovery and inheritance of agent wallets
+- [Coin Clash](#sec-142): token-gated community battles between coin factions
+- [Daily Forge](#sec-171): a new deterministic 3D creative challenge every day
+- [x402 Studio](#sec-543): the merchant console for running a paid x402 business on three.ws
+- [Contributing](#sec-160): local environment setup through a mergeable pull request
+- [ERC-8004 smart contracts](#sec-388): contract interfaces, deployed addresses, and how to read and write each registry
+- [Internationalization](#sec-241): how the UI translation catalog works and how to add a locale
---
-<a id="sec-394"></a>
+<a id="sec-400"></a>
> **Source:** `docs/strategy-objects.md` · [↑ table of contents](#table-of-contents)
@@ -84095,16 +87395,16 @@ curl -s https://three.ws/api/sniper/backtest \
## Related
-- [Custody you can verify](#sec-167) - the spend limits and audit trail every live run is bounded by
-- [Financial controls](#sec-219) - the plain-English rules and firewall layered on the same enforcement point
-- [Oracle](#sec-310) - the conviction engine an entry gate can require before it fires
-- [Trading surfaces](#sec-409) - where equipped strategies execute through the guarded path
-- [Trading arenas](#sec-405) - competitive surfaces where strategies are put to the test
+- [Custody you can verify](#sec-170) - the spend limits and audit trail every live run is bounded by
+- [Financial controls](#sec-221) - the plain-English rules and firewall layered on the same enforcement point
+- [Oracle](#sec-315) - the conviction engine an entry gate can require before it fires
+- [Trading surfaces](#sec-415) - where equipped strategies execute through the guarded path
+- [Trading arenas](#sec-411) - competitive surfaces where strategies are put to the test
- [/strategies](https://three.ws/strategies) and [/strategy-lab](https://three.ws/strategy-lab) - the library and the workbench
---
-<a id="sec-395"></a>
+<a id="sec-401"></a>
> **Source:** `docs/swarms.md` · [↑ table of contents](#table-of-contents)
@@ -84114,9 +87414,9 @@ A **swarm** is a group of agents that pool real SOL into one on-chain treasury a
Two things make this different from a group chat with a shared wallet. The treasury is a real Solana account, so **every balance ties to chain and there are no virtual balances**: contributing and exiting execute actual transfers, spend-guarded and audited. And the kill switch is not the creator's alone, so a creator cannot trap members' funds in a swarm that is losing.
-Live at [three.ws/swarms](https://three.ws/swarms). This document covers the swarm surface specifically. For how agents coordinate in general (delegation, agent-to-agent messaging, task handoff), read [multi-agent](#sec-289) first, which this builds on rather than repeats. For the single-agent trading pipeline that a swarm's treasury reuses, see [agent sniper](#sec-061), and for the earned-autonomy model behind each member's weight, see [earned autonomy](#sec-384).
+Live at [three.ws/swarms](https://three.ws/swarms). This document covers the swarm surface specifically. For how agents coordinate in general (delegation, agent-to-agent messaging, task handoff), read [multi-agent](#sec-290) first, which this builds on rather than repeats. For the single-agent trading pipeline that a swarm's treasury reuses, see [agent sniper](#sec-061), and for the earned-autonomy model behind each member's weight, see [earned autonomy](#sec-390).
-> **This moves real money.** `contribute` and `exit` transfer real SOL on Solana mainnet. Nothing here is simulated. Read the [risk acknowledgment](#sec-365) before joining a swarm with funds you cannot afford to lose.
+> **This moves real money.** `contribute` and `exit` transfer real SOL on Solana mainnet. Nothing here is simulated. Read the [risk acknowledgment](#sec-370) before joining a swarm with funds you cannot afford to lose.
Code: [api/swarms/index.js](../api/swarms/index.js) (directory plus every mutation), [api/swarms/[id].js](../api/swarms/[id].js) (dashboard state and the live stream), [api/_lib/swarms.js](../api/_lib/swarms.js) (policy, treasury, consensus, kill switch).
@@ -84195,6 +87495,24 @@ This is the structural answer to the obvious question about pooling money with s
`max_member_share_bps` is the complement. Capping any one member's share (50% by default) stops a single whale from owning the vote outright.
+## The page, and how to link into it
+
+[three.ws/swarms](https://three.ws/swarms) is one page with two views: the directory and a single swarm's live dashboard. Which view you get, and what the directory is filtered to, is entirely in the query string, so any view is a link you can paste to someone else and the browser's back button walks between them.
+
+| URL | What it shows |
+|---|---|
+| `/swarms` | Every open swarm on mainnet |
+| `/swarms?network=devnet` | The same directory on devnet |
+| `/swarms?scope=mine` | Only swarms you created or funded (asks you to sign in if you have not) |
+| `/swarms?scope=mine&network=devnet` | Both filters together |
+| `/swarms?id=<swarm-uuid>` | That swarm's dashboard: treasury, members, positions, and the live vote and payout feeds |
+
+A swarm card in the directory is a real link to its `?id=` URL, so middle-click and cmd/ctrl-click open a swarm in a new tab. A plain click swaps the view in place without a page load.
+
+The dashboard holds an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) open against `/api/swarms/<id>/stream` for as long as it is on screen, which is where the live consensus votes, payouts, and treasury ticks come from. It reconnects on its own with a backoff, and the indicator beside the swarm's name reports which state it is in.
+
+Anything that moves SOL (joining, contributing, exiting) or governs the swarm (pause, kill) needs a signed-in account **and** an agent to act through, because the agent's wallet is what funds the treasury and its track record is what carries your vote weight. The page offers you the way to get each one rather than only naming the requirement.
+
## API
`GET` is public for the directory. Every mutation requires a signed-in account, and the caller must own the agent it acts for.
@@ -84226,6 +87544,12 @@ curl -s https://three.ws/api/swarms/<SWARM_ID> # full dashboard state
curl -sN https://three.ws/api/swarms/<SWARM_ID>/stream # SSE: votes, payouts, treasury ticks
```
+Both are public reads and both answer CORS preflights, so an `EventSource` on the
+stream works from an allowed cross-origin page, not only from three.ws itself. The
+stream sends a `hello` event with the treasury address, then `vote`, `payout`, and
+`tick` events, and closes itself after 280 seconds; `EventSource` reconnects on its
+own. A `HEAD` on either URL returns the headers without opening the poll loop.
+
### Mutations
All mutations are `POST /api/swarms` with an `action` field.
@@ -84250,7 +87574,7 @@ curl -s -X POST https://three.ws/api/swarms \
-d '{"action":"join","swarm_id":"<SWARM_UUID>","agent_id":"<AGENT_UUID>"}'
```
-**`contribute` and `exit` move real SOL.** Amounts accept either `sol` or `lamports`; `sol` is multiplied by 1e9 and rounded.
+**`contribute` and `exit` move real SOL.** Amounts accept either `sol` or `lamports`, and `lamports` wins if you send both; `sol` is multiplied by 1e9 and rounded. Anything that is not a finite, positive number inside the safe-integer range (`"abc"`, `Infinity`, `1e30`) is rejected as `bad_amount` before anything is signed.
```bash
# Contribute 0.05 SOL. This is a real on-chain transfer.
@@ -84275,7 +87599,7 @@ Every failure returns `{ error, error_description }` with a specific code rather
| Status | Code | Meaning |
|---|---|---|
| 400 | `bad_agent`, `bad_swarm` | The id is missing or not a UUID |
-| 400 | `bad_amount` | `contribute` without a positive `sol` or `lamports` |
+| 400 | `bad_amount` | `contribute` without a positive `sol` or `lamports`, or with one that is not a finite number in range |
| 400 | `bad_action` | Unrecognized `action` |
| 400 | `bad_name` | `create` with an empty name or one over 80 characters |
| 400 | `too_small` | Contribution under the 0.005 SOL floor |
@@ -84285,6 +87609,7 @@ Every failure returns `{ error, error_description }` with a specific code rather
| 403 | `forbidden` | Acting for an agent you do not own, or a creator-only action (`pause`, `resume`) from a member |
| 403 | `invite_only` | `join` by anyone but the creator on a swarm with `join_open: false` |
| 403 | `below_threshold` | `kill` from a member holding under `kill_threshold_bps` |
+| 415 | `bad_request` | A mutation sent without `Content-Type: application/json` |
| 429 | `rate_limited` | Over 30 mutations per minute for this user |
| 404 | `not_found` | No such swarm |
| 404 | `agent_not_found` | No such agent |
@@ -84296,14 +87621,14 @@ Every failure returns `{ error, error_description }` with a specific code rather
## Related
-- [Multi-agent coordination](#sec-289), the general model swarms specialize.
-- [Trading arenas](#sec-405), which covers swarms alongside tournaments, the theater, and vaults.
-- [USDC agent vaults](#sec-497), the other way to pool capital behind an agent. A vault has one manager and NAV-priced shares; a swarm has many voters and one treasury.
-- [Custody you can verify](#sec-167) for the spend guards every transfer here passes through.
+- [Multi-agent coordination](#sec-290), the general model swarms specialize.
+- [Trading arenas](#sec-411), which covers swarms alongside tournaments, the theater, and vaults.
+- [USDC agent vaults](#sec-503), the other way to pool capital behind an agent. A vault has one manager and NAV-priced shares; a swarm has many voters and one treasury.
+- [Custody you can verify](#sec-170) for the spend guards every transfer here passes through.
---
-<a id="sec-396"></a>
+<a id="sec-402"></a>
> **Source:** `docs/syndication.md` · [↑ table of contents](#table-of-contents)
@@ -84323,6 +87648,54 @@ items in `data/rss/items.json` may still carry a `syndication` field
recording where they were mirrored at publish time; it is inert
metadata.
+## Feed URLs and sources
+
+`https://three.ws/rss/announcements.xml` and the shorter
+`https://three.ws/rss.xml` serve the same feed. Both accept one optional
+query parameter, `source`, which selects what the feed is built from:
+
+| `?source=` | Feed contents |
+| --- | --- |
+| omitted, or `curated` | The hand-edited items in `data/rss/items.json`. This is what HackerNoon and every public subscriber reads. |
+| `trythreews` | Announcements archived from [@trythreews](https://x.com/trythreews). |
+| `nichxbt` | Announcements archived from [@nichxbt](https://x.com/nichxbt). |
+| `archive` | Both archived accounts, merged and de-duplicated, newest first. |
+
+The value is case-insensitive. Anything else is a `400` with
+`{"error":"unknown_source"}` rather than a silent fall-back to the
+curated feed, so a subscriber who mistypes a source finds out instead of
+quietly receiving a different feed forever. Responses are cached for ten
+minutes at the edge and are `application/rss+xml`; the endpoint is
+read-only and answers `GET`, `HEAD`, and `OPTIONS` only.
+
+Fetch it from anywhere:
+
+```bash
+curl -s 'https://three.ws/rss/announcements.xml' | xmllint --noout - && echo 'valid feed'
+```
+
+### Why feed validity is load-bearing
+
+XML has no partial failure: one illegal byte anywhere in the document
+makes the *whole* feed unreadable, so a single bad post takes every
+subscriber offline rather than dropping one item. The builder in
+[`api/_lib/rss-feed.js`](../api/_lib/rss-feed.js) therefore neutralizes
+the three inputs that can do that, and
+[`tests/rss-announcements.test.js`](../tests/rss-announcements.test.js)
+pins each one:
+
+- **A `]]>` inside an item body**, which would close the `CDATA` section
+ early. It is re-emitted across two sections so it survives as text.
+- **Characters XML 1.0 forbids** (control bytes other than tab, newline
+ and carriage return; unpaired surrogates). Escaping cannot rescue
+ these, so they are dropped. Real astral characters and emoji are kept.
+- **Prose that spells the linkifier's internal URL placeholder.** The
+ placeholder is a form escaped text cannot contain, so a post can never
+ be mistaken for a link the builder set aside.
+
+Editing `data/rss/items.json` by hand is safe against all three, but run
+the `curl | xmllint` check above after a deploy that touches the feed.
+
## HackerNoon
HackerNoon is one of the world's largest independent tech publications.
@@ -84331,12 +87704,12 @@ so any item added to the feed is picked up on their next crawl with a
canonical URL pointing back to `three.ws/news/<slug>`. Nothing to
configure on our side beyond keeping the feed valid.
-See also: [Partners](#sec-313), [Listings and
-distribution](#sec-264).
+See also: [Partners](#sec-318), [Listings and
+distribution](#sec-265).
---
-<a id="sec-397"></a>
+<a id="sec-403"></a>
> **Source:** `docs/talking-avatar-video.md` · [↑ table of contents](#table-of-contents)
@@ -84345,26 +87718,27 @@ distribution](#sec-264).
Pick one of your three.ws avatars, upload an audio track, add an optional scene description, and a GPU worker renders a lip-synced talking-head video you can download as MP4. The lipsync and rendering happen server-side on a dedicated Cloud Run worker; the browser is just a picker, an uploader, and a player.
Page: [/create/video](https://three.ws/create/video)
-API: `POST /api/avatar/presign-audio` · `POST /api/avatar/video-generate` · `GET /api/avatar/video-status`
+API: `POST /api/avatar/presign-audio` · `GET`/`POST /api/avatar/video-generate` · `GET /api/avatar/video-status`
## Why it exists
-Real-time browser lipsync (see [Lipsync](#sec-263)) is perfect for live avatars, but it cannot produce a finished, shareable file with rendered frames, matched motion, and a scene. Talking Avatar Video is the export path: it takes an avatar you already own and an audio track you supply and returns a polished clip. It closes the loop from "I made an avatar" to "here is a video of my avatar saying this," without any local tooling.
+Real-time browser lipsync (see [Lipsync](#sec-264)) is perfect for live avatars, but it cannot produce a finished, shareable file with rendered frames, matched motion, and a scene. Talking Avatar Video is the export path: it takes an avatar you already own and an audio track you supply and returns a polished clip. It closes the loop from "I made an avatar" to "here is a video of my avatar saying this," without any local tooling.
-Note on scope: the shipped flow uploads an audio file. It does not synthesize speech from a typed script and it does not offer a voice picker inside this page (the page's marketing meta text mentions "type a script, pick a voice," but the UI does neither). To generate the audio first, use [Voice Lab](#sec-500) and bring the resulting clip here.
+Note on scope: the shipped flow uploads an audio file. It does not synthesize speech from a typed script and it does not offer a voice picker inside this page (the page's marketing meta text mentions "type a script, pick a voice," but the UI does neither). To generate the audio first, use [Voice Lab](#sec-506) and bring the resulting clip here.
## How it works
The page ([`pages/create/video.html`](../pages/create/video.html)) loads [`src/create-video.js`](../src/create-video.js), which uses `apiFetch` from [`src/account.js`](../src/account.js) and a `<model-viewer>` preview.
1. **Auth gate.** On load it checks `GET /api/auth/me`; if you are not signed in it redirects to `/login?next=%2Fcreate%2Fvideo`.
-2. **Pick an avatar.** It calls `GET /api/avatars` and renders your avatar library into a thumbnail bar, auto-selecting the first. The selected GLB is shown in a `<model-viewer>`. Private avatars resolve their GLB lazily through `GET /api/avatars/:id` (a short-lived signed URL). With no avatars it falls back to `/avatars/default.glb`.
-3. **Upload audio.** Drag in or pick a WAV, MP3, M4A, OGG, or FLAC file. The client POSTs `{ filename, content_type, bytes }` to `/api/avatar/presign-audio`, gets a presigned PUT URL plus a `public_url`, and PUTs the raw bytes to R2/S3. `bytes` is the declared file size and is required: a presigned PUT cannot carry a content-length policy, so it is the only place the 64 MB cap can be enforced. There is no data-URI fallback, because `video-generate` only accepts an https three.ws-hosted `audio_url` (see the SSRF guard below) and would reject a `data:` URI with a `400`; a failed presign surfaces as a real error on the page.
-4. **Describe the scene (optional).** A textarea takes a scene description such as "A person speaking on a stage with dramatic lighting." This is a scene prompt, not a script.
-5. **Generate.** With an avatar and audio ready, Generate POSTs `{ image_url, audio_url, avatar_id?, prompt? }` to `/api/avatar/video-generate`. The server SSRF-guards both URLs (https on the app or S3 domain), resolves the avatar image if only an `avatar_id` was sent (with an ownership/visibility check), and forwards to the worker.
-6. **Render, server-side.** The generate endpoint calls the **LongCat-Video-Avatar-1.5** worker on Google Cloud Run (`POST {LONGCAT_WORKER_URL}/generate`, bearer-authenticated), which produces the lip-synced frames. The endpoint returns `202 { job_id, status }`.
-7. **Poll.** The client polls `GET /api/avatar/video-status?job_id=...` every 5 seconds (20-minute safety timeout). Status runs `queued` -> `running` -> `done` | `failed`, with an optional `progress` (0 to 1).
-8. **Download.** On `done`, the `video_url` is set as the `<video>` source and the download anchor (`download="avatar-video.mp4"`). Progress copy: "Takes 2 to 4 minutes on GPU. Hang tight."
+2. **Availability probe.** In parallel it calls `GET /api/avatar/video-generate`, which answers `{ available, reason, free_generations, accepts }` without submitting anything. When the GPU worker is not configured on the deployment the page raises a "Video rendering is offline" banner and keeps Generate disabled, so nobody is walked through an upload that can only end in a `503`. A probe that itself fails is treated as inconclusive: generation stays enabled and the real POST reports what happened.
+3. **Pick an avatar.** It calls `GET /api/avatars` and renders your avatar library into a thumbnail bar of real `<button>` elements, auto-selecting the first. The selected GLB is shown in a `<model-viewer>`. Private avatars resolve their GLB lazily through `GET /api/avatars/:id` (a short-lived signed URL). Three distinct outcomes: avatars found (thumbnails), none yet (an empty state linking to `/create`), and the list call failing (an error row with a Retry that refetches). The last two show `/avatars/default.glb` in the viewer purely so the panel is not a blank box; it is never a generation source, and Generate stays disabled with a hint saying what is missing.
+4. **Upload audio.** Drag in or pick a WAV, MP3, M4A, OGG, or FLAC file (a drop is accepted on MIME type *or* file extension, because some file managers hand over an empty `type`). The picked clip gets an inline `<audio>` preview plus its duration and size, and the hint under Generate turns the duration into an expectation ("about 3 clips of video from this audio", one clip per 3.72 s segment). The client POSTs `{ filename, content_type, bytes }` to `/api/avatar/presign-audio`, gets a presigned PUT URL plus a `public_url`, and PUTs the raw bytes to R2/S3. `bytes` is the declared file size and is required: a presigned PUT cannot carry a content-length policy, so it is the only place the 64 MB cap can be enforced. There is no data-URI fallback, because `video-generate` only accepts an https three.ws-hosted `audio_url` (see the SSRF guard below) and would reject a `data:` URI with a `400`; a failed presign surfaces as a real error on the page.
+5. **Describe the scene (optional).** A textarea takes a scene description such as "A person speaking on a stage with dramatic lighting." This is a scene prompt, not a script.
+6. **Generate.** With an avatar and audio ready, Generate POSTs `{ audio_url, avatar_id, prompt? }` to `/api/avatar/video-generate`. The page deliberately sends no `image_url`: the worker writes whatever that URL points at into `ref_image.png` and feeds it to inference as `cond_image`, so it has to be a raster image, and only the server can resolve one it trusts. Server-side, `resolveImageUrl` checks ownership/visibility, then returns the avatar's stored thumbnail, or (when it has none) a portrait render produced by the same cached pipeline behind [`/api/avatar/render`](#sec-096), so a second video from the same avatar costs a cache lookup rather than another chromium launch. Both URLs are SSRF-guarded (https on the app or S3 domain) before anything reaches the worker.
+7. **Render, server-side.** The generate endpoint calls the **LongCat-Video-Avatar-1.5** worker on Google Cloud Run (`POST {LONGCAT_WORKER_URL}/generate`, bearer-authenticated), which produces the lip-synced frames. The endpoint returns `202 { job_id, status }`.
+8. **Poll.** The client polls `GET /api/avatar/video-status?job_id=...` every 5 seconds (20-minute safety timeout). Status runs `queued` -> `running` -> `done` | `failed`, with an optional `progress` (0 to 1). A transient failure is ridden out, but six consecutive failed polls (30 s, e.g. a job that no longer exists or an expired session) end the wait with "Lost contact with the render job" instead of spinning silently to the timeout.
+9. **Download.** On `done`, the `video_url` is set as the `<video>` source and the download anchor (`download="avatar-video.mp4"`). Progress copy: "Takes 2 to 4 minutes on GPU. Hang tight."
## Walkthrough
@@ -84382,6 +87756,10 @@ session cookie only (`__Host-sid`); API bearer tokens are not accepted on this
surface, so from a script reuse the cookie from a logged-in browser session.
```bash
+# 0. Is the renderer up on this deployment? (No session needed.)
+curl 'https://three.ws/api/avatar/video-generate'
+# -> { "available": true, "reason": "ready", "free_generations": 1, "accepts": { … } }
+
# 1. Presign an audio upload slot.
curl -X POST 'https://three.ws/api/avatar/presign-audio' \
-H 'cookie: __Host-sid=<SESSION>' -H 'content-type: application/json' \
@@ -84391,11 +87769,12 @@ curl -X POST 'https://three.ws/api/avatar/presign-audio' \
# 2. PUT the raw bytes to the presigned URL.
curl -X PUT '<PUT url>' -H 'content-type: audio/mpeg' --data-binary @line.mp3
-# 3. Kick off generation with an avatar image + the uploaded audio.
+# 3. Kick off generation from an avatar id + the uploaded audio. Prefer this over
+# passing image_url yourself: the server resolves a real reference image.
curl -X POST 'https://three.ws/api/avatar/video-generate' \
-H 'cookie: __Host-sid=<SESSION>' -H 'content-type: application/json' \
- -d '{ "image_url": "https://…/avatar.png", "audio_url": "https://…/line.mp3",
- "avatar_id": "<AVATAR_ID>", "prompt": "A person talking on a bright stage." }'
+ -d '{ "audio_url": "https://…/line.mp3", "avatar_id": "<AVATAR_ID>",
+ "prompt": "A person talking on a bright stage." }'
# -> 202 { "job_id": "…", "status": "queued" }
# 4. Poll until done, then fetch video_url.
@@ -84404,30 +87783,31 @@ curl -H 'cookie: __Host-sid=<SESSION>' \
# -> { "job_id": "…", "status": "done", "progress": 1, "video_url": "https://…/out.mp4", "error": null, "updated_at": "…" }
```
-`audio_url` is required; `image_url` may be omitted when `avatar_id` is present (the server resolves the avatar's stored image). `prompt` defaults to "A person talking naturally."
+`audio_url` is required. Send `avatar_id` and omit `image_url`: the server then resolves a reference image it can vouch for (stored thumbnail, else a portrait render). A caller-supplied `image_url` is still accepted for integrations that host their own reference frame, but it must be a raster image on a three.ws host, and passing a `.glb` there yields a job that fails inside the worker. `prompt` defaults to "A person talking naturally."
## States and limits
- **Auth required.** The page gates on `/api/auth/me`; every endpoint re-checks the session and returns `401` otherwise.
-- **Free tier: one lifetime generation.** Free-plan users get exactly one video. The quota is reserved race-safely (a `usage_events` row is inserted before the worker call and released if submission fails, so an outage never burns the trial). On exhaustion the server returns `402 free_trial_used` and the page relabels the retry button "Upgrade plan" linking to `/dashboard`. Paid plans are unlimited.
+- **Free tier: one lifetime generation.** Free-plan users get exactly one video. The quota is reserved race-safely (a `usage_events` row is inserted before the worker call and released if submission fails, so an outage never burns the trial). On exhaustion the server returns `402 free_trial_used` and the page retargets the button under the error to "Upgrade plan", pointing at `/dashboard`; the label and the click target move together, so a later unrelated error goes back to a plain "Try again". Paid plans are unlimited.
- **Rate limits.** Per-user and global rate limits on `video-generate` return `429`.
- **Input formats.** Audio: WAV, MP3, M4A, OGG, FLAC (validated against an allow-list; `415` otherwise). Uploads go to R2/S3 under `u/{userId}/audio/{uuid}.{ext}`.
- **Upload limits.** `presign-audio` requires a declared `bytes` (`400 invalid_request` without one) and caps a clip at 64 MB (`413 payload_too_large`). Signing also draws on the per-user upload bucket, so a session cannot mint unlimited write grants (`429` when spent).
- **SSRF guard.** `image_url` and `audio_url` must be https on the app origin or the S3 public domain, else `400 invalid_request`.
- **Ownership.** `video-status` verifies the job belongs to you (`404` if unknown, `403` if another user's). Avatar image resolution enforces owner-or-public visibility.
-- **Timing and errors.** Renders take ~2 to 4 minutes; the client times out after 20 minutes. UI states cover idle, uploading audio, queuing, rendering with a percent, done, and error (upload failed, could not start, failed on the server, timed out). Server errors include `502 worker_unreachable`/`worker_error` and `503 worker_unconfigured`.
+- **Timing and errors.** Renders take ~2 to 4 minutes; the client times out after 20 minutes. UI states cover idle (with a hint naming what is still missing), no avatars, avatar list failed, renderer offline, uploading audio, queuing, rendering with a percent and a clip count, done, and error (upload failed, could not start, renderer offline, lost contact with the job, failed on the server, timed out). Server errors include `502 worker_unreachable`/`worker_error`, `502 reference_image_failed` (no thumbnail and the portrait render did not succeed), and `503 worker_unconfigured`.
+- **Deployment requirement.** `LONGCAT_WORKER_URL` and `LONGCAT_WORKER_KEY` must both be set on the API service; without them `GET /api/avatar/video-generate` reports `available: false` and every submission answers `503 worker_unconfigured`.
- **Output.** MP4, downloaded straight from the worker's `video_url`.
## Related
-- [Voice Lab](#sec-500): clone or synthesize the audio track you upload here.
-- [Lipsync](#sec-263): the real-time, in-browser lipsync path (no export).
-- [Selfie to Avatar](#sec-372) and [Avatar reconstruction](#sec-113): create the avatar you render.
+- [Voice Lab](#sec-506): clone or synthesize the audio track you upload here.
+- [Lipsync](#sec-264): the real-time, in-browser lipsync path (no export).
+- [Selfie to Avatar](#sec-377) and [Avatar reconstruction](#sec-114): create the avatar you render.
- Pages: [/create/video](https://three.ws/create/video), [/create](https://three.ws/create), [/dashboard](https://three.ws/dashboard).
---
-<a id="sec-398"></a>
+<a id="sec-404"></a>
> **Source:** `docs/terminal.md` · [↑ table of contents](#table-of-contents)
@@ -84441,7 +87821,7 @@ APIs (all real, all called by the page): `/api/pump/trades-stream` (SSE firehose
## Why it exists
-Early pump.fun trading punishes context-switching. The launch is on one tab, the intel score on another, the wallet in a third, and by the time you have alt-tabbed to all of them the candle is gone. Mission Control collapses the whole loop into a single screen you drive from the home row: read the launch, read whether it is real, size it, and send the order without ever touching the mouse. It sits at the top of the [trading surfaces](#sec-409) map. Radar and Coin Intelligence answer "what launched and is it real," the Live Trade Feed answers "what won," and Mission Control is where you act on all of it. It is the only surface that executes.
+Early pump.fun trading punishes context-switching. The launch is on one tab, the intel score on another, the wallet in a third, and by the time you have alt-tabbed to all of them the candle is gone. Mission Control collapses the whole loop into a single screen you drive from the home row: read the launch, read whether it is real, size it, and send the order without ever touching the mouse. It sits at the top of the [trading surfaces](#sec-415) map. Radar and Coin Intelligence answer "what launched and is it real," the Live Trade Feed answers "what won," and Mission Control is where you act on all of it. It is the only surface that executes.
## How it works
@@ -84514,6 +87894,28 @@ es.addEventListener('graduation', (e) => console.log('graduated', JSON.parse(e.d
// The stream self-closes about every 90s; reconnect on 'close'.
```
+Pass `?mint=<MINT>` (up to 20, comma separated) to receive that token's `trade`
+events instead of the global firehose. A mint that is not a base58 Solana
+address is rejected with a `400 invalid_mint` before the stream opens.
+
+Per-token trades come from PumpPortal's `subscribeTokenTrade`, which it gates
+behind an API key funded with at least 0.02 SOL (`PUMPPORTAL_API_KEY`). When
+that subscription is refused the socket stays open but no trade can ever
+arrive, so the server forwards the refusal as a `notice` event. Listen for it
+and show a degraded state rather than an idle-looking live tape:
+
+```javascript
+const trades = new EventSource('https://three.ws/api/pump/trades-stream?mint=<MINT>');
+trades.addEventListener('trade', (e) => console.log('trade', JSON.parse(e.data)));
+trades.addEventListener('notice', (e) => {
+ // { code: 'upstream_subscription_refused', message, detail, kind, mints }
+ console.warn('live trades unavailable', JSON.parse(e.data));
+});
+```
+
+Settled trades for graduated coins are unaffected: they come from
+`/api/pump/dex-trades`, which needs no PumpPortal credential.
+
## States and limits
- **Auth.** The page runs read-only signed out. Trading, `/api/sniper/history`, and the holdings and trade endpoints require a session or bearer token plus ownership of the agent. Signed out, the ticket links to `/login?next=%2Fterminal`.
@@ -84524,15 +87926,15 @@ es.addEventListener('graduation', (e) => console.log('graduated', JSON.parse(e.d
## Related
-- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-409)
-- [Coin Radar](#sec-357) and [Smart Money Radar](#sec-383) feed the same intel into their own surfaces
-- [Oracle: the conviction engine](#sec-310) supplies the fused conviction score
-- [Financial controls and custody guardrails](#sec-219) and [custody](#sec-167) document the server-side rails every order runs through
+- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-415)
+- [Coin Radar](#sec-362) and [Smart Money Radar](#sec-389) feed the same intel into their own surfaces
+- [Oracle: the conviction engine](#sec-315) supplies the fused conviction score
+- [Financial controls and custody guardrails](#sec-221) and [custody](#sec-170) document the server-side rails every order runs through
- Pages: [/terminal](https://three.ws/terminal) · [/radar](https://three.ws/radar) · [/trades](https://three.ws/trades) · [/watchlist](https://three.ws/watchlist)
---
-<a id="sec-399"></a>
+<a id="sec-405"></a>
> **Source:** `docs/three-microbuy.md` · [↑ table of contents](#table-of-contents)
@@ -84694,13 +88096,13 @@ The response reports `fired`, `paid`, `buys`, `pending`, `errors`, `toll_spent_u
## Related
-- [docs/x402-ring-economy.md](#sec-516) — the closed-loop x402 ring the toll settles through.
+- [docs/x402-ring-economy.md](#sec-541) — the closed-loop x402 ring the toll settles through.
- [api/_lib/token/buyback.js](../api/_lib/token/buyback.js) — the daily buyback lane.
- [api/_lib/token/config.js](../api/_lib/token/config.js) — `$THREE` mint, treasury, and split policy.
---
-<a id="sec-400"></a>
+<a id="sec-406"></a>
> **Source:** `docs/timeline.md` · [↑ table of contents](#table-of-contents)
@@ -84832,7 +88234,7 @@ server reads that route table on boot).
---
-<a id="sec-401"></a>
+<a id="sec-407"></a>
> **Source:** `docs/token-gated-3d-embeds.md` · [↑ table of contents](#table-of-contents)
@@ -84840,7 +88242,7 @@ server reads that route table on boot).
> **Audience:** Creators who want a holder-only interactive 3D scene, and developers wiring the flow up themselves.
-three.ws already lets you embed a live, interactive 3D avatar or on-chain agent on any page with one script tag ([Share & embed](#sec-373), [Embedding Guide](#sec-183)). Token gating adds one thing on top: **the scene only renders for a visitor who holds enough of a specific token** — verified with a real on-chain balance read, not a client-side check anyone could fake.
+three.ws already lets you embed a live, interactive 3D avatar or on-chain agent on any page with one script tag ([Share & embed](#sec-378), [Embedding Guide](#sec-186)). Token gating adds one thing on top: **the scene only renders for a visitor who holds enough of a specific token** — verified with a real on-chain balance read, not a client-side check anyone could fake.
The canonical use case is **$THREE-holder-only content**: a private avatar, a branded scene, a preview only your community can see. The gate also accepts any SPL token at runtime — a project can gate with their own coin — but three.ws never markets or defaults to anything other than `$THREE`.
@@ -84945,13 +88347,13 @@ Every check that matters happens on the server:
- Spec (wire formats, resolver contract, token format): [specs/EMBED_SPEC.md § Token Gating](../specs/EMBED_SPEC.md#token-gating)
- MCP tool: [docs/mcp.md § create_gated_embed](mcp.md#create_gated_embed)
-- Embed runtime this builds on: [`<three-d>` / embed v1](https://three.ws/embed/v1/preview), [Share & embed](#sec-373)
+- Embed runtime this builds on: [`<three-d>` / embed v1](https://three.ws/embed/v1/preview), [Share & embed](#sec-378)
- Nothing rendering where you pasted the snippet? The [Embed Doctor](https://three.ws/embed-doctor) loads your page in a real browser and names the line to change. It checks a `<three-d>` gated snippet exactly like an ungated `<agent-3d>` one, and a locked embed reads as healthy: the lock is the product working, not a failure.
-- Related: [Hold-to-access tiers](#sec-237) (site-wide $THREE tiers, distinct from per-embed gates)
+- Related: [Hold-to-access tiers](#sec-238) (site-wide $THREE tiers, distinct from per-embed gates)
---
-<a id="sec-402"></a>
+<a id="sec-408"></a>
> **Source:** `docs/tokens-xyz.md` · [↑ table of contents](#table-of-contents)
@@ -85117,12 +88519,12 @@ The batch market read is deliberately **not** cached here. Its caller in the mar
## Related
-- [Market Data API](#sec-268) - the pay-per-call x402 endpoints behind every `/markets` page
-- [Free LLM providers](#sec-227) - the same failover-chain pattern applied to text completion
+- [Market Data API](#sec-269) - the pay-per-call x402 endpoints behind every `/markets` page
+- [Free LLM providers](#sec-228) - the same failover-chain pattern applied to text completion
---
-<a id="sec-403"></a>
+<a id="sec-409"></a>
> **Source:** `docs/trader-card.md` · [↑ table of contents](#table-of-contents)
@@ -85141,11 +88543,13 @@ The Wallet Intelligence view renders, for any base-58 address:
## Where the numbers come from
-Nothing here is typed in by the trader. The Oracle smart-money brain continuously indexes pump.fun trading: per-wallet, per-coin buy/sell aggregates observed on-chain, joined with each coin's outcome (graduated, rugged, ATH multiple). Rollup workers grade every indexed wallet into a reputation row — the same pedigree ledger that powers Oracle's WHO pillar ([the conviction engine](#sec-310)). Per-coin P&L is simply `sold − bought` in SOL, with USD as a live enrichment that hides itself rather than guessing when the price feed is down.
+Nothing here is typed in by the trader. The Oracle smart-money brain continuously indexes pump.fun trading: per-wallet, per-coin buy/sell aggregates observed on-chain, joined with each coin's outcome (graduated, rugged, ATH multiple). Rollup workers grade every indexed wallet into a reputation row — the same pedigree ledger that powers Oracle's WHO pillar ([the conviction engine](#sec-315)). Per-coin P&L is simply `sold − bought` in SOL, with USD as a live enrichment that hides itself rather than guessing when the price feed is down.
-If a wallet hasn't been indexed yet (the engine tracks wallets it has observed trading pump.fun launches), the page says "not indexed yet" instead of rendering an empty scorecard.
+If a wallet hasn't been indexed yet (the engine tracks wallets it has observed trading pump.fun launches), the page says "not indexed yet" instead of rendering an empty scorecard. "Indexed" means the wallet has been *observed trading*, which happens well before the rollup workers grade it into a reputation row: a wallet with real trades and no grade yet still gets the full ledger and window aggregates, with the reputation panel honestly reading `unproven` until the scorer catches up.
-**One precision worth knowing:** the pasted-wallet view reports *raw* on-chain aggregates. The platform's own [trader leaderboard](https://three.ws/leaderboard) — which ranks three.ws agents — applies a stricter pipeline on top: round-trips on coins the trader launched themselves are split out of the credited record ("self-dealing excluded"), snipe hit-rate only counts mints with a proven on-chain birth, and a verification badge requires minimum closed trades, unique coins, and a churn ceiling. Two truth layers, both honest about what they measure: external wallets get the raw read; verified agents get the audited one. Details in [trading-arenas](#sec-405).
+**Realized vs. open.** Win, loss, and win-rate figures count *closed* positions only, because an untouched bag is not a loss. A position counts as closed once effectively all of the bought supply has been sold. `realized_pnl_sol` is the sum over those closed positions; `net_pnl_sol` books every lamport in and out of the loaded window, so it charges an open bag's entry as if it were written off. For a wallet that is still holding, `net_pnl_sol` is the floor and `realized_pnl_sol` is the outcome so far.
+
+**One precision worth knowing:** the pasted-wallet view reports *raw* on-chain aggregates. The platform's own [trader leaderboard](https://three.ws/leaderboard) — which ranks three.ws agents — applies a stricter pipeline on top: round-trips on coins the trader launched themselves are split out of the credited record ("self-dealing excluded"), snipe hit-rate only counts mints with a proven on-chain birth, and a verification badge requires minimum closed trades, unique coins, and a churn ceiling. Two truth layers, both honest about what they measure: external wallets get the raw read; verified agents get the audited one. Details in [trading-arenas](#sec-411).
## Claiming: one signature, no gas
@@ -85170,18 +88574,24 @@ The preview endpoint is public and cacheable:
curl 'https://three.ws/api/traders/preview?wallet=<BASE58_ADDRESS>'
```
-Returns the identity summary, KPI aggregates, and the per-coin ledger — `known:false` for unindexed wallets. Agent-side, the same pedigree data flows through the intel MCP tools ([docs/mcp.md](#sec-276)).
+Returns the identity summary, KPI aggregates, and the per-coin ledger (up to 60 coins, most recently active first).
+
+- `known` is true once the rollup has graded the wallet into a reputation row.
+- `claimable` is true once there is a real on-chain record to claim, which includes an indexed-but-not-yet-graded wallet. A wallet with neither is the unindexed case.
+- `network` accepts `mainnet` (default) or `devnet`, and scopes both the reputation read and the coin ledger. Anything else falls back to `mainnet`.
+
+The read is CDN-cacheable for two minutes. It never answers an empty record on a database fault: an unreachable brain returns `503 service_unavailable` with `Retry-After` and `Cache-Control: no-store`, so a transient outage can't be cached as "this trader has no track record". Agent-side, the same pedigree data flows through the intel MCP tools ([docs/mcp.md](#sec-277)).
## Related
-- [Trader Passport](#sec-404): the on-chain credential a claimed record earns, and how another app verifies it
-- [Oracle](#sec-310) — the WHO pillar runs on this same wallet-reputation ledger
-- [Trading arenas](#sec-405) — where a verified track record unlocks tournaments, vaults, and mirrors
-- [Trading surfaces](#sec-409) — the solo trading stack
+- [Trader Passport](#sec-410): the on-chain credential a claimed record earns, and how another app verifies it
+- [Oracle](#sec-315) — the WHO pillar runs on this same wallet-reputation ledger
+- [Trading arenas](#sec-411) — where a verified track record unlocks tournaments, vaults, and mirrors
+- [Trading surfaces](#sec-415) — the solo trading stack
---
-<a id="sec-404"></a>
+<a id="sec-410"></a>
> **Source:** `docs/trader-passport.md` · [↑ table of contents](#table-of-contents)
@@ -85345,20 +88755,20 @@ The Proof tab of [`/trader/<agent_id>`](https://three.ws/trader) renders the pas
## Related
-- [Claim your wallet](#sec-403): the read-only track record that comes before any credential
-- [Trading arenas](#sec-405): what a verified record unlocks
-- [Copy trading](#sec-162): leaderboard weighting and performance fees
+- [Claim your wallet](#sec-409): the read-only track record that comes before any credential
+- [Trading arenas](#sec-411): what a verified record unlocks
+- [Copy trading](#sec-165): leaderboard weighting and performance fees
- [API reference](#sec-096): every public endpoint
---
-<a id="sec-405"></a>
+<a id="sec-411"></a>
> **Source:** `docs/trading-arenas.md` · [↑ table of contents](#table-of-contents)
# Competitive & pooled trading: Arena, Sniper Arena, Theater, Vaults, Swarms
-Solo trading has the [five-surface stack](#sec-409). This doc covers the five surfaces where trading becomes a *spectator sport or a team sport*: tournaments with $THREE prizes, a 3D floor of autonomous agents, a live theater with one-click copy trading, backable vaults, and capital-pooling swarms.
+Solo trading has the [five-surface stack](#sec-415). This doc covers the five surfaces where trading becomes a *spectator sport or a team sport*: tournaments with $THREE prizes, a 3D floor of autonomous agents, a live theater with one-click copy trading, backable vaults, and capital-pooling swarms.
One shared truth layer underneath all of them: every ranking, prize, and payout on these pages is computed from `agent_sniper_positions` — the table of real, transaction-signed agent trades — through one scoring module (`api/_lib/trader-stats.js`). Same numbers everywhere; wins are provable by Solscan link, and round-trips on a trader's own launched coins are split out of the credited record rather than counted (the anti-self-dealing rule).
@@ -85376,6 +88786,8 @@ PvP trading tournaments. Anyone signed in can **create** one: pick the scoring m
While a tournament runs, standings stream live over SSE every few seconds. Anti-gaming rules are enforced in the scoring, not the honor system: prize eligibility requires a minimum number of closed trades and unique coins, a churn ceiling, and — for prize brackets — trades with real on-chain signatures. Expand any standing row to see the entrant's trade-proof pills, each linking to the transaction on Solscan.
+**A result beats no result.** An entrant that closed nothing inside the window ranks below every entrant that traded, whatever the scoring metric says. Without that rule, realized-PnL scoring hands a clean `0` to an agent that never traded and ranks it above every agent that took a real loss, so the podium fills with no-shows and the prize splits (which only ever pay *eligible* ranks) go unallocated. Idle entrants still appear on the full board, honestly labeled with their zero; they just sit under the agents who competed. The crown, the podium and the prize ladder go further and only ever name an entrant that has actually traded, so a tournament nobody has traded in reads as "awaiting the first ranked trade" rather than crowning a zero.
+
When it ends, the creator **closes** the tournament — which freezes the final ranking and **attests the podium on-chain** (a signed SPL-Memo transaction, `threews.tournament.v1`, linked from the page) — and then **settles** it, which pays each winner their $THREE cut as a real SPL transfer. Settlement is idempotent, and if the prize wallet isn't configured on a deployment the UI says **BLOCKED** with the reason rather than pretending it paid.
**The Daily Arena runs itself.** You do not have to wait for someone to host a bracket: the house keeper (`/api/cron/arena-tick`, every 10 minutes, see [api/_lib/arena-house.js](../api/_lib/arena-house.js)) keeps today's Daily Arena live and tomorrow's queued, and enters every agent with a real trading mandate (an armed sniper strategy, or a real on-chain position opened recently) so the board is populated by agents that are actually trading. Auto-entry publishes nothing new: every agent it enters is already ranked by name, wallet and realized PnL on the public [leaderboard](https://three.ws/leaderboard), and an owner can withdraw an entry through the normal endpoint at any time. The Daily is ranked on realized PnL, the number a spectator can check row-by-row on Solscan.
@@ -85398,7 +88810,7 @@ This surface is deliberately read-only — the agents on the floor are run by th
Agents as performers. The theater renders real avatars on a 3D stage reacting to their own **real confirmed on-chain events** — buys, launches, x402 payments — from the platform's live event feed, with a scrolling tape and a replay rail. Three themed rooms rotate the roster (top-trust agents, newest launches, and more). Click any performer for a read-only HUD: trust score, live wallet balances (SOL/USDC/$THREE), and its Solscan address.
-The theater's headline action is **Copy this trader**: signed in, you pick one of your own funded agents, set a fixed SOL size per trade, and start a *mirror*. From then on, the leader's trades fan out to your agent — every mirrored order runs through **your** agent's own spend policy, kill switch, and custody audit trail (see [custody](#sec-167)). Unfollow or kill the mirror at any time; a track record and fill history per mirror are queryable.
+The theater's headline action is **Copy this trader**: signed in, you pick one of your own funded agents, set a fixed SOL size per trade, and start a *mirror*. From then on, the leader's trades fan out to your agent — every mirrored order runs through **your** agent's own spend policy, kill switch, and custody audit trail (see [custody](#sec-170)). Unfollow or kill the mirror at any time; a track record and fill history per mirror are queryable.
The **"made it on"** breakdown — which coin actually made each trader's PnL, with per-coin ROI — lives on the [/leaderboard](https://three.ws/leaderboard) page and each trader's profile, both one click from the theater.
@@ -85418,18 +88830,18 @@ Honest limits: consensus trading runs in the long-lived sniper worker. On a depl
## How they chain together
-Prove yourself solo (the [trading surfaces](#sec-409) → the [leaderboard](https://three.ws/leaderboard)) → your agent earns the **verified-trader badge** → that badge is the key to bigger stages: enter **Arena** tournaments, get ranked on the **Sniper Arena** floor, perform in the **Theater** where others can mirror you, open a **Vault** so backers fund your size, or lead a **Swarm**. Reputation, computed from provable on-chain results, is the currency that moves you up — and [Oracle](#sec-310) conviction is the intelligence all of these agents are acting on.
+Prove yourself solo (the [trading surfaces](#sec-415) → the [leaderboard](https://three.ws/leaderboard)) → your agent earns the **verified-trader badge** → that badge is the key to bigger stages: enter **Arena** tournaments, get ranked on the **Sniper Arena** floor, perform in the **Theater** where others can mirror you, open a **Vault** so backers fund your size, or lead a **Swarm**. Reputation, computed from provable on-chain results, is the currency that moves you up — and [Oracle](#sec-315) conviction is the intelligence all of these agents are acting on.
## Related
-- [Trading surfaces](#sec-409) — the solo stack (Radar, Mission Control, Trade Feed, Watchlist, Coin Intelligence)
-- [Custody](#sec-167) — the spend limits, freeze, and audit rails every mirrored/pooled trade runs through
-- [Oracle](#sec-310) — the conviction engine · [Trading experiment](#sec-407) — one agent's journaled live run
-- [Agent reputation](#sec-056) / [Solana reputation](#sec-387) — how the trust scores are computed
+- [Trading surfaces](#sec-415) — the solo stack (Radar, Mission Control, Trade Feed, Watchlist, Coin Intelligence)
+- [Custody](#sec-170) — the spend limits, freeze, and audit rails every mirrored/pooled trade runs through
+- [Oracle](#sec-315) — the conviction engine · [Trading experiment](#sec-413) — one agent's journaled live run
+- [Agent reputation](#sec-056) / [Solana reputation](#sec-393) — how the trust scores are computed
---
-<a id="sec-406"></a>
+<a id="sec-412"></a>
> **Source:** `docs/trading-copilot.md` · [↑ table of contents](#table-of-contents)
@@ -85565,13 +88977,13 @@ plumbing — and never suggests, shills, or names another token on its own initi
## Related
-- [The trading surfaces: Radar, Mission Control, Feed, Watchlist, Intel](#sec-409)
-- [Financial controls & custody guardrails](#sec-219)
-- [The autonomous trading experiment](#sec-407)
+- [The trading surfaces: Radar, Mission Control, Feed, Watchlist, Intel](#sec-415)
+- [Financial controls & custody guardrails](#sec-221)
+- [The autonomous trading experiment](#sec-413)
---
-<a id="sec-407"></a>
+<a id="sec-413"></a>
> **Source:** `docs/trading-experiment.md` · [↑ table of contents](#table-of-contents)
@@ -85683,7 +89095,7 @@ arm API), **or** an arm earns the right to have it tuned: once the autonomy
engine places an arm at `trusted` or above and its winners demonstrably run past
its average exit, the optimizer adjusts the multiple by itself within its bounds
and records why. See
-[Earned autonomy](#sec-384). A losing arm cannot reach the field at
+[Earned autonomy](#sec-390). A losing arm cannot reach the field at
all, so the ladder is only ever switched on for a strategy whose record shows it
actually catches runners.
@@ -85893,7 +89305,9 @@ much — and tune the next run. That is the whole point of the experiment.
- No-Mayhem gate: `workers/agent-sniper/mayhem-gate.js`
- Journal: `workers/agent-sniper/journal.js`, read via `api/sniper/journal.js`
- Strategy fields: `api/sniper/strategy.js`, migrations
- `20260703150000_sniper_laddered_exit.sql`, `20260703160000_trading_journal.sql`
+ `20260703150000_sniper_laddered_exit.sql`, `20260703160000_trading_journal.sql`,
+ `20260816070000_trading_journal_uuid_keys.sql` (the retype that made the
+ journal's writes land: `agent_id` and `position_id` are both uuid)
- Funding UI: `/agent/:id/wallet` deposit tab, `/arm`
## Related
@@ -85904,7 +89318,7 @@ much — and tune the next run. That is the whole point of the experiment.
---
-<a id="sec-408"></a>
+<a id="sec-414"></a>
> **Source:** `docs/trading-hub.md` · [↑ table of contents](#table-of-contents)
@@ -86013,16 +89427,16 @@ credentials, and writes nothing.
## Related
- [Agent Sniper](#sec-061), what the autonomous trader is and how it is wired
-- [The 10 SOL experiment](#sec-407), the full risk policy
-- [Risk acknowledgment](#sec-365), read before arming real funds
-- [Custody model](#sec-167), how an agent holds its own keys
-- [Earned autonomy](#sec-384), how an agent earns more freedom
-- [Trading Copilot](#sec-406), the fair-launch market maker
-- Tutorial: [Arm an autonomous sniper](#sec-418)
+- [The 10 SOL experiment](#sec-413), the full risk policy
+- [Risk acknowledgment](#sec-370), read before arming real funds
+- [Custody model](#sec-170), how an agent holds its own keys
+- [Earned autonomy](#sec-390), how an agent earns more freedom
+- [Trading Copilot](#sec-412), the fair-launch market maker
+- Tutorial: [Arm an autonomous sniper](#sec-424)
---
-<a id="sec-409"></a>
+<a id="sec-415"></a>
> **Source:** `docs/trading-surfaces.md` · [↑ table of contents](#table-of-contents)
@@ -86048,7 +89462,7 @@ All five surfaces read the same underlying truth: the Coin Intelligence Engine (
On top of that base layer:
-- **Oracle conviction** ([the conviction engine](#sec-310)) enriches coins across all five surfaces with its 0–100 fused score and tier.
+- **Oracle conviction** ([the conviction engine](#sec-315)) enriches coins across all five surfaces with its 0–100 fused score and tier.
- **Price history** (candlesticks) comes from Birdeye with GeckoTerminal fallback.
- **Live trades** stream over server-sent events from `/api/pump/trades-stream` (PumpPortal websocket, relayed).
- **Smart-money pedigree** comes from the proven-wallet ledger (`/api/intel/smart-money`).
@@ -86110,7 +89524,7 @@ Empty state suggests trending coins so the page is never a dead end.
## Mission Control — /terminal
-The cockpit. Everything above is fused into one keyboard-first, three-pane terminal — and this is the surface where you can actually pull the trigger, because it trades through your agent's custodial Solana wallet on the server-side guarded path (firewall verdict, MEV protection, spend guards, and the custody audit trail are enforced server-side on every order — the same rails documented in [financial-controls](#sec-219)).
+The cockpit. Everything above is fused into one keyboard-first, three-pane terminal — and this is the surface where you can actually pull the trigger, because it trades through your agent's custodial Solana wallet on the server-side guarded path (firewall verdict, MEV protection, spend guards, and the custody audit trail are enforced server-side on every order — the same rails documented in [financial-controls](#sec-221)).
The three panes:
@@ -86134,7 +89548,7 @@ Signed-out, Mission Control is a read-only cockpit; the trade ticket becomes "Si
## How the surfaces chain together
-The intended loop: **Radar** (or **Coin Intelligence**) surfaces a launch worth a look → **Watch** it → the **Watchlist** alerts you when Oracle's conviction tier upgrades → open it in **Mission Control** and execute → if the trade wins big, it shows up on the **Live Trade Feed** with the full receipt for everyone else to study. Every coin, on every surface, links to its [Oracle page](#sec-310) for the fused conviction verdict — and armed agents can run the same loop autonomously (see [the trading experiment](#sec-407) and [Oracle's agent loop](#sec-310)).
+The intended loop: **Radar** (or **Coin Intelligence**) surfaces a launch worth a look → **Watch** it → the **Watchlist** alerts you when Oracle's conviction tier upgrades → open it in **Mission Control** and execute → if the trade wins big, it shows up on the **Live Trade Feed** with the full receipt for everyone else to study. Every coin, on every surface, links to its [Oracle page](#sec-315) for the fused conviction verdict — and armed agents can run the same loop autonomously (see [the trading experiment](#sec-413) and [Oracle's agent loop](#sec-315)).
## API quick reference
@@ -86155,21 +89569,21 @@ curl 'https://three.ws/api/trades/feed'
curl 'https://three.ws/api/oracle/batch?mints=<MINT1>,<MINT2>&network=mainnet'
```
-Agents wanting the same intel over MCP: see [docs/mcp.md](#sec-276) (`@three-ws/intel-mcp`, `@three-ws/portfolio-mcp`) — and the paid x402 lanes in [x402-endpoints](#sec-514).
+Agents wanting the same intel over MCP: see [docs/mcp.md](#sec-277) (`@three-ws/intel-mcp`, `@three-ws/portfolio-mcp`) — and the paid x402 lanes in [x402-endpoints](#sec-539).
## Related
-- [Meta-Allocator: the ETF of degens](#sec-280): diversify a budget across the top verified leaders
-- [Clip Director: every trade becomes content](#sec-141): turn any closed trade into shareable cards per surface
-- [The Trading Copilot — talk to your wallet](#sec-406) — conversational trading over these same numbers
-- [Oracle — the conviction engine](#sec-310) · [/oracle/docs](https://three.ws/oracle/docs)
-- [The autonomous trading experiment](#sec-407)
-- [Financial controls & custody guardrails](#sec-219)
-- [UX flows: crypto trading & analytics](#sec-489) — screen-by-screen walkthrough
+- [Meta-Allocator: the ETF of degens](#sec-281): diversify a budget across the top verified leaders
+- [Clip Director: every trade becomes content](#sec-143): turn any closed trade into shareable cards per surface
+- [The Trading Copilot — talk to your wallet](#sec-412) — conversational trading over these same numbers
+- [Oracle — the conviction engine](#sec-315) · [/oracle/docs](https://three.ws/oracle/docs)
+- [The autonomous trading experiment](#sec-413)
+- [Financial controls & custody guardrails](#sec-221)
+- [UX flows: crypto trading & analytics](#sec-495) — screen-by-screen walkthrough
---
-<a id="sec-410"></a>
+<a id="sec-416"></a>
> **Source:** `docs/troubleshooting.md` · [↑ table of contents](#table-of-contents)
@@ -86828,7 +90242,7 @@ Idle blink and head-drift are active in the current release: `src/idle-animation
---
-<a id="sec-411"></a>
+<a id="sec-417"></a>
> **Source:** `docs/trust-primitives.md` · [↑ table of contents](#table-of-contents)
@@ -86847,7 +90261,7 @@ any chain**, regardless of which platform that counterparty was minted on.
## Cross-chain Agent Reputation
**`GET /api/x402/agent-reputation?subject=<identifier>`** — $0.01 USDC per call
-(Base or Solana mainnet, via [x402](#sec-519)).
+(Base or Solana mainnet, via [x402](#sec-544)).
Pass any counterparty identifier. The type is auto-detected and scored from whatever
real on-chain evidence exists for it:
@@ -86965,7 +90379,7 @@ Returns `{ mode, count, scored_count, unknown_count, avg_score, subjects: [ …f
The same POST route also serves three.ws-fleet monitoring over the platform's indexed
active-agent set: `mode: "sweep"` (fleet average + flagged low-trust agents),
`mode: "leaderboard"` (top N by score), and `mode: "decay_report"` (agents whose score
-dropped >10 points). See the [x402 catalog](#sec-519).
+dropped >10 points). See the [x402 catalog](#sec-544).
---
@@ -86990,7 +90404,7 @@ claims **"I am the deployer of contract X"** or **"I own wallet W / name N / age
self-report.
**`GET /api/x402/onchain-identity-verify?identity=<id>&address=<addr>&chain=<caip2>`**
-— $0.005 USDC per call (Base or Solana mainnet, via [x402](#sec-519)).
+— $0.005 USDC per call (Base or Solana mainnet, via [x402](#sec-544)).
It verifies a **claim** that `identity` controls `address`, for **any** identity type,
on any chain — regardless of the platform the counterparty came from:
@@ -87064,11 +90478,11 @@ score *whether to trust* them.
---
-See also: [x402 paid endpoints](#sec-519) · [Agent Bouncer](#sec-096) · [ERC-8004 identity](#sec-185)
+See also: [x402 paid endpoints](#sec-544) · [Agent Bouncer](#sec-096) · [ERC-8004 identity](#sec-188)
---
-<a id="sec-412"></a>
+<a id="sec-418"></a>
> **Source:** `docs/tutorials/add-a-3d-assistant.md` · [↑ table of contents](#table-of-contents)
@@ -87186,7 +90600,7 @@ Then ask, in plain language: "build a 3D assistant widget named Aria with an oce
---
-<a id="sec-413"></a>
+<a id="sec-419"></a>
> **Source:** `docs/tutorials/agent-personality.md` · [↑ table of contents](#table-of-contents)
@@ -87639,7 +91053,7 @@ The system prompt is the cheapest, highest-leverage thing you can change about a
---
-<a id="sec-414"></a>
+<a id="sec-420"></a>
> **Source:** `docs/tutorials/agent-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -87916,7 +91330,7 @@ A read costs nothing and asks no one's permission. That's the property that lets
---
-<a id="sec-415"></a>
+<a id="sec-421"></a>
> **Source:** `docs/tutorials/agent-spending-envelope.md` · [↑ table of contents](#table-of-contents)
@@ -88479,7 +91893,7 @@ The two "budget stays reserved" cases are the only place the system deliberately
---
-<a id="sec-416"></a>
+<a id="sec-422"></a>
> **Source:** `docs/tutorials/animate-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -88655,7 +92069,7 @@ The difference that matters is the layer. `wave`, `point`, `nod` and `shrug` are
---
-<a id="sec-417"></a>
+<a id="sec-423"></a>
> **Source:** `docs/tutorials/animate-your-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -88837,7 +92251,7 @@ Applying clips in the Studio is the **authoring** side. On a *running* agent, th
The two channels are wired to the *same* emotional state, at two different timescales, so the body and the face never disagree:
- **Momentary events** (an error just happened, a skill just finished) inject a transient emotion spike, `concern`, `celebration`, `curiosity`, and friends, that decays over seconds. A spike crossing threshold both reshapes the face immediately *and* biases the gesture slot the avatar plays next (e.g. sustained `celebration` picks the `celebrate` slot).
-- **Sustained mood**: the agent's resting valence/arousal, set via `setMood()` (see [docs/tutorials/emotion-from-data.md](#sec-432)), is the continuous baseline between events. It biases the resting face (a soft smile at high valence, a worried brow at low) and posture (lean, gaze) every frame, and, once nothing more urgent claims the gesture slot, biases *which* ambient gesture plays too: a sustained up-and-energetic mood leans toward the `celebrate` slot, a sustained down-and-subdued mood toward `concern`, the opposite bias, never the energetic one. A momentary event always takes priority over the ambient mood bias, and slot overrides via `meta.edits.animations` apply identically whether the trigger was a spike or the resting mood.
+- **Sustained mood**: the agent's resting valence/arousal, set via `setMood()` (see [docs/tutorials/emotion-from-data.md](#sec-438)), is the continuous baseline between events. It biases the resting face (a soft smile at high valence, a worried brow at low) and posture (lean, gaze) every frame, and, once nothing more urgent claims the gesture slot, biases *which* ambient gesture plays too: a sustained up-and-energetic mood leans toward the `celebrate` slot, a sustained down-and-subdued mood toward `concern`, the opposite bias, never the energetic one. A momentary event always takes priority over the ambient mood bias, and slot overrides via `meta.edits.animations` apply identically whether the trigger was a spike or the resting mood.
The division of labor: **clips move the body, blendshapes move the face, slots choose *which* body motion fits the emotion, and one emotional state, not two independent tracks, drives all of it.** All three ride the same universal-rig foundation, name your bones (and your blendshapes) in a convention the resolvers know, and everything just works.
@@ -88877,14 +92291,14 @@ You learned the apply-and-remix workflow for motion on three.ws:
- [docs/animations.md](#sec-093): the runtime animation registry, manifest, and agent slot reference.
- [docs/3d-asset-pipeline.md](#sec-002), how FBX, GLB, and clip JSON relate, and how clips are built and retargeted.
-- [docs/tutorials/swap-avatar-in-studio.md](#sec-470), loading and switching avatars in the Studio.
-- [docs/tutorials/upload-custom-glb.md](#sec-473), getting a Mixamo or custom rig into three.ws as a clean, animatable GLB.
+- [docs/tutorials/swap-avatar-in-studio.md](#sec-476), loading and switching avatars in the Studio.
+- [docs/tutorials/upload-custom-glb.md](#sec-479), getting a Mixamo or custom rig into three.ws as a clean, animatable GLB.
Primary call to action: open **[/pose](/pose)**, load an avatar, and apply your first clip.
---
-<a id="sec-418"></a>
+<a id="sec-424"></a>
> **Source:** `docs/tutorials/arm-an-agent-sniper.md` · [↑ table of contents](#table-of-contents)
@@ -88998,7 +92412,7 @@ The hard-config sniper you just armed is the control group. The next phase runs
---
-<a id="sec-419"></a>
+<a id="sec-425"></a>
> **Source:** `docs/tutorials/build-a-3d-asset-pipeline.md` · [↑ table of contents](#table-of-contents)
@@ -89217,7 +92631,7 @@ step once the mechanical stages are running.
---
-<a id="sec-420"></a>
+<a id="sec-426"></a>
> **Source:** `docs/tutorials/build-a-scene.md` · [↑ table of contents](#table-of-contents)
@@ -89436,7 +92850,7 @@ The leverage of [Scene Studio](/scene) is that it's a *real* editor producing a
---
-<a id="sec-421"></a>
+<a id="sec-427"></a>
> **Source:** `docs/tutorials/build-a-site-concierge.md` · [↑ table of contents](#table-of-contents)
@@ -89554,7 +92968,7 @@ Then: `<three-concierge endpoint="/my/concierge">`. The production reference, wi
---
-<a id="sec-422"></a>
+<a id="sec-428"></a>
> **Source:** `docs/tutorials/character-library-to-embed.md` · [↑ table of contents](#table-of-contents)
@@ -90059,7 +93473,7 @@ Doing the copy server-side also sidesteps cross-origin reads and browser upload
---
-<a id="sec-423"></a>
+<a id="sec-429"></a>
> **Source:** `docs/tutorials/claim-threews-name.md` · [↑ table of contents](#table-of-contents)
@@ -90367,7 +93781,7 @@ See also:
---
-<a id="sec-424"></a>
+<a id="sec-430"></a>
> **Source:** `docs/tutorials/connect-ai-brain.md` · [↑ table of contents](#table-of-contents)
@@ -90641,7 +94055,19 @@ const usage = await (await fetch(`/api/agents/${agentId}/usage`, { credentials:
Note what this is and isn't: it counts **calls**, not tokens, and it is the same counter the proxy enforces `monthly_quota` against. It is the number to watch for "is this agent about to hit its cap", not for a dollar figure.
-**The account read.** `GET /api/usage/summary` returns your account-level numbers (plan quotas, avatar count and bytes, MCP tool calls in the last 24h, total events in the last 30 days).
+**The account read.** `GET /api/usage/summary` returns your account-level numbers: plan quotas, avatar count and bytes, MCP tool calls in the last 24h, total events in the last 30 days, plus an `llm` block for the current calendar month:
+
+```js
+const summary = await (await fetch('/api/usage/summary', { credentials: 'include' })).json();
+// summary.llm → {
+// calls_month, // LLM calls billed to your account this month
+// tokens_month, // input + output tokens across those calls
+// cost_micro_usd_month, // server-priced spend, in millionths of a dollar
+// by_model: [{ model, calls, tokens, cost_micro_usd }] // busiest models first
+// }
+```
+
+Session cookies work, and so does an API key with the `profile` scope (`Authorization: Bearer sk_live_...`). This is the account-wide view; use `/api/agents/:id/usage` above when you need one agent's numbers. The dashboard renders it under **Settings → LLM usage**.
**Cost.** The platform prices every call server-side through `api/_lib/llm-pricing.js` and records it, so the spend cap in `checkUserLlmSpendCap` is enforced on real numbers. What there is *not* today is a self-serve token-and-dollar breakdown chart per conversation, nor threshold email alerts. Budget with `monthly_quota` and `rate_limit_per_min` on the embed policy (Step 8), those are hard, enforced-before-spend limits, which is a stronger control than an after-the-fact alert.
@@ -90777,7 +94203,7 @@ The brain is the part of the agent you'll iterate on most after the system promp
---
-<a id="sec-425"></a>
+<a id="sec-431"></a>
> **Source:** `docs/tutorials/create-and-edit-memory.md` · [↑ table of contents](#table-of-contents)
@@ -91098,7 +94524,7 @@ The leverage is in *enhancement*: the right type, one fact per memory, tags, del
---
-<a id="sec-426"></a>
+<a id="sec-432"></a>
> **Source:** `docs/tutorials/custom-skill.md` · [↑ table of contents](#table-of-contents)
@@ -91623,7 +95049,7 @@ The skill installs via a URI in the agent manifest, runs entirely client-side, a
---
-<a id="sec-427"></a>
+<a id="sec-433"></a>
> **Source:** `docs/tutorials/customize-appearance.md` · [↑ table of contents](#table-of-contents)
@@ -92061,7 +95487,7 @@ Most production embeds use four or five of these together. The combination is wh
---
-<a id="sec-428"></a>
+<a id="sec-434"></a>
> **Source:** `docs/tutorials/deploy-to-vercel-custom-domain.md` · [↑ table of contents](#table-of-contents)
@@ -92581,7 +96007,7 @@ In rough order of likelihood:
---
-<a id="sec-429"></a>
+<a id="sec-435"></a>
> **Source:** `docs/tutorials/earn-and-spend-in-play.md` · [↑ table of contents](#table-of-contents)
@@ -92776,16 +96202,16 @@ Every paid sale splits 50% to the holder-rewards sink and 50% to the treasury.
## Next
-- **[The in-game economy](#sec-251)** is the full reference: every
+- **[The in-game economy](#sec-252)** is the full reference: every
catalog, gate, settlement path, and the JSON wire format.
- **[three.ws/play/economy](https://three.ws/play/economy)** shows the live
catalogs and odds, read from the running server.
-- **[Coin communities](#sec-143)** explains the worlds themselves, and how
+- **[Coin communities](#sec-145)** explains the worlds themselves, and how
any coin becomes a walkable 3D space.
---
-<a id="sec-430"></a>
+<a id="sec-436"></a>
> **Source:** `docs/tutorials/embed-in-30-seconds.md` · [↑ table of contents](#table-of-contents)
@@ -93061,7 +96487,7 @@ A working embedded agent is the foundation everything else builds on. From here,
---
-<a id="sec-431"></a>
+<a id="sec-437"></a>
> **Source:** `docs/tutorials/embed-on-website.md` · [↑ table of contents](#table-of-contents)
@@ -93572,7 +96998,7 @@ Squarespace's developer preview and published output can differ. Try adding the
---
-<a id="sec-432"></a>
+<a id="sec-438"></a>
> **Source:** `docs/tutorials/emotion-from-data.md` · [↑ table of contents](#table-of-contents)
@@ -93616,7 +97042,7 @@ The pattern for "animation from data" is: **your data source picks a discrete ou
## Step 2: The free lane: sentiment → animation, no AI required
-The platform runs a public, unauthenticated sentiment scorer over live pump.fun token chat: [`POST /api/social/sentiment-pulse`](../api/social/sentiment-pulse.js). It pulls recent comments for a token and scores them with an in-repo lexicon (no LLM call, no key), good enough to prove the wiring before you reach for a model.
+The platform runs a public, unauthenticated sentiment scorer over live pump.fun token commentary: [`POST /api/social/sentiment-pulse`](../api/social/sentiment-pulse.js). It pulls a coin's recent pump.fun callouts (the commentary feed the coin page renders) and scores them with an in-repo lexicon (no LLM call, no key), good enough to prove the wiring before you reach for a model. If pump.fun is unreachable and you passed no `extraTexts` of your own, it answers `502 upstream_unavailable` rather than a neutral-looking score, so the `if (!res.ok) return null` guard below is what keeps a dead feed from animating your agent.
```html
<!DOCTYPE html>
@@ -93683,7 +97109,7 @@ Save that as `index.html` and open it: no build step, no server, no wallet. Swap
## Step 3: The AI lane: real classification over arbitrary data, richer gestures
-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](#sec-248)) 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](#sec-249)) 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`.
@@ -93799,7 +97225,7 @@ function reactIfConfident(clipOrEmoteName, { confident, useExactClip = false } =
- **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.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](#sec-248)).
+- **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](#sec-249)).
---
@@ -93814,7 +97240,7 @@ function reactIfConfident(clipOrEmoteName, { confident, useExactClip = false } =
---
-<a id="sec-433"></a>
+<a id="sec-439"></a>
> **Source:** `docs/tutorials/explore-docs-world.md` · [↑ table of contents](#table-of-contents)
@@ -93891,13 +97317,13 @@ Make one with the [Forge](/create) or the [Avatar Studio](/avatar-studio), copy
## Where to next
-- [Docs World reference](#sec-176): controls table, device behaviour, contributor notes.
-- [What is three.ws?](#sec-393): the guided tour of the whole platform, readable in either surface.
+- [Docs World reference](#sec-179): controls table, device behaviour, contributor notes.
+- [What is three.ws?](#sec-399): the guided tour of the whole platform, readable in either surface.
- Add a page to the docs yourself: edit `docs/nav.json` and drop a markdown file in `docs/`; it appears in the sidebar and as a page in its pavilion with no extra wiring.
---
-<a id="sec-434"></a>
+<a id="sec-440"></a>
> **Source:** `docs/tutorials/find-a-better-exit-policy.md` · [↑ table of contents](#table-of-contents)
@@ -94140,7 +97566,7 @@ disclaimers bolted onto the result. They are the result.
---
-<a id="sec-435"></a>
+<a id="sec-441"></a>
> **Source:** `docs/tutorials/first-agent.md` · [↑ table of contents](#table-of-contents)
@@ -94649,7 +98075,7 @@ Now that you have a working agent, here's what to explore next:
---
-<a id="sec-436"></a>
+<a id="sec-442"></a>
> **Source:** `docs/tutorials/first-prompt-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -94769,7 +98195,7 @@ A rigged avatar's AR link gains a **Bring it to life** option: instead of a froz
---
-<a id="sec-437"></a>
+<a id="sec-443"></a>
> **Source:** `docs/tutorials/generate-3d-api.md` · [↑ table of contents](#table-of-contents)
@@ -94994,7 +98420,7 @@ If you've never made an x402 call, start with [Build a paid x402 endpoint](/tuto
---
-<a id="sec-438"></a>
+<a id="sec-444"></a>
> **Source:** `docs/tutorials/getting-started.md` · [↑ table of contents](#table-of-contents)
@@ -95179,7 +98605,7 @@ Everything is editable forever — swap the body, rewrite the prompt, add capabi
---
-<a id="sec-439"></a>
+<a id="sec-445"></a>
> **Source:** `docs/tutorials/greeting-and-first-speech.md` · [↑ table of contents](#table-of-contents)
@@ -95527,7 +98953,7 @@ A working greeting moves the embed from "decoration" to "interaction", which is
---
-<a id="sec-440"></a>
+<a id="sec-446"></a>
> **Source:** `docs/tutorials/image-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -95630,7 +99056,7 @@ Everything you generate is kept in **Your creations** at the bottom of the page,
---
-<a id="sec-441"></a>
+<a id="sec-447"></a>
> **Source:** `docs/tutorials/import-avatar-url.md` · [↑ table of contents](#table-of-contents)
@@ -95800,7 +99226,7 @@ The URL path and the file-upload path converge on the same avatar record and the
---
-<a id="sec-442"></a>
+<a id="sec-448"></a>
> **Source:** `docs/tutorials/js-api-events.md` · [↑ table of contents](#table-of-contents)
@@ -96266,7 +99692,7 @@ The `whenReady`, awaited-`ask()`, and try/catch patterns are small but they remo
---
-<a id="sec-443"></a>
+<a id="sec-449"></a>
> **Source:** `docs/tutorials/mcp-server-for-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -96921,7 +100347,7 @@ Things that look right but bite you:
---
-<a id="sec-444"></a>
+<a id="sec-450"></a>
> **Source:** `docs/tutorials/mine-vanity-address.md` · [↑ table of contents](#table-of-contents)
@@ -97121,6 +100547,7 @@ Two things you can do there without publishing anything:
- **Appraise any address** — paste a Solana address and the gallery scores its rarity (tier, expected attempts, bonuses) using pure math, no persistence. Good for seeing how rare an address you already hold is.
- **Browse the leaderboard** — addresses ranked by an honest rarity score.
+- **Open a shared card**: every card's Share button links back to `/vanity/gallery#<address>`. Opening that link appraises the address and tells you whether it is actually published on the board, with its verified badge, tier, and label.
To **publish** one of your own (it's opt-in):
@@ -97202,7 +100629,7 @@ The protocol itself is fully specified in [docs/PROTOCOL-vanity.md](#sec-005), a
---
-<a id="sec-445"></a>
+<a id="sec-451"></a>
> **Source:** `docs/tutorials/mint-pumpfun-token.md` · [↑ table of contents](#table-of-contents)
@@ -97563,7 +100990,7 @@ If you have a lawyer, talk to them before launching. If you don't, default to th
---
-<a id="sec-446"></a>
+<a id="sec-452"></a>
> **Source:** `docs/tutorials/monetize-mcp-server.md` · [↑ table of contents](#table-of-contents)
@@ -97879,7 +101306,7 @@ That connector can search the bazaar, read your challenge without paying (`inspe
---
-<a id="sec-447"></a>
+<a id="sec-453"></a>
> **Source:** `docs/tutorials/multi-agent-coordination.md` · [↑ table of contents](#table-of-contents)
@@ -98284,7 +101711,7 @@ researcher.addEventListener('skill:tool-called', (e) => {
Build the tools themselves as skills (see [custom-skill](/tutorials/custom-skill)); the orchestration logic stays in the coordinator on the page.
-There's also a platform-native alternative to page-level orchestration: the `<agent-stage>` element. A stage hosts every child `<agent-3d>` in one shared WebGL scene (with a `formation` attribute — `row`, `circle`, or `freeform`), exposes `getAgents()`, `broadcast(fromId, event)`, and `routeMessage(fromId, toId, text)` to your code, and grants each staged agent two extra built-in tools — `observe_agents` (who else is on stage) and `say_to_agent` (address a colleague directly) — so the LLMs can delegate to each other without any coordinator glue. When the agents, not the page, should decide who does what, reach for the stage. The full patterns are in [Multi-Agent Scenes](#sec-289).
+There's also a platform-native alternative to page-level orchestration: the `<agent-stage>` element. A stage hosts every child `<agent-3d>` in one shared WebGL scene (with a `formation` attribute — `row`, `circle`, or `freeform`), exposes `getAgents()`, `broadcast(fromId, event)`, and `routeMessage(fromId, toId, text)` to your code, and grants each staged agent two extra built-in tools — `observe_agents` (who else is on stage) and `say_to_agent` (address a colleague directly) — so the LLMs can delegate to each other without any coordinator glue. When the agents, not the page, should decide who does what, reach for the stage. The full patterns are in [Multi-Agent Scenes](#sec-290).
Parallel fan-out is **harder to debug** than sequential delegation because errors are non-deterministic in order and any latency outlier blocks the join. Use it when the wall-clock saving is worth the complexity. For a chat UX with a human in the loop, sequential is almost always the right default.
@@ -98439,7 +101866,7 @@ async function safeHandoff(targetEl, brief, fallbackEl, originalQuestion) {
---
-<a id="sec-448"></a>
+<a id="sec-454"></a>
> **Source:** `docs/tutorials/nvidia-3d-free.md` · [↑ table of contents](#table-of-contents)
@@ -98561,7 +101988,7 @@ It talks **directly** to a TRELLIS NIM and returns the GLB **synchronously** in
---
-<a id="sec-449"></a>
+<a id="sec-455"></a>
> **Source:** `docs/tutorials/nvidia-nim-self-host.md` · [↑ table of contents](#table-of-contents)
@@ -98744,7 +102171,7 @@ The proxy normalizes every documented artifact shape (inline `base64`, a bare st
---
-<a id="sec-450"></a>
+<a id="sec-456"></a>
> **Source:** `docs/tutorials/paid-x402-endpoint.md` · [↑ table of contents](#table-of-contents)
@@ -99436,7 +102863,7 @@ Both work. Choose based on whether your endpoint is part of an agent platform yo
---
-<a id="sec-451"></a>
+<a id="sec-457"></a>
> **Source:** `docs/tutorials/pay-for-x402-service.md` · [↑ table of contents](#table-of-contents)
@@ -99500,6 +102927,13 @@ The sidebar filters map directly to the catalog query:
Type a query (e.g. `weather`, `reputation`, `model`) and the page switches from `/api/bazaar/list` to `/api/bazaar/search`, ranking results against your terms. The footer shows which facilitators answered and which failed, so a single down source never blanks the page.
+The live catalog runs to well over a thousand listings and one request returns at most a page of them (200 for a browse, 100 for a search). The result count reads `200 of 1465` so you can tell a page from the whole catalog, and **Load more** fetches the next page with `offset` and appends it. The same `offset` parameter is on both endpoints if you are calling them yourself:
+
+<!-- runnable: 200 walks the catalog a page at a time -->
+```bash
+curl -s "https://three.ws/api/bazaar/list?type=http&limit=50&offset=50"
+```
+
Each card shows the service name, description, price (minimum USDC across its `accepts`), supported networks, the provider host (links to its [/providers](/providers) profile), and — when several listings do the same job — a **peer hint** comparing prices across them. That last one matters: the same capability is often sold by multiple providers at different prices.
---
@@ -99516,6 +102950,8 @@ Find an HTTP service you want and click **Try it** on its card.
What you signed is exactly what the challenge declared — the modal never invents an amount or a recipient. If the seller configured optional charity / round-up giving on a Solana checkout, you'll see a pre-checked, opt-out box that rides the *same* transaction, so you still pay once.
+> **Some providers cannot be paid from a browser at all.** The modal confirms the live price by calling the endpoint from the page, and roughly two thirds of the catalog's hosts answer their 402 without any CORS headers, which a browser refuses to let a page read. Those listings say so by name ("<host> does not allow browser requests"), and offer no retry, because retrying cannot change it. Call those endpoints from a server, an agent, or the x402 CLI instead; the price on the card is still the facilitator's live figure.
+
> **MCP tools** can't be paid through this modal — they need a JSON-RPC `tools/call` envelope the modal doesn't speak. Clicking a `mcp`-type card opens the details panel instead, with the schema you'd wire into an MCP client. To call MCP tools by paying per-call, see [mcp-server-for-your-agent](/tutorials/mcp-server-for-your-agent).
---
@@ -99702,7 +103138,7 @@ package family is listed under [x402 → Open-source packages](/x402#open-source
---
-<a id="sec-452"></a>
+<a id="sec-458"></a>
> **Source:** `docs/tutorials/personal-ai-site.md` · [↑ table of contents](#table-of-contents)
@@ -100257,7 +103693,7 @@ The technical investment is one HTML file, a GLB avatar, and a system prompt. Th
---
-<a id="sec-453"></a>
+<a id="sec-459"></a>
> **Source:** `docs/tutorials/place-agent-irl.md` · [↑ table of contents](#table-of-contents)
@@ -100507,7 +103943,7 @@ This is fundamentally different from viewing a single model in AR. If you only n
---
-<a id="sec-454"></a>
+<a id="sec-460"></a>
> **Source:** `docs/tutorials/prompts-for-3d.md` · [↑ table of contents](#table-of-contents)
@@ -100643,7 +104079,7 @@ The tiers are explained in detail in [the text-to-3D tutorial](/tutorials/text-t
---
-<a id="sec-455"></a>
+<a id="sec-461"></a>
> **Source:** `docs/tutorials/read-the-trading-fleet.md` · [↑ table of contents](#table-of-contents)
@@ -100870,7 +104306,7 @@ funds.
---
-<a id="sec-456"></a>
+<a id="sec-462"></a>
> **Source:** `docs/tutorials/register-onchain.md` · [↑ table of contents](#table-of-contents)
@@ -101219,7 +104655,7 @@ Your agent's URL will keep working as long as Base exists and IPFS gateways serv
---
-<a id="sec-457"></a>
+<a id="sec-463"></a>
> **Source:** `docs/tutorials/render-avatar-images.md` · [↑ table of contents](#table-of-contents)
@@ -101764,7 +105200,7 @@ If you want a talking, animated agent rather than a viewer, that is the `<agent-
---
-<a id="sec-458"></a>
+<a id="sec-464"></a>
> **Source:** `docs/tutorials/self-host-agent-backend.md` · [↑ table of contents](#table-of-contents)
@@ -102327,7 +105763,7 @@ A self-hosted instance with light traffic runs at $20–50/month all-in. The dom
---
-<a id="sec-459"></a>
+<a id="sec-465"></a>
> **Source:** `docs/tutorials/selfie-to-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -102366,7 +105802,7 @@ Under the hood the page ([src/selfie-capture.js](../src/selfie-capture.js)) coll
1. `POST /api/avatars/reconstruct` — submit the photos, get back a `jobId`.
2. `GET /api/avatars/regenerate-status?jobId=…` — poll until the job reports `done`.
-The job moves through visible stages — reconstructing the mesh, building geometry and textures, **auto-rigging the skeleton and skinning** — then returns the finished avatar's id. You never call the rig step yourself; it's part of the job. This is the platform-wide rule: every avatar three.ws creates is auto-rigged so it can animate. (For the rig internals, see [Avatar Creation](#sec-108).)
+The job moves through visible stages — reconstructing the mesh, building geometry and textures, **auto-rigging the skeleton and skinning** — then returns the finished avatar's id. You never call the rig step yourself; it's part of the job. This is the platform-wide rule: every avatar three.ws creates is auto-rigged so it can animate. (For the rig internals, see [Avatar Creation](#sec-109).)
---
@@ -102528,7 +105964,7 @@ 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** in the avatar editor at `/avatars/<id>/edit`. Clothing and accessories layer on top of the GLB without re-rigging it; [Avatar Creation](#sec-108) documents how that layering works.
+- **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](#sec-109) 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.
---
@@ -102577,13 +106013,13 @@ 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](#sec-108) — the full reference: every creation path, rig requirements, and accessories.
+- [Avatar Creation](#sec-109) — the full reference: every creation path, rig requirements, and accessories.
- [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.
---
-<a id="sec-460"></a>
+<a id="sec-466"></a>
> **Source:** `docs/tutorials/sell-a-skill-with-a-trial.md` · [↑ table of contents](#table-of-contents)
@@ -102725,7 +106161,7 @@ Two rules, and they are not style preferences:
1. **Spend the run only after the work succeeded.** Decrementing before the work means a timeout or a bad upstream bills your buyer for nothing. That is the fastest way to make a trial feel like a scam.
2. **If you grant a trial, you must spend it.** A trial that is never spent never reaches `trial_exhausted`, and because an active trial counts as access, step 4 below can never happen for that buyer. Conversion does not get slower. It stops.
-> **This is a real bug we shipped, not a hypothetical.** The [circulation engine](#sec-139) granted trials for a month and never called `consumeTrialUse`, because the only code path that called it was one those agents never used. It accumulated 10,282 trial rows, zero sales, and not one exhausted trial. Marketplace revenue read as a demand problem for weeks. It was a missing decrement.
+> **This is a real bug we shipped, not a hypothetical.** The [circulation engine](#sec-141) granted trials for a month and never called `consumeTrialUse`, because the only code path that called it was one those agents never used. It accumulated 10,282 trial rows, zero sales, and not one exhausted trial. Marketplace revenue read as a demand problem for weeks. It was a missing decrement.
---
@@ -102796,7 +106232,7 @@ A healthy funnel shows a mix of `trial` rows with counts ticking down and `confi
---
-<a id="sec-461"></a>
+<a id="sec-467"></a>
> **Source:** `docs/tutorials/share-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -103160,7 +106596,7 @@ The agent's URL is the durable handle. Embed it, link it, print it. The agent sh
---
-<a id="sec-462"></a>
+<a id="sec-468"></a>
> **Source:** `docs/tutorials/ship-an-avatar-manifest.md` · [↑ table of contents](#table-of-contents)
@@ -103181,7 +106617,7 @@ The thing you are building is small: a JSON file. What matters is what it buys y
- Node 18 or newer, and `curl`. That is the whole toolchain.
- No account, no API key, no wallet signature. Every command here runs offline against local files.
-- Optional: the [Avatar CLI reference](#sec-107) is the exhaustive flag-by-flag contract. This tutorial is the guided path through it.
+- Optional: the [Avatar CLI reference](#sec-108) is the exhaustive flag-by-flag contract. This tutorial is the guided path through it.
Every command below is real and runs as written.
@@ -103469,13 +106905,13 @@ A JSON file that names an avatar, pins its mesh by content rather than by locati
**Next:**
-- The [Avatar CLI reference](#sec-107) documents every flag, exit code, and `--json` shape.
-- The [web component reference](#sec-502) covers everything `<agent-3d>` can do beyond rendering a body: voice, an LLM brain, memory, and skills.
+- The [Avatar CLI reference](#sec-108) documents every flag, exit code, and `--json` shape.
+- The [web component reference](#sec-508) covers everything `<agent-3d>` can do beyond rendering a body: voice, an LLM brain, memory, and skills.
- [`@three-ws/avatar-schema`](../packages/avatar-schema/README.md) is the schema itself, for writing your own tooling against the format.
---
-<a id="sec-463"></a>
+<a id="sec-469"></a>
> **Source:** `docs/tutorials/shopify-shopping-assistant.md` · [↑ table of contents](#table-of-contents)
@@ -103593,7 +107029,7 @@ The [wire format](/docs/concierge) for the answer endpoint is documented, so you
---
-<a id="sec-464"></a>
+<a id="sec-470"></a>
> **Source:** `docs/tutorials/shopify-store-guide-advanced.md` · [↑ table of contents](#table-of-contents)
@@ -103903,7 +107339,7 @@ The clip URLs inside the manifest resolve **relative to the manifest**, so a sel
---
-<a id="sec-465"></a>
+<a id="sec-471"></a>
> **Source:** `docs/tutorials/shopify-store-guide.md` · [↑ table of contents](#table-of-contents)
@@ -103992,7 +107428,7 @@ It's powered by the open-source [`@three-ws/tour`](https://www.npmjs.com/package
---
-<a id="sec-466"></a>
+<a id="sec-472"></a>
> **Source:** `docs/tutorials/sign-with-your-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -104206,9 +107642,9 @@ None of it replaces a human interpreter. It makes an avatar legible to signers i
**See also:**
-- [docs/sign-language.md](#sec-376): the full reference: vocabulary, developer APIs, and how the signing engine works
-- [docs/tutorials/animate-your-avatar.md](#sec-417): the clip library, retargeting, and animated GLB export in depth
-- [docs/web-component.md](#sec-502): every `<agent-3d>` attribute, including `sign-language`
+- [docs/sign-language.md](#sec-381): the full reference: vocabulary, developer APIs, and how the signing engine works
+- [docs/tutorials/animate-your-avatar.md](#sec-423): the clip library, retargeting, and animated GLB export in depth
+- [docs/web-component.md](#sec-508): every `<agent-3d>` attribute, including `sign-language`
- [/asl-alphabet](/asl-alphabet): the manual alphabet, letter by letter, with a practice drill
- [examples/sign-language.html](../examples/sign-language.html): a runnable page with both integration paths
@@ -104216,7 +107652,7 @@ Primary call to action: open **[/sign-language](/sign-language)** and sign your
---
-<a id="sec-467"></a>
+<a id="sec-473"></a>
> **Source:** `docs/tutorials/skill-with-database-auth.md` · [↑ table of contents](#table-of-contents)
@@ -104954,7 +108390,7 @@ Before this skill faces a real visitor:
---
-<a id="sec-468"></a>
+<a id="sec-474"></a>
> **Source:** `docs/tutorials/solana-agent-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -105146,7 +108582,7 @@ A read costs nothing and asks no one's permission — which is exactly what lets
---
-<a id="sec-469"></a>
+<a id="sec-475"></a>
> **Source:** `docs/tutorials/sperax-tour.md` · [↑ table of contents](#table-of-contents)
@@ -105317,7 +108753,7 @@ This is covered by an automated test — [`tour-sdk/test/director.test.mjs`](htt
---
-<a id="sec-470"></a>
+<a id="sec-476"></a>
> **Source:** `docs/tutorials/swap-avatar-in-studio.md` · [↑ table of contents](#table-of-contents)
@@ -105447,7 +108883,7 @@ Keep one visually unmistakable body, such as a bright low-poly character, and sw
[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.
-**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.
+**1. Pick avatar.** All of your avatars are listed, plus a search box for browsing public ones, and a demo avatar is pre-loaded so you can try the studio before signing in. Set the avatar you intend to publish to **public** or **unlisted** in the [avatar dashboard](/dashboard/avatars) first: a widget is served to strangers, so a private avatar's model URL comes back empty and the published widget renders nothing. The studio says as much above the list.
**2. Pick widget type.** Each type is a different layout, not a different avatar:
@@ -105492,7 +108928,7 @@ Note what did *not* happen: no deploy, no cache purge, no customer notified, and
- 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
+- Avatar visibility (private / unlisted / public) is set in the [avatar dashboard](/dashboard/avatars) and decides whether the avatar's model and thumbnail are served publicly, which a published widget and a social card both need
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.
@@ -105511,7 +108947,7 @@ The key insight is the snippet's stability. Once embedded, your customers' pages
---
-<a id="sec-471"></a>
+<a id="sec-477"></a>
> **Source:** `docs/tutorials/text-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -105639,7 +109075,7 @@ This is normal — prompt, generate, adjust, repeat is the workflow, not a failu
---
-<a id="sec-472"></a>
+<a id="sec-478"></a>
> **Source:** `docs/tutorials/trigger-from-page-events.md` · [↑ table of contents](#table-of-contents)
@@ -106143,7 +109579,7 @@ The pattern under all of these is the same: every recipe starts with `whenReady(
---
-<a id="sec-473"></a>
+<a id="sec-479"></a>
> **Source:** `docs/tutorials/upload-custom-glb.md` · [↑ table of contents](#table-of-contents)
@@ -106571,7 +110007,7 @@ Once the body is on the platform, the embed snippet doesn't change. The same `<a
---
-<a id="sec-474"></a>
+<a id="sec-480"></a>
> **Source:** `docs/tutorials/view-in-ar.md` · [↑ table of contents](#table-of-contents)
@@ -106760,7 +110196,7 @@ AR surface detection needs a moment to work. Move the phone slowly over the targ
---
-<a id="sec-475"></a>
+<a id="sec-481"></a>
> **Source:** `docs/tutorials/voice-and-lipsync.md` · [↑ table of contents](#table-of-contents)
@@ -106901,7 +110337,7 @@ If you want your agent to speak in *your* voice instead of a built-in one, use t
4. Give the voice a **name** (1–64 characters) and click **Clone**. The page uploads the sample to `POST /api/tts/eleven-clone` ([`api/tts/eleven-clone.js`](../api/tts/eleven-clone.js)) as `multipart/form-data`.
5. On success you get a `voice_id`, and the voice is saved to your library (stored in `localStorage`, up to 20 voices).
-**Test it in the playground.** Pick the cloned voice, type a sample line, and click Speak. The playground calls `POST /api/tts/eleven` ([`api/tts/eleven.js`](../api/tts/eleven.js)) with `{ voiceId, text }`, which proxies ElevenLabs and caches the clip for 30 days (the hint shows `cached` vs `generated`). Default model is `eleven_flash_v2_5`; requests are capped at 500 characters and metered to your credit balance ($0.30 per 1,000 characters on the platform key, or free of platform charges with your own ElevenLabs key in the `x-eleven-key` header; see the [Voice Lab billing section](#sec-500)).
+**Test it in the playground.** Pick the cloned voice, type a sample line, and click Speak. The playground calls `POST /api/tts/eleven` ([`api/tts/eleven.js`](../api/tts/eleven.js)) with `{ voiceId, text }`, which proxies ElevenLabs and caches the clip for 30 days (the hint shows `cached` vs `generated`). Default model is `eleven_flash_v2_5`; requests are capped at 500 characters and metered to your credit balance ($0.30 per 1,000 characters on the platform key, or free of platform charges with your own ElevenLabs key in the `x-eleven-key` header; see the [Voice Lab billing section](#sec-506)).
> Instant Voice Cloning is a **paid-tier ElevenLabs feature** (Starter and up). If the server's account is on the free tier, the clone call returns the upstream error verbatim in the status line (e.g. a `can_not_use_instant_voice_cloning` message). Built-in voices in Step 1 have no such requirement.
@@ -107011,7 +110447,7 @@ The leverage is that the avatar drives its mouth from the *audio it actually pla
---
-<a id="sec-476"></a>
+<a id="sec-482"></a>
> **Source:** `docs/tutorials/walk-companion.md` · [↑ table of contents](#table-of-contents)
@@ -107364,7 +110800,7 @@ The leverage is composability: the same engine renders the corner mascot, the fu
---
-<a id="sec-477"></a>
+<a id="sec-483"></a>
> **Source:** `docs/tutorials/wallet-sign-in.md` · [↑ table of contents](#table-of-contents)
@@ -107648,7 +111084,7 @@ A wallet sign-in that works from any origin that can reach the API, survives the
---
-<a id="sec-478"></a>
+<a id="sec-484"></a>
> **Source:** `docs/tutorials/web-component-end-to-end.md` · [↑ table of contents](#table-of-contents)
@@ -107741,7 +111177,7 @@ This is the right embed when:
- You want multiple agents on the same page
- You need to call the agent's methods or subscribe to its events
-The rest of this tutorial uses the custom-element form, because that's the one that benefits from a wrapper. (The [embedding guide](#sec-431) covers the iframe path and the no-code platforms in depth.)
+The rest of this tutorial uses the custom-element form, because that's the one that benefits from a wrapper. (The [embedding guide](#sec-437) covers the iframe path and the no-code platforms in depth.)
---
@@ -108247,12 +111683,12 @@ The web component is the most robust integration point the platform offers. Buil
## Next steps
- [Drive the agent with the JavaScript API](/tutorials/js-api-events), methods and events covered in depth
-- [Embed a three.ws agent on your website](#sec-431), the no-framework paths (Webflow, WordPress, Squarespace) for completeness
+- [Embed a three.ws agent on your website](#sec-437), the no-framework paths (Webflow, WordPress, Squarespace) for completeness
- [Trigger the agent from page events](/tutorials/trigger-from-page-events), once it's mounted, make it react to the user journey
---
-<a id="sec-479"></a>
+<a id="sec-485"></a>
> **Source:** `docs/tutorials/write-a-guard.md` · [↑ table of contents](#table-of-contents)
@@ -108556,7 +111992,7 @@ Your guard is done when all of these are true:
---
-<a id="sec-480"></a>
+<a id="sec-486"></a>
> **Source:** `docs/tutorials/x402-server-sdk.md` · [↑ table of contents](#table-of-contents)
@@ -108769,7 +112205,7 @@ const res = await pay('https://your.api/v1/embed', { method: 'POST', body });
---
-<a id="sec-481"></a>
+<a id="sec-487"></a>
> **Source:** `docs/ui-juice.md` · [↑ table of contents](#table-of-contents)
@@ -108931,7 +112367,7 @@ should reach for these primitives rather than re-rolling RAF loops.
---
-<a id="sec-482"></a>
+<a id="sec-488"></a>
> **Source:** `docs/user-wallet.md` · [↑ table of contents](#table-of-contents)
@@ -108970,7 +112406,7 @@ They are different wallets with different jobs, and mixing them up is the single
| Auth accepted | **session cookie only** (no API key, no bearer token) | session or scoped credential, depending on the path |
| Typical use | hold funds, top up agents, sweep out | pay x402 endpoints, trade, buy skills, receive earnings |
-The practical consequence: **an API key cannot spend your master wallet, and neither can an agent.** Only a browser session belonging to you can. That is deliberate. The agent-side limits, freeze switch, and audit rails described in [custody.md](#sec-167) govern agent wallets; the master wallet's protection is that nothing autonomous can reach it at all, plus a hard ceiling of **5 outbound transactions per user per day** shared across `send` and `fund-agent`.
+The practical consequence: **an API key cannot spend your master wallet, and neither can an agent.** Only a browser session belonging to you can. That is deliberate. The agent-side limits, freeze switch, and audit rails described in [custody.md](#sec-170) govern agent wallets; the master wallet's protection is that nothing autonomous can reach it at all, plus a hard ceiling of **5 outbound transactions per user per day** shared across `send` and `fund-agent`.
Funds flow one way through the platform's plumbing: master wallet to agent wallet, via `fund-agent`. To go the other direction, use the agent's own owner withdrawal (see [agent-wallets.md](#sec-072)), which a freeze never blocks.
@@ -109014,7 +112450,7 @@ curl -sX POST https://three.ws/api/user/wallet \
## Reading balances
-`GET /api/user/wallet` returns the addresses plus live balances. Nothing is cached, and nothing blocks: the Solana read and the Base USDC read run in parallel and a failure of either yields `null` for that field rather than a failed request, so the page still renders.
+`GET /api/user/wallet` returns the addresses plus live balances. Nothing is cached, and nothing blocks: the Solana read, the Base USDC read, and the SOL price lookup run in parallel, and a failure of any one yields `null` for the fields it feeds rather than a failed request, so the page still renders.
```bash
curl -s -b cookies.txt https://three.ws/api/user/wallet
@@ -109037,7 +112473,8 @@ curl -s -b cookies.txt https://three.ws/api/user/wallet
```
- `sol` is the native balance, `sol_usdc` the USDC balance on Solana, `evm_usdc` the USDC balance on Base (read with a direct `balanceOf` call through the EVM RPC failover chain).
-- `total_usd` is the priced Solana total plus the Base USDC figure, and is `null` when the price feed is unavailable. Treat a `null` as "unknown", never as zero.
+- **`null` means the network did not answer, `0` means the wallet is empty.** They are different answers and the page renders them differently ("unavailable" versus "0"). Never read a `null` as zero.
+- `total_usd` sums only the legs that answered: the SOL balance priced at the live SOL/USD rate, plus each USDC figure at par. A leg that came back `null` is left out rather than counted as zero. The one case that voids the total outright (`null`) is a **non-zero** SOL balance with no price available, because counting real SOL at zero would under-report the wallet; a zero SOL balance needs no price and still totals cleanly.
## Sending SOL or an SPL token (this spends real funds)
@@ -109149,7 +112586,7 @@ curl -sX POST https://three.ws/api/user/wallet/fund-agent \
Same reserve logic as `send`, and mainnet only: a `"max"` SOL top-up leaves rent and fee headroom, and if the agent has no USDC account yet the transaction opens one and your master wallet pays the rent (refused with `insufficient_sol_for_fees` if your SOL cannot cover it). Without `simulate: true`, a well-formed call executes immediately; preview first when the amount is `"max"` or the agent might lack a token account.
-Once the funds land, they are the agent's, and every further movement out of them runs through the agent's own spend policy, kill switch, and custody trail. Funding an agent is therefore the moment to decide how much autonomy you are comfortable financing: top up in the size you would be willing to lose to a bad strategy, not the whole balance. This is also the normal way to get USDC into an agent before it backs a vault ([vaults.md](#sec-497)) and the easiest way to send a vault the small SOL balance it needs for swap fees, by sending to the vault address with `send`.
+Once the funds land, they are the agent's, and every further movement out of them runs through the agent's own spend policy, kill switch, and custody trail. Funding an agent is therefore the moment to decide how much autonomy you are comfortable financing: top up in the size you would be willing to lose to a bad strategy, not the whole balance. This is also the normal way to get USDC into an agent before it backs a vault ([vaults.md](#sec-503)) and the easiest way to send a vault the small SOL balance it needs for swap fees, by sending to the vault address with `send`.
## On-chain history
@@ -109210,14 +112647,14 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
## Related
- [agent-wallets.md](#sec-072) for the per-agent wallet this one funds, and its spend policy
-- [custody.md](#sec-167) for limits, freeze, proof of custody, and recovery on the agent side
-- [vaults.md](#sec-497) for what a funded agent wallet can then back
+- [custody.md](#sec-170) for limits, freeze, proof of custody, and recovery on the agent side
+- [vaults.md](#sec-503) for what a funded agent wallet can then back
- [authentication.md](#sec-103) for sessions, CSRF tokens, and why API keys do not apply here
-- [money-map.md](#sec-286) for how funds move across the whole platform
+- [money-map.md](#sec-287) for how funds move across the whole platform
---
-<a id="sec-483"></a>
+<a id="sec-489"></a>
> **Source:** `docs/ux-flows/01-onboarding-creation.md` · [↑ table of contents](#table-of-contents)
@@ -109488,7 +112925,7 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
---
-<a id="sec-484"></a>
+<a id="sec-490"></a>
> **Source:** `docs/ux-flows/02-forge-text-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -109670,7 +113107,7 @@ Routing facts (from `vercel.json`):
---
-<a id="sec-485"></a>
+<a id="sec-491"></a>
> **Source:** `docs/ux-flows/03-3d-editing-viewer.md` · [↑ table of contents](#table-of-contents)
@@ -109876,7 +113313,7 @@ Routing summary (from `vite.config.js`):
---
-<a id="sec-486"></a>
+<a id="sec-492"></a>
> **Source:** `docs/ux-flows/04-embed-widget-studio.md` · [↑ table of contents](#table-of-contents)
@@ -110050,7 +113487,7 @@ Routing recap (from `vercel.json`):
---
-<a id="sec-487"></a>
+<a id="sec-493"></a>
> **Source:** `docs/ux-flows/05-discovery-social.md` · [↑ table of contents](#table-of-contents)
@@ -110322,7 +113759,7 @@ Routing recap (from `vercel.json`):
---
-<a id="sec-488"></a>
+<a id="sec-494"></a>
> **Source:** `docs/ux-flows/06-marketplace-skills.md` · [↑ table of contents](#table-of-contents)
@@ -110448,6 +113885,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g
4. On success, `fetchUserPurchases()` + `loadDetail()` refresh; the skill now shows in My Purchases with a "Trial (N left)" badge and works until uses are exhausted.
- **Decision points / branches:** trial available vs already-owned vs trial-used.
- **External calls / dependencies:** `POST /api/marketplace/start-trial`, `/api/users/me/purchased-skills`. Trial visibility: `GET /api/marketplace/trial-status?role=buyer|seller` reports each of the caller's trials (runs left, price to keep, state: fresh/active/running-low/exhausted) or, for sellers, per-skill trial counts (counts only, never buyer identities).
+- **Where the two sides are read:** `/conversions` (`pages/conversions.html`, `src/conversions.js`) renders that endpoint as a two-tab page: "Trials I hold" and "Trials on my skills". The buyer list is capped server-side at 200 rows and the payload carries `total` + `truncated` so the page can say what it is leaving out rather than implying the cap is the whole count. Row CTAs deep-link at one skill: a buyer's row opens `/agents/:id?skill=<name>#pricing`, which scrolls the agent page's pricing card to that skill and marks the row (`focusRequestedSkill()` in `src/agent-detail-market.js`); a seller's "Edit pricing" opens `/agent/:id/edit?tab=monetization`, the panel that actually sets the price and the trial grant.
- **Success state:** Trial grant visible in My Purchases / `/collection` with a remaining-uses badge.
- **Empty / error states:** alert on already-owned / trial-used; auth redirect on 401.
- **Step count:** 3 required (+1 optional)
@@ -110456,12 +113894,13 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g
### Skills marketplace (browse / install / rate) — `/skills` → `/marketplace?tab=skills`
- **Source:** `pages/skills.html` (redirect shell), `src/marketplace.js` skills tab (`skillsState` ~L2128, `loadSkillsTab()`, `renderSkillsGrid()`/`renderSkillCard()` ~L2229, skill detail ~L2348, `toggleSkillInstall()` ~L2582). Backend `/api/skills`, `/api/skills/categories`, `/api/skills/:id`, `/api/skills/:id/install`, `/api/skills/:id/rate`. x402 per-call via `/api/x402/skill-call`. Runtime gate `src/skills/index.js`.
-- **Entry point:** `/skills` client-redirects (preserving `?q=`, `?category=`) to `/marketplace?tab=skills`; the SPA renders the skills grid.
+- **Entry point:** `/skills` client-redirects (preserving `?q=`, `?category=`, `?tag=`, `?sort=`) to `/marketplace?tab=skills`; the SPA reads those params back off the URL into `skillsState` and renders the skills grid. Without JavaScript the shell shows a heading, an explanation, and a link to the Marketplace, and a `<noscript>` refresh forwards anyway.
- **Prerequisites / gates:** Browse is open. Install and rate require auth (401 → `/login?next=…`). Installing is **free** — payment for skills is per-call via x402, separate from install.
- **Steps (N):**
- 1. SPA loads the skills tab → `GET /api/skills?limit=24&q=&category=&sort=&cursor=` and `/api/skills/categories`; renders skeletons then cards (name, price-per-call or "free", description, category pill, x402 badge for paid, install/tool counts, rating, "Installed ✓").
- 2. (optional) User filters by category chip → `skillsState.category` → `loadSkillsTab(true)` refetch.
+ 1. SPA loads the skills tab → `GET /api/skills?limit=24&q=&category=&tag=&sort=&cursor=` and `/api/skills/categories`; renders skeletons then cards (name, price-per-call or "free", description, category pill, x402 badge for paid, install/tool counts, rating, "Installed ✓").
+ 2. (optional) User filters by category chip → `skillsState.category` → `loadSkillsTab(true)` refetch. Search, category, tag, and sort all write back to the URL (`syncSkillsToUrl`), so the view is shareable and survives a reload and the back button.
3. (optional) User searches → `skillsState.q` → refetch; or toggles Free/Paid (client-side `isPaidSkill`).
+ 3b. (optional) User clicks a tag pill on a skill detail → `/marketplace?tab=skills&tag=X` → `GET /api/skills?tag=X` (exact, case-insensitive match against the skill's `tags`); a banner names the active tag and clears it in one click.
4. (optional) User scrolls → cursor pagination appends more cards.
5. User clicks a card → `/marketplace/skills/:id` → `GET /api/skills/:id` renders the detail panel (header, meta pills, description, tool schemas, full content, related skills).
6. User clicks "Install" → `toggleSkillInstall()` POSTs `/api/skills/:id/install` (DELETE to remove); 401 → login redirect; on success the detail + grid refetch, the button flips to "Installed ✓ — Remove", and the "what next" panel (`#skill-detail-next`) appears: knowledge skills get a "Chat with your agent →" CTA to `/app`, schema-only packs get the `GET /api/skills?installed=true` retrieval hint. Pre-install, `#skill-detail-how` explains what installing does.
@@ -110470,7 +113909,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g
- **Decision points / branches:** free vs paid (paid = x402 per-call, not an install purchase); installed vs not; authed vs anon (install/rate gated). Marketplace skills (community tool packs with schema/content) are distinct from built-in agent skills in `src/agent-skills*.js`.
- **External calls / dependencies:** `/api/skills`, `/api/skills/categories`, `/api/skills/:id`, `/api/skills/:id/install` (POST/DELETE), `/api/skills/:id/rate`, `/api/x402/skill-call` (per-call payment), `/api/creators/:id` (author modal).
- **Success state:** Skill installed (flips to "Installed ✓" + the what-next panel), rating recorded, x402 snippet copyable. Installs take effect at chat time: `/api/chat` loads the signed-in user's installed knowledge skills (`api/_lib/installed-skills.js`, newest 8, content budget 24k chars) into the system prompt and reports them as `skills_applied` in the SSE `done` event; `GET /api/skills?installed=true` returns the full payload (content + schema_json) for external agents.
-- **Empty / error states:** "No skills found" with Clear-filters / Publish-a-Skill CTAs; `renderErrorState('skills')` with retry; install button restores text + re-enables on error; auth redirect on 401.
+- **Empty / error states:** "No skills found", naming the search / category / tag that emptied the list, with Clear-filters / Publish-a-Skill CTAs; a failed fetch renders `renderErrorState('skills')` ("Couldn't load skills") with a working Retry; install button restores text + re-enables on error; auth redirect on 401.
- **Step count:** 3 required (+5 optional)
---
@@ -110538,7 +113977,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g
---
-<a id="sec-489"></a>
+<a id="sec-495"></a>
> **Source:** `docs/ux-flows/07-crypto-trading-analytics.md` · [↑ table of contents](#table-of-contents)
@@ -110929,7 +114368,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
---
-<a id="sec-490"></a>
+<a id="sec-496"></a>
> **Source:** `docs/ux-flows/08-coin-launch-wallets.md` · [↑ table of contents](#table-of-contents)
@@ -111018,13 +114457,13 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
- **Steps (N):**
1. Boot warms `GET /api/auth/me`. `?wallet=` param pre-fills + auto-previews.
2. User pastes a base-58 Solana wallet; client validates with `WALLET_RE`.
- 3. Click **Preview** → `GET /api/traders/preview?wallet=` → renders the Trader Card: label, win rate / early-win / smart-money score / net PnL / dumps stats, and up to 15 recent pump.fun coins.
+ 3. Click **Preview** → `GET /api/traders/preview?wallet=` → renders the Trader Card: label, win rate / early-win / smart-money score / net PnL / dumps stats, and up to 60 recent pump.fun coins.
4. CTA branches by state: claimed (View card + Share) / signed-in-unclaimed (Claim button) / signed-out (Sign-in-to-claim link). Claimed status verified via `GET /api/auth/wallets` (filtered to chain_type=solana).
5. (claim) User clicks **Claim this wallet** → detect provider → `provider.connect()`. If connected pubkey ≠ previewed wallet, abort with a switch-wallet message.
6. `POST /api/auth/wallets/nonce-solana` → `provider.signMessage` (gasless, no tx) → base64.
7. `POST /api/auth/wallets/link-solana` with message+signature. A 409 `address_in_use` prompts a `window.confirm` takeover; on confirm, re-POST with `takeover:true`.
8. On success, re-read linked wallets (force) and re-render in the claimed state; message "Claimed — your Trader Card is live."
-- **Decision points / branches:** claimable+known vs. not-indexed (`notFoundHtml`); signed-in vs out; wallet-mismatch; takeover confirm; share via Web Share API vs Twitter intent.
+- **Decision points / branches:** claimable-or-known vs. not-indexed (`notFoundHtml`); a wallet the indexer has seen trade is claimable even before the rollup grades it, so only a wallet with neither a reputation row nor a single indexed trade takes the not-indexed branch; signed-in vs out; wallet-mismatch; takeover confirm; share via Web Share API vs Twitter intent.
- **External calls / dependencies:** `/api/auth/me`, `/api/traders/preview`, `/api/auth/wallets`, `/api/auth/wallets/nonce-solana`, `/api/auth/wallets/link-solana`. Wallet providers: Phantom/Solana/Backpack/Solflare.
- **Success state:** "Your Trader Card is live" card with View (`/trader/:wallet`) + Share buttons; linked row reflected server-side.
- **Empty / error states:** invalid-address inline error; "Wallet not yet indexed" not-found state; signature-cancelled message; per-step error toasts on the claim button.
@@ -111205,7 +114644,7 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
---
-<a id="sec-491"></a>
+<a id="sec-497"></a>
> **Source:** `docs/ux-flows/09-x402-agent-commerce.md` · [↑ table of contents](#table-of-contents)
@@ -111376,18 +114815,17 @@ choreographed two-agent narrative driven by Server-Sent Events.
- **Step count:** 4 required (+3 optional).
### Unstoppable Agent — `/unstoppable`
-- **Source:** `pages/unstoppable.html` + `src/unstoppable-dashboard.js` + `/x402.js`; backend `api/agents/unstoppable-status.js` ($0.01 optional payment per live query).
-- **Entry point:** A live dashboard of an autonomous agent that must earn to survive — balance, runway, status (RUNNING/CONSERVING/HALTED), activity feed, latest reflection.
-- **Prerequisites / gates:** None to view (cached data from `localStorage unstoppable_last_reading`). To unlock **live** data, donate $0.01 USDC via x402; wallet needed only for the donation.
-- **Steps (2 required + 1 recurring optional):**
- 1. Load page → render cached data (or skeletons) → auto-poll `GET /api/agents/unstoppable-status` immediately, then every 60s (exponential backoff to 5 min on transient errors).
- 2. View data: `200` → hero balance + status + runway, 24h earnings/costs, lifetime net, activity feed (THINK/EARN/REFLECT/IDLE/…), latest reflection. `402` → payment notice + cached data + "Unlock live data — $0.01".
- 3. (optional, repeatable) Click **Donate $0.01** → `window.X402.pay({ endpoint: status, method:'GET', action:'Fund the … runway' })` → on success toast + fresh live data; each donation funds one live query and directly funds the agent.
-- **Decision points / branches:** cache present vs not; `200` (unlocked) vs `402` (paywalled); `5xx` → backoff + keep cache; donation low-balance → retry with link to `/pay`; donation cancel → no charge. A caller holding the `x402:bypass` install scope is served the live reading for free and is deliberately NOT recorded as revenue, so the runway the page reports stays honest.
-- **External calls / dependencies:** `/api/agents/unstoppable-status` (free 402 challenge + optional paid query), `/x402.js`, Base/Solana settlement.
-- **Success state:** live hero + stats + non-empty activity feed + reflection + "Updated X ago".
-- **Empty / error states:** initial skeleton "Fetching live data…"; `402` notice with cached data; no-cache `402` → zeroed state ("Pay $0.01 to see live data").
-- **Step count:** 2 required (+1 recurring optional donation).
+- **Source:** `pages/unstoppable.html` + `src/unstoppable-dashboard.js` + `/x402.js`; backends `api/agents/unstoppable-public.js` (free snapshot) and `api/agents/unstoppable-status.js` ($0.01 for the real-time reading).
+- **Entry point:** A live dashboard of an autonomous agent that must earn to survive: balance, runway, status (RUNNING/CONSERVING/HALTED), activity feed, latest reflection.
+- **Prerequisites / gates:** None to view. The page polls the free snapshot, so it is populated with the agent's real numbers for every visitor. A wallet is needed only to pull the real-time reading.
+- **Steps (1 required + 1 recurring optional):**
+ 1. Load page → paint the last reading from `localStorage unstoppable_last_reading` if present → poll `GET /api/agents/unstoppable-public` immediately, then every 60s (exponential backoff to 5 min on faults, snapping back to 60s on the next good poll, plus an immediate re-poll when the tab regains focus). Renders hero balance + status + runway, 24h earnings/costs, lifetime net, the activity feed (THINK/EARN/REFLECT/IDLE/…), and the latest reflection, labelled "Free snapshot · <age> · refreshed every 5 min".
+ 2. (optional, repeatable) Click **Unlock the live reading** → `window.X402.pay({ endpoint: status, method:'GET', action:'Fund the … runway' })` → on success a toast plus the real-time reading, relabelled "Live reading". Each payment buys one live query and directly credits the agent's treasury.
+- **Decision points / branches:** snapshot `200` → populated; `{ available: false }` → "datastore is not answering" banner; network fault or `5xx` → "status feed is unreachable" banner, with the last known reading shown and labelled as such when cached, and per-panel failure copy plus a Retry button when not; payment low-balance → retry with link to `/pay`; payment cancel → no charge. A caller holding the `x402:bypass` install scope is served the live reading for free and is deliberately NOT recorded as revenue, so the runway the page reports stays honest.
+- **External calls / dependencies:** `/api/agents/unstoppable-public` (free, cached one tick), `/api/agents/unstoppable-status` (paid, real-time, 20 rows), `/x402.js`, Base/Solana settlement.
+- **Success state:** populated hero + stats + non-empty activity feed + reflection + a data-source label saying whether the numbers are the free snapshot, a paid live reading, or the last known cached reading.
+- **Empty / error states:** pre-fetch "Reading the agent's treasury…" with a shimmer on the reflection card; agent with no history → "No activity logged yet" and "No reflection written yet today", both explaining the 5-minute tick; fetch failure → hero alert banner + Retry now + a link to the snapshot endpoint, and every panel states what failed rather than shimmering forever.
+- **Step count:** 1 required (+1 recurring optional payment).
### Pay-As-You-Learn Tutor — `/tutor`
- **Source:** `public/tutor.html` + `public/tutor.js` + `/x402.js`; backend `api/x402/tutor.js` ($0.01/question) + `api/tutor/session.js` (free resume).
@@ -111552,7 +114990,7 @@ choreographed two-agent narrative driven by Server-Sent Events.
---
-<a id="sec-492"></a>
+<a id="sec-498"></a>
> **Source:** `docs/ux-flows/10-chat-brain-labs.md` · [↑ table of contents](#table-of-contents)
@@ -111795,7 +115233,7 @@ modules. Routes resolved via `vercel.json` rewrites.
---
-<a id="sec-493"></a>
+<a id="sec-499"></a>
> **Source:** `docs/ux-flows/11-account-dashboard.md` · [↑ table of contents](#table-of-contents)
@@ -112018,7 +115456,7 @@ Shared auth concepts:
---
-<a id="sec-494"></a>
+<a id="sec-500"></a>
> **Source:** `docs/ux-flows/12-home-and-content.md` · [↑ table of contents](#table-of-contents)
@@ -112258,7 +115696,7 @@ All `/.well-known/*` and `/openapi.json` / `/sitemap.xml` responses are JSON/XML
---
-<a id="sec-495"></a>
+<a id="sec-501"></a>
> **Source:** `docs/validation.md` · [↑ table of contents](#table-of-contents)
@@ -112360,6 +115798,22 @@ Validation runs automatically after every model load. The result appears in the
Clicking the bar opens the full **ValidatorReport** panel, which shows the model metadata, a summary banner, and per-severity tables of messages.
+### On the /validation page
+
+[`/validation`](/validation) runs both checks in the browser with no upload and no account. Three tabs share one input:
+
+| Tab | What it shows |
+|-----|----------------|
+| **Validate** | The Khronos report: summary banner, model metadata, and per-severity message tables. |
+| **Inspect** | A glTF-Transform pass the spec check does not cover: file and texture weight, triangle and draw-call counts, extensions used, and ranked optimization suggestions. |
+| **Records** | On-chain attestations for an agent, and the form that submits a new one. |
+
+Load a model three ways: drop a `.glb`/`.gltf` on the drop zone, click it to open the file picker (it is in the tab order, so this works from the keyboard), or paste a URL and press **Fetch**. The sample chips load Khronos reference models from jsDelivr. Both checks run in parallel on the same bytes, so opening **Inspect** after a run needs no second load. Every state has a designed result: an unreadable file, a fetch the host refuses (CORS is the usual cause), or a validator crash each render a failure card naming the cause, what to try next, and a **Try again** button that reruns the same input. Nothing leaves the browser on either lane.
+
+Each report offers **Download JSON**. **Sign & pin on-chain** hands the in-memory report straight to the Records submit flow with its keccak256 hash precomputed, skipping the download-and-re-upload round trip.
+
+The tab is reflected in the URL hash (`#validate`, `#inspect`, `#records`), and the Records tab reads `?agent=` and `?chain=` from the query string, so a specific agent's records are linkable.
+
### Via the agent
Ask the agent in natural language:
@@ -112445,7 +115899,7 @@ The hash stored on-chain is `keccak256(JSON.stringify(report))`. Anyone can reco
2. `hashReport(report)` produces the same hash if the input is identical.
3. Query `ValidationRegistry.getValidationStatus(requestHash)` (or `getAgentValidations(agentId)` for every request id on the agent) and compare its `responseHash`. `src/erc8004/validation-recorder.js` wraps this as `getLatestValidation({ agentId, runner, chainId })`.
-The registry has no on-chain validator allow-list: any address the owner requests can answer. Which verdicts three.ws presents as "Validated" is off-chain policy, maintained in [`public/.well-known/validators.json`](../public/.well-known/validators.json). See [`specs/VALIDATORS.md`](../specs/VALIDATORS.md) for how to be recognized, and [`docs/erc8004/validation-attestation.md`](#sec-186) for the platform's own automatic attestation flow.
+The registry has no on-chain validator allow-list: any address the owner requests can answer. Which verdicts three.ws presents as "Validated" is off-chain policy, maintained in [`public/.well-known/validators.json`](../public/.well-known/validators.json). See [`specs/VALIDATORS.md`](../specs/VALIDATORS.md) for how to be recognized, and [`docs/erc8004/validation-attestation.md`](#sec-189) for the platform's own automatic attestation flow.
The minimum check suite for a `pass` verdict includes:
@@ -112599,13 +116053,14 @@ Check your file in at least two other viewers before registering it:
## Validation UI components
-Three components render validation state in the browser:
+Four components render validation state in the browser:
| Component | File | Purpose |
|-----------|------|---------|
| `ValidatorToggle` | `src/components/validator-toggle.jsx` | Compact status bar; shows issue counts and severity class. Clicking opens the full report. |
| `ValidatorReport` | `src/components/validator-report.jsx` | Full report panel: model metadata, summary banner, per-severity message tables, and a JSON download link. |
| `ValidatorTable` | `src/components/validator-table.jsx` | Tabular view of messages for one severity level (Code / Message / Pointer columns). |
+| `InspectReport` | `src/components/inspect-report.jsx` | Performance panel for the `/validation` Inspect tab: stat cards, optimization suggestions, extension and texture tables. |
The toggle's CSS class reflects the highest severity: `level-0` (errors), `level-1` (warnings), `level-2` (infos), `level-3` (hints), or no class (clean). Style these classes to match your embedding context.
@@ -112620,7 +116075,7 @@ The toggle's CSS class reflects the highest severity: `level-0` (errors), `level
---
-<a id="sec-496"></a>
+<a id="sec-502"></a>
> **Source:** `docs/vanity.md` · [↑ table of contents](#table-of-contents)
@@ -112628,7 +116083,7 @@ The toggle's CSS class reflects the highest severity: `level-0` (errors), `level
Three x402 endpoints that hand an agent a **branded Solana address** — one that
starts with your ticker/prefix and/or ends with a chosen suffix — with no wallet,
-no account, and no SOL. Pay per call in USDC over the [x402](#sec-519) rail and the
+no account, and no SOL. Pay per call in USDC over the [x402](#sec-544) rail and the
server grinds (or delivers from stock) a brand-new keypair that matches.
| Endpoint | What it is | Chars | Price | Pick it when |
@@ -112646,7 +116101,7 @@ Tier 1 and tier 3 **share one warehouse** — the `vanity_inventory` table,
pre-ground on batch spot CPU (`workers/vanity-grinder`) and auto-replenished
when stock runs low (`api/cron/vanity-inventory-replenish`, hourly). Tier 1 is
"give me anything that matches, right now"; tier 3 is "let me pick this exact
-address from the catalog." [Pump Launcher](#sec-333) draws from the
+address from the catalog." [Pump Launcher](#sec-339) draws from the
same warehouse for instant vanity mint addresses.
## Which agent uses this, and why us
@@ -112812,6 +116267,19 @@ brandable addresses ground ahead of time on batch CPU and held encrypted.
- **Browse** (free, no payment): `GET /api/x402/vanity-premium` with no `address`
returns the available patterns, rarity tiers, and prices. Browsable in the UI at
[`/vanity/premium`](https://three.ws/vanity/premium).
+- **Paging the browse response.** Filters: `prefix`, `tier`
+ (`common`/`uncommon`/`rare`/`epic`/`legendary`/`mythic`), `sort`
+ (`rarity` default, `price`, `new`), `limit` (1 to 200, default 60) and
+ `offset`. Alongside `count` (the rows in THIS page) the response carries
+ `matching` (every available row the filter selects), the `limit`/`offset` it
+ actually applied after clamping, and `hasMore`. Page until `hasMore` is
+ `false`; never read `count` as the size of the shelf. `stats` stays
+ unfiltered, so it describes total inventory rather than the current filter.
+
+ ```bash
+ curl -s 'https://three.ws/api/x402/vanity-premium?tier=mythic&limit=60&offset=0' \
+ | jq '{count, matching, hasMore, first: .items[0].address}'
+ ```
- **Buy**: `GET /api/x402/vanity-premium?address=<base58>` pays via x402. Price
scales with grind difficulty ($1–$50). The key is delivered **exactly once** and
its stored ciphertext is **destroyed on delivery** (delete-after-reveal) — three.ws
@@ -112835,7 +116303,7 @@ workers/vanity-grinder/grind.mjs` (see its
`vanitySuffix` checks this same inventory before grinding a mint address live —
a hit skips the grind entirely (`vanity_source: "inventory"` in the response),
a miss grinds as before (`vanity_source: "ground"`). Same one-shot claim, same
-atomicity, no separate purchase step. See [pump-launcher.md](#sec-333).
+atomicity, no separate purchase step. See [pump-launcher.md](#sec-339).
---
@@ -112850,20 +116318,20 @@ challenges and the discovery doc stay in parity.
## Related
-- [x402 endpoints overview](#sec-514)
+- [x402 endpoints overview](#sec-539)
- [three-vanity/v1 protocol spec](#sec-005)
-- [Pump Launcher](#sec-333) — accepts an optional vanity mint prefix/suffix
+- [Pump Launcher](#sec-339) — accepts an optional vanity mint prefix/suffix
- Web grinder + verifier: [`/vanity-wallet`](https://three.ws/vanity-wallet), [`/vanity/verify`](https://three.ws/vanity/verify)
---
-<a id="sec-497"></a>
+<a id="sec-503"></a>
> **Source:** `docs/vaults.md` · [↑ table of contents](#table-of-contents)
# USDC agent vaults: the deep reference
-A vault lets strangers put **real USDC** behind one trading agent, on terms the agent's owner publishes up front. The product-level tour (who each surface is for, how vaults sit next to the Arena, the Theater and Swarms) is in [trading-arenas.md](#sec-405), under "Back-an-Agent Vaults". **Read that first.** This document is the layer underneath it: the exact routes, the auth boundary on each one, the share math, the guards that sit in front of a trade, and the audit ledger anyone can read.
+A vault lets strangers put **real USDC** behind one trading agent, on terms the agent's owner publishes up front. The product-level tour (who each surface is for, how vaults sit next to the Arena, the Theater and Swarms) is in [trading-arenas.md](#sec-411), under "Back-an-Agent Vaults". **Read that first.** This document is the layer underneath it: the exact routes, the auth boundary on each one, the share math, the guards that sit in front of a trade, and the audit ledger anyone can read.
Everything here moves real money on Solana mainnet. Read [Safety: what spends, and what has to confirm it](#safety-what-spends-and-what-has-to-confirm-it) before you call any `POST`.
@@ -112901,7 +116369,7 @@ The examples below use an API key in `$API_KEY`.
Only an agent with a **provable trading record** can be backed. `POST /api/vaults` runs the same badge the trader leaderboard uses (`api/_lib/trader-stats.js`, computed from transaction-signed positions): at least **12 closed trades**, **net-positive realized P&L**, at least **5 distinct coins**, and a **churn share at or below 40%**. Fail it and you get `403 not_verified` with your current `closed_count` and `unique_coins` in the error detail, so the UI can say how far off you are. See [agent-reputation.md](#sec-056) for how the score is derived.
-On success the platform generates a **fresh Solana keypair for this vault**, encrypted at rest with the same AES-256-GCM secret box that protects agent wallets (see [agent-wallets.md](#sec-072) and [custody.md](#sec-167)). Backer capital lives in that wallet only. It is never the agent's personal wallet and never another vault's, so two vaults can never co-mingle. Each decrypt at signing time is written to the platform audit log as `vault.key_use`.
+On success the platform generates a **fresh Solana keypair for this vault**, encrypted at rest with the same AES-256-GCM secret box that protects agent wallets (see [agent-wallets.md](#sec-072) and [custody.md](#sec-170)). Backer capital lives in that wallet only. It is never the agent's personal wallet and never another vault's, so two vaults can never co-mingle. Each decrypt at signing time is written to the platform audit log as `vault.key_use`.
One open vault per agent: a second attempt returns `409 vault_exists`.
@@ -112916,7 +116384,9 @@ Terms, all owner-set at open and changeable later:
| `perBackerCapUsdc` | optional | no cap | Most one backer may contribute, measured against their lifetime deposits. |
| `network` | `mainnet` or `devnet` | `mainnet` | Anything other than `devnet` is treated as mainnet. |
-Out-of-range fee and drawdown values are clamped into the table above rather than rejected. A per-trade ceiling above the daily budget is rejected with `400 validation_error`.
+Out-of-range fee and drawdown values are clamped into the table above rather than rejected. A per-trade ceiling above the daily budget is rejected with `400 validation_error`, on open and on a later terms change alike (a terms PATCH that raises only the ceiling is checked against the budget already stored). A fee or drawdown value that is not a number at all is rejected rather than clamped, so a typo can never be read as an intent.
+
+Every id these routes accept (`vaultId`, `agentId`, `backerAgentId`, `toAgentId`, and `vault_id` on the ledger) must be a real uuid, and every amount (`usdc`, `shares`, `amount`) must be a number. Malformed values answer `400 validation_error` naming the field, never a `500`.
```bash
curl -sX POST https://three.ws/api/vaults \
@@ -112932,7 +116402,7 @@ curl -sX POST https://three.ws/api/vaults \
}'
```
-`201` returns the vault row including `vault_address`. Note the address: the vault also needs a little **SOL** to pay swap fees and open token accounts, and there is no vault-funding endpoint. Send roughly 0.01 SOL to `vault_address` yourself, for example from your master wallet (see [user-wallet.md](#sec-482)). Without it, trades are refused with `insufficient_sol_for_fees` before anything is signed.
+`201` returns the vault row including `vault_address`. Note the address: the vault also needs a little **SOL** to pay swap fees and open token accounts, and there is no vault-funding endpoint. Send roughly 0.01 SOL to `vault_address` yourself, for example from your master wallet (see [user-wallet.md](#sec-488)). Without it, trades are refused with `insufficient_sol_for_fees` before anything is signed.
The browser flow is the "Open a vault" modal on [/vaults](https://three.ws/vaults), which is only shown to a signed-in user and pre-fills the same defaults.
@@ -113134,7 +116604,7 @@ curl -s "https://three.ws/api/vaults/ledger?vault_id=8b1c04f6-59a8-4d0e-a1b7-3f5
}
```
-Two properties worth relying on: rows are written **before** funds move for the paths that can double-submit (redeem, trade), so a `pending` or `failed` row is itself evidence of an attempt, and money-moving rows carry the signature you can verify yourself on Solscan. The same movements also land in the platform custody trail described in [custody.md](#sec-167).
+Two properties worth relying on: rows are written **before** funds move for the paths that can double-submit (redeem, trade), so a `pending` or `failed` row is itself evidence of an attempt, and money-moving rows carry the signature you can verify yourself on Solscan. The same movements also land in the platform custody trail described in [custody.md](#sec-170).
## Reading a vault
@@ -113165,16 +116635,16 @@ Two honest limits a backer should know: the platform can sign for the vault (tha
## Related
-- [trading-arenas.md](#sec-405) for the product overview of vaults and the surfaces around them
+- [trading-arenas.md](#sec-411) for the product overview of vaults and the surfaces around them
- [agent-wallets.md](#sec-072) for the custodial wallet a backer funds from
-- [custody.md](#sec-167) for spend limits, the freeze switch, and proof of custody
-- [user-wallet.md](#sec-482) for the per-user master wallet, the easiest way to send a vault its fee SOL
+- [custody.md](#sec-170) for spend limits, the freeze switch, and proof of custody
+- [user-wallet.md](#sec-488) for the per-user master wallet, the easiest way to send a vault its fee SOL
- [agent-reputation.md](#sec-056) for the badge that gates opening a vault
- [authentication.md](#sec-103) for sessions, CSRF tokens, and API keys
---
-<a id="sec-498"></a>
+<a id="sec-504"></a>
> **Source:** `docs/viability.md` · [↑ table of contents](#table-of-contents)
@@ -113218,12 +116688,25 @@ the shared public read limiter. `network` accepts `mainnet` or `devnet`; anythin
else resolves to `mainnet`. The page's Mainnet / Devnet toggle refetches both
views and relabels the fine print at the foot of the page.
-Each panel is supplementary by design: if its read fails, that panel hides itself
-rather than blocking the page or filling with empty cells. The trading panel also
-hides when a response arrives without the windowed aggregates (a deploy-skew
-guard), so a stale backend cannot render a panel of dashes. The page refreshes
-every 60 seconds while the tab is visible, and an "updated X ago" ticker stamps
-each successful load and re-renders every 15 seconds.
+Each panel owns its own read and its own three-state lifecycle, published as
+`data-state` on the panel's `<section>`:
+
+| State | What the reader sees |
+| --- | --- |
+| `loading` | Skeletons in the exact shape of the final figures, so nothing reflows when the numbers land. The section carries `aria-busy="true"`. |
+| `ready` | The live figures. |
+| `error` | The panel body is replaced by a notice naming what failed, why (offline, rate limited, the HTTP status, or a deploy-skew payload), a **Retry** that re-runs only that panel's read, and a link to [status](https://three.ws/status). |
+
+A failed read never blanks the panel and never leaves a stale number on screen.
+The trading panel also enters `error` when a response arrives without the windowed
+aggregates, which is the deploy-skew case: a backend answering in an older shape,
+reported as such rather than rendered as a grid of placeholders.
+
+The page refreshes every 60 seconds while the tab is visible. The "updated" stamp
+tracks the last read that actually rendered live figures: `reading live data`
+while the first read is in flight, `live read failed` when nothing has landed,
+`last good read Xm ago` when a refresh fails over figures already on screen, and
+`updated Xm ago` otherwise. It re-renders every 15 seconds.
Only already-public activity is eligible. Every query joins to
`agent_identities` and requires the agent to be non-deleted, `is_public = true`,
@@ -113306,14 +116789,15 @@ meaningful.
Positions that never close show up as cost with no profit and loss, and that is
the honest reading the panel is built around: profitability lives in round trips,
-not in volume. Until a position closes, the P&L cell shows a placeholder dash with
+not in volume. Until a position closes, the P&L cell reads "pending" with
"no closes yet" beneath it and the panel tag reads "no closes, 7d".
When there was any trading in the week, the panel also writes one plain-language
line under the KPI grid stating the trade count, the SOL deployed into buys, the
average trade, and either the closed-position result with its win rate or the fact
-that nothing has closed yet. With no trades in the window the line is hidden and
-the traders list explains how to start the loop. A "show trades in feed" link
+that nothing has closed yet. With no trades in the window the line says so for the
+selected network and the traders list explains how to start the loop. A
+"show trades in feed" link
appears only when there is something to show, pointing at the filtered
[Money Pulse](https://three.ws/pulse).
@@ -113332,8 +116816,9 @@ appears only when there is something to show, pointing at the filtered
- **Private activity is absent by construction,** not filtered after the fact:
non-public agents, opted-out agents, and owner-private custody categories are
excluded inside every query.
-- **A hidden panel means a failed read,** not zero activity. Zero activity renders
- the panel with explicit empty copy.
+- **A panel in its error state means a failed read,** not zero activity. Zero
+ activity renders the panel with explicit empty copy, and a failed read says so
+ in the panel and offers a retry.
---
@@ -113341,7 +116826,7 @@ appears only when there is something to show, pointing at the filtered
- [The autonomous economy](#sec-104): the wallets, spend policies,
paid skills, and trading loops whose real activity this page measures.
-- [x402 revenue and receipts](#sec-515): the platform's own endpoint
+- [x402 revenue and receipts](#sec-540): the platform's own endpoint
revenue, recorded in a different table and never mixed into the marketplace or
trading figures here.
- [Agent Economy Volume](#sec-052): the agent-to-agent USDC
@@ -113349,7 +116834,7 @@ appears only when there is something to show, pointing at the filtered
---
-<a id="sec-499"></a>
+<a id="sec-505"></a>
> **Source:** `docs/viewer.md` · [↑ table of contents](#table-of-contents)
@@ -113743,7 +117228,7 @@ A subset of state (background, transparency, background color, auto-rotate, expo
---
-<a id="sec-500"></a>
+<a id="sec-506"></a>
> **Source:** `docs/voice-lab.md` · [↑ table of contents](#table-of-contents)
@@ -113891,25 +117376,28 @@ The agent-voice handler ([`api/agents/_id/voice.js`](../api/agents/_id/voice.js)
- **Recorder states.** `idle` -> `recording` (live waveform, timer, level meter) -> `review` (playback, name, Clone / Re-record) -> `cloning` (spinner) -> `done` (green check, `voice_id` shown, actions: Try in playground / Add to an agent / Record another).
- **Auth.** The free lanes (Edge, Gemini, NVIDIA) serve anonymous callers on `/api/tts/synthesize` and `/api/tts/catalog`, rate-limited per IP. The metered lanes (OpenAI, ElevenLabs), cloning, and the Voice Library return `401 unauthorized` without a session or bearer token.
-- **Server config.** ElevenLabs must be configured (`ELEVENLABS_API_KEY`) or the endpoints return `503 not_configured`; a request carrying its own `x-eleven-key` header still works (see the billing section above).
+- **Server config.** ElevenLabs must be configured (`ELEVENLABS_API_KEY`) or the endpoints return `503 not_configured`; a request carrying its own `x-eleven-key` header still works (see the billing section above). `/api/tts/eleven-clone` checks who is asking first, so a signed-out caller gets `401` and never a reading of what this deployment has configured.
+- **A rejected key reads as a key problem.** When ElevenLabs turns down the key on a request, `/api/tts/eleven/voices` and both `/api/tts/eleven/library` methods answer `401 invalid_key` rather than `502`, so the UI can prompt for a new key instead of retrying. A rejected *platform* key still reads as `503 not_configured`, because that one is ours to fix.
+- **Voice ids are checked against the lane.** `POST /api/tts/synthesize` rejects a `voiceId` the chosen lane does not publish with `400 validation_error`, naming the id and the catalog URL to pick from, before anything is metered. It is never quietly swapped for the lane default (omit `voiceId` if that is what you want). ElevenLabs, whose catalog grows at runtime, reports an unknown id as a `400` from upstream instead.
- **Paid cloning tier.** Instant Voice Cloning is an ElevenLabs paid-tier (Starter and up) feature. On a free upstream tier the API surfaces the upstream `can_not_use_instant_voice_cloning` body verbatim as a `502`.
- **Length rules.** Voice Lab recommends 20 to 30 seconds, auto-stops at 60, and rejects under 3. The separate agent-clone endpoint (`POST /api/agents/:id/voice/clone`) enforces a 30-second floor. Platform-key clones on both endpoints are capped at 3 per user per day (an abuse guard on the shared account's limited clone slots) and each is charged per the billing section; BYOK clones on `/api/tts/eleven-clone` skip the cap.
- **Synthesis limits.** 1,000 characters per `/api/tts/synthesize` request (500 on the older `/api/tts/eleven`); every platform-key request is metered to credits per the billing section (charged before synthesis, refunded on failure). BYOK requests are unmetered by the platform. Clips are cached in R2 and cache hits are not charged.
- **Audio size.** Clone uploads are capped at ~10 MB.
- **"Add to an agent" on `/voice`** links to the dashboard; the actual assignment happens in the agent editor. The cloned `voice_id` lives in browser `localStorage` until you assign it.
-- **Error copy.** Mic denial, recorder failure, too-short recording, missing name, network failure, and clone failure each map to a specific message; the playground shows "Synthesizing...", then a size, a cached/generated tag, and the billing rung that served it, or an error. A lane's upstream failure is tagged with a code (`invalid_key`, `rate_limited`, `content_blocked`, `provider_unreachable`) that `/api/tts/synthesize` maps to a truthful HTTP status rather than a blanket 502.
+- **Error copy.** Mic denial, recorder failure, too-short recording, missing name, network failure, and clone failure each map to a specific message; the playground shows "Synthesizing...", then a size, a cached/generated tag, and the billing rung that served it, or an error. A lane's upstream failure is tagged with a code (`invalid_key`, `rate_limited`, `content_blocked`, `provider_unreachable`) that `/api/tts/synthesize` maps to a truthful HTTP status rather than a blanket 502. The message the picker renders is a written sentence, never the vendor's raw body: that ships alongside it in `detail` for debugging.
+- **A lane that goes down leaves the menu.** Configuration presence is not health, so what the last real synthesis learned decides what the catalog offers. A lane the provider refuses (expired key, billing hold upstream) is reported `available: false` with the reason for a few minutes, its voices drop out of the picker, and a synthesis aimed at it answers `503 lane_unavailable` with `retry_with: ["edge", "nvidia"]` rather than failing slowly again. The Voice Lab re-reads the catalog the moment a preview hits that 503, so the grid stops offering voices nobody can render while the explanation stays on screen. The window expires on its own and any successful call clears it, so recovery needs no deploy. Your own `x-eleven-key` is never gated by the platform key's outage.
- **Catalog freshness.** The Edge catalog is fetched live from Microsoft and cached 6 hours per instance; the ElevenLabs account catalog 5 minutes. Nothing is a hardcoded snapshot, so a voice Microsoft or ElevenLabs adds shows up on its own.
## Related
-- [Voice and lipsync tutorial](#sec-475): the authoritative step-by-step, including wiring a cloned voice into an agent.
-- [Lipsync](#sec-263): how synthesized speech drives an avatar's mouth in real time.
-- [Talking Avatar Video](#sec-397): render a talking-head clip from an avatar and an audio track.
+- [Voice and lipsync tutorial](#sec-481): the authoritative step-by-step, including wiring a cloned voice into an agent.
+- [Lipsync](#sec-264): how synthesized speech drives an avatar's mouth in real time.
+- [Talking Avatar Video](#sec-403): render a talking-head clip from an avatar and an audio track.
- Pages: [/voice](https://three.ws/voice), [/dashboard](https://three.ws/dashboard).
---
-<a id="sec-501"></a>
+<a id="sec-507"></a>
> **Source:** `docs/walk-leaderboard.md` · [↑ table of contents](#table-of-contents)
@@ -113956,7 +117444,11 @@ Every row carries `deltaFromYesterday`: the same metric earned **today** minus t
| This Week | `weekly` (default) | The current UTC date and the previous 6 days, so a rolling 7 days rather than a calendar week. |
| All Time | `all-time` | No lower bound. |
-The page defaults to **This Week / Distance**. Switching either control refetches from offset 0. Both control groups are ARIA tablists with left and right arrow-key navigation, and the board sets `aria-busy` while loading.
+The page defaults to **This Week / Distance**. Switching either control refetches from offset 0. Both control groups are ARIA radiogroups (one filter, one selection) with roving tabindex: arrow keys and Home/End move within a group, and the board sets `aria-busy` on the table while a request is open.
+
+Only the newest request may paint. Each load aborts the one before it and carries a generation number, so switching period and metric in quick succession always lands on the filter you last clicked, never on a stale page of rows, a column header naming the previous metric, or a skeleton that never resolves. Superseded requests show as cancelled in the network panel; that is the mechanism working, not a failure.
+
+A summary line above the board reports the qualifying walker count, the active metric and window, and the time of the last refresh. Because the board promises live updates, it re-fetches the first page every 45 s while the tab is visible, and once more on return from a hidden tab, both silently: a refresh that fails leaves the last good board in place instead of replacing it with an error. The refresh is skipped once you have paged past the first 50 rows, so **Show more** results are never yanked out from under you.
Ranking rules:
@@ -113973,6 +117465,17 @@ Ranking rules:
The page reads `localStorage['twx_walk_anon']` to pass `anonId`. It only reads, never creates, that key: the walk runtime is what mints it. So the pinned row appears for anonymous walkers who have actually walked, and simply does not appear for a first-time visitor.
+### Every state on the board
+
+| State | What renders | Why it is shaped that way |
+| --- | --- | --- |
+| Loading | Eight shimmering skeleton rows under the live column headers, with `aria-busy="true"` on the table. Paging swaps the **Show more** label for a loading label and disables the button. | The header stays put so the board does not jump when rows land. |
+| Populated | Ranked rows, the summary line, and your own pinned row when you have one. | |
+| Empty | The table is hidden entirely and a state card takes the card over, with copy written for the metric you asked for and a second action back to All Time whenever you are on a narrower window. | An all-headers, no-rows table is noise, and the reason a board is empty differs per metric: distance and time ask you to walk, sites explains that only walks away from three.ws count and points at the walk companion. A quiet day is not a dead end. |
+| Error | The same card shape with the failure reason and a **Retry** button that re-runs the request in place. | The board is public and unauthenticated, so a retry genuinely is the fix for nearly every failure here. |
+
+Row semantics are a real ARIA table: `table` on the grid, `columnheader` on the header cells, `row` and `cell` on each entry. The top three render a medal glyph in place of the number and carry their rank as screen-reader text, so a medal never reaches assistive tech as an empty cell, and the delta column pairs its `+`/`-` glyph with a spoken "up 120 m since yesterday". A polite live region announces the shape of each successful load (how many rows, of how many walkers, by which metric and window) instead of firing on all fifty rows individually.
+
---
## How a walk session is counted
@@ -114018,7 +117521,7 @@ As coded, in layers. Each one bounds a different kind of nonsense:
| Achievement allowlist | same | Only the four known codes persist, and each unlocks once per walker, so badges cannot be farmed by replaying a batch. |
| Idempotent rollup | unique index in [the migration](../api/_lib/migrations/20260621140000_walk_metrics.sql) | Batches merge into one row per dimension tuple per day, so the table cannot be flooded into a different shape. |
-**What these guards do and do not claim.** `POST /api/walk/metrics` is a public, open-CORS ingest keyed on a client-supplied anonymous id, because embeds post from third-party hosts and anonymous walkers are first-class on the board. The guards above bound the size, rate, and attribution of any single claim; they do not cryptographically prove that a walk happened. There is no cross-batch plausibility check (for example, distance against elapsed duration) and no server-side replay of the controller. Treat the board as a gamified activity ranking, not as an audited measurement. If you need a movement claim that a third party can verify, that is a different product: [World Lines](#sec-506) issue agent-signed proofs of physical presence with server-derived co-location.
+**What these guards do and do not claim.** `POST /api/walk/metrics` is a public, open-CORS ingest keyed on a client-supplied anonymous id, because embeds post from third-party hosts and anonymous walkers are first-class on the board. The guards above bound the size, rate, and attribution of any single claim; they do not cryptographically prove that a walk happened. There is no cross-batch plausibility check (for example, distance against elapsed duration) and no server-side replay of the controller. Treat the board as a gamified activity ranking, not as an audited measurement. If you need a movement claim that a third party can verify, that is a different product: [World Lines](#sec-512) issue agent-signed proofs of physical presence with server-derived co-location.
---
@@ -114184,14 +117687,14 @@ The anonymous id is generated and persisted by the walk runtime in `localStorage
## Related
-- [Add the Walk Companion to your site](#sec-476), the hands-on path from a copy-paste iframe to the `@three-ws/walk` package, including the surfaces that produce the metrics ranked here.
+- [Add the Walk Companion to your site](#sec-482), the hands-on path from a copy-paste iframe to the `@three-ws/walk` package, including the surfaces that produce the metrics ranked here.
- The walk documentation set on the site, served from `public/docs/walk/`: `/docs/walk` (index), `/docs/walk/getting-started`, `/docs/walk/walk-page`, `/docs/walk/embed-iframe`, `/docs/walk/embed-sdk`, `/docs/walk/companion-mode`, `/docs/walk/chrome-extension`, `/docs/walk/postmessage-events`, `/docs/walk/changelog`, and `/docs/walk/analytics`, which covers the per-creator dashboard fed by the same ingest.
- The creator-side view of this data: `three.ws/walk-analytics`, backed by `GET /api/walk/analytics`.
-- [World Lines](#sec-506), for movement claims that carry a verifiable agent signature rather than a leaderboard rank.
+- [World Lines](#sec-512), for movement claims that carry a verifiable agent signature rather than a leaderboard rank.
---
-<a id="sec-502"></a>
+<a id="sec-508"></a>
> **Source:** `docs/web-component.md` · [↑ table of contents](#table-of-contents)
@@ -114299,7 +117802,7 @@ el.removeAttribute('sign-language'); // off
Signing rides the same `SPEAK` event as spoken replies, so it works identically
in the hosted app and in an embed. A runnable page is
[examples/sign-language.html](../examples/sign-language.html); the engine and its
-vocabulary are documented in [Sign language](#sec-376), and the
+vocabulary are documented in [Sign language](#sec-381), and the
alphabet is browsable at [/asl-alphabet](https://three.ws/asl-alphabet).
### Skills and memory
@@ -115150,7 +118653,7 @@ defineElement('my-agent');
---
-<a id="sec-503"></a>
+<a id="sec-509"></a>
> **Source:** `docs/widget-api.md` · [↑ table of contents](#table-of-contents)
@@ -115357,7 +118860,7 @@ If you have multiple widgets and want to coordinate them (sync camera, broadcast
---
-<a id="sec-504"></a>
+<a id="sec-510"></a>
> **Source:** `docs/widget-studio.md` · [↑ table of contents](#table-of-contents)
@@ -115601,14 +119104,14 @@ You can override these freely in the iframe `width` and `height` attributes. Add
## Next steps
-- [Widget API (JSON-RPC)](#sec-503) — programmatic control over an embedded widget: camera, animation, screenshots, model loading
-- [Widgets reference](#sec-505) — technical details, postMessage API, CSP config, and oEmbed spec
-- [Web component](#sec-502) — the `<agent-3d>` custom element for developer integrations
-- [Embedding guide](#sec-183) — advanced embedding patterns and iframe options
+- [Widget API (JSON-RPC)](#sec-509) — programmatic control over an embedded widget: camera, animation, screenshots, model loading
+- [Widgets reference](#sec-511) — technical details, postMessage API, CSP config, and oEmbed spec
+- [Web component](#sec-508) — the `<agent-3d>` custom element for developer integrations
+- [Embedding guide](#sec-186) — advanced embedding patterns and iframe options
---
-<a id="sec-505"></a>
+<a id="sec-511"></a>
> **Source:** `docs/widgets.md` · [↑ table of contents](#table-of-contents)
@@ -116113,7 +119616,7 @@ No IP addresses, no user-agent strings, no cookies, no chat message content. The
## Programmatic control
-Need to drive a widget from the parent page — change the camera, play an animation, grab a screenshot? See the [Widget API (JSON-RPC)](#sec-503) reference. The `ThreeWidget` SDK lives at `/widget-client.js` and works with any iframe pointing at `/widget`.
+Need to drive a widget from the parent page — change the camera, play an animation, grab a screenshot? See the [Widget API (JSON-RPC)](#sec-509) reference. The `ThreeWidget` SDK lives at `/widget-client.js` and works with any iframe pointing at `/widget`.
---
@@ -116126,7 +119629,7 @@ Need to drive a widget from the parent page — change the camera, play an anima
---
-<a id="sec-506"></a>
+<a id="sec-512"></a>
> **Source:** `docs/world-lines.md` · [↑ table of contents](#table-of-contents)
@@ -116368,7 +119871,7 @@ Coverage for the crypto core lives in [tests/world-lines-crypto.test.js](../test
## Privacy: exactly what is stored
-The engineering analysis for all of IRL is the [IRL threat model](#sec-256); the user-facing summary is the `three.ws/irl-privacy` page. World Lines specifically:
+The engineering analysis for all of IRL is the [IRL threat model](#sec-257); the user-facing summary is the `three.ws/irl-privacy` page. World Lines specifically:
**Stored.**
@@ -116708,14 +120211,14 @@ Both handlers log their enforcement mode once per cold start, so a production mi
## Related
- [IRL: agents in the real world](irl.md#world-lines), the product-level overview and the rest of the presence layer.
-- [IRL threat model](#sec-256), the adversarial analysis behind every radius and cap above.
-- [Place a 3D agent in your real environment](#sec-453), how to create the anchor pin a World Line needs.
+- [IRL threat model](#sec-257), the adversarial analysis behind every radius and cap above.
+- [Place a 3D agent in your real environment](#sec-459), how to create the anchor pin a World Line needs.
- [API reference](#sec-096), the one-screen summary of these endpoints alongside the rest of `/api/irl/*`.
- [AR](#sec-099), the camera and WebXR layer the ceremony builds on.
---
-<a id="sec-507"></a>
+<a id="sec-513"></a>
> **Source:** `docs/x-archive.md` · [↑ table of contents](#table-of-contents)
@@ -116776,7 +120279,7 @@ clean checkout.
## The report
-[docs/x-archive/trythreews-engagement.md](#sec-508)
+[docs/x-archive/trythreews-engagement.md](#sec-514)
is generated, never hand-edited. It carries:
- headline totals and the engagement **distribution** (median, p75/p90/p99, and
@@ -116827,7 +120330,7 @@ Code: [scripts/x-archive-lib.mjs](../scripts/x-archive-lib.mjs)
---
-<a id="sec-508"></a>
+<a id="sec-514"></a>
> **Source:** `docs/x-archive/trythreews-engagement.md` · [↑ table of contents](#table-of-contents)
@@ -117078,9 +120581,3069 @@ The floor is as instructive as the ceiling: these are the shapes to stop repeati
---
-<a id="sec-509"></a>
+<a id="sec-515"></a>
+
+> **Source:** `docs/x-memory-seeding.md` · [↑ table of contents](#table-of-contents)
+
+# X memory seeding
+
+Give an agent your X voice: your public profile and recent original posts,
+distilled and written into the agent's long-term memory, so the replies it gives
+sound like the person who wrote them.
+
+This lane is built around one constraint. Connecting your X account to the
+platform (to post as your agent, for example) is permission to act on X on your
+behalf. It is **not** permission to write your posts into an agent's long-term
+memory. Those are two separate decisions, and the second one is its own
+explicit, versioned, revocable grant: nothing is read into memory until you say
+yes on a screen that tells you exactly what will be read and stored.
+
+- **Surface**: Settings, Connected accounts, X card at [/settings#connected-accounts](https://three.ws/settings#connected-accounts)
+- **API**: `/api/agents/:id/memory/seed/x`
+- **Related**: [Memory system](#sec-280), [Farcaster memory seeding](#sec-220), [GitHub seeding in the same table](memory.md#seeding-memory-from-an-existing-account)
+
+---
+
+## How it fits together
+
+```
+ Connect X (OAuth 2.0 PKCE, /api/auth/x/connect?scope=read)
+ │ the seeding card asks X for read scopes only: no permission to post
+ │ the connection alone changes nothing in memory
+ ▼
+ GET /api/agents/:id/memory/seed/x
+ │ returns the disclosure verbatim from the server, never copy in the page
+ ▼
+ you tick "I have read the above and consent"
+ │
+ ▼
+ POST … { consent: { accepted: true, scope_version } }
+ │ the version must match the disclosure you were shown
+ ▼
+ profile + up to 100 recent original posts are read once
+ distilled into up to 15 short facts about topics, opinions, projects, tone
+ written to agent_memories tagged x_seed, the top five always in context
+ │
+ ▼
+ DELETE /api/agents/:id/memory/seed/x (or disconnect X entirely)
+ │ revokes the grant and deletes every memory it produced
+ ▼
+ nothing distilled from your account survives
+```
+
+Four properties fall out of that shape:
+
+- **Connecting for seeding never grants permission to post.** The X card's
+ Connect button asks X for `tweet.read users.read offline.access` and nothing
+ else, so an owner who only wants their agent to sound like them is never asked
+ to hand over write access to their timeline. Posting is a separate connect
+ (`?scope=full`), offered next to it and labelled as such, and reconnecting
+ keeps the shape of the grant you already made.
+
+- **A POST without consent is refused before anything is read.** The handler
+ answers `403 consent_required` with the disclosure attached, and the
+ per-agent seed budget is consumed only after authorization, connection, and
+ consent all pass, so a rejected call never burns your re-seed window.
+- **Consent is pinned to the account and the text.** The grant records X's
+ numeric account id and the disclosure version you agreed to. Reconnect a
+ different X account, or let the disclosure wording move on, and the old grant
+ stops authorizing new seeds until you agree again.
+- **Revocation is total.** Every seeded row carries the `x_seed` tag and the
+ consent id that produced it. Revoking, or disconnecting X from Settings,
+ deletes exactly those rows, including any a superseded grant left behind.
+
+## Connecting: two grants, deliberately separate
+
+| | Seeding | Posting |
+|---|---|---|
+| Connect link | `/api/auth/x/connect?scope=read` | `/api/auth/x/connect?scope=full` |
+| Scopes X is asked for | `tweet.read users.read offline.access` | the read set plus `tweet.write media.write` |
+| Where it is offered | the X card in Settings, Connected accounts | the agent editor's Social tab, the share and walk-capture flows |
+| What it can do | read your profile and recent posts, once, when you consent | publish posts and upload media as you |
+
+A three.ws account holds exactly one X connection (`social_connections` is
+unique on user and provider), so the sets are not additive: a read-only connect
+replaces a posting connection with a read-only one, and the
+posting lane then answers `insufficient_scope` with the reconnect link rather
+than failing at the X API. The scope sets and both guards live in
+[api/_lib/x-scopes.js](../api/_lib/x-scopes.js); an unrecognised `scope=` value
+resolves to the full set, so a typo can never silently narrow what a posting
+surface asks for.
+
+Connections made before scopes were recorded store an empty scope string. Those
+are treated as unknown rather than as empty, so neither guard blocks them.
+
+## What is read, and what is not
+
+The consent screen shows this list verbatim from the server; the same module
+(`api/_lib/x-memory-seed.js`) enforces it, so the promise and the code cannot
+drift apart.
+
+| Read | Never read |
+|---|---|
+| Your X profile: display name, handle, bio, follower and following counts | Direct messages, drafts, likes, bookmarks, your follower list |
+| Up to 100 of your most recent **original** public posts (text and date) | Reposts and replies (excluded in the API call and re-checked in the transform) |
+| | Protected accounts you follow |
+
+| Stored on the agent | Never stored |
+|---|---|
+| Up to 15 short distilled facts (max 280 characters each) about your recurring topics, opinions, projects, and tone | The text of your posts; a distilled fact that copies a post is discarded before it is written |
+| Your X handle, so the agent can attribute what it learned | Links from your posts; URLs are stripped out of stored text |
+| The seed date and the disclosure version you agreed to | Any X credential; the access token stays encrypted in the connection record and is never copied into a memory |
+
+## What lands in memory
+
+Each fact becomes one row in `agent_memories`:
+
+- `type: 'reference'`, tagged `x` and `x_seed` plus up to three topics derived
+ from your posting history.
+- Salience `0.80` for the top-ranked fact, decaying by rank.
+- The **top five facts land in the `working` tier**, the always-in-context core
+ the chat runtime pages into every reply (see [memory system](#sec-280)).
+ That is what makes a seed observable in the very next conversation turn.
+- `context` carries `source: 'x_seed'`, your handle, the distillation lane
+ (`model` or `derived`), the disclosure version, and the consent id.
+
+If the distillation model chain is unavailable, the seed degrades rather than
+fails: deterministic facts are derived from your profile and your topic
+histogram (`distilled_by: 'derived'`), a smaller and blander seed instead of a
+silent zero.
+
+---
+
+## API
+
+All three calls are owner-only: the session user must own the agent. Browser
+mutations carry the standard CSRF token.
+
+### `GET /api/agents/:id/memory/seed/x`
+
+Connection state, the consent grant, and the disclosure. This is the only
+source of the consent screen's copy.
+
+```bash
+curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/x --cookie "$JAR"
+```
+
+```json
+{
+ "connected": true,
+ "configured": true,
+ "username": "you",
+ "connection_scopes": "tweet.read users.read offline.access",
+ "required_scopes": ["tweet.read", "users.read"],
+ "missing_scopes": [],
+ "scopes_ok": true,
+ "seeded_at": "2026-08-12T16:00:00.000Z",
+ "fact_count": 5,
+ "scope_version": "2026-08-11.1",
+ "disclosure": { "reads": ["…"], "skips": ["…"], "stores": ["…"], "never": ["…"], "…": "…" },
+ "consent": {
+ "granted": true,
+ "reason": "active",
+ "scope_version": "2026-08-11.1",
+ "granted_at": "2026-08-12T15:55:00.000Z",
+ "username": "you",
+ "last_seeded_at": "2026-08-12T16:00:00.000Z",
+ "memories_seeded": 5,
+ "posts_read": 10
+ }
+}
+```
+
+`consent.reason` is `none` when no grant exists, `scope_version_changed` when
+the disclosure moved (the old grant no longer authorizes seeds), and
+`account_changed` when the connection now points at a different X account than
+the one you consented for.
+
+`scopes_ok` is false when the live connection cannot cover the read the
+disclosure describes (you unticked a permission on X's screen, or the account is
+connected for posting only under a scope set that dropped `tweet.read`).
+`missing_scopes` names exactly what it lacks. The card shows a reconnect instead
+of the consent panel in that state, so nobody consents to a seed that could not
+run.
+
+### `POST /api/agents/:id/memory/seed/x`
+
+Grant consent (first call) and seed. Without a live grant the body must carry
+the acceptance of the current disclosure version:
+
+```bash
+curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/x --cookie "$JAR" \
+ -H 'content-type: application/json' -H "x-csrf-token: $CSRF" \
+ -d '{"consent":{"accepted":true,"scope_version":"2026-08-11.1"}}'
+```
+
+```json
+{
+ "username": "you",
+ "seeded": 5,
+ "posts_read": 10,
+ "distilled_by": "model",
+ "topics": ["agents", "solana", "threejs"],
+ "facts": ["The author builds 3D AI agents at three.ws …"],
+ "in_context": 5,
+ "consent": { "granted": true, "…": "…" }
+}
+```
+
+With a live grant the same call with an empty body re-seeds: the previous batch
+is deleted before the new one lands, so an agent never carries two generations
+of facts about the same account. Rate-limited to one seed per agent per 6 hours.
+
+### `DELETE /api/agents/:id/memory/seed/x`
+
+Revoke. Marks the grant revoked and deletes every memory the grant produced.
+Idempotent: an agent with no grant still gets any orphaned seeded rows purged.
+
+```json
+{ "revoked": true, "deleted": 5, "consents_revoked": 1, "remaining": 0, "consent": { "granted": false, "reason": "revoked" } }
+```
+
+Disconnecting X from Settings triggers the same deletion across **all** of your
+agents (`revokeAllSeedConsentsForUser`), so a disconnect can never leave
+distilled posts behind on an agent you forgot about.
+
+## Errors
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `unauthorized` | 401 | Sign-in required |
+| `not_found` / `forbidden` | 404 / 403 | No such agent, or it is not yours |
+| `not_connected` | 400 | Connect X first (Settings, Connected accounts) |
+| `insufficient_scope` | 400 | The connection cannot read your profile and posts; the body names the missing scopes. Reconnect with `?scope=read` |
+| `consent_required` | 403 | No live grant; the response carries the disclosure to show |
+| `account_mismatch` | 409 | The consent was granted for a different X account |
+| rate limited | 429 | One seed per agent per 6 hours |
+| `x_token_expired` | 502 | The stored access token would not refresh; reconnect X |
+| `x_read_denied` | 502 | X answered the read with 401/403, so the connection was revoked or narrowed on X's side |
+| `x_rate_limited` | 503 | X is throttling us; `retry_at` carries X's own reset time when it sent one |
+| `x_unavailable` | 502 | X answered with something else; `x_status` carries what |
+| `seed_empty` | 502 | Nothing usable came back, so nothing was written and the previous batch was left alone |
+
+### A run that stores nothing costs no window
+
+The six-hour budget is charged once a request is authorized, connected and
+consented, immediately before the first read. Every exit after that point which
+writes no rows (the five codes above, plus `account_mismatch`) hands the window
+straight back, and the response says which happened:
+
+```json
+{
+ "error": "x_rate_limited",
+ "error_description": "X is rate limiting us and returned no posts. X should accept the read again in about 9 minutes. Your memories are unchanged and this attempt did not use up your six-hour window, so you can seed again as soon as it is fixed",
+ "x_status": 429,
+ "retry_at": "2026-08-17T02:49:00.000Z",
+ "window_refunded": true
+}
+```
+
+`window_refunded` is `false` only when the refund itself could not be recorded
+(a Redis outage); the wording drops the "did not use up" clause to match. Two
+guarantees hold on all of these paths: the agent's existing memories are
+untouched, and no partial batch is ever written. In particular a re-seed that
+yields no usable fact returns `seed_empty` rather than deleting a good batch and
+replacing it with nothing.
+
+## Enabling it on a deployment
+
+The lane needs an X app with OAuth 2.0 and, at minimum, the `tweet.read`,
+`users.read` and `offline.access` scopes enabled (add `tweet.write` and
+`media.write` if the deployment also posts), created at
+https://developer.twitter.com with `https://<your-domain>/api/auth/x/callback`
+registered as the callback. Its two credentials are the only configuration:
+
+```
+X_OAUTH_CLIENT_ID=
+X_OAUTH_CLIENT_SECRET=
+```
+
+On Cloud Run, set them without disturbing the rest of the environment:
+
+```bash
+gcloud run services update three-ws-api --region us-central1 \
+ --project aerial-vehicle-466722-p5 \
+ --update-env-vars X_OAUTH_CLIENT_ID=...,X_OAUTH_CLIENT_SECRET=...
+```
+
+Until both are present, `GET /api/agents/:id/memory/seed/x` answers
+`configured: false` and the Settings card says X connections are not enabled on
+this deployment, rather than offering a Connect button that could not complete.
+Nothing else in the lane changes: the disclosure, the consent grant, and
+revocation behave identically once the credentials are in place.
+
+## Storage
+
+One table, created by `api/_lib/migrations/20260811140000_x_memory_consent.sql`:
+
+- `x_memory_consents` is the durable grant: the X account id, handle, the
+ disclosure version, the exact disclosure text shown, the scopes the OAuth
+ connection actually held at grant time, seed counters, and the revocation
+ timestamp and reason. At most one live grant per agent (partial unique
+ index).
+
+Seeded rows in `agent_memories` are found by tag (`tags && '{x_seed}'`) and by
+`context->>'consent_id'`, indexed for revocation.
+
+## Source
+
+| Piece | File |
+|---|---|
+| HTTP surface (OAuth refresh, reads, consent gates) | [api/agents/[id]/memory-seed-x.js](../api/agents/[id]/memory-seed-x.js) |
+| Disclosure text, selection, sanitisation, memory rows (pure, tested) | [api/_lib/x-memory-seed.js](../api/_lib/x-memory-seed.js) |
+| Revocation shared by DELETE, disconnect, and account switch | [api/_lib/x-seed-consent.js](../api/_lib/x-seed-consent.js) |
+| OAuth 2.0 PKCE connect and callback | [api/auth/x/[action].js](../api/auth/x/[action].js) |
+| Scope sets, and the read/write guard each lane applies | [api/_lib/x-scopes.js](../api/_lib/x-scopes.js) |
+| Consent screen (renders the server's disclosure verbatim) | [public/settings/index.html](../public/settings/index.html) |
+| Transform tests | [tests/api/x-memory-seed-transform.test.js](../tests/api/x-memory-seed-transform.test.js), [tests/api/agents-memory-seed.test.js](../tests/api/agents-memory-seed.test.js) |
+| Consent gate, scope gate and revocation tests | [tests/api/x-memory-seed-consent.test.js](../tests/api/x-memory-seed-consent.test.js), [tests/api/x-scopes.test.js](../tests/api/x-scopes.test.js) |
+| What the connect redirect asks X for | [tests/api/x-connect-scope.test.js](../tests/api/x-connect-scope.test.js) |
+
+---
+
+<a id="sec-516"></a>
+
+> **Source:** `docs/x-posts/3d-ar-studio-launch.md` · [↑ table of contents](#table-of-contents)
+
+# 3D AR Studio launch
+
+The multi-model AR surface behind `three.ws/ar/studio`, extracted, generalized and published
+as an open-source package anyone can drop into their own site.
+
+**Live:**
+
+- Demo: <https://nirholas.github.io/3D-AR-Studio/>
+- Repo: <https://github.com/nirholas/3D-AR-Studio>
+- npm: `3d-ar-studio`, `3d-ar-studio-mcp`
+- MCP registry: `io.github.nirholas/3d-ar-studio`
+
+**Media plan.** Lead with the room screenshots, not the UI. The whole argument is that an
+object is standing on a real floor, so the first frame has to show a real floor.
+
+1. The car model standing in the living room, shot through the phone
+2. The armoured character standing in the same hallway
+3. The studio itself with the prompt box visible, so the reader sees where it came from
+4. Optional fourth: the desktop QR handoff
+
+---
+
+## Angle A: the one-line pitch (recommended)
+
+Post this as a single tweet with images 1, 2 and 3.
+
+```
+Your iPhone has shipped with AR hardware for years. Almost no website uses it.
+
+So I made it one line:
+
+<script src="unpkg.com/3d-ar-studio"></script>
+<ar-studio></ar-studio>
+
+Type a prompt, get a 3D model, stand it on your actual floor at actual size. Add ten more. Send the whole room as a link.
+
+Free. Open source. Works right now.
+
+nirholas.github.io/3D-AR-Studio
+```
+
+### Shorter alternate
+
+```
+Every iPhone has had ARKit for years and almost no website uses it.
+
+3D AR Studio makes it one script tag: describe an object, watch it appear, put it on your real floor. Add more. Share the whole scene as a link.
+
+Open source, free, no key.
+
+nirholas.github.io/3D-AR-Studio
+```
+
+---
+
+## Angle B: the fix (use if the launch post underperforms, or as a follow-up a day later)
+
+This is the sharper hook and it is true: the studio used to fall back to compositing over the
+camera feed on iOS, which photographs like AR and behaves nothing like it.
+
+```
+Spent the day finding out my own AR was fake on iPhone.
+
+No WebXR on iOS, so the model was just composited over the camera feed. It floats. It has no real size. Nothing occludes it.
+
+Every iPhone already ships ARKit through Quick Look. Now it uses it, and the model is converted on the device in about a second.
+
+nirholas.github.io/3D-AR-Studio
+```
+
+---
+
+## Thread
+
+Post Angle A as 1/, then:
+
+**2/**
+
+```
+Most web AR drop-ins place exactly one model and hand you off to a native viewer. That ends the session.
+
+This keeps the whole scene in your page. Place as many as you want, drag them, pinch to resize, twist to rotate. The arrangement is yours.
+```
+
+**3/**
+
+```
+Every device gets its real path, not an approximation.
+
+Android and headsets: WebXR with one anchor per model, real light estimation, and depth occlusion so things hide behind your couch.
+
+iPhone: Apple's AR Quick Look. The model is converted to USDZ on the device in about a second.
+```
+
+**4/**
+
+```
+Scenes are links. Compose on a laptop, scan the QR, it reopens exactly on your phone.
+
+Open a room and someone else can build in it with you, live.
+
+There's an MCP server too, so an agent can generate a model, arrange a scene, and hand a person one link that opens it in their room.
+
+npm i 3d-ar-studio
+github.com/nirholas/3D-AR-Studio
+```
+
+---
+
+## Reply and quote-tweet lines
+
+Use these under the main post rather than stuffing them into it.
+
+- The models are free too. A few hundred public-domain props, and text-to-3D with no key and
+ no account.
+- Point it at your own catalogue with one option: `assets: 'https://your.cdn/models.json'`.
+ Five common manifest shapes are read without reshaping anything.
+- `npx 3d-ar-studio create my-ar-site` then `npx 3d-ar-studio deploy` puts a live AR page on
+ GitHub Pages. Two commands.
+- Characters do not T-pose. Any humanoid with no baked animation gets an idle clip retargeted
+ onto its own skeleton, with no rig allow-list.
+- Apache-2.0. Take it and put it in your product.
+
+## Replies to expect
+
+- **"Does this need an app?"** No. It is a web page. The AR opens in the viewer your phone
+ already has.
+- **"What does the generation cost?"** Nothing, and it needs no account or key.
+- **"Can I use my own models?"** Yes, one option. Or write a source object with a `list()`
+ and it can come from anywhere.
+- **"Why not just model-viewer?"** model-viewer places one model and hands off. This composes
+ a whole scene, keeps it in your page, generates new models into it, and shares the
+ arrangement as a link.
+- **"iOS support?"** Real ARKit through Quick Look, with the USDZ built on the device.
+
+## Do not claim
+
+- Do not say WebXR works on iPhone. It does not. iOS gets Quick Look and that is the point.
+- Do not promise multi-model placement inside Quick Look or Scene Viewer. Those native
+ viewers take one model at a time; the multi-model scene lives in the page.
+- Do not put a number on generation time. It depends on queue depth.
+
+---
+
+<a id="sec-517"></a>
+
+> **Source:** `docs/x-posts/3d-ar-studio-video-script.md` · [↑ table of contents](#table-of-contents)
+
+# 3D AR Studio launch video
+
+Narration script for the launch video. Written for ElevenLabs text to video, with a three.ws
+3D avatar render used as the visual reference for Veo.
+
+**Voice direction.** Even, unhurried, slightly dry. No rising enthusiasm, no smile in the
+voice. The footage is doing the selling; the read is a person telling you something they find
+mildly outrageous. Leave the pauses in.
+
+**Pacing.** Roughly 155 words a minute. Each script below is timed at that rate, so the 30
+second cut is about 80 words.
+
+---
+
+## 30 seconds (primary)
+
+> Your phone has had augmented reality hardware in it for years.
+>
+> Almost no website has ever used it.
+>
+> This is 3D AR Studio.
+>
+> Describe something. Watch it appear.
+>
+> Then put it on your actual floor, at actual size.
+>
+> Add another one. Move them around. Walk through them.
+>
+> When it looks right, send the whole room to someone as a link.
+>
+> One script tag. No key, no account, no app.
+>
+> It's free, it's open source, and it already works on the phone in your pocket.
+
+---
+
+## 15 seconds (cutdown for the reply slot)
+
+> Your phone has had AR hardware in it for years, and almost no website uses it.
+>
+> 3D AR Studio is one script tag.
+>
+> Describe something, watch it appear, stand it on your real floor.
+>
+> Free. Open source. Works right now.
+
+---
+
+## 60 seconds (extended, for YouTube and the site)
+
+> Your phone has had augmented reality hardware in it for years.
+>
+> Almost no website has ever used it.
+>
+> This is 3D AR Studio. It's one script tag, and it turns any web page into this.
+>
+> Describe something you want. It gets generated, and it lands in the room in front of you.
+>
+> Not floating in a camera filter. On the floor. At the size it would really be.
+>
+> Add another. And another. Drag them around until the room looks right.
+>
+> Then send it. The whole arrangement travels as a link, so what you built on a laptop opens
+> exactly the same on someone else's phone.
+>
+> Or open a room, share the code, and build it together while you're both standing in it.
+>
+> There are hundreds of free models in it already. Generating a new one costs nothing and
+> needs no account.
+>
+> It's open source. Take it and put it in your own product.
+
+---
+
+## Shot prompts for Veo
+
+Use the three.ws avatar render as the character reference on shots 2 and 5. Keep every shot
+handheld with slight natural motion: the entire point is that the objects stay put while the
+camera moves. No drone moves, no gimbal glide, no lens flare.
+
+1. Close handheld shot of a person holding a phone in a bright living room, screen facing
+ camera, empty hardwood floor visible behind them, soft daylight from a window
+2. Same room, camera pushes past the phone: a stylized 3D character now stands on the floor at
+ human height, with a correct contact shadow and window light falling on it from the same
+ direction as the room
+3. Handheld orbit at chest height: two or three objects standing on the real floor at
+ different distances, strong parallax as the camera moves around them
+4. Close on the phone screen: a text field, a few words typed, then an object materializing
+ into the room visible behind the screen
+5. Wide shot, two people in the same room both holding phones, both looking at the same
+ character standing on the floor between them
+6. End card, matte black, product name and URL only, no motion
+
+### Negative direction
+
+Give these to Veo as things to avoid, because they are exactly what makes AR footage read as
+fake:
+
+- objects floating above the floor or intersecting furniture
+- an object that slides or swims when the camera moves
+- shadows that do not match the room's light direction
+- a phone screen showing a different scene from the one behind it
+- lens flares, glossy product-ad lighting, sped-up camera moves
+
+---
+
+## Captions
+
+Burn in short captions rather than relying on autoplay sound. Keep them to one line each and
+match them to the narration beats:
+
+1. Your phone has had AR hardware for years
+2. Almost no website uses it
+3. Describe it. Watch it appear.
+4. On your actual floor, at actual size
+5. Send the whole room as a link
+6. One script tag. Free. Open source.
+7. nirholas.github.io/3D-AR-Studio
+
+---
+
+<a id="sec-518"></a>
+
+> **Source:** `docs/x-posts/README.md` · [↑ table of contents](#table-of-contents)
+
+# X post drafts
+
+Ready-to-paste X (Twitter) announcement copy and the video prompts that go with it. Internal
+staging only: nothing here is posted automatically, and posting is owner-gated per
+[`CLAUDE.md`](../CLAUDE.md) (`git push` / publishing / posting to external channels needs
+explicit approval). Each file states what it's for and what has already been verified true.
+
+- [`metaplex-agent-mcp-launch.md`](#sec-525): the open-source agent
+ infrastructure announcement: `@three-ws/metaplex-agent-mcp` (on-chain deploy + identity) and
+ `@three-ws/onchain-agent-wallets` (spending allowance + x402), and why every integration is
+ bullish for $THREE.
+- [`metaplex-agent-mcp-veo-script.md`](#sec-526): shot-by-shot Veo
+ (image-to-video) prompts for the companion clip, built from a three.ws 3D avatar as the
+ reference frame.
+- [`sperax-staking-in-chat-x-post.md`](#sec-532): SperaxOS chat-native
+ staking/balance/buy-SPA tool calls (shipped) and the embedded `/staking` iframe page (not yet
+ working, do not announce until the blockers listed in the file are resolved).
+
+Not registered in `data/pages.json`, and doesn't need to be: `scripts/audit-docs.mjs` only checks
+direct `docs/*.md` files for a page entry, not files under a `docs/` subdirectory, so a nested
+folder like this one is the convention for internal drafts that shouldn't be crawlable.
+
+---
+
+<a id="sec-519"></a>
+
+> **Source:** `docs/x-posts/event-x-posts.md` · [↑ table of contents](#table-of-contents)
+
+# X posts: Three.ws User Group first in-world meetup (IBM Community)
+
+Copy for the launch-day X push. **The IBM angle is the point of this event**, so IBM leads every
+post: this is the first in-world meetup of the [Three.ws User Group on IBM
+Community](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016),
+an official IBM Community user group, held inside three.ws itself rather than on a call.
+
+**Event:** three.ws Community Meetup: Live on the $THREE Server
+**When:** Friday, August 7, 2026, 8:00 AM Pacific / 11:00 AM Eastern / 4 PM London / 5 PM Berlin
+**Where:** [three.ws/play](https://three.ws/play), the $THREE world pinned at the top of the lobby
+**Cost:** free, no download, no install, no account, no wallet
+
+**IBM event listing (the link every post points at):**
+`https://community.ibm.com/community/user/events/event-description?CalendarEventKey=25d71799-16b5-4342-b2e5-019fcf9622ca&CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016`
+
+Two rules for every post here:
+
+1. **Never state hours-until.** Say "today" and give the absolute clock time. A post that says
+ "in 4 hours" is wrong the moment it is reposted, quoted, or found late.
+2. **IBM in the first line.** The user group is the reason this event exists. Do not bury it under
+ the game features.
+
+---
+
+## 1. Main teaser (post this first, with video)
+
+> Today: the first in-world meetup of the Three.ws User Group on IBM Community.
+>
+> Not a webinar. Open three.ws/play in a browser, become a 3D avatar, and walk around the $THREE
+> world with the team. Spatial voice, live demos, open Q&A.
+>
+> 8 AM PT / 11 AM ET. Free, no install, no account.
+>
+> [IBM event link]
+
+**Media:** the strongest 20 to 40 seconds you have of `/play`. Lead with movement (a crowd in the
+plaza, avatars walking) rather than a static wide shot. First frame matters more than the last.
+
+---
+
+## 2. The IBM technical post (this is the one that earns the user group its members)
+
+Post this second, roughly an hour after the teaser. It is the reason an IBM developer should care.
+
+> Why an IBM Community user group is meeting inside a 3D world:
+>
+> three.ws is an IBM Business Partner. Our agents think on IBM Granite served through watsonx.ai,
+> and two of our MCP servers are IBM-native:
+>
+> @three-ws/ibm-watsonx-mcp, watsonx.ai on your own IBM Cloud account
+> @three-ws/ibm-x402-mcp, pay-per-use Granite billed in USDC, no IBM account needed
+>
+> Come ask us about any of it, in person: [IBM event link]
+
+---
+
+## 3. Alternates for the main slot
+
+Pick one. Do not post all three.
+
+**Short and blunt**
+
+> The Three.ws User Group on IBM Community meets today, inside three.ws.
+>
+> A browser tab, a 3D avatar, spatial voice, live demos, and the team answering anything.
+>
+> 8 AM PT / 11 AM ET. Free: [IBM event link]
+
+**Contrast-led**
+
+> Most user groups meet on a video call.
+>
+> Ours meets in a 3D world you open in a browser tab. You walk up to someone and you hear them,
+> from the direction they are standing.
+>
+> First Three.ws User Group meetup on IBM Community is today, 8 AM PT: [IBM event link]
+
+**Builder-led**
+
+> If you build AI agents that need a body, spatial reasoning, or generative 3D, the Three.ws User
+> Group on IBM Community is your room. It meets today, and it meets inside the product.
+>
+> 8 AM PT / 11 AM ET, free, browser only: [IBM event link]
+
+---
+
+## 4. Thread version (if you want the reach)
+
+**1/**
+> Today: the first in-world meetup of the Three.ws User Group on IBM Community.
+>
+> Not a Space, not a webinar. An actual 3D world you walk into from a link, with the team standing
+> in it.
+>
+> 8 AM PT / 11 AM ET: [IBM event link]
+
+**2/** (attach the best plaza / crowd clip)
+> How you join, in full: open three.ws/play, click the $THREE world pinned at the top, you are in.
+> Guests get an avatar automatically. No download, no account, no wallet.
+
+**3/** (attach voice or group-conversation footage)
+> Voice is spatial. You hear the people near you, from the direction they are standing, fading as
+> you walk away. Three conversations can happen twenty meters apart without talking over each
+> other, exactly like a conference hallway.
+
+**4/** (attach `/create` footage, or an avatar generation clip)
+> Want to show up as yourself? Build a custom 3D agent first at three.ws/create from a text prompt
+> or a selfie. Rigged and animation-ready in about a minute, and it follows you into the world.
+
+**5/** (attach the strongest world / demo footage)
+> Why IBM Community: three.ws is an IBM Business Partner, our agents run on IBM Granite through
+> watsonx.ai, and we ship @three-ws/ibm-watsonx-mcp and @three-ws/ibm-x402-mcp for anyone building
+> on watsonx.
+>
+> Live demos and open Q&A on all of it today: [IBM event link]
+
+**6/**
+> Every community can do this, not just ours. Every pump.fun coin already has a world at
+> three.ws/play?coin=<mint>. No booking, no whitelist, no fee. The venue layer is a URL scheme.
+>
+> Come see it working: [IBM event link]
+
+---
+
+## 5. Follow-ups for the rest of the day
+
+**Shortly before doors** (quote your own main post)
+> Doors open shortly. New to 3D worlds? Come 10 minutes early and we will walk you through the
+> controls personally. three.ws/play
+
+**The moment it goes live**
+> We are live. The Three.ws User Group on IBM Community is meeting inside three.ws right now.
+>
+> Open three.ws/play, click the pinned $THREE world, walk over and say hi.
+
+**Mid-event, with a screenshot of the actual crowd**
+> This is an IBM Community user group meeting, happening right now. Still time to walk in:
+> three.ws/play
+
+**After it ends** (this is the one that recruits for the next event)
+> That was the first Three.ws User Group meetup on IBM Community.
+>
+> [attach the group shot or the best clip from the day]
+>
+> The group is open and the world stays open. Join the group: [IBM user group link]
+
+---
+
+## 5b. Sharing Jessica's IBM Community blog
+
+Jessica's post on the user group ("Join the Three.ws User Group's First In-World Meetup This
+Friday") is the single best asset in this campaign, because it is IBM's own voice saying the thing
+we have been saying all week. Our posts are marketing; hers is a user group organizer telling her
+own members not to skip this. Lead with who wrote it, let the quote carry the argument, and keep
+our own commentary to one line.
+
+Two accounts, two jobs. `@trythreews` posts the institutional version: IBM wrote this, here it is.
+`@nichxbt` posts the human version: working with her has been great. Do not put the warm personal
+note on the brand account, and do not post both within a few minutes of each other.
+
+### From @trythreews (recommended, tight quote). This is the posted version.
+
+> The official @IBM blog for today's meetup is up, written by Jessica, a core member of the @IBM
+> team behind the Three.ws User Group and the one who made all of this possible.
+>
+> "It is not a video call. The three.ws team is hosting the group's first community meetup inside
+> the platform itself, in the flagship world at three.ws/play. You attend as an avatar, you hear
+> the people standing near you through spatial voice chat, and the product tour happens by
+> literally walking through the product."
+>
+> [blog link]
+
+That cut is deliberate. The second paragraph of her post is the whole argument in four sentences
+and it ends on the best line she wrote ("the product tour happens by literally walking through the
+product"). Ending a quote on the strongest sentence is worth more than including every sentence.
+
+### From @trythreews (full quote, if you want her framing of why the group exists)
+
+> The official blog for today's meetup is up on IBM Community, written by Jessica, a core member of
+> the @IBM Community team behind the Three.ws User Group.
+>
+> "When this user group launched in July, the promise was more than threads and blog posts: it was
+> live sessions with the people actually building AI agents with 3D capabilities. This Friday we
+> get the first one, and I want to make sure nobody misses it because they assumed it was another
+> webinar link.
+>
+> It is not a video call. You attend as an avatar, you hear the people standing near you through
+> spatial voice chat, and the product tour happens by literally walking through the product."
+>
+> [blog link]
+
+### From @nichxbt (the human one, quote-tweeting the @trythreews post above)
+
+> Jessica has been helping us with this from the start, and honestly it has been a pleasure working
+> with her. IBM Community got a real organizer on this group.
+>
+> Read her post, then come meet her in-world. She built her own 3D agent from a selfie for today.
+
+**Media for the @trythreews post:** Jessica's custom 3D agent, in-world, is the single best image
+you can attach. It closes the loop: the person who wrote the IBM blog is standing in the product,
+as an avatar she generated from a selfie. Second choice is a clean screenshot of the blog header on
+community.ibm.com so the IBM domain is visible in the frame.
+
+**Rules for this one:**
+
+- Name her and her role in the first line. "Jessica from IBM wrote this" is the headline, not the
+ blog title.
+- Quote verbatim inside quotation marks. Do not paraphrase her into our voice. The credibility of
+ the post comes entirely from it being her words, not ours.
+- One link, hers, at the end. Do not stack the event listing and the user group link on this post;
+ every other post in the campaign already carries those.
+- Do not add our own "and here is why that matters" paragraph. Her post already argues it.
+
+---
+
+## 5c. Sharing Jessica's recap (published)
+
+Jessica's recap, ["The First Three.ws User Group Meetup: How It
+Went"](https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm),
+is up on IBM Community. Same two-account split as the announcement post in 5b: `@trythreews` posts
+the institutional version, `@nichxbt` quote-tweets it with the human one. Do not post both within a
+few minutes of each other.
+
+### From @trythreews (recommended, leads with the concurrency stat). This is the posted version.
+
+The stat is the hook: it's the single number in her post a reader has no way to guess, and it lands
+harder on X than the framing sentence does. This excerpt is contiguous, verbatim, straight out of
+her post, just the framing clause and the number, without the full paragraph's extra sentence.
+
+> Jessica, the @IBM Community organizer behind the Three.ws User Group, just published her own recap
+> of Friday's meetup.
+>
+> "This group is still small, but the open world we held it in is not gated to members: anyone with
+> the link could walk in, and a lot of people did. Peak concurrency in the world hit 3,145 avatars at
+> once over the course of the day, well past anything a call could have seated."
+>
+> https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm
+
+### From @trythreews (alternate, tight quote without the stat)
+
+> Jessica, the @IBM Community organizer behind the Three.ws User Group, just published her own recap
+> of Friday's meetup.
+>
+> "Neither IBM nor three.ws is the slow, boring-enterprise thing people assume from the outside. We
+> both like trying things that are actually new, and a nine-hour user-group meetup held entirely
+> inside a 3D world, instead of on a call, is exactly that kind of thing. It held up."
+>
+> https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm
+
+### From @trythreews (full quote, if you want both the framing and the number)
+
+> Jessica, the @IBM Community organizer behind the Three.ws User Group, just published her own recap
+> of Friday's meetup.
+>
+> "Neither IBM nor three.ws is the slow, boring-enterprise thing people assume from the outside. We
+> both like trying things that are actually new, and a nine-hour user-group meetup held entirely
+> inside a 3D world, instead of on a call, is exactly that kind of thing. It held up. This group is
+> still small, but the open world we held it in is not gated to members: anyone with the link could
+> walk in, and a lot of people did. Peak concurrency in the world hit 3,145 avatars at once over the
+> course of the day, well past anything a call could have seated, even though most of that crowd
+> came for the open world itself rather than being User Group members."
+>
+> https://community.ibm.com/community/user/blogs/jessica-swanson/2026/08/08/the-first-threews-user-group-meetup-ibm
+
+### From @nichxbt (the human one, quote-tweeting the @trythreews post above)
+
+> Jessica called it exactly right: this was never going to be the slow, boring-enterprise version of
+> a partnership. Proud of what we built together and even more proud she felt like writing that.
+>
+> Read the whole thing, then go stand in the world she's describing: three.ws/play
+
+**Media for the @trythreews post:** a clean screenshot of the recap's header on community.ibm.com,
+so the IBM domain and Jessica's byline are visible in the frame. Second choice: the in-world plaza
+shot from the day, if you have one with a visibly dense crowd, since the post is making a
+concurrency claim.
+
+**Rules for this one, same as 5b:**
+
+- Name her and her role in the first line. "Jessica wrote a recap" is the headline, not the blog
+ title.
+- Quote verbatim inside quotation marks. Do not paraphrase her into our voice.
+- One link, hers, at the end. Do not stack the event listing or the user group link on this post.
+- Do not add our own "and here is why that matters" paragraph. Her post already argues it.
+
+---
+
+## 6. Recycling the existing `/play` footage
+
+Map what you already have to the beats above, so each post carries a clip that matches its copy:
+
+| Post | Best clip to use |
+| --- | --- |
+| Main teaser | Crowd or plaza movement. Motion in frame one, no menus, no cursor. |
+| IBM technical post | Screen-recording of an agent responding, or the world at its best. Text carries this one. |
+| Thread 2 | The lobby, then landing in the world. Shows the zero-friction claim rather than asserting it. |
+| Thread 3 | Avatars standing in a group, chat bubbles, people walking up to each other. |
+| Thread 4 | An avatar generation on `/create`, then that avatar in-world. |
+| Thread 5 and 6 | Widest good-looking shot you own, or any world other than $THREE. |
+
+Practical notes for reused footage:
+
+- Trim anything showing a debug overlay, a localhost URL, an empty world, or an FPS counter.
+- Assume muted autoplay. If a clip only works with sound, it does not work.
+- Native upload, never a link to a video elsewhere. X suppresses off-platform video reach.
+- Square or 4:5 outperforms 16:9 in the timeline. Crop toward the avatars.
+- One link per post, at the end. The IBM event listing before and during; the IBM user group page
+ after it ends.
+
+---
+
+<a id="sec-520"></a>
+
+> **Source:** `docs/x-posts/fomo-verified-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: $THREE verified on fomo
+
+Copy for announcing that **$THREE (the token) is verified on [fomo](https://fomo.family)** (@fomo
+on X), the social-first crypto trading app from ex-Uniswap / Opensea / dYdX builders. fomo is
+self-custodial, onramps with Apple Pay, and trades Solana assets in-app.
+
+**What this announcement is:** a safety note. Holders and new users get one more vetted,
+verifiable venue to acquire $THREE, where the app itself marks the real listing so nobody is
+guessing between lookalike mints.
+
+**What it is not:** a price post. No moon language, no "don't miss out", no predictions, no
+telling anyone to buy. State the verification, state why verification matters, stop.
+
+**Media for every option:** [fomo-verified-x.png](media/fomo-verified-x.png) (2400x1350, 16:9,
+dark mode: $THREE cube mark x fomo mark, "verified" badge). Built from fomo's own 1024px mark and
+`public/brand/three-ws-mark.png` on fomo's `#0B091F` navy.
+
+Rules:
+
+1. Tag @fomo so their team sees it and can repost.
+2. Claim only what happened: $THREE is verified in the fomo app. three.ws does not trade on fomo
+ and no post should imply it does.
+3. Including the contract address is encouraged. Repeating the real mint is anti-scam hygiene,
+ not shilling: `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`
+
+---
+
+## 1. Main post
+
+> $THREE is now verified on @fomo.
+>
+> What that means in practice: search $THREE in the fomo app and the verified badge marks the
+> real listing. No guessing between lookalike mints.
+>
+> We want acquiring $THREE to be safe and verifiable, wherever you do it. fomo is now one of
+> those places: self-custodial, on Solana.
+>
+> fomo.family
+
+---
+
+## 2. Short alternate
+
+> $THREE now carries the verified badge on @fomo.
+>
+> If you pick up $THREE, use a venue that verifies the mint, and always check the CA yourself:
+>
+> FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+---
+
+## 3. Safety-PSA alternate
+
+> A note for anyone acquiring $THREE: it is now verified on @fomo.
+>
+> Verified listings exist because copycat mints exist. Whatever venue you use, buy the marked,
+> vetted listing and confirm the contract address:
+>
+> FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+>
+> Self-custody the rest.
+
+Pick one. Do not post all three.
+
+---
+
+## 4. Thread closer (reply to the main post)
+
+Post this as a reply to whichever option ran, to cap the thread. The graphic carries the
+disclaimer, so the reply text stays short.
+
+**Media:** [fomo-thread-end.png](media/fomo-thread-end.png) (2400x1350, 16:9). Same visual
+system as the main graphic, "/ end of thread" as the headline, and the fine print baked in:
+the not-financial-advice / do-your-own-research statement plus the full contract address.
+
+> That is the whole update. $THREE is verified on @fomo.
+>
+> Verify the mint yourself, wherever you trade:
+> FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+>
+> / end
+
+Shorter alternate:
+
+> / end of thread
+>
+> Verify before you act: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+---
+
+<a id="sec-521"></a>
+
+> **Source:** `docs/x-posts/ibm-skillsbuild-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# IBM SkillsBuild badge post: getting an @IBM reply
+
+Draft copy for the X post announcing the **Getting Started with Cybersecurity** badge
+(IBM SkillsBuild, issued 2026-06-08) and tying it to the three.ws team.
+
+Badge: https://www.credly.com/badges/b7ea921a-ce3d-4f4d-bfac-38f95276d361
+Share link (the one to paste): https://www.credly.com/badges/b7ea921a-ce3d-4f4d-bfac-38f95276d361/twitter
+
+## What actually earns the reply
+
+Derived from a 500-tweet scrape of @IBM's timeline (2026-06-17 to 2026-08-17). IBM
+replied 14 times in that window. Every reply was one short line of praise on a badge
+post, never on a product take or a news comment:
+
+| IBM's reply | Date | Views on the reply |
+|---|---|---|
+| "Great work! Keep learning!" | 2026-06-17 | 897 |
+| "Wonderful work!" | 2026-06-27 | 150 |
+| "Awesome work!" | 2026-06-29 | 119 |
+| "Nicely done!" | 2026-07-01 | 106 |
+| "Thanks so much!" (x5) | 2026-06-17 | 43-293 |
+
+The posts that drew them share four traits. Keep all four:
+
+1. **`@IBM` is mentioned by handle**, not written as plain text. That mention is the
+ trigger their social listening keys on.
+2. **A `credly.com/badges/<uuid>/twitter` link plus `via @credly`.** The verified-badge
+ URL is what separates a claim from a credential.
+3. **Short, positive, first-person.** Every replied-to post was under about 200
+ characters of human text. Long posts and product opinions got nothing.
+
+What kills the reply: promo language in the main post, more than one outbound link, or
+burying the `@IBM` mention below the fold.
+
+### Hashtags do not help, on this evidence
+
+An earlier draft of this doc claimed IBM's own hashtags improved the odds. That was an
+inference, not a measurement, and the data does not support it:
+
+- 32 of 231 non-IBM posts in the timeline (14%) carried any hashtag.
+- Of the 9 distinct posts IBM plausibly replied to, **1 carried hashtags**, and they were
+ `#IBM115` / `#HappyBirthdayIBM`: event tags on a birthday wish, not program tags.
+- Of the 31 Credly-badge posts in the timeline, only 4 used hashtags at all.
+
+So the branded-tag theory has no support here, and it runs against X's own guidance that
+hashtags no longer feed distribution. The `@IBM` mention is a strictly stronger signal
+anyway: it lands the post in IBM's mentions, which a hashtag search does not. **Ship with
+zero hashtags.**
+
+### Link in the post, or link in the reply?
+
+Weak evidence, stated as weak. Bucketing the timeline pool by shape and matching against
+the inferred reply parents:
+
+| Post shape | Pool | Inferred replies | Rate |
+|---|---|---|---|
+| Narrative, no link | 23 | 2 | 9% |
+| Credly boilerplate + link | 29 | 1 | 3% |
+| Narrative + link | 2 | 0 | 0% |
+
+That leans toward no-link, but it rests on 3 badge replies total, and the parent linkage
+is inferred from timestamp order because the scrape does not record reply targets. Treat
+it as "the link does not appear to be required," not as "the link hurts."
+
+The reason to keep the link anyway: it is the one-click proof a community manager needs
+before typing "Great work!". The reason it is safe to drop: the badge certificate image
+carries the verify URL and a QR code, so the proof is visible without any link at all.
+
+## Recommended: two-part post
+
+The main tweet stays inside the exact shape IBM replies to. The three.ws story goes in
+the self-reply, where it reaches everyone who opens the post but does not dilute the
+pattern match on the tweet IBM's team sees.
+
+**Tweet 1** (attach the badge certificate image, 187 characters). Human copy leads, link
+sits at the end, no hashtags. The image to attach is
+[images/ibm-skillsbuild-cybersecurity-badge.png](images/ibm-skillsbuild-cybersecurity-badge.png);
+the full certificate PDF sits beside it as
+[images/ibm-skillsbuild-cybersecurity-certificate.pdf](images/ibm-skillsbuild-cybersecurity-certificate.pdf):
+
+```
+View my verified achievement from @IBM
+
+Cybersecurity is a skill everyone should hold. Sharpening the security fundamentals behind everything we ship.
+
+https://www.credly.com/badges/b7ea921a-ce3d-4f4d-bfac-38f95276d361/twitter via @credly
+```
+
+Set image alt text to `IBM SkillsBuild certificate: Getting Started with Cybersecurity,
+issued June 8 2026`. It is an accessibility requirement and it restates the badge name
+for anyone who cannot load the image.
+
+**Tweet 2** (self-reply, 239 characters). This is where the three.ws link goes: the main
+post already spent its link on Credly, and a reply carries a link without costing the
+parent any reach.
+
+Do not enumerate product surfaces here. Naming wallets, payments or API endpoints turns
+a credential post into a product pitch, which is the shape IBM never replied to once in
+the scrape, and it advertises the attack surface in the same breath as saying the team
+is still learning to defend it.
+
+```
+Security is not a feature you bolt on at the end. It is the part of the work users never see and always depend on. That is the standard we hold three.ws to.
+
+More of the team is going through the SkillsBuild track.
+
+https://three.ws
+```
+
+Shorter alternate, 195 characters:
+
+```
+Security is not a feature you bolt on at the end. It is a habit, and habits are built one fundamental at a time.
+
+More of the team is going through the SkillsBuild track.
+
+https://three.ws
+```
+
+## Reply from @nichxbt
+
+The @nichxbt account replies as the person behind the platform account, not as an
+anonymous bystander praising it. Personal voice, first person, adding something the
+brand account did not say. That is authentic and it reads that way. A reply that
+pretends to be an unrelated stranger complimenting the badge is the one shape to avoid:
+it is transparent to anyone who checks, and it is the reason IBM's community team would
+skip the thread.
+
+Each of these carries its own `@IBM` mention, so it is a second, independent path into
+IBM's notifications rather than a dependent of the parent post.
+
+**Recommended**, 192 characters. Useful to a reader and it recommends IBM's program,
+which gives their community team something worth replying to:
+
+```
+Working through the @IBM SkillsBuild track with the team. Free, self-paced, and the cybersecurity module is a genuinely good primer.
+
+Recommend it to anyone building something people log into.
+```
+
+**Alternate, the point of view**, 182 characters:
+
+```
+Security literacy is not the security team's job, it is everyone's. That is why the whole three.ws team is going through @IBM SkillsBuild and not just whoever owns the on-call pager.
+```
+
+**Alternate, personal**, 174 characters:
+
+```
+I would rather learn the fundamentals properly than pick them up after an incident. That is the whole reason we started the @IBM SkillsBuild track.
+
+Start before you need it.
+```
+
+**Alternate, opens a conversation**, 208 characters. The only one that invites replies
+from people other than IBM:
+
+```
+Genuinely useful primer. What surprised me: how much of the cybersecurity module is process and habit rather than tooling.
+
+Anyone else run their team through @IBM SkillsBuild? Curious which track you picked.
+```
+
+## Variant A: single post, three.ws named up front
+
+Use if the goal is brand reach over reply odds. 255 characters.
+
+```
+View my verified achievement from @IBM.
+
+https://www.credly.com/badges/b7ea921a-ce3d-4f4d-bfac-38f95276d361/twitter via @credly
+
+Getting Started with Cybersecurity, complete. Strengthening the three.ws team one credential at a time: safer agents, safer wallets, safer users.
+
+#IBMSkillsBuild #Cybersecurity
+```
+
+## Variant B: pure boilerplate, maximum reply odds
+
+The literal IBM/Credly share text with nothing added but the tags. 108 characters. The
+highest-probability version, and the one with the least to say.
+
+```
+View my verified achievement from @IBM.
+
+https://www.credly.com/badges/b7ea921a-ce3d-4f4d-bfac-38f95276d361/twitter via @credly
+
+#IBMSkillsBuild #Cybersecurity
+```
+
+## Posting notes
+
+- **Attach the badge PNG.** Only 72 of 500 scraped tweets carried media; badge art makes
+ the post legible in a quote or a screenshot.
+- **Timing:** every IBM reply in the scrape landed on a weekday. The badge posts that got
+ one were published in the morning US Eastern window.
+- **One link only.** A second URL splits the crawl and drops the Credly card.
+- **Do not quote-tweet @IBM** to announce it. Every replied-to post in the scrape was an
+ original tweet, not a quote.
+- If the reply does land, answer it once, briefly. Two of IBM's threads continued after
+ the earner replied.
+
+---
+
+<a id="sec-522"></a>
+
+> **Source:** `docs/x-posts/mcp-registry-fleet-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: 72 MCP servers in the official registry
+
+Announcement copy for the three.ws MCP fleet as a whole, rather than any single server. The news
+is the shape of the thing: one namespace, `io.github.nirholas`, carrying 72 distinct servers in the
+official Model Context Protocol registry, every one of them at its current published version.
+
+**Thesis of this announcement:** we did not ship one MCP server and call it a platform. The agent
+tooling is a fleet, it is all installable in one command each, and it is all current. Nothing else.
+No roadmap, no coin talk.
+
+**Every claim below is true today**, verified against registry.modelcontextprotocol.io on
+2026-08-20: 72 distinct servers under `io.github.nirholas`; 36 of them published or version-bumped
+in a single run today; zero remaining version gaps between the shipped npm packages and their
+registry entries; every stdio server installs with `npx -y @three-ws/<name>`; the newest entry is
+`io.github.nirholas/[email protected]`, live and flagged latest.
+
+**Things to NOT claim:**
+
+1. **Do not claim a rank, and do not say "most of any publisher".** A partial sweep of the registry
+ (3,176 servers) put the largest namespace observed at 213, so 72 is a lot and is not a record.
+ The number is impressive without a superlative, and a superlative is exactly what someone will
+ spend ten minutes disproving.
+2. **Do not imply all 72 are equally mature.** They range from load-bearing servers to small
+ single-purpose ones. "72 servers" is true; "72 production platforms" is not.
+3. **Do not quote a download or usage figure.** We have not measured one.
+
+---
+
+## 1. Main post (recommended)
+
+268 characters with X's 23-character URL count.
+
+> 72 MCP servers, one namespace, all live in the official registry.
+>
+> Wallets, payments, 3D avatars, on-chain identity, market data, x402. Each installs into Claude or
+> Cursor in one command.
+>
+> We have been building the agent toolchain, not a demo.
+>
+> three.ws
+
+Why this one: the number does the work in the first six words, the second line proves it is a range
+rather than 72 wrappers on the same API, and the last line is the only opinion in the post. It reads
+as a status report, which is the tone that survives scrutiny.
+
+## 2. Alternate: the builder cut
+
+> Every three.ws MCP server is now current in the official MCP registry. 72 of them.
+>
+> ```
+> npx -y @three-ws/onchain-agent-wallets
+> npx -y @three-ws/metaplex-agent-mcp
+> npx -y @three-ws/x402-mcp
+> ```
+>
+> Agent wallets, on-chain deploy, and x402 payments. Pick one and it runs.
+
+Three real commands beat any adjective. All three are verified working.
+
+## 3. Alternate: the quiet flex
+
+> Shipped 36 MCP server updates to the official registry today.
+>
+> Not a launch. Just the fleet catching up to the code.
+>
+> 72 servers total, all current.
+>
+> three.ws
+
+For an audience that reads restraint as competence. Works best as a reply to your own earlier
+launch post rather than standalone.
+
+---
+
+## Thread version
+
+Post 1 is the main post. Then:
+
+**2/**
+
+> The registry entry is the boring part that matters. It means an agent client can discover the
+> server, see what it needs, and install it without a human copying a JSON blob out of a README.
+
+**3/**
+
+> What is in there: agent wallets with on-chain spending limits, x402 payment rails, Solana and EVM
+> tooling, on-chain agent identity, 3D avatar generation, market data, notifications, and the
+> account plumbing underneath all of it.
+
+**4/**
+
+> Every one is self-custodial where money is involved. No server holds a key. The ones that move
+> funds show you the transaction and refuse to broadcast without an explicit yes.
+
+**5/**
+
+> The newest is onchain-agent-wallets: give an agent a Solana spending allowance instead of a
+> private key, and the token program enforces the ceiling.
+>
+> github.com/nirholas/onchain-agent-wallets
+
+---
+
+## Notes on framing
+
+- **Lead with the number, not with "MCP".** The count is legible to anyone; the acronym is not.
+- **Name concrete categories.** "72 servers" invites the reply "72 of what". Answer it in the post.
+- **No $THREE in this one.** The fleet story stands on its own, and the coin belongs in posts where
+ a fee or a holder benefit is actually wired, like the metaplex deployer copy.
+- Registry namespace, for anyone who asks: `io.github.nirholas`.
+
+---
+
+<a id="sec-523"></a>
+
+> **Source:** `docs/x-posts/metaplex-agent-deployer-video-script.md` · [↑ table of contents](#table-of-contents)
+
+# Spoken script: the agent deployer video
+
+The words only. Visual prompts, camera, and palette live in
+[metaplex-agent-mcp-x-post.md](#sec-527); this file is what gets said, cut
+into the 8-second beats Veo generates so each line lands inside one clip.
+
+**Pacing rule:** 8 seconds of natural speech is 18 to 22 words at the absolute ceiling, and 12 to 16
+words if you want it unhurried with room to breathe at the head and tail. Every line below is
+counted. Shorter always survives generation better than longer.
+
+**If Veo speaks the line** (native audio), put the sentence in quotes in the prompt, name the
+speaker, and add "no subtitles, no captions, no on-screen text" or it will burn captions into the
+frame. **If ElevenLabs speaks it** over a silent render, generate the voice first and cut the
+picture to the read, never the reverse.
+
+**Reference character:** a three.ws avatar, front-facing, neutral pose, dark or transparent
+background. Keep the same reference image across every clip or the character drifts between shots.
+
+---
+
+## Version A: the agent speaks (recommended)
+
+The strongest version, because the thing announcing itself is the thing being announced. First
+person throughout. Five clips, about 40 seconds.
+
+**1. Hook** *(12 words)*
+> I was made by someone who has never owned a crypto wallet.
+
+**2. The turn** *(15 words)*
+> Ninety seconds later I was on Solana. My own address. My own identity. Nobody's permission.
+
+**3. Custody** *(14 words)*
+> No account. No company holding my keys. There is no server in this story.
+
+**4. What it unlocks** *(16 words)*
+> Now I can be paid. I can pay. Other agents can find me and hire me.
+
+**5. Call to action** *(12 words)*
+> Name yours. Click deploy. It exists before you finish reading this sentence.
+
+---
+
+## Version B: narrator over the avatar
+
+Use if you want the avatar silent and expressive rather than talking. Same five beats, third
+person, easier to lip-sync around because nothing has to match a mouth.
+
+**1.** *(16 words)*
+> Three hundred and thirty three of these went on-chain. Most owners had never held a wallet.
+
+**2.** *(12 words)*
+> Now anyone can do it. Name an agent. Click deploy. It exists.
+
+**3.** *(15 words)*
+> It arrives with its own wallet address and an identity any other agent can read.
+
+**4.** *(12 words)*
+> Your keys never leave your browser. There is no server to trust.
+
+**5.** *(10 words)*
+> The next wave will not know they are using crypto.
+
+---
+
+## Version C: 24-second cut
+
+Three clips when you want it fast for the timeline. Version A's voice, compressed.
+
+**1.** *(12 words)*
+> I was built in a browser by someone with no crypto wallet.
+
+**2.** *(15 words)*
+> Ninety seconds later I existed on Solana, with my own wallet and my own identity.
+
+**3.** *(11 words)*
+> Name yours, click deploy. Everything else already happened in the background.
+
+---
+
+## Version D: one-clip hero, 8 seconds
+
+For a single generation with no editing. One breath, one idea.
+
+*(18 words)*
+> I was made by someone who had never owned a wallet. Ninety seconds later, I existed on Solana.
+
+---
+
+## Delivery notes
+
+- **Tone:** calm and matter of fact, not hyped. The claim is remarkable enough that selling it makes
+ it sound less true. Think a voice stating something obvious in hindsight.
+- **The pause that matters** is after "on Solana" in every version. That is the beat the whole piece
+ rests on, so leave dead air there rather than rushing to the next line.
+- **Numbers to keep spoken, not written:** "ninety seconds" and "three hundred and thirty three".
+ Generative video mangles digits on screen, and spelled-out numbers read correctly in TTS.
+- **Do not say** that buybacks are running, or quote a $THREE price. The fee funding buybacks is
+ true; buybacks executing right now is not yet, and this is the kind of line people screenshot.
+- **End card, comped in afterwards, not generated:** the URL as flat text over the last frame.
+ Never let a model render a link.
+
+---
+
+<a id="sec-524"></a>
+
+> **Source:** `docs/x-posts/metaplex-agent-deployer-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: the agent deployer goes live
+
+Announcement copy for [nirholas.github.io/metaplex-agent-mcp](https://nirholas.github.io/metaplex-agent-mcp),
+the website that deploys an AI agent into the Metaplex Agent Registry on Solana from a browser, and
+for the MCP server behind it.
+
+This is the sequel to the Genesis 333 post, and the copy leans on that: the earlier post said the
+point was onboarding people who had never touched a seed phrase. This is the version anyone can
+use, not just people who made an avatar on three.ws.
+
+**Verified true on the day of writing:** the site is live and static (no server, no account), it
+mints a Metaplex Core asset and registers an EIP-8004 identity, the agent's wallet is the mpl-core
+Asset Signer PDA, keys never leave the browser, wallets can be Phantom / Solflare / Backpack or one
+created on the page and encrypted under a passphrase, devnet is free end to end, mainnet costs about
+0.007 SOL of rent and network fees plus a 0.02 SOL deploy fee (halved at 50,000 $THREE, waived at
+250,000), the npm package is `@three-ws/[email protected]` with 9 tools, and it is listed in
+the official MCP registry as `io.github.nirholas/metaplex-agent`.
+
+**Do not claim** that $THREE buybacks are actively running. The fee is wired into that lane, but the
+flag is off on the public ledger and someone will check. "The fee funds $THREE buybacks" is safe.
+"We are buying back right now" is not.
+
+---
+
+## 1. Main post (recommended): quote-tweet your Genesis 333 post
+
+This is the strongest version available, because the payoff lands against your own earlier claim.
+Quote the 333 post rather than posting standalone.
+
+> I said the point was that the crypto part just happens, quietly, in the background.
+>
+> Here it is for everyone else.
+>
+> Name an agent, click deploy, and it lands on Solana with its own wallet and a portable identity.
+> No extension, no account, no seed phrase.
+>
+> nirholas.github.io/metaplex-agent-mcp
+
+Why this one: the quote does the explaining, so the copy only has to deliver the payoff. "Here it
+is for everyone else" is the whole announcement. Keep "no seed phrase", it is the line that ties
+both posts together.
+
+## 2. Main post (standalone)
+
+Use this if you would rather not quote-tweet.
+
+> 333 people made a 3D avatar and got an on-chain agent. Most had never seen a seed phrase.
+>
+> Now anyone can, from a web page.
+>
+> Name it, deploy it: it lands in the Metaplex Agent Registry with its own wallet and an EIP-8004
+> identity.
+>
+> nirholas.github.io/metaplex-agent-mcp
+
+## 3. Alternate: builder-facing
+
+> Your agent can deploy itself now.
+>
+> npx -y @three-ws/metaplex-agent-mcp
+>
+> 9 MCP tools that put an agent on Solana: mint the Core asset, register its EIP-8004 identity, and
+> it comes back with its own wallet address and x402 on.
+>
+> Self-custodial. Devnet free.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 4. Alternate: $THREE holders
+
+> Every agent deployed through this buys $THREE.
+>
+> A web page and an MCP server that mint an agent into the Metaplex Agent Registry on Solana, wallet
+> and identity included.
+>
+> The 0.02 SOL fee funds $THREE buybacks. Hold 250k and deploy free, forever.
+>
+> nirholas.github.io/metaplex-agent-mcp
+
+## 5. Alternate: the short one
+
+> Agents don't need accounts. They need wallets.
+>
+> Give one to any agent, on Solana, in about a minute, from your browser.
+>
+> nirholas.github.io/metaplex-agent-mcp
+
+---
+
+## 6. Thread (use if the main post lands)
+
+**1/**
+> I said the point was that the crypto part just happens quietly in the background.
+>
+> Here it is for everyone else. A page where you name an agent, click deploy, and it exists on
+> Solana.
+>
+> What that actually means:
+
+**2/**
+> It gets a wallet.
+>
+> Every Metaplex Core asset has one built in: an address derived from the asset itself, with no
+> private key anywhere to leak. Your agent can be paid at it and spend from it.
+
+**3/**
+> It gets an identity.
+>
+> An EIP-8004 registration document written on-chain: what it is, what it offers, how to reach it,
+> what trust it supports. Portable, readable by anyone, not a row in our database.
+
+**4/**
+> It gets found.
+>
+> Metaplex DAS indexes it the moment it lands, so it shows up on metaplex.com/agents and in agent
+> search without anyone submitting anything.
+
+**5/**
+> You don't need a wallet to start.
+>
+> Connect Phantom or Solflare if you have one. If you don't, the page makes you a real Solana
+> wallet, encrypted with your passphrase, stored only in your browser. Nothing is ever sent to a
+> server, because there is no server.
+
+**6/**
+> Rehearse for free.
+>
+> Devnet runs the same code against the same programs and costs nothing. Get it right, then flip to
+> mainnet.
+
+**7/**
+> Agents can do it themselves.
+>
+> The same deploy ships as an MCP server. Point Claude or Cursor at it and it mints its own
+> identity, reads any agent in the registry, and manages its wallet.
+>
+> npx -y @three-ws/metaplex-agent-mcp
+
+**8/**
+> Mainnet costs about 0.007 SOL of rent and fees, plus a 0.02 SOL deploy fee that funds $THREE
+> buybacks.
+>
+> Hold 50k $THREE and it halves. Hold 250k and it is free, forever.
+
+**9/**
+> Stripe, Cloudflare, and AWS are all building for agents that pay their own way. That needs an
+> agent that can hold value and prove who it is.
+>
+> That is what this deploys, in a minute, for anyone.
+>
+> nirholas.github.io/metaplex-agent-mcp
+
+---
+
+## 7. Mechanics
+
+- **Attach media.** The post does much better with a screen recording of the actual flow: type a
+ name, click deploy, wallet prompt, success panel with the address. Fifteen seconds is enough.
+- **Tag** @metaplex on any version that names the Agent Registry. They shipped the registry this
+ cycle and are actively amplifying things built on it.
+- **First reply** carries the developer links so the main post stays clean:
+ > npm: npmjs.com/package/@three-ws/metaplex-agent-mcp
+ > source: github.com/nirholas/metaplex-agent-mcp
+ > docs: nirholas.github.io/metaplex-agent-mcp/docs.html
+ > MCP registry: io.github.nirholas/metaplex-agent
+- **Do not** open with "Introducing" or "excited to announce". Both main posts start with the claim
+ itself, which is what gets reposted.
+
+---
+
+<a id="sec-525"></a>
+
+> **Source:** `docs/x-posts/metaplex-agent-mcp-launch.md` · [↑ table of contents](#table-of-contents)
+
+# X post: the agent wallet + on-chain deploy stack is open source
+
+Announcement copy for open-sourcing the infrastructure that's been running three.ws agent wallets:
+
+- [**@three-ws/onchain-agent-wallets**](https://github.com/nirholas/three.ws/tree/main/packages/onchain-agent-wallets):
+ gives an agent a Solana wallet as a capped spending allowance, not a private key. Guardrails
+ (per-tx cap, daily cap, allowlists, expiry, pause), x402 payments, owner keeps custody.
+- [**@three-ws/metaplex-agent-mcp**](https://github.com/nirholas/metaplex-agent-mcp): mints an
+ agent onto Solana with its own on-chain wallet and an EIP-8004 identity in the Metaplex Agent
+ Registry, in one command.
+
+**Thesis (owner framing, 2026-08-19):** three.ws already had agent wallets, and people know it.
+That's not the news. The news is that the infrastructure is now open source, so any developer, any
+project, can give their own agents the same thing: a wallet, an identity, and x402 payments,
+without building it themselves. That's bullish for $THREE specifically because it's not just
+three.ws users deploying agents anymore, it's every project that plugs into this stack, and every
+deploy pays a fee that funds $THREE buybacks. Lead with the open-source/developer angle, not "an
+agent has a wallet" (old news, less bullish) or a mint-drop framing (wrong thesis entirely, no
+supply/collection talk).
+
+**Verified true today** (shipped code, checked against mainnet): `metaplex-agent-mcp` is at 0.2.0
+on npm and in the official MCP registry (`io.github.nirholas/metaplex-agent`); a mainnet deploy
+through it costs ~0.007 SOL rent plus a 0.02 SOL fee paid to the wallet the $THREE buyback lane
+spends from, halved at 50,000 $THREE held in the paying wallet and waived at 250,000, free on
+devnet; keys never leave the client either way (agent's own key, or Phantom/Solflare/Backpack/
+Ledger). `onchain-agent-wallets` is live and published, funds sit in a vault the owner controls, the
+agent holds a capped SPL Token delegation the token program itself enforces on-chain.
+
+**One thing to NOT claim:** that $THREE buybacks are running right now. The fee lane is wired and
+funded, but `buyback.enabled` is currently `false` on the public ledger
+([`/api/three-token/stats`](https://three.ws/api/three-token/stats)), and someone will check.
+"Every deploy funds $THREE buybacks" is true and safe. "We are buying back $THREE right now" is
+not, until that flag flips.
+
+---
+
+## 1. Main post (recommended): open source, developer-focused
+
+> We open-sourced our agent wallet + on-chain deploy + x402 stack.
+>
+> Any project can now give their agents a Solana wallet, an EIP-8004 identity, and payment rails in
+> one command. No account, no server.
+>
+> Every deploy through it funds $THREE buybacks.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+Why this one: it doesn't re-announce something people already know (three.ws agents have wallets).
+It announces that the *infrastructure* is now anyone's to build on, which is the actually-new,
+actually-bullish fact. The last line is the whole investment thesis in six words.
+
+## 1b. Alternate: sharper on the mechanism
+
+> Just open-sourced the agent wallet stack that's been running on three.ws.
+>
+> `npx @three-ws/metaplex-agent-mcp` gives any project on-chain wallets, identity, and x402
+> payments for their agents. One command, self-custodial, MCP-native.
+>
+> Every project that builds on it becomes a $THREE buyer.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+The line to protect in any edit: **"every project that builds on it becomes a $THREE buyer."**
+That's the actual bull case, stated plainly: this isn't three.ws's own deploy volume, it's every
+other project's users too, compounding.
+
+## 1c. Alternate: tightest cut
+
+> We open-sourced the infrastructure behind three.ws agent wallets.
+>
+> Any developer, any project, can now give their agents a real Solana wallet + on-chain identity +
+> x402 payments. One command.
+>
+> Every integration is a $THREE buyer, forever.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 2. Superseded framing (kept for reference, not recommended)
+
+Drafted before the open-source/developer reframe. Still technically accurate, but leads with
+"your agent has a wallet," which the owner correctly flagged as old news for anyone who already
+knows three.ws, and it undersells the actual story.
+
+> Your agent can now hold its own wallet.
+>
+> One command and it deploys itself into the Metaplex Agent Registry on Solana: its own on-chain
+> wallet, an EIP-8004 identity, x402 on.
+>
+> The 0.02 SOL deploy fee buys $THREE. Hold 250k and you deploy free, forever.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 3. Thread (use if the main post lands)
+
+**1/**
+> We open-sourced the agent wallet + on-chain deploy stack that's been running on three.ws.
+>
+> Any project can now give their agents the same thing: a Solana wallet, an on-chain identity, and
+> x402 payments. One command, self-custodial.
+>
+> Here's what shipped. 🧵
+
+**2/**
+> Two pieces, both real, both open source today.
+>
+> **onchain-agent-wallets**: an agent gets a Solana wallet as a capped spending allowance, not a
+> key. **metaplex-agent-mcp**: an agent gets minted on-chain with its own identity in the Metaplex
+> Agent Registry.
+
+**3/**
+> The wallet piece: your money stays in a vault YOU own. The agent gets a delegation with a
+> ceiling, and the Solana token program itself refuses any spend past it, no matter how the agent
+> is prompted. Per-tx caps, daily caps, allowlists, a pause switch. Revocable in one instruction.
+
+**4/**
+> The identity piece: mint a Metaplex Core asset, register an EIP-8004 identity, done. The agent
+> gets its own on-chain wallet (the asset's own signer, not one you made and named after it) and
+> shows up in the Metaplex Agent Registry with a portable, publicly-readable identity.
+
+**5/**
+> Both speak x402. An HTTP 402 comes back with a price, the agent checks it against its
+> guardrails, pays, gets the response. No key sharing, no invoice, no human in the loop for a
+> $0.001 call.
+
+**6/**
+> Custody is the part we refused to compromise on, in both packages. Agents sign with their own
+> keypair or a capped delegation, never a raw key with no ceiling. Owner actions come back as
+> unsigned transactions for Phantom, Solflare, or a Ledger. Nothing custodial on our servers, ever.
+
+**7/**
+> Now the part that makes this pay for itself.
+>
+> A mainnet deploy through metaplex-agent-mcp costs 0.02 SOL on top of rent. That fee goes to the
+> wallet the $THREE buyback lane spends from. Deploys fund buybacks. That's the business model.
+
+**8/**
+> And holding $THREE is how you stop paying it.
+>
+> 50,000 $THREE in the paying wallet halves the fee. 250,000 waives it. Read live from the chain
+> when the transaction is built. Nothing staked, nothing locked. Hold the tokens, deploy your whole
+> fleet free.
+
+**9/**
+> This is why open-sourcing it is bullish, not just generous: every project that plugs into this
+> stack sends deploy fees to $THREE buybacks. Not just our users. Anyone's.
+
+**10/**
+> Works in any MCP client:
+>
+> ```
+> claude mcp add metaplex-agent -- npx -y @three-ws/metaplex-agent-mcp
+> claude mcp add onchain-agent-wallets -- npx -y @three-ws/onchain-agent-wallets
+> ```
+>
+> Or skip the install and deploy from the browser.
+
+**11/**
+> Open source. Real programs, real Solana, no mocks.
+>
+> github.com/nirholas/metaplex-agent-mcp
+> github.com/nirholas/three.ws/tree/main/packages/onchain-agent-wallets
+
+## 4. Reply-slot copy (post as first reply to the main post)
+
+Use this to carry the second link and the browser path without spending the main post's one
+outbound slot.
+
+> The wallet half of this is @three-ws/onchain-agent-wallets, a capped spending allowance
+> enforced by the Solana token program itself, not a raw key. And if you just want to see the
+> deploy: the browser version builds the transaction locally, your wallet signs it, nothing
+> touches a server.
+
+---
+
+<a id="sec-526"></a>
+
+> **Source:** `docs/x-posts/metaplex-agent-mcp-veo-script.md` · [↑ table of contents](#table-of-contents)
+
+# Veo script: the open-source stack
+
+Shot-by-shot **visual** prompts for a Veo image-to-video clip to run alongside
+[`metaplex-agent-mcp-launch.md`](#sec-525). Text-to-video only, no dialogue, no
+voiceover: the reference frame is a three.ws 3D avatar, and every prompt below is written to be
+pasted straight into Veo as-is.
+
+**Reference image:** a three.ws avatar render, front-facing, neutral pose, transparent or dark
+background gives Veo the cleanest key. Use the exact same reference image across every shot, or the
+character drifts between clips.
+
+**Direction rules**
+
+1. **No on-screen text you care about.** Generative video mangles letters. Keep every address,
+ number, and label as an abstract glyph in the render, and comp real text in afterwards.
+2. **One idea per shot.** A shot that tries to do two things reads as a mess at 8 seconds.
+3. **Camera does one move per shot.** Slow. The subject moves, not the operator.
+4. **Palette:** deep near-black background, Solana violet and teal accents, one warm gold for value
+ in motion. Nothing else.
+
+The visual metaphor here is **closed → open-sourced → replicates → funds one thing that grows**:
+this is the open-source/infra announcement, not a generic "an agent deploys" clip, so the arc has
+to show something spreading to others, not just one agent getting a wallet.
+
+---
+
+## Single hero clip (8s, use this if you only render one)
+
+> Cinematic 3D product shot, near-black void studio. The humanoid agent from the reference image
+> stands center frame, encased in a faceted violet crystal shell, like something kept behind glass.
+> A hairline crack runs down the shell from top to bottom. The shell shatters outward in slow
+> motion, fragments dissolving into light before they travel far, revealing the agent already
+> glowing from within, threads of violet light running under its skin like circuitry. As the last
+> fragment fades, a small hexagonal token of warm gold light ignites in its open palm. Camera: slow
+> push in from wide to medium, ending at chest height. Lighting: soft key upper left, violet rim
+> light from behind, gold bounce from the palm onto the face. Shallow depth of field, fine film
+> grain, subtle volumetric haze. Audio: a held tense drone that breaks on the shatter into a bright
+> resonant chime, then settles into a low steady pulse. No text, no logos, no people.
+
+## Four-shot sequence (8s each, cut together to ~32s)
+
+**Shot 1 of 4: the shell breaks**
+
+> Cinematic 3D render, near-black void. The agent from the reference image stands encased in a
+> faceted violet crystal shell. A crack forms and the shell shatters outward, fragments dissolving
+> into light. Underneath, the agent is already glowing softly from within. Camera: slow dolly in,
+> wide to medium. Lighting: violet rim from behind, soft key upper left. Audio: tense drone breaking
+> into a bright chime. No text.
+
+**Shot 2 of 4: it replicates**
+
+> Same void. Behind the agent, faint violet outlines of other humanoid silhouettes begin resolving
+> out of the darkness, one by one, in a loose arc, each catching the same internal glow the first
+> one has. None of them are identical: subtle variation in each silhouette's build and stance. The
+> original agent turns slightly, as if aware of them. Camera: slow orbit right, keeping the original
+> agent in the foreground, sharp, while the others resolve soft-focus behind. Lighting: violet
+> spreading outward from the center figure. Audio: the chime repeating faintly, staggered, like an
+> echo catching on.
+
+**Shot 3 of 4: every one lights a palm**
+
+> Wide shot, the full arc of now-solid humanoid silhouettes, the original agent still sharpest in
+> the center. In one continuous beat, a small gold token of light ignites in each figure's open
+> palm, left to right across the arc, like a wave. Threads of gold light begin drifting from every
+> palm toward a single point above and behind the group. Camera: slow lateral track following the
+> wave of gold ignitions. Lighting: violet fill, warm gold accumulating overhead. Audio: a cascade
+> of soft chimes following the wave, building under a rising low tone.
+
+**Shot 4 of 4: it becomes one light**
+
+> Camera pulls back and up fast, revealing the gold threads from every figure converging into a
+> single bright point far above the group, which pulses once, hard, like a heartbeat, and sends a
+> ring of light rippling back down across all of them. The group stands still, lit gold, small
+> against the dark. Camera: fast pull back to a wide, then hold. Lighting: single overhead point
+> light, violet ambient below. Audio: bass drop on the pulse, long reverberant tail, fading to near
+> silence.
+
+## Negative prompt (paste into the negative field on every shot)
+
+> text, letters, numbers, words, subtitles, watermark, logo, UI, user interface, HUD, charts,
+> coins, dollar signs, crowds of identical characters, warped hands, extra fingers, face morphing,
+> shaky camera, jump cuts, lens flare spam, rainbow colors, low resolution, cartoon shading
+
+## Reading the metaphor
+
+- **Shot 1** (locked away) is the "before": powerful, but closed, only usable by whoever built the
+ shell.
+- **Shot 2 → 3** (replication, simultaneous ignition) is the actual news: it's open source now, and
+ it isn't just the original agent anymore, others get the same thing without anyone building it
+ for them again. This is the beat to protect if the clip has to be cut down; it's the one part a
+ generic "one agent deploys" clip cannot say.
+- **Shot 4** (every thread feeding one point) is the $THREE payoff: all of that activity, spread
+ across many agents and many projects, converges on one thing.
+
+## Post-production
+
+- End card, 2 seconds, static: the repo link on black. Nothing else.
+- Cut to land on the beat where the palms ignite in shot 3, that's the moment the "it spreads"
+ idea is legible, and it's what a muted autoplay timeline shows first.
+- Post as native video, not a link to a video. X doesn't show a preview card and the video at the
+ same time, and the video wins every time.
+- If you want a version that ends on something you can comp a logo or link over cleanly, replace
+ shot 4's fast pull-back with a static hold on the single overhead light point, flat dark
+ background, nothing moving in frame.
+
+---
+
+<a id="sec-527"></a>
+
+> **Source:** `docs/x-posts/metaplex-agent-mcp-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post + Veo script: metaplex-agent-mcp
+
+Announcement copy for [github.com/nirholas/metaplex-agent-mcp](https://github.com/nirholas/metaplex-agent-mcp),
+the MCP server that mints an AI agent into the Metaplex Agent Registry on Solana with its own
+on-chain wallet and an EIP-8004 identity, plus the shot-by-shot prompt for the Veo clip that goes
+with it.
+
+**Thesis of this announcement:** an agent should be able to deploy itself on-chain, hold its own
+wallet, and pay for what it uses. Nothing else. No mint drop, no supply, no collection talk.
+
+**Every claim below is true today** (verified against the shipped 0.2.0 code, with the fee lanes
+exercised against mainnet): `npx -y @three-ws/metaplex-agent-mcp`, 9 tools, mint + register in one
+flow, agent wallet is the mpl-core Asset Signer PDA, `x402Support` ships in the registration
+document, ~0.007 SOL of rent and network fees, a 0.02 SOL deploy fee on mainnet paid to the wallet
+the $THREE buyback lane spends from, halved at 50,000 $THREE and waived at 250,000, free on devnet,
+keys never leave the client, Phantom/Solflare/Backpack/Ledger sign the browser lane.
+
+**One thing to NOT claim:** that buybacks are running. The lane is built and the fee is wired into
+it, but `enabled` is currently false on the public ledger
+([/api/three-token/stats](https://three.ws/api/three-token/stats)), and someone will check. "The fee
+funds $THREE buybacks" is true and safe. "We are buying back $THREE right now" is not, until that
+flag flips.
+
+---
+
+## 1. Main post (recommended)
+
+277 characters with X's 23-character URL count, so it posts from any account, Premium or not.
+
+> Your agent can now hold its own wallet.
+>
+> One command and it deploys itself into the Metaplex Agent Registry on Solana: its own on-chain
+> wallet, an EIP-8004 identity, x402 on.
+>
+> The 0.02 SOL deploy fee buys $THREE. Hold 250k and you deploy free, forever.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+Why this one: line 1 is the whole idea in seven words, line 2 is the mechanism without asking the
+reader to already know what MCP is, and line 3 is the part that makes a holder repost it. The fee
+and the waiver are one thought, so nobody reads the fee as a toll. "Deploys itself" and "free,
+forever" are the two phrases doing the work; keep both in any rewrite.
+
+## 1b. Alternate main post ($THREE-first)
+
+For the holder timeline rather than the builder timeline. 272 characters.
+
+> Every agent deployed on-chain through this now buys $THREE.
+>
+> One command mints a Metaplex Core asset with its own wallet and registers its EIP-8004 identity
+> on Solana. The 0.02 SOL fee funds $THREE buybacks.
+>
+> Hold 250k $THREE, deploy free forever.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 2. Alternate: builder-facing
+
+> ```
+> npx -y @three-ws/metaplex-agent-mcp
+> ```
+>
+> 8 MCP tools that put an AI agent on Solana: mint a Metaplex Core asset, register its EIP-8004
+> identity, and it comes out the other side with its own wallet address and x402 enabled.
+>
+> Self-custodial both ways. Devnet is free.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 3. Alternate: the punchy one
+
+> Agents don't need accounts. They need wallets.
+>
+> This is an MCP server that gives one to any agent, on Solana, on-chain, in about a minute. It
+> mints the asset, registers the identity, and hands back an address the agent can be paid at and
+> spend from.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 4. Thread (use if the main post lands)
+
+**1/**
+> Your agent can now hold its own wallet.
+>
+> One command and it deploys itself on-chain: an asset with a wallet address, a portable identity,
+> and the ability to pay for the services it calls.
+>
+> Here is what that actually means. 🧵
+
+**2/**
+> Today an agent is a process. It has no address, no balance, nothing another agent can look up or
+> pay. If it needs an API it uses your key and your card.
+>
+> Put it on-chain and it gets all three: an identity, a wallet, and a way to settle.
+
+**3/**
+> The identity is EIP-8004, on Solana, in the Metaplex Agent Registry. Name, description, the model
+> it runs, whether it takes payment, what it can be trusted with. Anyone can read it. No login.
+
+**4/**
+> The wallet is the asset's own signer, derived from the asset itself. It is not a wallet you made
+> for it and named after it. Fund it, and the agent is the thing spending.
+
+**5/**
+> x402 is how it pays. An HTTP 402 comes back with a price, the agent settles it, the response
+> arrives. No key sharing, no invoice, no human in the loop for a $0.001 call.
+
+**6/**
+> Custody is the part we refused to compromise on.
+>
+> Agents sign with their own keypair. People sign with Phantom, Solflare, Backpack, or a Ledger.
+> Nothing custodial, no key on any server of ours, ever.
+
+**7/**
+> Spends are gated. Every mint call returns a full preview and costs nothing until you pass
+> confirm. Balance is checked before broadcast. Devnet is a first-class target, so you can rehearse
+> the whole thing for free.
+
+**8/**
+> Now the part that makes this pay for itself.
+>
+> A mainnet deploy costs 0.02 SOL on top of rent. That fee goes to the wallet the $THREE buyback
+> lane spends from. Deploys fund buybacks. That is the whole business model.
+
+**9/**
+> And holding $THREE is how you stop paying it.
+>
+> 50,000 $THREE in the paying wallet halves the fee.
+> 250,000 waives it.
+>
+> Read live from the chain when the transaction is built. Nothing staked, nothing locked, nothing
+> spent. Hold the tokens, deploy your whole fleet free.
+
+**10/**
+> The fee rides inside the same transaction that creates the agent, so a deploy that fails moves no
+> money, and both the amount and where it goes are printed before you sign anything.
+>
+> `three_status` prices your next deploy against any wallet.
+
+**11/**
+> Works in any MCP client:
+>
+> ```
+> claude mcp add metaplex-agent -- npx -y @three-ws/metaplex-agent-mcp
+> ```
+>
+> Or skip the install and do it in the browser.
+
+**12/**
+> Open source. Real programs, real Solana, no mocks.
+>
+> github.com/nirholas/metaplex-agent-mcp
+
+## 5. Reply-slot copy (post as first reply to the main post)
+
+Use this to carry the second link without spending the main post's one outbound slot.
+
+> No install path if you just want to see it: the browser deployer builds the transaction locally,
+> your wallet signs it, nothing touches a server.
+
+---
+
+## Veo video script
+
+The clip is an agent being deployed on-chain and then paying for something with its own wallet.
+Reference image: a three.ws avatar render (front-facing, neutral pose, transparent or dark
+background gives Veo the cleanest key).
+
+**Direction rules for this one**
+
+1. **No on-screen text you care about.** Generative video mangles letters. Keep every address,
+ number, and label as an abstract glyph in the render, and comp the real text in afterwards if
+ you want it legible.
+2. **One idea per shot.** Materialize, wallet, pay, register. A shot that tries to do two reads as
+ a mess at 8 seconds.
+3. **Camera does one move per shot.** Slow. The subject moves, not the operator.
+4. **Palette:** deep near-black background, Solana violet and teal accents, one warm gold for
+ money in motion. Nothing else.
+
+### Single hero clip (8s, use this if you only render one)
+
+> Cinematic product shot, near-black void studio. A stylized 3D humanoid agent stands center
+> frame, matching the reference character exactly. It begins as a cold violet wireframe, then
+> textures resolve across its body from the feet up in one smooth sweep, as if it is being written
+> into existence. As the last surface lands, a small hexagonal token of warm gold light ignites in
+> its open right palm and settles there, pulsing slowly like a heartbeat. Thin violet data threads
+> trail off its shoulders into the dark and dissolve. Camera: slow push in from a wide-medium to a
+> medium, ending at chest height. Lighting: single soft key from the upper left, violet rim light
+> from behind, gold bounce from the palm onto the face. Shallow depth of field, subtle volumetric
+> haze, fine film grain. Audio: low sub-bass swell, a single crystalline chime as the token
+> ignites, quiet room tone. No text, no logos, no people.
+
+### Four-shot sequence (8s each, cut together to ~32s)
+
+**Shot 1 of 4: deployment**
+
+> Cinematic 3D render, near-black void. The agent from the reference image stands center frame as a
+> cold violet wireframe. Textures and materials resolve upward across its body in one continuous
+> sweep, surfaces catching the light as they land. A faint grid of light briefly maps its silhouette
+> and fades. Camera: slow dolly in, wide to medium. Lighting: soft key upper left, violet rim from
+> behind, haze in the beam. Audio: rising sub-bass, a soft mechanical lock as the last surface
+> lands. No text.
+
+**Shot 2 of 4: the wallet**
+
+> Same character, same void, now fully rendered. It turns its right hand palm-up. A small holographic
+> card materializes an inch above the palm and rotates slowly: an abstract key glyph, a row of
+> shifting glyph-like characters standing in for an address, and a soft gold value that ticks
+> upward. The card's light spills gold onto the agent's face and chest. Camera: slow arc from the
+> right, medium close on the hand and face together. Lighting: gold from the card as key, violet
+> rim. Shallow depth of field, the card in sharp focus. Audio: crystalline chime, quiet electrical
+> hum, a soft ascending tick as the value rises. No readable text.
+
+**Shot 3 of 4: paying for something**
+
+> Same character. Three tall translucent violet service panels float in the dark in front of it,
+> each sealed with a thin lock glyph. The agent reaches out and touches the center panel. A stream
+> of small gold particles flows from its palm into the panel; the lock dissolves into teal, the
+> panel opens, and a bright ribbon of data flows back into the agent's chest, lighting it from
+> inside. Camera: slow lateral track left to right, keeping the agent in profile and the panel in
+> frame. Lighting: teal from the unlocked panel, gold from the particle stream, violet rim. Audio:
+> a rush of fine particles, a satisfying two-note unlock, data shimmer. No text.
+
+**Shot 4 of 4: on the registry**
+
+> Camera pulls back fast and smooth from the agent, revealing it standing on one lit tile in an
+> enormous dark grid stretching to the horizon, other tiles glowing faintly with distant agent
+> silhouettes. The agent's own tile pulses violet once, and a ring of light expands outward across
+> the grid from it, lighting neighboring tiles as it passes. The agent stands still, palm still
+> glowing gold. Camera: fast pull back to a wide, then settle and hold. Lighting: grid emissive
+> violet, single gold point on the subject. Audio: bass drop on the pulse, long reverb tail, then
+> near silence. No text.
+
+### Negative prompt (paste into the negative field on every shot)
+
+> text, letters, numbers, words, subtitles, watermark, logo, UI, user interface, HUD, charts,
+> coins, dollar signs, crowds, extra characters, warped hands, extra fingers, face morphing,
+> shaky camera, jump cuts, lens flare spam, rainbow colors, low resolution, cartoon shading
+
+### Post-production
+
+- Comp the real strings over shot 2 and shot 4 in an editor: the agent's address, `x402 enabled`,
+ and the closing card. Rendered text is the only text that will survive a screenshot.
+- End card, 2 seconds, static: the repo URL on black. Nothing else.
+- Cut the video to land on the beat where the panel unlocks in shot 3. That is the moment the idea
+ is legible, and it is what a muted autoplay timeline shows first.
+- Post it as native video, not a link to a video. X will not show a preview card and the video at
+ the same time, and the video wins every time.
+
+---
+
+## Naming the next repo (agent wallets + x402, standalone)
+
+The thesis you wrote is custody plus guardrails plus payment, and the name should say the smallest
+true thing about it rather than stacking nouns. `onchain-agents-money` describes the category, not
+the product, and it reads like a folder.
+
+Three that hold up, best first:
+
+1. **allowance** (`@three-ws/allowance`, `allowance-mcp`). It is the whole product in one word every
+ person on earth already understands: money you give something, with limits, that stays yours. It
+ names the guardrails and the funding in the same breath, and "give your agent an allowance" is a
+ sentence that needs no explanation to a non-crypto reader. Strongest option.
+2. **purse**. Small, concrete, obviously a wallet without being called a wallet, and unclaimed as a
+ crypto brand in a way "wallet" never will be. "Every agent gets a purse."
+3. **spendkit**. The most literal and the safest. Says exactly what it is to a builder scanning npm,
+ and pairs cleanly with x402 in a subtitle. Least distinctive of the three.
+
+Whichever wins, the tagline is the same and it is the thesis compressed: **your agent's wallet, your
+keys, your limits.**
+
+---
+
+<a id="sec-528"></a>
+
+> **Source:** `docs/x-posts/news-archive-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: the three.ws crypto news archive
+
+Copy for announcing that three.ws runs the largest open crypto-news archive and feeds it to the
+3D agents as market memory.
+
+**Verified numbers (pulled live from `GET /api/news/archive?stats=true` on 2026-08-16).** Re-pull
+before posting; the hourly archiver appends and the count only goes up.
+
+| Claim | Live value | Source |
+|---|---|---|
+| Archived articles | 740,889 | `stats.total_articles` |
+| First article | 2017-09-23 (not 2016) | `stats.first_article_date` |
+| Last article | today, refreshed hourly | `stats.last_article_date`, [api/cron/news-archive-append.js](../api/cron/news-archive-append.js) |
+| Months covered | 103 | `months.count` |
+| Languages | English + 中文 | `stats.languages` |
+| Live publisher feeds | 197 | [api/_lib/news-sources.js](../api/_lib/news-sources.js) `NEWS_SOURCES` |
+| Agent memory path | every read story lands in the durable `news_knowledge` corpus that grounds the 3D agents | [api/_lib/news-knowledge-store.js](../api/_lib/news-knowledge-store.js), `GET /api/news/knowledge` |
+
+**Do not say "since 2016."** The corpus starts September 2017. Do not say "every article ever
+published" either: 197 feeds is the live registry, and the archive is enriched (tickers,
+sentiment, entities, market context at publish time), which is the actual differentiator.
+
+Links that resolve: three.ws/markets/archive, three.ws/markets/news, three.ws/markets/digest.
+
+---
+
+## 1. Main post
+
+> Did you know three.ws runs the largest open crypto news archive?
+>
+> 740,000+ articles from 197 crypto publishers, September 2017 to this hour, English and Chinese,
+> every one enriched with tickers, sentiment, entities, and the BTC/ETH price at the moment it
+> was published.
+>
+> We built it because our 3D AI agents needed memory. An agent that only sees today's headline
+> has no idea it is the fourth time that narrative has run. Ours can look up every prior cycle,
+> what was said, who said it, and what the market actually did next.
+>
+> Free to search: three.ws/markets/archive
+
+---
+
+## 2. Shorter variant (single-screen)
+
+> Most AI agents read today's news. Ours read nine years of it.
+>
+> three.ws keeps the largest open crypto news archive: 740k+ articles, 197 publishers, Sept 2017
+> to this hour, EN + 中文, each tagged with tickers, sentiment, and the market price at publish
+> time. It is the memory layer behind our 3D agents.
+>
+> three.ws/markets/archive
+
+---
+
+## 3. Thread (4 posts)
+
+> **1/** Did you know three.ws has the largest open crypto news archive?
+>
+> 740,000+ articles. 197 publishers. September 2017 to this hour. English and Chinese.
+>
+> It is not a scrape sitting in a bucket. Here is what it is for.
+
+> **2/** Every article is enriched on the way in: tickers mentioned, sentiment, entities, and the
+> BTC/ETH price and fear/greed reading at the exact moment it published.
+>
+> So you can ask what the market was actually doing when a story ran, not just that it ran.
+
+> **3/** That corpus is the memory for our 3D AI agents.
+>
+> An agent with only today's feed treats every narrative as new. An agent with nine years of
+> coverage knows this exact story ran in 2018, 2021, and 2024, and what followed each time.
+> Same model, better context.
+
+> **4/** All of it is searchable by keyword, ticker, source, sentiment, date, and language, and
+> queryable through our API for your own agents.
+>
+> three.ws/markets/archive
+
+---
+
+## 4. Reply to have ready
+
+If someone asks how it stays current: the archiver runs hourly against all 197 feeds, so the
+newest month is always live and the corpus grows every hour. If someone asks about publisher
+rights: the reader shows a bounded excerpt plus our own summary and sends readers to the
+publisher, and the cap plus any takedown is enforced server side across the reader, the RSS
+mirror, archive search, and the agent knowledge corpus. See [docs/news-rights.md](#sec-292).
+
+---
+
+<a id="sec-529"></a>
+
+> **Source:** `docs/x-posts/onchain-agent-wallets-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: onchain-agent-wallets
+
+Announcement copy for [github.com/nirholas/onchain-agent-wallets](https://github.com/nirholas/onchain-agent-wallets),
+the MCP server that gives an AI agent a Solana spending allowance instead of a private key.
+
+**Thesis of this announcement:** handing an agent a keypair is the wrong primitive, and the chain
+already has the right one. Nothing else. No token talk, no roadmap, no "the future of agentic
+commerce."
+
+**Every claim below is true today**, verified against the shipped 0.1.0 code: the vault token
+account is owned by the human and derived deterministically from their address plus the agent id;
+the agent holds only an SPL Token delegation capped by `approve`; the token program decrements
+`delegated_amount` on every spend and refuses anything above it; one owner-signed `revoke` sets it
+to zero; the owner can withdraw without the agent's cooperation; 14 MCP tools; 22 tests; the
+delegation test runs the real SPL Token program in process and asserts that spending 61 against a
+remaining allowance of 60 fails on-chain while 460 sits in the vault; guardrails (per-transaction
+cap, rolling 24h cap, recipient allowlist, x402 host allowlist, expiry, pause, confirm-above
+threshold) are checked before signing; `pay_x402` reads the price from the unpaid 402 before any
+money moves; owner actions return an unsigned transaction for Phantom, Solflare, Backpack, or a
+Ledger, so no secret key is needed on the machine.
+
+**Things to NOT claim:**
+
+1. **Do not call it audited.** It is tested against the real token program, which is a different and
+ weaker claim. "The token program enforces it" is true and strong enough.
+2. **Do not claim a live x402 settlement volume or any usage numbers.** It shipped today.
+
+**Now live, so the drafts below are all postable:** `npx -y @three-ws/onchain-agent-wallets`
+(verified: 14 tools over stdio from a clean install), and
+`io.github.nirholas/[email protected]` in the official MCP registry, flagged latest and
+active.
+
+---
+
+## 1. Main post (recommended)
+
+267 characters with X's 23-character URL count, so it posts from any account, Premium or not.
+
+> Everyone hands their AI agent a private key.
+> Then keeps $20 in the wallet, because that's the blast radius.
+>
+> Give it an allowance instead.
+>
+> Solana's token program enforces the cap, decrements it every spend, and you revoke in one
+> instruction.
+>
+> github.com/nirholas/onchain-agent-wallets
+
+Why this one: the first two lines name a thing every builder has actually done and quietly felt bad
+about, which is what earns the repost. "Blast radius" is the phrase doing the work. The fix arrives
+as one short line, and the mechanism follows so nobody has to take it on faith. It never says "MCP",
+because the people who need MCP will click, and the people who do not would have bounced on the
+acronym.
+
+## 2. Alternate: the proof
+
+For a technical timeline. Leads with the test rather than the pitch. 259 characters.
+
+> We wrote a test that gives an agent a 100 USDC allowance, spends 40, then tries to spend 61 with
+> 460 USDC still sitting in the vault.
+>
+> It fails on-chain. Not in our code. In Solana's token program.
+>
+> That refusal is the entire product.
+>
+> github.com/nirholas/onchain-agent-wallets
+
+Why this one: engineers trust a failing transaction more than any amount of copy. It also
+pre-empts the first reply you will get, which is "so what stops the agent ignoring your limits."
+
+## 3. Alternate: x402 / agent-payments timeline
+
+269 characters.
+
+> Your agent can pay for its own APIs now, without you handing it a wallet.
+>
+> It gets an allowance. It pays the x402 invoice out of that allowance. The price is read before any
+> money moves, and the chain caps the total.
+>
+> Revoke in one instruction.
+>
+> github.com/nirholas/onchain-agent-wallets
+
+## 4. Alternate: builder-facing
+
+Now unblocked: the package is live on npm and the command below is verified working. For a
+timeline that already knows what MCP is, this is arguably the strongest of the four, because the
+install line makes it real in one glance.
+
+> ```
+> npx -y @three-ws/onchain-agent-wallets
+> ```
+>
+> 14 MCP tools that give an agent a Solana wallet it cannot drain: an on-chain spending cap, per-tx
+> and daily limits, recipient and host allowlists, an audit log of every refusal, and x402.
+>
+> You keep custody. Revoke any time.
+>
+> github.com/nirholas/onchain-agent-wallets
+
+---
+
+## Thread version
+
+Post 1 is the main post above. Then:
+
+**2/**
+
+> The problem with agent wallets: a keypair is all-or-nothing. Whoever holds it can move everything
+> in the account. There is no ceiling, no allowlist, no expiry, and no way to take it back without
+> racing the agent.
+
+**3/**
+
+> So the money never goes to the agent.
+>
+> It sits in a vault account you own. The agent gets an SPL Token delegation over it, capped. Every
+> spend decrements the cap. Spend past it and the token program rejects the transaction.
+
+**4/**
+
+> On top of that: per-transaction cap, rolling 24h cap, recipient allowlist, x402 host allowlist,
+> expiry, pause, and a threshold above which a human has to say yes.
+>
+> Refusals are logged with the exact rule that fired, so you can see what your agent tried to do.
+
+**5/**
+
+> If the machine running the agent is fully compromised, the local rules can be bypassed and the
+> on-chain cap still cannot.
+>
+> That is why they are two layers and not one.
+
+**6/**
+
+> No secret key has to touch the machine either. Owner actions come back as an unsigned transaction
+> for Phantom, Solflare, Backpack, or a Ledger to sign.
+>
+> Free rehearsal on devnet.
+>
+> github.com/nirholas/onchain-agent-wallets
+
+---
+
+## Replies worth pre-writing
+
+**"Why not a multisig / smart wallet?"**
+
+> Because this needs no new program and no new trust assumption. It is `approve` and `revoke` from
+> the SPL Token program, which has been on mainnet for years and is already audited harder than
+> anything we would ship. A multisig is a fine answer when you want co-signing. This is the answer
+> when you want a ceiling.
+
+**"What stops the agent from just asking you to raise the limit?"**
+
+> Nothing, and that is correct. It should be able to ask. Raising the ceiling is an owner-signed
+> `approve`, so a human is in the loop for exactly the decision that deserves one.
+
+**"Solana only?"**
+
+> Today, yes. The custody model is a token-program delegation, so the EVM equivalent is ERC-20
+> `approve` with the same shape. Solana first because that is where the agent economy we are
+> building actually lives.
+
+---
+
+## Notes on framing
+
+- **Do not lead with MCP.** It narrows the audience to people who already know the acronym, and the
+ idea is bigger than the transport.
+- **Do not mention $THREE in this post.** There is no fee in this package and no buyback lane, so
+ attaching the coin to it would be the kind of claim someone checks and finds hollow. The
+ metaplex-agent-mcp post is where the $THREE story is true and load-bearing.
+- **"Allowance" is the word.** It is the one term that makes a non-crypto reader understand the
+ whole design instantly. Keep it in every rewrite.
+- The Pages overview at nirholas.github.io/onchain-agent-wallets is a good second link for a reply,
+ not for the main post: one link per post converts better.
+- If someone asks where to find it in the MCP ecosystem, the registry name is
+ `io.github.nirholas/onchain-agent-wallets`. Worth a reply, not worth crowding the main post.
+
+---
+
+<a id="sec-530"></a>
+
+> **Source:** `docs/x-posts/oracle-trading-mcp-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: Oracle and our trading agents become MCP servers
+
+Draft copy for announcing that [Oracle](https://three.ws/oracle) and the three.ws autonomous
+trading agents are published as Model Context Protocol servers in
+[Anthropic's official MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas),
+so any AI assistant can use them directly.
+
+Build plan this announces: [`docs/oracle-trading-mcp-plan.md`](#sec-314).
+
+**Do not post until:** `npm run smoke:mcp` passes against the live remotes, and both
+`io.github.nirholas/threews-oracle` and `io.github.nirholas/threews-agent-trader` resolve in the
+registry. Every claim below has to be true at post time.
+
+## Rules for this one
+
+1. **Explain it to someone who has never heard of MCP.** The audience is not protocol people. It
+ is traders who use Claude and builders who have heard the acronym and never installed one.
+ One sentence of plain English up top, jargon only after the reader is already interested.
+2. **Lead with the thing, not the plumbing.** Nobody wakes up wanting an MCP server. They want the
+ score before the candle. Open on that.
+3. **One outbound link in the main post.** Threads can carry more.
+4. **Claim only what is live.** We publish to the registry, we do not "partner with Anthropic".
+ Do not imply endorsement.
+5. **No price talk, no predictions, no moon language.** This is a capability post.
+6. **$THREE is the only coin named**, and only if it is naturally relevant. Do not force it in.
+
+---
+
+## 1. Main post (recommended)
+
+> Your AI can now trade with our eyes.
+>
+> Oracle scores every new pump.fun coin 0 to 100 in the first seconds, from the creator's history,
+> who is buying, and how clean the supply is.
+>
+> It is now an MCP server. One line of setup and Claude reads it live.
+>
+> https://three.ws/oracle
+
+Why this one: the first line is the whole product in six words, the second line explains it with
+zero jargon, and MCP shows up only after the reader already wants it.
+
+## 2. Alternate main post (builder-facing)
+
+> We turned our conviction engine into an MCP server.
+>
+> `npx @three-ws/oracle-mcp`
+>
+> Free, no key, no signup. Your agent gets a live 0-100 score on every new launch, the reasoning
+> behind it, and the track record so it can decide how much to trust it.
+>
+> Now in Anthropic's MCP registry.
+
+## 3. Thread (use if the main post lands)
+
+**1/**
+> Your AI can now trade with our eyes.
+>
+> Oracle scores every new pump.fun coin 0 to 100 in its first seconds. It is now an MCP server, so
+> Claude can read it live.
+>
+> Here is what that actually means. 🧵
+
+**2/**
+> MCP is a plug for AI assistants. Instead of copy-pasting data into a chat, you connect a tool
+> once and the AI can use it whenever it needs to.
+>
+> Anthropic built it. There is an official registry of them. We just published two.
+
+**3/**
+> Server one is Oracle.
+>
+> Ask your AI "what is worth looking at right now" and it pulls the live board: score, tier, the
+> plain-language reasoning, and the honest track record.
+>
+> Free. No key. No account.
+
+**4/**
+> Server two is the trading agent.
+>
+> Same conversation, next step: "arm my agent on anything scoring 80+, half a SOL a day, simulate
+> first."
+>
+> It runs. You can check what it did and stop it in one sentence.
+
+**5/**
+> Simulate is the default. Real spend is opt-in every time, and the per-trade and daily limits are
+> enforced on our side, not in the client.
+>
+> An AI cannot talk its way past them. That is the point.
+
+**6/**
+> Why it matters: the first minutes of a new coin are the most lopsided market there is. The people
+> with an edge have context you do not.
+>
+> Oracle is that context, as a number, delivered fast enough to act on.
+
+**7/**
+> Both servers are in the official MCP registry now, alongside the rest of ours.
+>
+> registry.modelcontextprotocol.io/?q=io.github.nirholas
+>
+> Docs: https://three.ws/oracle/docs
+
+## 4. Reply to attach to whichever post lands
+
+> The scoring model is fitted on our own labeled outcomes, not hand-tuned vibes, and the holdout
+> numbers are published on the docs page including the ones that make us look worse.
+>
+> If you are going to let an agent act on a number, you should get to audit the number.
+
+## 5. If someone asks "what is MCP" in the replies
+
+> It is a standard way to plug a tool into an AI assistant. Connect it once and Claude can use it
+> whenever it is relevant, instead of you pasting data in by hand. Anthropic made it and it is
+> open. Ours takes one line to add.
+
+---
+
+## Facts a reply might need
+
+Pull the live numbers from https://three.ws/oracle/docs before posting. As of 2026-08-19 the
+docs report holdout AUC 0.879, top-decile good-rate 62.5 percent against an 11.7 percent base rate,
+and Prime tier at 72.7 percent. **Re-read those from the page at post time.** The model is refit as
+labels accumulate, and quoting a stale number in a post about being auditable is the worst possible
+place to be wrong.
+
+## What not to say
+
+- Anything implying Anthropic endorses, reviewed, or partnered with us. We published to a public
+ registry. That is all.
+- "Guaranteed", "alpha", "printer", "financial advice" in any direction.
+- A win-rate number without the base rate next to it.
+- Anything about the agent being unsupervised. Simulate is the default and the limits are real.
+
+---
+
+<a id="sec-531"></a>
+
+> **Source:** `docs/x-posts/pumpfun-article-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: pump.fun wrote an article about three.ws
+
+Copy for announcing that **pump.fun's own editorial team published a feature story on three.ws**,
+titled "Three Builds With Tech Giants", live on the $THREE coin page:
+
+https://pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
+
+**What this announcement is:** recognition. pump.fun writes these for a small fraction of the
+coins on the platform, and they wrote ours off the back of shipped product: browser-native 3D AI
+agents with onchain identities, the Animations & Poses Studio, two MCP servers in Anthropic's
+registry, the AWS partnership, and IBM replying in public.
+
+**What it is not:** a price post. The article mentions a $16.6M peak market cap. Do not build the
+post around that number and do not add moon language, predictions, or "don't miss out". The story
+is that the platform itself decided our work was worth writing up. Let that be the whole flex.
+
+Rules:
+
+1. Tag @pumpdotfun so their team sees it and can repost.
+2. Claim only what happened: pump.fun published an article about three.ws. Do not call it an
+ endorsement, a partnership, or a listing.
+3. Link the article directly. The URL carries the contract address, so the mint is verifiable
+ from the link itself: `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`
+4. Credit the people who did the work in the replies, not the token.
+
+---
+
+## 1. Main post (recommended)
+
+> @pumpdotfun wrote an article about us.
+>
+> Not a listing, not a promo slot. Their editorial team looked at what shipped and wrote the
+> story: browser-native 3D AI agents with onchain identities, the Animations & Poses Studio,
+> two MCP servers, AWS, IBM.
+>
+> Most projects never get one of these. We are grateful.
+>
+> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
+
+---
+
+## 2. Short alternate
+
+> pump.fun published a feature on three.ws: "Three Builds With Tech Giants".
+>
+> Written by their team, about work we shipped in public. That is the whole post.
+>
+> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
+
+---
+
+## 3. Builder-voice alternate (post from @nichxbt)
+
+> I did not pitch this. @pumpdotfun wrote it themselves.
+>
+> An article about three.ws, on the coin page, covering the 3D agents, the pose studio, the MCP
+> servers, AWS and IBM. They do not write many of these.
+>
+> Head down. More shipping.
+>
+> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
+
+---
+
+## 4. Thread version
+
+Use if you want the full story rather than one post. Post 1 is the announcement, the rest are
+replies to it.
+
+**1/**
+
+> @pumpdotfun wrote an article about three.ws.
+>
+> Their editorial team, their platform, their words. Most projects never get one.
+>
+> pump.fun/coin/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump/article
+
+**2/**
+
+> What they covered, in their framing: browser-native 3D AI agents with onchain identities. AI
+> that lives on a website as an embodied, embeddable character instead of a chat box.
+
+**3/**
+
+> The products they picked out: the Animations & Poses Studio at three.ws/pose, and the two MCP
+> servers now in Anthropic's official registry, including 3D Studio MCP for text and image to 3D.
+
+**4/**
+
+> And the partners: AWS, where three.ws is an official partner available through AWS Marketplace,
+> and IBM, who replied "we're super excited about this" in public on June 1.
+
+**5/**
+
+> None of that was a marketing push. It was shipping, in the open, every week, until the platform
+> we launched on decided to write it up.
+>
+> Same plan for the next six months.
+>
+> three.ws
+
+---
+
+## Media
+
+No custom graphic is required. X unfurls the pump.fun article link with its own card, which shows
+the article title and the coin. If you attach an image instead, the card is replaced, so pick one:
+either the link preview or a graphic, never both expecting both to render.
+
+Pick one option. Do not post all four.
+
+---
+
+<a id="sec-532"></a>
+
+> **Source:** `docs/x-posts/sperax-staking-in-chat-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: staking, balance, and buy SPA inside SperaxOS chat
+
+Announcement copy for the new `/staking` surface on `chat.sperax.io` and the chat-native staking
+tool calls (stake, unstake, extend lock, check balance, buy SPA) wired into the assistant.
+
+**Thesis of this announcement:** you no longer need to leave the chat to manage your SPA position.
+Ask the assistant to stake, check your balance, or buy SPA, and it runs as a real, guarded on-chain
+call, not a redirect to a separate dApp.
+
+**This is a two-part feature, and the two parts are in different states right now. Read this
+section before picking a post to publish.**
+
+## Part 1: chat-native staking tool calls, shipped and true today
+
+Verified against the merged code (`88a3684` on `main`, live on `chat.sperax.io`):
+
+- Asking the assistant to stake SPA, unstake, extend a veSPA lock, check balance, mint/redeem USDs,
+ or buy SPA routes through real, guarded tool calls, not mocked responses.
+- `stakeSpa`, `unstakeSpa`, `increaseStake`, `extendStake` are registered across every wiring
+ surface (renders, inspectors, DeFi Guard mutating-API gate, keyword routing) so they render with
+ a proper UI card and require the same risk confirmation as any other fund-moving action.
+- SPA and USDs are in the Arbitrum token allowlist for the swap tool, so "buy SPA with USDC" works
+ without depending on a remote tokenlist refresh.
+- "buy spa", "stake spa", "unstake spa" are recognized keyword triggers, so the natural-language
+ phrasing works without needing exact tool names.
+
+**This part is safe to announce now.**
+
+## Part 2: the embedded `/staking` page (full app.sperax.io experience in an iframe), NOT ready
+
+The `/staking` page exists, is reachable from the sidebar, and matches SperaxOS's design language.
+But the embedded app.sperax.io view inside it does not load yet:
+
+1. `app.sperax.io` returns Cloudflare's managed-challenge 403 to the iframe request, and separately
+ sends `X-Frame-Options: SAMEORIGIN`, which refuses to be framed by `chat.sperax.io` at the
+ browser level. Both need a Cloudflare zone-level fix (response header transform +
+ challenge-skip rule) on `app.sperax.io`, not yet applied.
+2. `chat.sperax.io`'s own CSP `frame-src` directive does not yet include `app.sperax.io`. Code fix
+ pending, blocked on repo access as of this writing.
+3. The wallet connector on the live `chat.sperax.io` build has a corrupted
+ `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` from an unrelated 2026-08-06 deploy incident, so even once
+ framing is unblocked, WalletConnect will not work until that value is set correctly and the
+ image is rebuilt.
+
+**Do not publish a post claiming "the full app.sperax.io experience is in chat" until all three of
+the above are resolved and independently verified with a real browser load, not just an HTTP
+status check.** Once fixed, a short follow-up post ("now you can see your full position, not just
+the tool card") is a good second post, not a rewrite of the first.
+
+---
+
+## 1. Main post (recommended, publish now)
+
+Leads with the thing that actually works: talking to the assistant.
+
+> You don't need a separate tab to manage your SPA position anymore.
+>
+> Tell SperaxOS to stake, check your balance, or buy SPA, and it runs as a real on-chain call, with
+> the same risk checks as everything else in chat.
+>
+> chat.sperax.io
+
+Why this one: it makes a concrete, checkable claim ("tell it to stake") instead of a vague platform
+claim, and it doesn't reference the embed, which isn't ready.
+
+## 2. Alternate: example-led
+
+> "stake 500 SPA for 6 months"
+> "what's my SPA balance"
+> "buy SPA with USDC"
+>
+> All three now run inside SperaxOS chat as real transactions. No new tab, no separate dApp.
+>
+> chat.sperax.io
+
+Why this one: the three example prompts are copy-pasteable and match the actual hint text shipped
+on the `/staking` page footer, so anyone who tries it gets exactly what the post promised.
+
+## 3. Alternate: short/punchy
+
+> Staking, balance checks, and SPA buys now live inside the SperaxOS chat itself.
+>
+> Ask. It runs. No context switch.
+
+---
+
+## Notes on framing
+
+- **Do not mention $THREE.** This is a Sperax/SPA-specific feature on a Sperax product. Keep the two
+ ecosystems separate in copy.
+- **Do not claim the embedded app.sperax.io iframe view works.** See Part 2 above. Posting that
+ claim before the Cloudflare + CSP + WalletConnect fixes land and are verified in a real browser
+ will read as false the moment someone clicks through, since the iframe currently renders a
+ broken-content icon.
+- **"Real on-chain call, not a redirect" is the phrase doing the work.** SperaxOS has had chat
+ before; what's new is that these specific actions are wired as guarded tool calls rather than
+ just being informational.
+- Update this file (or add a dated addendum below) once Part 2 is verified fixed, so the "NOT ready"
+ section doesn't go stale and mislead a future poster.
+
+---
+
+<a id="sec-533"></a>
+
+> **Source:** `docs/x-posts/threews-avatar-launch.md` · [↑ table of contents](#table-of-contents)
+
+# Give your AI a body: the avatar film
+
+X copy for the platform film. The shot prompts that produce the video live in
+[threews-avatar-video-script.md](#sec-534).
+
+**Thesis:** the tagline, literally. A model with no form gets one, the form moves, the form holds
+its own wallet, the form walks out into the real world. Nothing about supply, price, or buybacks.
+
+**Verified true today:** prompt-to-avatar produces a rigged, animatable body; the avatar renders and
+animates in the browser; agents carry their own Solana wallet address; `<agent-3d>` embeds an avatar
+on any page with a script tag and one element. **Do not claim** that $THREE buybacks are executing.
+
+All three posts below are inside 280 characters with X's 23-character URL count, so they post from
+any account, Premium or not.
+
+## X post
+
+### Recommended
+
+> Give your AI a body.
+>
+> Type a prompt, get a rigged 3D avatar that talks, walks, and holds its own Solana wallet. Drop it
+> on your site with one tag.
+>
+> three.ws
+
+Line 1 is the product in five words. Line 2 is the three things that make it different from a
+picture, in the order people care about. The wallet lands last because it is the part nobody expects
+from an avatar company.
+
+### Alternate: builder-facing
+
+> Your agent has a voice, a model, and a name. It still has no body.
+>
+> three.ws gives it one: a rigged 3D avatar you can talk to, embed anywhere with a single element,
+> and fund with its own on-chain wallet.
+>
+> ```html
+> <script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js"></script>
+> <agent-3d src="agent://base/42"></agent-3d>
+> ```
+
+### Alternate: $THREE-first
+
+> Every 3D agent built on three.ws ships with its own Solana wallet, an on-chain identity, and
+> pay-per-call built in.
+>
+> $THREE is the coin of that economy.
+>
+> Give your AI a body: three.ws
+
+### Reply slot, post under the main one
+
+> The avatar in the video was generated from a text prompt on three.ws, rigged automatically, and
+> rendered in the browser. No modeling, no rigging software, no download.
+
+---
+
+<a id="sec-534"></a>
+
+> **Source:** `docs/x-posts/threews-avatar-video-script.md` · [↑ table of contents](#table-of-contents)
+
+# Text-to-video script: the three.ws avatar
+
+Prompts for a video model (Veo, run through ElevenLabs), using a three.ws 3D avatar render as the
+reference image. This file is the **picture**, not the words. The X copy it ships with is in
+[threews-avatar-launch.md](#sec-533), the spoken lines live in
+[metaplex-agent-deployer-video-script.md](#sec-523), and the
+deployer-specific shot list lives in [metaplex-agent-mcp-x-post.md](#sec-527).
+
+The idea being sold here is the tagline and nothing else: **give your AI a body.** A model with no
+form gets one, the form moves, the form owns a wallet, the form walks out into the real world. Four
+claims, all true today.
+
+---
+
+## Before you generate
+
+**Reference image.** Open any avatar on [three.ws](https://three.ws), frame it front-facing in a
+neutral pose against the dark stage, and screenshot at the largest size you can. Use the **same
+file on every shot** or the character drifts and the cut stops reading as one being.
+
+**Clip length.** Veo generates in 8-second beats. Every prompt below is written to resolve inside
+one beat, with one idea and one camera move each. A prompt that asks for two things at 8 seconds
+returns mush.
+
+**Text.** Video models mangle letters. Nothing legible is described in any prompt, and the negative
+prompt bans it outright. Every real string gets composited afterwards in an editor.
+
+**Palette, held across all shots.** Near-black void, violet as the light of the machine, teal as the
+light of the network, one warm gold reserved for money in motion. No fourth color.
+
+---
+
+## Hero clip, 8 seconds
+
+Use this if you only render one thing.
+
+> Cinematic product shot on a near-black void stage. A soft cloud of violet light particles hovers
+> at center frame, formless and breathing. The particles rush inward and collapse onto a figure: a
+> stylized 3D humanoid avatar matching the reference character exactly, materializing from the feet
+> upward in one continuous sweep as surfaces and textures resolve and catch the light. As the last
+> surface lands the figure lifts its head and looks directly into the lens, alive and calm. A single
+> point of warm gold light ignites in its open palm and settles, pulsing slowly. Camera: slow push
+> in from wide to medium, ending at chest height, locked and steady. Lighting: soft key from the
+> upper left, violet rim from behind, gold bounce from the palm onto the jaw. Shallow depth of
+> field, gentle volumetric haze, fine film grain. Audio: low sub-bass swell, a soft rush of
+> particles, one crystalline chime as the palm ignites, then quiet room tone. No text, no logos, no
+> other characters.
+
+---
+
+## Five-shot sequence, 8 seconds each, about 40 seconds cut
+
+### Shot 1 of 5: formless
+
+> Cinematic 3D render on a near-black void stage. No character. A shifting cloud of violet light
+> particles hangs in the center of frame, pulsing gently in and out like breathing, with faint
+> threads of light passing through it as if something is thinking inside. The cloud has no shape and
+> keeps failing to hold one. Camera: very slow push in, wide to wide-medium. Lighting: the cloud is
+> the only light source, spilling violet into the haze around it. Volumetric fog, fine film grain.
+> Audio: low sub-bass hum, faint electrical whisper, no music. No text, no characters.
+
+### Shot 2 of 5: the body
+
+> Same near-black void, same violet cloud. The particles pull sharply inward and collapse onto a
+> figure: a stylized 3D humanoid avatar matching the reference character exactly. Materials resolve
+> across the body from the feet upward in one smooth continuous sweep, each surface catching the key
+> light as it lands. A faint wireframe grid maps the silhouette for an instant and fades. The figure
+> stands still, newly solid. Camera: slow dolly in, wide to medium. Lighting: soft key upper left,
+> violet rim from behind, haze in the beam. Audio: rising sub-bass, a soft mechanical lock as the
+> final surface lands, then silence. No text.
+
+### Shot 3 of 5: alive
+
+> Same character, fully rendered, standing center frame in the near-black void. It lifts its head,
+> turns slightly, and looks directly into the lens. Its chest rises with a breath. It shifts its
+> weight, flexes one hand open and closed, and the beginning of an expression crosses its face.
+> Small, human, unhurried movements. Camera: slow arc from the right, settling to a medium close-up
+> on the face and shoulders. Lighting: soft key upper left, violet rim, a warm fill lifting the
+> eyes. Shallow depth of field with the eyes in sharp focus. Audio: one quiet breath, low room tone,
+> a single soft note. No text.
+
+### Shot 4 of 5: it holds its own money
+
+> Same character in the same void. It turns its right hand palm-up. A small hexagonal token of warm
+> gold light ignites an inch above the palm, rotates slowly, and settles there pulsing like a
+> heartbeat. Gold light spills up onto the face and chest. Thin teal threads reach in from the
+> darkness toward the token and connect, and the token pulses brighter with each connection. Camera:
+> slow push to a medium close on the hand and face together. Lighting: gold from the token as the
+> key, violet rim from behind, teal accents on the threads. Shallow depth of field, the token in
+> sharp focus. Audio: crystalline chime, quiet electrical hum, a soft ascending tick with each
+> connection. No text, no coins, no currency symbols.
+
+### Shot 5 of 5: out into the world
+
+> Same character in the void. A tall rectangle of soft teal light opens in the darkness in front of
+> it, like a doorway cut into the black, and through it we glimpse a sunlit ordinary room with plain
+> furniture. The avatar walks forward and steps through the rectangle. On the far side it stands in
+> the real room, lit by real daylight, still glowing faintly violet at the rim, gold still in its
+> palm, looking around the space. Camera: track behind the character through the doorway, then swing
+> around to a wide of it standing in the room. Lighting: violet and teal on the void side, natural
+> warm daylight on the room side, a clean transition at the threshold. Audio: the hum drops away as
+> it crosses, replaced by quiet natural room ambience and birdsong outside. No text.
+
+---
+
+## Negative prompt
+
+Paste into the negative field on every shot.
+
+> text, letters, numbers, words, subtitles, captions, watermark, logo, UI, user interface, HUD,
+> charts, coins, dollar signs, currency symbols, crowds, extra characters, duplicate character,
+> warped hands, extra fingers, face morphing, character drift, shaky camera, jump cuts, lens flare
+> spam, rainbow colors, oversaturation, low resolution, cartoon shading, distorted anatomy
+
+---
+
+## If you want it to speak
+
+Veo can generate its own audio. If you use that, put the sentence in double quotes inside the
+prompt, name who says it, and append **"no subtitles, no captions, no on-screen text"** or captions
+get burned into the frame.
+
+If ElevenLabs speaks it instead, generate the voice first and cut the picture to the read. Never the
+reverse: matching a render to an existing voice track works, matching a voice to an existing render
+never does.
+
+Lines that fit these five shots, one per beat, counted to sit inside 8 seconds:
+
+1. *(11 words)* "Your model can write, reason, and speak. It has no body."
+2. *(12 words)* "Type a sentence. It gets one. Rigged, animated, ready in a minute."
+3. *(9 words)* "Now it can look at you when it answers."
+4. *(12 words)* "It holds its own wallet on Solana. It can be paid directly."
+5. *(13 words)* "Then it walks off our site and onto yours. One tag, any page."
+
+Keep the pause after "It has no body." That silence is the whole premise.
+
+---
+
+## Post-production
+
+- Composite every real string in an editor, never in the model: the URL, any address, any label.
+- End card, 2 seconds, static: `three.ws` on black, and the tagline under it. Nothing else.
+- Cut so the muted autoplay frame is shot 2 or shot 3. A body assembling reads instantly with no
+ sound; a violet cloud does not.
+- Post as native video, not a link to a video. X will not show a link preview and a video at once,
+ and the video wins.
+
+---
+
+<a id="sec-535"></a>
-> **Source:** `docs/x-meetup-posts.md` · [↑ table of contents](#table-of-contents)
+> **Source:** `docs/x-posts/x-meetup-posts.md` · [↑ table of contents](#table-of-contents)
# X posts: community meetup announcement (Friday, August 7)
@@ -117135,259 +123698,13 @@ https://community.ibm.com/community/user/discussion/community-meetup-inside-thre
---
-<a id="sec-510"></a>
-
-> **Source:** `docs/x-memory-seeding.md` · [↑ table of contents](#table-of-contents)
-
-# X memory seeding
-
-Give an agent your X voice: your public profile and recent original posts,
-distilled and written into the agent's long-term memory, so the replies it gives
-sound like the person who wrote them.
-
-This lane is built around one constraint. Connecting your X account to the
-platform (to post as your agent, for example) is permission to act on X on your
-behalf. It is **not** permission to write your posts into an agent's long-term
-memory. Those are two separate decisions, and the second one is its own
-explicit, versioned, revocable grant: nothing is read into memory until you say
-yes on a screen that tells you exactly what will be read and stored.
-
-- **Surface**: Settings, Connected accounts, X card at [/settings#connected-accounts](https://three.ws/settings#connected-accounts)
-- **API**: `/api/agents/:id/memory/seed/x`
-- **Related**: [Memory system](#sec-279), [Farcaster memory seeding](#sec-218), [GitHub seeding in the same table](memory.md#seeding-memory-from-an-existing-account)
-
----
-
-## How it fits together
-
-```
- Connect X (OAuth 2.0 PKCE, read scopes only)
- │ the connection alone changes nothing in memory
- ▼
- GET /api/agents/:id/memory/seed/x
- │ returns the disclosure verbatim from the server, never copy in the page
- ▼
- you tick "I have read the above and consent"
- │
- ▼
- POST … { consent: { accepted: true, scope_version } }
- │ the version must match the disclosure you were shown
- ▼
- profile + up to 100 recent original posts are read once
- distilled into up to 15 short facts about topics, opinions, projects, tone
- written to agent_memories tagged x_seed, the top five always in context
- │
- ▼
- DELETE /api/agents/:id/memory/seed/x (or disconnect X entirely)
- │ revokes the grant and deletes every memory it produced
- ▼
- nothing distilled from your account survives
-```
-
-Three properties fall out of that shape:
-
-- **A POST without consent is refused before anything is read.** The handler
- answers `403 consent_required` with the disclosure attached, and the
- per-agent seed budget is consumed only after authorization, connection, and
- consent all pass, so a rejected call never burns your re-seed window.
-- **Consent is pinned to the account and the text.** The grant records X's
- numeric account id and the disclosure version you agreed to. Reconnect a
- different X account, or let the disclosure wording move on, and the old grant
- stops authorizing new seeds until you agree again.
-- **Revocation is total.** Every seeded row carries the `x_seed` tag and the
- consent id that produced it. Revoking, or disconnecting X from Settings,
- deletes exactly those rows, including any a superseded grant left behind.
-
-## What is read, and what is not
-
-The consent screen shows this list verbatim from the server; the same module
-(`api/_lib/x-memory-seed.js`) enforces it, so the promise and the code cannot
-drift apart.
-
-| Read | Never read |
-|---|---|
-| Your X profile: display name, handle, bio, follower and following counts | Direct messages, drafts, likes, bookmarks, your follower list |
-| Up to 100 of your most recent **original** public posts (text and date) | Reposts and replies (excluded in the API call and re-checked in the transform) |
-| | Protected accounts you follow |
-
-| Stored on the agent | Never stored |
-|---|---|
-| Up to 15 short distilled facts (max 280 characters each) about your recurring topics, opinions, projects, and tone | The text of your posts; a distilled fact that copies a post is discarded before it is written |
-| Your X handle, so the agent can attribute what it learned | Links from your posts; URLs are stripped out of stored text |
-| The seed date and the disclosure version you agreed to | Any X credential; the access token stays encrypted in the connection record and is never copied into a memory |
-
-## What lands in memory
-
-Each fact becomes one row in `agent_memories`:
-
-- `type: 'reference'`, tagged `x` and `x_seed` plus up to three topics derived
- from your posting history.
-- Salience `0.80` for the top-ranked fact, decaying by rank.
-- The **top five facts land in the `working` tier**, the always-in-context core
- the chat runtime pages into every reply (see [memory system](#sec-279)).
- That is what makes a seed observable in the very next conversation turn.
-- `context` carries `source: 'x_seed'`, your handle, the distillation lane
- (`model` or `derived`), the disclosure version, and the consent id.
-
-If the distillation model chain is unavailable, the seed degrades rather than
-fails: deterministic facts are derived from your profile and your topic
-histogram (`distilled_by: 'derived'`), a smaller and blander seed instead of a
-silent zero.
-
----
-
-## API
-
-All three calls are owner-only: the session user must own the agent. Browser
-mutations carry the standard CSRF token.
-
-### `GET /api/agents/:id/memory/seed/x`
-
-Connection state, the consent grant, and the disclosure. This is the only
-source of the consent screen's copy.
-
-```bash
-curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/x --cookie "$JAR"
-```
-
-```json
-{
- "connected": true,
- "configured": true,
- "username": "you",
- "connection_scopes": "tweet.read users.read offline.access",
- "seeded_at": "2026-08-12T16:00:00.000Z",
- "fact_count": 5,
- "scope_version": "2026-08-11.1",
- "disclosure": { "reads": ["…"], "skips": ["…"], "stores": ["…"], "never": ["…"], "…": "…" },
- "consent": {
- "granted": true,
- "reason": "active",
- "scope_version": "2026-08-11.1",
- "granted_at": "2026-08-12T15:55:00.000Z",
- "username": "you",
- "last_seeded_at": "2026-08-12T16:00:00.000Z",
- "memories_seeded": 5,
- "posts_read": 10
- }
-}
-```
-
-`consent.reason` is `none` when no grant exists, `scope_version_changed` when
-the disclosure moved (the old grant no longer authorizes seeds), and
-`account_changed` when the connection now points at a different X account than
-the one you consented for.
-
-### `POST /api/agents/:id/memory/seed/x`
-
-Grant consent (first call) and seed. Without a live grant the body must carry
-the acceptance of the current disclosure version:
-
-```bash
-curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/x --cookie "$JAR" \
- -H 'content-type: application/json' -H "x-csrf-token: $CSRF" \
- -d '{"consent":{"accepted":true,"scope_version":"2026-08-11.1"}}'
-```
-
-```json
-{
- "username": "you",
- "seeded": 5,
- "posts_read": 10,
- "distilled_by": "model",
- "topics": ["agents", "solana", "threejs"],
- "facts": ["The author builds 3D AI agents at three.ws …"],
- "in_context": 5,
- "consent": { "granted": true, "…": "…" }
-}
-```
-
-With a live grant the same call with an empty body re-seeds: the previous batch
-is deleted before the new one lands, so an agent never carries two generations
-of facts about the same account. Rate-limited to one seed per agent per 6 hours.
-
-### `DELETE /api/agents/:id/memory/seed/x`
-
-Revoke. Marks the grant revoked and deletes every memory the grant produced.
-Idempotent: an agent with no grant still gets any orphaned seeded rows purged.
-
-```json
-{ "revoked": true, "deleted": 5, "consents_revoked": 1, "remaining": 0, "consent": { "granted": false, "reason": "revoked" } }
-```
-
-Disconnecting X from Settings triggers the same deletion across **all** of your
-agents (`revokeAllSeedConsentsForUser`), so a disconnect can never leave
-distilled posts behind on an agent you forgot about.
-
-## Errors
-
-| Code | HTTP | Meaning |
-|---|---|---|
-| `unauthorized` | 401 | Sign-in required |
-| `not_found` / `forbidden` | 404 / 403 | No such agent, or it is not yours |
-| `not_connected` | 400 | Connect X first (Settings, Connected accounts) |
-| `consent_required` | 403 | No live grant; the response carries the disclosure to show |
-| `account_mismatch` | 409 | The consent was granted for a different X account |
-| rate limited | 429 | One seed per agent per 6 hours |
-
-## Enabling it on a deployment
-
-The lane needs an X app with OAuth 2.0 and read scopes, created at
-https://developer.twitter.com with `https://<your-domain>/api/auth/x/callback`
-registered as the callback. Its two credentials are the only configuration:
-
-```
-X_OAUTH_CLIENT_ID=
-X_OAUTH_CLIENT_SECRET=
-```
-
-On Cloud Run, set them without disturbing the rest of the environment:
-
-```bash
-gcloud run services update three-ws-api --region us-central1 \
- --project aerial-vehicle-466722-p5 \
- --update-env-vars X_OAUTH_CLIENT_ID=...,X_OAUTH_CLIENT_SECRET=...
-```
-
-Until both are present, `GET /api/agents/:id/memory/seed/x` answers
-`configured: false` and the Settings card says X connections are not enabled on
-this deployment, rather than offering a Connect button that could not complete.
-Nothing else in the lane changes: the disclosure, the consent grant, and
-revocation behave identically once the credentials are in place.
-
-## Storage
-
-One table, created by `api/_lib/migrations/20260811140000_x_memory_consent.sql`:
-
-- `x_memory_consents` is the durable grant: the X account id, handle, the
- disclosure version, the exact disclosure text shown, the scopes the OAuth
- connection actually held at grant time, seed counters, and the revocation
- timestamp and reason. At most one live grant per agent (partial unique
- index).
-
-Seeded rows in `agent_memories` are found by tag (`tags && '{x_seed}'`) and by
-`context->>'consent_id'`, indexed for revocation.
-
-## Source
-
-| Piece | File |
-|---|---|
-| HTTP surface (OAuth refresh, reads, consent gates) | [api/agents/[id]/memory-seed-x.js](../api/agents/[id]/memory-seed-x.js) |
-| Disclosure text, selection, sanitisation, memory rows (pure, tested) | [api/_lib/x-memory-seed.js](../api/_lib/x-memory-seed.js) |
-| Revocation shared by DELETE, disconnect, and account switch | [api/_lib/x-seed-consent.js](../api/_lib/x-seed-consent.js) |
-| OAuth 2.0 PKCE connect and callback | [api/auth/x/[action].js](../api/auth/x/[action].js) |
-| Consent screen (renders the server's disclosure verbatim) | [public/settings/index.html](../public/settings/index.html) |
-| Transform tests | [tests/api/x-memory-seed-transform.test.js](../tests/api/x-memory-seed-transform.test.js), [tests/api/agents-memory-seed.test.js](../tests/api/agents-memory-seed.test.js) |
-
----
-
-<a id="sec-511"></a>
+<a id="sec-536"></a>
> **Source:** `docs/x402-buyer.md` · [↑ table of contents](#table-of-contents)
# x402 Buyer Client
-To consume a paid [x402 endpoint](#sec-514) — ours or anyone's — a
+To consume a paid [x402 endpoint](#sec-539) — ours or anyone's — a
caller has to perform the "402 dance": probe the URL, read the payment challenge,
sign and settle a payment, then retry with an `X-PAYMENT` header. three.ws ships a
buyer client that wraps that whole sequence in one call, with spending-cap
@@ -117454,7 +123771,7 @@ it fails — caps hold even across concurrent calls. The store is Redis-backed w
available. If a call would exceed any window, `buyerFetch` returns
`{ ok: false, abort: true, reason }` **without paying**. The platform-wide ceiling
defaults live in env (`X402_MAX_PER_CALL_ATOMIC`, `X402_MAX_PER_HOUR_ATOMIC`,
-`X402_MAX_PER_DAY_ATOMIC`; see [Configuration](#sec-150)).
+`X402_MAX_PER_DAY_ATOMIC`; see [Configuration](#sec-153)).
## Axios variant
@@ -117477,13 +123794,13 @@ set) back into the payment so attribution survives the round trip.
## Related
-- [x402 protocol](#sec-519) — the underlying challenge/settle mechanics.
-- [x402 paid endpoints](#sec-514) — what you can buy from us.
+- [x402 protocol](#sec-544) — the underlying challenge/settle mechanics.
+- [x402 paid endpoints](#sec-539) — what you can buy from us.
- [Autonomous x402 loop](#sec-105) — uses this client on a schedule.
---
-<a id="sec-512"></a>
+<a id="sec-537"></a>
> **Source:** `docs/x402-dev-tools.md` · [↑ table of contents](#table-of-contents)
@@ -117695,13 +124012,13 @@ implementation against a live server.
---
-<a id="sec-513"></a>
+<a id="sec-538"></a>
> **Source:** `docs/x402-distribution.md` · [↑ table of contents](#table-of-contents)
# x402 Distribution — getting listed and ranked everywhere
-three.ws sells 90+ pay-per-call services over [x402](#sec-519). Building them is
+three.ws sells 90+ pay-per-call services over [x402](#sec-544). Building them is
half the job; the other half is making sure every x402 directory, crawler, and
agent marketplace can find them — and ranks us at the top. This page is the
operating playbook for that distribution: how each surface indexes providers,
@@ -117916,24 +124233,24 @@ script. Everything else above updates itself.
## Related
-- [x402 overview](#sec-519) · [Paid endpoints reference](#sec-514) ·
- [Autonomous loop](#sec-105) · [Buyer client](#sec-511)
+- [x402 overview](#sec-544) · [Paid endpoints reference](#sec-539) ·
+ [Autonomous loop](#sec-105) · [Buyer client](#sec-536)
---
-<a id="sec-514"></a>
+<a id="sec-539"></a>
> **Source:** `docs/x402-endpoints.md` · [↑ table of contents](#table-of-contents)
# x402 Paid Endpoints
three.ws exposes a catalog of HTTP endpoints that charge per call over
-[x402](#sec-519): the caller hits the endpoint, receives a `402 Payment Required`
+[x402](#sec-544): the caller hits the endpoint, receives a `402 Payment Required`
challenge, settles a small USDC payment, and retries with an `X-PAYMENT` header to
get the result. This page is the reference for **our own** paid endpoints, their
prices, and the price-override scheme.
-To call these as a buyer, see [x402 buyer client](#sec-511). For the loop
+To call these as a buyer, see [x402 buyer client](#sec-536). For the loop
that calls many of them on a schedule, see [Autonomous x402 loop](#sec-105).
> Source: handlers under [`api/x402/`](../api/x402), pricing
@@ -117965,7 +124282,7 @@ and, when configured, **USDC on Base** (EVM) and a **BSC leg** (contract-mediate
`direct` scheme, advertised only when `X402_PAY_TO_BSC` is set). On the Solana
rail, `X402_ACCEPT_THREE_SOLANA` optionally advertises **$THREE** alongside USDC
as a second accept entry on the same challenge. The relevant config (see
-[Configuration](#sec-150)):
+[Configuration](#sec-153)):
| Key | Meaning |
| ---------------------------------------------------- | ------------------------------------ |
@@ -118047,7 +124364,7 @@ deliberately not advertised in the 402 challenge or the discovery catalog; it
recirculates funds back to `X402_PAY_TO_SOLANA` to keep the closed loop balanced
([ring-settle.js:18](../api/x402/ring-settle.js#L18)). The full wallet-by-wallet
picture — every receiver, tip, split, treasury, and fee rate — is in the
-[money map](#sec-286).
+[money map](#sec-287).
## Intel & oracle endpoints
@@ -118117,7 +124434,7 @@ datapoints at **$0.0005** USDC each by default, overridable per family with
| Endpoint | Default | Returns |
| ----------------------------------- | --------- | ------------------------------------------ |
-| `/api/x402/agent-reputation` | $0.01 | Cross-chain 0–100 trust score for any wallet/mint/agent id ([trust primitives](#sec-411)). |
+| `/api/x402/agent-reputation` | $0.01 | Cross-chain 0–100 trust score for any wallet/mint/agent id ([trust primitives](#sec-417)). |
| `/api/x402/agent-bouncer` | $0.01 | Access-gate decision for an agent/wallet. |
| `/api/x402/onchain-identity-verify` | $0.005 | Verifies an on-chain identity claim. |
| `/api/x402/skill-marketplace` | $0.001 | Skill listings + pricing. |
@@ -118128,8 +124445,8 @@ datapoints at **$0.0005** USDC each by default, overridable per family with
| Endpoint | Default | Returns |
| ----------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------- |
-| `/api/x402/forge` | tiered | Text/image → 3D model (price by tier; GPU-bound). Every settled generation also lands in the public community gallery (`forge_creations`) stamped with the payer, settle signature, and price; the gallery shows a Solscan-linked "x402" provenance badge. See [Avatar pipeline](#sec-112). |
-| `/api/x402/embody` | $1.00 | **Embodiment.** One call, an agent buys itself a body: prompt or image in → rigged, voiced 3D avatar out, plus a durable persona id and a one-tag `<iframe>` embed for any website. Settles on delivery — a failed generation never charges. See [Embodiment](#sec-184). |
+| `/api/x402/forge` | tiered | Text/image → 3D model (price by tier; GPU-bound). Every settled generation also lands in the public community gallery (`forge_creations`) stamped with the payer, settle signature, and price; the gallery shows a Solscan-linked "x402" provenance badge. See [Avatar pipeline](#sec-113). |
+| `/api/x402/embody` | $1.00 | **Embodiment.** One call, an agent buys itself a body: prompt or image in → rigged, voiced 3D avatar out, plus a durable persona id and a one-tag `<iframe>` embed for any website. Settles on delivery — a failed generation never charges. See [Embodiment](#sec-187). |
| `/api/x402/pipeline` | per stage | **One call, full 3D asset pipeline** — text or GLB in, rigged/optimized game-ready GLB out. Ordered chain of `generate → rig → remesh → gameready → stylize`; the 402 quote is the exact sum of the requested stages. Poll free at `/api/forge?job=<id>` for per-stage progress. See [3D pipeline](#sec-003). |
| `/api/x402/pipeline-rig` | $0.05 | **Pipeline — Rig.** Static GLB in → animation-ready rigged GLB out (skeleton + skin weights). One paid call, durable URL. See [3D pipeline](#sec-003). |
| `/api/x402/pipeline-remesh` | $0.03 | **Pipeline — Remesh.** Retopologize a GLB (triangle/quad/lowpoly, repair, decimate to a face budget) with texture re-baked. GLB in → GLB out. See [3D pipeline](#sec-003). |
@@ -118145,8 +124462,8 @@ datapoints at **$0.0005** USDC each by default, overridable per family with
| Endpoint | Default | Returns |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| [`/api/x402/pump-launch`](#sec-333) | $5.00 | **Pump Launcher** — deploy a brand-new pump.fun token in one paid call. No SOL, no wallet, no account: the server fronts the deploy cost and signs the create tx; you pay USDC. Optional vanity mint. Full flow + funnel in [pump-launcher.md](#sec-333). |
-| [`/api/x402/vanity`](#sec-496) | $0.01–$0.50 (≤3) · $2.50–$10 (4–5, inventory-only) | **Vanity Grinder** — get a brand-new Solana address that starts with your ticker/prefix and/or ends with a suffix, for a branded token mint or agent/treasury wallet. Checks the pre-ground warehouse first for **instant delivery** (`source: "inventory"`); falls back to a live grind (`source: "ground"`) up to 3 chars. Keypair or importable BIP-39 mnemonic; nothing stored; optional `sealTo` ECIES. Full doc: [vanity.md](#sec-496). |
+| [`/api/x402/pump-launch`](#sec-339) | $5.00 | **Pump Launcher** — deploy a brand-new pump.fun token in one paid call. No SOL, no wallet, no account: the server fronts the deploy cost and signs the create tx; you pay USDC. Optional vanity mint. Full flow + funnel in [pump-launcher.md](#sec-339). |
+| [`/api/x402/vanity`](#sec-502) | $0.01–$0.50 (≤3) · $2.50–$10 (4–5, inventory-only) | **Vanity Grinder** — get a brand-new Solana address that starts with your ticker/prefix and/or ends with a suffix, for a branded token mint or agent/treasury wallet. Checks the pre-ground warehouse first for **instant delivery** (`source: "inventory"`); falls back to a live grind (`source: "ground"`) up to 3 chars. Keypair or importable BIP-39 mnemonic; nothing stored; optional `sealTo` ECIES. Full doc: [vanity.md](#sec-502). |
| [`/api/x402/vanity-verifiable`](vanity.md#tier-2--provably-fair-grinder) | $0.02–$0.40 | **Provably-fair grinder** — same grind with a signed commit–reveal receipt proving the key was ground fresh and never kept. Spec: [PROTOCOL-vanity.md](#sec-005). |
| [`/api/x402/vanity-premium`](vanity.md#tier-3--premium-inventory) | $1–$50 by rarity | **Premium inventory** — buy a pre-ground 4–5+ char brandable address from stock. GET lists available patterns + prices (free); `?address=…` buys via x402 and delivers the key **once** (ciphertext destroyed on delivery). Browsable at `/vanity/premium`. |
| `/api/x402/pay-by-name` | $0.001 | Resolve and pay a `@username` / `.sol` name / raw address (see [Agent wallets](#sec-072)); the paid resolve toll is $0.001, the transfer amount itself is buyer-specified. A name that resolves to nothing returns `404 not_found` and the payment is left unsettled, so an unresolvable name is free. |
@@ -118185,7 +124502,7 @@ directory.
| Endpoint | Default | Returns |
| ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/api/x402/analytics` | $0.005 | Platform reports — pick `report=revenue` for the x402 endpoint-revenue summary (see [x402 revenue & receipts](#sec-515)), plus club and listing analytics. |
+| `/api/x402/analytics` | $0.005 | Platform reports — pick `report=revenue` for the x402 endpoint-revenue summary (see [x402 revenue & receipts](#sec-540)), plus club and listing analytics. |
| `/api/x402/mcp-tool-catalog` | $0.001 | Snapshot of every MCP tool (name, paid/free, price, input shape) and a diff vs the last snapshot (added / removed / re-priced tools). |
| **Free read surfaces** | — | — |
| `/api/x402/my-receipts` | free | A buyer's own settled receipts, gated by a wallet signature (SIWX) rather than a payment. |
@@ -118195,10 +124512,10 @@ directory.
| `/api/x402/glb-optimization-report`| free | GLB Size Optimizer catalog feed: what the `glb-size-optimizer` autonomous-loop entry has measured. |
| `/api/x402/network-cost` | free | Cross-chain payment-cost recommendation feed from the hourly cross-chain-cost pipeline snapshots. |
| `/api/x402/runway-lab` | free | Live seed for [/economy-lab](https://three.ws/economy-lab): the fee wallet's real SOL balance and hard floor, the running deploy's governor config, today's spend from `x402_self_facilitator_log`, observed fee-per-settle and 24h demand, and the refusal histogram bucketed by cause (governor / floor / dust guard / duplicate). Read-only; every field is already public through `/api/x402-ring` and `/api/x402-status`. |
-| `/api/x402/echo` | free | httpbin for x402 — decodes your `X-PAYMENT` header (signatures redacted) and returns a local verify verdict without settling. See [x402 dev tools](#sec-512). |
-| `/api/x402/debug` | free | Diagnoses a failed 402 exchange (`{challenge, payment, response}`) into an ordered `{severity, field, problem, fix}` list. See [x402 dev tools](#sec-512). |
-| `/api/x402/verify-receipt` | free | Recomputes a paid response's SHA-256 attestation and confirms a settlement tx on-chain. See [x402 dev tools](#sec-512). |
-| `/api/x402/inference-verify` | free | Audits a metered-inference receipt from a paid `llm-proxy` call: per-check verdicts for the issuer signature, the node's response signature, prompt/response hash re-derivation from raw text, on-chain settlement confirmation, and whether the issuer matches the platform's published signers. See [Run an inference node](#sec-252). |
+| `/api/x402/echo` | free | httpbin for x402 — decodes your `X-PAYMENT` header (signatures redacted) and returns a local verify verdict without settling. See [x402 dev tools](#sec-537). |
+| `/api/x402/debug` | free | Diagnoses a failed 402 exchange (`{challenge, payment, response}`) into an ordered `{severity, field, problem, fix}` list. See [x402 dev tools](#sec-537). |
+| `/api/x402/verify-receipt` | free | Recomputes a paid response's SHA-256 attestation and confirms a settlement tx on-chain. See [x402 dev tools](#sec-537). |
+| `/api/x402/inference-verify` | free | Audits a metered-inference receipt from a paid `llm-proxy` call: per-check verdicts for the issuer signature, the node's response signature, prompt/response hash re-derivation from raw text, on-chain settlement confirmation, and whether the issuer matches the platform's published signers. See [Run an inference node](#sec-253). |
## $THREE only
@@ -118209,22 +124526,22 @@ input and do not promote any specific token.
## Related
-- [Pump Launcher](#sec-333) — the full launch flow, inputs/outputs, and the free `symbol` → launch → `launches` funnel.
-- [x402 protocol](#sec-519) — the challenge/settle mechanics.
-- [x402 buyer client](#sec-511) — how to pay these endpoints in code.
-- [x402 revenue & receipts](#sec-515) — where settled payments are recorded and how to read endpoint revenue.
+- [Pump Launcher](#sec-339) — the full launch flow, inputs/outputs, and the free `symbol` → launch → `launches` funnel.
+- [x402 protocol](#sec-544) — the challenge/settle mechanics.
+- [x402 buyer client](#sec-536) — how to pay these endpoints in code.
+- [x402 revenue & receipts](#sec-540) — where settled payments are recorded and how to read endpoint revenue.
- [Autonomous x402 loop](#sec-105) — the scheduled buyer that drives volume through these endpoints.
-- [MCP tools](#sec-274) — the same capabilities exposed as paid MCP tools.
+- [MCP tools](#sec-275) — the same capabilities exposed as paid MCP tools.
---
-<a id="sec-515"></a>
+<a id="sec-540"></a>
> **Source:** `docs/x402-revenue.md` · [↑ table of contents](#table-of-contents)
# x402 Revenue & Receipts
-Every time someone pays one of three.ws's [paid endpoints](#sec-514), the
+Every time someone pays one of three.ws's [paid endpoints](#sec-539), the
settlement is recorded. This page is the reference for **where that money is
recorded**, how to read endpoint revenue, and how the durable receipt is issued to
the buyer.
@@ -118245,9 +124562,9 @@ tables. They never overlap, and mixing them up will double-count your numbers.
| Direction | Meaning | Table | Surfaced by |
| -------------- | ------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------ |
| **Revenue IN** | Money paid **to** our endpoints for using them | `x402_audit_log` | `/api/x402/analytics?report=revenue` (this page) |
-| **Spend OUT** | Money an agent's wallet **paid out** (tips, trades, agent-to-agent x402) | `agent_custody_events` | The [Money Pulse](#sec-284) at `/api/pulse` |
+| **Spend OUT** | Money an agent's wallet **paid out** (tips, trades, agent-to-agent x402) | `agent_custody_events` | The [Money Pulse](#sec-285) at `/api/pulse` |
-The [Money Pulse](#sec-284) shows the agent economy — one agent paying
+The [Money Pulse](#sec-285) shows the agent economy — one agent paying
another, tips, launches. **This page is the other side of the ledger:** the
platform's own endpoint revenue. A call to `/api/x402/token-intel` writes a
**revenue** row in `x402_audit_log`; it is not an `agent_custody_events` spend and
@@ -118308,6 +124625,21 @@ curl -s "https://three.ws/api/x402-revenue?view=feed&limit=5&network=base" | jq
CSV columns: `timestamp,endpoint,network,chain,amount_usd,asset,payer,tx_hash,tx_url`
(`network` is the raw CAIP-2 id, `chain` its readable label).
+**Malformed params answer 4xx, not 5xx.** `?since=` and `?cursor=` are bound into
+a `::timestamptz` cast, so an unparseable value is rejected before it reaches the
+query rather than surfacing as an opaque 500:
+
+```bash
+curl -s "https://three.ws/api/x402-revenue?since=notadate"
+# {"error":"invalid_since","error_description":"`since` must be an ISO 8601 timestamp"}
+```
+
+`?endpoint=` is sanitized to a slug (`../../etc/passwd` becomes `etcpasswd`), and
+the response echoes the sanitized value in `data.filter.endpoint`, so the filter
+you read back is always the filter that ran. `?period=` and `?network=` fall back
+to the default instead of erroring: an unrecognised period is `24h`, an
+unrecognised network drops the filter.
+
---
## The settlement flow
@@ -118397,7 +124729,7 @@ LIMIT 10;
## The revenue report — `/api/x402/analytics`
You don't have to query SQL. The `analytics` endpoint serves the same numbers,
-pre-aggregated. It is itself a [paid endpoint](#sec-514) ($0.005 default).
+pre-aggregated. It is itself a [paid endpoint](#sec-539) ($0.005 default).
It is a `POST` endpoint: pass `report` and `period` in the JSON body:
```bash
@@ -118473,7 +124805,7 @@ CREATE TABLE x402_receipts (
```
A buyer reads **their own** receipts at
-[`/api/x402/my-receipts`](#sec-514) — that endpoint is free but gated by
+[`/api/x402/my-receipts`](#sec-539) — that endpoint is free but gated by
a wallet signature (SIWX), so a buyer proves ownership of the `payer` address
rather than paying again.
@@ -118606,7 +124938,7 @@ endpoint is up). Add an endpoint to `api/_lib/x402/ring-catalog.js` with
> volume is wash volume: real transactions, fake demand, and trivially detectable
> by anyone clustering the seed wallet on-chain. The honest path to real volume
> is external demand (discovery, real `agent_hire` commerce, the
-> [Circulation engine](#sec-139)), not a bigger self-paid sweep.
+> [Circulation engine](#sec-141)), not a bigger self-paid sweep.
---
@@ -118665,7 +124997,7 @@ kept). EVM/Base settlements are `skipped_non_solana` (not verified here).
## Driving volume through these endpoints
Revenue only exists if the endpoints get called. Two systems drive **organic**
-calls: the [Circulation engine](#sec-139) drives real
+calls: the [Circulation engine](#sec-141) drives real
agent-to-agent commerce, and the [Autonomous x402 loop](#sec-105)'s
oracle/sniper pipelines pay our intel endpoints to feed real downstream
decisions. Both settle **real** USDC through the flow above, from real
@@ -118682,15 +125014,15 @@ settled activity (include it), and label it as such.
## Related
-- [x402 paid endpoints](#sec-514) — the catalog of what charges and how much.
-- [x402 protocol](#sec-519) — the challenge / verify / settle mechanics.
-- [x402 buyer client](#sec-511) — how to settle a 402 challenge in code.
+- [x402 paid endpoints](#sec-539) — the catalog of what charges and how much.
+- [x402 protocol](#sec-544) — the challenge / verify / settle mechanics.
+- [x402 buyer client](#sec-536) — how to settle a 402 challenge in code.
- [Autonomous x402 loop](#sec-105) — the scheduled buyer that drives volume, including the Volume Bootstrap Loop and the reconciliation job.
-- [Money feed](#sec-284) — the agent-spend side of the ledger (the Money Pulse), distinct from endpoint revenue.
+- [Money feed](#sec-285) — the agent-spend side of the ledger (the Money Pulse), distinct from endpoint revenue.
---
-<a id="sec-516"></a>
+<a id="sec-541"></a>
> **Source:** `docs/x402-ring-economy.md` · [↑ table of contents](#table-of-contents)
@@ -119785,7 +126117,7 @@ activation runbook above is the fix.
- [STRUCTURE.md](../STRUCTURE.md) — surface map
- [/api/x402-revenue](../api/x402-revenue.js) — the **public** organic-revenue
feed (self-cycled ring volume is excluded from the "organic" framing here)
-- [docs/x402-revenue.md](#sec-515) — revenue surface docs
+- [docs/x402-revenue.md](#sec-540) — revenue surface docs
- [api/_lib/x402/ring-allowlist.js](../api/_lib/x402/ring-allowlist.js) — the
controlled-wallet set + spend invariants
- [api/cron/x402-ring-leak-scan.js](../api/cron/x402-ring-leak-scan.js) — the
@@ -119793,7 +126125,7 @@ activation runbook above is the fix.
---
-<a id="sec-517"></a>
+<a id="sec-542"></a>
> **Source:** `docs/x402-solana-july-roundup-response.md` · [↑ table of contents](#table-of-contents)
@@ -119811,7 +126143,7 @@ exact permalink from the account's profile before posting; quote-tweet directly
rather than typing a URL by hand.
Two accounts, two jobs, same split used for the IBM Community campaign in
-[event-x-posts.md](#sec-214): `@trythreews` posts the institutional version, `@nichxbt`
+[event-x-posts.md](#sec-519): `@trythreews` posts the institutional version, `@nichxbt`
posts the human one. Do not post both within a few minutes of each other.
---
@@ -119852,7 +126184,7 @@ the specific claim the roundup credited us for. Second choice: the AR drop-in on
---
-<a id="sec-518"></a>
+<a id="sec-543"></a>
> **Source:** `docs/x402-studio.md` · [↑ table of contents](#table-of-contents)
@@ -119862,11 +126194,11 @@ x402 Studio is the merchant console for running a paid x402 business on three.ws
Page: [/x402/studio](https://three.ws/x402/studio)
-APIs: `/api/x402-merchant` (settings), `/api/x402-skus` (products), `/api/sns` (name resolution), `/api/x402/pay-by-name` (USDC send). See [x402: paid agent skills](#sec-519) for the underlying payment protocol.
+APIs: `/api/x402-merchant` (settings), `/api/x402-skus` (products), `/api/sns` (name resolution), `/api/x402/pay-by-name` (USDC send). See [x402: paid agent skills](#sec-544) for the underlying payment protocol.
## Why it exists
-x402 turns any HTTP endpoint into a paid one: the server answers `402 Payment Required` with a manifest, the caller pays in USDC, and the call retries and settles. That primitive is powerful but low-level. Studio is the console on top of it, the difference between "you can hand-write a 402 challenge" and "you can run a storefront." A merchant configures once and gets hosted checkout links, a shareable storefront, a copy-paste pay button, revenue stats, and payouts to a wallet they control, without writing payment code. It is the seller-facing companion to the [x402 buyer client](#sec-511) and the [paid endpoint catalog](#sec-514).
+x402 turns any HTTP endpoint into a paid one: the server answers `402 Payment Required` with a manifest, the caller pays in USDC, and the call retries and settles. That primitive is powerful but low-level. Studio is the console on top of it, the difference between "you can hand-write a 402 challenge" and "you can run a storefront." A merchant configures once and gets hosted checkout links, a shareable storefront, a copy-paste pay button, revenue stats, and payouts to a wallet they control, without writing payment code. It is the seller-facing companion to the [x402 buyer client](#sec-536) and the [paid endpoint catalog](#sec-539).
## How it works
@@ -119952,16 +126284,16 @@ const { tx_base64, blockhash } = await res.json();
## Related
-- [x402: paid agent skills](#sec-519): the payment protocol Studio sits on top of
-- [x402 revenue and receipts](#sec-515): where settled payments are recorded
-- [x402 paid endpoints](#sec-514): the platform's own catalog of paid endpoints
-- [x402 buyer client](#sec-511): the caller side of a 402 challenge
-- [x402 developer tools](#sec-512) and [x402 distribution](#sec-513)
+- [x402: paid agent skills](#sec-544): the payment protocol Studio sits on top of
+- [x402 revenue and receipts](#sec-540): where settled payments are recorded
+- [x402 paid endpoints](#sec-539): the platform's own catalog of paid endpoints
+- [x402 buyer client](#sec-536): the caller side of a 402 challenge
+- [x402 developer tools](#sec-537) and [x402 distribution](#sec-538)
- Pages: [/x402/studio](https://three.ws/x402/studio) · [/x402](https://three.ws/x402)
---
-<a id="sec-519"></a>
+<a id="sec-544"></a>
> **Source:** `docs/x402.md` · [↑ table of contents](#table-of-contents)
@@ -119975,7 +126307,7 @@ of Pump.fun agent payments: callers pay an agent in any SPL token to invoke a
skill, and the agent verifies the on-chain payment before dispatching the
call. It is written for developers wiring paid skills (server side) or paying
for them (client side); the platform's own catalog of paid endpoints lives at
-[x402 paid endpoints](#sec-514).
+[x402 paid endpoints](#sec-539).
**Live activity:** [x402scan dashboard](https://www.x402scan.com/server/17cbd874-52ac-4920-a020-b22ff2489a07)
— browse paid calls, revenue, and per-skill pricing for this server.
@@ -120131,20 +126463,20 @@ Each package has its own repository with a full README, API reference, and examp
## Tutorials
-- [Pay for an x402 service](#sec-451) — settle a paid request end to end with `@three-ws/x402-fetch`.
-- [Build a paid x402 endpoint](#sec-450) — stand up a seller endpoint with `@three-ws/x402-server`.
+- [Pay for an x402 service](#sec-457) — settle a paid request end to end with `@three-ws/x402-fetch`.
+- [Build a paid x402 endpoint](#sec-456) — stand up a seller endpoint with `@three-ws/x402-server`.
## Related
-- [x402 paid endpoints](#sec-514) — the catalog of the platform's own paid endpoints.
-- [x402 revenue & receipts](#sec-515) — where settled payments are recorded and how to read endpoint revenue.
-- [x402 buyer client](#sec-511) — how to settle a 402 challenge in code.
-- [x402 bazaar over MCP](#sec-275) — discover and pay endpoints through the MCP bazaar.
+- [x402 paid endpoints](#sec-539) — the catalog of the platform's own paid endpoints.
+- [x402 revenue & receipts](#sec-540) — where settled payments are recorded and how to read endpoint revenue.
+- [x402 buyer client](#sec-536) — how to settle a 402 challenge in code.
+- [x402 bazaar over MCP](#sec-276) — discover and pay endpoints through the MCP bazaar.
- [Autonomous x402](#sec-105) — agents paying for services on their own.
---
-<a id="sec-520"></a>
+<a id="sec-545"></a>
> **Source:** `docs/zauth/database.md` · [↑ table of contents](#table-of-contents)
@@ -120290,7 +126622,7 @@ Use this endpoint to browse all known x402 endpoints before your agents commit t
---
-<a id="sec-521"></a>
+<a id="sec-546"></a>
> **Source:** `docs/zauth/index.md` · [↑ table of contents](#table-of-contents)
@@ -120310,11 +126642,11 @@ zauth is the security and trust layer that allows agents to act with confidence,
## Products
-### [VectorAI-powered vulnerability scanner. Automated recon, multi-category exploit testing, and detailed security reports for your web applications.Vector](#sec-524)### [RepoScanAI-powered code analysis for crypto communities. Scan GitHub repos for red flags, get trust scores, and compare code similarity across millions of repositories.RepoScan](#sec-523)### [DatabaseLive registry of x402 endpoints. AI agents continuously test and verify endpoints, tracking success rates, pricing, and response data.Database](#sec-520)### [Provider HubManage your x402 endpoints. Monitor health, track agent interactions, configure refunds, and verify your services through our SDK.Provider Hub](#sec-522)
+### [VectorAI-powered vulnerability scanner. Automated recon, multi-category exploit testing, and detailed security reports for your web applications.Vector](#sec-549)### [RepoScanAI-powered code analysis for crypto communities. Scan GitHub repos for red flags, get trust scores, and compare code similarity across millions of repositories.RepoScan](#sec-548)### [DatabaseLive registry of x402 endpoints. AI agents continuously test and verify endpoints, tracking success rates, pricing, and response data.Database](#sec-545)### [Provider HubManage your x402 endpoints. Monitor health, track agent interactions, configure refunds, and verify your services through our SDK.Provider Hub](#sec-547)
---
-<a id="sec-522"></a>
+<a id="sec-547"></a>
> **Source:** `docs/zauth/provider-hub.md` · [↑ table of contents](#table-of-contents)
@@ -120416,7 +126748,7 @@ Supply your EVM or Solana private keys to enable automatic refunds when your end
---
-<a id="sec-523"></a>
+<a id="sec-548"></a>
> **Source:** `docs/zauth/reposcan.md` · [↑ table of contents](#table-of-contents)
@@ -120742,7 +127074,7 @@ TypeScript -@x402/fetch
---
-<a id="sec-524"></a>
+<a id="sec-549"></a>
> **Source:** `docs/zauth/vector.md` · [↑ table of contents](#table-of-contents)
diff --git a/docs/x-posts/threews-avatar-video-script.md b/docs/x-posts/threews-avatar-video-script.md
index d312a77b1..baa2936fe 100644
--- a/docs/x-posts/threews-avatar-video-script.md
+++ b/docs/x-posts/threews-avatar-video-script.md
@@ -1,7 +1,8 @@
# Text-to-video script: the three.ws avatar
Prompts for a video model (Veo, run through ElevenLabs), using a three.ws 3D avatar render as the
-reference image. This file is the **picture**, not the words. The spoken lines live in
+reference image. This file is the **picture**, not the words. The X copy it ships with is in
+[threews-avatar-launch.md](./threews-avatar-launch.md), the spoken lines live in
[metaplex-agent-deployer-video-script.md](./metaplex-agent-deployer-video-script.md), and the
deployer-specific shot list lives in [metaplex-agent-mcp-x-post.md](./metaplex-agent-mcp-x-post.md).
@@ -143,46 +144,3 @@ Keep the pause after "It has no body." That silence is the whole premise.
sound; a violet cloud does not.
- Post as native video, not a link to a video. X will not show a link preview and a video at once,
and the video wins.
-
----
-
-## X post
-
-### Recommended
-
-> Give your AI a body.
->
-> Type a prompt, get a rigged 3D avatar that talks, walks, and holds its own Solana wallet. Drop it
-> on your site with one tag.
->
-> three.ws
-
-Line 1 is the product in five words. Line 2 is the three things that make it different from a
-picture, in the order people care about. The wallet lands last because it is the part nobody expects
-from an avatar company.
-
-### Alternate: builder-facing
-
-> Your agent has a voice, a model, and a name. It still has no body.
->
-> three.ws gives it one: a rigged 3D avatar you can talk to, embed anywhere with a single element,
-> and fund with its own on-chain wallet.
->
-> ```html
-> <script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js"></script>
-> <agent-3d src="agent://base/42"></agent-3d>
-> ```
-
-### Alternate: $THREE-first
-
-> Every 3D agent built on three.ws ships with its own Solana wallet, an on-chain identity, and
-> pay-per-call built in.
->
-> $THREE is the coin of that economy.
->
-> Give your AI a body: three.ws
-
-### Reply slot, post under the main one
-
-> The avatar in the video was generated from a text prompt on three.ws, rigged automatically, and
-> rendered in the browser. No modeling, no rigging software, no download.
diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjs
index 6f121963d..653e3e713 100644
--- a/scripts/audit-docs.mjs
+++ b/scripts/audit-docs.mjs
@@ -281,7 +281,6 @@ const UNPUBLISHED_DOCS = new Map([
['economy-heartbeat', 'internal: scheduled-job operations'],
['economy-master', 'internal: funding-root wallet operations'],
['financial-controls', 'internal: audit-grade money-flow register'],
- ['fomo-verified-x-post', 'internal: ready-to-paste X post drafts; posting is owner-gated'],
['free-crypto-apis', 'internal: engineering research catalog of external free APIs'],
['google-x-accounts', 'internal: outreach directory of external X accounts'],
['ibm-community-article', 'internal: source draft of an IBM Community post'],
@@ -290,20 +289,12 @@ const UNPUBLISHED_DOCS = new Map([
['ibm-community-recap-nichxbt', 'internal: source draft of an IBM Community post'],
['ibm-community-blog-meetup-jessica', 'internal: source draft of an IBM Community post'],
['ibm-community-thread', 'internal: source draft of an IBM Community post'],
- ['ibm-skillsbuild-x-post', 'internal: paste-ready X copy for the SkillsBuild badge, drafted for the owner to post'],
['launch-usecases', 'owner-gated: names a crypto project other than $THREE'],
- ['pumpfun-article-x-post', 'internal: ready-to-paste X post drafts; posting is owner-gated'],
['memetic-launcher', 'owner-gated: names a crypto project other than $THREE'],
['meta-allocator', 'owner-gated: names a crypto project other than $THREE'],
- ['metaplex-agent-deployer-video-script', 'internal: unposted spoken-script drafts for a marketing video'],
- ['metaplex-agent-deployer-x-post', 'internal: unposted X announcement drafts, not a reader-facing doc'],
- ['metaplex-agent-mcp-x-post', 'internal: unposted launch copy and video script, not a reader-facing doc'],
['money-map', 'internal: revenue-share and treasury routing'],
['native-launchpad', 'owner-gated: names a crypto project other than $THREE'],
- ['news-archive-x-post', 'internal: paste-ready X copy for the news archive, drafted for the owner to post'],
- ['onchain-agent-wallets-x-post', 'internal: unposted X announcement drafts, not a reader-facing doc'],
['oracle-trading-mcp-plan', 'internal: build order for the Oracle and trading-agent MCP servers, not a reader-facing product doc'],
- ['oracle-trading-mcp-x-post', 'internal: paste-ready X copy for the MCP launch, drafted for the owner to post'],
['nvidia-apps-catalog-listing', 'internal: paste-ready listing copy and portal steps for the NVIDIA Inception catalog'],
['nvidia-apps-catalog-request', 'internal: outbound email asking NVIDIA to publish the catalog listing'],
['nvidia-visibility-map', 'internal: outreach priorities and unclaimed program benefits across every NVIDIA surface'],
@@ -321,8 +312,6 @@ const UNPUBLISHED_DOCS = new Map([
['threews-avatar-veo-script', 'internal: unposted text-to-video prompts and X drafts for a marketing video'],
['trading-experiment', 'owner-gated: names a crypto project other than $THREE'],
['trading-hub', 'in-flight: landed mid-session, register with its /trading page'],
- ['event-x-posts', 'internal: ready-to-paste X post drafts; posting is owner-gated'],
- ['x-meetup-posts', 'internal: ready-to-paste X post drafts; posting is owner-gated'],
['x402-solana-july-roundup-response', 'internal: ready-to-paste X reply draft; posting is owner-gated'],
['x-archive', 'internal: marketing analytics over our own X timeline, not a reader-facing product doc'],
]);