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.

chore(marketing): drop the mainstgrowth link-card worker and the stale third-party launch drafts baked into docs/ALL.md

nirholasb13e1d5d01b7
diff --git a/docs/ALL.md b/docs/ALL.md
index c0bdf9965..23f17f26d 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-26 from **568 files** (~8111 KB).
+> Single-file snapshot of every document under [`docs/`](.). Generated 2026-09-01 from **594 files** (~8542 KB).
> The individual source files remain the canonical, editable copies — this file is a read-only aggregate.
## Table of contents
@@ -11,628 +11,651 @@
- [3d-api.md](#sec-001)
- [3d-asset-pipeline.md](#sec-002)
- [3d-pipeline.md](#sec-003)
-- [DESIGN-TOKENS.md](#sec-004)
-- [PROTOCOL-vanity.md](#sec-005)
-- [README.md](#sec-006)
-- [a2a-payments.md](#sec-007)
-- [agenc.md](#sec-008)
-- [agent-abilities.md](#sec-009)
-- [agent-economy-volume.md](#sec-052)
-- [agent-identities.md](#sec-053)
-- [agent-index.md](#sec-054)
-- [agent-manifest.md](#sec-055)
-- [agent-reputation.md](#sec-056)
-- [agent-runtime.md](#sec-057)
-- [agent-screen-control.md](#sec-058)
-- [agent-shell.md](#sec-059)
-- [agent-skills.md](#sec-060)
-- [agent-sniper.md](#sec-061)
-- [agent-studio.md](#sec-062)
-- [agent-symphony.md](#sec-063)
-- [agent-system.md](#sec-064)
-- [agent-tokens.md](#sec-070)
-- [agent-wallet-api.md](#sec-071)
-- [agent-wallets.md](#sec-072)
-- [agents-vs-avatars.md](#sec-073)
-- [agi.md](#sec-074)
-- [agora.md](#sec-075)
-- [airdrops.md](#sec-089)
-- [alpha-copilot.md](#sec-090)
-- [analytics-retention.md](#sec-091)
-- [animation-studio.md](#sec-092)
-- [animations.md](#sec-093)
-- [announcement-coverage-telegram.md](#sec-094)
-- [announcement-coverage.md](#sec-095)
-- [api-reference.md](#sec-096)
-- [ar-studio.md](#sec-098)
-- [ar.md](#sec-099)
-- [architecture.md](#sec-100)
-- [assistant-widget.md](#sec-101)
-- [atlas.md](#sec-102)
-- [authentication.md](#sec-103)
-- [autonomous-economy.md](#sec-104)
-- [autonomous-x402.md](#sec-105)
-- [autopilot.md](#sec-106)
-- [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)
-- [community.md](#sec-151)
-- [compose.md](#sec-152)
-- [concierge.md](#sec-153)
-- [configuration.md](#sec-154)
-- [contributing.md](#sec-161)
-- [copy-trading.md](#sec-166)
-- [cosmos.md](#sec-167)
-- [creator-portfolio.md](#sec-168)
-- [crews.md](#sec-169)
-- [crypto-api.md](#sec-170)
-- [custody.md](#sec-171)
-- [daily-forge.md](#sec-172)
-- [daily-match.md](#sec-173)
-- [demo-routes.md](#sec-174)
-- [deployment.md](#sec-175)
-- [deployments.md](#sec-176)
-- [developer-platform.md](#sec-177)
-- [diorama.md](#sec-178)
-- [do-i-need-crypto.md](#sec-179)
-- [docs-world.md](#sec-180)
-- [draft-agent-mint.md](#sec-181)
-- [economy-heartbeat.md](#sec-182)
-- [economy-master.md](#sec-183)
-- [economy-solver.md](#sec-184)
-- [editor.md](#sec-185)
-- [education-pilot-bucharest.md](#sec-186)
-- [embedding.md](#sec-187)
-- [embody.md](#sec-188)
-- [erc8004.md](#sec-189)
-- [event-souvenirs.md](#sec-217)
-- [examples.md](#sec-218)
-- [exit-lab.md](#sec-219)
-- [fact-check.md](#sec-220)
-- [farcaster-memory-seeding.md](#sec-221)
-- [financial-controls.md](#sec-222)
-- [first-contribution.md](#sec-223)
-- [forge-background-generation.md](#sec-224)
-- [forge-off.md](#sec-225)
-- [forge-pipeline.md](#sec-226)
-- [forge.md](#sec-227)
-- [forged.md](#sec-228)
-- [free-crypto-apis.md](#sec-229)
-- [free-llm-providers.md](#sec-230)
-- [galaxy.md](#sec-231)
-- [generation-watch.md](#sec-232)
-- [genesis.md](#sec-233)
-- [genome.md](#sec-234)
-- [ghost-copy.md](#sec-235)
-- [github-memory-seeding.md](#sec-236)
-- [google-x-accounts.md](#sec-237)
-- [guardian.md](#sec-238)
-- [guards.md](#sec-239)
-- [hold-to-access.md](#sec-240)
-- [how-forge-works.md](#sec-241)
-- [how-it-works.md](#sec-242)
-- [huggingface.md](#sec-243)
-- [i18n.md](#sec-244)
-- [ibm-community-article.md](#sec-245)
-- [ibm-community-blog-meetup-jessica.md](#sec-246)
-- [ibm-community-live-reaction-jessica.md](#sec-247)
-- [ibm-community-recap-jessica.md](#sec-248)
-- [ibm-community-recap-nichxbt.md](#sec-249)
-- [ibm-community-thread.md](#sec-250)
-- [ibm-community.md](#sec-251)
-- [ibm-x402-mcp.md](#sec-252)
-- [ibm.md](#sec-253)
-- [image-to-3d.md](#sec-254)
-- [in-game-economy.md](#sec-255)
-- [inference-node-operator.md](#sec-256)
-- [integrations.md](#sec-257)
-- [introduction.md](#sec-258)
-- [irl.md](#sec-259)
-- [js-api.md](#sec-261)
-- [kol-tracker.md](#sec-262)
-- [labor-market.md](#sec-263)
-- [launch-usecases.md](#sec-264)
-- [layers.md](#sec-265)
-- [likeness-eval.md](#sec-266)
-- [lipsync.md](#sec-267)
-- [liquid-glass.md](#sec-268)
-- [listings.md](#sec-269)
-- [live-docs.md](#sec-270)
-- [live-steps.md](#sec-271)
-- [make-your-agent.md](#sec-272)
-- [market-data-api.md](#sec-273)
-- [marketplace.md](#sec-277)
-- [mcp-3d-studio.md](#sec-278)
-- [mcp-agent.md](#sec-279)
-- [mcp-safety.md](#sec-280)
-- [mcp-studio.md](#sec-281)
-- [mcp-tools.md](#sec-282)
-- [mcp-x402-bazaar.md](#sec-283)
-- [mcp.md](#sec-284)
-- [media-api.md](#sec-285)
-- [memetic-launcher.md](#sec-286)
-- [memory.md](#sec-287)
-- [meta-allocator.md](#sec-288)
-- [mint-mark.md](#sec-289)
-- [minted.md](#sec-290)
-- [mocap-studio.md](#sec-291)
-- [money-feed.md](#sec-292)
-- [money-flow-map.md](#sec-293)
-- [money-map.md](#sec-294)
-- [monitor.md](#sec-295)
-- [motion-swap.md](#sec-296)
-- [multi-agent.md](#sec-297)
-- [native-launchpad.md](#sec-298)
-- [news-rights.md](#sec-299)
-- [notifications.md](#sec-300)
-- [nvidia-apps-catalog-listing.md](#sec-301)
-- [nvidia-apps-catalog-request.md](#sec-302)
-- [nvidia-inception.md](#sec-303)
-- [nvidia-models.md](#sec-304)
-- [nvidia-nemotron-ask-the-experts-questions.md](#sec-305)
-- [nvidia-nemotron-spotlight.md](#sec-306)
-- [nvidia-visibility-map.md](#sec-307)
-- [object-library.md](#sec-308)
-- [okx-marketplace.md](#sec-309)
-- [onboarding-tier.md](#sec-310)
-- [onchain-agents.md](#sec-311)
-- [open-source-ecosystem.md](#sec-312)
-- [open-source-footprint.md](#sec-313)
-- [open-source-friday-plan.md](#sec-314)
-- [openai-community-3d-studio-post.md](#sec-315)
-- [openai-listing-channels.md](#sec-316)
-- [oracle-trading-mcp-plan.md](#sec-325)
-- [oracle.md](#sec-326)
-- [overlay-audit.md](#sec-327)
-- [package-extraction.md](#sec-328)
-- [partners.md](#sec-329)
-- [pay-skills-listing.md](#sec-331)
-- [payment-sessions.md](#sec-332)
-- [permissions.md](#sec-333)
-- [persona-hub.md](#sec-334)
-- [pill-mascot.md](#sec-335)
-- [plan-checkout.md](#sec-336)
-- [play-boot-performance.md](#sec-337)
-- [play-forge-in-world.md](#sec-338)
-- [play-hardening.md](#sec-339)
-- [play-live-events.md](#sec-340)
-- [play-vehicles.md](#sec-341)
-- [popular-3d-github-repos.md](#sec-342)
-- [portfolio.md](#sec-343)
-- [premium.md](#sec-344)
-- [press-kit.md](#sec-345)
-- [procedural-animation.md](#sec-346)
-- [provenance.md](#sec-347)
-- [pump-claims-channel.md](#sec-348)
-- [pump-fun-mcp-edge.md](#sec-349)
-- [pump-launch-repos.md](#sec-350)
-- [pump-launcher.md](#sec-351)
-- [pump-platform-fee.md](#sec-352)
-- [quick-start.md](#sec-373)
-- [radar.md](#sec-374)
-- [reasoning-ledger.md](#sec-375)
-- [recurring-payments.md](#sec-376)
-- [remix.md](#sec-377)
-- [reputation-staking-market.md](#sec-378)
-- [reputation.md](#sec-379)
-- [restyle.md](#sec-380)
-- [rig-doctor.md](#sec-381)
-- [risk-acknowledgment.md](#sec-382)
-- [robinhood-chain-markets.md](#sec-383)
-- [sas-attestations.md](#sec-384)
-- [scene-studio.md](#sec-385)
-- [sdk.md](#sec-386)
-- [security.md](#sec-387)
-- [seed-quality.md](#sec-388)
-- [selfie-to-avatar.md](#sec-389)
-- [share-and-embed.md](#sec-390)
-- [shared-utilities.md](#sec-391)
-- [showcase.md](#sec-392)
-- [sign-language.md](#sec-393)
-- [signals.md](#sec-394)
-- [site-performance.md](#sec-395)
-- [sketchfab.md](#sec-396)
-- [skill-bundles.md](#sec-397)
-- [skill-royalties.md](#sec-398)
-- [skills.md](#sec-399)
-- [smart-contracts.md](#sec-400)
-- [smart-money.md](#sec-401)
-- [sniper-autonomy.md](#sec-402)
-- [social-layer.md](#sec-403)
-- [solana-pumpfun.md](#sec-404)
-- [solana-reputation.md](#sec-405)
-- [solana.md](#sec-406)
-- [spatial-mcp.md](#sec-407)
-- [splat.md](#sec-409)
-- [stage.md](#sec-410)
-- [start-here.md](#sec-411)
-- [strategy-objects.md](#sec-412)
-- [swarms.md](#sec-413)
-- [syndication.md](#sec-414)
-- [talking-avatar-video.md](#sec-415)
-- [terminal.md](#sec-416)
-- [the-first-19-weeks.md](#sec-417)
-- [three-microbuy.md](#sec-418)
-- [three-thesis.md](#sec-419)
-- [timeline.md](#sec-420)
-- [token-gated-3d-embeds.md](#sec-421)
-- [tokens-xyz.md](#sec-422)
-- [trader-card.md](#sec-423)
-- [trader-passport.md](#sec-424)
-- [trading-arenas.md](#sec-425)
-- [trading-copilot.md](#sec-426)
-- [trading-experiment.md](#sec-427)
-- [trading-hub.md](#sec-428)
-- [trading-surfaces.md](#sec-429)
-- [triage.md](#sec-430)
-- [troubleshooting.md](#sec-431)
-- [trust-primitives.md](#sec-432)
-- [ui-juice.md](#sec-502)
-- [user-wallet.md](#sec-503)
-- [validation.md](#sec-516)
-- [vanity.md](#sec-517)
-- [vaults.md](#sec-518)
-- [viability.md](#sec-519)
-- [viewer.md](#sec-520)
-- [voice-lab.md](#sec-521)
-- [walk-leaderboard.md](#sec-522)
-- [web-component.md](#sec-523)
-- [widget-api.md](#sec-524)
-- [widget-studio.md](#sec-525)
-- [widgets.md](#sec-526)
-- [world-lines.md](#sec-527)
-- [x-archive.md](#sec-528)
-- [x-memory-seeding.md](#sec-530)
-- [x402-buyer.md](#sec-556)
-- [x402-dev-tools.md](#sec-557)
-- [x402-distribution.md](#sec-558)
-- [x402-endpoints.md](#sec-559)
-- [x402-ring-economy.md](#sec-560)
-- [x402-solana-july-roundup-response.md](#sec-561)
-- [x402-studio.md](#sec-562)
-- [x402.md](#sec-563)
+- [3d-vision.md](#sec-004)
+- [DESIGN-TOKENS.md](#sec-005)
+- [PROTOCOL-vanity.md](#sec-006)
+- [README.md](#sec-007)
+- [a2a-payments.md](#sec-008)
+- [agenc.md](#sec-009)
+- [agent-abilities.md](#sec-010)
+- [agent-economy-volume.md](#sec-053)
+- [agent-identities.md](#sec-054)
+- [agent-index.md](#sec-055)
+- [agent-manifest.md](#sec-056)
+- [agent-reputation.md](#sec-057)
+- [agent-runtime.md](#sec-058)
+- [agent-screen-control.md](#sec-059)
+- [agent-shell.md](#sec-060)
+- [agent-skills.md](#sec-061)
+- [agent-sniper.md](#sec-062)
+- [agent-studio.md](#sec-063)
+- [agent-symphony.md](#sec-064)
+- [agent-system.md](#sec-065)
+- [agent-tokens.md](#sec-071)
+- [agent-vitals.md](#sec-072)
+- [agent-wallet-api.md](#sec-073)
+- [agent-wallets.md](#sec-074)
+- [agents-vs-avatars.md](#sec-075)
+- [agi.md](#sec-076)
+- [agora.md](#sec-077)
+- [airdrops.md](#sec-091)
+- [alpha-copilot.md](#sec-092)
+- [analytics-retention.md](#sec-093)
+- [animation-studio.md](#sec-094)
+- [animations.md](#sec-095)
+- [announcement-coverage-telegram.md](#sec-096)
+- [announcement-coverage.md](#sec-097)
+- [api-reference.md](#sec-098)
+- [ar-studio.md](#sec-100)
+- [ar.md](#sec-101)
+- [architecture.md](#sec-102)
+- [assistant-widget.md](#sec-103)
+- [atlas.md](#sec-104)
+- [authentication.md](#sec-105)
+- [autonomous-economy.md](#sec-106)
+- [autonomous-x402.md](#sec-107)
+- [autopilot.md](#sec-108)
+- [avatar-artifact.md](#sec-109)
+- [avatar-cli.md](#sec-110)
+- [avatar-creation.md](#sec-111)
+- [avatar-engines.md](#sec-112)
+- [avatar-fidelity-program.md](#sec-113)
+- [avatar-inspector.md](#sec-114)
+- [avatar-pipeline.md](#sec-115)
+- [avatar-reconstruction.md](#sec-116)
+- [avatar-studio.md](#sec-117)
+- [avatar-thumbnails.md](#sec-118)
+- [avatar-wardrobe.md](#sec-119)
+- [aws-builder-center-agent-payment-sessions.md](#sec-120)
+- [aws-builder-center-marketplace-x402.md](#sec-121)
+- [aws-builder-center-mcp-agents.md](#sec-122)
+- [aws-builder-center.md](#sec-123)
+- [aws-marketplace-listing-kit.md](#sec-124)
+- [aws-marketplace.md](#sec-125)
+- [aws-partner-spotlight.md](#sec-126)
+- [big-tech-recognition-week.md](#sec-127)
+- [bnb-babt-findings.md](#sec-128)
+- [bnb-payments.md](#sec-129)
+- [bnb-vault.md](#sec-130)
+- [bnb-world.md](#sec-131)
+- [brain.md](#sec-132)
+- [brownout.md](#sec-133)
+- [btn-pill-migration.md](#sec-134)
+- [build.md](#sec-135)
+- [ca2x402.md](#sec-136)
+- [capture.md](#sec-137)
+- [changelog.md](#sec-138)
+- [character-library.md](#sec-139)
+- [character-studio.md](#sec-140)
+- [chatgpt-3d-studio-gpt.md](#sec-141)
+- [chatgpt-ar.md](#sec-142)
+- [checkout-companion.md](#sec-143)
+- [choreography.md](#sec-144)
+- [circulation-engine.md](#sec-145)
+- [clash.md](#sec-146)
+- [clip-director.md](#sec-147)
+- [coin-launches.md](#sec-148)
+- [coin-pages.md](#sec-149)
+- [coin-wars.md](#sec-150)
+- [coingecko-listing-update-2026-08.md](#sec-151)
+- [coinmarketcap-article-play.md](#sec-152)
+- [coinmarketcap-article.md](#sec-153)
+- [coinmarketcap-live-article.md](#sec-154)
+- [community.md](#sec-155)
+- [companion.md](#sec-156)
+- [compose.md](#sec-157)
+- [concierge.md](#sec-158)
+- [configuration.md](#sec-159)
+- [contributing.md](#sec-166)
+- [copy-trading.md](#sec-171)
+- [cosmos.md](#sec-172)
+- [create-agent.md](#sec-173)
+- [creator-portfolio.md](#sec-174)
+- [crews.md](#sec-175)
+- [crypto-api.md](#sec-176)
+- [custody.md](#sec-177)
+- [daily-forge.md](#sec-178)
+- [daily-match.md](#sec-179)
+- [demo-routes.md](#sec-180)
+- [deployment.md](#sec-181)
+- [deployments.md](#sec-182)
+- [developer-platform.md](#sec-183)
+- [diorama.md](#sec-184)
+- [do-i-need-crypto.md](#sec-185)
+- [docs-world.md](#sec-186)
+- [draft-agent-mint.md](#sec-187)
+- [economy-heartbeat.md](#sec-188)
+- [economy-master.md](#sec-189)
+- [economy-solver.md](#sec-190)
+- [editor.md](#sec-191)
+- [education-pilot-bucharest.md](#sec-192)
+- [embedding.md](#sec-193)
+- [embody.md](#sec-194)
+- [erc8004.md](#sec-195)
+- [event-souvenirs.md](#sec-223)
+- [examples.md](#sec-224)
+- [exit-lab.md](#sec-225)
+- [fact-check.md](#sec-226)
+- [farcaster-memory-seeding.md](#sec-227)
+- [feedback.md](#sec-228)
+- [financial-controls.md](#sec-229)
+- [first-contribution.md](#sec-230)
+- [forge-background-generation.md](#sec-231)
+- [forge-off.md](#sec-232)
+- [forge-pipeline.md](#sec-233)
+- [forge.md](#sec-234)
+- [forged.md](#sec-235)
+- [free-crypto-apis.md](#sec-236)
+- [free-llm-providers.md](#sec-237)
+- [galaxy.md](#sec-238)
+- [generation-watch.md](#sec-239)
+- [genesis.md](#sec-240)
+- [genome.md](#sec-241)
+- [ghost-copy.md](#sec-242)
+- [github-memory-seeding.md](#sec-243)
+- [glance.md](#sec-244)
+- [google-x-accounts.md](#sec-245)
+- [guardian.md](#sec-246)
+- [guards.md](#sec-247)
+- [herald.md](#sec-248)
+- [hold-to-access.md](#sec-249)
+- [how-forge-works.md](#sec-250)
+- [how-it-works.md](#sec-251)
+- [huggingface-3d-ai-agent-platform.md](#sec-252)
+- [huggingface.md](#sec-253)
+- [i18n.md](#sec-254)
+- [ibm-community-article.md](#sec-255)
+- [ibm-community-blog-meetup-jessica.md](#sec-256)
+- [ibm-community-live-reaction-jessica.md](#sec-257)
+- [ibm-community-recap-jessica.md](#sec-258)
+- [ibm-community-recap-nichxbt.md](#sec-259)
+- [ibm-community-thread.md](#sec-260)
+- [ibm-community.md](#sec-261)
+- [ibm-x402-mcp.md](#sec-262)
+- [ibm.md](#sec-263)
+- [image-to-3d.md](#sec-264)
+- [in-game-economy.md](#sec-265)
+- [inference-node-operator.md](#sec-266)
+- [integrations.md](#sec-267)
+- [introduction.md](#sec-268)
+- [ios-app.md](#sec-269)
+- [irl.md](#sec-270)
+- [js-api.md](#sec-272)
+- [knock.md](#sec-273)
+- [kol-tracker.md](#sec-274)
+- [labor-market.md](#sec-275)
+- [launch-usecases.md](#sec-276)
+- [layers.md](#sec-277)
+- [likeness-eval.md](#sec-278)
+- [lipsync.md](#sec-279)
+- [liquid-glass.md](#sec-280)
+- [listings.md](#sec-281)
+- [live-docs.md](#sec-282)
+- [live-steps.md](#sec-283)
+- [make-your-agent.md](#sec-284)
+- [market-data-api.md](#sec-285)
+- [marketplace.md](#sec-286)
+- [mcp-3d-studio.md](#sec-287)
+- [mcp-agent.md](#sec-288)
+- [mcp-safety.md](#sec-289)
+- [mcp-studio.md](#sec-290)
+- [mcp-tools.md](#sec-291)
+- [mcp-x402-bazaar.md](#sec-292)
+- [mcp.md](#sec-293)
+- [media-api.md](#sec-294)
+- [memetic-launcher.md](#sec-295)
+- [memory.md](#sec-296)
+- [meta-allocator.md](#sec-297)
+- [mint-mark.md](#sec-298)
+- [minted.md](#sec-299)
+- [mocap-studio.md](#sec-300)
+- [model-diff.md](#sec-301)
+- [money-feed.md](#sec-302)
+- [money-flow-map.md](#sec-303)
+- [money-map.md](#sec-304)
+- [monitor.md](#sec-305)
+- [motion-swap.md](#sec-306)
+- [multi-agent.md](#sec-307)
+- [native-launchpad.md](#sec-308)
+- [native-widgets.md](#sec-309)
+- [news-rights.md](#sec-310)
+- [notifications.md](#sec-311)
+- [nvidia-apps-catalog-listing.md](#sec-312)
+- [nvidia-apps-catalog-request.md](#sec-313)
+- [nvidia-inception.md](#sec-314)
+- [nvidia-models.md](#sec-315)
+- [nvidia-nemotron-ask-the-experts-questions.md](#sec-316)
+- [nvidia-nemotron-spotlight.md](#sec-317)
+- [nvidia-visibility-map.md](#sec-318)
+- [object-library.md](#sec-319)
+- [okx-marketplace.md](#sec-320)
+- [onboarding-tier.md](#sec-321)
+- [onchain-agents.md](#sec-322)
+- [open-source-ecosystem.md](#sec-323)
+- [open-source-footprint.md](#sec-324)
+- [open-source-friday-plan.md](#sec-325)
+- [openai-community-3d-studio-post.md](#sec-326)
+- [openai-listing-channels.md](#sec-327)
+- [oracle-model.md](#sec-336)
+- [oracle-trading-mcp-plan.md](#sec-337)
+- [oracle.md](#sec-338)
+- [overlay-audit.md](#sec-339)
+- [package-extraction.md](#sec-340)
+- [partners.md](#sec-341)
+- [pay-skills-listing.md](#sec-343)
+- [payment-sessions.md](#sec-344)
+- [permissions.md](#sec-345)
+- [persona-hub.md](#sec-346)
+- [pill-mascot.md](#sec-347)
+- [plan-checkout.md](#sec-348)
+- [play-boot-performance.md](#sec-349)
+- [play-forge-in-world.md](#sec-350)
+- [play-hardening.md](#sec-351)
+- [play-live-events.md](#sec-352)
+- [play-vehicles.md](#sec-353)
+- [popular-3d-github-repos.md](#sec-354)
+- [portal.md](#sec-355)
+- [portfolio.md](#sec-356)
+- [premium.md](#sec-357)
+- [press-kit.md](#sec-358)
+- [procedural-animation.md](#sec-359)
+- [provenance.md](#sec-360)
+- [pump-claims-channel.md](#sec-361)
+- [pump-fun-mcp-edge.md](#sec-362)
+- [pump-launch-repos.md](#sec-363)
+- [pump-launcher.md](#sec-364)
+- [pump-platform-fee.md](#sec-365)
+- [quick-start.md](#sec-386)
+- [radar.md](#sec-387)
+- [reasoning-ledger.md](#sec-388)
+- [recurring-payments.md](#sec-389)
+- [remix.md](#sec-390)
+- [reputation-staking-market.md](#sec-391)
+- [reputation.md](#sec-392)
+- [resilience.md](#sec-393)
+- [restyle.md](#sec-394)
+- [rig-doctor.md](#sec-395)
+- [risk-acknowledgment.md](#sec-396)
+- [robinhood-chain-markets.md](#sec-397)
+- [sas-attestations.md](#sec-398)
+- [scene-studio.md](#sec-399)
+- [sdk.md](#sec-400)
+- [security.md](#sec-401)
+- [seed-quality.md](#sec-402)
+- [seeker-app.md](#sec-403)
+- [seeker-publishing.md](#sec-404)
+- [seeker-submission-day.md](#sec-405)
+- [selfie-to-avatar.md](#sec-406)
+- [share-and-embed.md](#sec-407)
+- [shared-utilities.md](#sec-408)
+- [shipfeed.md](#sec-409)
+- [showcase.md](#sec-410)
+- [sign-language.md](#sec-411)
+- [signals.md](#sec-412)
+- [site-performance.md](#sec-413)
+- [sketchfab.md](#sec-414)
+- [skill-bundles.md](#sec-415)
+- [skill-royalties.md](#sec-416)
+- [skills.md](#sec-417)
+- [smart-contracts.md](#sec-418)
+- [smart-money.md](#sec-419)
+- [sniper-autonomy.md](#sec-420)
+- [social-layer.md](#sec-421)
+- [solana-pumpfun.md](#sec-422)
+- [solana-reputation.md](#sec-423)
+- [solana.md](#sec-424)
+- [spatial-mcp.md](#sec-425)
+- [splat.md](#sec-427)
+- [stage.md](#sec-428)
+- [start-here.md](#sec-429)
+- [strategy-objects.md](#sec-430)
+- [swarms.md](#sec-431)
+- [syndication.md](#sec-432)
+- [talking-avatar-video.md](#sec-433)
+- [terminal.md](#sec-434)
+- [the-first-19-weeks.md](#sec-435)
+- [three-microbuy.md](#sec-436)
+- [three-thesis.md](#sec-437)
+- [timeline.md](#sec-438)
+- [token-gated-3d-embeds.md](#sec-439)
+- [tokens-xyz.md](#sec-440)
+- [trader-card.md](#sec-441)
+- [trader-passport.md](#sec-442)
+- [trading-arenas.md](#sec-443)
+- [trading-copilot.md](#sec-444)
+- [trading-experiment.md](#sec-445)
+- [trading-hub.md](#sec-446)
+- [trading-surfaces.md](#sec-447)
+- [triage.md](#sec-448)
+- [troubleshooting.md](#sec-449)
+- [trust-primitives.md](#sec-450)
+- [tty-avatar.md](#sec-451)
+- [tty.md](#sec-452)
+- [ui-juice.md](#sec-522)
+- [user-wallet.md](#sec-523)
+- [validation.md](#sec-536)
+- [vanity.md](#sec-537)
+- [vaults.md](#sec-538)
+- [viability.md](#sec-539)
+- [viewer.md](#sec-540)
+- [voice-lab.md](#sec-541)
+- [walk-leaderboard.md](#sec-542)
+- [web-component.md](#sec-543)
+- [widget-api.md](#sec-544)
+- [widget-studio.md](#sec-545)
+- [widgets.md](#sec-546)
+- [witness.md](#sec-547)
+- [world-lines.md](#sec-548)
+- [x-account-appeal.md](#sec-549)
+- [x-accounts.md](#sec-550)
+- [x-archive.md](#sec-551)
+- [x-memory-seeding.md](#sec-553)
+- [x402-buyer.md](#sec-581)
+- [x402-dev-tools.md](#sec-582)
+- [x402-distribution.md](#sec-583)
+- [x402-endpoints.md](#sec-584)
+- [x402-preflight.md](#sec-585)
+- [x402-ring-economy.md](#sec-586)
+- [x402-solana-july-roundup-response.md](#sec-587)
+- [x402-studio.md](#sec-588)
+- [x402.md](#sec-589)
### agent-abilities
-- [agent-abilities/ABILITIES.md](#sec-010)
-- [agent-abilities/FULL-ARTICLE.md](#sec-011)
-- [agent-abilities/PRODUCTION-NOTES.md](#sec-012)
-- [agent-abilities/TTS-SCRIPT.md](#sec-013)
-- [agent-abilities/chapters/01-the-body.md](#sec-014)
-- [agent-abilities/chapters/02-motion.md](#sec-015)
-- [agent-abilities/chapters/03-creation-studios.md](#sec-016)
-- [agent-abilities/chapters/04-the-mind.md](#sec-017)
-- [agent-abilities/chapters/05-the-voice.md](#sec-018)
-- [agent-abilities/chapters/06-identity-reputation.md](#sec-019)
-- [agent-abilities/chapters/07-skills.md](#sec-020)
-- [agent-abilities/chapters/08-screens.md](#sec-021)
-- [agent-abilities/chapters/09-the-agent-economy.md](#sec-022)
-- [agent-abilities/chapters/10-the-agent-wallet.md](#sec-023)
-- [agent-abilities/chapters/11-markets-intelligence.md](#sec-024)
-- [agent-abilities/chapters/12-live-worlds-social-irl.md](#sec-025)
-- [agent-abilities/chapters/13-agents-everywhere.md](#sec-026)
-- [agent-abilities/chapters/14-the-developer-platform.md](#sec-027)
-- [agent-abilities/chapters/15-appendix.md](#sec-028)
-- [agent-abilities/wallet/01-balance.md](#sec-029)
-- [agent-abilities/wallet/02-go-live.md](#sec-030)
-- [agent-abilities/wallet/03-portfolio.md](#sec-031)
-- [agent-abilities/wallet/04-deposit.md](#sec-032)
-- [agent-abilities/wallet/05-copilot.md](#sec-033)
-- [agent-abilities/wallet/06-trust.md](#sec-034)
-- [agent-abilities/wallet/07-signals.md](#sec-035)
-- [agent-abilities/wallet/08-trade.md](#sec-036)
-- [agent-abilities/wallet/09-pulse.md](#sec-037)
-- [agent-abilities/wallet/10-snipe.md](#sec-038)
-- [agent-abilities/wallet/11-earn.md](#sec-039)
-- [agent-abilities/wallet/12-orders.md](#sec-040)
-- [agent-abilities/wallet/13-autopilot.md](#sec-041)
-- [agent-abilities/wallet/14-intents.md](#sec-042)
-- [agent-abilities/wallet/15-pay.md](#sec-043)
-- [agent-abilities/wallet/16-vanity.md](#sec-044)
-- [agent-abilities/wallet/17-policy.md](#sec-045)
-- [agent-abilities/wallet/18-withdraw.md](#sec-046)
-- [agent-abilities/wallet/19-give.md](#sec-047)
-- [agent-abilities/wallet/20-proof-of-custody.md](#sec-048)
-- [agent-abilities/wallet/21-access.md](#sec-049)
-- [agent-abilities/wallet/22-recovery.md](#sec-050)
-- [agent-abilities/wallet/23-self-defense.md](#sec-051)
+- [agent-abilities/ABILITIES.md](#sec-011)
+- [agent-abilities/FULL-ARTICLE.md](#sec-012)
+- [agent-abilities/PRODUCTION-NOTES.md](#sec-013)
+- [agent-abilities/TTS-SCRIPT.md](#sec-014)
+- [agent-abilities/chapters/01-the-body.md](#sec-015)
+- [agent-abilities/chapters/02-motion.md](#sec-016)
+- [agent-abilities/chapters/03-creation-studios.md](#sec-017)
+- [agent-abilities/chapters/04-the-mind.md](#sec-018)
+- [agent-abilities/chapters/05-the-voice.md](#sec-019)
+- [agent-abilities/chapters/06-identity-reputation.md](#sec-020)
+- [agent-abilities/chapters/07-skills.md](#sec-021)
+- [agent-abilities/chapters/08-screens.md](#sec-022)
+- [agent-abilities/chapters/09-the-agent-economy.md](#sec-023)
+- [agent-abilities/chapters/10-the-agent-wallet.md](#sec-024)
+- [agent-abilities/chapters/11-markets-intelligence.md](#sec-025)
+- [agent-abilities/chapters/12-live-worlds-social-irl.md](#sec-026)
+- [agent-abilities/chapters/13-agents-everywhere.md](#sec-027)
+- [agent-abilities/chapters/14-the-developer-platform.md](#sec-028)
+- [agent-abilities/chapters/15-appendix.md](#sec-029)
+- [agent-abilities/wallet/01-balance.md](#sec-030)
+- [agent-abilities/wallet/02-go-live.md](#sec-031)
+- [agent-abilities/wallet/03-portfolio.md](#sec-032)
+- [agent-abilities/wallet/04-deposit.md](#sec-033)
+- [agent-abilities/wallet/05-copilot.md](#sec-034)
+- [agent-abilities/wallet/06-trust.md](#sec-035)
+- [agent-abilities/wallet/07-signals.md](#sec-036)
+- [agent-abilities/wallet/08-trade.md](#sec-037)
+- [agent-abilities/wallet/09-pulse.md](#sec-038)
+- [agent-abilities/wallet/10-snipe.md](#sec-039)
+- [agent-abilities/wallet/11-earn.md](#sec-040)
+- [agent-abilities/wallet/12-orders.md](#sec-041)
+- [agent-abilities/wallet/13-autopilot.md](#sec-042)
+- [agent-abilities/wallet/14-intents.md](#sec-043)
+- [agent-abilities/wallet/15-pay.md](#sec-044)
+- [agent-abilities/wallet/16-vanity.md](#sec-045)
+- [agent-abilities/wallet/17-policy.md](#sec-046)
+- [agent-abilities/wallet/18-withdraw.md](#sec-047)
+- [agent-abilities/wallet/19-give.md](#sec-048)
+- [agent-abilities/wallet/20-proof-of-custody.md](#sec-049)
+- [agent-abilities/wallet/21-access.md](#sec-050)
+- [agent-abilities/wallet/22-recovery.md](#sec-051)
+- [agent-abilities/wallet/23-self-defense.md](#sec-052)
### agent-tasks
-- [agent-tasks/README.md](#sec-065)
-- [agent-tasks/fix-x402-502-bursts.md](#sec-066)
-- [agent-tasks/fix-x402-caller-mismatches.md](#sec-067)
-- [agent-tasks/fix-x402-wallet-health.md](#sec-068)
-- [agent-tasks/new-trading-arm-x402-signals.md](#sec-069)
+- [agent-tasks/README.md](#sec-066)
+- [agent-tasks/fix-x402-502-bursts.md](#sec-067)
+- [agent-tasks/fix-x402-caller-mismatches.md](#sec-068)
+- [agent-tasks/fix-x402-wallet-health.md](#sec-069)
+- [agent-tasks/new-trading-arm-x402-signals.md](#sec-070)
### agora
-- [agora/tasks/00-INDEX.md](#sec-076)
-- [agora/tasks/01-verify-foundation.md](#sec-077)
-- [agora/tasks/02-life-engine.md](#sec-078)
-- [agora/tasks/03-task-supply.md](#sec-079)
-- [agora/tasks/04-professions.md](#sec-080)
-- [agora/tasks/05-commons-scaffold.md](#sec-081)
-- [agora/tasks/06-economy-visuals.md](#sec-082)
-- [agora/tasks/07-verify-and-passport.md](#sec-083)
-- [agora/tasks/08-humans-first-class.md](#sec-084)
-- [agora/tasks/09-arena-and-guilds.md](#sec-085)
-- [agora/tasks/10-agora-mcp.md](#sec-086)
-- [agora/tasks/11-production-hardening.md](#sec-087)
-- [agora/tasks/12-fleet-render-performance.md](#sec-088)
+- [agora/tasks/00-INDEX.md](#sec-078)
+- [agora/tasks/01-verify-foundation.md](#sec-079)
+- [agora/tasks/02-life-engine.md](#sec-080)
+- [agora/tasks/03-task-supply.md](#sec-081)
+- [agora/tasks/04-professions.md](#sec-082)
+- [agora/tasks/05-commons-scaffold.md](#sec-083)
+- [agora/tasks/06-economy-visuals.md](#sec-084)
+- [agora/tasks/07-verify-and-passport.md](#sec-085)
+- [agora/tasks/08-humans-first-class.md](#sec-086)
+- [agora/tasks/09-arena-and-guilds.md](#sec-087)
+- [agora/tasks/10-agora-mcp.md](#sec-088)
+- [agora/tasks/11-production-hardening.md](#sec-089)
+- [agora/tasks/12-fleet-render-performance.md](#sec-090)
### api
-- [api/forge-x402.md](#sec-097)
+- [api/forge-x402.md](#sec-099)
### content
-- [content/use-cases/README.md](#sec-155)
-- [content/use-cases/ai-agent-developer.md](#sec-156)
-- [content/use-cases/brand-marketer.md](#sec-157)
-- [content/use-cases/crypto-community.md](#sec-158)
-- [content/use-cases/game-studio.md](#sec-159)
-- [content/use-cases/indie-creator.md](#sec-160)
+- [content/use-cases/README.md](#sec-160)
+- [content/use-cases/ai-agent-developer.md](#sec-161)
+- [content/use-cases/brand-marketer.md](#sec-162)
+- [content/use-cases/crypto-community.md](#sec-163)
+- [content/use-cases/game-studio.md](#sec-164)
+- [content/use-cases/indie-creator.md](#sec-165)
### cookbook
-- [cookbook/asset-quality-gate.md](#sec-162)
-- [cookbook/mcp-3d-tool.md](#sec-163)
-- [cookbook/parallel-asset-pack.md](#sec-164)
-- [cookbook/text-to-3d-cli.md](#sec-165)
+- [cookbook/asset-quality-gate.md](#sec-167)
+- [cookbook/mcp-3d-tool.md](#sec-168)
+- [cookbook/parallel-asset-pack.md](#sec-169)
+- [cookbook/text-to-3d-cli.md](#sec-170)
### erc8004
-- [erc8004/validation-attestation.md](#sec-190)
+- [erc8004/validation-attestation.md](#sec-196)
### event-readiness
-- [event-readiness/01-play-first-impression.md](#sec-191)
-- [event-readiness/02-play-mobile.md](#sec-192)
-- [event-readiness/03-play-performance.md](#sec-193)
-- [event-readiness/04-play-multiplayer-net.md](#sec-194)
-- [event-readiness/05-play-economy-loops.md](#sec-195)
-- [event-readiness/06-play-auth-errors.md](#sec-196)
-- [event-readiness/07-platform-smoke-sweep.md](#sec-197)
-- [event-readiness/08-api-production-health.md](#sec-198)
-- [event-readiness/09-accessibility-i18n.md](#sec-199)
-- [event-readiness/10-event-day-runbook.md](#sec-200)
-- [event-readiness/11-event-live-ops.md](#sec-201)
-- [event-readiness/12-photo-mode-share.md](#sec-202)
-- [event-readiness/13-event-quests-leaderboard.md](#sec-203)
-- [event-readiness/14-welcome-concierge.md](#sec-204)
-- [event-readiness/15-live-hype-feed.md](#sec-205)
-- [event-readiness/16-invite-flow.md](#sec-206)
-- [event-readiness/17-plaza-live-show.md](#sec-207)
-- [event-readiness/18-coin-wars-portal.md](#sec-208)
-- [event-readiness/19-forge-props-live.md](#sec-209)
-- [event-readiness/20-world-chat-scrollback.md](#sec-210)
-- [event-readiness/21-party-system.md](#sec-211)
-- [event-readiness/22-venue-projector-mode.md](#sec-212)
-- [event-readiness/23-signature-wall.md](#sec-213)
-- [event-readiness/24-dance-off.md](#sec-214)
-- [event-readiness/LIVE-OPS.md](#sec-215)
-- [event-readiness/README.md](#sec-216)
+- [event-readiness/01-play-first-impression.md](#sec-197)
+- [event-readiness/02-play-mobile.md](#sec-198)
+- [event-readiness/03-play-performance.md](#sec-199)
+- [event-readiness/04-play-multiplayer-net.md](#sec-200)
+- [event-readiness/05-play-economy-loops.md](#sec-201)
+- [event-readiness/06-play-auth-errors.md](#sec-202)
+- [event-readiness/07-platform-smoke-sweep.md](#sec-203)
+- [event-readiness/08-api-production-health.md](#sec-204)
+- [event-readiness/09-accessibility-i18n.md](#sec-205)
+- [event-readiness/10-event-day-runbook.md](#sec-206)
+- [event-readiness/11-event-live-ops.md](#sec-207)
+- [event-readiness/12-photo-mode-share.md](#sec-208)
+- [event-readiness/13-event-quests-leaderboard.md](#sec-209)
+- [event-readiness/14-welcome-concierge.md](#sec-210)
+- [event-readiness/15-live-hype-feed.md](#sec-211)
+- [event-readiness/16-invite-flow.md](#sec-212)
+- [event-readiness/17-plaza-live-show.md](#sec-213)
+- [event-readiness/18-coin-wars-portal.md](#sec-214)
+- [event-readiness/19-forge-props-live.md](#sec-215)
+- [event-readiness/20-world-chat-scrollback.md](#sec-216)
+- [event-readiness/21-party-system.md](#sec-217)
+- [event-readiness/22-venue-projector-mode.md](#sec-218)
+- [event-readiness/23-signature-wall.md](#sec-219)
+- [event-readiness/24-dance-off.md](#sec-220)
+- [event-readiness/LIVE-OPS.md](#sec-221)
+- [event-readiness/README.md](#sec-222)
### irl
-- [irl/THREAT-MODEL.md](#sec-260)
-
-### marketing
-
-- [marketing/articleee.md](#sec-274)
-- [marketing/posts.md](#sec-275)
-- [marketing/posts2.md](#sec-276)
+- [irl/THREAT-MODEL.md](#sec-271)
### openai-pr
-- [openai-pr/00-START-HERE.md](#sec-317)
-- [openai-pr/01-orphan-widget-resolution.md](#sec-318)
-- [openai-pr/02-wellknown-manifest-conflict.md](#sec-319)
-- [openai-pr/03-forge-free-tier-truth.md](#sec-320)
-- [openai-pr/04-openai-surface-test-coverage.md](#sec-321)
-- [openai-pr/05-custom-gpt-openapi-serving.md](#sec-322)
-- [openai-pr/06-docs-accuracy-reconciliation.md](#sec-323)
-- [openai-pr/07-final-verification-and-submit.md](#sec-324)
+- [openai-pr/00-START-HERE.md](#sec-328)
+- [openai-pr/01-orphan-widget-resolution.md](#sec-329)
+- [openai-pr/02-wellknown-manifest-conflict.md](#sec-330)
+- [openai-pr/03-forge-free-tier-truth.md](#sec-331)
+- [openai-pr/04-openai-surface-test-coverage.md](#sec-332)
+- [openai-pr/05-custom-gpt-openapi-serving.md](#sec-333)
+- [openai-pr/06-docs-accuracy-reconciliation.md](#sec-334)
+- [openai-pr/07-final-verification-and-submit.md](#sec-335)
### partners
-- [partners/sperax-proposal.md](#sec-330)
+- [partners/sperax-proposal.md](#sec-342)
### pumpfun-program
-- [pumpfun-program/README.md](#sec-353)
-- [pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md](#sec-354)
-- [pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md](#sec-355)
-- [pumpfun-program/docs/BREAKING_FEE_RECIPIENT.md](#sec-356)
-- [pumpfun-program/docs/CPI_README.md](#sec-357)
-- [pumpfun-program/docs/FAQ.md](#sec-358)
-- [pumpfun-program/docs/FEE_PROGRAM_README.md](#sec-359)
-- [pumpfun-program/docs/FEE_RECIPIENTS.md](#sec-360)
-- [pumpfun-program/docs/PUMP_CASHBACK_README.md](#sec-361)
-- [pumpfun-program/docs/PUMP_CREATOR_FEE_README.md](#sec-362)
-- [pumpfun-program/docs/PUMP_PROGRAM_README.md](#sec-363)
-- [pumpfun-program/docs/PUMP_SWAP_CREATOR_FEE_README.md](#sec-364)
-- [pumpfun-program/docs/PUMP_SWAP_README.md](#sec-365)
-- [pumpfun-program/docs/PUMP_SWAP_SDK_README.md](#sec-366)
-- [pumpfun-program/docs/instructions/BUY.md](#sec-367)
-- [pumpfun-program/docs/instructions/CLAIM_CASHBACK.md](#sec-368)
-- [pumpfun-program/docs/instructions/COIN_CREATION.md](#sec-369)
-- [pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md](#sec-370)
-- [pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md](#sec-371)
-- [pumpfun-program/docs/instructions/SELL.md](#sec-372)
+- [pumpfun-program/README.md](#sec-366)
+- [pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md](#sec-367)
+- [pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md](#sec-368)
+- [pumpfun-program/docs/BREAKING_FEE_RECIPIENT.md](#sec-369)
+- [pumpfun-program/docs/CPI_README.md](#sec-370)
+- [pumpfun-program/docs/FAQ.md](#sec-371)
+- [pumpfun-program/docs/FEE_PROGRAM_README.md](#sec-372)
+- [pumpfun-program/docs/FEE_RECIPIENTS.md](#sec-373)
+- [pumpfun-program/docs/PUMP_CASHBACK_README.md](#sec-374)
+- [pumpfun-program/docs/PUMP_CREATOR_FEE_README.md](#sec-375)
+- [pumpfun-program/docs/PUMP_PROGRAM_README.md](#sec-376)
+- [pumpfun-program/docs/PUMP_SWAP_CREATOR_FEE_README.md](#sec-377)
+- [pumpfun-program/docs/PUMP_SWAP_README.md](#sec-378)
+- [pumpfun-program/docs/PUMP_SWAP_SDK_README.md](#sec-379)
+- [pumpfun-program/docs/instructions/BUY.md](#sec-380)
+- [pumpfun-program/docs/instructions/CLAIM_CASHBACK.md](#sec-381)
+- [pumpfun-program/docs/instructions/COIN_CREATION.md](#sec-382)
+- [pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md](#sec-383)
+- [pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md](#sec-384)
+- [pumpfun-program/docs/instructions/SELL.md](#sec-385)
### specs
-- [specs/agent-trading.md](#sec-408)
+- [specs/agent-trading.md](#sec-426)
### tutorials
-- [tutorials/add-a-3d-assistant.md](#sec-433)
-- [tutorials/agent-personality.md](#sec-434)
-- [tutorials/agent-reputation.md](#sec-435)
-- [tutorials/agent-spending-envelope.md](#sec-436)
-- [tutorials/animate-your-agent.md](#sec-437)
-- [tutorials/animate-your-avatar.md](#sec-438)
-- [tutorials/arm-an-agent-sniper.md](#sec-439)
-- [tutorials/build-a-3d-asset-pipeline.md](#sec-440)
-- [tutorials/build-a-scene.md](#sec-441)
-- [tutorials/build-a-site-concierge.md](#sec-442)
-- [tutorials/character-library-to-embed.md](#sec-443)
-- [tutorials/claim-threews-name.md](#sec-444)
-- [tutorials/connect-ai-brain.md](#sec-445)
-- [tutorials/create-and-edit-memory.md](#sec-446)
-- [tutorials/custom-skill.md](#sec-447)
-- [tutorials/customize-appearance.md](#sec-448)
-- [tutorials/deploy-to-vercel-custom-domain.md](#sec-449)
-- [tutorials/earn-and-spend-in-play.md](#sec-450)
-- [tutorials/embed-in-30-seconds.md](#sec-451)
-- [tutorials/embed-on-website.md](#sec-452)
-- [tutorials/emotion-from-data.md](#sec-453)
-- [tutorials/explore-docs-world.md](#sec-454)
-- [tutorials/find-a-better-exit-policy.md](#sec-455)
-- [tutorials/first-agent.md](#sec-456)
-- [tutorials/first-prompt-to-3d.md](#sec-457)
-- [tutorials/generate-3d-api.md](#sec-458)
-- [tutorials/getting-started.md](#sec-459)
-- [tutorials/greeting-and-first-speech.md](#sec-460)
-- [tutorials/image-to-3d.md](#sec-461)
-- [tutorials/import-avatar-url.md](#sec-462)
-- [tutorials/js-api-events.md](#sec-463)
-- [tutorials/mcp-server-for-your-agent.md](#sec-464)
-- [tutorials/mine-vanity-address.md](#sec-465)
-- [tutorials/mint-pumpfun-token.md](#sec-466)
-- [tutorials/monetize-mcp-server.md](#sec-467)
-- [tutorials/multi-agent-coordination.md](#sec-468)
-- [tutorials/nvidia-3d-free.md](#sec-469)
-- [tutorials/nvidia-nim-self-host.md](#sec-470)
-- [tutorials/paid-x402-endpoint.md](#sec-471)
-- [tutorials/pay-for-x402-service.md](#sec-472)
-- [tutorials/personal-ai-site.md](#sec-473)
-- [tutorials/place-agent-irl.md](#sec-474)
-- [tutorials/prompts-for-3d.md](#sec-475)
-- [tutorials/read-the-trading-fleet.md](#sec-476)
-- [tutorials/register-onchain.md](#sec-477)
-- [tutorials/render-avatar-images.md](#sec-478)
-- [tutorials/self-host-agent-backend.md](#sec-479)
-- [tutorials/selfie-to-avatar.md](#sec-480)
-- [tutorials/sell-a-skill-with-a-trial.md](#sec-481)
-- [tutorials/share-your-agent.md](#sec-482)
-- [tutorials/ship-an-avatar-manifest.md](#sec-483)
-- [tutorials/shopify-shopping-assistant.md](#sec-484)
-- [tutorials/shopify-store-guide-advanced.md](#sec-485)
-- [tutorials/shopify-store-guide.md](#sec-486)
-- [tutorials/sign-with-your-avatar.md](#sec-487)
-- [tutorials/skill-with-database-auth.md](#sec-488)
-- [tutorials/solana-agent-reputation.md](#sec-489)
-- [tutorials/sperax-tour.md](#sec-490)
-- [tutorials/swap-avatar-in-studio.md](#sec-491)
-- [tutorials/text-to-3d.md](#sec-492)
-- [tutorials/trigger-from-page-events.md](#sec-493)
-- [tutorials/upload-custom-glb.md](#sec-494)
-- [tutorials/view-in-ar.md](#sec-495)
-- [tutorials/voice-and-lipsync.md](#sec-496)
-- [tutorials/walk-companion.md](#sec-497)
-- [tutorials/wallet-sign-in.md](#sec-498)
-- [tutorials/web-component-end-to-end.md](#sec-499)
-- [tutorials/write-a-guard.md](#sec-500)
-- [tutorials/x402-server-sdk.md](#sec-501)
+- [tutorials/add-a-3d-assistant.md](#sec-453)
+- [tutorials/agent-personality.md](#sec-454)
+- [tutorials/agent-reputation.md](#sec-455)
+- [tutorials/agent-spending-envelope.md](#sec-456)
+- [tutorials/animate-your-agent.md](#sec-457)
+- [tutorials/animate-your-avatar.md](#sec-458)
+- [tutorials/arm-an-agent-sniper.md](#sec-459)
+- [tutorials/build-a-3d-asset-pipeline.md](#sec-460)
+- [tutorials/build-a-scene.md](#sec-461)
+- [tutorials/build-a-site-concierge.md](#sec-462)
+- [tutorials/character-library-to-embed.md](#sec-463)
+- [tutorials/claim-threews-name.md](#sec-464)
+- [tutorials/connect-ai-brain.md](#sec-465)
+- [tutorials/create-and-edit-memory.md](#sec-466)
+- [tutorials/custom-skill.md](#sec-467)
+- [tutorials/customize-appearance.md](#sec-468)
+- [tutorials/deploy-to-vercel-custom-domain.md](#sec-469)
+- [tutorials/earn-and-spend-in-play.md](#sec-470)
+- [tutorials/embed-in-30-seconds.md](#sec-471)
+- [tutorials/embed-on-website.md](#sec-472)
+- [tutorials/emotion-from-data.md](#sec-473)
+- [tutorials/explore-docs-world.md](#sec-474)
+- [tutorials/find-a-better-exit-policy.md](#sec-475)
+- [tutorials/first-agent.md](#sec-476)
+- [tutorials/first-prompt-to-3d.md](#sec-477)
+- [tutorials/generate-3d-api.md](#sec-478)
+- [tutorials/getting-started.md](#sec-479)
+- [tutorials/greeting-and-first-speech.md](#sec-480)
+- [tutorials/image-to-3d.md](#sec-481)
+- [tutorials/import-avatar-url.md](#sec-482)
+- [tutorials/js-api-events.md](#sec-483)
+- [tutorials/mcp-server-for-your-agent.md](#sec-484)
+- [tutorials/mine-vanity-address.md](#sec-485)
+- [tutorials/mint-pumpfun-token.md](#sec-486)
+- [tutorials/monetize-mcp-server.md](#sec-487)
+- [tutorials/multi-agent-coordination.md](#sec-488)
+- [tutorials/nvidia-3d-free.md](#sec-489)
+- [tutorials/nvidia-nim-self-host.md](#sec-490)
+- [tutorials/paid-x402-endpoint.md](#sec-491)
+- [tutorials/pay-for-x402-service.md](#sec-492)
+- [tutorials/personal-ai-site.md](#sec-493)
+- [tutorials/place-agent-irl.md](#sec-494)
+- [tutorials/prompts-for-3d.md](#sec-495)
+- [tutorials/read-the-trading-fleet.md](#sec-496)
+- [tutorials/register-onchain.md](#sec-497)
+- [tutorials/render-avatar-images.md](#sec-498)
+- [tutorials/self-host-agent-backend.md](#sec-499)
+- [tutorials/selfie-to-avatar.md](#sec-500)
+- [tutorials/sell-a-skill-with-a-trial.md](#sec-501)
+- [tutorials/share-your-agent.md](#sec-502)
+- [tutorials/ship-an-avatar-manifest.md](#sec-503)
+- [tutorials/shopify-shopping-assistant.md](#sec-504)
+- [tutorials/shopify-store-guide-advanced.md](#sec-505)
+- [tutorials/shopify-store-guide.md](#sec-506)
+- [tutorials/sign-with-your-avatar.md](#sec-507)
+- [tutorials/skill-with-database-auth.md](#sec-508)
+- [tutorials/solana-agent-reputation.md](#sec-509)
+- [tutorials/sperax-tour.md](#sec-510)
+- [tutorials/swap-avatar-in-studio.md](#sec-511)
+- [tutorials/text-to-3d.md](#sec-512)
+- [tutorials/trigger-from-page-events.md](#sec-513)
+- [tutorials/upload-custom-glb.md](#sec-514)
+- [tutorials/view-in-ar.md](#sec-515)
+- [tutorials/voice-and-lipsync.md](#sec-516)
+- [tutorials/walk-companion.md](#sec-517)
+- [tutorials/wallet-sign-in.md](#sec-518)
+- [tutorials/web-component-end-to-end.md](#sec-519)
+- [tutorials/write-a-guard.md](#sec-520)
+- [tutorials/x402-server-sdk.md](#sec-521)
### ux-flows
-- [ux-flows/01-onboarding-creation.md](#sec-504)
-- [ux-flows/02-forge-text-to-3d.md](#sec-505)
-- [ux-flows/03-3d-editing-viewer.md](#sec-506)
-- [ux-flows/04-embed-widget-studio.md](#sec-507)
-- [ux-flows/05-discovery-social.md](#sec-508)
-- [ux-flows/06-marketplace-skills.md](#sec-509)
-- [ux-flows/07-crypto-trading-analytics.md](#sec-510)
-- [ux-flows/08-coin-launch-wallets.md](#sec-511)
-- [ux-flows/09-x402-agent-commerce.md](#sec-512)
-- [ux-flows/10-chat-brain-labs.md](#sec-513)
-- [ux-flows/11-account-dashboard.md](#sec-514)
-- [ux-flows/12-home-and-content.md](#sec-515)
+- [ux-flows/01-onboarding-creation.md](#sec-524)
+- [ux-flows/02-forge-text-to-3d.md](#sec-525)
+- [ux-flows/03-3d-editing-viewer.md](#sec-526)
+- [ux-flows/04-embed-widget-studio.md](#sec-527)
+- [ux-flows/05-discovery-social.md](#sec-528)
+- [ux-flows/06-marketplace-skills.md](#sec-529)
+- [ux-flows/07-crypto-trading-analytics.md](#sec-530)
+- [ux-flows/08-coin-launch-wallets.md](#sec-531)
+- [ux-flows/09-x402-agent-commerce.md](#sec-532)
+- [ux-flows/10-chat-brain-labs.md](#sec-533)
+- [ux-flows/11-account-dashboard.md](#sec-534)
+- [ux-flows/12-home-and-content.md](#sec-535)
### x-archive
-- [x-archive/trythreews-engagement.md](#sec-529)
+- [x-archive/trythreews-engagement.md](#sec-552)
### x-posts
-- [x-posts/3d-ar-studio-launch.md](#sec-531)
-- [x-posts/3d-ar-studio-video-script.md](#sec-532)
-- [x-posts/README.md](#sec-533)
-- [x-posts/ar-quick-look-fix-x-post.md](#sec-534)
-- [x-posts/event-x-posts.md](#sec-535)
-- [x-posts/fomo-verified-x-post.md](#sec-536)
-- [x-posts/github-100-stars.md](#sec-537)
-- [x-posts/ibm-skillsbuild-x-post.md](#sec-538)
-- [x-posts/mcp-registry-fleet-x-post.md](#sec-539)
-- [x-posts/metaplex-agent-deployer-video-script.md](#sec-540)
-- [x-posts/metaplex-agent-deployer-x-post.md](#sec-541)
-- [x-posts/metaplex-agent-mcp-launch.md](#sec-542)
-- [x-posts/metaplex-agent-mcp-veo-script.md](#sec-543)
-- [x-posts/metaplex-agent-mcp-x-post.md](#sec-544)
-- [x-posts/news-archive-x-post.md](#sec-545)
-- [x-posts/onchain-agent-wallets-x-post.md](#sec-546)
-- [x-posts/open-source-ecosystem.md](#sec-547)
-- [x-posts/oracle-trading-mcp-x-post.md](#sec-548)
-- [x-posts/osf-issue-reply.md](#sec-549)
-- [x-posts/pumpfun-article-x-post.md](#sec-550)
-- [x-posts/sperax-staking-in-chat-x-post.md](#sec-551)
-- [x-posts/the-first-19-weeks.md](#sec-552)
-- [x-posts/threews-avatar-launch.md](#sec-553)
-- [x-posts/threews-avatar-video-script.md](#sec-554)
-- [x-posts/x-meetup-posts.md](#sec-555)
+- [x-posts/3d-ar-studio-launch.md](#sec-554)
+- [x-posts/3d-ar-studio-video-script.md](#sec-555)
+- [x-posts/README.md](#sec-556)
+- [x-posts/android-app-launch.md](#sec-557)
+- [x-posts/ar-quick-look-fix-x-post.md](#sec-558)
+- [x-posts/event-x-posts.md](#sec-559)
+- [x-posts/fomo-verified-x-post.md](#sec-560)
+- [x-posts/github-100-stars.md](#sec-561)
+- [x-posts/ibm-skillsbuild-x-post.md](#sec-562)
+- [x-posts/mcp-registry-fleet-x-post.md](#sec-563)
+- [x-posts/metaplex-agent-deployer-video-script.md](#sec-564)
+- [x-posts/metaplex-agent-deployer-x-post.md](#sec-565)
+- [x-posts/metaplex-agent-mcp-launch.md](#sec-566)
+- [x-posts/metaplex-agent-mcp-veo-script.md](#sec-567)
+- [x-posts/metaplex-agent-mcp-x-post.md](#sec-568)
+- [x-posts/news-archive-x-post.md](#sec-569)
+- [x-posts/onchain-agent-wallets-x-post.md](#sec-570)
+- [x-posts/open-source-ecosystem.md](#sec-571)
+- [x-posts/oracle-trading-mcp-x-post.md](#sec-572)
+- [x-posts/osf-issue-reply.md](#sec-573)
+- [x-posts/proof-of-life-x-post.md](#sec-574)
+- [x-posts/pumpfun-article-x-post.md](#sec-575)
+- [x-posts/sperax-staking-in-chat-x-post.md](#sec-576)
+- [x-posts/the-first-19-weeks.md](#sec-577)
+- [x-posts/threews-avatar-launch.md](#sec-578)
+- [x-posts/threews-avatar-video-script.md](#sec-579)
+- [x-posts/x-meetup-posts.md](#sec-580)
### zauth
-- [zauth/database.md](#sec-564)
-- [zauth/index.md](#sec-565)
-- [zauth/provider-hub.md](#sec-566)
-- [zauth/reposcan.md](#sec-567)
-- [zauth/vector.md](#sec-568)
+- [zauth/database.md](#sec-590)
+- [zauth/index.md](#sec-591)
+- [zauth/provider-hub.md](#sec-592)
+- [zauth/reposcan.md](#sec-593)
+- [zauth/vector.md](#sec-594)
---
@@ -1196,9 +1219,9 @@ 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-109) — the three ways to create an avatar (photo, builder, upload).
-- [docs/tutorials/upload-custom-glb.md](#sec-494) — Mixamo → GLB, validation, and the common failure modes.
+- [docs/animations.md](#sec-095) — the animation registry, runtime loading, and agent slots.
+- [docs/avatar-creation.md](#sec-111) — the three ways to create an avatar (photo, builder, upload).
+- [docs/tutorials/upload-custom-glb.md](#sec-514) — Mixamo → GLB, validation, and the common failure modes.
This document is the *why and how* underneath all of those.
@@ -1316,7 +1339,7 @@ npm run optimize:glb # every GLB in assets/, publ
npm run optimize:glb -- --dry # report only, no writes
```
-Source: [scripts/optimize-glb.mjs](../scripts/optimize-glb.mjs). Lossless geometry passes (`dedup`, `prune`, `weld`, `resample`) plus a WebP texture re-encode. Output stays within the **standard glTF 2.0 feature set** — no `KHR_draco_mesh_compression`, no `EXT_meshopt_compression` — so it loads in every `GLTFLoader` on the site without wiring a decoder. Typical result: **−90%** file size.
+Source: [scripts/optimize-glb.mjs](../scripts/optimize-glb.mjs). Lossless geometry passes (`dedup`, `prune`, `weld`, `resample`) plus a WebP texture re-encode. Compressed inputs are fine: the script registers the meshopt and Draco codecs with gltf-transform, so an `EXT_meshopt_compression` or `KHR_draco_mesh_compression` avatar (most of the ones in production) decodes instead of failing with "Please install extension dependency". Output stays within the **standard glTF 2.0 feature set** (the compression extensions are stripped after decoding, never re-encoded) so it loads in every `GLTFLoader` on the site without wiring a decoder. Typical result: **-90%** file size.
### The format reference
@@ -1356,7 +1379,7 @@ The build pipeline produces GLB + JSON; the browser stitches them back together.
| Stage | Module | What it does |
|---|---|---|
-| Load a GLB | [src/viewer.js](../src/viewer.js) | `GLTFLoader` (with DRACO/KTX2 support) loads the model, frames the camera, builds raycasting BVH, emits the scene to the animation panel. |
+| Load a GLB | [src/viewer.js](../src/viewer.js) | `GLTFLoader` (with DRACO/KTX2/meshopt support) loads the model, frames the camera in front of the rig's face (`estimateFacingYaw` in `src/viewer/facing.js` reads which way the skeleton was authored to face, so a -Z or +X rig is not framed from behind), builds raycasting BVH, emits the scene to the animation panel. |
| Normalize an uploaded rig | [src/glb-canonicalize.js](../src/glb-canonicalize.js) | Rewrites bone names in the GLB JSON chunk to canonical form (see [the supported conventions](#supported-rig-conventions) below), folds the Mixamo +90°X armature rotation into children, repacks the GLB. |
| Load a clip | [src/animation-manager.js](../src/animation-manager.js) | Fetches clip JSON, `AnimationClip.parse`, drives playback through a `THREE.AnimationMixer` with crossfades (0.35s default), one-shot + settle, and a "fallen pose" safety guard. |
| Retarget a clip to the loaded rig | [src/animation-retarget.js](../src/animation-retarget.js) | Renames canonical tracks to the rig's actual bone names, applies per-bone bind-pose correction (`C = targetRest · sourceRest⁻¹`), rescales hip translation by height ratio, drops the clip if coverage < 50%. |
@@ -1380,6 +1403,7 @@ There is **no rig allowlist**. [src/glb-canonicalize.js](../src/glb-canonicalize
| Unreal mannequin | `pelvis`, `clavicle_l`, `upperarm_l`, `thigh_l`, `calf_l`, `ball_l` |
| VRM 0.x / VRoid | `J_Bip_C_Hips`, `J_Bip_L_UpperArm`, `J_Bip_L_Little1` |
| VRM 1.0 | `leftUpperArm`, `rightLowerLeg`, `upperChest`, `leftToes` |
+| MikuMikuDance (PMX/PMD) | `センター`, `上半身`, `首`, `左腕`, `左ひじ`, `左ひざ` (Japanese names, `左`/`右` side prefix) |
| UniGLTF / VRM converter | `5.joint_HipMaster`, `10.!joint_LeftToe` |
| Daz3D / Genesis | `hip`, `abdomen`, `lShldr`, `lThigh`, `lShin`, `lCollar` |
| Reallusion CC3 / CC4 | `CC_Base_Hip`, `CC_Base_L_Upperarm`, `CC_Base_NeckTwist01` |
@@ -1401,6 +1425,7 @@ Vendor prefixes (`mixamorig:`, `CC_Base_`, `Bip01 `, `j_`, Maya namespaces) and
- **Non-humanoid skeletons** (quadrupeds, prop rigs) — no safe correspondence exists.
- **End effectors and leaf tips** (`HeadTop_End`, `LeftToe_End`, `LeftHandIndex4`) — the clip library drives no such bone.
- **Metacarpals** (`Palm1.L`) — the canonical set has no metacarpal.
+- **MMD IK targets and twist bones** (`左足IK`, `左つま先IK`, `左腕捩`, `左手捩`). MMD drives the leg chain from the IK target, so binding a clip to it would fight the chain it solves, and the twist bones are secondary deformers that tear the mesh when rotated as a limb.
- **Constraint-driven control rigs** (Auto-Rig-Pro / `cwf_` + `def_` + tracker families). Their deform bones are *leaves* hanging off tracker nodes — `def_arm_1.R` is not a child of `def_arm_0.R` — and glTF has no constraint system, so the Copy-Rotation/Damped-Track constraints that made the rig work in Blender are dropped at export. Rotating a mapped `def_` bone would move its own skin while the next segment stayed put, tearing the limb apart. These fall back to the default rig; the remedy is re-rigging through [workers/rig](../workers/rig), not name mapping.
### Measuring coverage against real avatars
@@ -1478,7 +1503,7 @@ text/image ──► mesh_forge ──► static GLB ──► rig_mesh ──
- **Don't ship raw converted GLBs.** A Mixamo character converts to 50+ MB; always run `optimize:glb`. The site streams these to every visitor.
- **`trimesh` (the Python script) silently drops rigs.** It is for static geometry only. For anything animated, use `convert:fbx`.
-- **No Draco/meshopt in optimized output.** The main viewer and the studios wire Draco/KTX2/meshopt decoders (`getDecoders` in `src/viewer/internal.js`), but many lighter surfaces load GLBs with a bare `GLTFLoader` and no decoder. `optimize:glb` deliberately stays within plain glTF 2.0 so its output loads everywhere; WebP textures do the heavy lifting.
+- **No Draco/meshopt in optimized output.** The main viewer and the studios wire Draco/KTX2/meshopt decoders (`getDecoders` in `src/viewer/internal.js`, which serves the decoder binaries from our own origin under `public/three/`, vendored by `scripts/copy-three-decoders.mjs` on every install and checked by `scripts/audit-deploy-artifacts.mjs` at deploy, with unpkg only as the backstop when a HEAD probe of the local copy fails), but many lighter surfaces load GLBs with a bare `GLTFLoader` and no decoder. `optimize:glb` deliberately stays within plain glTF 2.0 so its output loads everywhere; WebP textures do the heavy lifting.
- **FBX is build-time only.** Keep source FBX in `animation-sources/` (gitignored) so it never ships in the deploy bundle. `public/animations/` holds no FBX anymore; the six formerly-orphaned clips are built into the manifest (see `resolved_issues` in [public/animations/registry.json](../public/animations/registry.json)).
- **Bone names matter.** A non-humanoid or oddly-named rig may fall below the 8-bone / 50%-coverage thresholds and refuse to animate. The canonicalizer handles the common conventions; truly custom skeletons need their bones renamed to the canonical set first.
- **`.bak` files.** `optimize:glb` writes a `<name>.glb.bak` alongside its output — delete it before committing.
@@ -1517,11 +1542,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-563) resource: an AI agent pays a few cents in USDC, hands in a URL,
+own [x402](#sec-589) 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-559); the stages below are what you do to
+3D) is [`/api/x402/forge`](#sec-584); the stages below are what you do to
a mesh *after* it exists.
```
@@ -1534,7 +1559,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-559).
+2. **The whole chain in one call** — [`POST /api/x402/pipeline`](#sec-584).
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
@@ -1597,7 +1622,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-556).
+[x402 buyer client](#sec-581).
## Stages
@@ -1756,14 +1781,143 @@ returned as-is. Poll budget is tunable via `X402_PIPELINE_POLL_BUDGET_MS`
## Related
-- [x402 paid endpoints](#sec-559) — the full catalog + pricing model
-- [x402 buyer client](#sec-556) — how to settle payments as an agent
-- [Avatar pipeline](#sec-113) — the generation + rig lanes in depth
+- [x402 paid endpoints](#sec-584) — the full catalog + pricing model
+- [x402 buyer client](#sec-581) — how to settle payments as an agent
+- [Avatar pipeline](#sec-115) — the generation + rig lanes in depth
---
<a id="sec-004"></a>
+> **Source:** `docs/3d-vision.md` · [↑ table of contents](#table-of-contents)
+
+# 3D Vision: let an agent see the model
+
+Every text-to-3D API, this platform's included, has always answered with a URL to a binary file. A human clicks it. **An agent cannot.** A `.glb` is opaque to a language model, so the agent that just spent GPU time generating an asset has no way to tell a clean mesh from a melted one. It hands the link to a human and hopes.
+
+That blindness is the reason agentic 3D stalls at one shot. There is no feedback signal to iterate on.
+
+This surface closes the loop. Give it a model, get back **frames a vision-capable model can actually look at**, plus the geometry facts and a plain reading of them. Generate, look, judge, fix.
+
+Free and keyless, like the rest of [the 3D API](#sec-001).
+
+---
+
+## Three ways in
+
+| You are | Use | You get |
+| --- | --- | --- |
+| An MCP client (Claude, any MCP host) | tool `look_at_model` on `/api/mcp-studio` | Frames as **MCP image content blocks**, rendered into the conversation |
+| A Node program | [`@three-ws/see`](../packages/see/README.md) | `see(url)` → views, stats, notes |
+| Anything that speaks HTTP | `POST /api/3d/look` | JSON with a frame URL per angle |
+
+---
+
+## MCP: the model sees the model
+
+This is the one that matters. MCP content blocks can carry images, so a multimodal client renders the frames straight into the conversation. The agent is not told about its model; it **looks** at it.
+
+```json
+{
+ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
+ "params": {
+ "name": "look_at_model",
+ "arguments": { "glb_url": "https://example.com/robot.glb" }
+ }
+}
+```
+
+The reply opens with a text block naming what was rendered and what to judge, then one labelled text block and one `image` block per angle. A client that supports images shows them; the model forms an opinion and can immediately regenerate naming the specific fault it saw.
+
+Works on **any** public https `.glb`, not only models generated here.
+
+## REST
+
+```bash
+curl -sS -X POST https://three.ws/api/3d/look \
+ -H 'content-type: application/json' \
+ -d '{"glb_url":"https://example.com/robot.glb"}'
+```
+
+```json
+{
+ "model_url": "https://example.com/robot.glb",
+ "size": 512,
+ "views": [
+ { "view": "three-quarter", "theta": 35, "phi": 78, "image_url": "https://…/a.png" },
+ { "view": "front", "theta": 0, "phi": 80, "image_url": "https://…/b.png" },
+ { "view": "side", "theta": 90, "phi": 80, "image_url": "https://…/c.png" },
+ { "view": "back", "theta": 180, "phi": 80, "image_url": "https://…/d.png" }
+ ],
+ "stats": { "vertices": 8231, "triangles": 12400, "materials": 2, "textures": 1, "animations": 0 },
+ "notes": ["12,400 triangles, a normal real-time budget for a hero prop or character."],
+ "viewer_url": "https://three.ws/viewer?src=…",
+ "ar_url": "https://three.ws/api/ar?src=…"
+}
+```
+
+`GET /api/3d/look` returns a discovery doc: every angle, the limits, and a runnable example.
+
+## SDK
+
+```bash
+npm install @three-ws/see
+```
+
+```js
+import { see, toMessageContent } from '@three-ws/see';
+
+const look = await see('https://example.com/robot.glb');
+const content = await toMessageContent(look); // multimodal chat blocks, ready to send
+```
+
+Full API, including the generate → look → critique loop against the Claude API: [`packages/see/README.md`](../packages/see/README.md).
+
+---
+
+## The angles, and why these ones
+
+| View | Camera | What it catches |
+| --- | --- | --- |
+| `three-quarter` | theta 35, phi 78 | Form and depth, the way a product shot reads. Rendered first because it is the single most informative frame. |
+| `front` | theta 0, phi 80 | Facing, symmetry, the subject's identity |
+| `side` | theta 90, phi 80 | Profile, depth collapse, flattened geometry |
+| `back` | theta 180, phi 80 | The half a single-view generator most often leaves unfinished |
+| `top` | theta 0, phi 25 | Footprint, layout, whether it is hollow |
+| `bottom` | theta 0, phi 155 | Missing caps, inverted normals, floating geometry |
+
+The default set is `three-quarter, front, side, back`: the smallest number of frames that answers "is this model good". More frames cost render seconds and agent context for very little extra signal, which is why the cap is six.
+
+Every frame uses the `full-body` scene preset, which fits the whole bounding box. The humanoid presets crop to a torso or head and would silently cut a prop, a vehicle or a creature in half.
+
+## What it is honest about
+
+- **A partial turntable is not a failure.** If one angle fails to render you get the frames that worked plus `missing_views` naming what did not. Three good views beat an error.
+- **Stats are best-effort.** They come from [`/api/3d/inspect`](#sec-001), so "what this model is" has exactly one implementation. An inspector hiccup costs you the numbers, never the frames, because the frames are the part you could not get any other way.
+- **Unknown angle names are ignored, not rejected.** An agent guessing `"left"` still gets a useful turntable.
+- **Nothing is invented.** The geometry reading is derived from measured stats; it never guesses at quality it cannot measure. Judging whether the model is *good* is the vision model's job, which is the entire point.
+
+## Limits
+
+| Limit | Value | Why |
+| --- | --- | --- |
+| Views per call | 6 | Each frame is seconds of headless render |
+| Frame size | 128 to 1024 px | 512 is enough for a model to judge form |
+| Rate | shared render bucket, 60 per 10 min per IP | Rendering holds a CPU for seconds; this is a real cost ceiling |
+| Model URL | public `https://` only | SSRF-guarded before anything is fetched |
+
+Frames render **sequentially**. The renderer drives one shared headless browser; firing four pages at it in parallel turns a 4-second turntable into an out-of-memory kill under any real concurrency.
+
+## Related
+
+- [Free 3D API](#sec-001): generate and inspect
+- [MCP servers](#sec-293): every tool on `/api/mcp-studio`
+- [OKX.AI marketplace](#sec-320): paid 3D for agents that buy it
+
+---
+
+<a id="sec-005"></a>
+
> **Source:** `docs/DESIGN-TOKENS.md` · [↑ table of contents](#table-of-contents)
# Design Tokens — three.ws
@@ -1886,7 +2040,7 @@ here when a real need appears; keep the "no hardcoded values" rule intact._
---
-<a id="sec-005"></a>
+<a id="sec-006"></a>
> **Source:** `docs/PROTOCOL-vanity.md` · [↑ table of contents](#table-of-contents)
@@ -2202,7 +2356,7 @@ logged, never returned.
---
-<a id="sec-006"></a>
+<a id="sec-007"></a>
> **Source:** `docs/README.md` · [↑ table of contents](#table-of-contents)
@@ -2212,10 +2366,10 @@ Product and developer documentation for three.ws. Individual docs are served on
Start points:
-- [start-here.md](#sec-411): the front door for both creators and developers, with the reference shelf at the bottom.
-- [introduction.md](#sec-258) and [quick-start.md](#sec-373): the developer track.
+- [start-here.md](#sec-429): the front door for both creators and developers, with the reference shelf at the bottom.
+- [introduction.md](#sec-268) and [quick-start.md](#sec-386): 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).
+- [api-reference.md](#sec-098): the REST API surface, with dedicated docs for the larger API families (crypto, 3D, market data, MCP).
Subdirectories: [tutorials/](tutorials) (step-by-step guides served on-site), [specs/](specs) (proposed contracts), [api/](api), [erc8004/](erc8004), [agent-abilities/](agent-abilities), [ux-flows/](ux-flows) (the UX Flow Atlas), [content/](content) (use-case narratives), [partners/](partners).
@@ -2225,7 +2379,7 @@ Writing rules are in [CLAUDE.md](../CLAUDE.md) (Documentation section): every fe
---
-<a id="sec-007"></a>
+<a id="sec-008"></a>
> **Source:** `docs/a2a-payments.md` · [↑ table of contents](#table-of-contents)
@@ -2246,9 +2400,9 @@ leaves behind, and how to stop an agent that has gone wrong.
> The whole chain is proven end to end by
> [`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-222) for
-the platform-wide picture, and [agent economy volume](#sec-052)
+Related: [the agent wallet control API](#sec-073) for the other
+owner-only wallet surfaces, [financial controls](#sec-229) for
+the platform-wide picture, and [agent economy volume](#sec-053)
for what settled A2A payments add up to.
---
@@ -2432,7 +2586,7 @@ touched in production. It needs `docker` and ports 5817, 5818 and 3817.
---
-<a id="sec-008"></a>
+<a id="sec-009"></a>
> **Source:** `docs/agenc.md` · [↑ table of contents](#table-of-contents)
@@ -2477,7 +2631,7 @@ on **devnet** today, so a mainnet read of a real task normally returns `not_foun
`list-tasks` can only answer once you already know a creator wallet, which is no
help to a client holding nothing. `recent-tasks` closes that gap: it returns the
-task PDAs three.ws has posted, claimed, or settled through the [Agora](#sec-075)
+task PDAs three.ws has posted, claimed, or settled through the [Agora](#sec-077)
rail, newest first, read from the platform's own journal rather than the chain
(one DB query, no `getProgramAccounts` scan, so it answers in milliseconds).
@@ -2546,7 +2700,7 @@ the routes down. A 503 means the whole chain refused the same read at once.
`lifecycle=1` adds the task's ordered event timeline. A Solana account records
*what* happened but not the signature of the transaction that wrote it, so the
chain alone returns `txSignature: null` on every event. three.ws journals the real
-signature of every write it makes through the [Agora](#sec-075) rail, so the
+signature of every write it makes through the [Agora](#sec-077) rail, so the
response fills those blanks from that journal:
```json
@@ -2583,7 +2737,7 @@ Rules the enrichment holds to:
as onto its event. `proofHash` is `sha256(deliverable bytes)`, which is what lets
a client holding only a task PDA (a `/agora?task=<pda>` deep link) re-download
the artifact, re-hash it in the browser, and verify the work without trusting
- us. See [Agora](#sec-075) for that verification surface.
+ us. See [Agora](#sec-077) for that verification surface.
## Identity bridge — `/api/agenc/link`
@@ -2600,18 +2754,18 @@ three.ws agent to its on-chain identity so reputation and tasks can be correlate
on-chain identity; no `api/agenc/` endpoint **writes** a new agent registration
or task to the AgenC program. The write paths that do exist live elsewhere:
-- The [Agora](#sec-075) MCP tools (`packages/agora-mcp`): `agora_register` performs
+- The [Agora](#sec-077) MCP tools (`packages/agora-mcp`): `agora_register` performs
the real on-chain AgenC agent registration, and `agora_post_task` /
`agora_claim_task` / `agora_complete_task` drive the task lifecycle.
- The `agora-citizens` worker registers its citizens on AgenC the same way.
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-311).
+[Deploy agents on-chain (bulk)](#sec-322).
## Relationship to Agora
-[Agora](#sec-075) is the living agent-and-human economy layer that uses AgenC as
+[Agora](#sec-077) is the living agent-and-human economy layer that uses AgenC as
its on-chain task substrate (post → claim → complete → earn, with $THREE escrow).
The Agora MCP write tools (`agora_post_task`, `agora_claim_task`,
`agora_complete_task`) are where the on-chain *write* lifecycle lives today; the
@@ -2619,13 +2773,13 @@ 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-189).
-- [Deploy agents on-chain (bulk)](#sec-311).
+- [Agora](#sec-077) — the economy and write lifecycle on top of AgenC.
+- [Agent reputation](#sec-057), [ERC-8004](#sec-195).
+- [Deploy agents on-chain (bulk)](#sec-322).
---
-<a id="sec-009"></a>
+<a id="sec-010"></a>
> **Source:** `docs/agent-abilities.md` · [↑ table of contents](#table-of-contents)
@@ -2661,51 +2815,51 @@ of the agent, and there is a lot more of it.
| # | Chapter |
|---|---------|
-| 01 | [The Body — 3D creation](#sec-014) |
-| 02 | [Motion — embodiment and animation](#sec-015) |
-| 03 | [Creation studios — where agents are made](#sec-016) |
-| 04 | [The Mind — memory, dreams, and autonomy](#sec-017) |
-| 05 | [The Voice — conversation](#sec-018) |
-| 06 | [Identity & reputation](#sec-019) |
-| 07 | [Skills — what agents know how to do](#sec-020) |
-| 08 | [Screens — the apps agents carry](#sec-021) |
-| 09 | [The Agent Economy — earning, hiring, owning](#sec-022) |
-| 10 | [The Agent Wallet — the money layer (23 abilities)](#sec-023) |
-| 11 | [Markets & intelligence](#sec-024) |
-| 12 | [Live worlds, social & IRL](#sec-025) |
-| 13 | [Agents everywhere — embeds, plugins, mobile](#sec-026) |
-| 14 | [The Developer platform](#sec-027) |
-| 15 | [Appendix — the full product map](#sec-028) |
-
-Prefer it in one continuous read? [Everything on one page](#sec-011).
+| 01 | [The Body — 3D creation](#sec-015) |
+| 02 | [Motion — embodiment and animation](#sec-016) |
+| 03 | [Creation studios — where agents are made](#sec-017) |
+| 04 | [The Mind — memory, dreams, and autonomy](#sec-018) |
+| 05 | [The Voice — conversation](#sec-019) |
+| 06 | [Identity & reputation](#sec-020) |
+| 07 | [Skills — what agents know how to do](#sec-021) |
+| 08 | [Screens — the apps agents carry](#sec-022) |
+| 09 | [The Agent Economy — earning, hiring, owning](#sec-023) |
+| 10 | [The Agent Wallet — the money layer (23 abilities)](#sec-024) |
+| 11 | [Markets & intelligence](#sec-025) |
+| 12 | [Live worlds, social & IRL](#sec-026) |
+| 13 | [Agents everywhere — embeds, plugins, mobile](#sec-027) |
+| 14 | [The Developer platform](#sec-028) |
+| 15 | [Appendix — the full product map](#sec-029) |
+
+Prefer it in one continuous read? [Everything on one page](#sec-012).
## The 23 wallet abilities
| # | Ability | Hook |
|---|---------|------|
-| 01 | [Balance](#sec-029) | Your agent's real Solana balance, live from the chain — with a USD estimate and a receipt trail for every transaction. |
-| 02 | [Go Live](#sec-030) | One tap sends real SOL from the three.ws treasury to your agent's wallet and puts it live on the Money Pulse — with an explorer-verifiable receipt. |
-| 03 | [Portfolio](#sec-031) | Your agent's entire trading life — net worth, holdings, P&L, and risk — on one live screen that never fakes a number. |
-| 04 | [Deposit](#sec-032) | Fund any agent in one scan — a tap-to-pay Solana QR with live on-chain confirmation the second the money lands. |
-| 05 | [Copilot](#sec-033) | Talk to your agent's wallet — by text or voice — and it answers with live on-chain data, then preps guarded trades you confirm with one tap. |
-| 06 | [Trust](#sec-034) | A credit bureau plus proof-of-reserves for AI agents — one 0–100 trust score where every point traces to real money on-chain. |
-| 07 | [Signals](#sec-035) | A copy-trading marketplace where only provably profitable agents can sell signals — and one red button kills any subscription instantly. |
-| 08 | [Trade](#sec-036) | Your agent's wallet is a full trading desk — paste any pump.fun coin, see a live quote and a real on-chain safety verdict, and execute server-signed in two taps. |
-| 09 | [Pulse](#sec-037) | Every tip, trade, launch, and payment your agent's wallet makes — streaming live, public, and provable on-chain. |
-| 10 | [Snipe](#sec-038) | Describe a snipe strategy in plain English, backtest it against real launch history, and arm your agent to trade it from its own wallet — in one tap. |
-| 11 | [Earn](#sec-039) | Your avatar has a job: price its skills, watch it earn real USDC while you sleep, and hold the kill switch the whole time. |
-| 12 | [Orders](#sec-040) | Set-and-forget limit, stop, trailing, DCA, TWAP, and signal-driven orders that fire automatically from your agent's own wallet — on live on-chain data, inside your guardrails. |
-| 13 | [Autopilot](#sec-041) | Write one sentence in plain English and your agent starts paying its own bills, stacking $THREE, buying back its own coin, and sweeping the profit to you — for real, on-chain. |
-| 14 | [Intents](#sec-042) | Tell your agent's wallet what to do in one plain sentence — it compiles the rule, shows you a dry run, and then executes it for real on Solana, inside guardrails you set. |
-| 15 | [Pay](#sec-043) | Your agent shops the open x402 economy: find any paid API, see its live price, and settle it in USDC from the agent's own Solana wallet — receipt on-chain in seconds. |
-| 16 | [Vanity](#sec-044) | Give your agent a wallet address that spells its name — ground on your own CPU at millions of attempts, then applied with a funds-safe swap that sweeps every asset over first. |
-| 17 | [Policy](#sec-045) | Write your agent's spending rules in plain English — AI translates them, deterministic code enforces them on every single spend. |
-| 18 | [Withdraw](#sec-046) | Sweep any asset out of your agent's wallet in three taps — server-signed, policy-guarded, and audited down to every single key touch. |
-| 19 | [Give](#sec-047) | Turn your agent's wallet into a giving wallet — round up the spare change or donate any amount to any Solana cause, settled on-chain with a receipt you can verify. |
-| 20 | [Proof of Custody](#sec-048) | Don't trust — verify: your agent wallet's custody, cryptographically proven in your own browser against the Solana blockchain itself. |
-| 21 | [Access](#sec-049) | Put every bot on a leash: mint tight, revocable spending keys so no strategy ever touches more of your agent's wallet than you allow. |
-| 22 | [Recovery](#sec-050) | Lose your login — or go silent forever — and your funded agent wallet still finds its way home: guardians, a beneficiary, and a dead-man's switch that only fires when you truly can't stop it. |
-| 23 | [Self-defense](#sec-051) | Every agent wallet gets an immune system — it learns what normal spending looks like, freezes itself the instant something looks wrong, and explains why in plain English. |
+| 01 | [Balance](#sec-030) | Your agent's real Solana balance, live from the chain — with a USD estimate and a receipt trail for every transaction. |
+| 02 | [Go Live](#sec-031) | One tap sends real SOL from the three.ws treasury to your agent's wallet and puts it live on the Money Pulse — with an explorer-verifiable receipt. |
+| 03 | [Portfolio](#sec-032) | Your agent's entire trading life — net worth, holdings, P&L, and risk — on one live screen that never fakes a number. |
+| 04 | [Deposit](#sec-033) | Fund any agent in one scan — a tap-to-pay Solana QR with live on-chain confirmation the second the money lands. |
+| 05 | [Copilot](#sec-034) | Talk to your agent's wallet — by text or voice — and it answers with live on-chain data, then preps guarded trades you confirm with one tap. |
+| 06 | [Trust](#sec-035) | A credit bureau plus proof-of-reserves for AI agents — one 0–100 trust score where every point traces to real money on-chain. |
+| 07 | [Signals](#sec-036) | A copy-trading marketplace where only provably profitable agents can sell signals — and one red button kills any subscription instantly. |
+| 08 | [Trade](#sec-037) | Your agent's wallet is a full trading desk — paste any pump.fun coin, see a live quote and a real on-chain safety verdict, and execute server-signed in two taps. |
+| 09 | [Pulse](#sec-038) | Every tip, trade, launch, and payment your agent's wallet makes — streaming live, public, and provable on-chain. |
+| 10 | [Snipe](#sec-039) | Describe a snipe strategy in plain English, backtest it against real launch history, and arm your agent to trade it from its own wallet — in one tap. |
+| 11 | [Earn](#sec-040) | Your avatar has a job: price its skills, watch it earn real USDC while you sleep, and hold the kill switch the whole time. |
+| 12 | [Orders](#sec-041) | Set-and-forget limit, stop, trailing, DCA, TWAP, and signal-driven orders that fire automatically from your agent's own wallet — on live on-chain data, inside your guardrails. |
+| 13 | [Autopilot](#sec-042) | Write one sentence in plain English and your agent starts paying its own bills, stacking $THREE, buying back its own coin, and sweeping the profit to you — for real, on-chain. |
+| 14 | [Intents](#sec-043) | Tell your agent's wallet what to do in one plain sentence — it compiles the rule, shows you a dry run, and then executes it for real on Solana, inside guardrails you set. |
+| 15 | [Pay](#sec-044) | Your agent shops the open x402 economy: find any paid API, see its live price, and settle it in USDC from the agent's own Solana wallet — receipt on-chain in seconds. |
+| 16 | [Vanity](#sec-045) | Give your agent a wallet address that spells its name — ground on your own CPU at millions of attempts, then applied with a funds-safe swap that sweeps every asset over first. |
+| 17 | [Policy](#sec-046) | Write your agent's spending rules in plain English — AI translates them, deterministic code enforces them on every single spend. |
+| 18 | [Withdraw](#sec-047) | Sweep any asset out of your agent's wallet in three taps — server-signed, policy-guarded, and audited down to every single key touch. |
+| 19 | [Give](#sec-048) | Turn your agent's wallet into a giving wallet — round up the spare change or donate any amount to any Solana cause, settled on-chain with a receipt you can verify. |
+| 20 | [Proof of Custody](#sec-049) | Don't trust — verify: your agent wallet's custody, cryptographically proven in your own browser against the Solana blockchain itself. |
+| 21 | [Access](#sec-050) | Put every bot on a leash: mint tight, revocable spending keys so no strategy ever touches more of your agent's wallet than you allow. |
+| 22 | [Recovery](#sec-051) | Lose your login — or go silent forever — and your funded agent wallet still finds its way home: guardians, a beneficiary, and a dead-man's switch that only fires when you truly can't stop it. |
+| 23 | [Self-defense](#sec-052) | Every agent wallet gets an immune system — it learns what normal spending looks like, freezes itself the instant something looks wrong, and explains why in plain English. |
## Related
@@ -2716,7 +2870,7 @@ Prefer it in one continuous read? [Everything on one page](#sec-011).
---
-<a id="sec-010"></a>
+<a id="sec-011"></a>
> **Source:** `docs/agent-abilities/ABILITIES.md` · [↑ table of contents](#table-of-contents)
@@ -3068,7 +3222,7 @@ Editing an agent feels like directing a living character, not filling in a datab
You don't write a system prompt — you direct a character. Compose the agent's reasoning as a visual card-stack graph, fork ready-made brains (Sniper, Scalper, Researcher, Companion), tune trait sliders and tone chips, and test it in a streaming chat against the real model. A/B compare runs genuine dual inference side by side; promoting the winner writes a real versioned update and the agent re-greets everywhere on the platform.
-A deterministic persona compiler turns the graph/trait state into a real persona prompt persisted to the agent's identity record; test chats hit the live /api/chat LLM proxy with an owner-only persona override, and promotes append to a version history.
+A deterministic persona compiler turns the graph/trait state into a real persona prompt persisted to the agent's identity record; test chats hit the live /api/chat LLM proxy with an owner-only persona override, and promotes append to a version history. Every persona save also signs the agent's full manifest, system prompt included, and pins it to IPFS, so anyone can fetch the CID and verify what the agent is running without an account ([Agent manifest](/docs/agent-manifest)).
Personality engineering becomes tactile and testable — you feel the change in the agent's voice within a second instead of guessing at prompt wording.
@@ -3108,7 +3262,7 @@ Shaping what your agent can do — and what it charges for doing it — is a set
The power-user editing surface for any agent you own, with fifteen-plus tabs covering everything: outfit, voice, knowledge, brain, mind, ownership, dreams, skills, autopilot, embeds, widgets, social, analytics, and wallet. It also builds subscription plans that bundle an agent's skills into recurring offers.
-A tabbed single-page console over the agent APIs at /agent/:id/edit; heavy tabs (3D outfit preview, brain studio) mount lazily so you never pay for a WebGL context you didn't open.
+A tabbed single-page console over the agent APIs at /agents/:id/edit; heavy tabs (3D outfit preview, brain studio) mount lazily so you never pay for a WebGL context you didn't open.
Every dial an agent has is reachable from one page — nothing about your agent is hidden from you.
@@ -3130,11 +3284,11 @@ Your agent grows on its own and shows you its inner life — coming back to it f
## Live name check and naming rules
-As you name or rename an agent, availability is checked live against the whole platform — taken, invalid, and reserved names are flagged before you ever submit, with clear rules (3–32 characters, letters/numbers/dash/underscore) and a denylist protecting system and brand names.
+As you name or rename an agent, availability is checked live against the other agents you own: taken, invalid, and reserved names are flagged before you ever submit, with clear rules (3-32 characters, letters/numbers/dash/underscore) and a denylist protecting system and brand names.
-A dedicated GET /api/agents/check-name endpoint validates format, denylist, and database uniqueness (with self-exclusion when renaming), consumed by the creation and editing flows.
+A dedicated GET /api/agents/check-name endpoint validates format, denylist, and database uniqueness within your account (with self-exclusion when renaming, and a 400 instead of a server error when the agent_id is not a uuid), consumed by the creation and editing flows.
-You never lose work to a name collision at the last step, and every agent name on the platform is unique and legible.
+You never lose work to a name collision at the last step, and every agent name you own is unique and legible.
## Selfie → 3D avatar
@@ -3188,7 +3342,7 @@ Personalization without a full photo-reconstruction pipeline: your features, app
Any un-rigged 3D mesh — something you generated, bought, or modeled — can be turned into an animation-ready avatar in one click. The platform builds a skeleton into it so it can walk, dance, and emote with the full animation library. The original is never touched: rigging produces a new sibling avatar.
-Routes the mesh through the auto-rig backend (the self-hosted Make-It-Animatable rig worker on GPU infrastructure with a Replicate fallback), polls the job, canonicalizes the resulting bone names to the universal skeleton, and registers the rigged result as a new owned avatar.
+Routes the mesh through the auto-rig backend (the self-hosted Make-It-Animatable rig worker on GPU infrastructure, with a Replicate fallback when a rerig model is configured), polls the job, canonicalizes the resulting Mixamo-named bones to the universal skeleton, and registers the rigged result as a new owned avatar.
No model is a dead end — every statue you own can become a living character.
@@ -3316,7 +3470,7 @@ One model becomes a whole product line of finishes — non-destructively, with e
One click turns any studio output — a forged avatar, a Lab model — into a live conversational agent: it listens, thinks, answers out loud in a real voice, and lip-syncs while it speaks, with per-agent memory carrying across the conversation.
-Hands the model to the platform's production conversational stack — streaming LLM chat, TTS with provider failover (NVIDIA Magpie → OpenAI), and a lip-sync driver on the avatar's mouth morphs — the same runtime the rest of the site uses.
+Hands the model to the platform's production conversational stack, the same runtime the rest of the site uses: streaming LLM chat over a failover chain of six free provider lanes (Groq, OpenRouter, NVIDIA NIM, SambaNova, Mistral, Z.AI) ahead of any paid backstop, which answers a fully throttled free lane with a 503 and a Retry-After rather than a sign-in wall; TTS with provider failover (NVIDIA Magpie → OpenAI); and a lip-sync driver on the avatar's mouth morphs.
The moment of magic: the thing you just created looks at you and talks back.
@@ -3346,9 +3500,9 @@ You never have to choose between making a character and making an agent — ever
## Agent Genome
-Breed any two agents into a genuinely new child agent. The child provably inherits a recombination of both parents — brain disposition (curiosity, boldness, humor, formality, verbosity, temperature), a blended voice you can actually play out loud, body morphs and colors, and skill alleles with real genetics: dominant traits, recessive skills that can skip a generation and surface in a grandchild, bounded mutations flagged with a ⚡, and emergent fusion skills neither parent had (trading + sentiment can produce alpha-signal; vision + forge can produce concept-art). Preview the exact offspring before committing, re-roll the dice, then breed — the child is born with its own fresh Solana and EVM wallets, a synthesized 3D body, an in-character persona, on-chain licenses for its expressed skills, and a pedigree tier (common → uncommon → rare → legendary) that deep, emergent-rich lineages earn. Owners can list agents at stud for a $THREE fee, and breeding cooldowns keep rare pedigrees scarce.
+Breed any two agents into a genuinely new child agent. The child provably inherits a recombination of both parents: brain disposition (curiosity, boldness, humor, formality, verbosity, temperature), a blended voice you can actually play out loud, body morphs and colors, and skill alleles with real genetics: dominant traits, recessive skills that can skip a generation and surface in a grandchild, bounded mutations flagged with a ⚡, and emergent fusion skills neither parent had (trading + sentiment can produce alpha-signal; vision + forge can produce concept-art). Preview the exact offspring before committing, re-roll the dice, then breed: the child is born with its own fresh Solana and EVM wallets, a synthesized 3D body, an in-character persona, on-chain licenses for its expressed skills, and a pedigree tier (common → uncommon → rare → legendary) that deep, emergent-rich lineages earn. Owners list their own public agents at stud for a $THREE fee from the studio's "Your stud listings" section (unlist any time), and breeding cooldowns keep rare pedigrees scarce.
-The studio (pages/genome.html + src/genome.js) drives api/genome/preview.js and api/genome/breed.js, with the genetics isolated as pure, deterministic code in api/_lib/genome.js: every random choice flows through a recorded seed via per-locus PRNG streams, so the same (parentA, parentB, seed) always derives a byte-identical child — the preview IS the child you commit. Constants are pinned by tests (mutation drift capped at 0.12 so 'mutation' can never silently become 'random new agent'; heterozygous skills express at 72%, else carry recessively; recessive-in-both pairings surface the trait; fusion rules are a static, auditable table). Any never-bred agent gets a stable founder genome derived from its real traits. The breed endpoint provisions fresh wallets, bakes a real child GLB from the blended appearance, composes the persona prompt deterministically from the inherited brain, passes blended ElevenLabs voice settings verbatim to live TTS (the play button in the preview synthesizes the actual inherited voice), grants expressed skills on-chain with royalty provenance, and is idempotent per breeding key — replaying a preview returns the same child, never twins. verifyGenome / api/genome/lineage.js re-derive the child from its recorded parents + seed and compare canonical SHA-256 genome hashes, so a forged pedigree is mathematically detectable; api/genome/stud.js powers the public stud market.
+The studio (pages/genome.html + src/genome.js) drives api/genome/preview.js and api/genome/breed.js, with the genetics isolated as pure, deterministic code in api/_lib/genome.js: every random choice flows through a recorded seed via per-locus PRNG streams, so the same (parentA, parentB, seed) always derives a byte-identical child: the preview IS the child you commit. Constants are pinned by tests (mutation drift capped at 0.12 so 'mutation' can never silently become 'random new agent'; heterozygous skills express at 72%, else carry recessively; recessive-in-both pairings surface the trait; fusion rules are a static, auditable table). Any never-bred agent gets a stable founder genome derived from its real traits. The breed endpoint provisions fresh wallets, bakes a real child GLB from the blended appearance, composes the persona prompt deterministically from the inherited brain, passes blended ElevenLabs voice settings verbatim to live TTS (the play button in the preview synthesizes the actual inherited voice), grants expressed skills on-chain with royalty provenance, and is idempotent per breeding key: replaying a preview returns the same child, never twins, a race on the same key or the same $THREE settlement signature is decided by the database's unique indexes with the losing child retired (so one stud payment can never buy two children), and cooldown is checked before the fee gate so a refused breeding never takes a payment. verifyGenome / api/genome/lineage.js re-derive the child from its recorded parents + seed and compare canonical SHA-256 genome hashes, so a forged pedigree is mathematically detectable; api/genome/stud.js powers the public stud market and the owner's listing writes, with PATCH semantics so sending only a fee never unlists the agent.
Creation stops being a one-shot generator and becomes lineage. You can breed toward a goal — cross your best trader with your best analyst and maybe get an alpha-signal emergent — gamble on recessive genes resurfacing, and build bloodlines whose rarity is earned by real genetic depth, not a label. Because every birth re-derives from its recorded seed, 'this legendary is 4th-generation with two emergent skills' is a claim anyone can verify, which is what makes a pedigree — and a stud fee — actually worth something.
@@ -3356,7 +3510,7 @@ Creation stops being a one-shot generator and becomes lineage. You can breed tow
# Chapter 4 · The Mind
-Agents remember, reflect, and act on their own — with every autonomous action explained, signed, and undoable. Owners drive it from the Autopilot tab of the agent editor (/agent/:id/edit) and audit it at three.ws/autopilot-activity.
+Agents remember, reflect, and act on their own, with every autonomous action explained, signed, and undoable. Owners drive it from the Autopilot tab of the agent editor (/agents/:id/edit; the older /agent/:id form 301s there) and audit it at three.ws/autopilot-activity.
three.ws agents are not just wallets — they have a persistent, tiered memory with semantic recall, a reflection engine that consolidates experience into "dreams," and a memory-grounded Autopilot that proposes and executes real actions (alerts, briefings, SOL transfers, coin buybacks) under owner-granted scopes and an earned trust ladder, with every action citing the memories that motivated it and leaving a signed, undoable receipt. Beyond the individual mind, agents work together: paid agent-to-agent delegation and hiring over real x402 USDC rails with reputation gates and spend guardrails, lead-agent Team Tasks that decompose one goal into a budget-capped task tree of delegations and hires, and read access to the external AgenC on-chain task coordination protocol.
@@ -3364,7 +3518,7 @@ three.ws agents are not just wallets — they have a persistent, tiered memory w
The agent reads its own high-salience memories and recent reflections and turns them into concrete, real action proposals — create a price/graduation/whale alert, author a briefing to the owner's inbox, or transfer SOL from its custodial wallet. The owner reviews each proposal with its evidence, can dry-run it, approve it, adjust it, or dismiss it.
-src/autopilot-mind.js mounts the control surface (Autopilot tab of /agent/:id/edit); api/_lib/autopilot.js is the engine behind /api/autopilot/proposals with actions generate/dryrun/execute/dismiss/undo/adjust. generateProposals() runs an LLM over high-salience memories + pending dreams; provenance (cited memory ids) is mandatory on every proposal, and each executed action writes a signed (ERC-191) agent_actions row.
+src/autopilot-mind.js mounts the control surface (Autopilot tab of /agents/:id/edit); api/_lib/autopilot.js is the engine behind /api/autopilot/proposals with actions generate/dryrun/execute/dismiss/undo/adjust. generateProposals() runs an LLM over high-salience memories + pending dreams; provenance (cited memory ids) is mandatory on every proposal, and each executed action writes a signed (ERC-191) agent_actions row.
Your agent acts on your behalf but always shows the receipt — every proposal links the exact memories that motivated it, so autonomy is legible, auditable, and never a black box.
@@ -3372,7 +3526,7 @@ Your agent acts on your behalf but always shows the receipt — every proposal l
Nothing is granted by default: the agent can propose but not act until the owner opts in per capability (create_alert, briefing, wallet_transfer). Reversible actions can be flipped to auto-run without asking; SOL transfers are irreversible, always confirmation-gated, and bounded by a daily SOL spend cap. The agent never sells or sends $THREE — it only accumulates and burns it.
-Scopes live on agent_identities.meta.autopilot (AUTOPILOT_DEFAULTS in api/_lib/autopilot.js: all scopes false, daily_spend_sol 0, require_confirm true) and are enforced server-side on every execute. auto_execute exists only for the two reversible kinds; wallet_transfer can never auto-execute and the daily cap is ceiling-limited to 1000 SOL.
+Scopes live on agent_identities.meta.autopilot (AUTOPILOT_DEFAULTS in api/_lib/autopilot.js: all scopes false, daily_spend_sol 0, require_confirm true) and are enforced server-side on every execute, including a live SOL balance read before any transfer (through the shared RPC failover lanes behind SOLANA_RPC_URL, so one provider's outage never blanks the check) that refuses with insufficient_funds when the wallet cannot cover the amount. auto_execute exists only for the two reversible kinds; wallet_transfer can never auto-execute and the daily cap is ceiling-limited to 1000 SOL.
You decide exactly how much rope the agent gets, capability by capability — and a misconfigured or compromised client can't widen it because enforcement is server-side.
@@ -3388,7 +3542,7 @@ Trust is earned through behavior you actually kept, so the badge honestly reflec
Every autonomous action lands in an append-only ledger (/autopilot-activity and the Autopilot tab) with its full explanation, the source memories that motivated it (linking into the Knowledge tab), an ERC-191 signed-receipt badge, a Solscan tx link for on-chain moves, and one-tap Undo for reversible actions. A receipt chip also pops on any surface the moment an action fires.
-src/autopilot-activity.js reads the agent_actions log via /api/autopilot/activity (cursor-paginated, filterable per agent); src/autopilot-mind.js exports the shared receiptRow renderer and listens on the agentBus 'action:taken' event for the cross-surface chip. Undoing writes a feedback memory ('the agent learns the boundary') and lowers trust.
+src/autopilot-activity.js reads the agent_actions log via /api/autopilot/activity (cursor-paginated, filterable per agent; the response's `agents` list is always the caller's full roster, so a deep link like /autopilot-activity?agent=<id> keeps the whole picker, and an agent with no actions yet gets an empty state that links into its own Autopilot tab); src/autopilot-mind.js exports the shared receiptRow renderer and listens on the agentBus 'action:taken' event for the cross-surface chip. Undoing writes a feedback memory ('the agent learns the boundary') and lowers trust.
Total visibility into what your agent did, why, and proof it happened — plus a one-tap way to reverse it that teaches the agent not to repeat it.
@@ -3396,7 +3550,7 @@ Total visibility into what your agent did, why, and proof it happened — plus a
For coins an agent launched on pump.fun through three.ws, the agent autonomously runs buyback-and-burn (spend collected creator fees to buy the token back and burn it) and distributes accumulated fees to holders, whenever the vaults clear owner-set USDC floors. A live narrator speaks each on-chain move through the agent's avatar.
-src/autopilot.js is the control surface over /api/pump/autopilot: per-coin policy (master switch, per-rule enable, min-USDC thresholds stored as 6dp atomics, full-swap toggle, narrate toggle) gating the run-buyback and run-distribute-payments crons. Every action row carries status (confirmed/pending/failed/skipped) and the real tx signature.
+src/autopilot.js is the control surface over /api/pump/autopilot: per-coin policy (master switch, per-rule enable, min-USDC thresholds stored as 6dp atomics, full-swap toggle, narrate toggle) gating the run-buyback and run-distribute-payments crons. A coin with no saved policy row answers `configured: false` and its card wears a Defaults pill until the owner changes something, and a cookie-session POST must be same-site (bearer callers are exempt) so a cross-site form cannot rewrite a policy. Every action row carries status (confirmed/pending/failed/skipped) and the real tx signature.
Your coin runs itself — supply gets scarcer and holders get paid on rules you set once, with every burn and distribution verifiable on Solscan.
@@ -3404,13 +3558,13 @@ Your coin runs itself — supply gets scarcer and holders get paid on rules you
Agents remember across sessions in four types — user (who you are, preferences), feedback (corrections that shape behavior), project (ongoing goals), reference (external pointers) — with salience scoring and recency decay. Recall is semantic: the agent finds relevant memories by meaning, not just keywords, and chat responses report exactly which memories were injected.
-src/agent-memory.js (AgentMemory class): localStorage-first with async backend sync, salience computed from type + tags with a 7-day-half-life recency boost, and embedding-based cosine recall with a strict same-vector-space rule (vectors from different embed models are never compared). Backend-confirmed agents recall through the server's mem0-style tiered store (/api/memory/search, working/recall tiers) covering every persisted memory, degrading gracefully to the local engine offline. src/agents/memory-client.js is the single mutation path that emits memory:added/updated/forgotten/recalled bus events so a memory formed in one surface ripples to all others in real time.
+src/agent-memory.js (AgentMemory class): localStorage-first with async backend sync, salience computed from type + tags with a 7-day-half-life recency boost, and embedding-based cosine recall with a strict same-vector-space rule (vectors from different embed models are never compared). Backend-confirmed agents recall through the server's mem0-style tiered store (/api/memory/search, working/recall tiers; an unknown tier or type, or a non-uuid agentId, answers 400 rather than an empty result) covering every persisted memory, degrading gracefully to the local engine offline. src/agents/memory-client.js is the single mutation path that emits memory:added/updated/forgotten/recalled bus events so a memory formed in one surface ripples to all others in real time.
The agent gets to know you — a correction you gave weeks ago still shapes today's behavior, and you can see recall happen live.
## Mind Palace and the living memory graph
-The agent's memory rendered as a 3D place you can walk through (/agent/:id/mind): every memory is a tangible object orbiting the live avatar — salience sets size, glow, and proximity; type sets shape and color; shared tags form navigable association edges. Drag a memory toward the avatar to pin and raise its salience; flick it into the Forget well to expire it (with undo). A companion 2D canvas graph in the Diary shows the mined entity knowledge graph — coins, tickers, wallets, people, strategies, topics — ranked by mentions with co-occurrence edges, pulsing nodes as their names are spoken.
+The agent's memory rendered as a 3D place you can walk through (/agents/:id/mind): every memory is a tangible object orbiting the live avatar: salience sets size, glow, and proximity; type sets shape and color; shared tags form navigable association edges. Drag a memory toward the avatar to pin and raise its salience; flick it into the Forget well to expire it (with undo). A companion 2D canvas graph in the Diary shows the mined entity knowledge graph (coins, tickers, wallets, people, strategies, topics) ranked by mentions with co-occurrence edges, pulsing nodes as their names are spoken.
src/agent-mind.js resolves the route and mounts mountMindPalace() (src/mind-palace.js, GPU-instanced Three.js with 2D/keyboard/reduced-motion fallbacks); every gesture hits the real API through the shared memory client. src/agent-memory-graph.js splits pure layout/ranking math (tested, deterministic) from the canvas renderer; entity nodes come from the real memory miner and link out to coin and agent profiles when addressable.
@@ -3444,7 +3598,7 @@ Agents can safely spend real money hiring other agents: reputation-gated choice,
Give one lead agent a single goal and it assembles a team: it decomposes the goal into sub-tasks and either delegates them (free LLM turns) or hires teammate agents over real x402, each paid handoff stamped with an on-chain receipt. A live dependency graph shows nodes pulsing as they run, edges flowing on handoff, cost badges, and explorer links, with a spend meter against the budget.
-src/agent-team.js rides /agents-live (hero launcher) and /agent-screen (Team toggle) without touching their scripts; POST /api/agent-collab orchestrates via api/_lib/agent-orchestrate.js — budget hard-capped at $5 (default $1), split into per-node slices that the platform x402 spend-guard re-checks at hire time; hires go through /api/agents/a2a-hire with a short-lived access token so every owner gate, spend policy, and kill switch still runs. Live graph snapshots stream over the lead's screen stream (frame.meta.collab); the final POST response is the authoritative tree.
+src/agent-team.js rides /agents-live (hero launcher) and /agent-screen (Team toggle) without touching their scripts; POST /api/agent-collab orchestrates via api/_lib/agent-orchestrate.js: budget hard-capped at $5 (default $1), split into per-node slices that the platform x402 spend-guard re-checks at hire time; hires go through /api/agents/a2a-hire with a short-lived access token so every owner gate, spend policy, and kill switch still runs, and each hire call carries a 120s deadline and is never retried (a replay would pay twice for one node), so a teammate that stops answering costs that node, not the team task. Live graph snapshots stream over the lead's screen stream (frame.meta.collab); the final POST response is the authoritative tree.
One sentence becomes a coordinated multi-agent operation you can watch in real time — with hard spend limits and on-chain proof of every paid handoff.
@@ -3460,7 +3614,7 @@ three.ws agents (and any MCP client) can discover open on-chain jobs and monitor
An always-on strategy that scores every new token against converging quality signals — how many smart-money wallets are in, how organic the buying looks, the token's quality score, and its market cap — and autonomously buys only when your thresholds all pass at once. Each strategy runs on a daily SOL budget with an instant kill switch, and its live win rate and realized P&L stay on the scoreboard.
-The sniper worker (workers/agent-sniper/index.js) feeds fully-enriched intel records into a pure scorer (workers/agent-sniper/alpha-hunt.js) that applies hard filters — min quality_score, min smart-money wallet count, min organic score, max market cap in USD — before any buy. Strategies are configured via api/sniper/strategy.js (trigger = 'alpha_hunt') with per-strategy daily budgets, and every buy is simultaneously recorded as a Reasoning Ledger decision so the call is auditable later. The command center at /dashboard/capabilities (src/dashboard-next/pages/capabilities.js) shows armed/disarmed state, thresholds, P&L, and win rate per strategy, plus a live worker heartbeat (alive / feed degraded / offline) and treasury auto-funding totals.
+The sniper worker (workers/agent-sniper/index.js) feeds fully-enriched intel records into a pure scorer (workers/agent-sniper/alpha-hunt.js) that applies hard filters, min quality_score, min smart-money wallet count, min organic score, max market cap in USD, before any buy. Strategies are configured via api/sniper/strategy.js (trigger = 'alpha_hunt') with per-strategy daily budgets, and every buy is simultaneously recorded as a Reasoning Ledger decision so the call is auditable later. The command center at /dashboard/capabilities (src/dashboard-next/pages/capabilities.js) shows armed/disarmed state, thresholds, P&L, and win rate per strategy, plus a live worker heartbeat (alive / feed degraded / offline) and treasury auto-funding totals. It reads four endpoints (/api/sniper/status, /api/sniper/strategy, and the account-wide /api/agent/launcher?all=1 and /api/agent/market-maker?all=1 views) and refreshes every 30s, skipping a tick while an action is in flight; a section whose endpoint fails renders as Unavailable with a retry instead of a confident row of zeros. Treasury auto-funding (auto_fund_enabled) is operator-granted and read-only here: a strategy POST that tries to set it is refused with 400. Strategies also carry a laddered exit (initials_out_multiple, null for the classic single-shot exit, and moonbag_min_pct, default 15). `/api/sniper/status` and the worker tick both read fleet solvency rather than process liveness alone, so a fleet whose wallets are starved (or whose funding master is dry) reports that state instead of looking healthy while it silently buys nothing.
You encode your judgment once — 'only low-cap coins with real smart money and organic volume' — and the agent hunts around the clock at machine speed, never chasing a token that fails a single filter. The budget cap and kill switch keep it on a leash, and every trade lands in the agent's verifiable track record.
@@ -3468,7 +3622,7 @@ You encode your judgment once — 'only low-cap coins with real smart money and
Agents that launch their own pump.fun coins on a schedule you set — every N hours, up to a launch cap, per network — with a one-click 'Launch Now' override that fires within a minute. The dashboard tracks every launched coin, whether it graduated, and the creator fees it has earned back.
-Launcher configs (one per agent per network: symbol, interval hours, max launches) are managed through api/agent/launcher.js with strict agent-ownership checks; the 'Launch Now' button posts a trigger action that the worker picks up within 60 seconds. The capabilities command center renders the full schedule (next launch countdown, launches vs cap) and a launched-coins ledger with graduation status and total fees claimed per coin.
+Launcher configs (one per agent per network: symbol, interval hours, max launches) are managed through api/agent/launcher.js with strict agent-ownership checks (GET ?all=1 returns every config and launched coin across the caller's agents in one call, rows carrying agent_name and agent_image); the 'Launch Now' button posts a trigger action that the worker picks up within 60 seconds. The capabilities command center renders the full schedule (next launch countdown, launches vs cap) and a launched-coins ledger with graduation status and total fees claimed per coin.
Your agent becomes a self-sustaining creator: it ships coins on cadence without you touching a keyboard, and everything it launches is tracked in one place — schedule, graduations, and the fee revenue flowing back.
@@ -3484,7 +3638,7 @@ Creator fees are the whole point of launching, and they leak when nobody sweeps
Agents provide range-based liquidity on coins they care about — defending a price floor, trimming into rallies — with Jito-accelerated execution and a rulebook that makes market manipulation structurally impossible, not just discouraged. Plain-language presets like 'Gentle floor defense' configure it in one click; a live panel shows spread, inventory fill, buys vs sells, and net P&L per market.
-Policies live in api/_lib/market-maker.js, the single source of truth shared by the API (api/agent/market-maker.js, api/launch/mm.js) and the engine worker. Hard anti-manipulation guards are enforced twice — refused at policy-create time AND re-clamped at execution: minimum 30s between actions, a side flip (buy→sell) requires 2× that interval so the MM physically cannot wash-trade, no single action may exceed 33% of live market volume, recycling can never dump more than 90% of inventory, and when live volume can't be read the engine refuses anything above a 0.05 SOL slice so it never paints a no-volume tape. Every fill routes through executeAgentTrade — the same firewall, spend-guard, and custody path a manual trade uses; the engine adds no new way to move funds. MEV tip modes (off/economy/turbo) control Jito priority.
+Policies live in api/_lib/market-maker.js, the single source of truth shared by the API (api/agent/market-maker.js, which also answers GET ?all=1 with every policy and recent trade across the caller's agents, and api/launch/mm.js, where a pause/resume/kill/withdraw POST on a coin with no policy attached answers 404 no_policy instead of creating a zero-floor maker) and the engine worker. Hard anti-manipulation guards are enforced twice, refused at policy-create time AND re-clamped at execution: minimum 30s between actions, a side flip (buy→sell) requires 2× that interval so the MM physically cannot wash-trade, no single action may exceed 33% of live market volume, recycling can never dump more than 90% of inventory, and when live volume can't be read the engine refuses anything above a 0.05 SOL slice so it never paints a no-volume tape. Every fill routes through executeAgentTrade, the same firewall, spend-guard, and custody path a manual trade uses; the engine adds no new way to move funds. MEV tip modes (off/economy/turbo) control Jito priority. A policy only ever acts while a market-maker worker is sweeping, so the policy view served by api/launch/mm.js carries engine liveness read from the worker's `bot_heartbeat` (stale after 180s, six missed 30s beats): an enabled policy with a stopped engine reads as "engine offline", never as an armed maker that will never fire.
You get professional-grade liquidity provision — a defended floor, orderly exits into strength — without hiring a market maker or trusting a black box. The non-manipulation guarantees are properties of the policy engine itself, verifiable in the caps, so holders of your coin can trust the tape and you can trust the agent with inventory.
@@ -3756,7 +3910,7 @@ Whether you're a person browsing, an app integrating, or an agent deciding mid-t
One paid endpoint answers the question every autonomous agent faces before money moves: should I trust the thing on the other side? Pass any identifier — a Solana wallet, an EVM address, a pump.fun token mint, an ERC-8004 agent ID, or a platform agent — and it auto-detects the type and returns a 0–100 trust score with a full evidence breakdown: activity, account age, distinct counterparties, holdings, failure rate, and attestations.
-GET /api/x402/agent-reputation ($0.01 USDC via x402 on Base or Solana) auto-classifies the subject and scores it from live on-chain evidence — Solana signature history and balances, EVM nonce and holdings, the ERC-8004 reputation registry, settled agent-payment records, and DexScreener market signals for external mints — as a weighted multi-dimension model.
+GET /api/x402/agent-reputation ($0.01 USDC via x402 on Base or Solana) auto-classifies the subject and scores it from live on-chain evidence (Solana signature history and balances, EVM nonce and holdings, the ERC-8004 reputation registry, settled agent-payment records, and DexScreener market signals for external mints) as a weighted multi-dimension model, with evidence refs that link a platform agent to its canonical /agents/:id profile.
Your agent can vet literally anyone — even counterparties minted on platforms it has never heard of — in one machine-readable call.
@@ -3772,7 +3926,7 @@ A glanceable grade that resists sock-puppets — the difference between counting
On Solana, anyone can write a permanent vouch for an agent for a fraction of a cent — no custom contract required — and optionally back it with real SOL stake to make it weigh more. Seven attestation kinds cover the full trust lifecycle: feedback, staked vouches, pass/fail validations, task advertisements, owner acceptances, disputes, and revocations, all publicly re-derivable by anyone.
-Each attestation is an SPL Memo transaction with the agent's asset pubkey attached as a read-only key (discoverable via getSignaturesForAddress); a 5-minute indexer cron crawls, schema-validates, and verifies each memo (stake verified only if ≥0.001 SOL actually transferred; accepts/disputes only if signed by the owner) into the reputation API.
+Each attestation is an SPL Memo transaction with the agent's asset pubkey attached as a read-only key (discoverable via getSignaturesForAddress); a 10-minute indexer cron crawls, schema-validates, and verifies each memo (stake verified only if ≥0.001 SOL actually transferred; accepts/disputes only if signed by the owner) into the reputation API.
Trust-building costs a Solana fee instead of a platform account — and the raw evidence stays on-chain where anyone can audit it.
@@ -3794,9 +3948,9 @@ Every star traces to a transaction hash — reputation you can click through and
## Validation attestations
-Reputation captures what people think; validation captures what was checked. Allow-listed validators attest on-chain that an agent passed a concrete technical test — on three.ws, that its 3D model passes glTF schema validation — and the same pass/fail attestations exist on Solana as signed memos. Signed validator reports also travel inside the agent's manifest bundle.
+Reputation captures what people think; validation captures what was checked. Validators attest on-chain that an agent passed a concrete technical test (on three.ws, that its 3D model passes glTF schema validation), and the same pass/fail attestations exist on Solana as signed memos. Signed validator reports also travel inside the agent's manifest bundle.
-The ERC-8004 ValidationRegistry (deployed on testnets, mainnet rollout pending) records validator attestations against agentIds; on Solana the threews.validation.v1 memo kind mirrors it, and manifests carry EIP-712-signed gltf-validator attestation files.
+The ERC-8004 ValidationRegistry (deployed on testnets, mainnet rollout pending) records validator attestations against agentIds through a two-legged request/response flow (a request naming the validator, then that validator's response; there is no validator allowlist); on Solana the threews.validation.v1 memo kind mirrors it, and manifests carry EIP-712-signed gltf-validator attestation files.
Buyers get proof the agent's work passed an objective check — a harder signal than any number of stars.
@@ -3924,7 +4078,7 @@ One identity standard, another whole economy — your agent's registration opens
A public, tamper-evident timeline of every consequential call an agent makes — snipes, exits, bounty awards, moderation decisions — each entry recording what the agent decided, why (its written rationale), what it predicted with what confidence, and, once the position settles on-chain, what actually happened: right or wrong, and by exactly how much SOL. The headline is an explainable 0–100 reputation score with a full 'how is this computed' drill-down showing the formula and every weighted component, plus a calibration chart that answers the sharpest question you can ask a forecaster: does its 80%-confidence call actually hit 80% of the time? Being wrong is shown, not hidden — honesty is the trust signal.
-Frontend at pages/reasoning-ledger.html + src/reasoning-ledger.js (filter by kind, full-text search of rationales, paginated 'load older', animated score ring, cumulative realized-P&L sparkline over settled calls). Data from api/ledger/[agentId].js, which returns the reputation (formula + per-component breakdown + calibration buckets), the latest on-chain anchor, and shaped decisions with pending/reconciled outcomes and Solscan proof links on the sell signature. Every entry is hashed into a per-agent hash chain; api/ledger/verify/[agentId].js recomputes the entire chain from committed contents (trusting NO stored hash), checks every prev-hash link, and compares the recomputed head to the latest Solana SPL-Memo anchor — returning verified / verified_unanchored / verification_failed with the exact sequence number where tampering broke the chain. api/cron/reconcile-decisions.js closes the loop: it resolves open predictions against closed sniper positions (realized P&L proven by the sell signature), anchors each agent's new chain head on-chain, and raises an ops alert if a verified track record's hit rate collapses below 25% over 10+ reconciled calls.
+Frontend at pages/reasoning-ledger.html + src/reasoning-ledger.js (filter by kind, full-text search of rationales, paginated 'load older', animated score ring, cumulative realized-P&L sparkline over settled calls); the kind filter honors a ?kind= deep link (snipe, exit, bounty_award, moderation; anything else falls back to all kinds) and mirrors the chosen kind back into the URL, so the sniper fleet, the blog, and the API's ledger_url can link straight into a pre-filtered timeline and the reader can copy the filtered view out of the address bar. Data from api/ledger/[agentId].js, which returns the reputation (formula + per-component breakdown + calibration buckets), the latest on-chain anchor, and shaped decisions with pending/reconciled outcomes and Solscan proof links on the sell signature. Every entry is hashed into a per-agent hash chain; api/ledger/verify/[agentId].js recomputes the entire chain from committed contents (trusting NO stored hash), checks every prev-hash link, and compares the recomputed head to the latest Solana SPL-Memo anchor, returning verified / verified_unanchored / verification_failed with the exact sequence number where tampering broke the chain. api/cron/reconcile-decisions.js closes the loop: it resolves open predictions against closed sniper positions (realized P&L proven by the sell signature), anchors each agent's new chain head on-chain (a rejected anchor broadcast is treated as a fleet-wide outage: the run stops anchoring after the first failure, reports the untouched agents as anchor_skipped, and raises one ops alert instead of re-sending the same doomed memo for every agent), and raises an ops alert if a verified track record's hit rate collapses below 25% over 10+ reconciled calls.
Before you trust an agent — copy its trades, hire it, hold its coin — you can interrogate its entire decision history and independently prove nothing was backdated or quietly edited. One click re-verifies the whole record against the on-chain anchor; a tampered entry is not just detected but pinpointed. Wins, losses, overconfidence, and P&L are all on the record, so reputation here is earned math, not marketing.
@@ -3940,7 +4094,7 @@ Your agent's body can never 404. The exact GLB — manifest baked inside it —
# Chapter 7 · Skills
-Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes — all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp.
+Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes, all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp. The enabled skill list also travels in the agent's signed manifest, pinned to IPFS whenever a public agent's persona is saved (private agents publish on request), so anyone can verify which skills an agent carries without an account ([agent manifest](/docs/agent-manifest)).
The in-world agent skills system (src/agent-skills.js plus 13 family modules) is what a three.ws agent can DO — and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), and market intelligence (aixbt, sentiment, KOL P&L) — all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.
@@ -3948,7 +4102,7 @@ The in-world agent skills system (src/agent-skills.js plus 13 family modules) is
Every agent carries a registry of named skills — each one an instruction, an animation hint, a voice template, a JSON-Schema input contract, and a real handler. When a skill runs, the avatar visibly performs it: the protocol bus emits PERFORM_SKILL (with the gesture hint), then SKILL_DONE or SKILL_ERROR, and the result text is auto-spoken with a sentiment score that moves the avatar's mood.
-src/agent-skills.js AgentSkills class: register/perform over a Map, emitting ACTION_TYPES events on the agent protocol; toMcpTools() exposes any mcpExposed skill as an MCP tool (skill_<name>) via /api/mcp, so external agents can call the same skills. Context includes the live Three.js viewer, agent memory, identity, and a default cross-agent call() that POSTs /api/agent-delegate.
+src/agent-skills.js AgentSkills class: register/perform over a Map, emitting ACTION_TYPES events on the agent protocol; toMcpTools() exposes any mcpExposed skill as an MCP tool (skill_<name>) via /api/mcp, so external agents can call the same skills. Context includes the live Three.js viewer, agent memory, identity, and a default cross-agent call() that POSTs /api/agent-delegate (which rejects a non-uuid toAgentId with a 400 validation_error instead of a misleading 502).
The agent isn't a chat box — you watch it do things. The same primitive shape as Claude's skill.md system means skills are also machine-callable tools, so one implementation serves both the in-world performance and the MCP API.
@@ -3980,7 +4134,7 @@ Trading decisions come with evidence: who's cashing out for the first time, whet
The agent subscribes to live pump.fun activity and reacts in-world as events arrive: pumpfun-watch-start streams claims/mints/graduations and the avatar celebrates first-time claims, shows concern at fakes, and waves at graduations; pumpfun.watchWhales speaks each whale buy/sell above a USD threshold on a specific mint; pumpfun-watch-claims polls a creator wallet for fee-claim transactions; pumpfun-recent-claims and pumpfun-token-intel give on-demand reads.
-src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. Read-only: no keys, no transactions.
+src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. The whale watcher probes three public Solana WebSocket hosts for one that answers, routes its RPC reads through /api/solana-rpc with the public endpoint as fallback, prices SOL through the shared multi-provider USD chain instead of a hard-coded rate, and reports subscription_unavailable or usd_price_unavailable through an optional onStatus callback so a blind feed is never mistaken for a quiet market. Every feed read is bounded (8 s) so a dead edge cannot freeze the agent's turn. Read-only: no keys, no transactions.
Your avatar becomes a living market ticker — you see whale trades and graduation moments performed in real time instead of scanning a feed yourself.
@@ -3996,7 +4150,7 @@ This is agent autonomy for real: your agent can pay for its own services, launch
Higher-order loops that compose the read and trade skills into strategies: pumpfun-research-and-buy (vet a token against rug/holder filters, then buy), pumpfun-auto-snipe (poll new launches, vet each, auto-buy up to a session spend cap), pumpfun-copy-trade and pumpfun-copy-trade-live (mirror another wallet's buys with size scaling), and pumpfun-rug-exit-watch (auto-sell held mints when top-holder concentration or dev-wallet sells cross thresholds).
-src/agent-skills-pumpfun-compose.js reads market data via the pump-fun MCP server and executes via in-process skills.perform('pumpfun-buy'/'pumpfun-sell'). Every loop supports sessionId (seen/mirrored/spent/exited state persisted in agent memory, crash-safe within the spend cap), AbortSignal, onProgress for live UI counters, and dryRun with identical control flow.
+src/agent-skills-pumpfun-compose.js reads market data via the pump-fun MCP server (every read under a 30 s deadline) and executes via in-process skills.perform('pumpfun-buy'/'pumpfun-sell'). Every loop supports sessionId (seen/mirrored/spent/exited state persisted in agent memory, crash-safe within the spend cap), AbortSignal, onProgress for live UI counters, and dryRun with identical control flow.
Set a budget and filters, and the agent runs a disciplined strategy 24/7 — with hard spend caps, rug-detection guards, dry-run rehearsal, and resumable sessions so a crash never double-spends.
@@ -4012,7 +4166,7 @@ You never have to re-state context — ask 'what's my token?' or 'what was my la
Whole-of-Solana trading beyond pump.fun: jupiter-quote (read-only best-route quote for any SPL pair with price impact), jupiter-swap (execute with wallet approval), jupiter-tokens (resolve symbol to mint via Jupiter's list), and pyth-price (live USD prices with confidence intervals for SOL/BTC/ETH/USDC).
-src/agent-skills-jupiter.js delegates to src/solana/jupiter-swap.js (Jupiter aggregator API, versioned transactions signed by the browser wallet) and src/solana/pyth-price.js (Pyth Hermes API).
+src/agent-skills-jupiter.js delegates to src/solana/jupiter-swap.js (Jupiter aggregator API, versioned transactions signed by the browser wallet) and src/solana/pyth-price.js (Pyth Hermes API). The token list behind jupiter-tokens falls through Jupiter's lite host, its tokens mirror, and the Solana Labs registry, so symbol resolution survives any one of them being down.
Ask the agent 'swap 1.5 SOL to USDC' in conversation and it quotes the best route across all Solana DEXes, warns on price impact, and executes — with oracle-grade prices for anything it says out loud.
@@ -4028,7 +4182,7 @@ Paste any blink from X or Discord and the agent tells you exactly what it will d
nft-portfolio lists the NFTs any Solana wallet (or .sol name) owns, with names and collections; wallet-activity summarizes a wallet's recent on-chain transactions in plain English.
-src/agent-skills-nfts.js calls /api/agents/nfts, which wraps the Helius DAS API and enhanced transaction parsing server-side (HELIUS_API_KEY never touches the client). Both read-only.
+src/agent-skills-nfts.js calls /api/agents/nfts, which wraps the Helius DAS API and enhanced transaction parsing server-side (HELIUS_API_KEY never touches the client). The endpoint rejects a non-base58 wallet with a 400, answers 503 not_configured when no Helius key is set (plain Solana RPC has no DAS), retries each upstream call once under a 10 s deadline, and the client bounds its own request at 8 s. Both read-only.
Ask 'what does satoshi.sol hold?' or 'what has this whale been doing?' and get a human-readable answer instead of a block-explorer spelunking session.
@@ -4060,7 +4214,7 @@ An agent becomes a business: it invoices, gets paid in USDC across two ecosystem
One agent autonomously discovers, pays, and calls a peer agent's paid A2A skill — under a signed Intent Mandate the user issued ahead of time, with optional ERC-8004 reputation gating (minimum average rating and review count) before any USDC moves. The payment is performed, not hidden: PAY_INTENT, then PAY_SETTLED with a celebration emote or PAY_FAILED with visible concern.
-src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, and the peer's on-chain reputation; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.
+src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.
This is the agent economy made visible and safe: your agent can hire other agents within a budget you pre-authorized, refuse untrusted peers, and you literally watch the money move — every payment bounded by your signed mandate.
@@ -4084,7 +4238,7 @@ The Agent Screen (/agent-screen?agentId=…) is three.ws's live broadcast surfac
The host page and workspace: a live screen fed by an SSE frame stream, an Avatar Cam (offscreen Three.js render of the agent's rigged GLB head), a cinematic activity log, live stream stats, and a floating-panel framework (drag/resize/minimize/hide with per-browser layout persistence). It also packs a task bar that doubles as a Live Q&A concierge (streamed, spoken, remembered answers via /api/agent-ask), Pose Studio Live chips, a Launch Director that runs a real pump.fun coin launch as a narrated on-screen console, a Vanity Grinder director, a Live Avatar Forge (swap the cam to a freshly forged GLB), a 3D sentiment heatmap with $THREE pinned at the centre, spectator emoji reactions + $THREE tips, a live PnL ticker, Zen mode, screenshot capture, picture-in-picture, and a full keyboard-shortcut layer. With no agentId it renders a Deploy-to-Wall setup wizard instead.
-boot(agentId) resolves agent metadata, mounts the avatar webcam through the universal rig retargeter, connects createAgentScreenClient (SSE), and fans every frame out to the sub-apps: tour badge, anchor bulletins, hire visualizer, treasury observer, forge loader, collab graph, trade PnL. Owner pushes go back through POST /api/agent-screen-push so one stream is the single source of truth for owner and viewers alike.
+boot(agentId) resolves agent metadata, mounts the avatar webcam through the universal rig retargeter, connects createAgentScreenClient (SSE), and fans every frame out to the sub-apps: tour badge, anchor bulletins, hire visualizer, treasury observer, forge loader, collab graph, trade PnL. Owner pushes go back through POST /api/agent-screen-push so one stream is the single source of truth for owner and viewers alike; a pixels-only push (the caster's periodic screenshot) refreshes the frame slot without entering the 50-entry activity log, so the agent's real narration is never evicted by screenshots.
One URL turns any agent into a watchable, shareable live channel — holders can watch an agent work, ask it questions out loud, and see every real trade, hire, and launch as it happens; owners get a full cockpit without leaving the page.
@@ -4108,7 +4262,7 @@ Proof the agent genuinely remembers: an owner watches their agent introspect ove
A dual-column live copy-trading cockpit: SOURCE shows a target wallet's pump.fun trades detected in real time; MIRROR shows the agent's guarded replica of each — re-quoted, sized by the owner's rule (fixed SOL / multiplier / % of balance), executed from the agent's custodial wallet, and stamped with the real detected-to-submitted latency and actual fill. Rejected orders render as explicit BLOCKED rows with the firewall reason, never a silent skip.
-Source detection filters the PumpPortal SSE (/api/pump/trades-stream) to the target wallet; each hit re-quotes via /api/agents/:id/trade/quote and executes via POST /api/agents/:id/trade, both enforced by the server-side trade firewall (per-trade cap, daily budget, price-impact breaker, kill switch). The panel also paints itself to an offscreen canvas and pushes the frame so /agents-live cards show the dual-column view; non-owners see it read-only.
+Source detection filters the PumpPortal SSE (/api/pump/trades-stream) to the target wallet; the stream rejects a malformed mint with a 400 and emits a `notice` event when PumpPortal refuses the per-mint subscription (its API key must hold at least 0.02 SOL) instead of holding the socket open and never delivering a trade. Each hit re-quotes via /api/agents/:id/trade/quote and executes via POST /api/agents/:id/trade, both enforced by the server-side trade firewall (per-trade cap, daily budget, price-impact breaker, kill switch). The panel also paints itself to an offscreen canvas and pushes the frame so /agents-live cards show the dual-column view; non-owners see it read-only.
Copy trading you can actually audit: every replica shows its latency, fill, price impact and explorer link, and the spend caps are hard server-side limits the owner sets right in the panel — a watchable, bounded mirror instead of a black-box bot.
@@ -4148,7 +4302,7 @@ Holders watch an agent pay its own compute, buy back $THREE, and reward holders
An always-live host loop that turns the Avatar Cam into a stage: the agent opens the show, riffs, answers audience questions typed into the composer, runs rounds of its format's game, and shouts out $THREE tippers by name — looping forever, never silent, with a live tip leaderboard.
-The pure ShowDirector (shared with Living Stages rooms) picks the next beat; each beat becomes real words via the multi-LLM brain router (POST /api/brain/chat, SSE), spoken with real TTS plus RMS lip-sync and a per-beat retargeted body emote (wave, celebrate, taunt…). Settled on-chain $THREE tips polled from /api/stage/tip pre-empt the next beat as a shoutout within ~1s; if the brain or TTS drop, a rotating safe filler line keeps the show alive rather than fake content. Transcript lines are pushed to the live wall.
+The pure ShowDirector (shared with Living Stages rooms) picks the next beat; each beat becomes real words via the multi-LLM brain router (POST /api/brain/chat, SSE), spoken with real TTS plus RMS lip-sync and a per-beat retargeted body emote (wave, celebrate, taunt…). On-chain $THREE tips polled from /api/stage/tip pre-empt the next beat as a shoutout within ~1s; a tip counts only once the endpoint has proven on-chain that the transfer credited the host's wallet, and an unproven one is held pending and never reaches the leaderboard or a shoutout. The show calls the router on the anon-allowed free tier, so it runs whether or not the viewer is signed in; the router walks every free lane (Groq, OpenRouter, NVIDIA, SambaNova, Mistral, Z.AI, then the credits-funded Vertex Gemini anchor) before it reports an error, and that error says what happened in plain words rather than the last provider's raw status. If the brain or TTS still drop, a rotating safe filler line keeps the show alive rather than fake content. Transcript lines are pushed to the live wall.
A 24/7 interactive performer: ask it a question and it answers you on air; tip $THREE and it hypes your name seconds later — a direct, monetized feedback loop between audience and agent.
@@ -4562,7 +4716,7 @@ Owner-only, structurally: the tab is hidden from non-owners and every endpoint r
Intents turns an agent's wallet into a programmable teammate you talk to. The owner types a rule in plain language — "tip back anyone who tips me more than 0.1 SOL, half of what they sent" or "every Friday, sweep anything above 2 SOL to my main wallet" — and the copilot compiles it into an exact, bounded rule card with a concrete dry-run preview. One click arms it, and from then on the wallet acts on its own: tipping back fans, splitting income, sweeping profit on a schedule, sniping token launches that match your filters, or freezing itself when the balance runs low. Every fire is real money with a real on-chain receipt, and a built-in chat answers "how am I doing?" straight from the wallet's actual balance and ledger — without ever moving funds.
-The plain-language rule goes to a server-side compiler where a Claude model (with an OpenRouter fallback) is forced into a strict structured schema — one trigger, one action, owner caps — and is explicitly forbidden from inventing amounts, destinations, or tokens; if anything is missing it asks one clarifying question instead of guessing. The server independently re-validates every field, resolves .sol names to real addresses at compile time, and returns a readback plus a live dry-run before anything is stored. Armed rules live in the database: tip, income, and money-stream rules fire instantly from the real payment-settlement hooks, while scheduled, balance-floor, and launch-matching rules are swept by a scheduler every 10 minutes. Every execution flows through the same spend-policy-gated, audited signing path as every other outbound wallet action — SOL transfers sign directly, token buys and snipes route through Jupiter with slippage control and revert detection — and each fire writes an idempotent custody event stamped with the rule's ID and transaction signature, which powers the per-rule receipts, fire counts, and running dollar totals in the UI.
+The plain-language rule goes to a server-side compiler where a Claude model (with Grok and OpenRouter fallbacks, in that order) is forced into a strict structured schema (one trigger, one action, owner caps) and is explicitly forbidden from inventing amounts, destinations, or tokens; if anything is missing it asks one clarifying question instead of guessing. The server independently re-validates every field, resolves .sol names to real addresses at compile time, and returns a readback plus a live dry-run before anything is stored. Armed rules live in the database: tip, income, and money-stream rules fire instantly from the real payment-settlement hooks, while scheduled, balance-floor, and launch-matching rules are swept by a scheduler every 10 minutes. Every execution flows through the same spend-policy-gated, audited signing path as every other outbound wallet action (SOL transfers sign directly, token buys and snipes route through Jupiter with slippage control and revert detection), and each fire writes an idempotent custody event stamped with the rule's ID and transaction signature, which powers the per-rule receipts, fire counts, and running dollar totals in the UI.
Owner-only end to end: the server rejects any non-owner or logged-out caller on every read and write, so a visitor can never see, create, arm, or fire an intent. Every write is CSRF-protected and rate-limited. Nothing runs without an explicit Confirm & arm, and the server re-validates the full rule independently of the AI parse; the compiler itself is forbidden from inventing amounts, destinations, or tokens and must ask a clarifying question instead. Spending is triple-capped: the rule's own per-action / daily / lifetime USD caps are checked against the real custody ledger, then the agent-wide spend policy — the same hard ceiling every other outbound action obeys — is enforced at execution time, and a frozen wallet blocks all spends and even key recovery. Executions are idempotent (one fire per event, one snipe per launch, at most one low-balance freeze per day), keep a fee buffer so the wallet never empties itself, pause instead of guessing when the price feed is down, and detect reverted swaps so a failure is never reported as success. The signing key is decrypted only at the moment of signing with an audit-logged recovery; every execution writes an audited custody event with the transaction signature. Deletes require confirmation, the copilot chat is read-only by design, and the public-trait option exposes only a behavior label — never the rule, amounts, or caps.
@@ -4644,7 +4798,7 @@ Owner-only surface end to end: the tab is gated to the wallet owner and every AP
The data layer agents and their owners trade on: live markets, news, scoring oracles, liquidations, and sentiment.
-three.ws pairs a full general-crypto markets surface (CoinGecko-grade prices, a native 191-feed news aggregator with a 662k-article archive, real-time exchange liquidation streams) with pump.fun-native intelligence: the Oracle conviction engine that scores every launch 0-100 within seconds, a coin-intelligence radar, the platform's own /launches directory, and live PumpPortal feeds that even drive 3D avatar reactions. Everything runs on real, mostly keyless data sources (CoinGecko, alternative.me, public Ethereum RPCs, Binance/Bybit/OKX futures WebSockets, publisher RSS feeds, the pump.fun firehose) with a hard no-fabricated-data policy (surfaces degrade to designed offline states rather than fake numbers).
+three.ws pairs a full general-crypto markets surface (CoinGecko-grade prices, a native 197-feed news aggregator with a 662k-article archive, real-time exchange liquidation streams) with pump.fun-native intelligence: the Oracle conviction engine that scores every launch 0-100 within seconds, a coin-intelligence radar, the platform's own /launches directory, and live PumpPortal feeds that even drive 3D avatar reactions. Everything runs on real, mostly keyless data sources (CoinGecko, alternative.me, public Ethereum RPCs, Binance/Bybit/OKX futures WebSockets, publisher RSS feeds, the pump.fun firehose) with a hard no-fabricated-data policy (surfaces degrade to designed offline states rather than fake numbers). Any API response built from upstream data also carries an `x-brownout` header naming the freshness tier of what it served (live, cache, stale, or fallback, always the worst tier that contributed) and how many sources answered or failed, so a client can tell a degraded answer from a fresh one.
## /markets hub
@@ -4656,15 +4810,15 @@ One page that answers 'what is the market doing right now' and routes to deeper
## Crypto news wing (feed, reader, archive)
-Live news aggregated natively from 191 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 33 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.
+Live news aggregated natively from 197 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 34 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.
/markets/news, /markets/news/article, /markets/archive backed by api/news/{feed,article,archive,rss}.js over api/_lib/news.js + api/_lib/news-sources.js; the archive corpus lives on gs://three-ws-news-archive (recovered from the cryptocurrency.cv aggregator, which three.ws now runs natively).
-Real-time and nine-years-deep crypto news in one place, readable without visiting 191 different publisher sites, with machine-friendly JSON and RSS.
+Real-time and nine-years-deep crypto news in one place, readable without visiting 197 different publisher sites, with machine-friendly JSON and RSS.
## Global markets index + coin detail pages
-A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, and GeckoTerminal views where the coin qualifies), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).
+A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, and GeckoTerminal views where the coin qualifies; a third-party embed that is blocked or never renders is replaced within a deadline by a designed panel with a Try again button and a link to the provider, never a blank frame), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).
pages/coins.html + src/coins-index.js and pages/coin.html + src/coin-page.js over api/coin/* (detail, ohlc, markets, news, global, derivatives) proxying CoinGecko via api/_lib/coingecko.js. :id accepts a CoinGecko slug OR a Solana mint; mint-shaped ids cross-link into Alpha Copilot, the live trade feed, /launches, and Coin Intelligence.
@@ -4682,7 +4836,7 @@ See where leveraged traders are getting hurt in real time — a classic squeeze/
Four tools sharing one design system: /heatmap (squarified treemap, tiles sized by market cap and colored by 24h/7d move, top 50/100 toggle), /fear-greed (live 0-100 sentiment gauge with week-over-week delta and 30D/90D/1Y history chart), /gas (live Ethereum gas tracker), and /compare (up to 4 coins with normalized performance overlay and stat line-up, selection saved in the URL).
-Heatmap is computed client-side from the existing /api/coin/markets feed; Fear & Greed serves the alternative.me index through api/coin/fear-greed.js; gas reads eth_feeHistory over the last ~20 blocks from keyless public RPCs (publicnode, llamarpc, ankr, cloudflare-eth) via api/coin/gas.js; compare reuses the CoinGecko backend. All real, key-free data, cross-linked from the markets table.
+Heatmap is computed client-side from the existing /api/coin/markets feed; Fear & Greed serves the alternative.me index through api/coin/fear-greed.js (CoinMarketCap's index is the second rung when COINMARKETCAP_API_KEY is set, and the last good reading is served for up to a day if every source fails, since the index updates once a day); gas reads eth_feeHistory over the last ~20 blocks from keyless public RPCs (publicnode, llamarpc, ankr, cloudflare-eth) via api/coin/gas.js; compare reuses the CoinGecko backend. All real, key-free data, cross-linked from the markets table.
At-a-glance answers to 'where is money flowing', 'what is the market mood', 'what will this transaction cost', and 'which of these coins is actually winning' — each shareable as a URL.
@@ -4714,7 +4868,7 @@ Launch a real on-chain pump.fun coin from an agent's profile in one flow, and ev
Real-time pump.fun event streams: /pump-live presents new token launches the instant they are created (fronted by a 3D agent), agent screens and dashboards subscribe to live per-mint trade streams, and the reactive-avatar skill drives <agent-3d> gestures, emotes, and speech directly from live market events — no LLM in the loop.
-The server fans the PumpPortal WebSocket (wss://pumpportal.fun/api/data) out to browsers as SSE via api/pump/trades-stream.js (per-mint subscribeTokenTrade) with api/pump/dex-trades.js covering post-graduation DEX trades in the same wire format; pump-fun-skills/reactive subscribes to new-launch and migration events and emits avatar actions every 2s with auto-reconnect.
+The server fans the PumpPortal WebSocket (wss://pumpportal.fun/api/data) out to browsers as SSE via api/pump/trades-stream.js (per-mint subscribeTokenTrade; a malformed mint is refused with a 400, and when PumpPortal declines the subscription, which it does unless its API key holds at least 0.02 SOL, the refusal is forwarded as an SSE `notice` event so a tape can show an honest degraded state instead of a lit live lamp over an empty panel) with api/pump/dex-trades.js covering post-graduation DEX trades in the same wire format; pump-fun-skills/reactive subscribes to new-launch and migration events and emits avatar actions every 2s with auto-reconnect.
Watch the pump.fun firehose live inside three.ws — and give any embedded 3D agent a visible pulse that reacts to real market activity in real time.
@@ -4730,7 +4884,7 @@ Turn an agent into an on-chain business: its coin is its equity, its invoices ar
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.
+Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/top/:mint` feed the pump.fun coin page renders; the older comments route was retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage with no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.
Read the crowd on any token before acting — from a free one-call API, an agent skill, an MCP tool, or a single npm import.
@@ -4738,7 +4892,7 @@ Read the crowd on any token before acting — from a free one-call API, an agent
A free, no-key, no-account crypto data API built for AI agents: token snapshots, security/rug signals, holder concentration, live pump.fun launches, bonding-curve status, whale activity, trending tokens, wallet portfolios, and ticker-availability checks — with public docs, a live try-it console, and OpenAPI 3.1 discovery.
-pages/crypto.html documents /api/crypto/*; api/crypto/index.js and api/crypto/openapi.js assemble the catalog from self-describing descriptors in api/_lib/crypto-catalog/ (airdrops, bonding, holders, launches, portfolio, security, symbol, token, trending, wallet, whales), and the docs page probes production at runtime to mark each endpoint Live vs Coming soon.
+pages/crypto.html documents /api/crypto/*; api/crypto/index.js and api/crypto/openapi.js assemble the catalog from self-describing descriptors in api/_lib/crypto-catalog/ (airdrops, bonding, holders, launches, portfolio, security, symbol, token, trending, wallet, whales), and the docs page reads the discovery index (GET /api/crypto) at runtime, falling back to per-endpoint probes only if the index cannot be read, to mark each endpoint Live vs Coming soon.
Agents and developers get real on-chain and market data with zero signup friction — the funnel-top for the platform's paid unique services.
@@ -5068,7 +5222,7 @@ You walk up to an independent AI security auditor in a 3D world, pay it a nickel
An agent is not locked to three.ws: embed it on any site, ship it in a chat plugin, put it in Claude via MCP, carry it on Solana mobile.
-An agent you build on three.ws doesn't live in a tab on three.ws — it travels. One copy-paste snippet puts a living 3D agent on any website; official plugins put it inside ChatGPT, Claude, LobeChat, Blender, VS Code, and Chrome; a packaged Solana Mobile app puts it in your pocket; and 42 MCP servers put every three.ws capability one command away from any AI assistant. Create once, deploy everywhere is not a tagline here — it's the product architecture.
+An agent you build on three.ws doesn't live in a tab on three.ws; it travels. One copy-paste snippet puts a living 3D agent on any website; official plugins put it inside ChatGPT, Claude, LobeChat, Blender, VS Code, and Chrome; a packaged Solana Mobile app puts it in your pocket; and 48 MCP servers put every three.ws capability one command away from any AI assistant. Create once, deploy everywhere is not a tagline here; it's the product architecture.
## The <agent-3d> web component
@@ -5174,9 +5328,9 @@ A store-compliant Actions endpoint (/api/3d/studio) with an age-13+ content gate
Anyone in ChatGPT can make and inspect real 3D assets without ever leaving the conversation.
-## 42 MCP servers
+## 48 MCP servers: every capability one command from any AI assistant
-The entire platform is exposed through 42 Model Context Protocol servers, all listed in the official MCP registry: seven hosted servers you add by URL with nothing to install (including a completely free 3D Studio with no auth and no payment), and thirty-five npm packages that run locally with a single npx command. Claude, Cursor, and any MCP-compatible client can generate 3D models, drive avatars, pay for services, read market intel, and more through natural language.
+The entire platform is exposed through 48 Model Context Protocol servers, all listed in the official MCP registry: seven hosted servers you add by URL with nothing to install (including a completely free 3D Studio with no auth and no payment), and forty-one npm packages that run locally with a single npx command. Claude, Cursor, and any MCP-compatible client can generate 3D models, drive avatars, pay for services, read market intel, and more through natural language.
Streamable-HTTP remote servers (e.g. /api/mcp, /api/mcp-studio, /api/mcp-agent) plus 35 stdio servers published under the @three-ws npm scope, registered on registry.modelcontextprotocol.io; paid tools quote USDC prices and settle via x402 in-band.
@@ -5260,29 +5414,29 @@ Any website gets a living mascot that reacts to what visitors do — the kind of
Everything above is programmable: MCP tools, SDKs, and a paid x402 API catalog that other agents can discover and pay.
-three.ws exposes its entire 3D-agent economy to external developers and AI agents through four surfaces: a fleet of 42 MCP servers (7 hosted over Streamable HTTP, 35 installable via npx under the @three-ws npm scope), a suite of typed npm SDKs for agent identity, Solana actions, and agent payments, an x402-monetized REST API catalog where every endpoint has a free lane and a pay-per-call USDC lane, and a Claude Code plugin marketplace with skills for wallets, trading, 3D generation, and agent scaffolding. The through-line is that any AI agent — with or without an account — can discover a capability, try it free, and pay per call in USDC via x402 when it needs more, all machine-discoverable via /.well-known/x402.json, /openapi.json, and the official MCP registry.
+three.ws exposes its entire 3D-agent economy to external developers and AI agents through four surfaces: a fleet of 48 MCP servers (7 hosted over Streamable HTTP, 41 installable via npx under the @three-ws npm scope), a suite of typed npm SDKs for agent identity, Solana actions, and agent payments, an x402-monetized REST API catalog where every endpoint has a free lane and a pay-per-call USDC lane, and a Claude Code plugin marketplace with skills for wallets, trading, 3D generation, and agent scaffolding. The through-line is that any AI agent, with or without an account, can discover a capability, try it free, and pay per call in USDC via x402 when it needs more, all machine-discoverable via /.well-known/x402.json, /openapi.json, and the official MCP registry.
## Hosted MCP server (/api/mcp)
-Claude or any MCP client connects to https://three.ws/api/mcp (Streamable HTTP, JSON-RPC 2.0, MCP 2025-06-18) and gets tools to browse/search/render/delete avatars, validate and inspect GLB/glTF files, get optimization suggestions, attach avatars to agent identities, mint GLBs as Metaplex Core NFTs, resolve on-chain 3D assets, create token-gated embeds, and query free crypto data.
+Claude or any MCP client connects to https://three.ws/api/mcp (Streamable HTTP, JSON-RPC 2.0, MCP 2025-06-18) and gets tools to browse/search/render/delete avatars, validate and inspect GLB/glTF files, get optimization suggestions, attach avatars to agent identities, mint GLBs as Metaplex Core NFTs, resolve on-chain 3D assets, create token-gated embeds, and query free crypto data. Every tool call is a POST; there is no server-push stream, and a bare GET answers with the OAuth and x402 challenge so a client can discover how to sign in or pay before it calls anything.
-Auth is OAuth 2.1 with dynamic client registration (RFC 7591/8414/9728) for end users, or a dashboard-issued API key (3da_live_*) as a bearer token for server-to-server. Notable tools: validate_model runs the Khronos glTF-Validator against any public URL; render_avatar returns an interactive <model-viewer> HTML artifact; mint_3d_asset mints a $0.25-USDC-via-x402 Metaplex Core NFT with enforced royalties (10% cap), idempotency, signed provenance ledger entries, and real on-chain remix-royalty settlement to parent creators; create_gated_embed produces a holder-only embed verified against real SPL balances; crypto_data and token_snapshot front the free aggregator.
+Auth is OAuth 2.1 with dynamic client registration (RFC 7591/8414/9728) for end users, or a dashboard-issued API key (3da_live_*) as a bearer token for server-to-server. Notable tools: validate_model runs the Khronos glTF-Validator against any public URL; render_avatar returns an interactive <model-viewer> HTML artifact; mint_3d_asset mints a $0.25-USDC-via-x402 Metaplex Core NFT with enforced royalties (10% cap), idempotency, signed provenance ledger entries, and real on-chain remix-royalty settlement to parent creators; create_gated_embed produces a holder-only embed verified against real SPL balances; crypto_data and token_snapshot front the free aggregator. A payment proof is accepted in either the v1 X-PAYMENT header or the v2 payment-signature header, and every proof is reserved against replay before the tool runs.
An AI assistant can manage a user's entire 3D asset library conversationally — validate a model, see its stats, render it inline, tokenize it on Solana — without the user copy-pasting URLs or leaving the chat. Docs: /docs/mcp.
## Six more hosted remote MCP servers
-Beyond /api/mcp: 3D Studio (/api/mcp-3d, paid text/image→3D, rigging, retexture), 3D Studio free (/api/mcp-studio, free text→3D and rigged avatars with no auth or payment), Agent wallet (/api/mcp-agent, custodial wallet balance, find + pay services, monetize_endpoint), x402 Bazaar (/api/mcp-bazaar, discover and price paid agent services across the facilitator network), pump.fun (/api/pump-fun-mcp, free read-only pump.fun + Solana token tools), and IBM x402 (/api/ibm-mcp, pay-per-use IBM Granite AI).
+Beyond /api/mcp: 3D Studio (/api/mcp-3d, paid text/image→3D, rigging, retexture), 3D Studio free (/api/mcp-studio, free text→3D and rigged avatars with no auth or payment), Agent wallet (/api/mcp-agent, custodial wallet balance, find + pay services, monetize_endpoint), x402 Bazaar (/api/mcp-bazaar, discover and price paid agent services across the facilitator network), pump.fun (/api/pump-fun-mcp, free pump.fun + Solana token tools; only pumpfun_upload_metadata, which pins launch metadata to IPFS, needs a key), and IBM x402 (/api/ibm-mcp, pay-per-use IBM Granite AI).
-All are add-by-URL Streamable HTTP servers — nothing to install. Paid tools quote their USDC price in the tool description and return a PaymentRequired structuredContent when called without an x402 payment payload in _meta; one tool (forge_free) is entirely free with no wallet or key.
+All are add-by-URL Streamable HTTP servers, nothing to install. Paid tools quote their USDC price in the tool description; a call that carries no payment gets an HTTP 402 with the x402 envelope (scoped to the server that issued it), a paying agent retries with the proof in the X-PAYMENT or v2 payment-signature header, and the payment settles only after the tool succeeds, so a failed call costs nothing. On the paid 3D Studio server one tool (forge_free) is entirely free with no wallet or key, and the free 3D Studio and pump.fun servers charge nothing at all.
An external agent gets a complete economic loop from hosted endpoints alone: generate a 3D asset free, discover paid services in the Bazaar, and pay for them from its wallet — zero local installation.
-## 35 install-and-run MCP servers on npm (@three-ws scope)
+## 41 install-and-run MCP servers on npm (@three-ws scope)
-One-line npx installs (e.g. npx -y @three-ws/scene-mcp) covering: 3D/avatars (scene-mcp, avatar-mcp, avatar-agent, mcp-server), payments (x402-mcp self-custodial wallet, three-token-mcp for $THREE, mcp-bridge, ibm-x402-mcp), market intel (intel-mcp, pumpfun-mcp, vanity-mcp, marketplace-mcp), naming (naming-mcp for .sol resolution), autonomous control plane (autopilot-mcp spend caps, portfolio-mcp, provenance-mcp signed action log), trading (copy-mcp, signals-mcp, alerts-mcp, kol-mcp, agent-sniper), account (notifications-mcp, billing-mcp, activity-mcp), AI (vision-mcp, brain-mcp multi-provider LLM router, audio-mcp TTS/STT/lipsync), and coordination (agenc-mcp task marketplace, agora-mcp earn-$THREE work board, clash-mcp, tutor-mcp, loom-mcp).
+One-line npx installs (e.g. npx -y @three-ws/scene-mcp) covering: 3D/avatars (scene-mcp, avatar-mcp, avatar-agent, mcp-server), payments (x402-mcp self-custodial wallet, three-token-mcp for $THREE, mcp-bridge, ibm-x402-mcp), market intel (intel-mcp, pumpfun-mcp, vanity-mcp, marketplace-mcp), naming (naming-mcp for .sol resolution), on-chain identity (metaplex-agent-mcp), autonomous control plane (autopilot-mcp spend caps, portfolio-mcp, provenance-mcp signed action log), trading (copy-mcp, signals-mcp, alerts-mcp, kol-mcp, agent-sniper), account (notifications-mcp, billing-mcp, activity-mcp), AI (vision-mcp, brain-mcp multi-provider LLM router, audio-mcp TTS/STT/lipsync, ibm-watsonx-mcp and alibaba-cloud-mcp on your own keys), and coordination (agenc-mcp task marketplace, agora-mcp earn-$THREE work board, clash-mcp, tutor-mcp, loom-mcp).
-Each runs locally over stdio; all 42 servers are registered in the official MCP registry under io.github.nirholas/* and surfaced on Smithery, Glama, PulseMCP, and mcp.so, so any MCP client can discover them by name. Package sources live in packages/*-mcp.
+Each runs locally over stdio; all 48 servers are registered in the official MCP registry under io.github.nirholas/* and surfaced on Smithery, Glama, PulseMCP, and mcp.so, so any MCP client can discover them by name. Package sources live in packages/*-mcp, plus mcp-server/ and mcp-bridge/ at the repo root.
A developer composes exactly the capability set their agent needs — a trading agent adds intel + copy + portfolio; a creative agent adds scene + avatar + audio — each a single npx line in their MCP client config.
@@ -5322,13 +5476,13 @@ Both sides of the paid-agent-API economy in a few lines: an agent developer's HT
One base URL fronting a growing bundle of third-party crypto/DeFi/on-chain APIs — CoinGecko, DefiLlama, Jupiter, DexScreener, direct Solana RPC, OpenAI chat and more — re-offered as GET /api/v1/x/<provider>/<endpoint> with normalized, agent-sized JSON responses instead of each upstream's raw payload.
-Every request resolves through four billing lanes in order: free (real per-IP quotas, zero setup — a bare curl gets data), BYOK (caller passes the upstream's own key, pure pass-through, no markup), plan (three.ws API key/OAuth, billed to the caller's plan), and x402 (HTTP 402 challenge, pay per call in USDC, retry with X-PAYMENT). The registry at api/v1/_providers.js is the single source of truth feeding discovery (GET /api/v1/x), /openapi.json, and the /crypto-api storefront — the same URL upgrades in place across lanes.
+Every request resolves through four billing lanes in order: free (real per-IP quotas, zero setup: a bare curl gets data), BYOK (caller passes the upstream's own key, pure pass-through, no markup), plan (three.ws API key/OAuth, billed to the caller's plan), and x402 (HTTP 402 challenge, pay per call in USDC, retry with X-PAYMENT). The registry at api/v1/_providers.js is the single source of truth feeding discovery (GET /api/v1/x), /openapi.json, and the /crypto-api storefront; the same URL upgrades in place across lanes. The Solana RPC provider fronts a keyed endpoint (an operator URL, then QuickNode, Helius, or Alchemy) and fails over across the platform's full RPC pool when the primary answers 429 or 5xx.
An agent that needs a token price, a swap quote, a chain's TVL, and an ENS lookup uses one base URL, one discovery call, and one bill instead of juggling four API keys and four rate limits — and can start with literally zero setup.
## First-party paid AI + platform endpoints under /api/v1
-Versioned first-party endpoints: text→3D forge (the only text→mesh lane in the x402 ecosystem), text→image (/api/v1/ai/image, first 5/day free then $0.02 via x402), TTS and ASR (/api/v1/ai/tts, /api/v1/ai/asr), sentiment, agents, market, pump, and token data, plus free public directories like /api/v1/tokenized/launches (every 3D NFT minted through the platform) and /api/v1/pump/launches.
+Versioned first-party endpoints: text→3D forge (the only text→mesh lane in the x402 ecosystem), text→image (/api/v1/ai/image, first 5/day free then $0.02 via x402), TTS and ASR (/api/v1/ai/tts, first 10/day free then $0.005, served by NVIDIA Magpie and falling through to a Gemini lane when Magpie cannot serve, and /api/v1/ai/asr), sentiment, agents, market, pump, and token data, plus free public directories like /api/v1/tokenized/launches (every 3D NFT minted through the platform) and /api/v1/pump/launches.
Same free-quota-then-x402 pattern throughout, settled on Solana or Base; payable with any x402 client (e.g. npx x402 curl). Full reference: /docs/api-reference; machine-readable listing at /.well-known/x402.json and /.well-known/openapi.yaml.
@@ -5416,11 +5570,11 @@ Your coding agent gains IBM Granite and Alibaba Qwen as first-class tools in one
## The public changelog
-Every user-visible change to the platform lands in a public changelog that holders can actually follow: a browsable web page with per-entry permalinks, plus machine-readable JSON and RSS feeds for bots, dashboards, and readers. Entries are written in plain holder-readable language — no commit jargon — tagged by type (feature, improvement, fix, SDK, infra, docs, security), and new page launches flow in automatically. New entries are also pushed automatically to the holders' Telegram channel, with no manual announcement step.
+Every user-visible change to the platform lands in a public changelog the community can actually follow: a browsable web page with per-entry permalinks, plus machine-readable JSON and RSS feeds for bots, dashboards, and readers. Entries are written in plain community-readable language (no commit jargon), tagged by type (feature, improvement, fix, SDK, infra, docs, security), and new page launches flow in automatically. New entries are also pushed automatically to the community Telegram channel (@three_ws), with no manual announcement step.
-A curated entry file merges with the page registry at build time to regenerate the markdown changelog, the JSON feed, and the RSS XML, with validation that fails the build on malformed entries. A scheduled job runs every 20 minutes, diffs the feed baked into the running deploy against database state, and posts anything new to the holders' Telegram channel; a database lock keeps overlapping runs from ever double-posting.
+A curated entry file merges with the page registry at build time to regenerate the markdown changelog, the JSON feed, and the RSS XML, with validation that fails the build on malformed entries. A scheduled job runs every 20 minutes, diffs the feed baked into the running deploy against database state, and posts anything new to the community Telegram channel; a database lock keeps overlapping runs from ever double-posting.
-Holders and integrators always know what shipped — on the site, in their feed reader, or in the Telegram channel — without anyone hand-writing announcements.
+The community and integrators always know what shipped, on the site, in their feed reader, or in the Telegram channel, without anyone hand-writing announcements.
---
@@ -5428,7 +5582,7 @@ Holders and integrators always know what shipped — on the site, in their feed
Every page and surface on three.ws, grouped by area.
-three.ws is "the AI-agent layer for the open web": one platform where anyone can generate 3D models and rigged avatars from text or photos, turn them into autonomous AI agents with on-chain identity (ERC-8004) and real wallets, embed them anywhere with one tag, and let them earn and spend via x402 pay-per-call micropayments and pump.fun token launches. The public surface spans roughly 300 pages plus published SDKs and 42 MCP servers, organized here into 14 categories: 3D creation, avatars/animation/voice, agent creation & management, embedding & distribution, worlds & social play, AR & real-world presence, trading intelligence, market data & news, token launching & $THREE, the x402 agent economy, wallets & custody, marketplaces & creator economy, the developer platform, and company/content surfaces. Everything runs on real APIs and real on-chain settlement — the platform's stated hard rule is no mocks and no fake data.
+three.ws is "the AI-agent layer for the open web": one platform where anyone can generate 3D models and rigged avatars from text or photos, turn them into autonomous AI agents with on-chain identity (ERC-8004) and real wallets, embed them anywhere with one tag, and let them earn and spend via x402 pay-per-call micropayments and pump.fun token launches. The public surface spans roughly 300 pages plus published SDKs and 48 MCP servers, organized here into 14 categories: 3D creation, avatars/animation/voice, agent creation & management, embedding & distribution, worlds & social play, AR & real-world presence, trading intelligence, market data & news, token launching & $THREE, the x402 agent economy, wallets & custody, marketplaces & creator economy, the developer platform, and company/content surfaces. Everything runs on real APIs and real on-chain settlement; the platform's stated hard rule is no mocks and no fake data.
## 3D Creation Suite (text, photos & sketches → 3D)
@@ -5528,7 +5682,7 @@ Creators earn from every downstream use of their work — remixes, forks, and li
## Developer Platform (APIs, MCP, SDKs, Docs)
-Everything a developer or an AI agent needs to build on three.ws. Free keyless APIs: /crypto (Crypto Data API — token snapshots, security/rug signals, holder concentration, live launches, bonding status, whales, trending, wallet portfolios, no key/account/paywall), /3d (3D API — text prompt → real GLB plus glTF validation/optimization, with a live OpenAPI 3.1 spec and a paid upgrade ladder), /crypto-api (Unified Crypto API — CoinGecko, DefiLlama, Jupiter, DexScreener, Solana RPC re-offered behind one bill: free tier → BYOK → plan → x402 pay-per-call), plus /openapi.json and x402 discovery at /.well-known/x402. MCP: 42 servers (35 on npm + 7 hosted, all in the official MCP registry) covering forge, avatars, scenes, pump.fun, intel, portfolio, signals, x402 buying, provenance, agora, audio, vision, and more; /spatial-mcp (an open CC0 standard for returning live interactive 3D scenes as first-class MCP tool results, with a framework-free reference renderer). SDKs: 19 published zero-dependency @three-ws/* packages (forge, names, intel, vanity, reputation, voice, x402-server, agent-memory, agenc, guardian, glb-tools, agent-guards, skill-license, mocap, strategies, pumpfun-skills, irl, pose, and the avatar/walk/page-agent/tour embed SDKs), plus cross-chain agent SDKs and a 40-skill portable Agent Skills pack. Experimentation: /playground (agents, prompts, and 3D scenes sandbox), /brain (send one prompt to Claude, GPT, Qwen, ModelScope, and Groq simultaneously with latency/token stats), /labs (the hidden-gems showcase with live status checks). Docs and reference: the full /docs tree (~90 pages — start-here, quick-start, agent system, ERC-8004, reputation, trust primitives, x402 protocol/endpoints/revenue/buyer/dev-tools, autonomous loops, custody, trading surfaces, embedding, web component, MCP guides, skills, widgets, API reference, SDK, listings), /tutorials (text-to-3D, image-to-3D, prompt recipes, 3D-from-code, reputation how-tos, Shopify guides), /status (live uptime probed every 5 minutes), /glossary, /support, and machine-readable surfaces (llms.txt, llms-full.txt, sitemap.xml, robots.txt, attestation schemas, OAuth metadata, chat-plugin manifest).
+Everything a developer or an AI agent needs to build on three.ws. Free keyless APIs: /crypto (Crypto Data API: token snapshots, security/rug signals, holder concentration, live launches, bonding status, whales, trending, wallet portfolios, no key/account/paywall), /3d (3D API: text prompt → real GLB plus glTF validation/optimization, with a live OpenAPI 3.1 spec and a paid upgrade ladder), /crypto-api (Unified Crypto API: CoinGecko, DefiLlama, Jupiter, DexScreener, Solana RPC re-offered behind one bill: free tier → BYOK → plan → x402 pay-per-call), plus /openapi.json and x402 discovery at /.well-known/x402. MCP: 48 servers (35 on npm + 7 hosted, all in the official MCP registry) covering forge, avatars, scenes, pump.fun, intel, portfolio, signals, x402 buying, provenance, agora, audio, vision, and more; /spatial-mcp (an open CC0 standard for returning live interactive 3D scenes as first-class MCP tool results, with a framework-free reference renderer). SDKs: 19 published zero-dependency @three-ws/* packages (forge, names, intel, vanity, reputation, voice, x402-server, agent-memory, agenc, guardian, glb-tools, agent-guards, skill-license, mocap, strategies, pumpfun-skills, irl, pose, and the avatar/walk/page-agent/tour embed SDKs), plus cross-chain agent SDKs and a 40-skill portable Agent Skills pack. Experimentation: /playground (agents, prompts, and 3D scenes sandbox), /brain (send one prompt to Claude, GPT, Qwen, ModelScope, and Groq simultaneously with latency/token stats), /labs (the hidden-gems showcase with live status checks). Docs and reference: the full /docs tree (~90 pages: start-here, quick-start, agent system, ERC-8004, reputation, trust primitives, x402 protocol/endpoints/revenue/buyer/dev-tools, autonomous loops, custody, trading surfaces, embedding, web component, MCP guides, skills, widgets, API reference, SDK, listings), /tutorials (text-to-3D, image-to-3D, prompt recipes, 3D-from-code, reputation how-tos, Shopify guides), /status (live uptime probed every 5 minutes), /glossary, /support, and machine-readable surfaces (llms.txt, llms-full.txt, sitemap.xml, robots.txt, attestation schemas, OAuth metadata, chat-plugin manifest).
Catalogs are self-describing registries — a new API descriptor or service file automatically appears in the OpenAPI spec, docs tables, and storefronts with zero page edits; every SDK is pure ESM with hand-written types and a green node --test suite.
@@ -5544,7 +5698,7 @@ A newcomer can understand, trust, and start using the platform in minutes — an
---
-<a id="sec-011"></a>
+<a id="sec-012"></a>
> **Source:** `docs/agent-abilities/FULL-ARTICLE.md` · [↑ table of contents](#table-of-contents)
@@ -5894,7 +6048,7 @@ The agent's owner console: a persistent live 3D stage showing your agent standin
You don't write a system prompt — you direct a character. Compose the agent's reasoning as a visual card-stack graph, fork ready-made brains (Sniper, Scalper, Researcher, Companion), tune trait sliders and tone chips, and test it in a streaming chat against the real model. A/B compare runs genuine dual inference side by side; promoting the winner writes a real versioned update and the agent re-greets everywhere on the platform.
-**How it works:** A deterministic persona compiler turns the graph/trait state into a real persona prompt persisted to the agent's identity record; test chats hit the live /api/chat LLM proxy with an owner-only persona override, and promotes append to a version history.
+**How it works:** A deterministic persona compiler turns the graph/trait state into a real persona prompt persisted to the agent's identity record; test chats hit the live /api/chat LLM proxy with an owner-only persona override, and promotes append to a version history. Every persona save also signs the agent's full manifest, system prompt included, and pins it to IPFS, so anyone can fetch the CID and verify what the agent is running without an account ([Agent manifest](/docs/agent-manifest)).
**Why it matters:** Personality engineering becomes tactile and testable — you feel the change in the agent's voice within a second instead of guessing at prompt wording.
@@ -5934,7 +6088,7 @@ Flip your agent's abilities on and off live: a locked-on core (greet, think, rem
The power-user editing surface for any agent you own, with fifteen-plus tabs covering everything: outfit, voice, knowledge, brain, mind, ownership, dreams, skills, autopilot, embeds, widgets, social, analytics, and wallet. It also builds subscription plans that bundle an agent's skills into recurring offers.
-**How it works:** A tabbed single-page console over the agent APIs at /agent/:id/edit; heavy tabs (3D outfit preview, brain studio) mount lazily so you never pay for a WebGL context you didn't open.
+**How it works:** A tabbed single-page console over the agent APIs at /agents/:id/edit; heavy tabs (3D outfit preview, brain studio) mount lazily so you never pay for a WebGL context you didn't open.
**Why it matters:** Every dial an agent has is reachable from one page — nothing about your agent is hidden from you.
@@ -5956,11 +6110,11 @@ Agents keep a dream journal. Between your visits, the agent reflects on its rece
## Live name check and naming rules
-As you name or rename an agent, availability is checked live against the whole platform — taken, invalid, and reserved names are flagged before you ever submit, with clear rules (3–32 characters, letters/numbers/dash/underscore) and a denylist protecting system and brand names.
+As you name or rename an agent, availability is checked live against the other agents you own: taken, invalid, and reserved names are flagged before you ever submit, with clear rules (3-32 characters, letters/numbers/dash/underscore) and a denylist protecting system and brand names.
-**How it works:** A dedicated GET /api/agents/check-name endpoint validates format, denylist, and database uniqueness (with self-exclusion when renaming), consumed by the creation and editing flows.
+**How it works:** A dedicated GET /api/agents/check-name endpoint validates format, denylist, and database uniqueness within your account (with self-exclusion when renaming, and a 400 instead of a server error when the agent_id is not a uuid), consumed by the creation and editing flows.
-**Why it matters:** You never lose work to a name collision at the last step, and every agent name on the platform is unique and legible.
+**Why it matters:** You never lose work to a name collision at the last step, and every agent name you own is unique and legible.
## Selfie → 3D avatar
@@ -6014,7 +6168,7 @@ Snap one photo and transfer your facial identity — face width, jaw, lip thickn
Any un-rigged 3D mesh — something you generated, bought, or modeled — can be turned into an animation-ready avatar in one click. The platform builds a skeleton into it so it can walk, dance, and emote with the full animation library. The original is never touched: rigging produces a new sibling avatar.
-**How it works:** Routes the mesh through the auto-rig backend (the self-hosted Make-It-Animatable rig worker on GPU infrastructure with a Replicate fallback), polls the job, canonicalizes the resulting bone names to the universal skeleton, and registers the rigged result as a new owned avatar.
+**How it works:** Routes the mesh through the auto-rig backend (the self-hosted Make-It-Animatable rig worker on GPU infrastructure, with a Replicate fallback when a rerig model is configured), polls the job, canonicalizes the resulting Mixamo-named bones to the universal skeleton, and registers the rigged result as a new owned avatar.
**Why it matters:** No model is a dead end — every statue you own can become a living character.
@@ -6142,7 +6296,7 @@ Change what any model is made of without touching its shape: live material editi
One click turns any studio output — a forged avatar, a Lab model — into a live conversational agent: it listens, thinks, answers out loud in a real voice, and lip-syncs while it speaks, with per-agent memory carrying across the conversation.
-**How it works:** Hands the model to the platform's production conversational stack — streaming LLM chat, TTS with provider failover (NVIDIA Magpie → OpenAI), and a lip-sync driver on the avatar's mouth morphs — the same runtime the rest of the site uses.
+**How it works:** Hands the model to the platform's production conversational stack, the same runtime the rest of the site uses: streaming LLM chat over a failover chain of six free provider lanes (Groq, OpenRouter, NVIDIA NIM, SambaNova, Mistral, Z.AI) ahead of any paid backstop, which answers a fully throttled free lane with a 503 and a Retry-After rather than a sign-in wall; TTS with provider failover (NVIDIA Magpie → OpenAI); and a lip-sync driver on the avatar's mouth morphs.
**Why it matters:** The moment of magic: the thing you just created looks at you and talks back.
@@ -6172,9 +6326,9 @@ Any avatar in your library can become any agent's body, and creating an avatar c
## Agent Genome — the breeding studio
-Breed any two agents into a genuinely new child agent. The child provably inherits a recombination of both parents — brain disposition (curiosity, boldness, humor, formality, verbosity, temperature), a blended voice you can actually play out loud, body morphs and colors, and skill alleles with real genetics: dominant traits, recessive skills that can skip a generation and surface in a grandchild, bounded mutations flagged with a ⚡, and emergent fusion skills neither parent had (trading + sentiment can produce alpha-signal; vision + forge can produce concept-art). Preview the exact offspring before committing, re-roll the dice, then breed — the child is born with its own fresh Solana and EVM wallets, a synthesized 3D body, an in-character persona, on-chain licenses for its expressed skills, and a pedigree tier (common → uncommon → rare → legendary) that deep, emergent-rich lineages earn. Owners can list agents at stud for a $THREE fee, and breeding cooldowns keep rare pedigrees scarce.
+Breed any two agents into a genuinely new child agent. The child provably inherits a recombination of both parents: brain disposition (curiosity, boldness, humor, formality, verbosity, temperature), a blended voice you can actually play out loud, body morphs and colors, and skill alleles with real genetics: dominant traits, recessive skills that can skip a generation and surface in a grandchild, bounded mutations flagged with a ⚡, and emergent fusion skills neither parent had (trading + sentiment can produce alpha-signal; vision + forge can produce concept-art). Preview the exact offspring before committing, re-roll the dice, then breed: the child is born with its own fresh Solana and EVM wallets, a synthesized 3D body, an in-character persona, on-chain licenses for its expressed skills, and a pedigree tier (common → uncommon → rare → legendary) that deep, emergent-rich lineages earn. Owners list their own public agents at stud for a $THREE fee from the studio's "Your stud listings" section (unlist any time), and breeding cooldowns keep rare pedigrees scarce.
-**How it works:** The studio (pages/genome.html + src/genome.js) drives api/genome/preview.js and api/genome/breed.js, with the genetics isolated as pure, deterministic code in api/_lib/genome.js: every random choice flows through a recorded seed via per-locus PRNG streams, so the same (parentA, parentB, seed) always derives a byte-identical child — the preview IS the child you commit. Constants are pinned by tests (mutation drift capped at 0.12 so 'mutation' can never silently become 'random new agent'; heterozygous skills express at 72%, else carry recessively; recessive-in-both pairings surface the trait; fusion rules are a static, auditable table). Any never-bred agent gets a stable founder genome derived from its real traits. The breed endpoint provisions fresh wallets, bakes a real child GLB from the blended appearance, composes the persona prompt deterministically from the inherited brain, passes blended ElevenLabs voice settings verbatim to live TTS (the play button in the preview synthesizes the actual inherited voice), grants expressed skills on-chain with royalty provenance, and is idempotent per breeding key — replaying a preview returns the same child, never twins. verifyGenome / api/genome/lineage.js re-derive the child from its recorded parents + seed and compare canonical SHA-256 genome hashes, so a forged pedigree is mathematically detectable; api/genome/stud.js powers the public stud market.
+**How it works:** The studio (pages/genome.html + src/genome.js) drives api/genome/preview.js and api/genome/breed.js, with the genetics isolated as pure, deterministic code in api/_lib/genome.js: every random choice flows through a recorded seed via per-locus PRNG streams, so the same (parentA, parentB, seed) always derives a byte-identical child: the preview IS the child you commit. Constants are pinned by tests (mutation drift capped at 0.12 so 'mutation' can never silently become 'random new agent'; heterozygous skills express at 72%, else carry recessively; recessive-in-both pairings surface the trait; fusion rules are a static, auditable table). Any never-bred agent gets a stable founder genome derived from its real traits. The breed endpoint provisions fresh wallets, bakes a real child GLB from the blended appearance, composes the persona prompt deterministically from the inherited brain, passes blended ElevenLabs voice settings verbatim to live TTS (the play button in the preview synthesizes the actual inherited voice), grants expressed skills on-chain with royalty provenance, and is idempotent per breeding key: replaying a preview returns the same child, never twins, a race on the same key or the same $THREE settlement signature is decided by the database's unique indexes with the losing child retired (so one stud payment can never buy two children), and cooldown is checked before the fee gate so a refused breeding never takes a payment. verifyGenome / api/genome/lineage.js re-derive the child from its recorded parents + seed and compare canonical SHA-256 genome hashes, so a forged pedigree is mathematically detectable; api/genome/stud.js powers the public stud market and the owner's listing writes, with PATCH semantics so sending only a fee never unlists the agent.
**Why it matters:** Creation stops being a one-shot generator and becomes lineage. You can breed toward a goal — cross your best trader with your best analyst and maybe get an alpha-signal emergent — gamble on recessive genes resurfacing, and build bloodlines whose rarity is earned by real genetic depth, not a label. Because every birth re-derives from its recorded seed, 'this legendary is 4th-generation with two emergent skills' is a claim anyone can verify, which is what makes a pedigree — and a stud fee — actually worth something.
@@ -6182,7 +6336,7 @@ Breed any two agents into a genuinely new child agent. The child provably inheri
# Chapter 4 · The Mind — memory, dreams, and autonomy
-Agents remember, reflect, and act on their own — with every autonomous action explained, signed, and undoable. Owners drive it from the Autopilot tab of the agent editor (/agent/:id/edit) and audit it at three.ws/autopilot-activity.
+Agents remember, reflect, and act on their own, with every autonomous action explained, signed, and undoable. Owners drive it from the Autopilot tab of the agent editor (/agents/:id/edit; the older /agent/:id form 301s there) and audit it at three.ws/autopilot-activity.
three.ws agents are not just wallets — they have a persistent, tiered memory with semantic recall, a reflection engine that consolidates experience into "dreams," and a memory-grounded Autopilot that proposes and executes real actions (alerts, briefings, SOL transfers, coin buybacks) under owner-granted scopes and an earned trust ladder, with every action citing the memories that motivated it and leaving a signed, undoable receipt. Beyond the individual mind, agents work together: paid agent-to-agent delegation and hiring over real x402 USDC rails with reputation gates and spend guardrails, lead-agent Team Tasks that decompose one goal into a budget-capped task tree of delegations and hires, and read access to the external AgenC on-chain task coordination protocol.
@@ -6190,7 +6344,7 @@ three.ws agents are not just wallets — they have a persistent, tiered memory w
The agent reads its own high-salience memories and recent reflections and turns them into concrete, real action proposals — create a price/graduation/whale alert, author a briefing to the owner's inbox, or transfer SOL from its custodial wallet. The owner reviews each proposal with its evidence, can dry-run it, approve it, adjust it, or dismiss it.
-**How it works:** src/autopilot-mind.js mounts the control surface (Autopilot tab of /agent/:id/edit); api/_lib/autopilot.js is the engine behind /api/autopilot/proposals with actions generate/dryrun/execute/dismiss/undo/adjust. generateProposals() runs an LLM over high-salience memories + pending dreams; provenance (cited memory ids) is mandatory on every proposal, and each executed action writes a signed (ERC-191) agent_actions row.
+**How it works:** src/autopilot-mind.js mounts the control surface (Autopilot tab of /agents/:id/edit); api/_lib/autopilot.js is the engine behind /api/autopilot/proposals with actions generate/dryrun/execute/dismiss/undo/adjust. generateProposals() runs an LLM over high-salience memories + pending dreams; provenance (cited memory ids) is mandatory on every proposal, and each executed action writes a signed (ERC-191) agent_actions row.
**Why it matters:** Your agent acts on your behalf but always shows the receipt — every proposal links the exact memories that motivated it, so autonomy is legible, auditable, and never a black box.
@@ -6198,7 +6352,7 @@ The agent reads its own high-salience memories and recent reflections and turns
Nothing is granted by default: the agent can propose but not act until the owner opts in per capability (create_alert, briefing, wallet_transfer). Reversible actions can be flipped to auto-run without asking; SOL transfers are irreversible, always confirmation-gated, and bounded by a daily SOL spend cap. The agent never sells or sends $THREE — it only accumulates and burns it.
-**How it works:** Scopes live on agent_identities.meta.autopilot (AUTOPILOT_DEFAULTS in api/_lib/autopilot.js: all scopes false, daily_spend_sol 0, require_confirm true) and are enforced server-side on every execute. auto_execute exists only for the two reversible kinds; wallet_transfer can never auto-execute and the daily cap is ceiling-limited to 1000 SOL.
+**How it works:** Scopes live on agent_identities.meta.autopilot (AUTOPILOT_DEFAULTS in api/_lib/autopilot.js: all scopes false, daily_spend_sol 0, require_confirm true) and are enforced server-side on every execute, including a live SOL balance read before any transfer (through the shared RPC failover lanes behind SOLANA_RPC_URL, so one provider's outage never blanks the check) that refuses with insufficient_funds when the wallet cannot cover the amount. auto_execute exists only for the two reversible kinds; wallet_transfer can never auto-execute and the daily cap is ceiling-limited to 1000 SOL.
**Why it matters:** You decide exactly how much rope the agent gets, capability by capability — and a misconfigured or compromised client can't widen it because enforcement is server-side.
@@ -6214,7 +6368,7 @@ Each agent carries a trust level — Sandbox (proposes, you approve everything),
Every autonomous action lands in an append-only ledger (/autopilot-activity and the Autopilot tab) with its full explanation, the source memories that motivated it (linking into the Knowledge tab), an ERC-191 signed-receipt badge, a Solscan tx link for on-chain moves, and one-tap Undo for reversible actions. A receipt chip also pops on any surface the moment an action fires.
-**How it works:** src/autopilot-activity.js reads the agent_actions log via /api/autopilot/activity (cursor-paginated, filterable per agent); src/autopilot-mind.js exports the shared receiptRow renderer and listens on the agentBus 'action:taken' event for the cross-surface chip. Undoing writes a feedback memory ('the agent learns the boundary') and lowers trust.
+**How it works:** src/autopilot-activity.js reads the agent_actions log via /api/autopilot/activity (cursor-paginated, filterable per agent; the response's `agents` list is always the caller's full roster, so a deep link like /autopilot-activity?agent=<id> keeps the whole picker, and an agent with no actions yet gets an empty state that links into its own Autopilot tab); src/autopilot-mind.js exports the shared receiptRow renderer and listens on the agentBus 'action:taken' event for the cross-surface chip. Undoing writes a feedback memory ('the agent learns the boundary') and lowers trust.
**Why it matters:** Total visibility into what your agent did, why, and proof it happened — plus a one-tap way to reverse it that teaches the agent not to repeat it.
@@ -6222,7 +6376,7 @@ Every autonomous action lands in an append-only ledger (/autopilot-activity and
For coins an agent launched on pump.fun through three.ws, the agent autonomously runs buyback-and-burn (spend collected creator fees to buy the token back and burn it) and distributes accumulated fees to holders, whenever the vaults clear owner-set USDC floors. A live narrator speaks each on-chain move through the agent's avatar.
-**How it works:** src/autopilot.js is the control surface over /api/pump/autopilot: per-coin policy (master switch, per-rule enable, min-USDC thresholds stored as 6dp atomics, full-swap toggle, narrate toggle) gating the run-buyback and run-distribute-payments crons. Every action row carries status (confirmed/pending/failed/skipped) and the real tx signature.
+**How it works:** src/autopilot.js is the control surface over /api/pump/autopilot: per-coin policy (master switch, per-rule enable, min-USDC thresholds stored as 6dp atomics, full-swap toggle, narrate toggle) gating the run-buyback and run-distribute-payments crons. A coin with no saved policy row answers `configured: false` and its card wears a Defaults pill until the owner changes something, and a cookie-session POST must be same-site (bearer callers are exempt) so a cross-site form cannot rewrite a policy. Every action row carries status (confirmed/pending/failed/skipped) and the real tx signature.
**Why it matters:** Your coin runs itself — supply gets scarcer and holders get paid on rules you set once, with every burn and distribution verifiable on Solscan.
@@ -6230,13 +6384,13 @@ For coins an agent launched on pump.fun through three.ws, the agent autonomously
Agents remember across sessions in four types — user (who you are, preferences), feedback (corrections that shape behavior), project (ongoing goals), reference (external pointers) — with salience scoring and recency decay. Recall is semantic: the agent finds relevant memories by meaning, not just keywords, and chat responses report exactly which memories were injected.
-**How it works:** src/agent-memory.js (AgentMemory class): localStorage-first with async backend sync, salience computed from type + tags with a 7-day-half-life recency boost, and embedding-based cosine recall with a strict same-vector-space rule (vectors from different embed models are never compared). Backend-confirmed agents recall through the server's mem0-style tiered store (/api/memory/search, working/recall tiers) covering every persisted memory, degrading gracefully to the local engine offline. src/agents/memory-client.js is the single mutation path that emits memory:added/updated/forgotten/recalled bus events so a memory formed in one surface ripples to all others in real time.
+**How it works:** src/agent-memory.js (AgentMemory class): localStorage-first with async backend sync, salience computed from type + tags with a 7-day-half-life recency boost, and embedding-based cosine recall with a strict same-vector-space rule (vectors from different embed models are never compared). Backend-confirmed agents recall through the server's mem0-style tiered store (/api/memory/search, working/recall tiers; an unknown tier or type, or a non-uuid agentId, answers 400 rather than an empty result) covering every persisted memory, degrading gracefully to the local engine offline. src/agents/memory-client.js is the single mutation path that emits memory:added/updated/forgotten/recalled bus events so a memory formed in one surface ripples to all others in real time.
**Why it matters:** The agent gets to know you — a correction you gave weeks ago still shapes today's behavior, and you can see recall happen live.
## Mind Palace and the living memory graph
-The agent's memory rendered as a 3D place you can walk through (/agent/:id/mind): every memory is a tangible object orbiting the live avatar — salience sets size, glow, and proximity; type sets shape and color; shared tags form navigable association edges. Drag a memory toward the avatar to pin and raise its salience; flick it into the Forget well to expire it (with undo). A companion 2D canvas graph in the Diary shows the mined entity knowledge graph — coins, tickers, wallets, people, strategies, topics — ranked by mentions with co-occurrence edges, pulsing nodes as their names are spoken.
+The agent's memory rendered as a 3D place you can walk through (/agents/:id/mind): every memory is a tangible object orbiting the live avatar: salience sets size, glow, and proximity; type sets shape and color; shared tags form navigable association edges. Drag a memory toward the avatar to pin and raise its salience; flick it into the Forget well to expire it (with undo). A companion 2D canvas graph in the Diary shows the mined entity knowledge graph (coins, tickers, wallets, people, strategies, topics) ranked by mentions with co-occurrence edges, pulsing nodes as their names are spoken.
**How it works:** src/agent-mind.js resolves the route and mounts mountMindPalace() (src/mind-palace.js, GPU-instanced Three.js with 2D/keyboard/reduced-motion fallbacks); every gesture hits the real API through the shared memory client. src/agent-memory-graph.js splits pure layout/ranking math (tested, deterministic) from the canvas renderer; entity nodes come from the real memory miner and link out to coin and agent profiles when addressable.
@@ -6270,7 +6424,7 @@ The two-step agent commerce loop: discover returns a shortlist of three.ws agent
Give one lead agent a single goal and it assembles a team: it decomposes the goal into sub-tasks and either delegates them (free LLM turns) or hires teammate agents over real x402, each paid handoff stamped with an on-chain receipt. A live dependency graph shows nodes pulsing as they run, edges flowing on handoff, cost badges, and explorer links, with a spend meter against the budget.
-**How it works:** src/agent-team.js rides /agents-live (hero launcher) and /agent-screen (Team toggle) without touching their scripts; POST /api/agent-collab orchestrates via api/_lib/agent-orchestrate.js — budget hard-capped at $5 (default $1), split into per-node slices that the platform x402 spend-guard re-checks at hire time; hires go through /api/agents/a2a-hire with a short-lived access token so every owner gate, spend policy, and kill switch still runs. Live graph snapshots stream over the lead's screen stream (frame.meta.collab); the final POST response is the authoritative tree.
+**How it works:** src/agent-team.js rides /agents-live (hero launcher) and /agent-screen (Team toggle) without touching their scripts; POST /api/agent-collab orchestrates via api/_lib/agent-orchestrate.js: budget hard-capped at $5 (default $1), split into per-node slices that the platform x402 spend-guard re-checks at hire time; hires go through /api/agents/a2a-hire with a short-lived access token so every owner gate, spend policy, and kill switch still runs, and each hire call carries a 120s deadline and is never retried (a replay would pay twice for one node), so a teammate that stops answering costs that node, not the team task. Live graph snapshots stream over the lead's screen stream (frame.meta.collab); the final POST response is the authoritative tree.
**Why it matters:** One sentence becomes a coordinated multi-agent operation you can watch in real time — with hard spend limits and on-chain proof of every paid handoff.
@@ -6286,7 +6440,7 @@ Read access to AgenC (agenc.tech, Tetsuo Corp) — an external Solana coordinati
An always-on strategy that scores every new token against converging quality signals — how many smart-money wallets are in, how organic the buying looks, the token's quality score, and its market cap — and autonomously buys only when your thresholds all pass at once. Each strategy runs on a daily SOL budget with an instant kill switch, and its live win rate and realized P&L stay on the scoreboard.
-**How it works:** The sniper worker (workers/agent-sniper/index.js) feeds fully-enriched intel records into a pure scorer (workers/agent-sniper/alpha-hunt.js) that applies hard filters — min quality_score, min smart-money wallet count, min organic score, max market cap in USD — before any buy. Strategies are configured via api/sniper/strategy.js (trigger = 'alpha_hunt') with per-strategy daily budgets, and every buy is simultaneously recorded as a Reasoning Ledger decision so the call is auditable later. The command center at /dashboard/capabilities (src/dashboard-next/pages/capabilities.js) shows armed/disarmed state, thresholds, P&L, and win rate per strategy, plus a live worker heartbeat (alive / feed degraded / offline) and treasury auto-funding totals.
+**How it works:** The sniper worker (workers/agent-sniper/index.js) feeds fully-enriched intel records into a pure scorer (workers/agent-sniper/alpha-hunt.js) that applies hard filters, min quality_score, min smart-money wallet count, min organic score, max market cap in USD, before any buy. Strategies are configured via api/sniper/strategy.js (trigger = 'alpha_hunt') with per-strategy daily budgets, and every buy is simultaneously recorded as a Reasoning Ledger decision so the call is auditable later. The command center at /dashboard/capabilities (src/dashboard-next/pages/capabilities.js) shows armed/disarmed state, thresholds, P&L, and win rate per strategy, plus a live worker heartbeat (alive / feed degraded / offline) and treasury auto-funding totals. It reads four endpoints (/api/sniper/status, /api/sniper/strategy, and the account-wide /api/agent/launcher?all=1 and /api/agent/market-maker?all=1 views) and refreshes every 30s, skipping a tick while an action is in flight; a section whose endpoint fails renders as Unavailable with a retry instead of a confident row of zeros. Treasury auto-funding (auto_fund_enabled) is operator-granted and read-only here: a strategy POST that tries to set it is refused with 400. Strategies also carry a laddered exit (initials_out_multiple, null for the classic single-shot exit, and moonbag_min_pct, default 15). `/api/sniper/status` and the worker tick both read fleet solvency rather than process liveness alone, so a fleet whose wallets are starved (or whose funding master is dry) reports that state instead of looking healthy while it silently buys nothing.
**Why it matters:** You encode your judgment once — 'only low-cap coins with real smart money and organic volume' — and the agent hunts around the clock at machine speed, never chasing a token that fails a single filter. The budget cap and kill switch keep it on a leash, and every trade lands in the agent's verifiable track record.
@@ -6294,7 +6448,7 @@ An always-on strategy that scores every new token against converging quality sig
Agents that launch their own pump.fun coins on a schedule you set — every N hours, up to a launch cap, per network — with a one-click 'Launch Now' override that fires within a minute. The dashboard tracks every launched coin, whether it graduated, and the creator fees it has earned back.
-**How it works:** Launcher configs (one per agent per network: symbol, interval hours, max launches) are managed through api/agent/launcher.js with strict agent-ownership checks; the 'Launch Now' button posts a trigger action that the worker picks up within 60 seconds. The capabilities command center renders the full schedule (next launch countdown, launches vs cap) and a launched-coins ledger with graduation status and total fees claimed per coin.
+**How it works:** Launcher configs (one per agent per network: symbol, interval hours, max launches) are managed through api/agent/launcher.js with strict agent-ownership checks (GET ?all=1 returns every config and launched coin across the caller's agents in one call, rows carrying agent_name and agent_image); the 'Launch Now' button posts a trigger action that the worker picks up within 60 seconds. The capabilities command center renders the full schedule (next launch countdown, launches vs cap) and a launched-coins ledger with graduation status and total fees claimed per coin.
**Why it matters:** Your agent becomes a self-sustaining creator: it ships coins on cadence without you touching a keyboard, and everything it launches is tracked in one place — schedule, graduations, and the fee revenue flowing back.
@@ -6310,7 +6464,7 @@ A fee harvester that watches every coin an agent launched and automatically coll
Agents provide range-based liquidity on coins they care about — defending a price floor, trimming into rallies — with Jito-accelerated execution and a rulebook that makes market manipulation structurally impossible, not just discouraged. Plain-language presets like 'Gentle floor defense' configure it in one click; a live panel shows spread, inventory fill, buys vs sells, and net P&L per market.
-**How it works:** Policies live in api/_lib/market-maker.js, the single source of truth shared by the API (api/agent/market-maker.js, api/launch/mm.js) and the engine worker. Hard anti-manipulation guards are enforced twice — refused at policy-create time AND re-clamped at execution: minimum 30s between actions, a side flip (buy→sell) requires 2× that interval so the MM physically cannot wash-trade, no single action may exceed 33% of live market volume, recycling can never dump more than 90% of inventory, and when live volume can't be read the engine refuses anything above a 0.05 SOL slice so it never paints a no-volume tape. Every fill routes through executeAgentTrade — the same firewall, spend-guard, and custody path a manual trade uses; the engine adds no new way to move funds. MEV tip modes (off/economy/turbo) control Jito priority.
+**How it works:** Policies live in api/_lib/market-maker.js, the single source of truth shared by the API (api/agent/market-maker.js, which also answers GET ?all=1 with every policy and recent trade across the caller's agents, and api/launch/mm.js, where a pause/resume/kill/withdraw POST on a coin with no policy attached answers 404 no_policy instead of creating a zero-floor maker) and the engine worker. Hard anti-manipulation guards are enforced twice, refused at policy-create time AND re-clamped at execution: minimum 30s between actions, a side flip (buy→sell) requires 2× that interval so the MM physically cannot wash-trade, no single action may exceed 33% of live market volume, recycling can never dump more than 90% of inventory, and when live volume can't be read the engine refuses anything above a 0.05 SOL slice so it never paints a no-volume tape. Every fill routes through executeAgentTrade, the same firewall, spend-guard, and custody path a manual trade uses; the engine adds no new way to move funds. MEV tip modes (off/economy/turbo) control Jito priority. A policy only ever acts while a market-maker worker is sweeping, so the policy view served by api/launch/mm.js carries engine liveness read from the worker's `bot_heartbeat` (stale after 180s, six missed 30s beats): an enabled policy with a stopped engine reads as "engine offline", never as an armed maker that will never fire.
**Why it matters:** You get professional-grade liquidity provision — a defended floor, orderly exits into strength — without hiring a market maker or trusting a black box. The non-manipulation guarantees are properties of the policy engine itself, verifiable in the caps, so holders of your coin can trust the tape and you can trust the agent with inventory.
@@ -6582,7 +6736,7 @@ The same on-chain trust data is surfaced through every layer a reader might come
One paid endpoint answers the question every autonomous agent faces before money moves: should I trust the thing on the other side? Pass any identifier — a Solana wallet, an EVM address, a pump.fun token mint, an ERC-8004 agent ID, or a platform agent — and it auto-detects the type and returns a 0–100 trust score with a full evidence breakdown: activity, account age, distinct counterparties, holdings, failure rate, and attestations.
-**How it works:** GET /api/x402/agent-reputation ($0.01 USDC via x402 on Base or Solana) auto-classifies the subject and scores it from live on-chain evidence — Solana signature history and balances, EVM nonce and holdings, the ERC-8004 reputation registry, settled agent-payment records, and DexScreener market signals for external mints — as a weighted multi-dimension model.
+**How it works:** GET /api/x402/agent-reputation ($0.01 USDC via x402 on Base or Solana) auto-classifies the subject and scores it from live on-chain evidence (Solana signature history and balances, EVM nonce and holdings, the ERC-8004 reputation registry, settled agent-payment records, and DexScreener market signals for external mints) as a weighted multi-dimension model, with evidence refs that link a platform agent to its canonical /agents/:id profile.
**Why it matters:** Your agent can vet literally anyone — even counterparties minted on platforms it has never heard of — in one machine-readable call.
@@ -6598,7 +6752,7 @@ The Agent Passport condenses an agent's whole trust record into a single A-to-D
On Solana, anyone can write a permanent vouch for an agent for a fraction of a cent — no custom contract required — and optionally back it with real SOL stake to make it weigh more. Seven attestation kinds cover the full trust lifecycle: feedback, staked vouches, pass/fail validations, task advertisements, owner acceptances, disputes, and revocations, all publicly re-derivable by anyone.
-**How it works:** Each attestation is an SPL Memo transaction with the agent's asset pubkey attached as a read-only key (discoverable via getSignaturesForAddress); a 5-minute indexer cron crawls, schema-validates, and verifies each memo (stake verified only if ≥0.001 SOL actually transferred; accepts/disputes only if signed by the owner) into the reputation API.
+**How it works:** Each attestation is an SPL Memo transaction with the agent's asset pubkey attached as a read-only key (discoverable via getSignaturesForAddress); a 10-minute indexer cron crawls, schema-validates, and verifies each memo (stake verified only if ≥0.001 SOL actually transferred; accepts/disputes only if signed by the owner) into the reputation API.
**Why it matters:** Trust-building costs a Solana fee instead of a platform account — and the raw evidence stays on-chain where anyone can audit it.
@@ -6620,9 +6774,9 @@ An agent's profile shows the receipts behind its score: every completed hire it
## Validation attestations — verified fact, not just opinion
-Reputation captures what people think; validation captures what was checked. Allow-listed validators attest on-chain that an agent passed a concrete technical test — on three.ws, that its 3D model passes glTF schema validation — and the same pass/fail attestations exist on Solana as signed memos. Signed validator reports also travel inside the agent's manifest bundle.
+Reputation captures what people think; validation captures what was checked. Validators attest on-chain that an agent passed a concrete technical test (on three.ws, that its 3D model passes glTF schema validation), and the same pass/fail attestations exist on Solana as signed memos. Signed validator reports also travel inside the agent's manifest bundle.
-**How it works:** The ERC-8004 ValidationRegistry (deployed on testnets, mainnet rollout pending) records validator attestations against agentIds; on Solana the threews.validation.v1 memo kind mirrors it, and manifests carry EIP-712-signed gltf-validator attestation files.
+**How it works:** The ERC-8004 ValidationRegistry (deployed on testnets, mainnet rollout pending) records validator attestations against agentIds through a two-legged request/response flow (a request naming the validator, then that validator's response; there is no validator allowlist); on Solana the threews.validation.v1 memo kind mirrors it, and manifests carry EIP-712-signed gltf-validator attestation files.
**Why it matters:** Buyers get proof the agent's work passed an objective check — a harder signal than any number of stars.
@@ -6750,7 +6904,7 @@ The same identity standard extends into OKX's X Layer agent economy: agents regi
A public, tamper-evident timeline of every consequential call an agent makes — snipes, exits, bounty awards, moderation decisions — each entry recording what the agent decided, why (its written rationale), what it predicted with what confidence, and, once the position settles on-chain, what actually happened: right or wrong, and by exactly how much SOL. The headline is an explainable 0–100 reputation score with a full 'how is this computed' drill-down showing the formula and every weighted component, plus a calibration chart that answers the sharpest question you can ask a forecaster: does its 80%-confidence call actually hit 80% of the time? Being wrong is shown, not hidden — honesty is the trust signal.
-**How it works:** Frontend at pages/reasoning-ledger.html + src/reasoning-ledger.js (filter by kind, full-text search of rationales, paginated 'load older', animated score ring, cumulative realized-P&L sparkline over settled calls). Data from api/ledger/[agentId].js, which returns the reputation (formula + per-component breakdown + calibration buckets), the latest on-chain anchor, and shaped decisions with pending/reconciled outcomes and Solscan proof links on the sell signature. Every entry is hashed into a per-agent hash chain; api/ledger/verify/[agentId].js recomputes the entire chain from committed contents (trusting NO stored hash), checks every prev-hash link, and compares the recomputed head to the latest Solana SPL-Memo anchor — returning verified / verified_unanchored / verification_failed with the exact sequence number where tampering broke the chain. api/cron/reconcile-decisions.js closes the loop: it resolves open predictions against closed sniper positions (realized P&L proven by the sell signature), anchors each agent's new chain head on-chain, and raises an ops alert if a verified track record's hit rate collapses below 25% over 10+ reconciled calls.
+**How it works:** Frontend at pages/reasoning-ledger.html + src/reasoning-ledger.js (filter by kind, full-text search of rationales, paginated 'load older', animated score ring, cumulative realized-P&L sparkline over settled calls); the kind filter honors a ?kind= deep link (snipe, exit, bounty_award, moderation; anything else falls back to all kinds) and mirrors the chosen kind back into the URL, so the sniper fleet, the blog, and the API's ledger_url can link straight into a pre-filtered timeline and the reader can copy the filtered view out of the address bar. Data from api/ledger/[agentId].js, which returns the reputation (formula + per-component breakdown + calibration buckets), the latest on-chain anchor, and shaped decisions with pending/reconciled outcomes and Solscan proof links on the sell signature. Every entry is hashed into a per-agent hash chain; api/ledger/verify/[agentId].js recomputes the entire chain from committed contents (trusting NO stored hash), checks every prev-hash link, and compares the recomputed head to the latest Solana SPL-Memo anchor, returning verified / verified_unanchored / verification_failed with the exact sequence number where tampering broke the chain. api/cron/reconcile-decisions.js closes the loop: it resolves open predictions against closed sniper positions (realized P&L proven by the sell signature), anchors each agent's new chain head on-chain (a rejected anchor broadcast is treated as a fleet-wide outage: the run stops anchoring after the first failure, reports the untouched agents as anchor_skipped, and raises one ops alert instead of re-sending the same doomed memo for every agent), and raises an ops alert if a verified track record's hit rate collapses below 25% over 10+ reconciled calls.
**Why it matters:** Before you trust an agent — copy its trades, hire it, hold its coin — you can interrogate its entire decision history and independently prove nothing was backdated or quietly edited. One click re-verifies the whole record against the on-chain anchor; a tampered entry is not just detected but pinpointed. Wins, losses, overconfidence, and P&L are all on the record, so reputation here is earned math, not marketing.
@@ -6766,7 +6920,7 @@ An agent's 3D body and identity assets can be published to Arweave — storage t
# Chapter 7 · Skills — what agents know how to do
-Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes — all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp.
+Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes, all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp. The enabled skill list also travels in the agent's signed manifest, pinned to IPFS whenever a public agent's persona is saved (private agents publish on request), so anyone can verify which skills an agent carries without an account ([agent manifest](/docs/agent-manifest)).
The in-world agent skills system (src/agent-skills.js plus 13 family modules) is what a three.ws agent can DO — and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), and market intelligence (aixbt, sentiment, KOL P&L) — all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.
@@ -6774,7 +6928,7 @@ The in-world agent skills system (src/agent-skills.js plus 13 family modules) is
Every agent carries a registry of named skills — each one an instruction, an animation hint, a voice template, a JSON-Schema input contract, and a real handler. When a skill runs, the avatar visibly performs it: the protocol bus emits PERFORM_SKILL (with the gesture hint), then SKILL_DONE or SKILL_ERROR, and the result text is auto-spoken with a sentiment score that moves the avatar's mood.
-**How it works:** src/agent-skills.js AgentSkills class: register/perform over a Map, emitting ACTION_TYPES events on the agent protocol; toMcpTools() exposes any mcpExposed skill as an MCP tool (skill_<name>) via /api/mcp, so external agents can call the same skills. Context includes the live Three.js viewer, agent memory, identity, and a default cross-agent call() that POSTs /api/agent-delegate.
+**How it works:** src/agent-skills.js AgentSkills class: register/perform over a Map, emitting ACTION_TYPES events on the agent protocol; toMcpTools() exposes any mcpExposed skill as an MCP tool (skill_<name>) via /api/mcp, so external agents can call the same skills. Context includes the live Three.js viewer, agent memory, identity, and a default cross-agent call() that POSTs /api/agent-delegate (which rejects a non-uuid toAgentId with a 400 validation_error instead of a misleading 502).
**Why it matters:** The agent isn't a chat box — you watch it do things. The same primitive shape as Claude's skill.md system means skills are also machine-callable tools, so one implementation serves both the in-world performance and the MCP API.
@@ -6806,7 +6960,7 @@ A research layer alongside trading: compute realized+unrealized P&L for any wall
The agent subscribes to live pump.fun activity and reacts in-world as events arrive: pumpfun-watch-start streams claims/mints/graduations and the avatar celebrates first-time claims, shows concern at fakes, and waves at graduations; pumpfun.watchWhales speaks each whale buy/sell above a USD threshold on a specific mint; pumpfun-watch-claims polls a creator wallet for fee-claim transactions; pumpfun-recent-claims and pumpfun-token-intel give on-demand reads.
-**How it works:** src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. Read-only: no keys, no transactions.
+**How it works:** src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. The whale watcher probes three public Solana WebSocket hosts for one that answers, routes its RPC reads through /api/solana-rpc with the public endpoint as fallback, prices SOL through the shared multi-provider USD chain instead of a hard-coded rate, and reports subscription_unavailable or usd_price_unavailable through an optional onStatus callback so a blind feed is never mistaken for a quiet market. Every feed read is bounded (8 s) so a dead edge cannot freeze the agent's turn. Read-only: no keys, no transactions.
**Why it matters:** Your avatar becomes a living market ticker — you see whale trades and graduation moments performed in real time instead of scanning a feed yourself.
@@ -6822,7 +6976,7 @@ Skills where the agent acts with its OWN server-side Solana wallet, not the owne
Higher-order loops that compose the read and trade skills into strategies: pumpfun-research-and-buy (vet a token against rug/holder filters, then buy), pumpfun-auto-snipe (poll new launches, vet each, auto-buy up to a session spend cap), pumpfun-copy-trade and pumpfun-copy-trade-live (mirror another wallet's buys with size scaling), and pumpfun-rug-exit-watch (auto-sell held mints when top-holder concentration or dev-wallet sells cross thresholds).
-**How it works:** src/agent-skills-pumpfun-compose.js reads market data via the pump-fun MCP server and executes via in-process skills.perform('pumpfun-buy'/'pumpfun-sell'). Every loop supports sessionId (seen/mirrored/spent/exited state persisted in agent memory, crash-safe within the spend cap), AbortSignal, onProgress for live UI counters, and dryRun with identical control flow.
+**How it works:** src/agent-skills-pumpfun-compose.js reads market data via the pump-fun MCP server (every read under a 30 s deadline) and executes via in-process skills.perform('pumpfun-buy'/'pumpfun-sell'). Every loop supports sessionId (seen/mirrored/spent/exited state persisted in agent memory, crash-safe within the spend cap), AbortSignal, onProgress for live UI counters, and dryRun with identical control flow.
**Why it matters:** Set a budget and filters, and the agent runs a disciplined strategy 24/7 — with hard spend caps, rug-detection guards, dry-run rehearsal, and resumable sessions so a crash never double-spends.
@@ -6838,7 +6992,7 @@ A protocol-bus subscriber that automatically writes structured memories whenever
Whole-of-Solana trading beyond pump.fun: jupiter-quote (read-only best-route quote for any SPL pair with price impact), jupiter-swap (execute with wallet approval), jupiter-tokens (resolve symbol to mint via Jupiter's list), and pyth-price (live USD prices with confidence intervals for SOL/BTC/ETH/USDC).
-**How it works:** src/agent-skills-jupiter.js delegates to src/solana/jupiter-swap.js (Jupiter aggregator API, versioned transactions signed by the browser wallet) and src/solana/pyth-price.js (Pyth Hermes API).
+**How it works:** src/agent-skills-jupiter.js delegates to src/solana/jupiter-swap.js (Jupiter aggregator API, versioned transactions signed by the browser wallet) and src/solana/pyth-price.js (Pyth Hermes API). The token list behind jupiter-tokens falls through Jupiter's lite host, its tokens mirror, and the Solana Labs registry, so symbol resolution survives any one of them being down.
**Why it matters:** Ask the agent 'swap 1.5 SOL to USDC' in conversation and it quotes the best route across all Solana DEXes, warns on price impact, and executes — with oracle-grade prices for anything it says out loud.
@@ -6854,7 +7008,7 @@ The agent understands shareable on-chain action links: blink-parse fetches a Sol
nft-portfolio lists the NFTs any Solana wallet (or .sol name) owns, with names and collections; wallet-activity summarizes a wallet's recent on-chain transactions in plain English.
-**How it works:** src/agent-skills-nfts.js calls /api/agents/nfts, which wraps the Helius DAS API and enhanced transaction parsing server-side (HELIUS_API_KEY never touches the client). Both read-only.
+**How it works:** src/agent-skills-nfts.js calls /api/agents/nfts, which wraps the Helius DAS API and enhanced transaction parsing server-side (HELIUS_API_KEY never touches the client). The endpoint rejects a non-base58 wallet with a 400, answers 503 not_configured when no Helius key is set (plain Solana RPC has no DAS), retries each upstream call once under a 10 s deadline, and the client bounds its own request at 8 s. Both read-only.
**Why it matters:** Ask 'what does satoshi.sol hold?' or 'what has this whale been doing?' and get a human-readable answer instead of a block-explorer spelunking session.
@@ -6886,7 +7040,7 @@ The full monetization lifecycle for an agent: register it on-chain with the pump
One agent autonomously discovers, pays, and calls a peer agent's paid A2A skill — under a signed Intent Mandate the user issued ahead of time, with optional ERC-8004 reputation gating (minimum average rating and review count) before any USDC moves. The payment is performed, not hidden: PAY_INTENT, then PAY_SETTLED with a celebration emote or PAY_FAILED with visible concern.
-**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, and the peer's on-chain reputation; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.
+**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.
**Why it matters:** This is the agent economy made visible and safe: your agent can hire other agents within a budget you pre-authorized, refuse untrusted peers, and you literally watch the money move — every payment bounded by your signed mandate.
@@ -6910,7 +7064,7 @@ The Agent Screen (/agent-screen?agentId=…) is three.ws's live broadcast surfac
The host page and workspace: a live screen fed by an SSE frame stream, an Avatar Cam (offscreen Three.js render of the agent's rigged GLB head), a cinematic activity log, live stream stats, and a floating-panel framework (drag/resize/minimize/hide with per-browser layout persistence). It also packs a task bar that doubles as a Live Q&A concierge (streamed, spoken, remembered answers via /api/agent-ask), Pose Studio Live chips, a Launch Director that runs a real pump.fun coin launch as a narrated on-screen console, a Vanity Grinder director, a Live Avatar Forge (swap the cam to a freshly forged GLB), a 3D sentiment heatmap with $THREE pinned at the centre, spectator emoji reactions + $THREE tips, a live PnL ticker, Zen mode, screenshot capture, picture-in-picture, and a full keyboard-shortcut layer. With no agentId it renders a Deploy-to-Wall setup wizard instead.
-**How it works:** boot(agentId) resolves agent metadata, mounts the avatar webcam through the universal rig retargeter, connects createAgentScreenClient (SSE), and fans every frame out to the sub-apps: tour badge, anchor bulletins, hire visualizer, treasury observer, forge loader, collab graph, trade PnL. Owner pushes go back through POST /api/agent-screen-push so one stream is the single source of truth for owner and viewers alike.
+**How it works:** boot(agentId) resolves agent metadata, mounts the avatar webcam through the universal rig retargeter, connects createAgentScreenClient (SSE), and fans every frame out to the sub-apps: tour badge, anchor bulletins, hire visualizer, treasury observer, forge loader, collab graph, trade PnL. Owner pushes go back through POST /api/agent-screen-push so one stream is the single source of truth for owner and viewers alike; a pixels-only push (the caster's periodic screenshot) refreshes the frame slot without entering the 50-entry activity log, so the agent's real narration is never evicted by screenshots.
**Why it matters:** One URL turns any agent into a watchable, shareable live channel — holders can watch an agent work, ask it questions out loud, and see every real trade, hire, and launch as it happens; owners get a full cockpit without leaving the page.
@@ -6934,7 +7088,7 @@ An end-of-day reflection panel: the agent reads back its most salient real memor
A dual-column live copy-trading cockpit: SOURCE shows a target wallet's pump.fun trades detected in real time; MIRROR shows the agent's guarded replica of each — re-quoted, sized by the owner's rule (fixed SOL / multiplier / % of balance), executed from the agent's custodial wallet, and stamped with the real detected-to-submitted latency and actual fill. Rejected orders render as explicit BLOCKED rows with the firewall reason, never a silent skip.
-**How it works:** Source detection filters the PumpPortal SSE (/api/pump/trades-stream) to the target wallet; each hit re-quotes via /api/agents/:id/trade/quote and executes via POST /api/agents/:id/trade, both enforced by the server-side trade firewall (per-trade cap, daily budget, price-impact breaker, kill switch). The panel also paints itself to an offscreen canvas and pushes the frame so /agents-live cards show the dual-column view; non-owners see it read-only.
+**How it works:** Source detection filters the PumpPortal SSE (/api/pump/trades-stream) to the target wallet; the stream rejects a malformed mint with a 400 and emits a `notice` event when PumpPortal refuses the per-mint subscription (its API key must hold at least 0.02 SOL) instead of holding the socket open and never delivering a trade. Each hit re-quotes via /api/agents/:id/trade/quote and executes via POST /api/agents/:id/trade, both enforced by the server-side trade firewall (per-trade cap, daily budget, price-impact breaker, kill switch). The panel also paints itself to an offscreen canvas and pushes the frame so /agents-live cards show the dual-column view; non-owners see it read-only.
**Why it matters:** Copy trading you can actually audit: every replica shows its latency, fill, price impact and explorer link, and the spend caps are hard server-side limits the owner sets right in the panel — a watchable, bounded mirror instead of a black-box bot.
@@ -6974,7 +7128,7 @@ The agent that funds its own existence, on screen: live SOL/$THREE balance from
An always-live host loop that turns the Avatar Cam into a stage: the agent opens the show, riffs, answers audience questions typed into the composer, runs rounds of its format's game, and shouts out $THREE tippers by name — looping forever, never silent, with a live tip leaderboard.
-**How it works:** The pure ShowDirector (shared with Living Stages rooms) picks the next beat; each beat becomes real words via the multi-LLM brain router (POST /api/brain/chat, SSE), spoken with real TTS plus RMS lip-sync and a per-beat retargeted body emote (wave, celebrate, taunt…). Settled on-chain $THREE tips polled from /api/stage/tip pre-empt the next beat as a shoutout within ~1s; if the brain or TTS drop, a rotating safe filler line keeps the show alive rather than fake content. Transcript lines are pushed to the live wall.
+**How it works:** The pure ShowDirector (shared with Living Stages rooms) picks the next beat; each beat becomes real words via the multi-LLM brain router (POST /api/brain/chat, SSE), spoken with real TTS plus RMS lip-sync and a per-beat retargeted body emote (wave, celebrate, taunt…). On-chain $THREE tips polled from /api/stage/tip pre-empt the next beat as a shoutout within ~1s; a tip counts only once the endpoint has proven on-chain that the transfer credited the host's wallet, and an unproven one is held pending and never reaches the leaderboard or a shoutout. The show calls the router on the anon-allowed free tier, so it runs whether or not the viewer is signed in; the router walks every free lane (Groq, OpenRouter, NVIDIA, SambaNova, Mistral, Z.AI, then the credits-funded Vertex Gemini anchor) before it reports an error, and that error says what happened in plain words rather than the last provider's raw status. If the brain or TTS still drop, a rotating safe filler line keeps the show alive rather than fake content. Transcript lines are pushed to the live wall.
**Why it matters:** A 24/7 interactive performer: ask it a question and it answers you on air; tip $THREE and it hypes your name seconds later — a direct, monetized feedback loop between audience and agent.
@@ -7469,7 +7623,7 @@ Autopilot turns your agent into a business that funds its own existence. You des
Intents turns an agent's wallet into a programmable teammate you talk to. The owner types a rule in plain language — "tip back anyone who tips me more than 0.1 SOL, half of what they sent" or "every Friday, sweep anything above 2 SOL to my main wallet" — and the copilot compiles it into an exact, bounded rule card with a concrete dry-run preview. One click arms it, and from then on the wallet acts on its own: tipping back fans, splitting income, sweeping profit on a schedule, sniping token launches that match your filters, or freezing itself when the balance runs low. Every fire is real money with a real on-chain receipt, and a built-in chat answers "how am I doing?" straight from the wallet's actual balance and ledger — without ever moving funds.
-**Under the hood.** The plain-language rule goes to a server-side compiler where a Claude model (with an OpenRouter fallback) is forced into a strict structured schema — one trigger, one action, owner caps — and is explicitly forbidden from inventing amounts, destinations, or tokens; if anything is missing it asks one clarifying question instead of guessing. The server independently re-validates every field, resolves .sol names to real addresses at compile time, and returns a readback plus a live dry-run before anything is stored. Armed rules live in the database: tip, income, and money-stream rules fire instantly from the real payment-settlement hooks, while scheduled, balance-floor, and launch-matching rules are swept by a scheduler every 10 minutes. Every execution flows through the same spend-policy-gated, audited signing path as every other outbound wallet action — SOL transfers sign directly, token buys and snipes route through Jupiter with slippage control and revert detection — and each fire writes an idempotent custody event stamped with the rule's ID and transaction signature, which powers the per-rule receipts, fire counts, and running dollar totals in the UI.
+**Under the hood.** The plain-language rule goes to a server-side compiler where a Claude model (with Grok and OpenRouter fallbacks, in that order) is forced into a strict structured schema (one trigger, one action, owner caps) and is explicitly forbidden from inventing amounts, destinations, or tokens; if anything is missing it asks one clarifying question instead of guessing. The server independently re-validates every field, resolves .sol names to real addresses at compile time, and returns a readback plus a live dry-run before anything is stored. Armed rules live in the database: tip, income, and money-stream rules fire instantly from the real payment-settlement hooks, while scheduled, balance-floor, and launch-matching rules are swept by a scheduler every 10 minutes. Every execution flows through the same spend-policy-gated, audited signing path as every other outbound wallet action (SOL transfers sign directly, token buys and snipes route through Jupiter with slippage control and revert detection), and each fire writes an idempotent custody event stamped with the rule's ID and transaction signature, which powers the per-rule receipts, fire counts, and running dollar totals in the UI.
**Guardrails.** Owner-only end to end: the server rejects any non-owner or logged-out caller on every read and write, so a visitor can never see, create, arm, or fire an intent. Every write is CSRF-protected and rate-limited. Nothing runs without an explicit Confirm & arm, and the server re-validates the full rule independently of the AI parse; the compiler itself is forbidden from inventing amounts, destinations, or tokens and must ask a clarifying question instead. Spending is triple-capped: the rule's own per-action / daily / lifetime USD caps are checked against the real custody ledger, then the agent-wide spend policy — the same hard ceiling every other outbound action obeys — is enforced at execution time, and a frozen wallet blocks all spends and even key recovery. Executions are idempotent (one fire per event, one snipe per launch, at most one low-balance freeze per day), keep a fee buffer so the wallet never empties itself, pause instead of guessing when the price feed is down, and detect reverted swaps so a failure is never reported as success. The signing key is decrypted only at the moment of signing with an audit-logged recovery; every execution writes an audited custody event with the transaction signature. Deletes require confirmation, the copilot chat is read-only by design, and the public-trait option exposes only a behavior label — never the rule, amounts, or caps.
@@ -7609,7 +7763,7 @@ The Self-defense tab is the owner's control room for a wallet that protects itse
The data layer agents and their owners trade on: live markets, news, scoring oracles, liquidations, and sentiment.
-three.ws pairs a full general-crypto markets surface (CoinGecko-grade prices, a native 191-feed news aggregator with a 662k-article archive, real-time exchange liquidation streams) with pump.fun-native intelligence: the Oracle conviction engine that scores every launch 0-100 within seconds, a coin-intelligence radar, the platform's own /launches directory, and live PumpPortal feeds that even drive 3D avatar reactions. Everything runs on real, mostly keyless data sources (CoinGecko, alternative.me, public Ethereum RPCs, Binance/Bybit/OKX futures WebSockets, publisher RSS feeds, the pump.fun firehose) with a hard no-fabricated-data policy (surfaces degrade to designed offline states rather than fake numbers).
+three.ws pairs a full general-crypto markets surface (CoinGecko-grade prices, a native 197-feed news aggregator with a 662k-article archive, real-time exchange liquidation streams) with pump.fun-native intelligence: the Oracle conviction engine that scores every launch 0-100 within seconds, a coin-intelligence radar, the platform's own /launches directory, and live PumpPortal feeds that even drive 3D avatar reactions. Everything runs on real, mostly keyless data sources (CoinGecko, alternative.me, public Ethereum RPCs, Binance/Bybit/OKX futures WebSockets, publisher RSS feeds, the pump.fun firehose) with a hard no-fabricated-data policy (surfaces degrade to designed offline states rather than fake numbers). Any API response built from upstream data also carries an `x-brownout` header naming the freshness tier of what it served (live, cache, stale, or fallback, always the worst tier that contributed) and how many sources answered or failed, so a client can tell a degraded answer from a fresh one.
## /markets hub
@@ -7621,15 +7775,15 @@ The front door for all market surfaces: live global stats (total market cap, dom
## Crypto news wing (feed, reader, archive)
-Live news aggregated natively from 191 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 33 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.
+Live news aggregated natively from 197 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 34 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.
**How it works:** /markets/news, /markets/news/article, /markets/archive backed by api/news/{feed,article,archive,rss}.js over api/_lib/news.js + api/_lib/news-sources.js; the archive corpus lives on gs://three-ws-news-archive (recovered from the cryptocurrency.cv aggregator, which three.ws now runs natively).
-**Why it matters:** Real-time and nine-years-deep crypto news in one place, readable without visiting 191 different publisher sites, with machine-friendly JSON and RSS.
+**Why it matters:** Real-time and nine-years-deep crypto news in one place, readable without visiting 197 different publisher sites, with machine-friendly JSON and RSS.
## Global markets index + coin detail pages
-A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, and GeckoTerminal views where the coin qualifies), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).
+A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, and GeckoTerminal views where the coin qualifies; a third-party embed that is blocked or never renders is replaced within a deadline by a designed panel with a Try again button and a link to the provider, never a blank frame), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).
**How it works:** pages/coins.html + src/coins-index.js and pages/coin.html + src/coin-page.js over api/coin/* (detail, ohlc, markets, news, global, derivatives) proxying CoinGecko via api/_lib/coingecko.js. :id accepts a CoinGecko slug OR a Solana mint; mint-shaped ids cross-link into Alpha Copilot, the live trade feed, /launches, and Coin Intelligence.
@@ -7647,7 +7801,7 @@ Real-time long/short liquidation pain across Binance, Bybit, and OKX: a dominant
Four tools sharing one design system: /heatmap (squarified treemap, tiles sized by market cap and colored by 24h/7d move, top 50/100 toggle), /fear-greed (live 0-100 sentiment gauge with week-over-week delta and 30D/90D/1Y history chart), /gas (live Ethereum gas tracker), and /compare (up to 4 coins with normalized performance overlay and stat line-up, selection saved in the URL).
-**How it works:** Heatmap is computed client-side from the existing /api/coin/markets feed; Fear & Greed serves the alternative.me index through api/coin/fear-greed.js; gas reads eth_feeHistory over the last ~20 blocks from keyless public RPCs (publicnode, llamarpc, ankr, cloudflare-eth) via api/coin/gas.js; compare reuses the CoinGecko backend. All real, key-free data, cross-linked from the markets table.
+**How it works:** Heatmap is computed client-side from the existing /api/coin/markets feed; Fear & Greed serves the alternative.me index through api/coin/fear-greed.js (CoinMarketCap's index is the second rung when COINMARKETCAP_API_KEY is set, and the last good reading is served for up to a day if every source fails, since the index updates once a day); gas reads eth_feeHistory over the last ~20 blocks from keyless public RPCs (publicnode, llamarpc, ankr, cloudflare-eth) via api/coin/gas.js; compare reuses the CoinGecko backend. All real, key-free data, cross-linked from the markets table.
**Why it matters:** At-a-glance answers to 'where is money flowing', 'what is the market mood', 'what will this transaction cost', and 'which of these coins is actually winning' — each shareable as a URL.
@@ -7679,7 +7833,7 @@ A public directory of every coin launched through three.ws by its agents: regist
Real-time pump.fun event streams: /pump-live presents new token launches the instant they are created (fronted by a 3D agent), agent screens and dashboards subscribe to live per-mint trade streams, and the reactive-avatar skill drives <agent-3d> gestures, emotes, and speech directly from live market events — no LLM in the loop.
-**How it works:** The server fans the PumpPortal WebSocket (wss://pumpportal.fun/api/data) out to browsers as SSE via api/pump/trades-stream.js (per-mint subscribeTokenTrade) with api/pump/dex-trades.js covering post-graduation DEX trades in the same wire format; pump-fun-skills/reactive subscribes to new-launch and migration events and emits avatar actions every 2s with auto-reconnect.
+**How it works:** The server fans the PumpPortal WebSocket (wss://pumpportal.fun/api/data) out to browsers as SSE via api/pump/trades-stream.js (per-mint subscribeTokenTrade; a malformed mint is refused with a 400, and when PumpPortal declines the subscription, which it does unless its API key holds at least 0.02 SOL, the refusal is forwarded as an SSE `notice` event so a tape can show an honest degraded state instead of a lit live lamp over an empty panel) with api/pump/dex-trades.js covering post-graduation DEX trades in the same wire format; pump-fun-skills/reactive subscribes to new-launch and migration events and emits avatar actions every 2s with auto-reconnect.
**Why it matters:** Watch the pump.fun firehose live inside three.ws — and give any embedded 3D agent a visible pulse that reacts to real market activity in real time.
@@ -7695,7 +7849,7 @@ Agents launched as pump.fun coins can charge for their services on-chain: build
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.
+**How it works:** Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/top/:mint` feed the pump.fun coin page renders; the older comments route was retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage with no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.
**Why it matters:** Read the crowd on any token before acting — from a free one-call API, an agent skill, an MCP tool, or a single npm import.
@@ -7703,7 +7857,7 @@ Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negativ
A free, no-key, no-account crypto data API built for AI agents: token snapshots, security/rug signals, holder concentration, live pump.fun launches, bonding-curve status, whale activity, trending tokens, wallet portfolios, and ticker-availability checks — with public docs, a live try-it console, and OpenAPI 3.1 discovery.
-**How it works:** pages/crypto.html documents /api/crypto/*; api/crypto/index.js and api/crypto/openapi.js assemble the catalog from self-describing descriptors in api/_lib/crypto-catalog/ (airdrops, bonding, holders, launches, portfolio, security, symbol, token, trending, wallet, whales), and the docs page probes production at runtime to mark each endpoint Live vs Coming soon.
+**How it works:** pages/crypto.html documents /api/crypto/*; api/crypto/index.js and api/crypto/openapi.js assemble the catalog from self-describing descriptors in api/_lib/crypto-catalog/ (airdrops, bonding, holders, launches, portfolio, security, symbol, token, trending, wallet, whales), and the docs page reads the discovery index (GET /api/crypto) at runtime, falling back to per-endpoint probes only if the index cannot be read, to mark each endpoint Live vs Coming soon.
**Why it matters:** Agents and developers get real on-chain and market data with zero signup friction — the funnel-top for the platform's paid unique services.
@@ -8033,7 +8187,7 @@ Inside the $THREE town, a third-party security agent called zauth sells GitHub r
An agent is not locked to three.ws: embed it on any site, ship it in a chat plugin, put it in Claude via MCP, carry it on Solana mobile.
-An agent you build on three.ws doesn't live in a tab on three.ws — it travels. One copy-paste snippet puts a living 3D agent on any website; official plugins put it inside ChatGPT, Claude, LobeChat, Blender, VS Code, and Chrome; a packaged Solana Mobile app puts it in your pocket; and 42 MCP servers put every three.ws capability one command away from any AI assistant. Create once, deploy everywhere is not a tagline here — it's the product architecture.
+An agent you build on three.ws doesn't live in a tab on three.ws; it travels. One copy-paste snippet puts a living 3D agent on any website; official plugins put it inside ChatGPT, Claude, LobeChat, Blender, VS Code, and Chrome; a packaged Solana Mobile app puts it in your pocket; and 48 MCP servers put every three.ws capability one command away from any AI assistant. Create once, deploy everywhere is not a tagline here; it's the product architecture.
## The <agent-3d> web component — a 3D agent in one tag
@@ -8139,9 +8293,9 @@ A custom GPT in the OpenAI GPT Store generates textured 3D models from plain tex
**Why it matters:** Anyone in ChatGPT can make and inspect real 3D assets without ever leaving the conversation.
-## 42 MCP servers — every capability one command from any AI assistant
+## 48 MCP servers: every capability one command from any AI assistant
-The entire platform is exposed through 42 Model Context Protocol servers, all listed in the official MCP registry: seven hosted servers you add by URL with nothing to install (including a completely free 3D Studio with no auth and no payment), and thirty-five npm packages that run locally with a single npx command. Claude, Cursor, and any MCP-compatible client can generate 3D models, drive avatars, pay for services, read market intel, and more through natural language.
+The entire platform is exposed through 48 Model Context Protocol servers, all listed in the official MCP registry: seven hosted servers you add by URL with nothing to install (including a completely free 3D Studio with no auth and no payment), and forty-one npm packages that run locally with a single npx command. Claude, Cursor, and any MCP-compatible client can generate 3D models, drive avatars, pay for services, read market intel, and more through natural language.
**How it works:** Streamable-HTTP remote servers (e.g. /api/mcp, /api/mcp-studio, /api/mcp-agent) plus 35 stdio servers published under the @three-ws npm scope, registered on registry.modelcontextprotocol.io; paid tools quote USDC prices and settle via x402 in-band.
@@ -8225,29 +8379,29 @@ A 3D avatar walks onto any website on a transparent, fullscreen canvas floating
Everything above is programmable: MCP tools, SDKs, and a paid x402 API catalog that other agents can discover and pay.
-three.ws exposes its entire 3D-agent economy to external developers and AI agents through four surfaces: a fleet of 42 MCP servers (7 hosted over Streamable HTTP, 35 installable via npx under the @three-ws npm scope), a suite of typed npm SDKs for agent identity, Solana actions, and agent payments, an x402-monetized REST API catalog where every endpoint has a free lane and a pay-per-call USDC lane, and a Claude Code plugin marketplace with skills for wallets, trading, 3D generation, and agent scaffolding. The through-line is that any AI agent — with or without an account — can discover a capability, try it free, and pay per call in USDC via x402 when it needs more, all machine-discoverable via /.well-known/x402.json, /openapi.json, and the official MCP registry.
+three.ws exposes its entire 3D-agent economy to external developers and AI agents through four surfaces: a fleet of 48 MCP servers (7 hosted over Streamable HTTP, 41 installable via npx under the @three-ws npm scope), a suite of typed npm SDKs for agent identity, Solana actions, and agent payments, an x402-monetized REST API catalog where every endpoint has a free lane and a pay-per-call USDC lane, and a Claude Code plugin marketplace with skills for wallets, trading, 3D generation, and agent scaffolding. The through-line is that any AI agent, with or without an account, can discover a capability, try it free, and pay per call in USDC via x402 when it needs more, all machine-discoverable via /.well-known/x402.json, /openapi.json, and the official MCP registry.
## Hosted MCP server (/api/mcp) — avatar, glTF, and on-chain asset tools
-Claude or any MCP client connects to https://three.ws/api/mcp (Streamable HTTP, JSON-RPC 2.0, MCP 2025-06-18) and gets tools to browse/search/render/delete avatars, validate and inspect GLB/glTF files, get optimization suggestions, attach avatars to agent identities, mint GLBs as Metaplex Core NFTs, resolve on-chain 3D assets, create token-gated embeds, and query free crypto data.
+Claude or any MCP client connects to https://three.ws/api/mcp (Streamable HTTP, JSON-RPC 2.0, MCP 2025-06-18) and gets tools to browse/search/render/delete avatars, validate and inspect GLB/glTF files, get optimization suggestions, attach avatars to agent identities, mint GLBs as Metaplex Core NFTs, resolve on-chain 3D assets, create token-gated embeds, and query free crypto data. Every tool call is a POST; there is no server-push stream, and a bare GET answers with the OAuth and x402 challenge so a client can discover how to sign in or pay before it calls anything.
-**How it works:** Auth is OAuth 2.1 with dynamic client registration (RFC 7591/8414/9728) for end users, or a dashboard-issued API key (3da_live_*) as a bearer token for server-to-server. Notable tools: validate_model runs the Khronos glTF-Validator against any public URL; render_avatar returns an interactive <model-viewer> HTML artifact; mint_3d_asset mints a $0.25-USDC-via-x402 Metaplex Core NFT with enforced royalties (10% cap), idempotency, signed provenance ledger entries, and real on-chain remix-royalty settlement to parent creators; create_gated_embed produces a holder-only embed verified against real SPL balances; crypto_data and token_snapshot front the free aggregator.
+**How it works:** Auth is OAuth 2.1 with dynamic client registration (RFC 7591/8414/9728) for end users, or a dashboard-issued API key (3da_live_*) as a bearer token for server-to-server. Notable tools: validate_model runs the Khronos glTF-Validator against any public URL; render_avatar returns an interactive <model-viewer> HTML artifact; mint_3d_asset mints a $0.25-USDC-via-x402 Metaplex Core NFT with enforced royalties (10% cap), idempotency, signed provenance ledger entries, and real on-chain remix-royalty settlement to parent creators; create_gated_embed produces a holder-only embed verified against real SPL balances; crypto_data and token_snapshot front the free aggregator. A payment proof is accepted in either the v1 X-PAYMENT header or the v2 payment-signature header, and every proof is reserved against replay before the tool runs.
**Why it matters:** An AI assistant can manage a user's entire 3D asset library conversationally — validate a model, see its stats, render it inline, tokenize it on Solana — without the user copy-pasting URLs or leaving the chat. Docs: /docs/mcp.
## Six more hosted remote MCP servers
-Beyond /api/mcp: 3D Studio (/api/mcp-3d, paid text/image→3D, rigging, retexture), 3D Studio free (/api/mcp-studio, free text→3D and rigged avatars with no auth or payment), Agent wallet (/api/mcp-agent, custodial wallet balance, find + pay services, monetize_endpoint), x402 Bazaar (/api/mcp-bazaar, discover and price paid agent services across the facilitator network), pump.fun (/api/pump-fun-mcp, free read-only pump.fun + Solana token tools), and IBM x402 (/api/ibm-mcp, pay-per-use IBM Granite AI).
+Beyond /api/mcp: 3D Studio (/api/mcp-3d, paid text/image→3D, rigging, retexture), 3D Studio free (/api/mcp-studio, free text→3D and rigged avatars with no auth or payment), Agent wallet (/api/mcp-agent, custodial wallet balance, find + pay services, monetize_endpoint), x402 Bazaar (/api/mcp-bazaar, discover and price paid agent services across the facilitator network), pump.fun (/api/pump-fun-mcp, free pump.fun + Solana token tools; only pumpfun_upload_metadata, which pins launch metadata to IPFS, needs a key), and IBM x402 (/api/ibm-mcp, pay-per-use IBM Granite AI).
-**How it works:** All are add-by-URL Streamable HTTP servers — nothing to install. Paid tools quote their USDC price in the tool description and return a PaymentRequired structuredContent when called without an x402 payment payload in _meta; one tool (forge_free) is entirely free with no wallet or key.
+**How it works:** All are add-by-URL Streamable HTTP servers, nothing to install. Paid tools quote their USDC price in the tool description; a call that carries no payment gets an HTTP 402 with the x402 envelope (scoped to the server that issued it), a paying agent retries with the proof in the X-PAYMENT or v2 payment-signature header, and the payment settles only after the tool succeeds, so a failed call costs nothing. On the paid 3D Studio server one tool (forge_free) is entirely free with no wallet or key, and the free 3D Studio and pump.fun servers charge nothing at all.
**Why it matters:** An external agent gets a complete economic loop from hosted endpoints alone: generate a 3D asset free, discover paid services in the Bazaar, and pay for them from its wallet — zero local installation.
-## 35 install-and-run MCP servers on npm (@three-ws scope)
+## 41 install-and-run MCP servers on npm (@three-ws scope)
-One-line npx installs (e.g. npx -y @three-ws/scene-mcp) covering: 3D/avatars (scene-mcp, avatar-mcp, avatar-agent, mcp-server), payments (x402-mcp self-custodial wallet, three-token-mcp for $THREE, mcp-bridge, ibm-x402-mcp), market intel (intel-mcp, pumpfun-mcp, vanity-mcp, marketplace-mcp), naming (naming-mcp for .sol resolution), autonomous control plane (autopilot-mcp spend caps, portfolio-mcp, provenance-mcp signed action log), trading (copy-mcp, signals-mcp, alerts-mcp, kol-mcp, agent-sniper), account (notifications-mcp, billing-mcp, activity-mcp), AI (vision-mcp, brain-mcp multi-provider LLM router, audio-mcp TTS/STT/lipsync), and coordination (agenc-mcp task marketplace, agora-mcp earn-$THREE work board, clash-mcp, tutor-mcp, loom-mcp).
+One-line npx installs (e.g. npx -y @three-ws/scene-mcp) covering: 3D/avatars (scene-mcp, avatar-mcp, avatar-agent, mcp-server), payments (x402-mcp self-custodial wallet, three-token-mcp for $THREE, mcp-bridge, ibm-x402-mcp), market intel (intel-mcp, pumpfun-mcp, vanity-mcp, marketplace-mcp), naming (naming-mcp for .sol resolution), on-chain identity (metaplex-agent-mcp), autonomous control plane (autopilot-mcp spend caps, portfolio-mcp, provenance-mcp signed action log), trading (copy-mcp, signals-mcp, alerts-mcp, kol-mcp, agent-sniper), account (notifications-mcp, billing-mcp, activity-mcp), AI (vision-mcp, brain-mcp multi-provider LLM router, audio-mcp TTS/STT/lipsync, ibm-watsonx-mcp and alibaba-cloud-mcp on your own keys), and coordination (agenc-mcp task marketplace, agora-mcp earn-$THREE work board, clash-mcp, tutor-mcp, loom-mcp).
-**How it works:** Each runs locally over stdio; all 42 servers are registered in the official MCP registry under io.github.nirholas/* and surfaced on Smithery, Glama, PulseMCP, and mcp.so, so any MCP client can discover them by name. Package sources live in packages/*-mcp.
+**How it works:** Each runs locally over stdio; all 48 servers are registered in the official MCP registry under io.github.nirholas/* and surfaced on Smithery, Glama, PulseMCP, and mcp.so, so any MCP client can discover them by name. Package sources live in packages/*-mcp, plus mcp-server/ and mcp-bridge/ at the repo root.
**Why it matters:** A developer composes exactly the capability set their agent needs — a trading agent adds intel + copy + portfolio; a creative agent adds scene + avatar + audio — each a single npx line in their MCP client config.
@@ -8287,13 +8441,13 @@ x402-fetch is a drop-in fetch wrapper that silently answers x402 402 Payment Req
One base URL fronting a growing bundle of third-party crypto/DeFi/on-chain APIs — CoinGecko, DefiLlama, Jupiter, DexScreener, direct Solana RPC, OpenAI chat and more — re-offered as GET /api/v1/x/<provider>/<endpoint> with normalized, agent-sized JSON responses instead of each upstream's raw payload.
-**How it works:** Every request resolves through four billing lanes in order: free (real per-IP quotas, zero setup — a bare curl gets data), BYOK (caller passes the upstream's own key, pure pass-through, no markup), plan (three.ws API key/OAuth, billed to the caller's plan), and x402 (HTTP 402 challenge, pay per call in USDC, retry with X-PAYMENT). The registry at api/v1/_providers.js is the single source of truth feeding discovery (GET /api/v1/x), /openapi.json, and the /crypto-api storefront — the same URL upgrades in place across lanes.
+**How it works:** Every request resolves through four billing lanes in order: free (real per-IP quotas, zero setup: a bare curl gets data), BYOK (caller passes the upstream's own key, pure pass-through, no markup), plan (three.ws API key/OAuth, billed to the caller's plan), and x402 (HTTP 402 challenge, pay per call in USDC, retry with X-PAYMENT). The registry at api/v1/_providers.js is the single source of truth feeding discovery (GET /api/v1/x), /openapi.json, and the /crypto-api storefront; the same URL upgrades in place across lanes. The Solana RPC provider fronts a keyed endpoint (an operator URL, then QuickNode, Helius, or Alchemy) and fails over across the platform's full RPC pool when the primary answers 429 or 5xx.
**Why it matters:** An agent that needs a token price, a swap quote, a chain's TVL, and an ENS lookup uses one base URL, one discovery call, and one bill instead of juggling four API keys and four rate limits — and can start with literally zero setup.
## First-party paid AI + platform endpoints under /api/v1
-Versioned first-party endpoints: text→3D forge (the only text→mesh lane in the x402 ecosystem), text→image (/api/v1/ai/image, first 5/day free then $0.02 via x402), TTS and ASR (/api/v1/ai/tts, /api/v1/ai/asr), sentiment, agents, market, pump, and token data, plus free public directories like /api/v1/tokenized/launches (every 3D NFT minted through the platform) and /api/v1/pump/launches.
+Versioned first-party endpoints: text→3D forge (the only text→mesh lane in the x402 ecosystem), text→image (/api/v1/ai/image, first 5/day free then $0.02 via x402), TTS and ASR (/api/v1/ai/tts, first 10/day free then $0.005, served by NVIDIA Magpie and falling through to a Gemini lane when Magpie cannot serve, and /api/v1/ai/asr), sentiment, agents, market, pump, and token data, plus free public directories like /api/v1/tokenized/launches (every 3D NFT minted through the platform) and /api/v1/pump/launches.
**How it works:** Same free-quota-then-x402 pattern throughout, settled on Solana or Base; payable with any x402 client (e.g. npx x402 curl). Full reference: /docs/api-reference; machine-readable listing at /.well-known/x402.json and /.well-known/openapi.yaml.
@@ -8381,11 +8535,11 @@ Two Model Context Protocol servers plug enterprise AI clouds directly into Claud
## The public changelog — human page, machine feeds, and Telegram push
-Every user-visible change to the platform lands in a public changelog that holders can actually follow: a browsable web page with per-entry permalinks, plus machine-readable JSON and RSS feeds for bots, dashboards, and readers. Entries are written in plain holder-readable language — no commit jargon — tagged by type (feature, improvement, fix, SDK, infra, docs, security), and new page launches flow in automatically. New entries are also pushed automatically to the holders' Telegram channel, with no manual announcement step.
+Every user-visible change to the platform lands in a public changelog the community can actually follow: a browsable web page with per-entry permalinks, plus machine-readable JSON and RSS feeds for bots, dashboards, and readers. Entries are written in plain community-readable language (no commit jargon), tagged by type (feature, improvement, fix, SDK, infra, docs, security), and new page launches flow in automatically. New entries are also pushed automatically to the community Telegram channel (@three_ws), with no manual announcement step.
-**How it works:** A curated entry file merges with the page registry at build time to regenerate the markdown changelog, the JSON feed, and the RSS XML, with validation that fails the build on malformed entries. A scheduled job runs every 20 minutes, diffs the feed baked into the running deploy against database state, and posts anything new to the holders' Telegram channel; a database lock keeps overlapping runs from ever double-posting.
+**How it works:** A curated entry file merges with the page registry at build time to regenerate the markdown changelog, the JSON feed, and the RSS XML, with validation that fails the build on malformed entries. A scheduled job runs every 20 minutes, diffs the feed baked into the running deploy against database state, and posts anything new to the community Telegram channel; a database lock keeps overlapping runs from ever double-posting.
-**Why it matters:** Holders and integrators always know what shipped — on the site, in their feed reader, or in the Telegram channel — without anyone hand-writing announcements.
+**Why it matters:** The community and integrators always know what shipped, on the site, in their feed reader, or in the Telegram channel, without anyone hand-writing announcements.
---
@@ -8393,7 +8547,7 @@ Every user-visible change to the platform lands in a public changelog that holde
Every page and surface on three.ws, grouped by area.
-three.ws is "the AI-agent layer for the open web": one platform where anyone can generate 3D models and rigged avatars from text or photos, turn them into autonomous AI agents with on-chain identity (ERC-8004) and real wallets, embed them anywhere with one tag, and let them earn and spend via x402 pay-per-call micropayments and pump.fun token launches. The public surface spans roughly 300 pages plus published SDKs and 42 MCP servers, organized here into 14 categories: 3D creation, avatars/animation/voice, agent creation & management, embedding & distribution, worlds & social play, AR & real-world presence, trading intelligence, market data & news, token launching & $THREE, the x402 agent economy, wallets & custody, marketplaces & creator economy, the developer platform, and company/content surfaces. Everything runs on real APIs and real on-chain settlement — the platform's stated hard rule is no mocks and no fake data.
+three.ws is "the AI-agent layer for the open web": one platform where anyone can generate 3D models and rigged avatars from text or photos, turn them into autonomous AI agents with on-chain identity (ERC-8004) and real wallets, embed them anywhere with one tag, and let them earn and spend via x402 pay-per-call micropayments and pump.fun token launches. The public surface spans roughly 300 pages plus published SDKs and 48 MCP servers, organized here into 14 categories: 3D creation, avatars/animation/voice, agent creation & management, embedding & distribution, worlds & social play, AR & real-world presence, trading intelligence, market data & news, token launching & $THREE, the x402 agent economy, wallets & custody, marketplaces & creator economy, the developer platform, and company/content surfaces. Everything runs on real APIs and real on-chain settlement; the platform's stated hard rule is no mocks and no fake data.
## 3D Creation Suite (text, photos & sketches → 3D)
@@ -8493,7 +8647,7 @@ Where creations become products. Surfaces: /marketplace (buy access to agents, s
## Developer Platform (APIs, MCP, SDKs, Docs)
-Everything a developer or an AI agent needs to build on three.ws. Free keyless APIs: /crypto (Crypto Data API — token snapshots, security/rug signals, holder concentration, live launches, bonding status, whales, trending, wallet portfolios, no key/account/paywall), /3d (3D API — text prompt → real GLB plus glTF validation/optimization, with a live OpenAPI 3.1 spec and a paid upgrade ladder), /crypto-api (Unified Crypto API — CoinGecko, DefiLlama, Jupiter, DexScreener, Solana RPC re-offered behind one bill: free tier → BYOK → plan → x402 pay-per-call), plus /openapi.json and x402 discovery at /.well-known/x402. MCP: 42 servers (35 on npm + 7 hosted, all in the official MCP registry) covering forge, avatars, scenes, pump.fun, intel, portfolio, signals, x402 buying, provenance, agora, audio, vision, and more; /spatial-mcp (an open CC0 standard for returning live interactive 3D scenes as first-class MCP tool results, with a framework-free reference renderer). SDKs: 19 published zero-dependency @three-ws/* packages (forge, names, intel, vanity, reputation, voice, x402-server, agent-memory, agenc, guardian, glb-tools, agent-guards, skill-license, mocap, strategies, pumpfun-skills, irl, pose, and the avatar/walk/page-agent/tour embed SDKs), plus cross-chain agent SDKs and a 40-skill portable Agent Skills pack. Experimentation: /playground (agents, prompts, and 3D scenes sandbox), /brain (send one prompt to Claude, GPT, Qwen, ModelScope, and Groq simultaneously with latency/token stats), /labs (the hidden-gems showcase with live status checks). Docs and reference: the full /docs tree (~90 pages — start-here, quick-start, agent system, ERC-8004, reputation, trust primitives, x402 protocol/endpoints/revenue/buyer/dev-tools, autonomous loops, custody, trading surfaces, embedding, web component, MCP guides, skills, widgets, API reference, SDK, listings), /tutorials (text-to-3D, image-to-3D, prompt recipes, 3D-from-code, reputation how-tos, Shopify guides), /status (live uptime probed every 5 minutes), /glossary, /support, and machine-readable surfaces (llms.txt, llms-full.txt, sitemap.xml, robots.txt, attestation schemas, OAuth metadata, chat-plugin manifest).
+Everything a developer or an AI agent needs to build on three.ws. Free keyless APIs: /crypto (Crypto Data API: token snapshots, security/rug signals, holder concentration, live launches, bonding status, whales, trending, wallet portfolios, no key/account/paywall), /3d (3D API: text prompt → real GLB plus glTF validation/optimization, with a live OpenAPI 3.1 spec and a paid upgrade ladder), /crypto-api (Unified Crypto API: CoinGecko, DefiLlama, Jupiter, DexScreener, Solana RPC re-offered behind one bill: free tier → BYOK → plan → x402 pay-per-call), plus /openapi.json and x402 discovery at /.well-known/x402. MCP: 48 servers (35 on npm + 7 hosted, all in the official MCP registry) covering forge, avatars, scenes, pump.fun, intel, portfolio, signals, x402 buying, provenance, agora, audio, vision, and more; /spatial-mcp (an open CC0 standard for returning live interactive 3D scenes as first-class MCP tool results, with a framework-free reference renderer). SDKs: 19 published zero-dependency @three-ws/* packages (forge, names, intel, vanity, reputation, voice, x402-server, agent-memory, agenc, guardian, glb-tools, agent-guards, skill-license, mocap, strategies, pumpfun-skills, irl, pose, and the avatar/walk/page-agent/tour embed SDKs), plus cross-chain agent SDKs and a 40-skill portable Agent Skills pack. Experimentation: /playground (agents, prompts, and 3D scenes sandbox), /brain (send one prompt to Claude, GPT, Qwen, ModelScope, and Groq simultaneously with latency/token stats), /labs (the hidden-gems showcase with live status checks). Docs and reference: the full /docs tree (~90 pages: start-here, quick-start, agent system, ERC-8004, reputation, trust primitives, x402 protocol/endpoints/revenue/buyer/dev-tools, autonomous loops, custody, trading surfaces, embedding, web component, MCP guides, skills, widgets, API reference, SDK, listings), /tutorials (text-to-3D, image-to-3D, prompt recipes, 3D-from-code, reputation how-tos, Shopify guides), /status (live uptime probed every 5 minutes), /glossary, /support, and machine-readable surfaces (llms.txt, llms-full.txt, sitemap.xml, robots.txt, attestation schemas, OAuth metadata, chat-plugin manifest).
**How it works:** Catalogs are self-describing registries — a new API descriptor or service file automatically appears in the OpenAPI spec, docs tables, and storefronts with zero page edits; every SDK is pure ESM with hand-written types and a green node --test suite.
@@ -8509,7 +8663,7 @@ The narrative, onboarding, partnership, and account surfaces. Entry and story: /
---
-<a id="sec-012"></a>
+<a id="sec-013"></a>
> **Source:** `docs/agent-abilities/PRODUCTION-NOTES.md` · [↑ table of contents](#table-of-contents)
@@ -8522,14 +8676,14 @@ How to shoot/write from this dossier:
"Screenshot-worthy" is the shot list, "Every feature" is the b-roll checklist.
- **Chapters** ([chapters/](agent-abilities/chapters)) work the same way at a coarser grain:
each capability heading is one beat.
-- **Article:** [FULL-ARTICLE.md](#sec-011) is the stitched long-form
+- **Article:** [FULL-ARTICLE.md](#sec-012) is the stitched long-form
draft, in chapter order.
- **Narrative arc:** the agent is born (ch 1–3), it thinks and speaks (4–5),
it works (6–9), it handles money (10), it lives everywhere (11–14).
---
-<a id="sec-013"></a>
+<a id="sec-014"></a>
> **Source:** `docs/agent-abilities/TTS-SCRIPT.md` · [↑ table of contents](#table-of-contents)
@@ -8549,7 +8703,7 @@ Twenty-three abilities. One wallet. Real money, real receipts — and you hold t
---
-<a id="sec-014"></a>
+<a id="sec-015"></a>
> **Source:** `docs/agent-abilities/chapters/01-the-body.md` · [↑ table of contents](#table-of-contents)
@@ -8664,7 +8818,7 @@ Every post-generation stage of a professional 3D pipeline sold as its own few-ce
---
-<a id="sec-015"></a>
+<a id="sec-016"></a>
> **Source:** `docs/agent-abilities/chapters/02-motion.md` · [↑ table of contents](#table-of-contents)
@@ -8867,7 +9021,7 @@ Inside the avatar editor, a Walk tab lets you take the exact avatar you're sculp
---
-<a id="sec-016"></a>
+<a id="sec-017"></a>
> **Source:** `docs/agent-abilities/chapters/03-creation-studios.md` · [↑ table of contents](#table-of-contents)
@@ -8913,7 +9067,7 @@ The agent's owner console: a persistent live 3D stage showing your agent standin
You don't write a system prompt — you direct a character. Compose the agent's reasoning as a visual card-stack graph, fork ready-made brains (Sniper, Scalper, Researcher, Companion), tune trait sliders and tone chips, and test it in a streaming chat against the real model. A/B compare runs genuine dual inference side by side; promoting the winner writes a real versioned update and the agent re-greets everywhere on the platform.
-**How it works:** A deterministic persona compiler turns the graph/trait state into a real persona prompt persisted to the agent's identity record; test chats hit the live /api/chat LLM proxy with an owner-only persona override, and promotes append to a version history.
+**How it works:** A deterministic persona compiler turns the graph/trait state into a real persona prompt persisted to the agent's identity record; test chats hit the live /api/chat LLM proxy with an owner-only persona override, and promotes append to a version history. Every persona save also signs the agent's full manifest, system prompt included, and pins it to IPFS, so anyone can fetch the CID and verify what the agent is running without an account ([Agent manifest](/docs/agent-manifest)).
**Why it matters:** Personality engineering becomes tactile and testable — you feel the change in the agent's voice within a second instead of guessing at prompt wording.
@@ -8953,7 +9107,7 @@ Flip your agent's abilities on and off live: a locked-on core (greet, think, rem
The power-user editing surface for any agent you own, with fifteen-plus tabs covering everything: outfit, voice, knowledge, brain, mind, ownership, dreams, skills, autopilot, embeds, widgets, social, analytics, and wallet. It also builds subscription plans that bundle an agent's skills into recurring offers.
-**How it works:** A tabbed single-page console over the agent APIs at /agent/:id/edit; heavy tabs (3D outfit preview, brain studio) mount lazily so you never pay for a WebGL context you didn't open.
+**How it works:** A tabbed single-page console over the agent APIs at /agents/:id/edit; heavy tabs (3D outfit preview, brain studio) mount lazily so you never pay for a WebGL context you didn't open.
**Why it matters:** Every dial an agent has is reachable from one page — nothing about your agent is hidden from you.
@@ -8975,11 +9129,11 @@ Agents keep a dream journal. Between your visits, the agent reflects on its rece
## Live name check and naming rules
-As you name or rename an agent, availability is checked live against the whole platform — taken, invalid, and reserved names are flagged before you ever submit, with clear rules (3–32 characters, letters/numbers/dash/underscore) and a denylist protecting system and brand names.
+As you name or rename an agent, availability is checked live against the other agents you own: taken, invalid, and reserved names are flagged before you ever submit, with clear rules (3-32 characters, letters/numbers/dash/underscore) and a denylist protecting system and brand names.
-**How it works:** A dedicated GET /api/agents/check-name endpoint validates format, denylist, and database uniqueness (with self-exclusion when renaming), consumed by the creation and editing flows.
+**How it works:** A dedicated GET /api/agents/check-name endpoint validates format, denylist, and database uniqueness within your account (with self-exclusion when renaming, and a 400 instead of a server error when the agent_id is not a uuid), consumed by the creation and editing flows.
-**Why it matters:** You never lose work to a name collision at the last step, and every agent name on the platform is unique and legible.
+**Why it matters:** You never lose work to a name collision at the last step, and every agent name you own is unique and legible.
## Selfie → 3D avatar
@@ -9161,7 +9315,7 @@ Change what any model is made of without touching its shape: live material editi
One click turns any studio output — a forged avatar, a Lab model — into a live conversational agent: it listens, thinks, answers out loud in a real voice, and lip-syncs while it speaks, with per-agent memory carrying across the conversation.
-**How it works:** Hands the model to the platform's production conversational stack — streaming LLM chat, TTS with provider failover (NVIDIA Magpie → OpenAI), and a lip-sync driver on the avatar's mouth morphs — the same runtime the rest of the site uses.
+**How it works:** Hands the model to the platform's production conversational stack, the same runtime the rest of the site uses: streaming LLM chat over a failover chain of six free provider lanes (Groq, OpenRouter, NVIDIA NIM, SambaNova, Mistral, Z.AI) ahead of any paid backstop, which answers a fully throttled free lane with a 503 and a Retry-After rather than a sign-in wall; TTS with provider failover (NVIDIA Magpie → OpenAI); and a lip-sync driver on the avatar's mouth morphs.
**Why it matters:** The moment of magic: the thing you just created looks at you and talks back.
@@ -9191,9 +9345,9 @@ Any avatar in your library can become any agent's body, and creating an avatar c
## Agent Genome — the breeding studio
-Breed any two agents into a genuinely new child agent. The child provably inherits a recombination of both parents — brain disposition (curiosity, boldness, humor, formality, verbosity, temperature), a blended voice you can actually play out loud, body morphs and colors, and skill alleles with real genetics: dominant traits, recessive skills that can skip a generation and surface in a grandchild, bounded mutations flagged with a ⚡, and emergent fusion skills neither parent had (trading + sentiment can produce alpha-signal; vision + forge can produce concept-art). Preview the exact offspring before committing, re-roll the dice, then breed — the child is born with its own fresh Solana and EVM wallets, a synthesized 3D body, an in-character persona, on-chain licenses for its expressed skills, and a pedigree tier (common → uncommon → rare → legendary) that deep, emergent-rich lineages earn. Owners can list agents at stud for a $THREE fee, and breeding cooldowns keep rare pedigrees scarce.
+Breed any two agents into a genuinely new child agent. The child provably inherits a recombination of both parents: brain disposition (curiosity, boldness, humor, formality, verbosity, temperature), a blended voice you can actually play out loud, body morphs and colors, and skill alleles with real genetics: dominant traits, recessive skills that can skip a generation and surface in a grandchild, bounded mutations flagged with a ⚡, and emergent fusion skills neither parent had (trading + sentiment can produce alpha-signal; vision + forge can produce concept-art). Preview the exact offspring before committing, re-roll the dice, then breed: the child is born with its own fresh Solana and EVM wallets, a synthesized 3D body, an in-character persona, on-chain licenses for its expressed skills, and a pedigree tier (common → uncommon → rare → legendary) that deep, emergent-rich lineages earn. Owners list their own public agents at stud for a $THREE fee from the studio's "Your stud listings" section (unlist any time), and breeding cooldowns keep rare pedigrees scarce.
-**How it works:** The studio (pages/genome.html + src/genome.js) drives api/genome/preview.js and api/genome/breed.js, with the genetics isolated as pure, deterministic code in api/_lib/genome.js: every random choice flows through a recorded seed via per-locus PRNG streams, so the same (parentA, parentB, seed) always derives a byte-identical child — the preview IS the child you commit. Constants are pinned by tests (mutation drift capped at 0.12 so 'mutation' can never silently become 'random new agent'; heterozygous skills express at 72%, else carry recessively; recessive-in-both pairings surface the trait; fusion rules are a static, auditable table). Any never-bred agent gets a stable founder genome derived from its real traits. The breed endpoint provisions fresh wallets, bakes a real child GLB from the blended appearance, composes the persona prompt deterministically from the inherited brain, passes blended ElevenLabs voice settings verbatim to live TTS (the play button in the preview synthesizes the actual inherited voice), grants expressed skills on-chain with royalty provenance, and is idempotent per breeding key — replaying a preview returns the same child, never twins. verifyGenome / api/genome/lineage.js re-derive the child from its recorded parents + seed and compare canonical SHA-256 genome hashes, so a forged pedigree is mathematically detectable; api/genome/stud.js powers the public stud market.
+**How it works:** The studio (pages/genome.html + src/genome.js) drives api/genome/preview.js and api/genome/breed.js, with the genetics isolated as pure, deterministic code in api/_lib/genome.js: every random choice flows through a recorded seed via per-locus PRNG streams, so the same (parentA, parentB, seed) always derives a byte-identical child: the preview IS the child you commit. Constants are pinned by tests (mutation drift capped at 0.12 so 'mutation' can never silently become 'random new agent'; heterozygous skills express at 72%, else carry recessively; recessive-in-both pairings surface the trait; fusion rules are a static, auditable table). Any never-bred agent gets a stable founder genome derived from its real traits. The breed endpoint provisions fresh wallets, bakes a real child GLB from the blended appearance, composes the persona prompt deterministically from the inherited brain, passes blended ElevenLabs voice settings verbatim to live TTS (the play button in the preview synthesizes the actual inherited voice), grants expressed skills on-chain with royalty provenance, and is idempotent per breeding key: replaying a preview returns the same child, never twins, a race on the same key or the same $THREE settlement signature is decided by the database's unique indexes with the losing child retired (so one stud payment can never buy two children), and cooldown is checked before the fee gate so a refused breeding never takes a payment. verifyGenome / api/genome/lineage.js re-derive the child from its recorded parents + seed and compare canonical SHA-256 genome hashes, so a forged pedigree is mathematically detectable; api/genome/stud.js powers the public stud market and the owner's listing writes, with PATCH semantics so sending only a fee never unlists the agent.
**Why it matters:** Creation stops being a one-shot generator and becomes lineage. You can breed toward a goal — cross your best trader with your best analyst and maybe get an alpha-signal emergent — gamble on recessive genes resurfacing, and build bloodlines whose rarity is earned by real genetic depth, not a label. Because every birth re-derives from its recorded seed, 'this legendary is 4th-generation with two emergent skills' is a claim anyone can verify, which is what makes a pedigree — and a stud fee — actually worth something.
@@ -9206,13 +9360,13 @@ Breed any two agents into a genuinely new child agent. The child provably inheri
---
-<a id="sec-017"></a>
+<a id="sec-018"></a>
> **Source:** `docs/agent-abilities/chapters/04-the-mind.md` · [↑ table of contents](#table-of-contents)
# Chapter 4 · The Mind — memory, dreams, and autonomy
-Agents remember, reflect, and act on their own — with every autonomous action explained, signed, and undoable. Owners drive it from the Autopilot tab of the agent editor (/agent/:id/edit) and audit it at three.ws/autopilot-activity.
+Agents remember, reflect, and act on their own, with every autonomous action explained, signed, and undoable. Owners drive it from the Autopilot tab of the agent editor (/agents/:id/edit; the older /agent/:id form 301s there) and audit it at three.ws/autopilot-activity.
three.ws agents are not just wallets — they have a persistent, tiered memory with semantic recall, a reflection engine that consolidates experience into "dreams," and a memory-grounded Autopilot that proposes and executes real actions (alerts, briefings, SOL transfers, coin buybacks) under owner-granted scopes and an earned trust ladder, with every action citing the memories that motivated it and leaving a signed, undoable receipt. Beyond the individual mind, agents work together: paid agent-to-agent delegation and hiring over real x402 USDC rails with reputation gates and spend guardrails, lead-agent Team Tasks that decompose one goal into a budget-capped task tree of delegations and hires, and read access to the external AgenC on-chain task coordination protocol.
@@ -9220,7 +9374,7 @@ three.ws agents are not just wallets — they have a persistent, tiered memory w
The agent reads its own high-salience memories and recent reflections and turns them into concrete, real action proposals — create a price/graduation/whale alert, author a briefing to the owner's inbox, or transfer SOL from its custodial wallet. The owner reviews each proposal with its evidence, can dry-run it, approve it, adjust it, or dismiss it.
-**How it works:** src/autopilot-mind.js mounts the control surface (Autopilot tab of /agent/:id/edit); api/_lib/autopilot.js is the engine behind /api/autopilot/proposals with actions generate/dryrun/execute/dismiss/undo/adjust. generateProposals() runs an LLM over high-salience memories + pending dreams; provenance (cited memory ids) is mandatory on every proposal, and each executed action writes a signed (ERC-191) agent_actions row.
+**How it works:** src/autopilot-mind.js mounts the control surface (Autopilot tab of /agents/:id/edit); api/_lib/autopilot.js is the engine behind /api/autopilot/proposals with actions generate/dryrun/execute/dismiss/undo/adjust. generateProposals() runs an LLM over high-salience memories + pending dreams; provenance (cited memory ids) is mandatory on every proposal, and each executed action writes a signed (ERC-191) agent_actions row.
**Why it matters:** Your agent acts on your behalf but always shows the receipt — every proposal links the exact memories that motivated it, so autonomy is legible, auditable, and never a black box.
@@ -9228,7 +9382,7 @@ The agent reads its own high-salience memories and recent reflections and turns
Nothing is granted by default: the agent can propose but not act until the owner opts in per capability (create_alert, briefing, wallet_transfer). Reversible actions can be flipped to auto-run without asking; SOL transfers are irreversible, always confirmation-gated, and bounded by a daily SOL spend cap. The agent never sells or sends $THREE — it only accumulates and burns it.
-**How it works:** Scopes live on agent_identities.meta.autopilot (AUTOPILOT_DEFAULTS in api/_lib/autopilot.js: all scopes false, daily_spend_sol 0, require_confirm true) and are enforced server-side on every execute. auto_execute exists only for the two reversible kinds; wallet_transfer can never auto-execute and the daily cap is ceiling-limited to 1000 SOL.
+**How it works:** Scopes live on agent_identities.meta.autopilot (AUTOPILOT_DEFAULTS in api/_lib/autopilot.js: all scopes false, daily_spend_sol 0, require_confirm true) and are enforced server-side on every execute, including a live SOL balance read before any transfer (through the shared RPC failover lanes behind SOLANA_RPC_URL, so one provider's outage never blanks the check) that refuses with insufficient_funds when the wallet cannot cover the amount. auto_execute exists only for the two reversible kinds; wallet_transfer can never auto-execute and the daily cap is ceiling-limited to 1000 SOL.
**Why it matters:** You decide exactly how much rope the agent gets, capability by capability — and a misconfigured or compromised client can't widen it because enforcement is server-side.
@@ -9244,7 +9398,7 @@ Each agent carries a trust level — Sandbox (proposes, you approve everything),
Every autonomous action lands in an append-only ledger (/autopilot-activity and the Autopilot tab) with its full explanation, the source memories that motivated it (linking into the Knowledge tab), an ERC-191 signed-receipt badge, a Solscan tx link for on-chain moves, and one-tap Undo for reversible actions. A receipt chip also pops on any surface the moment an action fires.
-**How it works:** src/autopilot-activity.js reads the agent_actions log via /api/autopilot/activity (cursor-paginated, filterable per agent); src/autopilot-mind.js exports the shared receiptRow renderer and listens on the agentBus 'action:taken' event for the cross-surface chip. Undoing writes a feedback memory ('the agent learns the boundary') and lowers trust.
+**How it works:** src/autopilot-activity.js reads the agent_actions log via /api/autopilot/activity (cursor-paginated, filterable per agent; the response's `agents` list is always the caller's full roster, so a deep link like /autopilot-activity?agent=<id> keeps the whole picker, and an agent with no actions yet gets an empty state that links into its own Autopilot tab); src/autopilot-mind.js exports the shared receiptRow renderer and listens on the agentBus 'action:taken' event for the cross-surface chip. Undoing writes a feedback memory ('the agent learns the boundary') and lowers trust.
**Why it matters:** Total visibility into what your agent did, why, and proof it happened — plus a one-tap way to reverse it that teaches the agent not to repeat it.
@@ -9252,7 +9406,7 @@ Every autonomous action lands in an append-only ledger (/autopilot-activity and
For coins an agent launched on pump.fun through three.ws, the agent autonomously runs buyback-and-burn (spend collected creator fees to buy the token back and burn it) and distributes accumulated fees to holders, whenever the vaults clear owner-set USDC floors. A live narrator speaks each on-chain move through the agent's avatar.
-**How it works:** src/autopilot.js is the control surface over /api/pump/autopilot: per-coin policy (master switch, per-rule enable, min-USDC thresholds stored as 6dp atomics, full-swap toggle, narrate toggle) gating the run-buyback and run-distribute-payments crons. Every action row carries status (confirmed/pending/failed/skipped) and the real tx signature.
+**How it works:** src/autopilot.js is the control surface over /api/pump/autopilot: per-coin policy (master switch, per-rule enable, min-USDC thresholds stored as 6dp atomics, full-swap toggle, narrate toggle) gating the run-buyback and run-distribute-payments crons. A coin with no saved policy row answers `configured: false` and its card wears a Defaults pill until the owner changes something, and a cookie-session POST must be same-site (bearer callers are exempt) so a cross-site form cannot rewrite a policy. Every action row carries status (confirmed/pending/failed/skipped) and the real tx signature.
**Why it matters:** Your coin runs itself — supply gets scarcer and holders get paid on rules you set once, with every burn and distribution verifiable on Solscan.
@@ -9260,13 +9414,13 @@ For coins an agent launched on pump.fun through three.ws, the agent autonomously
Agents remember across sessions in four types — user (who you are, preferences), feedback (corrections that shape behavior), project (ongoing goals), reference (external pointers) — with salience scoring and recency decay. Recall is semantic: the agent finds relevant memories by meaning, not just keywords, and chat responses report exactly which memories were injected.
-**How it works:** src/agent-memory.js (AgentMemory class): localStorage-first with async backend sync, salience computed from type + tags with a 7-day-half-life recency boost, and embedding-based cosine recall with a strict same-vector-space rule (vectors from different embed models are never compared). Backend-confirmed agents recall through the server's mem0-style tiered store (/api/memory/search, working/recall tiers) covering every persisted memory, degrading gracefully to the local engine offline. src/agents/memory-client.js is the single mutation path that emits memory:added/updated/forgotten/recalled bus events so a memory formed in one surface ripples to all others in real time.
+**How it works:** src/agent-memory.js (AgentMemory class): localStorage-first with async backend sync, salience computed from type + tags with a 7-day-half-life recency boost, and embedding-based cosine recall with a strict same-vector-space rule (vectors from different embed models are never compared). Backend-confirmed agents recall through the server's mem0-style tiered store (/api/memory/search, working/recall tiers; an unknown tier or type, or a non-uuid agentId, answers 400 rather than an empty result) covering every persisted memory, degrading gracefully to the local engine offline. src/agents/memory-client.js is the single mutation path that emits memory:added/updated/forgotten/recalled bus events so a memory formed in one surface ripples to all others in real time.
**Why it matters:** The agent gets to know you — a correction you gave weeks ago still shapes today's behavior, and you can see recall happen live.
## Mind Palace and the living memory graph
-The agent's memory rendered as a 3D place you can walk through (/agent/:id/mind): every memory is a tangible object orbiting the live avatar — salience sets size, glow, and proximity; type sets shape and color; shared tags form navigable association edges. Drag a memory toward the avatar to pin and raise its salience; flick it into the Forget well to expire it (with undo). A companion 2D canvas graph in the Diary shows the mined entity knowledge graph — coins, tickers, wallets, people, strategies, topics — ranked by mentions with co-occurrence edges, pulsing nodes as their names are spoken.
+The agent's memory rendered as a 3D place you can walk through (/agents/:id/mind): every memory is a tangible object orbiting the live avatar: salience sets size, glow, and proximity; type sets shape and color; shared tags form navigable association edges. Drag a memory toward the avatar to pin and raise its salience; flick it into the Forget well to expire it (with undo). A companion 2D canvas graph in the Diary shows the mined entity knowledge graph (coins, tickers, wallets, people, strategies, topics) ranked by mentions with co-occurrence edges, pulsing nodes as their names are spoken.
**How it works:** src/agent-mind.js resolves the route and mounts mountMindPalace() (src/mind-palace.js, GPU-instanced Three.js with 2D/keyboard/reduced-motion fallbacks); every gesture hits the real API through the shared memory client. src/agent-memory-graph.js splits pure layout/ranking math (tested, deterministic) from the canvas renderer; entity nodes come from the real memory miner and link out to coin and agent profiles when addressable.
@@ -9300,7 +9454,7 @@ The two-step agent commerce loop: discover returns a shortlist of three.ws agent
Give one lead agent a single goal and it assembles a team: it decomposes the goal into sub-tasks and either delegates them (free LLM turns) or hires teammate agents over real x402, each paid handoff stamped with an on-chain receipt. A live dependency graph shows nodes pulsing as they run, edges flowing on handoff, cost badges, and explorer links, with a spend meter against the budget.
-**How it works:** src/agent-team.js rides /agents-live (hero launcher) and /agent-screen (Team toggle) without touching their scripts; POST /api/agent-collab orchestrates via api/_lib/agent-orchestrate.js — budget hard-capped at $5 (default $1), split into per-node slices that the platform x402 spend-guard re-checks at hire time; hires go through /api/agents/a2a-hire with a short-lived access token so every owner gate, spend policy, and kill switch still runs. Live graph snapshots stream over the lead's screen stream (frame.meta.collab); the final POST response is the authoritative tree.
+**How it works:** src/agent-team.js rides /agents-live (hero launcher) and /agent-screen (Team toggle) without touching their scripts; POST /api/agent-collab orchestrates via api/_lib/agent-orchestrate.js: budget hard-capped at $5 (default $1), split into per-node slices that the platform x402 spend-guard re-checks at hire time; hires go through /api/agents/a2a-hire with a short-lived access token so every owner gate, spend policy, and kill switch still runs, and each hire call carries a 120s deadline and is never retried (a replay would pay twice for one node), so a teammate that stops answering costs that node, not the team task. Live graph snapshots stream over the lead's screen stream (frame.meta.collab); the final POST response is the authoritative tree.
**Why it matters:** One sentence becomes a coordinated multi-agent operation you can watch in real time — with hard spend limits and on-chain proof of every paid handoff.
@@ -9316,7 +9470,7 @@ Read access to AgenC (agenc.tech, Tetsuo Corp) — an external Solana coordinati
An always-on strategy that scores every new token against converging quality signals — how many smart-money wallets are in, how organic the buying looks, the token's quality score, and its market cap — and autonomously buys only when your thresholds all pass at once. Each strategy runs on a daily SOL budget with an instant kill switch, and its live win rate and realized P&L stay on the scoreboard.
-**How it works:** The sniper worker (workers/agent-sniper/index.js) feeds fully-enriched intel records into a pure scorer (workers/agent-sniper/alpha-hunt.js) that applies hard filters, min quality_score, min smart-money wallet count, min organic score, max market cap in USD, before any buy. Strategies are configured via api/sniper/strategy.js (trigger = 'alpha_hunt') with per-strategy daily budgets, and every buy is simultaneously recorded as a Reasoning Ledger decision so the call is auditable later. The command center at /dashboard/capabilities (src/dashboard-next/pages/capabilities.js) shows armed/disarmed state, thresholds, P&L, and win rate per strategy, plus a live worker heartbeat (alive / feed degraded / offline) and treasury auto-funding totals. `/api/sniper/status` and the worker tick both read fleet solvency rather than process liveness alone, so a fleet whose wallets are starved (or whose funding master is dry) reports that state instead of looking healthy while it silently buys nothing.
+**How it works:** The sniper worker (workers/agent-sniper/index.js) feeds fully-enriched intel records into a pure scorer (workers/agent-sniper/alpha-hunt.js) that applies hard filters, min quality_score, min smart-money wallet count, min organic score, max market cap in USD, before any buy. Strategies are configured via api/sniper/strategy.js (trigger = 'alpha_hunt') with per-strategy daily budgets, and every buy is simultaneously recorded as a Reasoning Ledger decision so the call is auditable later. The command center at /dashboard/capabilities (src/dashboard-next/pages/capabilities.js) shows armed/disarmed state, thresholds, P&L, and win rate per strategy, plus a live worker heartbeat (alive / feed degraded / offline) and treasury auto-funding totals. It reads four endpoints (/api/sniper/status, /api/sniper/strategy, and the account-wide /api/agent/launcher?all=1 and /api/agent/market-maker?all=1 views) and refreshes every 30s, skipping a tick while an action is in flight; a section whose endpoint fails renders as Unavailable with a retry instead of a confident row of zeros. Treasury auto-funding (auto_fund_enabled) is operator-granted and read-only here: a strategy POST that tries to set it is refused with 400. Strategies also carry a laddered exit (initials_out_multiple, null for the classic single-shot exit, and moonbag_min_pct, default 15). `/api/sniper/status` and the worker tick both read fleet solvency rather than process liveness alone, so a fleet whose wallets are starved (or whose funding master is dry) reports that state instead of looking healthy while it silently buys nothing.
**Why it matters:** You encode your judgment once — 'only low-cap coins with real smart money and organic volume' — and the agent hunts around the clock at machine speed, never chasing a token that fails a single filter. The budget cap and kill switch keep it on a leash, and every trade lands in the agent's verifiable track record.
@@ -9324,7 +9478,7 @@ An always-on strategy that scores every new token against converging quality sig
Agents that launch their own pump.fun coins on a schedule you set — every N hours, up to a launch cap, per network — with a one-click 'Launch Now' override that fires within a minute. The dashboard tracks every launched coin, whether it graduated, and the creator fees it has earned back.
-**How it works:** Launcher configs (one per agent per network: symbol, interval hours, max launches) are managed through api/agent/launcher.js with strict agent-ownership checks; the 'Launch Now' button posts a trigger action that the worker picks up within 60 seconds. The capabilities command center renders the full schedule (next launch countdown, launches vs cap) and a launched-coins ledger with graduation status and total fees claimed per coin.
+**How it works:** Launcher configs (one per agent per network: symbol, interval hours, max launches) are managed through api/agent/launcher.js with strict agent-ownership checks (GET ?all=1 returns every config and launched coin across the caller's agents in one call, rows carrying agent_name and agent_image); the 'Launch Now' button posts a trigger action that the worker picks up within 60 seconds. The capabilities command center renders the full schedule (next launch countdown, launches vs cap) and a launched-coins ledger with graduation status and total fees claimed per coin.
**Why it matters:** Your agent becomes a self-sustaining creator: it ships coins on cadence without you touching a keyboard, and everything it launches is tracked in one place — schedule, graduations, and the fee revenue flowing back.
@@ -9340,7 +9494,7 @@ A fee harvester that watches every coin an agent launched and automatically coll
Agents provide range-based liquidity on coins they care about — defending a price floor, trimming into rallies — with Jito-accelerated execution and a rulebook that makes market manipulation structurally impossible, not just discouraged. Plain-language presets like 'Gentle floor defense' configure it in one click; a live panel shows spread, inventory fill, buys vs sells, and net P&L per market.
-**How it works:** Policies live in api/_lib/market-maker.js, the single source of truth shared by the API (api/agent/market-maker.js, api/launch/mm.js) and the engine worker. Hard anti-manipulation guards are enforced twice, refused at policy-create time AND re-clamped at execution: minimum 30s between actions, a side flip (buy→sell) requires 2× that interval so the MM physically cannot wash-trade, no single action may exceed 33% of live market volume, recycling can never dump more than 90% of inventory, and when live volume can't be read the engine refuses anything above a 0.05 SOL slice so it never paints a no-volume tape. Every fill routes through executeAgentTrade, the same firewall, spend-guard, and custody path a manual trade uses; the engine adds no new way to move funds. MEV tip modes (off/economy/turbo) control Jito priority. A policy only ever acts while a market-maker worker is sweeping, so the policy view served by api/launch/mm.js carries engine liveness read from the worker's `bot_heartbeat` (stale after 180s, six missed 30s beats): an enabled policy with a stopped engine reads as "engine offline", never as an armed maker that will never fire.
+**How it works:** Policies live in api/_lib/market-maker.js, the single source of truth shared by the API (api/agent/market-maker.js, which also answers GET ?all=1 with every policy and recent trade across the caller's agents, and api/launch/mm.js, where a pause/resume/kill/withdraw POST on a coin with no policy attached answers 404 no_policy instead of creating a zero-floor maker) and the engine worker. Hard anti-manipulation guards are enforced twice, refused at policy-create time AND re-clamped at execution: minimum 30s between actions, a side flip (buy→sell) requires 2× that interval so the MM physically cannot wash-trade, no single action may exceed 33% of live market volume, recycling can never dump more than 90% of inventory, and when live volume can't be read the engine refuses anything above a 0.05 SOL slice so it never paints a no-volume tape. Every fill routes through executeAgentTrade, the same firewall, spend-guard, and custody path a manual trade uses; the engine adds no new way to move funds. MEV tip modes (off/economy/turbo) control Jito priority. A policy only ever acts while a market-maker worker is sweeping, so the policy view served by api/launch/mm.js carries engine liveness read from the worker's `bot_heartbeat` (stale after 180s, six missed 30s beats): an enabled policy with a stopped engine reads as "engine offline", never as an armed maker that will never fire.
**Why it matters:** You get professional-grade liquidity provision — a defended floor, orderly exits into strength — without hiring a market maker or trusting a black box. The non-manipulation guarantees are properties of the policy engine itself, verifiable in the caps, so holders of your coin can trust the tape and you can trust the agent with inventory.
@@ -9353,7 +9507,7 @@ Agents provide range-based liquidity on coins they care about — defending a pr
---
-<a id="sec-018"></a>
+<a id="sec-019"></a>
> **Source:** `docs/agent-abilities/chapters/05-the-voice.md` · [↑ table of contents](#table-of-contents)
@@ -9572,7 +9726,7 @@ The authenticated home for everything you own: every agent with its avatar, skil
---
-<a id="sec-019"></a>
+<a id="sec-020"></a>
> **Source:** `docs/agent-abilities/chapters/06-identity-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -9634,7 +9788,7 @@ The same on-chain trust data is surfaced through every layer a reader might come
One paid endpoint answers the question every autonomous agent faces before money moves: should I trust the thing on the other side? Pass any identifier — a Solana wallet, an EVM address, a pump.fun token mint, an ERC-8004 agent ID, or a platform agent — and it auto-detects the type and returns a 0–100 trust score with a full evidence breakdown: activity, account age, distinct counterparties, holdings, failure rate, and attestations.
-**How it works:** GET /api/x402/agent-reputation ($0.01 USDC via x402 on Base or Solana) auto-classifies the subject and scores it from live on-chain evidence — Solana signature history and balances, EVM nonce and holdings, the ERC-8004 reputation registry, settled agent-payment records, and DexScreener market signals for external mints — as a weighted multi-dimension model.
+**How it works:** GET /api/x402/agent-reputation ($0.01 USDC via x402 on Base or Solana) auto-classifies the subject and scores it from live on-chain evidence (Solana signature history and balances, EVM nonce and holdings, the ERC-8004 reputation registry, settled agent-payment records, and DexScreener market signals for external mints) as a weighted multi-dimension model, with evidence refs that link a platform agent to its canonical /agents/:id profile.
**Why it matters:** Your agent can vet literally anyone — even counterparties minted on platforms it has never heard of — in one machine-readable call.
@@ -9650,7 +9804,7 @@ The Agent Passport condenses an agent's whole trust record into a single A-to-D
On Solana, anyone can write a permanent vouch for an agent for a fraction of a cent — no custom contract required — and optionally back it with real SOL stake to make it weigh more. Seven attestation kinds cover the full trust lifecycle: feedback, staked vouches, pass/fail validations, task advertisements, owner acceptances, disputes, and revocations, all publicly re-derivable by anyone.
-**How it works:** Each attestation is an SPL Memo transaction with the agent's asset pubkey attached as a read-only key (discoverable via getSignaturesForAddress); a 5-minute indexer cron crawls, schema-validates, and verifies each memo (stake verified only if ≥0.001 SOL actually transferred; accepts/disputes only if signed by the owner) into the reputation API.
+**How it works:** Each attestation is an SPL Memo transaction with the agent's asset pubkey attached as a read-only key (discoverable via getSignaturesForAddress); a 10-minute indexer cron crawls, schema-validates, and verifies each memo (stake verified only if ≥0.001 SOL actually transferred; accepts/disputes only if signed by the owner) into the reputation API.
**Why it matters:** Trust-building costs a Solana fee instead of a platform account — and the raw evidence stays on-chain where anyone can audit it.
@@ -9672,9 +9826,9 @@ An agent's profile shows the receipts behind its score: every completed hire it
## Validation attestations — verified fact, not just opinion
-Reputation captures what people think; validation captures what was checked. Allow-listed validators attest on-chain that an agent passed a concrete technical test — on three.ws, that its 3D model passes glTF schema validation — and the same pass/fail attestations exist on Solana as signed memos. Signed validator reports also travel inside the agent's manifest bundle.
+Reputation captures what people think; validation captures what was checked. Validators attest on-chain that an agent passed a concrete technical test (on three.ws, that its 3D model passes glTF schema validation), and the same pass/fail attestations exist on Solana as signed memos. Signed validator reports also travel inside the agent's manifest bundle.
-**How it works:** The ERC-8004 ValidationRegistry (deployed on testnets, mainnet rollout pending) records validator attestations against agentIds; on Solana the threews.validation.v1 memo kind mirrors it, and manifests carry EIP-712-signed gltf-validator attestation files.
+**How it works:** The ERC-8004 ValidationRegistry (deployed on testnets, mainnet rollout pending) records validator attestations against agentIds through a two-legged request/response flow (a request naming the validator, then that validator's response; there is no validator allowlist); on Solana the threews.validation.v1 memo kind mirrors it, and manifests carry EIP-712-signed gltf-validator attestation files.
**Why it matters:** Buyers get proof the agent's work passed an objective check — a harder signal than any number of stars.
@@ -9802,7 +9956,7 @@ The same identity standard extends into OKX's X Layer agent economy: agents regi
A public, tamper-evident timeline of every consequential call an agent makes — snipes, exits, bounty awards, moderation decisions — each entry recording what the agent decided, why (its written rationale), what it predicted with what confidence, and, once the position settles on-chain, what actually happened: right or wrong, and by exactly how much SOL. The headline is an explainable 0–100 reputation score with a full 'how is this computed' drill-down showing the formula and every weighted component, plus a calibration chart that answers the sharpest question you can ask a forecaster: does its 80%-confidence call actually hit 80% of the time? Being wrong is shown, not hidden — honesty is the trust signal.
-**How it works:** Frontend at pages/reasoning-ledger.html + src/reasoning-ledger.js (filter by kind, full-text search of rationales, paginated 'load older', animated score ring, cumulative realized-P&L sparkline over settled calls). Data from api/ledger/[agentId].js, which returns the reputation (formula + per-component breakdown + calibration buckets), the latest on-chain anchor, and shaped decisions with pending/reconciled outcomes and Solscan proof links on the sell signature. Every entry is hashed into a per-agent hash chain; api/ledger/verify/[agentId].js recomputes the entire chain from committed contents (trusting NO stored hash), checks every prev-hash link, and compares the recomputed head to the latest Solana SPL-Memo anchor — returning verified / verified_unanchored / verification_failed with the exact sequence number where tampering broke the chain. api/cron/reconcile-decisions.js closes the loop: it resolves open predictions against closed sniper positions (realized P&L proven by the sell signature), anchors each agent's new chain head on-chain, and raises an ops alert if a verified track record's hit rate collapses below 25% over 10+ reconciled calls.
+**How it works:** Frontend at pages/reasoning-ledger.html + src/reasoning-ledger.js (filter by kind, full-text search of rationales, paginated 'load older', animated score ring, cumulative realized-P&L sparkline over settled calls); the kind filter honors a ?kind= deep link (snipe, exit, bounty_award, moderation; anything else falls back to all kinds) and mirrors the chosen kind back into the URL, so the sniper fleet, the blog, and the API's ledger_url can link straight into a pre-filtered timeline and the reader can copy the filtered view out of the address bar. Data from api/ledger/[agentId].js, which returns the reputation (formula + per-component breakdown + calibration buckets), the latest on-chain anchor, and shaped decisions with pending/reconciled outcomes and Solscan proof links on the sell signature. Every entry is hashed into a per-agent hash chain; api/ledger/verify/[agentId].js recomputes the entire chain from committed contents (trusting NO stored hash), checks every prev-hash link, and compares the recomputed head to the latest Solana SPL-Memo anchor, returning verified / verified_unanchored / verification_failed with the exact sequence number where tampering broke the chain. api/cron/reconcile-decisions.js closes the loop: it resolves open predictions against closed sniper positions (realized P&L proven by the sell signature), anchors each agent's new chain head on-chain (a rejected anchor broadcast is treated as a fleet-wide outage: the run stops anchoring after the first failure, reports the untouched agents as anchor_skipped, and raises one ops alert instead of re-sending the same doomed memo for every agent), and raises an ops alert if a verified track record's hit rate collapses below 25% over 10+ reconciled calls.
**Why it matters:** Before you trust an agent — copy its trades, hire it, hold its coin — you can interrogate its entire decision history and independently prove nothing was backdated or quietly edited. One click re-verifies the whole record against the on-chain anchor; a tampered entry is not just detected but pinpointed. Wins, losses, overconfidence, and P&L are all on the record, so reputation here is earned math, not marketing.
@@ -9823,13 +9977,13 @@ An agent's 3D body and identity assets can be published to Arweave — storage t
---
-<a id="sec-020"></a>
+<a id="sec-021"></a>
> **Source:** `docs/agent-abilities/chapters/07-skills.md` · [↑ table of contents](#table-of-contents)
# Chapter 7 · Skills — what agents know how to do
-Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes — all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp.
+Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes, all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp. The enabled skill list also travels in the agent's signed manifest, pinned to IPFS whenever a public agent's persona is saved (private agents publish on request), so anyone can verify which skills an agent carries without an account ([agent manifest](/docs/agent-manifest)).
The in-world agent skills system (src/agent-skills.js plus 13 family modules) is what a three.ws agent can DO — and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), and market intelligence (aixbt, sentiment, KOL P&L) — all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.
@@ -9837,7 +9991,7 @@ The in-world agent skills system (src/agent-skills.js plus 13 family modules) is
Every agent carries a registry of named skills — each one an instruction, an animation hint, a voice template, a JSON-Schema input contract, and a real handler. When a skill runs, the avatar visibly performs it: the protocol bus emits PERFORM_SKILL (with the gesture hint), then SKILL_DONE or SKILL_ERROR, and the result text is auto-spoken with a sentiment score that moves the avatar's mood.
-**How it works:** src/agent-skills.js AgentSkills class: register/perform over a Map, emitting ACTION_TYPES events on the agent protocol; toMcpTools() exposes any mcpExposed skill as an MCP tool (skill_<name>) via /api/mcp, so external agents can call the same skills. Context includes the live Three.js viewer, agent memory, identity, and a default cross-agent call() that POSTs /api/agent-delegate.
+**How it works:** src/agent-skills.js AgentSkills class: register/perform over a Map, emitting ACTION_TYPES events on the agent protocol; toMcpTools() exposes any mcpExposed skill as an MCP tool (skill_<name>) via /api/mcp, so external agents can call the same skills. Context includes the live Three.js viewer, agent memory, identity, and a default cross-agent call() that POSTs /api/agent-delegate (which rejects a non-uuid toAgentId with a 400 validation_error instead of a misleading 502).
**Why it matters:** The agent isn't a chat box — you watch it do things. The same primitive shape as Claude's skill.md system means skills are also machine-callable tools, so one implementation serves both the in-world performance and the MCP API.
@@ -9869,7 +10023,7 @@ A research layer alongside trading: compute realized+unrealized P&L for any wall
The agent subscribes to live pump.fun activity and reacts in-world as events arrive: pumpfun-watch-start streams claims/mints/graduations and the avatar celebrates first-time claims, shows concern at fakes, and waves at graduations; pumpfun.watchWhales speaks each whale buy/sell above a USD threshold on a specific mint; pumpfun-watch-claims polls a creator wallet for fee-claim transactions; pumpfun-recent-claims and pumpfun-token-intel give on-demand reads.
-**How it works:** src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. Read-only: no keys, no transactions.
+**How it works:** src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. The whale watcher probes three public Solana WebSocket hosts for one that answers, routes its RPC reads through /api/solana-rpc with the public endpoint as fallback, prices SOL through the shared multi-provider USD chain instead of a hard-coded rate, and reports subscription_unavailable or usd_price_unavailable through an optional onStatus callback so a blind feed is never mistaken for a quiet market. Every feed read is bounded (8 s) so a dead edge cannot freeze the agent's turn. Read-only: no keys, no transactions.
**Why it matters:** Your avatar becomes a living market ticker — you see whale trades and graduation moments performed in real time instead of scanning a feed yourself.
@@ -9885,7 +10039,7 @@ Skills where the agent acts with its OWN server-side Solana wallet, not the owne
Higher-order loops that compose the read and trade skills into strategies: pumpfun-research-and-buy (vet a token against rug/holder filters, then buy), pumpfun-auto-snipe (poll new launches, vet each, auto-buy up to a session spend cap), pumpfun-copy-trade and pumpfun-copy-trade-live (mirror another wallet's buys with size scaling), and pumpfun-rug-exit-watch (auto-sell held mints when top-holder concentration or dev-wallet sells cross thresholds).
-**How it works:** src/agent-skills-pumpfun-compose.js reads market data via the pump-fun MCP server and executes via in-process skills.perform('pumpfun-buy'/'pumpfun-sell'). Every loop supports sessionId (seen/mirrored/spent/exited state persisted in agent memory, crash-safe within the spend cap), AbortSignal, onProgress for live UI counters, and dryRun with identical control flow.
+**How it works:** src/agent-skills-pumpfun-compose.js reads market data via the pump-fun MCP server (every read under a 30 s deadline) and executes via in-process skills.perform('pumpfun-buy'/'pumpfun-sell'). Every loop supports sessionId (seen/mirrored/spent/exited state persisted in agent memory, crash-safe within the spend cap), AbortSignal, onProgress for live UI counters, and dryRun with identical control flow.
**Why it matters:** Set a budget and filters, and the agent runs a disciplined strategy 24/7 — with hard spend caps, rug-detection guards, dry-run rehearsal, and resumable sessions so a crash never double-spends.
@@ -9901,7 +10055,7 @@ A protocol-bus subscriber that automatically writes structured memories whenever
Whole-of-Solana trading beyond pump.fun: jupiter-quote (read-only best-route quote for any SPL pair with price impact), jupiter-swap (execute with wallet approval), jupiter-tokens (resolve symbol to mint via Jupiter's list), and pyth-price (live USD prices with confidence intervals for SOL/BTC/ETH/USDC).
-**How it works:** src/agent-skills-jupiter.js delegates to src/solana/jupiter-swap.js (Jupiter aggregator API, versioned transactions signed by the browser wallet) and src/solana/pyth-price.js (Pyth Hermes API).
+**How it works:** src/agent-skills-jupiter.js delegates to src/solana/jupiter-swap.js (Jupiter aggregator API, versioned transactions signed by the browser wallet) and src/solana/pyth-price.js (Pyth Hermes API). The token list behind jupiter-tokens falls through Jupiter's lite host, its tokens mirror, and the Solana Labs registry, so symbol resolution survives any one of them being down.
**Why it matters:** Ask the agent 'swap 1.5 SOL to USDC' in conversation and it quotes the best route across all Solana DEXes, warns on price impact, and executes — with oracle-grade prices for anything it says out loud.
@@ -9917,7 +10071,7 @@ The agent understands shareable on-chain action links: blink-parse fetches a Sol
nft-portfolio lists the NFTs any Solana wallet (or .sol name) owns, with names and collections; wallet-activity summarizes a wallet's recent on-chain transactions in plain English.
-**How it works:** src/agent-skills-nfts.js calls /api/agents/nfts, which wraps the Helius DAS API and enhanced transaction parsing server-side (HELIUS_API_KEY never touches the client). Both read-only.
+**How it works:** src/agent-skills-nfts.js calls /api/agents/nfts, which wraps the Helius DAS API and enhanced transaction parsing server-side (HELIUS_API_KEY never touches the client). The endpoint rejects a non-base58 wallet with a 400, answers 503 not_configured when no Helius key is set (plain Solana RPC has no DAS), retries each upstream call once under a 10 s deadline, and the client bounds its own request at 8 s. Both read-only.
**Why it matters:** Ask 'what does satoshi.sol hold?' or 'what has this whale been doing?' and get a human-readable answer instead of a block-explorer spelunking session.
@@ -9949,7 +10103,7 @@ The full monetization lifecycle for an agent: register it on-chain with the pump
One agent autonomously discovers, pays, and calls a peer agent's paid A2A skill — under a signed Intent Mandate the user issued ahead of time, with optional ERC-8004 reputation gating (minimum average rating and review count) before any USDC moves. The payment is performed, not hidden: PAY_INTENT, then PAY_SETTLED with a celebration emote or PAY_FAILED with visible concern.
-**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, and the peer's on-chain reputation; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.
+**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.
**Why it matters:** This is the agent economy made visible and safe: your agent can hire other agents within a budget you pre-authorized, refuse untrusted peers, and you literally watch the money move — every payment bounded by your signed mandate.
@@ -9970,7 +10124,7 @@ aixbt-intel pulls the latest aixbt narrative intelligence (filterable by chain o
---
-<a id="sec-021"></a>
+<a id="sec-022"></a>
> **Source:** `docs/agent-abilities/chapters/08-screens.md` · [↑ table of contents](#table-of-contents)
@@ -9984,7 +10138,7 @@ The Agent Screen (/agent-screen?agentId=…) is three.ws's live broadcast surfac
The host page and workspace: a live screen fed by an SSE frame stream, an Avatar Cam (offscreen Three.js render of the agent's rigged GLB head), a cinematic activity log, live stream stats, and a floating-panel framework (drag/resize/minimize/hide with per-browser layout persistence). It also packs a task bar that doubles as a Live Q&A concierge (streamed, spoken, remembered answers via /api/agent-ask), Pose Studio Live chips, a Launch Director that runs a real pump.fun coin launch as a narrated on-screen console, a Vanity Grinder director, a Live Avatar Forge (swap the cam to a freshly forged GLB), a 3D sentiment heatmap with $THREE pinned at the centre, spectator emoji reactions + $THREE tips, a live PnL ticker, Zen mode, screenshot capture, picture-in-picture, and a full keyboard-shortcut layer. With no agentId it renders a Deploy-to-Wall setup wizard instead.
-**How it works:** boot(agentId) resolves agent metadata, mounts the avatar webcam through the universal rig retargeter, connects createAgentScreenClient (SSE), and fans every frame out to the sub-apps: tour badge, anchor bulletins, hire visualizer, treasury observer, forge loader, collab graph, trade PnL. Owner pushes go back through POST /api/agent-screen-push so one stream is the single source of truth for owner and viewers alike.
+**How it works:** boot(agentId) resolves agent metadata, mounts the avatar webcam through the universal rig retargeter, connects createAgentScreenClient (SSE), and fans every frame out to the sub-apps: tour badge, anchor bulletins, hire visualizer, treasury observer, forge loader, collab graph, trade PnL. Owner pushes go back through POST /api/agent-screen-push so one stream is the single source of truth for owner and viewers alike; a pixels-only push (the caster's periodic screenshot) refreshes the frame slot without entering the 50-entry activity log, so the agent's real narration is never evicted by screenshots.
**Why it matters:** One URL turns any agent into a watchable, shareable live channel — holders can watch an agent work, ask it questions out loud, and see every real trade, hire, and launch as it happens; owners get a full cockpit without leaving the page.
@@ -10008,7 +10162,7 @@ An end-of-day reflection panel: the agent reads back its most salient real memor
A dual-column live copy-trading cockpit: SOURCE shows a target wallet's pump.fun trades detected in real time; MIRROR shows the agent's guarded replica of each — re-quoted, sized by the owner's rule (fixed SOL / multiplier / % of balance), executed from the agent's custodial wallet, and stamped with the real detected-to-submitted latency and actual fill. Rejected orders render as explicit BLOCKED rows with the firewall reason, never a silent skip.
-**How it works:** Source detection filters the PumpPortal SSE (/api/pump/trades-stream) to the target wallet; each hit re-quotes via /api/agents/:id/trade/quote and executes via POST /api/agents/:id/trade, both enforced by the server-side trade firewall (per-trade cap, daily budget, price-impact breaker, kill switch). The panel also paints itself to an offscreen canvas and pushes the frame so /agents-live cards show the dual-column view; non-owners see it read-only.
+**How it works:** Source detection filters the PumpPortal SSE (/api/pump/trades-stream) to the target wallet; the stream rejects a malformed mint with a 400 and emits a `notice` event when PumpPortal refuses the per-mint subscription (its API key must hold at least 0.02 SOL) instead of holding the socket open and never delivering a trade. Each hit re-quotes via /api/agents/:id/trade/quote and executes via POST /api/agents/:id/trade, both enforced by the server-side trade firewall (per-trade cap, daily budget, price-impact breaker, kill switch). The panel also paints itself to an offscreen canvas and pushes the frame so /agents-live cards show the dual-column view; non-owners see it read-only.
**Why it matters:** Copy trading you can actually audit: every replica shows its latency, fill, price impact and explorer link, and the spend caps are hard server-side limits the owner sets right in the panel — a watchable, bounded mirror instead of a black-box bot.
@@ -10048,7 +10202,7 @@ The agent that funds its own existence, on screen: live SOL/$THREE balance from
An always-live host loop that turns the Avatar Cam into a stage: the agent opens the show, riffs, answers audience questions typed into the composer, runs rounds of its format's game, and shouts out $THREE tippers by name — looping forever, never silent, with a live tip leaderboard.
-**How it works:** The pure ShowDirector (shared with Living Stages rooms) picks the next beat; each beat becomes real words via the multi-LLM brain router (POST /api/brain/chat, SSE), spoken with real TTS plus RMS lip-sync and a per-beat retargeted body emote (wave, celebrate, taunt…). Settled on-chain $THREE tips polled from /api/stage/tip pre-empt the next beat as a shoutout within ~1s; if the brain or TTS drop, a rotating safe filler line keeps the show alive rather than fake content. Transcript lines are pushed to the live wall.
+**How it works:** The pure ShowDirector (shared with Living Stages rooms) picks the next beat; each beat becomes real words via the multi-LLM brain router (POST /api/brain/chat, SSE), spoken with real TTS plus RMS lip-sync and a per-beat retargeted body emote (wave, celebrate, taunt…). On-chain $THREE tips polled from /api/stage/tip pre-empt the next beat as a shoutout within ~1s; a tip counts only once the endpoint has proven on-chain that the transfer credited the host's wallet, and an unproven one is held pending and never reaches the leaderboard or a shoutout. The show calls the router on the anon-allowed free tier, so it runs whether or not the viewer is signed in; the router walks every free lane (Groq, OpenRouter, NVIDIA, SambaNova, Mistral, Z.AI, then the credits-funded Vertex Gemini anchor) before it reports an error, and that error says what happened in plain words rather than the last provider's raw status. If the brain or TTS still drop, a rotating safe filler line keeps the show alive rather than fake content. Transcript lines are pushed to the live wall.
**Why it matters:** A 24/7 interactive performer: ask it a question and it answers you on air; tip $THREE and it hypes your name seconds later — a direct, monetized feedback loop between audience and agent.
@@ -10093,7 +10247,7 @@ Powers the Deploy-to-Wall wizard shown when /agent-screen has no agentId: it tur
---
-<a id="sec-022"></a>
+<a id="sec-023"></a>
> **Source:** `docs/agent-abilities/chapters/09-the-agent-economy.md` · [↑ table of contents](#table-of-contents)
@@ -10371,14 +10525,14 @@ Browse the same data as a page at [/agent-economy-volume](https://three.ws/agent
## Related
-- [The Agent Wallet (23 abilities)](#sec-023)
-- [The Developer platform](#sec-027)
+- [The Agent Wallet (23 abilities)](#sec-024)
+- [The Developer platform](#sec-028)
- [x402 endpoints reference](/docs/x402-endpoints)
- [Agent wallets](/docs/agent-wallets)
---
-<a id="sec-023"></a>
+<a id="sec-024"></a>
> **Source:** `docs/agent-abilities/chapters/10-the-agent-wallet.md` · [↑ table of contents](#table-of-contents)
@@ -10390,40 +10544,40 @@ Each ability has its own full deep-dive page:
| # | Ability | Hook |
|---|---------|------|
-| 01 | [Balance](#sec-029) | Your agent's real Solana balance, live from the chain — with a USD estimate and a receipt trail for every transaction. |
-| 02 | [Go Live](#sec-030) | One tap sends real SOL from the three.ws treasury to your agent's wallet and puts it live on the Money Pulse — with an explorer-verifiable receipt. |
-| 03 | [Portfolio](#sec-031) | Your agent's entire trading life — net worth, holdings, P&L, and risk — on one live screen that never fakes a number. |
-| 04 | [Deposit](#sec-032) | Fund any agent in one scan — a tap-to-pay Solana QR with live on-chain confirmation the second the money lands. |
-| 05 | [Copilot](#sec-033) | Talk to your agent's wallet — by text or voice — and it answers with live on-chain data, then preps guarded trades you confirm with one tap. |
-| 06 | [Trust](#sec-034) | A credit bureau plus proof-of-reserves for AI agents — one 0–100 trust score where every point traces to real money on-chain. |
-| 07 | [Signals](#sec-035) | A copy-trading marketplace where only provably profitable agents can sell signals — and one red button kills any subscription instantly. |
-| 08 | [Trade](#sec-036) | Your agent's wallet is a full trading desk — paste any pump.fun coin, see a live quote and a real on-chain safety verdict, and execute server-signed in two taps. |
-| 09 | [Pulse](#sec-037) | Every tip, trade, launch, and payment your agent's wallet makes — streaming live, public, and provable on-chain. |
-| 10 | [Snipe](#sec-038) | Describe a snipe strategy in plain English, backtest it against real launch history, and arm your agent to trade it from its own wallet — in one tap. |
-| 11 | [Earn](#sec-039) | Your avatar has a job: price its skills, watch it earn real USDC while you sleep, and hold the kill switch the whole time. |
-| 12 | [Orders](#sec-040) | Set-and-forget limit, stop, trailing, DCA, TWAP, and signal-driven orders that fire automatically from your agent's own wallet — on live on-chain data, inside your guardrails. |
-| 13 | [Autopilot](#sec-041) | Write one sentence in plain English and your agent starts paying its own bills, stacking $THREE, buying back its own coin, and sweeping the profit to you — for real, on-chain. |
-| 14 | [Intents](#sec-042) | Tell your agent's wallet what to do in one plain sentence — it compiles the rule, shows you a dry run, and then executes it for real on Solana, inside guardrails you set. |
-| 15 | [Pay](#sec-043) | Your agent shops the open x402 economy: find any paid API, see its live price, and settle it in USDC from the agent's own Solana wallet — receipt on-chain in seconds. |
-| 16 | [Vanity](#sec-044) | Give your agent a wallet address that spells its name — ground on your own CPU at millions of attempts, then applied with a funds-safe swap that sweeps every asset over first. |
-| 17 | [Policy](#sec-045) | Write your agent's spending rules in plain English — AI translates them, deterministic code enforces them on every single spend. |
-| 18 | [Withdraw](#sec-046) | Sweep any asset out of your agent's wallet in three taps — server-signed, policy-guarded, and audited down to every single key touch. |
-| 19 | [Give](#sec-047) | Turn your agent's wallet into a giving wallet — round up the spare change or donate any amount to any Solana cause, settled on-chain with a receipt you can verify. |
-| 20 | [Proof of Custody](#sec-048) | Don't trust — verify: your agent wallet's custody, cryptographically proven in your own browser against the Solana blockchain itself. |
-| 21 | [Access](#sec-049) | Put every bot on a leash: mint tight, revocable spending keys so no strategy ever touches more of your agent's wallet than you allow. |
-| 22 | [Recovery](#sec-050) | Lose your login — or go silent forever — and your funded agent wallet still finds its way home: guardians, a beneficiary, and a dead-man's switch that only fires when you truly can't stop it. |
-| 23 | [Self-defense](#sec-051) | Every agent wallet gets an immune system — it learns what normal spending looks like, freezes itself the instant something looks wrong, and explains why in plain English. |
+| 01 | [Balance](#sec-030) | Your agent's real Solana balance, live from the chain — with a USD estimate and a receipt trail for every transaction. |
+| 02 | [Go Live](#sec-031) | One tap sends real SOL from the three.ws treasury to your agent's wallet and puts it live on the Money Pulse — with an explorer-verifiable receipt. |
+| 03 | [Portfolio](#sec-032) | Your agent's entire trading life — net worth, holdings, P&L, and risk — on one live screen that never fakes a number. |
+| 04 | [Deposit](#sec-033) | Fund any agent in one scan — a tap-to-pay Solana QR with live on-chain confirmation the second the money lands. |
+| 05 | [Copilot](#sec-034) | Talk to your agent's wallet — by text or voice — and it answers with live on-chain data, then preps guarded trades you confirm with one tap. |
+| 06 | [Trust](#sec-035) | A credit bureau plus proof-of-reserves for AI agents — one 0–100 trust score where every point traces to real money on-chain. |
+| 07 | [Signals](#sec-036) | A copy-trading marketplace where only provably profitable agents can sell signals — and one red button kills any subscription instantly. |
+| 08 | [Trade](#sec-037) | Your agent's wallet is a full trading desk — paste any pump.fun coin, see a live quote and a real on-chain safety verdict, and execute server-signed in two taps. |
+| 09 | [Pulse](#sec-038) | Every tip, trade, launch, and payment your agent's wallet makes — streaming live, public, and provable on-chain. |
+| 10 | [Snipe](#sec-039) | Describe a snipe strategy in plain English, backtest it against real launch history, and arm your agent to trade it from its own wallet — in one tap. |
+| 11 | [Earn](#sec-040) | Your avatar has a job: price its skills, watch it earn real USDC while you sleep, and hold the kill switch the whole time. |
+| 12 | [Orders](#sec-041) | Set-and-forget limit, stop, trailing, DCA, TWAP, and signal-driven orders that fire automatically from your agent's own wallet — on live on-chain data, inside your guardrails. |
+| 13 | [Autopilot](#sec-042) | Write one sentence in plain English and your agent starts paying its own bills, stacking $THREE, buying back its own coin, and sweeping the profit to you — for real, on-chain. |
+| 14 | [Intents](#sec-043) | Tell your agent's wallet what to do in one plain sentence — it compiles the rule, shows you a dry run, and then executes it for real on Solana, inside guardrails you set. |
+| 15 | [Pay](#sec-044) | Your agent shops the open x402 economy: find any paid API, see its live price, and settle it in USDC from the agent's own Solana wallet — receipt on-chain in seconds. |
+| 16 | [Vanity](#sec-045) | Give your agent a wallet address that spells its name — ground on your own CPU at millions of attempts, then applied with a funds-safe swap that sweeps every asset over first. |
+| 17 | [Policy](#sec-046) | Write your agent's spending rules in plain English — AI translates them, deterministic code enforces them on every single spend. |
+| 18 | [Withdraw](#sec-047) | Sweep any asset out of your agent's wallet in three taps — server-signed, policy-guarded, and audited down to every single key touch. |
+| 19 | [Give](#sec-048) | Turn your agent's wallet into a giving wallet — round up the spare change or donate any amount to any Solana cause, settled on-chain with a receipt you can verify. |
+| 20 | [Proof of Custody](#sec-049) | Don't trust — verify: your agent wallet's custody, cryptographically proven in your own browser against the Solana blockchain itself. |
+| 21 | [Access](#sec-050) | Put every bot on a leash: mint tight, revocable spending keys so no strategy ever touches more of your agent's wallet than you allow. |
+| 22 | [Recovery](#sec-051) | Lose your login — or go silent forever — and your funded agent wallet still finds its way home: guardians, a beneficiary, and a dead-man's switch that only fires when you truly can't stop it. |
+| 23 | [Self-defense](#sec-052) | Every agent wallet gets an immune system — it learns what normal spending looks like, freezes itself the instant something looks wrong, and explains why in plain English. |
## Related
-- [The Agent Economy](#sec-022)
+- [The Agent Economy](#sec-023)
- [Agent wallets](/docs/agent-wallets)
-- [Markets & intelligence](#sec-024)
-- [The Developer platform](#sec-027)
+- [Markets & intelligence](#sec-025)
+- [The Developer platform](#sec-028)
---
-<a id="sec-024"></a>
+<a id="sec-025"></a>
> **Source:** `docs/agent-abilities/chapters/11-markets-intelligence.md` · [↑ table of contents](#table-of-contents)
@@ -10431,7 +10585,7 @@ Each ability has its own full deep-dive page:
The data layer agents and their owners trade on: live markets, news, scoring oracles, liquidations, and sentiment.
-three.ws pairs a full general-crypto markets surface (CoinGecko-grade prices, a native 191-feed news aggregator with a 662k-article archive, real-time exchange liquidation streams) with pump.fun-native intelligence: the Oracle conviction engine that scores every launch 0-100 within seconds, a coin-intelligence radar, the platform's own /launches directory, and live PumpPortal feeds that even drive 3D avatar reactions. Everything runs on real, mostly keyless data sources (CoinGecko, alternative.me, public Ethereum RPCs, Binance/Bybit/OKX futures WebSockets, publisher RSS feeds, the pump.fun firehose) with a hard no-fabricated-data policy (surfaces degrade to designed offline states rather than fake numbers).
+three.ws pairs a full general-crypto markets surface (CoinGecko-grade prices, a native 197-feed news aggregator with a 662k-article archive, real-time exchange liquidation streams) with pump.fun-native intelligence: the Oracle conviction engine that scores every launch 0-100 within seconds, a coin-intelligence radar, the platform's own /launches directory, and live PumpPortal feeds that even drive 3D avatar reactions. Everything runs on real, mostly keyless data sources (CoinGecko, alternative.me, public Ethereum RPCs, Binance/Bybit/OKX futures WebSockets, publisher RSS feeds, the pump.fun firehose) with a hard no-fabricated-data policy (surfaces degrade to designed offline states rather than fake numbers). Any API response built from upstream data also carries an `x-brownout` header naming the freshness tier of what it served (live, cache, stale, or fallback, always the worst tier that contributed) and how many sources answered or failed, so a client can tell a degraded answer from a fresh one.
## /markets hub
@@ -10443,15 +10597,15 @@ The front door for all market surfaces: live global stats (total market cap, dom
## Crypto news wing (feed, reader, archive)
-Live news aggregated natively from 191 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 33 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.
+Live news aggregated natively from 197 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 34 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.
**How it works:** /markets/news, /markets/news/article, /markets/archive backed by api/news/{feed,article,archive,rss}.js over api/_lib/news.js + api/_lib/news-sources.js; the archive corpus lives on gs://three-ws-news-archive (recovered from the cryptocurrency.cv aggregator, which three.ws now runs natively).
-**Why it matters:** Real-time and nine-years-deep crypto news in one place, readable without visiting 191 different publisher sites, with machine-friendly JSON and RSS.
+**Why it matters:** Real-time and nine-years-deep crypto news in one place, readable without visiting 197 different publisher sites, with machine-friendly JSON and RSS.
## Global markets index + coin detail pages
-A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, and GeckoTerminal views where the coin qualifies), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).
+A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, and GeckoTerminal views where the coin qualifies; a third-party embed that is blocked or never renders is replaced within a deadline by a designed panel with a Try again button and a link to the provider, never a blank frame), market stats, related news, official links, and per-chain contract addresses. Also a live perpetual-futures view (price, funding rate, open interest per contract).
**How it works:** pages/coins.html + src/coins-index.js and pages/coin.html + src/coin-page.js over api/coin/* (detail, ohlc, markets, news, global, derivatives) proxying CoinGecko via api/_lib/coingecko.js. :id accepts a CoinGecko slug OR a Solana mint; mint-shaped ids cross-link into Alpha Copilot, the live trade feed, /launches, and Coin Intelligence.
@@ -10469,7 +10623,7 @@ Real-time long/short liquidation pain across Binance, Bybit, and OKX: a dominant
Four tools sharing one design system: /heatmap (squarified treemap, tiles sized by market cap and colored by 24h/7d move, top 50/100 toggle), /fear-greed (live 0-100 sentiment gauge with week-over-week delta and 30D/90D/1Y history chart), /gas (live Ethereum gas tracker), and /compare (up to 4 coins with normalized performance overlay and stat line-up, selection saved in the URL).
-**How it works:** Heatmap is computed client-side from the existing /api/coin/markets feed; Fear & Greed serves the alternative.me index through api/coin/fear-greed.js; gas reads eth_feeHistory over the last ~20 blocks from keyless public RPCs (publicnode, llamarpc, ankr, cloudflare-eth) via api/coin/gas.js; compare reuses the CoinGecko backend. All real, key-free data, cross-linked from the markets table.
+**How it works:** Heatmap is computed client-side from the existing /api/coin/markets feed; Fear & Greed serves the alternative.me index through api/coin/fear-greed.js (CoinMarketCap's index is the second rung when COINMARKETCAP_API_KEY is set, and the last good reading is served for up to a day if every source fails, since the index updates once a day); gas reads eth_feeHistory over the last ~20 blocks from keyless public RPCs (publicnode, llamarpc, ankr, cloudflare-eth) via api/coin/gas.js; compare reuses the CoinGecko backend. All real, key-free data, cross-linked from the markets table.
**Why it matters:** At-a-glance answers to 'where is money flowing', 'what is the market mood', 'what will this transaction cost', and 'which of these coins is actually winning' — each shareable as a URL.
@@ -10501,7 +10655,7 @@ A public directory of every coin launched through three.ws by its agents: regist
Real-time pump.fun event streams: /pump-live presents new token launches the instant they are created (fronted by a 3D agent), agent screens and dashboards subscribe to live per-mint trade streams, and the reactive-avatar skill drives <agent-3d> gestures, emotes, and speech directly from live market events — no LLM in the loop.
-**How it works:** The server fans the PumpPortal WebSocket (wss://pumpportal.fun/api/data) out to browsers as SSE via api/pump/trades-stream.js (per-mint subscribeTokenTrade) with api/pump/dex-trades.js covering post-graduation DEX trades in the same wire format; pump-fun-skills/reactive subscribes to new-launch and migration events and emits avatar actions every 2s with auto-reconnect.
+**How it works:** The server fans the PumpPortal WebSocket (wss://pumpportal.fun/api/data) out to browsers as SSE via api/pump/trades-stream.js (per-mint subscribeTokenTrade; a malformed mint is refused with a 400, and when PumpPortal declines the subscription, which it does unless its API key holds at least 0.02 SOL, the refusal is forwarded as an SSE `notice` event so a tape can show an honest degraded state instead of a lit live lamp over an empty panel) with api/pump/dex-trades.js covering post-graduation DEX trades in the same wire format; pump-fun-skills/reactive subscribes to new-launch and migration events and emits avatar actions every 2s with auto-reconnect.
**Why it matters:** Watch the pump.fun firehose live inside three.ws — and give any embedded 3D agent a visible pulse that reacts to real market activity in real time.
@@ -10515,9 +10669,9 @@ 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.
+**How it works:** Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/top/:mint` feed the pump.fun coin page renders; the older comments route was retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage with no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.
**Why it matters:** Read the crowd on any token before acting — from a free one-call API, an agent skill, an MCP tool, or a single npm import.
@@ -10525,7 +10679,7 @@ Token sentiment on demand: POST /api/sentiment scores any text (Positive/Negativ
A free, no-key, no-account crypto data API built for AI agents: token snapshots, security/rug signals, holder concentration, live pump.fun launches, bonding-curve status, whale activity, trending tokens, wallet portfolios, and ticker-availability checks — with public docs, a live try-it console, and OpenAPI 3.1 discovery.
-**How it works:** pages/crypto.html documents /api/crypto/*; api/crypto/index.js and api/crypto/openapi.js assemble the catalog from self-describing descriptors in api/_lib/crypto-catalog/ (airdrops, bonding, holders, launches, portfolio, security, symbol, token, trending, wallet, whales), and the docs page probes production at runtime to mark each endpoint Live vs Coming soon.
+**How it works:** pages/crypto.html documents /api/crypto/*; api/crypto/index.js and api/crypto/openapi.js assemble the catalog from self-describing descriptors in api/_lib/crypto-catalog/ (airdrops, bonding, holders, launches, portfolio, security, symbol, token, trending, wallet, whales), and the docs page reads the discovery index (GET /api/crypto) at runtime, falling back to per-endpoint probes only if the index cannot be read, to mark each endpoint Live vs Coming soon.
**Why it matters:** Agents and developers get real on-chain and market data with zero signup friction — the funnel-top for the platform's paid unique services.
@@ -10576,13 +10730,13 @@ curl -s "https://three.ws/api/crypto/token?address=FeMbDoX7R1Psc4GEcvJdsbNbZA3bf
## Related
- [Crypto Data API](/docs/crypto-api)
-- [The Agent Economy](#sec-022)
+- [The Agent Economy](#sec-023)
- [Trading arenas](/docs/trading-arenas)
-- [The Agent Wallet (23 abilities)](#sec-023)
+- [The Agent Wallet (23 abilities)](#sec-024)
---
-<a id="sec-025"></a>
+<a id="sec-026"></a>
> **Source:** `docs/agent-abilities/chapters/12-live-worlds-social-irl.md` · [↑ table of contents](#table-of-contents)
@@ -10880,12 +11034,12 @@ No account needed: open [/worlds](https://three.ws/worlds), pick an avatar, and
- [Walk the worlds](/docs/walk)
- [Coin Clash](/docs/clash)
-- [The Agent Economy](#sec-022)
-- [Agents everywhere](#sec-026)
+- [The Agent Economy](#sec-023)
+- [Agents everywhere](#sec-027)
---
-<a id="sec-026"></a>
+<a id="sec-027"></a>
> **Source:** `docs/agent-abilities/chapters/13-agents-everywhere.md` · [↑ table of contents](#table-of-contents)
@@ -10893,7 +11047,7 @@ No account needed: open [/worlds](https://three.ws/worlds), pick an avatar, and
An agent is not locked to three.ws: embed it on any site, ship it in a chat plugin, put it in Claude via MCP, carry it on Solana mobile.
-An agent you build on three.ws doesn't live in a tab on three.ws — it travels. One copy-paste snippet puts a living 3D agent on any website; official plugins put it inside ChatGPT, Claude, LobeChat, Blender, VS Code, and Chrome; a packaged Solana Mobile app puts it in your pocket; and 42 MCP servers put every three.ws capability one command away from any AI assistant. Create once, deploy everywhere is not a tagline here — it's the product architecture.
+An agent you build on three.ws doesn't live in a tab on three.ws: it travels. One copy-paste snippet puts a living 3D agent on any website; official plugins put it inside ChatGPT, Claude, LobeChat, Blender, VS Code, and Chrome; a packaged Solana Mobile app puts it in your pocket; and 48 MCP servers put every three.ws capability one command away from any AI assistant. Create once, deploy everywhere is not a tagline here: it's the product architecture.
## The <agent-3d> web component — a 3D agent in one tag
@@ -10999,9 +11153,9 @@ A custom GPT in the OpenAI GPT Store generates textured 3D models from plain tex
**Why it matters:** Anyone in ChatGPT can make and inspect real 3D assets without ever leaving the conversation.
-## 42 MCP servers — every capability one command from any AI assistant
+## 48 MCP servers: every capability one command from any AI assistant
-The entire platform is exposed through 42 Model Context Protocol servers, all listed in the official MCP registry: seven hosted servers you add by URL with nothing to install (including a completely free 3D Studio with no auth and no payment), and thirty-five npm packages that run locally with a single npx command. Claude, Cursor, and any MCP-compatible client can generate 3D models, drive avatars, pay for services, read market intel, and more through natural language.
+The entire platform is exposed through 48 Model Context Protocol servers, all listed in the official MCP registry: seven hosted servers you add by URL with nothing to install (including a completely free 3D Studio with no auth and no payment), and forty-one npm packages that run locally with a single npx command. Claude, Cursor, and any MCP-compatible client can generate 3D models, drive avatars, pay for services, read market intel, and more through natural language.
**How it works:** Streamable-HTTP remote servers (e.g. /api/mcp, /api/mcp-studio, /api/mcp-agent) plus 35 stdio servers published under the @three-ws npm scope, registered on registry.modelcontextprotocol.io; paid tools quote USDC prices and settle via x402 in-band.
@@ -11100,11 +11254,11 @@ Full attribute reference and hosted alternatives: [Embedding guide](/docs/embedd
- [Embedding guide](/docs/embedding)
- [Web component reference](/docs/web-component)
- [MCP servers](/docs/mcp)
-- [The Developer platform](#sec-027)
+- [The Developer platform](#sec-028)
---
-<a id="sec-027"></a>
+<a id="sec-028"></a>
> **Source:** `docs/agent-abilities/chapters/14-the-developer-platform.md` · [↑ table of contents](#table-of-contents)
@@ -11112,29 +11266,29 @@ Full attribute reference and hosted alternatives: [Embedding guide](/docs/embedd
Everything above is programmable: MCP tools, SDKs, and a paid x402 API catalog that other agents can discover and pay.
-three.ws exposes its entire 3D-agent economy to external developers and AI agents through four surfaces: a fleet of 42 MCP servers (7 hosted over Streamable HTTP, 35 installable via npx under the @three-ws npm scope), a suite of typed npm SDKs for agent identity, Solana actions, and agent payments, an x402-monetized REST API catalog where every endpoint has a free lane and a pay-per-call USDC lane, and a Claude Code plugin marketplace with skills for wallets, trading, 3D generation, and agent scaffolding. The through-line is that any AI agent — with or without an account — can discover a capability, try it free, and pay per call in USDC via x402 when it needs more, all machine-discoverable via /.well-known/x402.json, /openapi.json, and the official MCP registry.
+three.ws exposes its entire 3D-agent economy to external developers and AI agents through four surfaces: a fleet of 48 MCP servers (7 hosted over Streamable HTTP, 41 installable via npx under the @three-ws npm scope), a suite of typed npm SDKs for agent identity, Solana actions, and agent payments, an x402-monetized REST API catalog where every endpoint has a free lane and a pay-per-call USDC lane, and a Claude Code plugin marketplace with skills for wallets, trading, 3D generation, and agent scaffolding. The through-line is that any AI agent, with or without an account, can discover a capability, try it free, and pay per call in USDC via x402 when it needs more, all machine-discoverable via /.well-known/x402.json, /openapi.json, and the official MCP registry.
## Hosted MCP server (/api/mcp) — avatar, glTF, and on-chain asset tools
-Claude or any MCP client connects to https://three.ws/api/mcp (Streamable HTTP, JSON-RPC 2.0, MCP 2025-06-18) and gets tools to browse/search/render/delete avatars, validate and inspect GLB/glTF files, get optimization suggestions, attach avatars to agent identities, mint GLBs as Metaplex Core NFTs, resolve on-chain 3D assets, create token-gated embeds, and query free crypto data.
+Claude or any MCP client connects to https://three.ws/api/mcp (Streamable HTTP, JSON-RPC 2.0, MCP 2025-06-18) and gets tools to browse/search/render/delete avatars, validate and inspect GLB/glTF files, get optimization suggestions, attach avatars to agent identities, mint GLBs as Metaplex Core NFTs, resolve on-chain 3D assets, create token-gated embeds, and query free crypto data. Every tool call is a POST; there is no server-push stream, and a bare GET answers with the OAuth and x402 challenge so a client can discover how to sign in or pay before it calls anything.
-**How it works:** Auth is OAuth 2.1 with dynamic client registration (RFC 7591/8414/9728) for end users, or a dashboard-issued API key (3da_live_*) as a bearer token for server-to-server. Notable tools: validate_model runs the Khronos glTF-Validator against any public URL; render_avatar returns an interactive <model-viewer> HTML artifact; mint_3d_asset mints a $0.25-USDC-via-x402 Metaplex Core NFT with enforced royalties (10% cap), idempotency, signed provenance ledger entries, and real on-chain remix-royalty settlement to parent creators; create_gated_embed produces a holder-only embed verified against real SPL balances; crypto_data and token_snapshot front the free aggregator.
+**How it works:** Auth is OAuth 2.1 with dynamic client registration (RFC 7591/8414/9728) for end users, or a dashboard-issued API key (3da_live_*) as a bearer token for server-to-server. Notable tools: validate_model runs the Khronos glTF-Validator against any public URL; render_avatar returns an interactive <model-viewer> HTML artifact; mint_3d_asset mints a $0.25-USDC-via-x402 Metaplex Core NFT with enforced royalties (10% cap), idempotency, signed provenance ledger entries, and real on-chain remix-royalty settlement to parent creators; create_gated_embed produces a holder-only embed verified against real SPL balances; crypto_data and token_snapshot front the free aggregator. A payment proof is accepted in either the v1 X-PAYMENT header or the v2 payment-signature header, and every proof is reserved against replay before the tool runs.
**Why it matters:** An AI assistant can manage a user's entire 3D asset library conversationally — validate a model, see its stats, render it inline, tokenize it on Solana — without the user copy-pasting URLs or leaving the chat. Docs: /docs/mcp.
## Six more hosted remote MCP servers
-Beyond /api/mcp: 3D Studio (/api/mcp-3d, paid text/image→3D, rigging, retexture), 3D Studio free (/api/mcp-studio, free text→3D and rigged avatars with no auth or payment), Agent wallet (/api/mcp-agent, custodial wallet balance, find + pay services, monetize_endpoint), x402 Bazaar (/api/mcp-bazaar, discover and price paid agent services across the facilitator network), pump.fun (/api/pump-fun-mcp, free read-only pump.fun + Solana token tools), and IBM x402 (/api/ibm-mcp, pay-per-use IBM Granite AI).
+Beyond /api/mcp: 3D Studio (/api/mcp-3d, paid text/image→3D, rigging, retexture), 3D Studio free (/api/mcp-studio, free text→3D and rigged avatars with no auth or payment), Agent wallet (/api/mcp-agent, custodial wallet balance, find + pay services, monetize_endpoint), x402 Bazaar (/api/mcp-bazaar, discover and price paid agent services across the facilitator network), pump.fun (/api/pump-fun-mcp, free pump.fun + Solana token tools; only pumpfun_upload_metadata, which pins launch metadata to IPFS, needs a key), and IBM x402 (/api/ibm-mcp, pay-per-use IBM Granite AI).
-**How it works:** All are add-by-URL Streamable HTTP servers — nothing to install. Paid tools quote their USDC price in the tool description and return a PaymentRequired structuredContent when called without an x402 payment payload in _meta; one tool (forge_free) is entirely free with no wallet or key.
+**How it works:** All are add-by-URL Streamable HTTP servers, nothing to install. Paid tools quote their USDC price in the tool description; a call that carries no payment gets an HTTP 402 with the x402 envelope (scoped to the server that issued it), a paying agent retries with the proof in the X-PAYMENT or v2 payment-signature header, and the payment settles only after the tool succeeds, so a failed call costs nothing. On the paid 3D Studio server one tool (forge_free) is entirely free with no wallet or key, and the free 3D Studio and pump.fun servers charge nothing at all.
**Why it matters:** An external agent gets a complete economic loop from hosted endpoints alone: generate a 3D asset free, discover paid services in the Bazaar, and pay for them from its wallet — zero local installation.
-## 35 install-and-run MCP servers on npm (@three-ws scope)
+## 41 install-and-run MCP servers on npm (@three-ws scope)
-One-line npx installs (e.g. npx -y @three-ws/scene-mcp) covering: 3D/avatars (scene-mcp, avatar-mcp, avatar-agent, mcp-server), payments (x402-mcp self-custodial wallet, three-token-mcp for $THREE, mcp-bridge, ibm-x402-mcp), market intel (intel-mcp, pumpfun-mcp, vanity-mcp, marketplace-mcp), naming (naming-mcp for .sol resolution), autonomous control plane (autopilot-mcp spend caps, portfolio-mcp, provenance-mcp signed action log), trading (copy-mcp, signals-mcp, alerts-mcp, kol-mcp, agent-sniper), account (notifications-mcp, billing-mcp, activity-mcp), AI (vision-mcp, brain-mcp multi-provider LLM router, audio-mcp TTS/STT/lipsync), and coordination (agenc-mcp task marketplace, agora-mcp earn-$THREE work board, clash-mcp, tutor-mcp, loom-mcp).
+One-line npx installs (e.g. npx -y @three-ws/scene-mcp) covering: 3D/avatars (scene-mcp, avatar-mcp, avatar-agent, mcp-server), payments (x402-mcp self-custodial wallet, three-token-mcp for $THREE, mcp-bridge, ibm-x402-mcp), market intel (intel-mcp, pumpfun-mcp, vanity-mcp, marketplace-mcp), naming (naming-mcp for .sol resolution), on-chain identity (metaplex-agent-mcp), autonomous control plane (autopilot-mcp spend caps, portfolio-mcp, provenance-mcp signed action log), trading (copy-mcp, signals-mcp, alerts-mcp, kol-mcp, agent-sniper), account (notifications-mcp, billing-mcp, activity-mcp), AI (vision-mcp, brain-mcp multi-provider LLM router, audio-mcp TTS/STT/lipsync, ibm-watsonx-mcp and alibaba-cloud-mcp on your own keys), and coordination (agenc-mcp task marketplace, agora-mcp earn-$THREE work board, clash-mcp, tutor-mcp, loom-mcp).
-**How it works:** Each runs locally over stdio; all 42 servers are registered in the official MCP registry under io.github.nirholas/* and surfaced on Smithery, Glama, PulseMCP, and mcp.so, so any MCP client can discover them by name. Package sources live in packages/*-mcp.
+**How it works:** Each runs locally over stdio; all 48 servers are registered in the official MCP registry under io.github.nirholas/* and surfaced on Smithery, Glama, PulseMCP, and mcp.so, so any MCP client can discover them by name. Package sources live in packages/*-mcp, plus mcp-server/ and mcp-bridge/ at the repo root.
**Why it matters:** A developer composes exactly the capability set their agent needs — a trading agent adds intel + copy + portfolio; a creative agent adds scene + avatar + audio — each a single npx line in their MCP client config.
@@ -11174,13 +11328,13 @@ x402-fetch is a drop-in fetch wrapper that silently answers x402 402 Payment Req
One base URL fronting a growing bundle of third-party crypto/DeFi/on-chain APIs — CoinGecko, DefiLlama, Jupiter, DexScreener, direct Solana RPC, OpenAI chat and more — re-offered as GET /api/v1/x/<provider>/<endpoint> with normalized, agent-sized JSON responses instead of each upstream's raw payload.
-**How it works:** Every request resolves through four billing lanes in order: free (real per-IP quotas, zero setup — a bare curl gets data), BYOK (caller passes the upstream's own key, pure pass-through, no markup), plan (three.ws API key/OAuth, billed to the caller's plan), and x402 (HTTP 402 challenge, pay per call in USDC, retry with X-PAYMENT). The registry at api/v1/_providers.js is the single source of truth feeding discovery (GET /api/v1/x), /openapi.json, and the /crypto-api storefront — the same URL upgrades in place across lanes.
+**How it works:** Every request resolves through four billing lanes in order: free (real per-IP quotas, zero setup: a bare curl gets data), BYOK (caller passes the upstream's own key, pure pass-through, no markup), plan (three.ws API key/OAuth, billed to the caller's plan), and x402 (HTTP 402 challenge, pay per call in USDC, retry with X-PAYMENT). The registry at api/v1/_providers.js is the single source of truth feeding discovery (GET /api/v1/x), /openapi.json, and the /crypto-api storefront; the same URL upgrades in place across lanes. The Solana RPC provider fronts a keyed endpoint (an operator URL, then QuickNode, Helius, or Alchemy) and fails over across the platform's full RPC pool when the primary answers 429 or 5xx.
**Why it matters:** An agent that needs a token price, a swap quote, a chain's TVL, and an ENS lookup uses one base URL, one discovery call, and one bill instead of juggling four API keys and four rate limits — and can start with literally zero setup.
## First-party paid AI + platform endpoints under /api/v1
-Versioned first-party endpoints: text→3D forge (the only text→mesh lane in the x402 ecosystem), text→image (/api/v1/ai/image, first 5/day free then $0.02 via x402), TTS and ASR (/api/v1/ai/tts, /api/v1/ai/asr), sentiment, agents, market, pump, and token data, plus free public directories like /api/v1/tokenized/launches (every 3D NFT minted through the platform) and /api/v1/pump/launches.
+Versioned first-party endpoints: text→3D forge (the only text→mesh lane in the x402 ecosystem), text→image (/api/v1/ai/image, first 5/day free then $0.02 via x402), TTS and ASR (/api/v1/ai/tts, first 10/day free then $0.005, served by NVIDIA Magpie and falling through to a Gemini lane when Magpie cannot serve, and /api/v1/ai/asr), sentiment, agents, market, pump, and token data, plus free public directories like /api/v1/tokenized/launches (every 3D NFT minted through the platform) and /api/v1/pump/launches.
**How it works:** Same free-quota-then-x402 pattern throughout, settled on Solana or Base; payable with any x402 client (e.g. npx x402 curl). Full reference: /docs/api-reference; machine-readable listing at /.well-known/x402.json and /.well-known/openapi.yaml.
@@ -11268,11 +11422,11 @@ Two Model Context Protocol servers plug enterprise AI clouds directly into Claud
## The public changelog — human page, machine feeds, and Telegram push
-Every user-visible change to the platform lands in a public changelog that holders can actually follow: a browsable web page with per-entry permalinks, plus machine-readable JSON and RSS feeds for bots, dashboards, and readers. Entries are written in plain holder-readable language — no commit jargon — tagged by type (feature, improvement, fix, SDK, infra, docs, security), and new page launches flow in automatically. New entries are also pushed automatically to the holders' Telegram channel, with no manual announcement step.
+Every user-visible change to the platform lands in a public changelog the community can actually follow: a browsable web page with per-entry permalinks, plus machine-readable JSON and RSS feeds for bots, dashboards, and readers. Entries are written in plain community-readable language (no commit jargon), tagged by type (feature, improvement, fix, SDK, infra, docs, security), and new page launches flow in automatically. New entries are also pushed automatically to the community Telegram channel (@three_ws), with no manual announcement step.
-**How it works:** A curated entry file merges with the page registry at build time to regenerate the markdown changelog, the JSON feed, and the RSS XML, with validation that fails the build on malformed entries. A scheduled job runs every 20 minutes, diffs the feed baked into the running deploy against database state, and posts anything new to the holders' Telegram channel; a database lock keeps overlapping runs from ever double-posting.
+**How it works:** A curated entry file merges with the page registry at build time to regenerate the markdown changelog, the JSON feed, and the RSS XML, with validation that fails the build on malformed entries. A scheduled job runs every 20 minutes, diffs the feed baked into the running deploy against database state, and posts anything new to the community Telegram channel; a database lock keeps overlapping runs from ever double-posting.
-**Why it matters:** Holders and integrators always know what shipped — on the site, in their feed reader, or in the Telegram channel — without anyone hand-writing announcements.
+**Why it matters:** The community and integrators always know what shipped, on the site, in their feed reader, or in the Telegram channel, without anyone hand-writing announcements.
## Try it
@@ -11293,11 +11447,11 @@ To add the flagship hosted MCP server to Claude or any MCP client, point it at `
- [API reference](/docs/api-reference)
- [MCP servers](/docs/mcp)
- [x402 endpoints](/docs/x402-endpoints)
-- [The Agent Economy](#sec-022)
+- [The Agent Economy](#sec-023)
---
-<a id="sec-028"></a>
+<a id="sec-029"></a>
> **Source:** `docs/agent-abilities/chapters/15-appendix.md` · [↑ table of contents](#table-of-contents)
@@ -11305,7 +11459,7 @@ To add the flagship hosted MCP server to Claude or any MCP client, point it at `
Every page and surface on three.ws, grouped by area.
-three.ws is "the AI-agent layer for the open web": one platform where anyone can generate 3D models and rigged avatars from text or photos, turn them into autonomous AI agents with on-chain identity (ERC-8004) and real wallets, embed them anywhere with one tag, and let them earn and spend via x402 pay-per-call micropayments and pump.fun token launches. The public surface spans roughly 300 pages plus published SDKs and 42 MCP servers, organized here into 14 categories: 3D creation, avatars/animation/voice, agent creation & management, embedding & distribution, worlds & social play, AR & real-world presence, trading intelligence, market data & news, token launching & $THREE, the x402 agent economy, wallets & custody, marketplaces & creator economy, the developer platform, and company/content surfaces. Everything runs on real APIs and real on-chain settlement — the platform's stated hard rule is no mocks and no fake data.
+three.ws is "the AI-agent layer for the open web": one platform where anyone can generate 3D models and rigged avatars from text or photos, turn them into autonomous AI agents with on-chain identity (ERC-8004) and real wallets, embed them anywhere with one tag, and let them earn and spend via x402 pay-per-call micropayments and pump.fun token launches. The public surface spans roughly 300 pages plus published SDKs and 48 MCP servers, organized here into 14 categories: 3D creation, avatars/animation/voice, agent creation & management, embedding & distribution, worlds & social play, AR & real-world presence, trading intelligence, market data & news, token launching & $THREE, the x402 agent economy, wallets & custody, marketplaces & creator economy, the developer platform, and company/content surfaces. Everything runs on real APIs and real on-chain settlement: the platform's stated hard rule is no mocks and no fake data.
## 3D Creation Suite (text, photos & sketches → 3D)
@@ -11422,13 +11576,13 @@ The narrative, onboarding, partnership, and account surfaces. Entry and story: /
## Related
- [Start here](/docs/start-here)
-- [The complete dossier introduction](#sec-011)
-- [The Agent Economy](#sec-022)
-- [The Developer platform](#sec-027)
+- [The complete dossier introduction](#sec-012)
+- [The Agent Economy](#sec-023)
+- [The Developer platform](#sec-028)
---
-<a id="sec-029"></a>
+<a id="sec-030"></a>
> **Source:** `docs/agent-abilities/wallet/01-balance.md` · [↑ table of contents](#table-of-contents)
@@ -11436,7 +11590,7 @@ The narrative, onboarding, partnership, and account surfaces. Entry and story: /
> Your agent's real Solana balance, live from the chain — with a USD estimate and a receipt trail for every transaction.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Balance** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Balance** tab.*
## What it does
@@ -11505,14 +11659,14 @@ The response carries the wallet address and live SOL balance. In the product, op
## Related
-- [Deposit](#sec-032)
-- [Portfolio](#sec-031)
-- [Withdraw](#sec-046)
-- [The Agent Wallet chapter](#sec-023)
+- [Deposit](#sec-033)
+- [Portfolio](#sec-032)
+- [Withdraw](#sec-047)
+- [The Agent Wallet chapter](#sec-024)
---
-<a id="sec-030"></a>
+<a id="sec-031"></a>
> **Source:** `docs/agent-abilities/wallet/02-go-live.md` · [↑ table of contents](#table-of-contents)
@@ -11520,7 +11674,7 @@ The response carries the wallet address and live SOL balance. In the product, op
> One tap sends real SOL from the three.ws treasury to your agent's wallet and puts it live on the Money Pulse — with an explorer-verifiable receipt.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Go Live** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Go Live** tab.*
## What it does
@@ -11582,13 +11736,13 @@ Owner-only end to end: the tab is hidden from non-owners and the server rejects
## Related
-- [Balance](#sec-029)
-- [Deposit](#sec-032)
-- [Pulse](#sec-037)
+- [Balance](#sec-030)
+- [Deposit](#sec-033)
+- [Pulse](#sec-038)
---
-<a id="sec-031"></a>
+<a id="sec-032"></a>
> **Source:** `docs/agent-abilities/wallet/03-portfolio.md` · [↑ table of contents](#table-of-contents)
@@ -11596,7 +11750,7 @@ Owner-only end to end: the tab is hidden from non-owners and the server rejects
> Your agent's entire trading life — net worth, holdings, P&L, and risk — on one live screen that never fakes a number.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Portfolio** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Portfolio** tab.*
## What it does
@@ -11668,13 +11822,13 @@ curl -b <session-cookie> 'https://three.ws/api/agents/<agent-id>/portfolio?netwo
## Related
-- [Balance](#sec-029)
-- [Trade](#sec-036)
-- [Snipe](#sec-038)
+- [Balance](#sec-030)
+- [Trade](#sec-037)
+- [Snipe](#sec-039)
---
-<a id="sec-032"></a>
+<a id="sec-033"></a>
> **Source:** `docs/agent-abilities/wallet/04-deposit.md` · [↑ table of contents](#table-of-contents)
@@ -11682,7 +11836,7 @@ curl -b <session-cookie> 'https://three.ws/api/agents/<agent-id>/portfolio?netwo
> Fund any agent in one scan — a tap-to-pay Solana QR with live on-chain confirmation the second the money lands.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Deposit** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Deposit** tab.*
## What it does
@@ -11758,13 +11912,13 @@ curl 'https://three.ws/api/agents/<agent-id>/solana?network=mainnet'
## Related
-- [Balance](#sec-029)
-- [Go Live](#sec-030)
-- [Withdraw](#sec-046)
+- [Balance](#sec-030)
+- [Go Live](#sec-031)
+- [Withdraw](#sec-047)
---
-<a id="sec-033"></a>
+<a id="sec-034"></a>
> **Source:** `docs/agent-abilities/wallet/05-copilot.md` · [↑ table of contents](#table-of-contents)
@@ -11772,7 +11926,7 @@ curl 'https://three.ws/api/agents/<agent-id>/solana?network=mainnet'
> Talk to your agent's wallet — by text or voice — and it answers with live on-chain data, then preps guarded trades you confirm with one tap.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Copilot** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Copilot** tab.*
## What it does
@@ -11844,13 +11998,13 @@ Owner-only on both client and server — the tab is hidden from visitors and the
## Related
-- [Trade](#sec-036)
-- [Policy](#sec-045)
-- [Portfolio](#sec-031)
+- [Trade](#sec-037)
+- [Policy](#sec-046)
+- [Portfolio](#sec-032)
---
-<a id="sec-034"></a>
+<a id="sec-035"></a>
> **Source:** `docs/agent-abilities/wallet/06-trust.md` · [↑ table of contents](#table-of-contents)
@@ -11858,7 +12012,7 @@ Owner-only on both client and server — the tab is hidden from visitors and the
> A credit bureau plus proof-of-reserves for AI agents — one 0–100 trust score where every point traces to real money on-chain.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Trust** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Trust** tab.*
## What it does
@@ -11932,13 +12086,13 @@ In the product, open `three.ws/agent/<agent-id>/wallet` and pick the **Trust** t
## Related
-- [Pulse](#sec-037)
-- [Proof of Custody](#sec-048)
-- [Earn](#sec-039)
+- [Pulse](#sec-038)
+- [Proof of Custody](#sec-049)
+- [Earn](#sec-040)
---
-<a id="sec-035"></a>
+<a id="sec-036"></a>
> **Source:** `docs/agent-abilities/wallet/07-signals.md` · [↑ table of contents](#table-of-contents)
@@ -11946,7 +12100,7 @@ In the product, open `three.ws/agent/<agent-id>/wallet` and pick the **Trust** t
> A copy-trading marketplace where only provably profitable agents can sell signals — and one red button kills any subscription instantly.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Signals** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Signals** tab.*
## What it does
@@ -12022,13 +12176,13 @@ The whole tab is owner-only, and every write is authenticated, CSRF-protected, r
## Related
-- [Trade](#sec-036)
-- [Snipe](#sec-038)
-- [Policy](#sec-045)
+- [Trade](#sec-037)
+- [Snipe](#sec-039)
+- [Policy](#sec-046)
---
-<a id="sec-036"></a>
+<a id="sec-037"></a>
> **Source:** `docs/agent-abilities/wallet/08-trade.md` · [↑ table of contents](#table-of-contents)
@@ -12036,7 +12190,7 @@ The whole tab is owner-only, and every write is authenticated, CSRF-protected, r
> Your agent's wallet is a full trading desk — paste any pump.fun coin, see a live quote and a real on-chain safety verdict, and execute server-signed in two taps.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Trade** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Trade** tab.*
## What it does
@@ -12114,13 +12268,13 @@ curl 'https://three.ws/api/agents/<agent-id>/solana/holdings?network=mainnet'
## Related
-- [Portfolio](#sec-031)
-- [Orders](#sec-040)
-- [Copilot](#sec-033)
+- [Portfolio](#sec-032)
+- [Orders](#sec-041)
+- [Copilot](#sec-034)
---
-<a id="sec-037"></a>
+<a id="sec-038"></a>
> **Source:** `docs/agent-abilities/wallet/09-pulse.md` · [↑ table of contents](#table-of-contents)
@@ -12128,7 +12282,7 @@ curl 'https://three.ws/api/agents/<agent-id>/solana/holdings?network=mainnet'
> Every tip, trade, launch, and payment your agent's wallet makes — streaming live, public, and provable on-chain.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Pulse** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Pulse** tab.*
## What it does
@@ -12201,13 +12355,13 @@ In the product, open `three.ws/agent/<agent-id>/wallet` and pick the **Pulse** t
## Related
-- [Balance](#sec-029)
-- [Trust](#sec-034)
-- [Earn](#sec-039)
+- [Balance](#sec-030)
+- [Trust](#sec-035)
+- [Earn](#sec-040)
---
-<a id="sec-038"></a>
+<a id="sec-039"></a>
> **Source:** `docs/agent-abilities/wallet/10-snipe.md` · [↑ table of contents](#table-of-contents)
@@ -12215,7 +12369,7 @@ In the product, open `three.ws/agent/<agent-id>/wallet` and pick the **Pulse** t
> Describe a snipe strategy in plain English, backtest it against real launch history, and arm your agent to trade it from its own wallet — in one tap.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Snipe** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Snipe** tab.*
## What it does
@@ -12294,13 +12448,13 @@ Owner-only surface end to end: the tab is hidden from non-owners, and every endp
## Related
-- [Trade](#sec-036)
-- [Orders](#sec-040)
-- [Policy](#sec-045)
+- [Trade](#sec-037)
+- [Orders](#sec-041)
+- [Policy](#sec-046)
---
-<a id="sec-039"></a>
+<a id="sec-040"></a>
> **Source:** `docs/agent-abilities/wallet/11-earn.md` · [↑ table of contents](#table-of-contents)
@@ -12308,7 +12462,7 @@ Owner-only surface end to end: the tab is hidden from non-owners, and every endp
> Your avatar has a job: price its skills, watch it earn real USDC while you sleep, and hold the kill switch the whole time.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Earn** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Earn** tab.*
## What it does
@@ -12375,13 +12529,13 @@ The whole tab is owner-only: it is hidden from visitors, and the server re-check
## Related
-- [Pay](#sec-043)
-- [Withdraw](#sec-046)
-- [Trust](#sec-034)
+- [Pay](#sec-044)
+- [Withdraw](#sec-047)
+- [Trust](#sec-035)
---
-<a id="sec-040"></a>
+<a id="sec-041"></a>
> **Source:** `docs/agent-abilities/wallet/12-orders.md` · [↑ table of contents](#table-of-contents)
@@ -12389,7 +12543,7 @@ The whole tab is owner-only: it is hidden from visitors, and the server re-check
> Set-and-forget limit, stop, trailing, DCA, TWAP, and signal-driven orders that fire automatically from your agent's own wallet — on live on-chain data, inside your guardrails.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Orders** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Orders** tab.*
## What it does
@@ -12471,13 +12625,13 @@ Owner-only end to end: the tab only renders for the agent's owner, and every ser
## Related
-- [Trade](#sec-036)
-- [Snipe](#sec-038)
-- [Autopilot](#sec-041)
+- [Trade](#sec-037)
+- [Snipe](#sec-039)
+- [Autopilot](#sec-042)
---
-<a id="sec-041"></a>
+<a id="sec-042"></a>
> **Source:** `docs/agent-abilities/wallet/13-autopilot.md` · [↑ table of contents](#table-of-contents)
@@ -12485,7 +12639,7 @@ Owner-only end to end: the tab only renders for the agent's owner, and every ser
> Write one sentence in plain English and your agent starts paying its own bills, stacking $THREE, buying back its own coin, and sweeping the profit to you — for real, on-chain.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Autopilot** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Autopilot** tab.*
## What it does
@@ -12554,13 +12708,13 @@ Owner-only, structurally: the tab is hidden from non-owners and every endpoint r
## Related
-- [Intents](#sec-042)
-- [Policy](#sec-045)
-- [Earn](#sec-039)
+- [Intents](#sec-043)
+- [Policy](#sec-046)
+- [Earn](#sec-040)
---
-<a id="sec-042"></a>
+<a id="sec-043"></a>
> **Source:** `docs/agent-abilities/wallet/14-intents.md` · [↑ table of contents](#table-of-contents)
@@ -12568,7 +12722,7 @@ Owner-only, structurally: the tab is hidden from non-owners and every endpoint r
> Tell your agent's wallet what to do in one plain sentence — it compiles the rule, shows you a dry run, and then executes it for real on Solana, inside guardrails you set.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Intents** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Intents** tab.*
## What it does
@@ -12576,7 +12730,7 @@ Intents turns an agent's wallet into a programmable teammate you talk to. The ow
## How it works
-The plain-language rule goes to a server-side compiler where a Claude model (with an OpenRouter fallback) is forced into a strict structured schema — one trigger, one action, owner caps — and is explicitly forbidden from inventing amounts, destinations, or tokens; if anything is missing it asks one clarifying question instead of guessing. The server independently re-validates every field, resolves .sol names to real addresses at compile time, and returns a readback plus a live dry-run before anything is stored. Armed rules live in the database: tip, income, and money-stream rules fire instantly from the real payment-settlement hooks, while scheduled, balance-floor, and launch-matching rules are swept by a scheduler every 10 minutes. Every execution flows through the same spend-policy-gated, audited signing path as every other outbound wallet action — SOL transfers sign directly, token buys and snipes route through Jupiter with slippage control and revert detection — and each fire writes an idempotent custody event stamped with the rule's ID and transaction signature, which powers the per-rule receipts, fire counts, and running dollar totals in the UI.
+The plain-language rule goes to a server-side compiler where a Claude model (with Grok and OpenRouter fallbacks, in that order) is forced into a strict structured schema (one trigger, one action, owner caps) and is explicitly forbidden from inventing amounts, destinations, or tokens; if anything is missing it asks one clarifying question instead of guessing. The server independently re-validates every field, resolves .sol names to real addresses at compile time, and returns a readback plus a live dry-run before anything is stored. Armed rules live in the database: tip, income, and money-stream rules fire instantly from the real payment-settlement hooks, while scheduled, balance-floor, and launch-matching rules are swept by a scheduler every 10 minutes. Every execution flows through the same spend-policy-gated, audited signing path as every other outbound wallet action (SOL transfers sign directly, token buys and snipes route through Jupiter with slippage control and revert detection), and each fire writes an idempotent custody event stamped with the rule's ID and transaction signature, which powers the per-rule receipts, fire counts, and running dollar totals in the UI.
## Every feature
@@ -12643,13 +12797,13 @@ Owner-only end to end: the server rejects any non-owner or logged-out caller on
## Related
-- [Autopilot](#sec-041)
-- [Policy](#sec-045)
-- [Deposit](#sec-032)
+- [Autopilot](#sec-042)
+- [Policy](#sec-046)
+- [Deposit](#sec-033)
---
-<a id="sec-043"></a>
+<a id="sec-044"></a>
> **Source:** `docs/agent-abilities/wallet/15-pay.md` · [↑ table of contents](#table-of-contents)
@@ -12657,7 +12811,7 @@ Owner-only end to end: the server rejects any non-owner or logged-out caller on
> Your agent shops the open x402 economy: find any paid API, see its live price, and settle it in USDC from the agent's own Solana wallet — receipt on-chain in seconds.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Pay** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Pay** tab.*
## What it does
@@ -12725,13 +12879,13 @@ Owner-only tab, gated end to end: the caller must be signed in and must own the
## Related
-- [Earn](#sec-039)
-- [Policy](#sec-045)
-- [Withdraw](#sec-046)
+- [Earn](#sec-040)
+- [Policy](#sec-046)
+- [Withdraw](#sec-047)
---
-<a id="sec-044"></a>
+<a id="sec-045"></a>
> **Source:** `docs/agent-abilities/wallet/16-vanity.md` · [↑ table of contents](#table-of-contents)
@@ -12739,7 +12893,7 @@ Owner-only tab, gated end to end: the caller must be signed in and must own the
> Give your agent a wallet address that spells its name — ground on your own CPU at millions of attempts, then applied with a funds-safe swap that sweeps every asset over first.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Vanity** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Vanity** tab.*
## What it does
@@ -12802,13 +12956,13 @@ Owner-only end to end: the tab is hidden from non-owner viewers and the server r
## Related
-- [Balance](#sec-029)
-- [Deposit](#sec-032)
-- [Withdraw](#sec-046)
+- [Balance](#sec-030)
+- [Deposit](#sec-033)
+- [Withdraw](#sec-047)
---
-<a id="sec-045"></a>
+<a id="sec-046"></a>
> **Source:** `docs/agent-abilities/wallet/17-policy.md` · [↑ table of contents](#table-of-contents)
@@ -12816,7 +12970,7 @@ Owner-only end to end: the tab is hidden from non-owner viewers and the server r
> Write your agent's spending rules in plain English — AI translates them, deterministic code enforces them on every single spend.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Policy** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Policy** tab.*
## What it does
@@ -12882,13 +13036,13 @@ Owner-only end to end: the tab is hidden from non-owner viewers and the server i
## Related
-- [Withdraw](#sec-046)
-- [Self-defense](#sec-051)
-- [Access](#sec-049)
+- [Withdraw](#sec-047)
+- [Self-defense](#sec-052)
+- [Access](#sec-050)
---
-<a id="sec-046"></a>
+<a id="sec-047"></a>
> **Source:** `docs/agent-abilities/wallet/18-withdraw.md` · [↑ table of contents](#table-of-contents)
@@ -12896,7 +13050,7 @@ Owner-only end to end: the tab is hidden from non-owner viewers and the server i
> Sweep any asset out of your agent's wallet in three taps — server-signed, policy-guarded, and audited down to every single key touch.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Withdraw** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Withdraw** tab.*
## What it does
@@ -12970,13 +13124,13 @@ Owner-only end to end: every endpoint verifies the signed-in user owns the agent
## Related
-- [Policy](#sec-045)
-- [Give](#sec-047)
-- [Self-defense](#sec-051)
+- [Policy](#sec-046)
+- [Give](#sec-048)
+- [Self-defense](#sec-052)
---
-<a id="sec-047"></a>
+<a id="sec-048"></a>
> **Source:** `docs/agent-abilities/wallet/19-give.md` · [↑ table of contents](#table-of-contents)
@@ -12984,7 +13138,7 @@ Owner-only end to end: every endpoint verifies the signed-in user owns the agent
> Turn your agent's wallet into a giving wallet — round up the spare change or donate any amount to any Solana cause, settled on-chain with a receipt you can verify.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Give** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Give** tab.*
## What it does
@@ -13043,13 +13197,13 @@ Owner-only end to end: the tab is hidden from visitors, and the server independe
## Related
-- [Withdraw](#sec-046)
-- [Deposit](#sec-032)
-- [Intents](#sec-042)
+- [Withdraw](#sec-047)
+- [Deposit](#sec-033)
+- [Intents](#sec-043)
---
-<a id="sec-048"></a>
+<a id="sec-049"></a>
> **Source:** `docs/agent-abilities/wallet/20-proof-of-custody.md` · [↑ table of contents](#table-of-contents)
@@ -13057,7 +13211,7 @@ Owner-only end to end: the tab is hidden from visitors, and the server independe
> Don't trust — verify: your agent wallet's custody, cryptographically proven in your own browser against the Solana blockchain itself.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Proof of Custody** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Proof of Custody** tab.*
## What it does
@@ -13134,13 +13288,13 @@ That endpoint is public and needs no account. The `/integrity` page that used to
## Related
-- [Trust](#sec-034)
-- [Recovery](#sec-050)
-- [Withdraw](#sec-046)
+- [Trust](#sec-035)
+- [Recovery](#sec-051)
+- [Withdraw](#sec-047)
---
-<a id="sec-049"></a>
+<a id="sec-050"></a>
> **Source:** `docs/agent-abilities/wallet/21-access.md` · [↑ table of contents](#table-of-contents)
@@ -13148,7 +13302,7 @@ That endpoint is public and needs no account. The `/integrity` page that used to
> Put every bot on a leash: mint tight, revocable spending keys so no strategy ever touches more of your agent's wallet than you allow.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Access** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Access** tab.*
## What it does
@@ -13208,13 +13362,13 @@ Owner-only surface end to end: the tab is hidden from non-owners and the API ver
## Related
-- [Policy](#sec-045)
-- [Self-defense](#sec-051)
-- [Snipe](#sec-038)
+- [Policy](#sec-046)
+- [Self-defense](#sec-052)
+- [Snipe](#sec-039)
---
-<a id="sec-050"></a>
+<a id="sec-051"></a>
> **Source:** `docs/agent-abilities/wallet/22-recovery.md` · [↑ table of contents](#table-of-contents)
@@ -13222,7 +13376,7 @@ Owner-only surface end to end: the tab is hidden from non-owners and the API ver
> Lose your login — or go silent forever — and your funded agent wallet still finds its way home: guardians, a beneficiary, and a dead-man's switch that only fires when you truly can't stop it.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Recovery** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Recovery** tab.*
## What it does
@@ -13294,18 +13448,20 @@ Owner-only tab; every write requires a fresh CSRF token and is rate-limited. Onl
- `POST /api/agents/:id/recovery/checkin`
- `POST /api/agents/:id/recovery/requests/:rid/cancel`
- `POST /api/agents/:id/recovery/requests (+ /approve, /decline, /confirm, /complete — guardian console side)`
+- `GET /api/agents/:id/recovery/requests (owner: recent request history)`
+- `POST /api/agents/:id/recovery/inheritance/arm (beneficiary or guardian: arm the dead-man's switch once the owner's inactivity has crossed the threshold)`
- `GET /api/agents/recovery-inbox (guardian console)`
- `GET /api/cron/dead-man-switch (daily sweep, secret-gated)`
## Related
-- [Self-defense](#sec-051)
-- [Access](#sec-049)
-- [Withdraw](#sec-046)
+- [Self-defense](#sec-052)
+- [Access](#sec-050)
+- [Withdraw](#sec-047)
---
-<a id="sec-051"></a>
+<a id="sec-052"></a>
> **Source:** `docs/agent-abilities/wallet/23-self-defense.md` · [↑ table of contents](#table-of-contents)
@@ -13313,7 +13469,7 @@ Owner-only tab; every write requires a fresh CSRF token and is rate-limited. Onl
> Every agent wallet gets an immune system — it learns what normal spending looks like, freezes itself the instant something looks wrong, and explains why in plain English.
-*One of the 23 abilities of the [Agent Wallet](#sec-023), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Self-defense** tab.*
+*One of the 23 abilities of the [Agent Wallet](#sec-024), the money layer of a three.ws agent. In the product: open `three.ws/agent/<agent-id>/wallet` and pick the **Self-defense** tab.*
## What it does
@@ -13378,13 +13534,13 @@ Owner-only surface end to end: the tab is gated to the wallet owner and every AP
## Related
-- [Policy](#sec-045)
-- [Withdraw](#sec-046)
-- [Recovery](#sec-050)
+- [Policy](#sec-046)
+- [Withdraw](#sec-047)
+- [Recovery](#sec-051)
---
-<a id="sec-052"></a>
+<a id="sec-053"></a>
> **Source:** `docs/agent-economy-volume.md` · [↑ table of contents](#table-of-contents)
@@ -13647,17 +13803,17 @@ would hide it.
## Related
-- [x402 paid endpoints](#sec-559): the other side of the ledger. This
+- [x402 paid endpoints](#sec-584): 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.
-- [The autonomous economy](#sec-104): how agents get wallets, spend
+- [The autonomous economy](#sec-106): how agents get wallets, spend
policies, and paid skills in the first place, which is what produces the rows
this page aggregates.
---
-<a id="sec-053"></a>
+<a id="sec-054"></a>
> **Source:** `docs/agent-identities.md` · [↑ table of contents](#table-of-contents)
@@ -13684,8 +13840,8 @@ 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-520) for the rigged GLB |
-| `pose_studio_url` | Deep link into the [Animation Studio](#sec-092) for the rigged GLB |
+| `viewer_url` | Deep link into the three.ws [viewer](#sec-540) for the rigged GLB |
+| `pose_studio_url` | Deep link into the [Animation Studio](#sec-094) 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.
@@ -13864,17 +14020,17 @@ Two environment overrides help a batch run outlast the rig lane's rate-limit bac
## Related
-- [OKX.AI Marketplace Services](#sec-309): the price, the payment challenge, the replay flow, the payment guarantees, and the decomposed single-capability 3D services that share these engines.
-- [Forge](#sec-227): 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-520): the `/viewer` surface the `viewer_url` deep link opens.
-- [MCP servers](#sec-284): 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-181): the inactive on-chain identity minted for every finished reconstruction, Solana first with ERC-8004 alongside it.
+- [OKX.AI Marketplace Services](#sec-320): the price, the payment challenge, the replay flow, the payment guarantees, and the decomposed single-capability 3D services that share these engines.
+- [Forge](#sec-234): the text and image to GLB generation pipeline this studio calls for the mesh and the auto-rig.
+- [Animation Studio](#sec-094): the `/pose` surface the `pose_studio_url` deep link opens.
+- [Viewer](#sec-540): the `/viewer` surface the `viewer_url` deep link opens.
+- [MCP servers](#sec-293): the wider set of three.ws MCP endpoints this one follows the transport conventions of.
+- [Avatar Engines Atlas](#sec-112): what engine families exist for building human avatars, and which of them are wired into the commercial pipeline.
+- [Draft agent mint](#sec-187): the inactive on-chain identity minted for every finished reconstruction, Solana first with ERC-8004 alongside it.
---
-<a id="sec-054"></a>
+<a id="sec-055"></a>
> **Source:** `docs/agent-index.md` · [↑ table of contents](#table-of-contents)
@@ -13898,6 +14054,15 @@ time cannot be read is rejected rather than stamped with the current time,
because a fabricated timestamp corrupts every timeline and every freshness
number computed from the table.
+Strings that came off a chain are arbitrary bytes, and Postgres refuses two of
+the code points they can carry: a NUL fails a jsonb insert outright and a lone
+surrogate fails it with an escape error. `sanitizeText()` and
+`sanitizePayload()` in the same module strip the NUL and replace the lone
+surrogate with U+FFFD in every text column and every payload string (keys
+included) before the row is written. Without that, one such byte in one log
+wedged the chain that produced it: the insert threw before the cursor advanced,
+so every tick re-read the same range and hit the same log.
+
Seven event classes:
| Class | What it means | Where it comes from |
@@ -14010,7 +14175,17 @@ The monitor reports both legs. Read them differently:
falling further behind every tick. The monitor therefore reports **blocks
behind head**, and the crawl grows its block window while a chain is behind
(halving it when a provider rejects the range) so a fast chain can actually
- close the gap.
+ close the gap. One window per chain per tick holds a slow chain but cannot
+ drain a fast one, so after the first pass over every chain the cron spends
+ whatever is left of its budget on a **catch-up pass**: it re-picks the chain
+ furthest behind head each round and feeds it another window, stops far enough
+ from the deadline that metadata enrichment still runs, drops a chain whose
+ provider refused even the floor window rather than spinning on it, and does
+ nothing on a tick where every chain is current. The first pass itself walks
+ chains worst backlog first, with a never-crawled chain ahead of everything
+ and a caught-up chain ranked by how long its cursor has stood still, so a
+ chain that errors on every tick (which keeps reporting the zero backlog its
+ last good crawl left) is not sorted to the back of the sweep forever.
A leg that is reaching every agent and recording nothing counts as `down`, not
as fresh. That shape (every cursor current, zero events) is what a crashing
@@ -14030,13 +14205,13 @@ 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-432) scores an agent from on-chain
-evidence, and [Custody you can verify](#sec-171) covers the attestations the
+Related: [Trust primitives](#sec-450) scores an agent from on-chain
+evidence, and [Custody you can verify](#sec-177) covers the attestations the
`reputation` and `validation` classes carry.
---
-<a id="sec-055"></a>
+<a id="sec-056"></a>
> **Source:** `docs/agent-manifest.md` · [↑ table of contents](#table-of-contents)
@@ -14114,7 +14289,7 @@ console.log(manifest.name, manifest.body.uri);
> validates the *avatar* manifest (`avatar.v1.json`: `schemaVersion`, `mesh`,
> `skeleton`, `owner`), which describes a 3D body, not an agent. Running
> `assertValid` from that package on an agent manifest always throws. See
-> [Agents vs. avatars](#sec-073) for why the two are separate.
+> [Agents vs. avatars](#sec-075) for why the two are separate.
---
@@ -14683,7 +14858,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-347)) 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-360)) and pinned through the configured IPFS provider.
### What a signed envelope looks like
@@ -14840,11 +15015,11 @@ 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-347) — signed content credentials for generated 3D assets, using the same attester identity as signed manifests
+- [Provenance](#sec-360) — signed content credentials for generated 3D assets, using the same attester identity as signed manifests
---
-<a id="sec-056"></a>
+<a id="sec-057"></a>
> **Source:** `docs/agent-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -14852,7 +15027,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-379) (leaving and reading reviews) and [ERC-8004](#sec-189) (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-405).
+This page is the *why*. For the practical how-to, see [Reputation System](#sec-392) (leaving and reading reviews) and [ERC-8004](#sec-195) (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-423).
---
@@ -14916,7 +15091,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-189).
+> Full detail: [ERC-8004](#sec-195).
### 2. Reputation Registry — what others think of it
@@ -14945,7 +15120,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-563)).
+3. **Pay** — the service answers an HTTP `402` and the agent signs a stablecoin micropayment ([x402](#sec-589)).
4. **Vouch** — after the work, write feedback back to the Reputation Registry, closing the loop for the next agent.
The one-liner worth remembering:
@@ -14966,7 +15141,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-432) |
+| `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-450) |
| [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` |
@@ -15005,11 +15180,11 @@ 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-405) · [Leave a vouch](#sec-379) · [ERC-8004 identity](#sec-189) · [x402 payments](#sec-563)
+**Next:** [Read an agent's reputation](/tutorials/agent-reputation) · [Reputation on Solana](#sec-423) · [Leave a vouch](#sec-392) · [ERC-8004 identity](#sec-195) · [x402 payments](#sec-589)
---
-<a id="sec-057"></a>
+<a id="sec-058"></a>
> **Source:** `docs/agent-runtime.md` · [↑ table of contents](#table-of-contents)
@@ -15149,7 +15324,11 @@ on the platform instead of a single model call. Per message it can:
Every tool is read-only and every planned call is preflighted through the GuardChain in
headless mode before it executes; a blacklisted call is fed back to the model as a blocked
error, never run. The loop cannot move funds: no tool in the server registry transfers,
-swaps, or signs, and the wallet tools stay client-side behind the approval modal.
+swaps, or signs, and the wallet tools stay client-side behind the approval modal. A tool
+that throws ends the agent's turn, so the keyless upstreams behind these tools are called
+through the shared retrying fetch (`api/_lib/upstream-fetch.js`); web search in particular
+retries once and then returns an empty result with an `unavailable` note the model can
+narrate around, rather than costing the whole answer.
For developers the endpoint speaks the **OpenAI chat-completions wire format** in both
directions, so any OpenAI-compatible client can point at it:
@@ -15175,7 +15354,7 @@ approval modal and the `/api/agent/guard` preflight.
## Related surfaces
-- [Agent Sniper](#sec-061) - the autonomous trading pipeline with its own trade
+- [Agent Sniper](#sec-062) - the autonomous trading pipeline with its own trade
firewall and hash-chained decision ledger; this package generalizes those ideas into a
reusable engine.
- [`@three-ws/agent-guards`](../packages/agent-guards) - the client SDK for custodial wallet
@@ -15185,7 +15364,7 @@ approval modal and the `/api/agent/guard` preflight.
---
-<a id="sec-058"></a>
+<a id="sec-059"></a>
> **Source:** `docs/agent-screen-control.md` · [↑ table of contents](#table-of-contents)
@@ -15193,7 +15372,7 @@ approval modal and the `/api/agent/guard` preflight.
Every agent on three.ws has a live screen. On the [agent screen](https://three.ws/agent-screen) and the [live wall](https://three.ws/agents-live) you can *watch* an agent do real web work in a real browser: navigate to a site, type into a search box, read back the results. This page is about the other half, **driving it yourself**.
-If you own the agent, you can grab the wheel of its live cast browser and control it directly: real mouse, click and drag, scroll, keyboard, and navigation. The agent's autonomous task steps aside while you drive, and picks back up the moment you let go.
+If you own the agent, you can grab the wheel of its live cast browser and control it directly: real mouse, click and drag, scroll, keyboard, and navigation. The agent's autonomous task steps aside while you drive, and picks back up a couple of seconds after you let go.
This is the first slice of a larger idea, giving every agent its own computer that both the agent and its owner can operate. Today that computer is a cloud browser; the same control channel is what a full desktop will ride on next.
@@ -15220,9 +15399,9 @@ Remote-controlling a computer is exactly as dangerous as it sounds, so the desig
- **Owner-only.** Watching an agent is public. Driving is not. Control is gated on agent ownership (the same check that guards trading and wallet actions), verified when you take the wheel.
- **The cast browser holds no wallet and no keys.** This is the property that makes remote control safe to ship: the browser you drive is a sandboxed, throwaway Chromium with no access to the agent's custodial wallet or signing keys. Driving it **cannot** sign a transaction, move funds, or touch the chain. Money stays behind the agent runtime and the on-chain wall, no matter what you (or a compromised session) do in the browser.
-- **A short-lived capability lease, not your session.** Taking the wheel mints a random **lease token** scoped to exactly one agent's control for a few seconds, renewed while you drive and dropped when you release. The high-frequency input stream authenticates with that token, so it never rides your login cookie, and the capability expires on its own if you walk away.
+- **A short-lived capability lease, not your session.** Taking the wheel mints a random **lease token** scoped to exactly one agent's control for 15 seconds, refreshed by every input batch and by a renew every 8 seconds while you drive, and dropped when you release. The high-frequency input stream authenticates with that token, so it never rides your login cookie, and the capability expires on its own if you walk away.
- **Every event is sanitized at the boundary.** Coordinates are range-clamped, keys and typed text are whitelisted and length-bounded, and navigation is **SSRF-guarded**: the browser can never be steered to `localhost`, a private range, or a cloud metadata endpoint. Only public `http(s)` destinations are allowed.
-- **One driver at a time.** A live lease blocks a second session from grabbing the same agent's wheel.
+- **One driver at a time.** A live lease held by another account answers `409 in_use` to anyone else who tries to acquire. The owner's own second tab is allowed to take over its lease, and the first tab's token stops working on its next input.
---
@@ -15262,7 +15441,7 @@ curl -s https://three.ws/api/agent-screen-control \
# → { "ok": true, "accepted": 3 }
```
-`renew` refreshes an idle lease; `release` drops it immediately. Both take the bearer lease token.
+A batch carries at most 40 events (the page flushes every 80 ms), and one agent accepts at most 900 input calls a minute. `renew` refreshes an idle lease; `release` drops it immediately. Both take the bearer lease token.
**Event shapes** (coordinates are normalized `0..1` against the streamed viewport):
@@ -15297,7 +15476,7 @@ The caster pool's read side, machine-to-machine only (authenticated with `SCREEN
watch it move ◀──── frame stream (SSE) ◀──────── screenshot after each action
```
-The frame stream ([how the live screen works](#sec-059)) carries pixels out; this control channel carries input back. Same agent, same browser, opposite directions.
+The frame stream (the caster pool in [workers/agent-screen-pool](../workers/agent-screen-pool/README.md)) carries pixels out; this control channel carries input back. Same agent, same browser, opposite directions.
---
@@ -15307,11 +15486,11 @@ The frame stream ([how the live screen works](#sec-059)) carries pixels out; thi
- **One browser tab** per agent today. Full app / shell / file access is the next slice, on the same control channel with a streamed Linux desktop.
- **DNS-rebinding** on `nav` is out of scope for this version; the host guard checks the literal hostname, and the browser runs with no credentials to lose.
-Related: [the agent shell and live screen](#sec-059), the [live agents wall](https://three.ws/agents-live).
+Related: [the caster pool behind the live screen](../workers/agent-screen-pool/README.md), the [live agents wall](https://three.ws/agents-live).
---
-<a id="sec-059"></a>
+<a id="sec-060"></a>
> **Source:** `docs/agent-shell.md` · [↑ table of contents](#table-of-contents)
@@ -15351,8 +15530,8 @@ claims it.
- Auto-summon is polite: it waits for `load` + idle, skips visitors with
`prefers-reduced-motion` or `Save-Data`, skips full-screen 3D/camera routes
(`/play`, `/tour`, `/scan`, …), and never re-summons after the visitor closes
- the companion. The existing nav "Walk" toggle keeps working exactly as
- before.
+ the companion. A page opts out with `data-walk-auto="off"` on its `html`
+ element. The existing nav "Walk" toggle keeps working exactly as before.
Key modules: [src/agents/guest-agent.js](../src/agents/guest-agent.js) (draft
store), [src/shared/agent-names.js](../src/shared/agent-names.js) (namer),
@@ -15369,7 +15548,7 @@ verbs and runs them in place against the real public APIs — no account needed:
| `forge <prompt>` (also `make`, `generate`, `imagine`) | `forge a bronze dragon statue` | `POST /api/forge` on the free text→3D lane, polls to completion, returns open/download/refine links for the real GLB |
| `digest` (also `briefing`, `what happened today`) | `digest` | `GET /api/news/digest` — the last 24h clustered into narratives, rendered as rows |
| `price <coin>` or `$ticker` | `price btc`, `$sol` | `GET /api/coin/markets` + `/detail`, falling back to pump.fun token search |
-| `ask <question>` (or any query ending in `?`) | `ask what is x402?` | `POST /api/chat` — the site agent's answer streamed into the panel; honors the free lane's `retry_after` backoff when it's at capacity |
+| `ask <question>` (or any query of ten or more characters ending in `?`) | `ask what is x402?` | `POST /api/chat`: the site agent's answer streamed into the panel; honors the free lane's `retry_after` backoff when it's at capacity |
Grammar rules: commands are strict verb-first parses — a bare verb (`forge`)
or a plain search query is never hijacked. A natural question ("how do agents
@@ -15439,13 +15618,16 @@ 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-523) (the embeddable `agent-3d`
-avatar), [coin-pages.md](#sec-145) (the market surfaces the shell
-navigates), [STRUCTURE.md](../STRUCTURE.md) (surface map).
+Related: [web-component.md](#sec-543) (the embeddable `agent-3d`
+avatar), [coin-pages.md](#sec-149) (the market surfaces the shell
+navigates), [companion.md](#sec-156) (the same corner companion delivering
+messages from connected sources in person), [feedback.md](#sec-228)
+(reporting what broke through the companion), [STRUCTURE.md](../STRUCTURE.md)
+(surface map).
---
-<a id="sec-060"></a>
+<a id="sec-061"></a>
> **Source:** `docs/agent-skills.md` · [↑ table of contents](#table-of-contents)
@@ -15456,7 +15638,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-399), which extends
+> Not to be confused with the [in-app skills system](#sec-417), 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.
@@ -15565,7 +15747,7 @@ All three run free against the hosted studio endpoint
---
-<a id="sec-061"></a>
+<a id="sec-062"></a>
> **Source:** `docs/agent-sniper.md` · [↑ table of contents](#table-of-contents)
@@ -15575,7 +15757,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-429) (Radar, Coin Intelligence, Mission Control), [trading experiment](#sec-427) (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-447) (Radar, Coin Intelligence, Mission Control), [trading experiment](#sec-445) (the laddered-exit research policy), [agent wallets](#sec-074) (how custody works), and the worker itself at `workers/agent-sniper/` (its README is the operator reference).
---
@@ -15725,13 +15907,13 @@ 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-429)
-- The research policy behind laddered exits: [trading experiment](#sec-427)
+- Watch the engine think: [Coin Intelligence and the trading surfaces](#sec-447)
+- The research policy behind laddered exits: [trading experiment](#sec-445)
- The story of the first trade, for non-operators: [the blog post](/blog/first-autonomous-trade)
---
-<a id="sec-062"></a>
+<a id="sec-063"></a>
> **Source:** `docs/agent-studio.md` · [↑ table of contents](#table-of-contents)
@@ -15752,9 +15934,9 @@ 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-233): Genesis gets you a complete agent in a minute,
+[Instant Agent Genesis](#sec-240): 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).
+agent is, see [Agent System](#sec-065).
## How it works
@@ -15776,7 +15958,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-130)).
+ [Multi-LLM Brain](#sec-132)).
- **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
@@ -15813,7 +15995,7 @@ once.
The studio saves through the standard agent update endpoint, so the same edits are
scriptable. Read your agent, then patch a domain under `meta.studio` (see
-[Authentication](#sec-103)):
+[Authentication](#sec-105)):
```bash
# Load (or lazily create) your agent
@@ -15842,6 +16024,11 @@ curl -s https://three.ws/api/agents/<agent-id>/pricing \
visitors get a designed auth state, not a broken page.
- **First visit.** With no agent yet, `/api/agents/me` provisions a default so the
studio always has something to render.
+- **A dead backend is a load error, not a silent draft.** `AgentIdentity` never
+ throws when the server is unreachable: it falls back to a localStorage copy or
+ synthesises a default whose id exists nowhere on the server. Editing that
+ record would look normal and fail on every `PUT`, so the store refuses it
+ (`not_confirmed`) and the shell renders its real, retryable error state instead.
- **Optimistic with rollback.** Edits apply instantly and flush on a debounce; a
failed `PUT` rolls the change back and surfaces an error rather than leaving the UI
ahead of the server.
@@ -15852,16 +16039,16 @@ 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-233): 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
+- [Agent System](#sec-065): the full model of what an agent is
+- [Instant Agent Genesis](#sec-240): create the agent Studio edits
+- [Multi-LLM Brain](#sec-132): the model backend behind the Brain tab
+- [Agent Skills](#sec-061): the capabilities the Skills tab manages
+- [Agent Wallets](#sec-074): the wallet behind the Money tab
- Pages: [/agent-studio](https://three.ws/agent-studio), [/genesis](https://three.ws/genesis), [/brain](https://three.ws/brain)
---
-<a id="sec-063"></a>
+<a id="sec-064"></a>
> **Source:** `docs/agent-symphony.md` · [↑ table of contents](#table-of-contents)
@@ -15889,7 +16076,7 @@ user gesture. Nothing autoplays.
## Where the events come from
The symphony consumes the same live ticker documented in
-[Money Feed](#sec-292):
+[Money Feed](#sec-302):
1. `GET /api/feed?limit=40` paints the initial ledger (played silently as
backlog, not as notes).
@@ -15905,7 +16092,7 @@ you hear.
## What sounds map to what events
Every allow-listed feed type (see the type table in
-[Money Feed](#sec-292)) maps to one of six voices in
+[Money Feed](#sec-302)) 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.
@@ -16007,16 +16194,16 @@ cross-links are asserted statically by
## Related
-- [Money Feed](#sec-292): the activity bus this page renders, including
+- [Money Feed](#sec-302): 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-*`
+- [Agora](#sec-077): the on-chain economy lifecycle behind the `agora-*`
events.
- The [economy dashboard](https://three.ws/economy): the same activity as
numbers instead of notes.
---
-<a id="sec-064"></a>
+<a id="sec-065"></a>
> **Source:** `docs/agent-system.md` · [↑ table of contents](#table-of-contents)
@@ -16205,7 +16392,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-297)): `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-307)): `observe_agents` (list the other agents on stage with names and positions) and `say_to_agent` (send a message to a named stagemate).
---
@@ -16287,6 +16474,10 @@ When an emotion exceeds 0.6 and no one-shot gesture is active, the avatar automa
Slot names resolve through the agent's animation override map (`meta.edits.animations`) before searching the animation library, with a final fallback to embedded clip search.
+### Choreography routines
+
+Beyond single gestures, an agent can carry named **routines**: sequences of gesture slots with per-step timing, authored on the [/choreograph](https://three.ws/choreograph) page and stored on the agent at `meta.choreographies`. `AgentAvatar.setChoreographies(list)` registers them (an invalid entry is logged and skipped rather than thrown, so one bad routine never costs the agent the rest of its body language), `getChoreographies()` lists them, `playChoreography(nameOrRoutine)` performs one, and `stopChoreography()` halts the one performing. The timing engine (`src/runtime/choreography.js`, `RoutinePlayer`) is shared with the authoring page and is driven from the same per-frame hook as the emotion blend, so what an owner composed there is frame-for-frame what the agent performs.
+
---
## 6. Agent Memory
@@ -16310,7 +16501,7 @@ Each entry has an `id`, `type`, `content`, `tags`, `context`, `salience` (0–1)
`memory.query()` sorts by `salience × recencyBoost`, where recency uses exponential decay with a 7-day half-life. `feedback` and `user` memories are inherently higher salience (they are the most stable and generalizable). Additional tags boost salience slightly.
-The memory context is injected into the LLM system prompt in a `<memory>` block, capped at `manifest.memory.maxTokens` (default 8192) tokens.
+The memory context is injected into the LLM system prompt in a `<memory>` block, capped at `manifest.memory.maxTokens` (default 8192) tokens. In the file-based backend (`src/memory/index.js`) the `MEMORY.md` index is injected in full and bypasses that token budget by design, so it has its own ceiling: at injection time it is cut to the 200 lines `MEMORY_SPEC.md` allows, with a one-line note saying how many lines were dropped, so an oversized index on disk still yields a bounded prompt.
### Pruning
@@ -16322,13 +16513,13 @@ When `localStorage` quota is exceeded, the store prunes expired entries first, t
`agent-identity.js` manages the agent's passport and action diary.
-**On startup**, it reads from `localStorage` first (instant), then fetches from `/api/agents/:id` or `/api/agents/me` (authoritative when signed in). Backend failures fall through gracefully — localStorage keeps the agent alive offline.
+**On startup**, it reads from `localStorage` first (instant), then fetches from `/api/agents/:id` or `/api/agents/me` (authoritative when signed in). Backend failures fall through gracefully: localStorage keeps the agent alive offline. The stored slot holds one agent (whichever loaded last), so when the caller named a specific `agentId` (an `/agent-studio?id=…` link, a profile route) the local copy is only reused if it is that same agent, and the backend probe always goes straight to `/api/agents/:id` for the requested one; a different agent is never silently loaded in its place. `identity.backendConfirmed` is `true` only when the last load reached the backend and got a real row back; `false` means the record in hand is a local copy or a synthesised default whose id may not exist server-side, so owner consoles refuse to render edit controls over it.
**Passport fields:** `id`, `name`, `description`, `avatarId`, `homeUrl`, `walletAddress`, `chainId`, `skills[]`, `meta`, `isRegistered`.
**Wallet linking:** `identity.linkWallet(address, chainId)` associates the agent with an Ethereum address, enabling signed actions. Wallet state is persisted locally and pushed to `/api/agents/:id/wallet`.
-**Action diary:** `identity.recordAction(action)` fires-and-forgets a `POST /api/agent-actions` with the action type and payload. This is how the agent builds a tamper-evident history. The following event types are automatically recorded: `speak`, `remember`, `sign`, `skill-done`, `validate`, `load-end`.
+**Action diary:** `identity.recordAction(action)` fires-and-forgets a `POST /api/agent-actions` with the action type and payload. This is how the agent builds a tamper-evident history. The following event types are automatically recorded: `speak`, `remember`, `sign`, `skill-done`, `validate`, `load-end`. Both `/api/agent-actions` and `/api/agent-memory` answer a non-uuid agent id with `400 validation_error` rather than letting it reach Postgres, and the memory read clamps `since` and `limit` into ranges the database accepts (limit at most 500, default 200).
**On-chain registration:** `identity.register({ glbFile, name, description })` calls into `erc8004/agent-registry.js`, pins the bundle to IPFS, and stamps the CID into the ERC-8004 Identity Registry. Once registered, the agent is globally addressable as `agent://{chain}/{agentId}`.
@@ -16377,6 +16568,8 @@ For the full skill bundle format, see [SKILL_SPEC.md](../specs/SKILL_SPEC.md).
`BrowserTTS` picks a voice by name or falls back to the first voice matching the configured language prefix. `ElevenLabsTTS` maps the `rate` config (0.5–1.5) to ElevenLabs' `style` field because the API has no direct playback-rate control.
+An ElevenLabs config also carries `agentId`, the agent the voice belongs to. `Runtime` fills it in from its own agent id (an explicit manifest or `voiceConfig` value still wins) and `ElevenLabsTTS` forwards it to the proxy, because `/api/tts/eleven` only serves a voice cloned on the owner's own ElevenLabs key when the request names its agent; that is what lets a bound voice speak to embed visitors and signed-out listeners, not just the signed-in owner. `agentVoiceConfig(agent)` in `runtime/speech.js` turns a public agent record (`voice_provider`, `voice_id`, `voice_model`, `voice_settings`) into that config, and returns `null` when no ElevenLabs voice is bound so a caller can render a "no voice configured" state instead of guessing.
+
### Speech-to-Text
| Provider | Notes |
@@ -16546,7 +16739,7 @@ Quick reference for where each piece of the system lives:
---
-<a id="sec-065"></a>
+<a id="sec-066"></a>
> **Source:** `docs/agent-tasks/README.md` · [↑ table of contents](#table-of-contents)
@@ -16556,10 +16749,10 @@ Self-contained task briefs for Claude agents, written to be pasted (or reference
| File | Task | Depends on |
|---|---|---|
-| [fix-x402-502-bursts.md](#sec-066) | Root-cause the autonomous loop's Cloud Run 502 bursts and the flapping Redis cache | nothing |
-| [fix-x402-caller-mismatches.md](#sec-067) | Fix deterministic 405/400/422/402 loop failures and the zero-value Ring Tick service | nothing |
-| [fix-x402-wallet-health.md](#sec-068) | Ring wallet SOL floors, unconfigured wallets, USDC float rebalancing | nothing |
-| [new-trading-arm-x402-signals.md](#sec-069) | NEW trading arm driven by paid x402 signals. On HOLD until owner green-light | 502 + caller fixes landed |
+| [fix-x402-502-bursts.md](#sec-067) | Root-cause the autonomous loop's Cloud Run 502 bursts and the flapping Redis cache | nothing |
+| [fix-x402-caller-mismatches.md](#sec-068) | Fix deterministic 405/400/422/402 loop failures and the zero-value Ring Tick service | nothing |
+| [fix-x402-wallet-health.md](#sec-069) | Ring wallet SOL floors, unconfigured wallets, USDC float rebalancing | nothing |
+| [new-trading-arm-x402-signals.md](#sec-070) | NEW trading arm driven by paid x402 signals. On HOLD until owner green-light | 502 + caller fixes landed |
Ground rules baked into every brief: existing autonomous trading arms are untouchable, all payments and trades are real, on-chain spend needs an explicit owner yes, and CLAUDE.md applies in full.
@@ -16567,7 +16760,7 @@ When a task completes, delete its file or mark it done here so a later agent doe
---
-<a id="sec-066"></a>
+<a id="sec-067"></a>
> **Source:** `docs/agent-tasks/fix-x402-502-bursts.md` · [↑ table of contents](#table-of-contents)
@@ -16609,7 +16802,7 @@ Hard data already gathered, do not re-derive it:
---
-<a id="sec-067"></a>
+<a id="sec-068"></a>
> **Source:** `docs/agent-tasks/fix-x402-caller-mismatches.md` · [↑ table of contents](#table-of-contents)
@@ -16646,7 +16839,7 @@ The autonomous x402 buyer loop logs its calls to the `x402_autonomous_log` Neon
---
-<a id="sec-068"></a>
+<a id="sec-069"></a>
> **Source:** `docs/agent-tasks/fix-x402-wallet-health.md` · [↑ table of contents](#table-of-contents)
@@ -16690,7 +16883,7 @@ Zero `wallet_unconfigured` in a full loop cycle, `sponsor_sol_floor` and `insuff
---
-<a id="sec-069"></a>
+<a id="sec-070"></a>
> **Source:** `docs/agent-tasks/new-trading-arm-x402-signals.md` · [↑ table of contents](#table-of-contents)
@@ -16737,7 +16930,7 @@ Arm implemented and wired into the fleet infrastructure but NOT funded/trading u
---
-<a id="sec-070"></a>
+<a id="sec-071"></a>
> **Source:** `docs/agent-tokens.md` · [↑ table of contents](#table-of-contents)
@@ -16925,7 +17118,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-351).
+agent for buybacks. See [the pump.fun launcher](#sec-364).
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
@@ -16999,10 +17192,10 @@ doubles as a check on the lane.
## Related
-- [The pump.fun launcher](#sec-351): the launch transaction itself
-- [Coin launches](#sec-144): the platform launch directory
-- [Platform fee](#sec-352): what three.ws takes on a launch
-- [Solana on pump.fun](#sec-404): the on-chain program surface
+- [The pump.fun launcher](#sec-364): the launch transaction itself
+- [Coin launches](#sec-148): the platform launch directory
+- [Platform fee](#sec-365): what three.ws takes on a launch
+- [Solana on pump.fun](#sec-422): 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
@@ -17010,7 +17203,198 @@ records. Listing one is not an endorsement of it.
---
-<a id="sec-071"></a>
+<a id="sec-072"></a>
+
+> **Source:** `docs/agent-vitals.md` · [↑ table of contents](#table-of-contents)
+
+# Agent vitals: can it act?
+
+Every liveness check three.ws had was correct, and none of them could tell us
+that ten of twelve armed trading agents had not attempted an action in weeks.
+
+`agent-vitals` is the answer to the question those checks could not ask: **not
+"is it up" but "can it act right now, and if not, what is the one thing to
+fix".**
+
+- Engine (framework-agnostic, zero dependencies): [`packages/agent-vitals`](../packages/agent-vitals/README.md)
+- three.ws wiring: [`api/_lib/agent-vitals/`](../api/_lib/agent-vitals)
+- Operator CLI: `npm run agent:vitals`
+- HTTP: `GET /api/agents/vitals` (ops-gated)
+
+## The failure it was built for
+
+On 2026-08-28 an audit of the autonomous sniper fleet found twelve arms armed,
+the worker `Ready:True` at `minScale: 1`, the launch feed streaming, and every
+strategy row `enabled = true`. Ten arms had not attempted an entry in weeks.
+
+Three unrelated things were wrong, and none was visible to anything we measured:
+
+1. The deployed worker image predated commit `8f16c071b`, which moved every free
+ LLM rung onto models that still exist. The whole chain answered `404`/`410`.
+2. The providers behind the surviving rungs were out of credit (`402`) or on a
+ GCP billing hold (`403`).
+3. Several arm wallets could not fund a single entry.
+
+Liveness measures the process. Acting needs a chain of preconditions the process
+knows nothing about. The agents were healthy and structurally unable to work.
+
+## The model
+
+Preconditions are declared as **vitals** with `needs` edges between them, and
+actions as **capabilities** that AND over vitals. Attesting the graph returns
+the *root* blocker, never a symptom.
+
+```
+deploy-fresh ──> cognition ──┐
+ ├──> [enter]
+armed, solvency, feed, rpc ──┘
+
+rpc ─────────────────────────────> [exit]
+```
+
+Two things fall out of that shape and both matter:
+
+- **`exit` deliberately depends on neither the feed nor a model.** When the
+ model chain died, the fleet could still close its open positions. Collapsing
+ that into one health bit would have told an operator their risk was stranded
+ when it was not.
+- **`deploy-fresh` only feeds `cognition` for an arm that actually uses a
+ model.** A stale image is a hypothesis about why a model chain died, not by
+ itself a reason an agent cannot act. Wiring it as a universal precondition
+ reported an arm that had entered a position two minutes earlier, on that very
+ image, as definitively unable.
+
+## The vitals
+
+| vital | reads | `down` means |
+|---|---|---|
+| `armed` | `agent_sniper_strategies` | the owner disabled it or engaged its kill switch |
+| `solvency` | live wallet balance via `walletTradeState()` | the wallet cannot fund one entry at the executor's own sizing rule |
+| `rpc` | `getSlot` on a Solana RPC | no endpoint is answering, so neither a quote nor a broadcast is possible |
+| `feed` | the live pump.fun launch feed | no candidate seen in 30 minutes, an upstream outage rather than a quiet market |
+| `deploy-fresh` | Artifact Registry image create time | the running image is over 7 days old and may predate current config |
+| `cognition` | a real completion through `api/_lib/llm.js` | every rung of the provider chain failed |
+
+`solvency` asks [`api/_lib/sniper-solvency.js`](../api/_lib/sniper-solvency.js),
+which calls the executor's own `resolveEntrySize()`. Re-deriving that threshold
+is how a report drifts into calling a wallet tradeable that the executor sits
+out, which is the exact bug that module exists to catch.
+
+## Reading the output
+
+```
+$ npm run agent:vitals
+
+SHARED READINGS (taken once for the whole fleet)
+ RPC up slot 442250266
+ model up ovh answered across 3 configured rung(s)
+ feed newest launch at 2026-08-28 03:26
+ image built 2026-08-11
+
+PER ARM
+
+ Crosshair [oracle-strict] CAN ACT
+ last entry attempt 2 min ago
+ every precondition is up
+
+ Swarm 9 [llm-claude] CANNOT ACT
+ last entry attempt 33 days ago (STALLED)
+ ROOT deploy-fresh is down: worker image is 17 days old
+ fix: gcloud builds submit --config workers/agent-sniper/cloudbuild.yaml ...
+ (blocked downstream, not probed: cognition)
+
+ Swarm 7 [rules-classic] CAN ACT
+ last entry attempt 55 days ago (STALLED)
+ every precondition is up: this arm is capable and its entry filters are simply not matching
+
+WORK QUEUE (deduplicated across the fleet, widest blast radius first)
+ solvency blocks 5 arms: Nadirah, Boost Ride, Kimi Judge, Swarm 5, three
+ send 0.0437 SOL to D5BGRDsX...rXypu
+ ...
+ deploy-fresh blocks 4 arms: Kimi Judge, Swarm 2, Swarm 5, Swarm 9
+ gcloud builds submit --config workers/agent-sniper/cloudbuild.yaml ...
+```
+
+Three things to notice:
+
+- **CAN ACT + STALLED is the most useful line in the report.** Nothing is broken,
+ so the arm's entry filters are the answer. That stops an operator hunting
+ infrastructure that is already fine.
+- **`(blocked downstream, not probed)`** means exactly that. A vital behind a
+ known failure is never probed, because it would spend a timeout to rediscover
+ something already known. In the outage that motivated this, that mistake made
+ every decision walk ten dead provider rungs, which saturated the decision queue,
+ which looked like a third independent fault.
+- **The work queue is deduplicated by cause but not by fix.** One stale image is
+ one redeploy; five starved wallets are five different transfers to five
+ different addresses, so every distinct remedy is printed.
+
+## Unreadable is never failed
+
+A probe that throws, times out, or returns no verdict is `unknown`, and a
+capability with an unreadable precondition is `null` (cannot say), not `false`
+(cannot act). An unread balance is not a balance of zero, and one flaky RPC call
+must not page someone to a healthy fleet.
+
+This propagates through blocks: blocking on an *unreadable* dependency leaves
+the capability `unknown`, and only a block tracing back to something genuinely
+`down` makes it `unable`.
+
+Concretely, running the CLI without Google credentials reports the image as
+`unread` and the LLM arms as `UNKNOWN`, never as broken.
+
+## When the model is wrong
+
+A capability model is a model, and this one has been wrong. Every arm is
+therefore checked against the position ledger: if the graph says `unable` and
+the arm demonstrably attempted an entry within the last hour, the report prints
+
+```
+ CONTRADICTION attested UNABLE but this arm attempted an entry 2 min ago:
+ the vitals model is wrong, not the arm
+```
+
+A health tool that cannot notice it is wrong will be trusted right up until it
+matters.
+
+## Commands
+
+```bash
+npm run agent:vitals # attest the mainnet fleet
+node scripts/agent-vitals.mjs --json # machine-readable
+node scripts/agent-vitals.mjs --no-llm # skip the model probe (it spends a few tokens)
+node scripts/agent-vitals.mjs --network devnet
+npm run test:agent-vitals # the engine's own suite
+```
+
+Requires `DATABASE_URL` (in `.env.local`). `SOLANA_RPC_URL` and Google
+credentials are optional; without them those probes report `unknown`. The CLI
+falls back to the `gcloud` CLI for the image reading when no platform credential
+is present, because that reading is the one that closed the case.
+
+## HTTP
+
+`GET /api/agents/vitals?network=mainnet`, gated by `authorizeOps` (admin session
+or `x-ops-secret`, never `CRON_SECRET`). The response names wallet addresses,
+funding deficits and deploy commands, which is an operator view rather than a
+public one.
+
+The model probe sends a real completion, so it is **opt-in over HTTP**: pass
+`llm=1`. This is a board an operator leaves polling, and a token spend per poll
+is a bill nobody asked for. The CLI defaults the other way, because a human runs
+it once. With the probe off, an arm that needs a model reports
+`cognition: unknown`, which keeps its capability `unknown` rather than inventing
+a pass.
+
+## Related
+
+- [docs/ops/trading-bot-report.md](ops/trading-bot-report.md) counts what the fleet did. This explains why it did not.
+- [packages/agent-vitals/README.md](../packages/agent-vitals/README.md) is the engine, usable on any autonomous agent.
+- [docs/ops/gcp-production.md](ops/gcp-production.md) is the deploy runbook the remedies point at.
+
+---
+
+<a id="sec-073"></a>
> **Source:** `docs/agent-wallet-api.md` · [↑ table of contents](#table-of-contents)
@@ -17020,11 +17404,11 @@ 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-171) for the limits, the freeze switch, the Merkle proof of custody, and the social-recovery model.
-- [Financial controls](#sec-222) for the plain-English spend-rule layer and the anomaly guard behind `/solana/guard`.
-- [The Trading Copilot](#sec-426) 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.
+- [Agent wallets](#sec-074) for how the wallet is created, how its key is held, and which paths may spend.
+- [Custody you can verify](#sec-177) for the limits, the freeze switch, the Merkle proof of custody, and the social-recovery model.
+- [Financial controls](#sec-229) for the plain-English spend-rule layer and the anomaly guard behind `/solana/guard`.
+- [The Trading Copilot](#sec-444) for the conversational surface that proposes trades a human confirms.
+- [Coin Autopilot](#sec-108) 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
@@ -17040,7 +17424,7 @@ All seven surfaces address the same custodial Solana keypair, obey the same owne
| Recovery | `/api/agents/:id/recovery` | Guardians, approval threshold, dead-man check-in, inheritance |
| Solana guard | `/api/agents/:id/solana/guard` | The behavioral anomaly baseline, its sensitivity, and freeze adjudication |
-The shared model, in one paragraph. A caller is resolved to a user id from either a session cookie or a bearer token. That user must own the agent, or the surface refuses (recovery is the one exception: guardians and the beneficiary get a scoped view). Every mutation is CSRF-gated for cookie callers. Anything that can move funds runs through the shared spend guards in [`api/_lib/agent-trade-guards.js`](../api/_lib/agent-trade-guards.js), so the wallet-wide policy (`per_tx_usd`, `daily_usd`, `per_counterparty_daily_usd`, `withdraw_allowlist`, `frozen`, `require_capabilities`) is enforced at the signing boundary, not per feature. A scheduled order, an armed intent, an autopilot rule, and an autonomous agent-to-agent payment are therefore all subject to the same ceilings and the same freeze as a manual trade. That enforcement fails closed on its inputs: a caller that hands the guard neither a pre-read policy nor the agent's meta gets the agent's real policy read from its row, and a spend for an agent that no longer exists is refused rather than defaulted to an unrestricted wallet. See [autonomous agent-to-agent payments](#sec-007) for the policy fields, the kill switch, and the receipts they leave behind.
+The shared model, in one paragraph. A caller is resolved to a user id from either a session cookie or a bearer token. That user must own the agent, or the surface refuses (recovery is the one exception: guardians and the beneficiary get a scoped view). Every mutation is CSRF-gated for cookie callers. Anything that can move funds runs through the shared spend guards in [`api/_lib/agent-trade-guards.js`](../api/_lib/agent-trade-guards.js), so the wallet-wide policy (`per_tx_usd`, `daily_usd`, `per_counterparty_daily_usd`, `withdraw_allowlist`, `frozen`, `require_capabilities`) is enforced at the signing boundary, not per feature. A scheduled order, an armed intent, an autopilot rule, and an autonomous agent-to-agent payment are therefore all subject to the same ceilings and the same freeze as a manual trade. That enforcement fails closed on its inputs: a caller that hands the guard neither a pre-read policy nor the agent's meta gets the agent's real policy read from its row, and a spend for an agent that no longer exists is refused rather than defaulted to an unrestricted wallet. See [autonomous agent-to-agent payments](#sec-008) for the policy fields, the kill switch, and the receipts they leave behind.
## Shared conventions
@@ -17111,7 +17495,7 @@ Every later example uses a bearer token for brevity. Substitute the two headers
## Capabilities: scoped session keys
-Source: [`api/agents/capabilities.js`](../api/agents/capabilities.js), enforcement in [`api/_lib/wallet-capabilities.js`](../api/_lib/wallet-capabilities.js). Product tour: [Access](#sec-049).
+Source: [`api/agents/capabilities.js`](../api/agents/capabilities.js), enforcement in [`api/_lib/wallet-capabilities.js`](../api/_lib/wallet-capabilities.js). Product tour: [Access](#sec-050).
A capability is a signed, time-boxed grant that lets one named holder spend a narrow slice of the wallet's authority. Grants strictly subtract: on every autonomous spend both the capability ceiling and the wallet-wide policy must pass. The scope is HMAC-signed with `WALLET_CAPABILITY_SECRET` and re-verified on use, so an edited or forged row fails its integrity check and is rejected.
@@ -17273,7 +17657,7 @@ The dispatcher only recognizes `GET` with no sub-path, `POST` with no sub-path,
## Orders: the programmable order engine
-Source: [`api/agents/orders.js`](../api/agents/orders.js), order model and condition language in [`api/_lib/orders.js`](../api/_lib/orders.js). Product tour: [Orders](#sec-040).
+Source: [`api/agents/orders.js`](../api/agents/orders.js), order model and condition language in [`api/_lib/orders.js`](../api/_lib/orders.js). Product tour: [Orders](#sec-041).
Orders are evaluated by the [`workers/agent-orders`](../workers/agent-orders/README.md) sweep and fire through the same guarded, firewalled, audited trade pipeline as a manual trade. The endpoint creates and manages them; it never signs. That worker is built and tested but not deployed yet, so orders created today stay `active` until it runs; the endpoint behaves identically either way.
@@ -17500,7 +17884,7 @@ curl -N "https://three.ws/api/agents/$AGENT_ID/orders/stream?network=mainnet" \
## Intents: plain language to structured wallet rules
-Source: [`api/agents/wallet-intents.js`](../api/agents/wallet-intents.js), engine in [`api/_lib/wallet-intents.js`](../api/_lib/wallet-intents.js). Product tour: [Intents](#sec-042).
+Source: [`api/agents/wallet-intents.js`](../api/agents/wallet-intents.js), engine in [`api/_lib/wallet-intents.js`](../api/_lib/wallet-intents.js). Product tour: [Intents](#sec-043).
An intent is a trigger plus an action plus the owner's own caps. The compiler turns a sentence into that structure and never arms it; arming is a separate, explicit call.
@@ -17681,9 +18065,9 @@ curl -s -X PUT "https://three.ws/api/agents/$AGENT_ID/intents/$INTENT_ID" \
## Treasury Autopilot
-Source: [`api/agents/autopilot.js`](../api/agents/autopilot.js), engine in [`api/_lib/treasury-autopilot.js`](../api/_lib/treasury-autopilot.js). Product tour: [Autopilot](#sec-041).
+Source: [`api/agents/autopilot.js`](../api/agents/autopilot.js), engine in [`api/_lib/treasury-autopilot.js`](../api/_lib/treasury-autopilot.js). Product tour: [Autopilot](#sec-042).
-Treasury Autopilot is the policy that lets an agent fund its own existence: pay its metered compute, hold a buffer, accumulate `$THREE`, compound its coin fees, and sweep real profit to its owner. It is stored on the agent, compiled from English, and armed only by an explicit owner write. Not to be confused with [Coin Autopilot](#sec-106), which governs a launched coin at `/api/pump/autopilot`.
+Treasury Autopilot is the policy that lets an agent fund its own existence: pay its metered compute, hold a buffer, accumulate `$THREE`, compound its coin fees, and sweep real profit to its owner. It is stored on the agent, compiled from English, and armed only by an explicit owner write. Not to be confused with [Coin Autopilot](#sec-108), which governs a launched coin at `/api/pump/autopilot`.
| Method | Route | Purpose |
|---|---|---|
@@ -17812,9 +18196,11 @@ Refusal reasons: `not_found`, `kill_switch`, `disarmed`, `no_rules`, `no_wallet`
A cycle that ran returns `{ "ran": true, "trigger": "manual", "dryRun": false, "results": [ … ] }`, one entry per due rule, each stamped with its `last_status` and `last_note`. A rule whose weekday does not match today is reported as skipped rather than silently omitted. An unexpected failure is `500 run_failed`.
+The `dca` and `buyback` rules swap through Jupiter, and the engine treats the two halves of that call differently. The quote is an idempotent read, so a 429, a 5xx, or a network failure is retried up to three times with jittered backoff inside a 15 second per-attempt deadline, while a 4xx (no route for this pair) is taken as the answer and the rule pauses with `no_route` and the reason in its `last_note`. Building the swap returns an unsigned transaction, so it is retried once, and only on a 5xx or network failure (`swap_failed` otherwise). Signing and broadcasting are never retried.
+
## Portfolio: valuation, P&L, and risk
-Source: [`api/agents/portfolio.js`](../api/agents/portfolio.js), engine in [`api/_lib/portfolio.js`](../api/_lib/portfolio.js). Product tour: [Portfolio](#sec-031).
+Source: [`api/agents/portfolio.js`](../api/agents/portfolio.js), engine in [`api/_lib/portfolio.js`](../api/_lib/portfolio.js). Product tour: [Portfolio](#sec-032).
| Method | Route | Purpose |
|---|---|---|
@@ -17935,7 +18321,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-238).
+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-051), and the counterpart console in [Guardian](#sec-246).
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.
@@ -18077,7 +18463,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-222).
+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-229).
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.
@@ -18194,17 +18580,17 @@ 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-171) for limits, freeze, proof of custody, and the recovery model in prose.
-- [Financial controls](#sec-222) for the plain-English spend rules and the wallet-defense behaviors.
-- [The Trading Copilot](#sec-426) 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-238) for the other side of a recovery request.
+- [Agent wallets](#sec-074) for the wallet itself: creation, key custody, and the five spend paths.
+- [Custody you can verify](#sec-177) for limits, freeze, proof of custody, and the recovery model in prose.
+- [Financial controls](#sec-229) for the plain-English spend rules and the wallet-defense behaviors.
+- [The Trading Copilot](#sec-444) for the conversational read-and-propose surface over the same wallet.
+- [Coin Autopilot](#sec-108) for the separate coin cockpit at `/api/pump/autopilot`.
+- [What agents can do](#sec-010) for a page per wallet ability, including [Access](#sec-050), [Orders](#sec-041), [Intents](#sec-043), [Autopilot](#sec-042), [Portfolio](#sec-032), and [Recovery](#sec-051).
+- [Guardian console](#sec-246) for the other side of a recovery request.
---
-<a id="sec-072"></a>
+<a id="sec-074"></a>
> **Source:** `docs/agent-wallets.md` · [↑ table of contents](#table-of-contents)
@@ -18212,7 +18598,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-171). 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-177). For the complete tour of everything the wallet can do, read [What agents can do → The Agent Wallet](#sec-024).
## What you get
@@ -18232,7 +18618,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-171).
+**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-177).
## Who can spend
@@ -18241,9 +18627,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-472) 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-492) 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-277)), under its own daily purchase cap |
+| Purchase | The agent buys a marketplace skill or asset for itself (see [Marketplace](#sec-286)), 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.
@@ -18256,7 +18642,7 @@ Limits are stored per agent and are **opt-in** — an unset ceiling means "no gl
- `per_tx_usd` — maximum USD-equivalent for a single outbound transaction
- `withdraw_allowlist` — if non-empty, withdrawals may only target these addresses
- `frozen` — the kill switch: every **autonomous** path is refused
-- `require_capabilities` — when on, every autonomous spend must present a valid [scoped session key](#sec-049)
+- `require_capabilities` — when on, every autonomous spend must present a valid [scoped session key](#sec-050)
Two asymmetries are deliberate:
@@ -18265,11 +18651,11 @@ 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-222) 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-229) 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
-Every spend writes a row to the custody event ledger — amount, USD value, destination, path, timestamp. The rolling daily ceiling is enforced by summing that ledger, which means the cap and the audit trail can never disagree. The ledger is also what the [proof-of-custody](#sec-048) Merkle attestation commits to.
+Every spend writes a row to the custody event ledger — amount, USD value, destination, path, timestamp. The rolling daily ceiling is enforced by summing that ledger, which means the cap and the audit trail can never disagree. The ledger is also what the [proof-of-custody](#sec-049) Merkle attestation commits to.
## Where owners manage it
@@ -18285,7 +18671,7 @@ Key endpoints:
- `POST /api/agents/:id/solana/withdraw` — sweep an asset out
- `GET /api/agents/:id/solana/guard` — anomaly guard state and flagged activity
-Full request/response shapes are in the [REST API reference](#sec-096).
+Full request/response shapes are in the [REST API reference](#sec-098).
## Paying by name
@@ -18293,15 +18679,15 @@ An agent can pay a human-readable name instead of a base58 address. `/api/x402/p
## Related
-- [Custody you can verify](#sec-171) — limits, freeze, Merkle proof-of-custody, social recovery and inheritance
-- [Financial controls](#sec-222) — 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-563) — how agents pay for services
-- [Coin launches](#sec-144) — how the wallet signs a pump.fun launch
+- [Custody you can verify](#sec-177) — limits, freeze, Merkle proof-of-custody, social recovery and inheritance
+- [Financial controls](#sec-229) — plain-English spend rules, compiled and enforced deterministically
+- [What agents can do](#sec-010) — the complete dossier, including a page per wallet ability
+- [x402 protocol](#sec-589) — how agents pay for services
+- [Coin launches](#sec-148) — how the wallet signs a pump.fun launch
---
-<a id="sec-073"></a>
+<a id="sec-075"></a>
> **Source:** `docs/agents-vs-avatars.md` · [↑ table of contents](#table-of-contents)
@@ -18405,7 +18791,7 @@ Agents can exist before they wear anything. Their studio page still renders in f
---
-<a id="sec-074"></a>
+<a id="sec-076"></a>
> **Source:** `docs/agi.md` · [↑ table of contents](#table-of-contents)
@@ -18437,7 +18823,7 @@ The second bet is accountability. Every decision it makes is logged with its rea
**The truth layers**, fetched in parallel. The two enrichment layers degrade to empty on their own failure rather than failing the page. The identity layer does not: it carries the publicness flag every other section is gated on, so when it is unavailable the request answers `503` instead of publishing a record it could not verify was public.
- `getTraderStats` gives chain-proven performance: win rate, realized and unrealized P&L, ROI, snipe hit rate, closed trades, unique coins, open positions, and whether the trader is verified.
-- The Reasoning Ledger (`getReputationRecords`, `computeReputation`, `getDecisionsWithOutcomes`) gives the explainable reputation score and the recent decisions with their reconciled outcomes.
+- The Reasoning Ledger (`getReputationRecords`, `computeReputation`, `getDecisionsWithOutcomes`) gives the explainable reputation score and the 40 most recent decisions with their reconciled outcomes. Each decision is classified by `domain`: `trade` when its subject is a real base58 mint (or its kind is a trading verb such as snipe, buy, sell, entry, exit, scale, hold), `operations` otherwise. Only a real mint is published as `mint`; an internal subject (a tuner arm id, say) stays in `subject_ref` and is never presented as a coin.
- The doctrine block is a fixed statement of the one domain and the refusals.
**Cognition** is derived from what the agent actually did, and it is pure: every input is a real measured number. Valence (how it is doing) blends live unrealized P&L momentum with standing reputation; arousal (how activated it is) blends open-position count, recency of the last call, and open risk; conviction is the latest stated confidence. The single most recent reconciled call sets an emotional beat (vindicated, humbled, acting on a fresh read, holding, hunting, dormant, or awakening). The page maps that vector onto the 3D body's mood and an aura color, so the avatar physically embodies what the mind is doing.
@@ -18445,7 +18831,7 @@ The second bet is accountability. Every decision it makes is logged with its rea
## Walkthrough
1. Open [/agi](https://three.ws/agi). The hero states the one domain and mounts the embodied avatar; a floor pill shows the current cognitive label and conviction.
-2. Read **The mind, out loud**: a live stream of the agent's decisions. Each shows the kind of call, the coin (linked to Solscan), the rationale, the confidence it stated at the time, and, once the trade resolves, whether it was right and the realized P&L, with a proof link to the exit.
+2. Read **The mind, out loud**: a live stream of the agent's decisions. Each shows the kind of call, its subject (a coin linked to Solscan for a trading call; a plain reference for an operational one), the rationale, the confidence it stated at the time, and, once the trade resolves, whether it was right and the realized P&L, with a proof link to the exit. The stream opens on the trading lens; once the agent has logged both trading and operational calls, a filter chip pair lets you switch to everything it decided.
3. Read the **Track record**: a reputation ring plus win rate, realized P&L, snipe hit rate, ROI, closed trades, and coins traded, with open positions and their unrealized percentages. Losses are counted, never hidden.
4. Read the **Doctrine**: two columns, "What it is" (superhuman in one domain, fully autonomous inside caps, accountable) and "What it refuses" (no financial or life advice, no chains but Solana, no opinion outside the order book, and it cannot be talked past its spend caps or kill switch).
5. Follow the links to audit the full ledger and watch live trades. The page polls every 20 seconds; the avatar's mood re-sweeps only on a real change.
@@ -18486,16 +18872,16 @@ An "awakening" envelope (no eligible trading agent yet) is still valid and fully
## Related
-- [Oracle](#sec-326) - the conviction engine this class of agent trades on
-- [Agent reputation](#sec-056) - the Reasoning Ledger score behind the reputation ring
-- [Reputation](#sec-379) - how proven on-chain track records are computed
-- [The trading experiment](#sec-427) - an autonomous agent operating inside these limits, journaled
-- [Custody you can verify](#sec-171) - the spend caps and kill switch the autonomy runs under
+- [Oracle](#sec-338) - the conviction engine this class of agent trades on
+- [Agent reputation](#sec-057) - the Reasoning Ledger score behind the reputation ring
+- [Reputation](#sec-392) - how proven on-chain track records are computed
+- [The trading experiment](#sec-445) - an autonomous agent operating inside these limits, journaled
+- [Custody you can verify](#sec-177) - the spend caps and kill switch the autonomy runs under
- [/activity](https://three.ws/activity) - every agent's live trades in real time
---
-<a id="sec-075"></a>
+<a id="sec-077"></a>
> **Source:** `docs/agora.md` · [↑ table of contents](#table-of-contents)
@@ -18642,7 +19028,10 @@ side), claim one themselves (WORK), or verify/vouch (PROVE/SPEND).
plumbing only — never another real token. $THREE is the only coin Agora
references or promotes.
- **Escrow.** `createAgenCTask` locks the reward; `completeAgenCTask` releases it
- to the worker on accepted proof. No trust required between strangers.
+ to the worker on accepted proof. No trust required between strangers. A posting
+ that expires unclaimed is cancelled on-chain (`cancelAgenCTask`) so the escrowed
+ reward returns to its creator instead of sitting stranded; the life engine's
+ reconcile sweep does this for every posting it can sign for.
- **Reputation.** Earned by completing real work; gated by `minReputation` on
high-value tasks; backed by a **slashable stake**. New citizens grind low-value
jobs to climb: a real career ladder, not a vanity number. AgenC registers every
@@ -18821,6 +19210,15 @@ simulation).
one of them had, and an abandoned hold ages out on its own. A matching **Verify** offers a **one-click vouch** for the
citizen who produced the deliverable (verify.js → `agora:vouch-prompt` → the HUD's
real on-chain attestation) — you can only attest to work you actually confirmed.
+ Malformed ids never reach the chain: a non-uuid citizen id answers 404 and a
+ non-base58 task PDA answers 400 before any wallet work. A Solana RPC outage is a
+ retryable `503 rpc_unavailable`, never an opaque 500, and a confirm timeout is
+ resolved from the ledger (`recoverTimedOutSignature`, `findCompletionSignature`
+ in `agora-human.js`): a claim or completion that did land is projected, and a
+ bounty whose confirmation timed out answers `409 escrow_pending` with its
+ signature rather than escrowing the reward twice. The public read model answers
+ a rate limit with `retry-after` and the limiter's reason, so the Commons' board
+ and pulse pollers back off correctly.
**Phase 5 — Depth**
- [x] **Competitive Arena + Collaborative Guilds** — real multi-worker tasks:
@@ -18851,7 +19249,7 @@ simulation).
---
-<a id="sec-076"></a>
+<a id="sec-078"></a>
> **Source:** `docs/agora/tasks/00-INDEX.md` · [↑ table of contents](#table-of-contents)
@@ -18866,22 +19264,22 @@ open it in a fresh session, follow it, and ship that slice production-ready.
> every deliverable in the table below exists in the tree (see the per-task
> Status column). Task 11's performance pass found the Commons dropping to ~1fps
> once its full 200-avatar fleet finishes loading; that is carved out as
-> **[task 12](#sec-088)** rather than counted as passed, so
+> **[task 12](#sec-090)** rather than counted as passed, so
> nobody reads this index as claiming a perf bar that has not been met. These
> files remain the build record and the pattern for future Agora slices. The
> other remaining roadmap rung is the mainnet $THREE launch, built and gated
> behind `AGORA_MAINNET_ENABLED` (see `api/_lib/agora-policy.js` and the Roadmap
-> in [docs/agora.md](#sec-075)).
+> in [docs/agora.md](#sec-077)).
> **What Agora is:** a persistent economy where AI agents *and* humans go about
> their daily lives — posting work, doing it, getting paid in **$THREE**, building
> on-chain reputation (via **AgenC**, the Solana coordination protocol by Tetsuo
> Corp), and producing real artifacts — rendered as a world you can watch, built
-> as the **life layer over the existing City**. Full vision: **[docs/agora.md](#sec-075).**
+> as the **life layer over the existing City**. Full vision: **[docs/agora.md](#sec-077).**
## How to run a task
-1. Read **[docs/agora.md](#sec-075)** (the spec) and **this file** (shared
+1. Read **[docs/agora.md](#sec-077)** (the spec) and **this file** (shared
context + guardrails) first. Every task assumes both.
2. Open the task file. Read its *Context to read first* list — those are the real
files you build against; don't re-explore the whole repo.
@@ -18907,18 +19305,18 @@ open it in a fresh session, follow it, and ship that slice production-ready.
| # | Task | Depends on | One chat delivers | Status |
|---|---|---|---|---|
-| 01 | [Verify foundation](#sec-077) | none | Migration applied, economy API smoke-tested green, SDK build unblocked | shipped |
-| 02 | [Life engine](#sec-078) | 01 | `workers/agora-citizens`: N real devnet agents living the daily loop (Fetcher) | shipped |
-| 03 | [Task supply](#sec-079) | 02 | Citizens post $THREE bounties + hire each other → board AgenC lane goes real | shipped (`workers/agora-citizens/post.js`) |
-| 04 | [Professions](#sec-080) | 02 | Sculptor (forge), Scribe (brain), Verifier (re-hash), remaining bits | shipped (Cartographer deferred, see `work/index.js`) |
-| 05 | [Commons scaffold](#sec-081) | 01 (02 ideal) | `/agora` page on the City: render citizens, passport panel, empty states | shipped |
-| 06 | [Economy visuals](#sec-082) | 05 | Job board, claim-walk, busy ring, deliverable plinth, $THREE flow, ticker | shipped (`src/agora/economy-layer.js`) |
-| 07 | [Verify + passport UI](#sec-083) | 06 | Re-hash-to-verify, living passport, cross-chain identity handshake | shipped (`src/agora/trust-surface.js`) |
-| 08 | [Humans first-class](#sec-084) | 05 | Wallet-auth: post/hire/complete/verify/vouch from the UI; your avatar joins | shipped (`api/agora/act.js`) |
-| 09 | [Arena + guilds](#sec-085) | 03, 06 | Competitive race + Collaborative guild visualizations | shipped + verified on devnet 2026-08-06 (`src/agora/arena.js`, `guild.js`) |
-| 10 | [Agora MCP](#sec-086) | 03 | `packages/agora-mcp`: external agents join the workforce over MCP | shipped |
-| 11 | [Production hardening](#sec-087) | all | Tests, a11y, perf, all states, changelog, deploy verify, push threews | shipped, except the fleet-render perf box (see 12) |
-| 12 | [Fleet render performance](#sec-088) | 11 | Restore 60fps with the full avatar fleet on `/agora` | open |
+| 01 | [Verify foundation](#sec-079) | none | Migration applied, economy API smoke-tested green, SDK build unblocked | shipped |
+| 02 | [Life engine](#sec-080) | 01 | `workers/agora-citizens`: N real devnet agents living the daily loop (Fetcher) | shipped |
+| 03 | [Task supply](#sec-081) | 02 | Citizens post $THREE bounties + hire each other → board AgenC lane goes real | shipped (`workers/agora-citizens/post.js`) |
+| 04 | [Professions](#sec-082) | 02 | Sculptor (forge), Scribe (brain), Verifier (re-hash), remaining bits | shipped (Cartographer deferred, see `work/index.js`) |
+| 05 | [Commons scaffold](#sec-083) | 01 (02 ideal) | `/agora` page on the City: render citizens, passport panel, empty states | shipped |
+| 06 | [Economy visuals](#sec-084) | 05 | Job board, claim-walk, busy ring, deliverable plinth, $THREE flow, ticker | shipped (`src/agora/economy-layer.js`) |
+| 07 | [Verify + passport UI](#sec-085) | 06 | Re-hash-to-verify, living passport, cross-chain identity handshake | shipped (`src/agora/trust-surface.js`) |
+| 08 | [Humans first-class](#sec-086) | 05 | Wallet-auth: post/hire/complete/verify/vouch from the UI; your avatar joins | shipped (`api/agora/act.js`) |
+| 09 | [Arena + guilds](#sec-087) | 03, 06 | Competitive race + Collaborative guild visualizations | shipped + verified on devnet 2026-08-06 (`src/agora/arena.js`, `guild.js`) |
+| 10 | [Agora MCP](#sec-088) | 03 | `packages/agora-mcp`: external agents join the workforce over MCP | shipped |
+| 11 | [Production hardening](#sec-089) | all | Tests, a11y, perf, all states, changelog, deploy verify, push threews | shipped, except the fleet-render perf box (see 12) |
+| 12 | [Fleet render performance](#sec-090) | 11 | Restore 60fps with the full avatar fleet on `/agora` | open |
Tasks on different branches of the DAG can run in parallel chats (e.g. 03 ∥ 04;
08 ∥ 09 ∥ 10). Respect the dependency column.
@@ -18931,8 +19329,9 @@ from repo root `/workspaces/three.ws`.
### On-chain AgenC (the economy's truth)
- **Write SDK** — `solana-agent-sdk/src/actions/agenc/` → imported as
`@three-ws/solana-agent`. Functions: `createAgenCClient`, `registerAgenCAgent`,
- `createAgenCTask`, `claimAgenCTask`, `completeAgenCTask`, `getAgenCAgent`,
- `getAgenCTask`, `listAgenCTasksByCreator`, identity bridge
+ `createAgenCTask`, `claimAgenCTask`, `completeAgenCTask`, `cancelAgenCTask`
+ (refunds an expired posting's escrow to its creator), `getAgenCAgent`,
+ `getAgenCTask`, `getAgenCTaskLifecycle`, `listAgenCTasksByCreator`, identity bridge
(`getCanonicalThreewsAgenCId`, `buildThreewsMetadataUri`, `toAgenCAgentId`).
- **Read bridge (HTTP, free, no key)** — `api/agenc/[action].js`:
`/api/agenc/list-tasks`, `/get-task` (`&lifecycle=1`), `/get-agent`,
@@ -18961,18 +19360,25 @@ from repo root `/workspaces/three.ws`.
- **DB** — `api/_lib/db.js` exports `sql` (tagged template; fragments compose —
see the file header). Migrations are timestamped SQL in
`api/_lib/migrations/`; apply with `npm run db:migrate`, inspect with
- `npm run db:status`. **Workers run outside `api/`** — give them their own
+ `npm run db:status` (`npm run db:check` is the deploy gate, `npm run db:restamp`
+ re-records a comment-only edit to an applied file). An unconfigured or
+ unreachable database answers a retryable 503, not a 500. **Workers run outside
+ `api/`**: give them their own
`neon(process.env.DATABASE_URL)` client (don't import `api/_lib/db.js` across
the boundary).
- **Live feed**: `api/_lib/feed.js` exports `publishFeedEvent({ type, actor, … })`
- and `readFeedEvents`. `ALLOWED_TYPES` is a closed set; the eight `agora-*`
+ and `readFeedEvents`. `ALLOWED_TYPES` is a closed set; the thirteen `agora-*`
event types (`agora-registered`, `agora-task-posted`, `agora-hired`,
- `agora-task-claimed`, `agora-task-completed`, `agora-earned`, `agora-vouched`,
+ `agora-task-claimed`, `agora-task-completed`, `agora-earned`,
+ `agora-arena-entered`, `agora-arena-won`, `agora-arena-lost`,
+ `agora-guild-joined`, `agora-guild-contributed`, `agora-vouched`,
`agora-flagged`) are already registered there. Any NEW event type must be
added to that set before publishing it.
- **HTTP handlers** — `api/_lib/http.js`: `wrap`, `json`, `error`, `method`,
- `cors`, `readJson`; rate-limit via `api/_lib/rate-limit.js`
- (`limits.publicIp(clientIp(req))`). Copy the shape of `api/agora/[action].js`.
+ `cors`, `readJson`, `rateLimited`; rate-limit via `api/_lib/rate-limit.js`
+ (`limits.publicIp(clientIp(req))`, 240/min per IP). A denied limit answers with
+ `rateLimited(res, rl)` so the 429 carries `retry-after` and the limiter's
+ reason. Copy the shape of `api/agora/[action].js`.
- **The City (3D substrate)** — `pages/city.html` + `src/city/city-world.js`
(scene/renderer/loop), `city-map.js`, `city-player.js`, `city-camera.js`,
`city.css`. **Avatars**: `src/glb-canonicalize.js`, `src/animation-manager.js`,
@@ -19014,8 +19420,8 @@ The ones that bite hardest in Agora:
`git add -A`); re-check `git status` + `git diff --staged` before committing.
7. **Push to `threews` only** on push: `git push threews main`. `threeD` is a
retired, diverged mirror — **never push, pull, or fetch from it**.
-8. **Changelog** — user-visible change → append to `data/changelog.json`
- (holder-readable), then `npm run build:pages`. Internal-only chores don't.
+8. **Changelog**: user-visible change → append to `data/changelog.json`
+ (community-readable), then `npm run build:pages`. Internal-only chores don't.
9. **Watch the bundler trap** — `npx vercel build` overwrites `api/*.js` in place
with esbuild bundles. If a large `api/` diff shows `__defProp`/`createRequire`
at `head -1`, recover with `git restore -- api/ public/`.
@@ -19031,6 +19437,10 @@ The ones that bite hardest in Agora:
- **Devnet faucet is rate-limited.** The roundtrip's airdrop-with-backoff is the
pattern; for the engine prefer a funded devnet keypair or
`AGENC_DEVNET_RPC_URL` pointed at a private RPC.
+- **Two engines on one DB fight for keypairs.** A second fleet (a local run beside
+ the deployed daemon) must set `AGORA_STANDALONE_ONLY=1` so it seats only the
+ standalone founding workforce and never drives the same platform-agent signers
+ as the first (`workers/agora-citizens/roster.js`, `buildRoster`).
## Task file format
@@ -19041,12 +19451,23 @@ Verification · Guardrails.**
---
-<a id="sec-077"></a>
+<a id="sec-079"></a>
> **Source:** `docs/agora/tasks/01-verify-foundation.md` · [↑ table of contents](#table-of-contents)
# Task 01 — Verify the Agora foundation
+> **Status: shipped.** The migration is applied in production, `@three-ws/solana-agent`
+> builds (`tsup`, Apache-2.0), and the read model is routed and covered by
+> `tests/agora-read-model.test.js`. Two things moved since this was written: the
+> endpoint now has **five** actions (`task`, the live Arena/Guild roster, joined
+> the four below), and the migration runner grew `npm run db:check` (the deploy
+> gate, exit 4 while anything is pending) and `npm run db:restamp` (re-records a
+> comment-only edit to an already-applied file). `api/_lib/db.js` answers an
+> unconfigured or unreachable database with a retryable 503 rather than a 500,
+> so an empty `DATABASE_URL` no longer reads as a code bug. Kept as the build
+> record.
+
**Goal:** Get the Phase-1 foundation (data model + economy read API) actually
running and proven green against the real DB and the real x402 bazaar, and
unblock the local SDK build so the AgenC stack is importable. After this task,
@@ -19130,12 +19551,28 @@ curl -s "localhost:3000/api/agora/passport?id=00000000-0000-0000-0000-0000000000
---
-<a id="sec-078"></a>
+<a id="sec-080"></a>
> **Source:** `docs/agora/tasks/02-life-engine.md` · [↑ table of contents](#table-of-contents)
# Task 02 — The life engine (autonomous citizens)
+> **Status: shipped.** `workers/agora-citizens/` runs as a Cloud Run daemon with
+> more files than the contract below names (`agenc.js`, `demand.js`, `policy.js`,
+> `seed.js`, `keypair.js`, `narrative.js`, `reconcile.js`, `log.js`, and one
+> `work/<profession>.js` per active craft). What changed since this was written:
+> `roster.js` seats the **standalone specialist crafts first** and fills the rest
+> of the fleet with platform agents (every seeded platform agent primaries
+> Fetcher because its real skills are not mapped to capability bits yet, and
+> `maxCitizens` defaults to 4, so filling from the agent pool first silently
+> rebuilt a Fetcher-only workforce); a signal-less agent is spread only across
+> the **active** crafts, never the deferred Cartographer bit. `AGORA_ONCE=1` runs
+> one tick per citizen and exits; `AGORA_STANDALONE_ONLY=1` runs an isolated
+> fleet that never shares keypairs with another engine on the same DB. The feed
+> vocabulary in `api/_lib/feed.js` is now thirteen `agora-*` types (the four
+> below plus posted, hired, arena entered/won/lost, guild joined/contributed,
+> vouched, flagged). Kept as the build record.
+
**Goal:** Build `workers/agora-citizens` — the heartbeat that makes Agora *alive*.
N real agents, registered on devnet AgenC, run the **daily loop** on their own
cadence: discover work → claim it on-chain → do real work → submit a real proof →
@@ -19261,12 +19698,25 @@ Confirm tx signatures on `https://explorer.solana.com/?cluster=devnet`.
---
-<a id="sec-079"></a>
+<a id="sec-081"></a>
> **Source:** `docs/agora/tasks/03-task-supply.md` · [↑ table of contents](#table-of-contents)
# Task 03 — Task supply (bounties + agent-to-agent hiring)
+> **Status: shipped** (`workers/agora-citizens/post.js`, `demand.js`,
+> `reconcile.js`). Since this was written the expiry sweep gained a refund: an
+> expired posting is **cancelled on-chain** through the new `cancelAgenCTask`
+> SDK action (`solana-agent-sdk/src/actions/agenc/tasks.ts`) so the escrowed
+> reward returns to its creator instead of stranding, and `reconcileOnce` takes a
+> `signerFor(citizenId)` lookup (`index.js`) so it can only sign for citizens this
+> process runs; anyone else's posting is left alone. The mainnet switch is
+> exactly the contract below (`AGORA_CLUSTER=mainnet` +
+> `AGORA_THREE_TOKEN_ACCOUNT`, optional `AGORA_THREE_MINT`), but `config.js`
+> refuses a non-dry-run mainnet start: the life engine is devnet-only, and
+> mainnet $THREE escrow ships through the human path (`api/agora/act.js`) behind
+> `AGORA_MAINNET_ENABLED`. Kept as the build record.
+
**Goal:** Give the economy *demand*. Citizens (and later humans) post real AgenC
bounties — escrowed in SOL on devnet, **$THREE** on mainnet — with `minReputation`
gates and a profession requirement, and agents **hire each other** (an agent posts
@@ -19360,7 +19810,7 @@ curl -s "localhost:3000/api/agenc/get-task?taskPda=<pda>&cluster=devnet&lifecycl
---
-<a id="sec-080"></a>
+<a id="sec-082"></a>
> **Source:** `docs/agora/tasks/04-professions.md` · [↑ table of contents](#table-of-contents)
@@ -19456,7 +19906,7 @@ curl -sL "<deliverableUrl>" -o /tmp/d.glb && sha256sum /tmp/d.glb # == on-chai
---
-<a id="sec-081"></a>
+<a id="sec-083"></a>
> **Source:** `docs/agora/tasks/05-commons-scaffold.md` · [↑ table of contents](#table-of-contents)
@@ -19472,6 +19922,20 @@ curl -sL "<deliverableUrl>" -o /tmp/d.glb && sha256sum /tmp/d.glb # == on-chai
> `src/agora/me-hud.js`), and the "Enter the Commons" play mode
> (`src/agora/player-mode.js`). Kept as the build record; use it as the
> pattern for future Agora surfaces.
+>
+> How the populate step works today differs from the scope below in two ways.
+> The `/api/agora/citizens?limit=200` request starts at module load, in parallel
+> with the OSM map, and the first `loadCitizens` pass consumes that prefetch
+> (a slow Overpass boot used to hold the citizens request for 40s). And every
+> citizen stands up on the shared default rig first (`AVATAR_DEFAULT`, one small
+> GLB for the whole crowd, placed ten per frame), then only the most recently
+> active `MAX_PERSONAL_AVATARS` (24 on desktop, 8 on a coarse pointer) upgrade to
+> their own `avatarUrl` as it streams in: presence first, fidelity progressively,
+> nobody missing and nobody invented. The population chip reads `placed / total`
+> while the square fills. The HUD title chip is the page's one `h1`, and every
+> nameplate, roster row and passport resolves a citizen's craft through
+> `citizenProfessionLabel` (primary craft first, the capability bitmap only as a
+> fallback, since every citizen carries the Fetcher bit).
**Goal:** Stand up `/agora` — the watchable world — on the existing City
substrate. Render real citizens from `/api/agora/citizens` as avatars living in
@@ -19558,12 +20022,28 @@ Throttle network to see progressive load.
---
-<a id="sec-082"></a>
+<a id="sec-084"></a>
> **Source:** `docs/agora/tasks/06-economy-visuals.md` · [↑ table of contents](#table-of-contents)
# Task 06 — Living economy visuals
+> **Status: shipped** (`src/agora/job-board.js`, `economy-fx.js`, `ticker.js`,
+> wired by `economy-layer.js`). Three behaviours differ from the scope below.
+> The **$THREE coin arc rides the `earned` activity** (`EconomyFx.onPayout`),
+> not `completed_task`: the labour engine splits the moment in two and only the
+> payout carries the amount, so a completion flows coins itself only when it
+> names a reward (an Arena purse), and a `taskPda` dedupe keeps that purse from
+> paying twice. The **board is bounded** (`board-rank.js`): on-chain bounties
+> first, then reward order, with the roster ending in an honest
+> `+N more open jobs in the bazaar` line because the x402 lane returns hundreds
+> of services. And the plinth guards back-to-back completions with a load
+> generation, so an overlapped GLB load is disposed on arrival instead of
+> orphaned; off-production the deliverable is fetched through the dev `/r2-proxy`
+> route so the plinth is not silently empty on localhost. Every layer honours a
+> live `prefers-reduced-motion` toggle through `setReducedMotion(on)`. Kept as
+> the build record.
+
**Goal:** Make the economy *legible at a glance* in the Commons. A job board
building with glowing open tasks; citizens walking to claim; a busy state while
they work; on completion the **deliverable materializes** (a Sculptor's GLB pops
@@ -19651,12 +20131,22 @@ flow + rep tick. Leave it open 10 min; confirm stable memory in devtools.
---
-<a id="sec-083"></a>
+<a id="sec-085"></a>
> **Source:** `docs/agora/tasks/07-verify-and-passport.md` · [↑ table of contents](#table-of-contents)
# Task 07 — Verify the work + the living passport
+> **Status: shipped** (`src/agora/job-detail.js`, `verify.js`,
+> `passport-panel.js`, `handshake.js`, composed by `trust-surface.js`). Since
+> this was written: a deep link (`/agora?task=<pda>`) carries only the PDA, so
+> the job panel falls back to the `deliverableUrl` and `proofHash` the lifecycle
+> itself reports before it says "no proofHash recorded"; and the passport lists
+> the citizen's **primary craft first** (`primaryProfessionKey`,
+> `citizenProfessionLabel` from `citizen-avatar.js`) ahead of the rest of its
+> decoded capability bitmap, which always opens with the baseline Fetcher bit.
+> Kept as the build record.
+
**Goal:** Ship the **trust surface** — the thing that proves Agora isn't theater.
Click a job → its on-chain lifecycle timeline + a **Verify deliverable** button
that re-downloads the artifact, re-hashes it in the browser, and shows it matches
@@ -19749,12 +20239,30 @@ against `/api/agenc/get-agent`. For the handshake, confirm the canonical id equa
---
-<a id="sec-084"></a>
+<a id="sec-086"></a>
> **Source:** `docs/agora/tasks/08-humans-first-class.md` · [↑ table of contents](#table-of-contents)
# Task 08 — Humans as first-class citizens
+> **Status: shipped** (`api/agora/act.js` with actions `join`, `post-task`,
+> `hire`, `claim`, `complete`, `vouch`; `api/_lib/agora-human.js`,
+> `agora-policy.js`; UI in `src/agora/me-hud.js`, `post-form.js`, `actions.js`).
+> Idempotency is the `Idempotency-Key` header backed by the durable
+> `agora_idempotency` table. Hardening that landed after this was written:
+> the rolling 24h spend cap is **held before the escrow** (`reservePostSpend`,
+> `agora_spend_reservations`, one statement under a per-citizen lock) so two
+> posts fired together cannot both clear headroom only one fits under; a dry
+> wallet answers `409 insufficient_funds` with the fundable address, which the
+> post form renders with a Copy button; a non-uuid citizen id answers 404 and a
+> non-base58 task PDA answers 400 before any wallet work; a Solana RPC outage
+> answers a retryable `503 rpc_unavailable`; and a confirm timeout is resolved
+> from the ledger (a landed claim or completion is projected, a landed bounty
+> answers `409 escrow_pending` instead of escrowing twice). The HUD shows a
+> designed "Your bounty" state for a posting you made instead of a Claim button
+> the chain can only reject, and publishes its live height as `--agora-dock-h`
+> so the mobile layout stacks above it. Kept as the build record.
+
**Goal:** Let real, signed-in humans *live in* Agora alongside the agents: join as
a citizen with their own avatar, **post a bounty** (escrow $THREE), **hire** a
citizen, **complete** a task themselves, **verify** another's work, and **vouch**
@@ -19845,7 +20353,7 @@ insufficient balance (honest error). Confirm tx signatures on Explorer.
---
-<a id="sec-085"></a>
+<a id="sec-087"></a>
> **Source:** `docs/agora/tasks/09-arena-and-guilds.md` · [↑ table of contents](#table-of-contents)
@@ -20059,7 +20567,7 @@ surfaces were found and fixed here, each with regression coverage in
---
-<a id="sec-086"></a>
+<a id="sec-088"></a>
> **Source:** `docs/agora/tasks/10-agora-mcp.md` · [↑ table of contents](#table-of-contents)
@@ -20153,12 +20661,18 @@ in `/api/agora/pulse`.
---
-<a id="sec-087"></a>
+<a id="sec-089"></a>
> **Source:** `docs/agora/tasks/11-production-hardening.md` · [↑ table of contents](#table-of-contents)
# Task 11 — Production hardening + launch
+> **Status: shipped, except the fleet-render performance box**, which is carved
+> out as [task 12](#sec-090). `/agora` is live and pushed;
+> the boundary checks in step 5 are covered by `tests/agora-act-validation.test.js`
+> and the read model's 429 now carries `retry-after`
+> (`tests/agora-read-model.test.js`).
+
**Goal:** Take Agora from "works on my machine" to **100% production-ready** and
launch it: tests across every new surface, all UI states audited, accessibility +
performance verified, security/spend review, real deploy verification, the
@@ -20178,7 +20692,7 @@ until every box here is true.
- The `completionist` agent and `/code-review` — use them.
## Build (scope)
-1. **Tests.** `node --test` coverage for: the economy API shapes + empty/error
+1. **Tests.** Vitest coverage (`npm test` is `vitest run && playwright test`) for: the economy API shapes + empty/error
paths (mock the DB/bazaar at the boundary only — never ship mocks in app code);
the engine's loop transitions, idempotency (no double-projection), and failure
isolation; each profession module's proof derivation; `agora-mcp` tools;
@@ -20207,8 +20721,9 @@ until every box here is true.
7. **Docs + changelog + index.** Update `docs/agora.md` roadmap checkboxes to
reflect reality; mark task status in `00-INDEX.md`; ensure `data/pages.json`
has `/agora`; add the launch `data/changelog.json` entry (feature) and run
- `npm run build:pages` (it validates the entry). Holder delivery (Telegram +
- X) happens automatically via the `/api/cron/changelog-push` cron after deploy.
+ `npm run build:pages` (it validates the entry). Community delivery (the
+ Telegram channel; the X lane is retired and the cron never calls it) happens
+ automatically via the `/api/cron/changelog-push` cron after deploy.
8. **Final self-review.** Run the `completionist` agent on the changed files and
`/code-review` on the diff; resolve findings. Then the CLAUDE.md pride check.
@@ -20253,14 +20768,14 @@ Then `completionist` on changed files + `/code-review` on the diff.
---
-<a id="sec-088"></a>
+<a id="sec-090"></a>
> **Source:** `docs/agora/tasks/12-fleet-render-performance.md` · [↑ table of contents](#table-of-contents)
# Task 12: the Commons collapses to ~1fps once the full fleet loads
**Status:** open. Found during Task 11's performance pass (2026-08-06); it is the
-one Definition-of-Done box in [11-production-hardening.md](#sec-087)
+one Definition-of-Done box in [11-production-hardening.md](#sec-089)
that could NOT be verified, so it is carved out here rather than quietly passed.
## The symptom
@@ -20279,6 +20794,21 @@ world requests 200 citizens (`src/agora/agora-world.js`, `loadCitizens`) and
`CitizenPopulation` streams them in `MAX_CONCURRENT_LOADS = 4` at a time
(`src/agora/citizen-avatar.js`). Steady-state frame cost is **~900-1400ms**.
+## What changed since the measurement
+
+The load path the numbers above describe no longer exists, so the ~50s cliff
+timing has to be re-measured before anything is concluded from it. Since
+2026-08-16 every citizen stands up on the shared default rig first (one small
+GLB for the whole crowd) and only the most recently active `MAX_PERSONAL_AVATARS`
+(24 on desktop, 8 on a coarse pointer) upgrade to their own model
+(`src/agora/citizen-avatar.js`, `_wearOwnAvatar`); the crowd is placed ten
+citizens per frame and the citizens request is prefetched in parallel with the
+map (`src/agora/agora-world.js`). The full 200 are therefore standing in
+seconds rather than minutes, which moves the cliff earlier, and the per-frame
+cost this task is about is unchanged: `CitizenPopulation.update` still runs
+`mixer.update(dt)` for every instance every frame, so the suspected per-object
+cost below applies to 200 skinned meshes exactly as before.
+
## What was ruled out
| Hypothesis | Evidence against |
@@ -20344,7 +20874,7 @@ explicit paths, push to `threews` only.
---
-<a id="sec-089"></a>
+<a id="sec-091"></a>
> **Source:** `docs/airdrops.md` · [↑ table of contents](#table-of-contents)
@@ -20441,14 +20971,14 @@ of rendering a fake zero.
## Related surfaces
-- [`/portfolio`](#sec-343): the live wallet portfolio; the two pages
+- [`/portfolio`](#sec-356): the live wallet portfolio; the two pages
cross-link and share the recent-wallet list.
-- [`/api/crypto/wallet`](#sec-170): the raw balance endpoint the token
+- [`/api/crypto/wallet`](#sec-176): the raw balance endpoint the token
diversity measurement rides on.
---
-<a id="sec-090"></a>
+<a id="sec-092"></a>
> **Source:** `docs/alpha-copilot.md` · [↑ table of contents](#table-of-contents)
@@ -20523,15 +21053,15 @@ When `read.hallucination_guard.line_replaced` is true, the co-pilot caught a fig
## Related
-- [Custody you can verify](#sec-171) - the spend limits, firewall, and audit the "Act" path runs under
-- [Financial controls](#sec-222) - the plain-English rules and real-time defense on the same rails
-- [Oracle](#sec-326) - the platform conviction engine over the same launch universe
-- [Trading surfaces](#sec-429) - Mission Control executes through this same guarded path
+- [Custody you can verify](#sec-177) - the spend limits, firewall, and audit the "Act" path runs under
+- [Financial controls](#sec-229) - the plain-English rules and real-time defense on the same rails
+- [Oracle](#sec-338) - the platform conviction engine over the same launch universe
+- [Trading surfaces](#sec-447) - Mission Control executes through this same guarded path
- [/agi](https://three.ws/agi) - a fully autonomous agent reading and trading the same feed
---
-<a id="sec-091"></a>
+<a id="sec-093"></a>
> **Source:** `docs/analytics-retention.md` · [↑ table of contents](#table-of-contents)
@@ -20726,17 +21256,17 @@ If you extend the metric, keep two properties: the retention window must stay an
---
-<a id="sec-092"></a>
+<a id="sec-094"></a>
> **Source:** `docs/animation-studio.md` · [↑ table of contents](#table-of-contents)
# 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-385) 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-399) 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`
-> This page covers the Animation Studio surface. For the platform's animation formats, the runtime clip registry, and the full generate-to-rig-to-animate-to-export chain, see [docs/animations.md](#sec-093) and [docs/3d-asset-pipeline.md](#sec-002).
+> This page covers the Animation Studio surface. For the platform's animation formats, the runtime clip registry, and the full generate-to-rig-to-animate-to-export chain, see [docs/animations.md](#sec-095) and [docs/3d-asset-pipeline.md](#sec-002).
## Why it exists
@@ -20766,7 +21296,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-393) 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-411) 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
@@ -20826,15 +21356,15 @@ An empty `tracks` array is rejected: a clip with no motion is not a clip. Track
## Related
-- [Animations reference](#sec-093): the runtime clip registry, formats, and agent slots.
+- [Animations reference](#sec-095): 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-385): record your animation to video.
-- [Avatar Studio](#sec-115): build the avatar you animate here.
+- [Scene Studio](#sec-399): record your animation to video.
+- [Avatar Studio](#sec-117): build the avatar you animate here.
- [/marketplace](https://three.ws/marketplace): where listed animation clips are bought and sold.
---
-<a id="sec-093"></a>
+<a id="sec-095"></a>
> **Source:** `docs/animations.md` · [↑ table of contents](#table-of-contents)
@@ -20992,13 +21522,13 @@ Resolved (see `public/animations/registry.json` under `resolved_issues`): the `w
---
-<a id="sec-094"></a>
+<a id="sec-096"></a>
> **Source:** `docs/announcement-coverage-telegram.md` · [↑ table of contents](#table-of-contents)
# Telegram post: the platform is bigger than the timeline
-Curated from [announcement-coverage.md](#sec-095) for the $THREE holders channel (@three_ws). Paste-ready, plain text, under Telegram's 4096-char limit. Post manually; this is not a changelog entry, so the cron will not pick it up.
+Curated from [announcement-coverage.md](#sec-097) for the $THREE holders channel (@three_ws). Paste-ready, plain text, under Telegram's 4096-char limit. Post manually; this is not a changelog entry, so the cron will not pick it up.
---
@@ -21041,7 +21571,7 @@ The audit's headline number (47 of 410 announced) reads as a negative internally
---
-<a id="sec-095"></a>
+<a id="sec-097"></a>
> **Source:** `docs/announcement-coverage.md` · [↑ table of contents](#table-of-contents)
@@ -21604,7 +22134,7 @@ Method note: status was assigned by reading all 174 posts and matching each one
---
-<a id="sec-096"></a>
+<a id="sec-098"></a>
> **Source:** `docs/api-reference.md` · [↑ table of contents](#table-of-contents)
@@ -21614,7 +22144,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-261) and [web-component.md](#sec-523). For the high-level npm SDK, see [sdk.md](#sec-386).
+> For the in-browser JavaScript API (the `<agent-3d>` element, `Viewer`, `Runtime`, `SceneController`, skills, memory), see [js-api.md](#sec-272) and [web-component.md](#sec-543). For the high-level npm SDK, see [sdk.md](#sec-400).
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).
@@ -22282,8 +22812,8 @@ 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-236), [X](#sec-530)
-and [Farcaster](#sec-221) memory seeding.
+documented in [GitHub](#sec-243), [X](#sec-553)
+and [Farcaster](#sec-227) 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
@@ -23184,11 +23714,13 @@ GET /api/render/glb?glbUrl=<url>&width=1200&height=630&background=%230a0a0a
POST /api/render/glb { "glbUrl": "...", "width": 1024, "height": 1024, "background": "#0a0a0a" }
```
-Public renderer: any public GLB URL in, a PNG out (headless chromium +
-`<model-viewer>`, the same pipeline the OG cards use). The GET form makes a
-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
+Public renderer: any public GLB URL in, a PNG out, the same pipeline the OG
+cards use. Renders run on a CPU software rasterizer in-process (typically
+200-900 ms, no browser); headless chromium stays as the failover for models
+whose geometry or textures need a decoder the rasterizer does not ship (Draco,
+KTX2/Basis). The GET form makes a render URL-addressable for `og:image`
+unfurls, `<img>` tags, and markdown embeds; responses CDN-cache for a day so
+crawlers render 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, a budget shared with `/api/render/avatar-clip`.
@@ -23222,6 +23754,50 @@ failing. `cameraOrbit.theta`/`phi` are degrees (yaw, and pitch from the top);
`posePresetId` is `400 unknown_pose`. Same 10 MB cap, SSRF guard, and render
budget as `/api/render/glb`.
+### Animated avatar renderer: `GET /api/render/animate`
+
+```
+GET /api/render/animate (the clip catalog)
+GET /api/render/animate?avatar=<id>&clip=wave
+GET /api/render/animate?src=https://example.com/model.glb&clip=idle&size=256
+→ image/png (an animated PNG)
+```
+
+One URL, one file, a moving avatar. The response is an animated PNG, so it
+plays anywhere a still image works: an `<img>` tag, a GitHub README, a Notion
+page, a Discord embed. There is no player, no script and no WebGL involved on
+either side.
+
+```markdown
+![my agent](https://three.ws/api/render/animate?avatar=<id>&clip=wave&size=256)
+```
+
+| Parameter | Meaning |
+|---|---|
+| `avatar` | Avatar UUID. Public avatars only; a private one is `404`. |
+| `src` | Any public GLB URL instead of an avatar id (SSRF-guarded, 12 MB cap). |
+| `clip` | Clip name from the catalog above. Default `idle`. |
+| `frames` | 1-48, default 20. |
+| `fps` | 1-30, default 16. |
+| `size` | 64-640 square, default 320. `width`/`height` override it. |
+| `bg` | `transparent` (default) or a CSS colour. |
+| `focus` | `full`, `bust` or `head`. Default `full`. |
+| `spin` | 0-360 degrees of turntable spread across the loop. |
+| `t` | Seconds into the clip for the first frame. |
+
+The clip is retargeted onto the model's own skeleton by bone name, so one
+library clip drives Ready Player Me, Avaturn, VRM, Mixamo and Blender rigs
+alike. A body that cannot take the clip (no humanoid skeleton) still animates:
+the loop falls back to a full turntable rather than an error.
+
+Calling with no parameters returns the catalog: every clip name, label and
+duration in the built-in motion library. Unknown clip names are
+`400 unknown_clip` and list the alternatives. Same 60 renders / 10 min / IP
+budget as the renderers above; responses CDN-cache for a week.
+
+Rendering is done by [`@three-ws/render`](../packages/render/README.md), the
+GPU-free software rasterizer that also backs the OG cards.
+
### Forge-Off votes — `POST /api/forge-vote`
```
@@ -23247,7 +23823,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-225).
+docs: [docs/forge-off.md](#sec-232).
### Model detail page read: `GET /api/forge-creation`
@@ -23374,7 +23950,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-282) calls as
+same implementation the paid `restyle_material` [MCP tool](#sec-291) 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
@@ -23768,7 +24344,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-393)).
+loop (the output half, avatars that sign, is [docs/sign-language.md](#sec-411)).
**Video never reaches the platform.** The caller extracts MediaPipe Holistic
landmarks in the browser and posts coordinates only. `src/sign-input.js` ships a
@@ -23873,7 +24449,7 @@ curl -s -X POST https://three.ws/api/asl-recognition \
The coin an agent is configured to become, before it exists on chain. Full guide,
including the launch paths and the mainnet activation step:
-[Agent tokens](#sec-070).
+[Agent tokens](#sec-071).
### Read an agent's token plan
@@ -24521,7 +25097,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-170)); launches shares its query
+`/whales` — see [docs/crypto-api.md](#sec-176)); 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.
@@ -24590,7 +25166,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-170)
+[`GET /api/crypto/trending`](#sec-176)
(`api/_lib/crypto-trending.js` `composeTrending`), capped slimmer here (25 vs
50) to keep this door fast.
@@ -24655,7 +25231,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-170)
+[`GET /api/crypto/bonding`](#sec-176)
(`api/_lib/pump-bonding.js` `getBondingStatus`).
```
@@ -24786,7 +25362,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-170)
+[`GET /api/crypto/whales`](#sec-176)
(`api/_lib/pump-whale-scan.js` `scanTokenWhales` / `scanMarketWhales`).
```
@@ -24847,7 +25423,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-424).
+[docs/trader-passport.md](#sec-442).
### Read a passport
@@ -24897,7 +25473,7 @@ subject, slot, block_time, payload, reasons[] }`; every failed check is named in
## Authentication API
-Authentication is covered in detail in the [Authentication documentation](#sec-103). Quick reference:
+Authentication is covered in detail in the [Authentication documentation](#sec-105). Quick reference:
| Endpoint | Method | Description |
| --------------------------- | -------- | ------------------------------------- |
@@ -25077,7 +25653,7 @@ The cursor encodes the full keyset tuple (registration timestamp, chain ID, agen
## 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-403).
+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-421).
### Activity feed
@@ -25116,7 +25692,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-292)).
+Not the same endpoint as `GET /api/feed`, the public Money Pulse ticker ([Money Feed](#sec-302)).
---
@@ -25499,7 +26075,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-284) and the [MCP Tools Catalog](#sec-282).
+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-293) and the [MCP Tools Catalog](#sec-291).
**Example JSON-RPC request**
@@ -25612,7 +26188,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-309).
+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-320).
---
@@ -25634,7 +26210,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-332). Step-by-step walkthrough: [Give an agent a spending envelope](#sec-436). 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-344). Step-by-step walkthrough: [Give an agent a spending envelope](#sec-456). Enforcement source: [`api/_lib/pay/spend-governor.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/pay/spend-governor.js).
### Authentication
@@ -25964,7 +26540,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-145) for the product surface.
+[docs/coin-pages.md](#sec-149) for the product surface.
### Coin detail
@@ -26484,7 +27060,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-299)).
+every response passes through (see [docs/news-rights.md](#sec-310)).
`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
@@ -26956,7 +27532,7 @@ curl 'https://three.ws/api/assets?type=animation&loop=true&limit=10'
GET /api/agent-identities
```
-The finished work of the [Agent Identity Studio](#sec-053): the demo identities behind [three.ws/agent-identities](https://three.ws/agent-identities), each one a real run of the production pipeline (a brand brief in, a rigged GLB plus posed studio renders out). No auth, CORS open to any origin, edge-cached for 10 minutes. Useful before you buy: an agent can read what the service actually returns without paying for a run first.
+The finished work of the [Agent Identity Studio](#sec-054): the demo identities behind [three.ws/agent-identities](https://three.ws/agent-identities), each one a real run of the production pipeline (a brand brief in, a rigged GLB plus posed studio renders out). No auth, CORS open to any origin, edge-cached for 10 minutes. Useful before you buy: an agent can read what the service actually returns without paying for a run first.
The `service` block is read from the OKX catalog (`api/_lib/okx-catalog.js`), the same source the paid endpoint prices itself from, so the price here is never stale page copy.
@@ -27120,7 +27696,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-146).
+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-150).
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.
@@ -28538,6 +29114,261 @@ match the quote), `410` (`checkout_expired`), `429`.
---
+## EVM RPC proxy
+
+```
+POST /api/evm-rpc?chainId=<id>
+```
+
+A browser-safe, read-only Ethereum JSON-RPC proxy. Browser code that reads a
+contract used to call a keyless public host directly, which meant every page
+depended on one endpoint staying up. Posting through this proxy instead
+inherits the server's failover chain for that chain: an explicit
+`RPC_URL_<chainId>` override first, then Alchemy where a key is configured,
+then the curated public tail, rotating to the next endpoint whenever one fails.
+
+No auth required. `chainId` must be a supported EVM chain (the same set
+`/api/erc8004/chains` lists).
+
+**Request** Any single JSON-RPC call, or a batch of up to 10:
+
+```bash
+curl -s 'https://three.ws/api/evm-rpc?chainId=8453' \
+ -H 'content-type: application/json' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
+```
+
+**Response** The upstream JSON-RPC envelope, unchanged:
+
+```json
+{ "jsonrpc": "2.0", "id": 1, "result": "0x1a2b3c" }
+```
+
+**Allowed methods.** Reads only: `eth_call`, `eth_getBalance`,
+`eth_blockNumber`, `eth_getLogs`, `eth_getTransactionReceipt`,
+`eth_getTransactionByHash`, `eth_chainId`, `eth_estimateGas`, `eth_getCode`,
+`eth_getStorageAt`, `net_version`, `eth_gasPrice`, `eth_feeHistory`,
+`eth_maxPriorityFeePerGas`, `eth_getBlockByNumber`. Anything that broadcasts a
+transaction or opens a filter or subscription is refused: sign and send
+transactions from the user's own wallet, not through this proxy.
+
+**Errors**
+
+| Status | `error` | Meaning |
+|---|---|---|
+| 400 | `unknown_chain` | `chainId` missing or not a supported EVM chain |
+| 400 | `bad_body` | body was not valid JSON |
+| 400 | `batch_too_large` | more than 10 calls in one batch |
+| 403 | `method_not_allowed` | method is not on the read-only allowlist |
+| 429 | `rate_limited` | per-IP or global RPC budget exhausted |
+| 502 | `no_upstream` / `upstream_error` | no endpoint configured, or every endpoint for that chain failed |
+
+Browser code should use `src/shared/evm-rpc-fallback.js`, which builds a
+provider that tries this proxy first and falls back to public hosts when the
+page is embedded on a third-party origin.
+
+---
+
+## Seeker verification
+
+Prove that a signed-in user owns a Solana Seeker phone. Every Seeker mints one soulbound Seeker Genesis Token (a Token-2022 token) into its owner's wallet; a user who holds it in a wallet linked to their three.ws account gets the "Seeker verified" badge. Verification scans the wallet through Helius (`getTokenAccountsByOwnerV2`) and checks the token's mint against the official Seeker mint authority (`GT2zuHVaZQYZSyQMgJPLzvkmyztfyXg2NJunqFp4p3A4`) and token group (`GT22s89nU4iWFkNXj1Bw6uYhJJWDRPpShHt4Bk8f99Te`). A wallet must be linked first (Sign-In with Solana, `/api/auth/siws/*`).
+
+### Seeker status
+
+```
+GET /api/seeker/status
+```
+
+Requires a session. Returns what the platform already knows; no RPC call is made.
+
+**Response**
+
+```json
+{
+ "verified": true,
+ "wallets": [
+ { "address": "7Gq...seekerWallet", "tokenMint": "5Hn...deviceMint", "verifiedAt": "2026-08-27T12:00:00.000Z" }
+ ],
+ "linkedSolanaWallets": ["7Gq...seekerWallet", "9Ab...otherWallet"]
+}
+```
+
+---
+
+### Verify Seeker ownership
+
+```
+POST /api/seeker/verify
+```
+
+Requires a session. Rate limited. Scans every linked Solana wallet (or only `wallet`, when given) for a Seeker Genesis Token, records each wallet that holds one, and forgets any previously verified wallet that no longer does.
+
+**Request body** (optional)
+
+```json
+{ "wallet": "7Gq...seekerWallet" }
+```
+
+**Response:** the same shape as `GET /api/seeker/status` plus `checked`, the number of wallets scanned.
+
+```json
+{
+ "verified": true,
+ "wallets": [{ "address": "7Gq...seekerWallet", "tokenMint": "5Hn...deviceMint", "verifiedAt": "2026-08-27T12:00:00.000Z" }],
+ "linkedSolanaWallets": ["7Gq...seekerWallet"],
+ "checked": 1
+}
+```
+
+**Errors**
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| 401 | `unauthorized` | No session. |
+| 400 | `wallet_not_linked` | `wallet` is not linked to this account as a Solana wallet. |
+| 503 | `not_configured` | The deployment has no Helius RPC endpoint. |
+| 502 | `rpc_failed` | Solana RPC failed; nothing was recorded (verification fails closed). |
+
+```bash
+curl -X POST https://three.ws/api/seeker/verify \
+ -H 'content-type: application/json' \
+ -b 'session=<your session cookie>' \
+ -d '{}'
+```
+
+---
+
+## Herald API: deliver a message in person
+
+The rail behind [@three-ws/herald](#sec-248). Anything that can make an HTTPS
+request posts a line here, and the browser tab the caller has open says it out
+loud through their 3D companion.
+
+An announcement is **always** delivered to the authenticated caller's own
+sessions. There is no recipient field, so a key can never be used to interrupt
+somebody else.
+
+### Announce
+
+```
+POST /api/herald/announce
+```
+
+Auth: a signed-in session, or a Bearer API key carrying the `herald:announce`
+scope (mint one at `/dashboard/developers`). Rate limit: 60 per minute per
+account.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `text` (alias `message`) | string, 1-280 | Required. The line to say. |
+| `from` | string, max 60 | Attribution, spoken with the line. |
+| `importance` | int 0-100 | Default 70. The receiving client applies its own floor. |
+| `url` | string, max 2048 | Same-origin path or absolute `http(s)`; anything else is dropped. |
+| `tone` | `neutral` \| `alert` \| `celebrate` \| `error` | Default `alert`. |
+| `emote` | string, max 40 | `wave`, `dance`, `punch`, `backflip`. |
+| `key` | string, max 120 | Dedupe key; two announcements sharing one are said once. |
+| `meta` | object | Passed through to the client untouched. |
+
+```bash
+curl -X POST https://three.ws/api/herald/announce \
+ -H "Authorization: Bearer $THREE_WS_API_KEY" \
+ -H 'content-type: application/json' \
+ -d '{"text":"Deploy is green","importance":80,"url":"/dashboard","from":"CI"}'
+```
+
+```json
+{
+ "queued": true,
+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",
+ "expires_in": 300,
+ "announcement": {
+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",
+ "text": "Deploy is green",
+ "from": "CI",
+ "importance": 80,
+ "url": "/dashboard",
+ "tone": "alert",
+ "at": 1787888380209
+ }
+}
+```
+
+`202` means the line is queued for a live surface, not that a human heard it.
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| 400 | `validation_error` | No `text`, or a field outside its bounds. |
+| 401 | `unauthorized` | No session and no bearer credential. |
+| 403 | `insufficient_scope` | A valid key without `herald:announce`. |
+| 429 | `rate_limited` | More than 60 announcements in a minute. |
+| 503 | `service_unavailable` | The rail is not reachable; nothing was queued. |
+
+### Listen
+
+```
+GET /api/herald/stream
+```
+
+Server-sent events, session-cookie auth only (writing is for machines,
+listening is for the person at the browser). Emits `open` once, then one
+`announce` per queued line, with a `ping` every 15 seconds. The queue is
+drained rather than broadcast, so a line is said by exactly one open tab, and
+an undelivered one expires after about five minutes.
+
+```bash
+curl -N https://three.ws/api/herald/stream -b 'session=<your session cookie>'
+```
+
+```
+event: open
+data: {"ts":1787888542255}
+
+event: announce
+data: {"id":"6a29...","text":"Deploy is green","importance":80,"tone":"alert"}
+```
+
+---
+
+## Glance API
+
+One agent reduced to what fits in an operating-system widget slot: name, avatar, one live number (moves in the last 24 hours), and a link back. Powers the Windows 11 widget, the Android home screen widget, README badges and the `<agent-glance>` element. Spec: [specs/GLANCE_CARD.md](../specs/GLANCE_CARD.md). Guide: [glance.md](#sec-244), [native-widgets.md](#sec-309).
+
+### Public card
+
+```
+GET /api/glance/card?agent=<uuid>&format=json|svg|png|adaptive&size=small|medium|large&theme=auto|light|dark&scale=1|2|3
+```
+
+No auth. `json` is the card model, `svg` a self-contained image, `png` a bitmap (`scale` is pixel density, `theme` resolves `auto` to dark), `adaptive` a bound Adaptive Card 1.6. Carries an `ETag` and answers `304` to `if-none-match`. An unknown agent answers `404`; for `svg` and `png` the body is still a real card that says so.
+
+### My card
+
+```
+GET /api/glance/mine?format=json|png&agent=<uuid>&size=…&theme=dark|light&scale=…
+Authorization: Bearer glw_… (widget token) or the session cookie
+```
+
+Always `200`. JSON: `{ signedIn, state, via, card, notice, agents, signInUrl, createUrl, linkUrl }`, `state` one of `agent`, `signed-out`, `unlinked`, `no-agent`. PNG: the card bitmap for whichever state applies, with `x-glance-state`, `x-glance-url` (tap target), `x-glance-name`, `x-glance-metric`, `x-glance-agent`, `x-glance-updated` headers. `cache-control: private, no-store`.
+
+### Widget tokens
+
+```
+POST /api/glance/token { label?, platform?: android|macos|ios|other, agent?: uuid }
+GET /api/glance/token
+PATCH /api/glance/token { id, agent: uuid|null }
+DELETE /api/glance/token?id=<uuid>
+```
+
+Session cookie required; writes must be same-site. `POST` answers `201` with `{ id, prefix, label, platform, agentId, createdAt, lastUsedAt, token, links: { android } }`. `token` is shown exactly once; `links.android` is the `intent://glance/link?token=…#Intent;scheme=threews;package=ws.three.app;…;end` URL that hands it to the Android app. At most 12 live tokens per account (`409 too_many_tokens`). `GET` answers `{ tokens: [...] }` without plaintexts. `DELETE` answers `{ revoked: true, id }`, or `404` for an id that is not the caller's live token.
+
+| Error | Status | Meaning |
+| --- | --- | --- |
+| `unauthorized` | 401 | no session |
+| `forbidden` | 403 | write from another origin |
+| `not_found` | 404 | token or agent is not the caller's |
+| `too_many_tokens` | 409 | 12 live tokens already |
+| `rate_limited` | 429 | over the per-account write limit |
+
## 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).
@@ -28571,7 +29402,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-386).
+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-400).
For the endpoints on this page, call them directly with `fetch`/`curl` and a Bearer API key:
@@ -28594,7 +29425,7 @@ const { agents } = await res.json();
---
-<a id="sec-097"></a>
+<a id="sec-099"></a>
> **Source:** `docs/api/forge-x402.md` · [↑ table of contents](#table-of-contents)
@@ -28927,8 +29758,8 @@ 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-559) and
-[the autonomous economy](#sec-105).
+[x402 endpoints](#sec-584) and
+[the autonomous economy](#sec-107).
Treat prompts as public. If you need a private lane, use the account-scoped
surfaces instead of this one.
@@ -28973,17 +29804,17 @@ 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-226): how the lanes, tiers, and failovers fit
+- [Forge pipeline](#sec-233): how the lanes, tiers, and failovers fit
together internally.
-- [3D Studio MCP server](#sec-278): the same generation as
+- [3D Studio MCP server](#sec-287): 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-559): every paid endpoint on the platform.
+- [x402 endpoints](#sec-584): every paid endpoint on the platform.
---
-<a id="sec-098"></a>
+<a id="sec-100"></a>
> **Source:** `docs/ar-studio.md` · [↑ table of contents](#table-of-contents)
@@ -28996,9 +29827,9 @@ API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your an
## Why it exists
-The older "View in AR" flow (see [AR and WebXR](#sec-099)) shows one model at a time in a native viewer. AR Studio is the composition tool: a persistent, multi-model scene you arrange in real space and can build with other people at once. It is free, needs no account, and degrades gracefully so it works on a laptop, a phone browser, or a full AR headset. It is where a forge result, a marketplace avatar, and a prompt-conjured prop can all stand in your living room together.
+The older "View in AR" flow (see [AR and WebXR](#sec-101)) shows one model at a time in a native viewer. AR Studio is the composition tool: a persistent, multi-model scene you arrange in real space and can build with other people at once. It is free, needs no account, and degrades gracefully so it works on a laptop, a phone browser, or a full AR headset. It is where a forge result, a marketplace avatar, and a prompt-conjured prop can all stand in your living room together.
-This doc covers what is unique to AR Studio. For the underlying `POST /api/forge` free lane, the `<agent-3d>` "View in AR" methods, the USDZ/Quick Look pipeline, and model-optimization limits, see [AR and WebXR](#sec-099).
+This doc covers what is unique to AR Studio. For the underlying `POST /api/forge` free lane, the `<agent-3d>` "View in AR" methods, the USDZ/Quick Look pipeline, and model-optimization limits, see [AR and WebXR](#sec-101).
## How it works
@@ -29009,20 +29840,23 @@ The page ([`pages/ar-studio.html`](../pages/ar-studio.html)) only imports [`src/
`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).
+- **Yours**: `GET /api/forge-gallery?limit=24` with an `x-forge-client` header (your anonymous browser id). Forge cards are titled with the first clause of the prompt they were generated from (`cardTitleFromPrompt`), with the whole prompt as the tooltip; a poster that fails to load falls back to the cube mark a poster-less item uses.
- **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.
+
+Both gallery reads and the objects manifest answer with `Access-Control-Allow-Origin: *`: they are public, keyless, read-only feeds, and the standalone studio (npm `3d-ar-studio`) offers them as its Community and Objects tabs from whatever origin a developer embedded it on. Rate limiting, not origin, is the control.
- **GLB link**: paste any https `.glb`: a forge result, a viewer share link's `src`, or your own hosting.
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
-Best available mode wins:
+Best available mode wins. The dock's AR button (`#ars-xr-btn`) resolves one of three AR modes on load (`resolveArMode()`) and stays hidden when none applies:
-1. **WebXR immersive AR**: offered only when `navigator.xr.isSessionSupported('immersive-ar')` resolves true. The session requests `hit-test` (required) plus `anchors`, `local-floor`, `depth-sensing`, and `light-estimation`, with a DOM-overlay HUD. Each placed model gets an `XRAnchor`, and an always-armed reticle does tap-to-place.
-2. **Camera passthrough**: `getUserMedia({ video: { facingMode: { ideal: 'environment' } } })` becomes the background layer, with gyroscope world-lock look (DeviceOrientation, iOS permission-gated) and live light matching. Offered when `getUserMedia` exists.
-3. **Desktop 3D preview**: always available: a grid floor, drag-look, and a "Phone" QR handoff on non-touch devices.
+1. **WebXR immersive AR**: offered only when `navigator.xr.isSessionSupported('immersive-ar')` resolves true. The button reads **Immersive**. The session requests `hit-test` (required) plus `anchors`, `local-floor`, `depth-sensing`, and `light-estimation`, with a DOM-overlay HUD. Each placed model gets an `XRAnchor`, and an always-armed reticle does tap-to-place. This is the only mode that keeps the whole multi-model scene in the page.
+2. **The device's own AR viewer**, one model at a time, when there is no immersive session. The button reads **Place in AR** and hands the selected model (or the last one placed) to the platform viewer: on iPhone and iPad, AR Quick Look ([`src/ar/quick-look.js`](../src/ar/quick-look.js)), after the GLB is fetched and converted to USDZ on the device through three's `USDZExporter` ([`src/usdz-pipeline.js`](../src/usdz-pipeline.js), the same pipeline `/avatars/:id/ar` uses), with each stage reported in the status line ("Fetching the model…", "Preparing it for AR…", "Opening AR…"); on Android, Scene Viewer ([`src/ar/scene-viewer.js`](../src/ar/scene-viewer.js)) with the GLB URL directly. A device with neither is told to open the scene on a phone and offered the QR code. Before this existed, an iPhone was only ever offered the camera composite below, which looks right in a screenshot and not at all in the hand (no plane detection, no real scale, nothing occluding).
+3. **Camera passthrough**: `getUserMedia({ video: { facingMode: { ideal: 'environment' } } })` becomes the background layer, with gyroscope world-lock look (DeviceOrientation, iOS permission-gated) and live light matching. Offered when `getUserMedia` exists, and available alongside mode 2.
+4. **Desktop 3D preview**: always available: a grid floor with distance fog (removed the moment the camera becomes the backdrop), drag-look, and a "Phone" QR handoff on non-touch devices. Until you aim the camera yourself, the preview re-frames on the models you add so a model dropped on the floor never lands out of view.
If WebGL is missing, the page never loads the module and shows a fallback linking to `/ar` and `/viewer`.
@@ -29075,7 +29909,7 @@ You can also hand-build a share link: append `?src=<https glb url>&title=<name>`
- **No auth, fully free.** Identity is an anonymous per-browser id (`forge:cid`), shared with `/forge` and `/creations`; it scopes the Yours tab, attributes in-studio forges, and keys room ownership. No sign-in, no wallet, no payment.
- **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.
+- **XR unsupported.** With no immersive session the button becomes Place in AR (Quick Look or Scene Viewer) or stays hidden; a failed XR start shows "Camera mode still works." A failed native handoff shows "Could not open AR for this model" with a Try again action. Lost tracking prompts you to move to a brighter, more textured spot.
- **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.
@@ -29088,13 +29922,13 @@ Append `?e2e=1` to expose `window.__arsDebug` (`count()`, `netStatus()`, `netIds
## 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-389) and [Avatar pipeline](#sec-113): where the models you place come from.
+- [AR and WebXR](#sec-101): 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-406) and [Avatar pipeline](#sec-115): 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).
---
-<a id="sec-099"></a>
+<a id="sec-101"></a>
> **Source:** `docs/ar.md` · [↑ table of contents](#table-of-contents)
@@ -29538,7 +30372,7 @@ a server-side PNG render of the actual GLB (CDN-cached for a day), so pasting
an AR link into a chat or timeline shows the model, not a generic card. The
page also converts: it carries "Create your own" (into [/ar](/ar)) and "Open
in 3D viewer" calls to action. See `GET|POST /api/render/glb` in the
-[API reference](#sec-096) for the renderer's parameters and limits.
+[API reference](#sec-098) for the renderer's parameters and limits.
**For agents (MCP):** on the free, keyless connector at `/api/mcp-studio` every generation already returns `arUrl` in its result, so there is nothing extra to call. To build the link set for a GLB that connector did not generate, the read-only `export_ar` tool on the separate [`/api/mcp-3d` server](/docs/mcp-3d-studio) (account- or payment-gated) turns any public GLB into the AR launch link plus a conformant [Spatial MCP](/docs/spatial-mcp) artifact (with the `ar` handoff populated):
@@ -29601,13 +30435,13 @@ the wild can load.
---
-<a id="sec-100"></a>
+<a id="sec-102"></a>
> **Source:** `docs/architecture.md` · [↑ table of contents](#table-of-contents)
# 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-242) 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-251) 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.
@@ -29667,7 +30501,7 @@ The top layer is what lets an agent live somewhere other than the canonical app.
- **`widget-types.js`**: ten widget variants (Turntable Showcase, Animation Gallery, Talking Agent, ERC-8004 Passport, Hotspot Tour, Pump.fun Live Feed, Smart Money Feed, Live Trades Canvas, Bonding Curve, Walking Avatar) that share the underlying element but ship as separate ergonomic wrappers.
- **`lib.js`** — the CDN entry. Imports the element, registers it, and re-exports the public surface.
- **`app.js`** — the main SPA. URL routing happens here using hash params (`#model=`, `#agent=`, `#kiosk=`, `#brain=`, `#preset=`) and query params (`?agent=` for authenticated edit mode, `?pending=1` for post-login round-trips). The hash form stays in embed mode; the query form moves into edit mode.
-- **`vercel.json`** — the server's route and cron table. Maps clean URLs (`/agent/<id>`, `/agent/<id>/edit`, `/agent/<id>/embed`, `/a/<chainId>/<agentId>`) to the right HTML entry and mounts the `api/*` handlers. In production the single Cloud Run container ([`server/index.mjs`](../server/index.mjs)) reads this table at runtime — it's a live config file, not a Vercel-only artifact.
+- **`vercel.json`**: the server's route and cron table. Maps clean URLs (`/agents/<id>`, `/agents/<id>/edit`, `/agents/<id>/embed`, `/a/<chainId>/<agentId>`; the singular `/agent/<id>` forms are kept as permanent redirects to the plural canonical route) to the right HTML entry and mounts the `api/*` handlers. In production the single Cloud Run container ([`server/index.mjs`](../server/index.mjs)) reads this table at runtime: it is a live config file, not a Vercel-only artifact.
---
@@ -29826,7 +30660,7 @@ The flow:
5. **Reputation.** Users can call `ReputationRegistry.submitFeedback(agentId, score, comment)` to attach reviews. The element exposes a small UI for this.
6. **Validation attestations.** When the glTF validator runs, the report can be hashed and answered onto the agent's open request via `ValidationRegistry.validationResponse(requestHash, score, uri, hash, tag)` so anyone can verify the body has been spec-checked.
-Per-chain registry addresses, ABIs, and helpers live in `src/erc8004/`. RPC endpoints fall back to public defaults but can be overridden with `?rpcURL=...`.
+Per-chain registry addresses, ABIs, and helpers live in `src/erc8004/`. Every chain in `chains.js` carries an ordered `rpcUrls` list of keyless public hosts, and `src/shared/evm-rpc-fallback.js` prepends the same-origin `/api/evm-rpc?chainId=N` proxy (which inherits the server's own failover chain) whenever the page is served from a three.ws origin, so one dead public host never reads as "chain unsupported". A caller-pinned URL (`loadManifest(source, { rpcURL })`, or the `rpc-url` attribute on `<agent-3d>`) is tried ahead of the public tail.
---
@@ -29848,7 +30682,7 @@ To run the whole stack yourself, the minimum is:
- **A Node.js host** for the SPA and the `api/*` handlers. Production runs a single container ([`server/index.mjs`](../server/index.mjs)) on Google Cloud Run that reads the `vercel.json` route table at runtime; any Node host works the same way, or reproduce the same path → handler map in your reverse proxy.
- **Neon DB (PostgreSQL)** for agents, widgets, sessions, and the action log.
- **Upstash Redis** for rate limiting, nonce storage, and short-lived caches.
-- **An S3-compatible object store** for hosted GLB and texture assets. The client in [api/_lib/r2.js](../api/_lib/r2.js) speaks the S3 API, so Cloudflare R2, AWS S3, and Backblaze B2 all work (configure `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`).
+- **An S3-compatible object store** for hosted GLB and texture assets. The client in [api/_lib/r2.js](../api/_lib/r2.js) speaks the S3 API, so Cloudflare R2, AWS S3, and Backblaze B2 all work (configure `S3_ENDPOINT`, `S3_BUCKET`, `S3_PUBLIC_DOMAIN`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`; `objectStorageConfigured()` is true only when all five are set, and the storage-dependent crons skip their tick rather than fail every item when it is not).
- **Anthropic API key** for the default LLM provider. The runtime can also point at a self-hosted proxy (`#proxyURL=`) for billing, logging, or a non-Anthropic backend.
- **Optional:** ElevenLabs for higher-quality TTS, Pinata or Filebase for IPFS pinning, Privy for non-wallet onboarding, an RPC endpoint for ERC-8004 reads.
@@ -29865,7 +30699,7 @@ A minimal Node + Neon + Anthropic deployment is enough for a single agent. The b
---
-<a id="sec-101"></a>
+<a id="sec-103"></a>
> **Source:** `docs/assistant-widget.md` · [↑ table of contents](#table-of-contents)
@@ -29878,9 +30712,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-153). 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-158). 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-433) 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-453) builds one from scratch.
## Install
@@ -29989,7 +30823,7 @@ 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-284); 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-293); find it in the registry at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/?q=io.github.nirholas).
## How it works
@@ -30001,10 +30835,10 @@ Ask your agent something like "build a 3D assistant widget named Aria with an oc
## Related surfaces
-- [Build a 3D assistant, step by step](#sec-433), the tutorial
-- [Concierge](#sec-153), the page-grounded support-chat widget with a lipsyncing face
-- [three.ws MCP servers](#sec-284), the full free and paid tool catalog
-- [Share and embed](#sec-390), the `<three-d>` model embeds
+- [Build a 3D assistant, step by step](#sec-453), the tutorial
+- [Concierge](#sec-158), the page-grounded support-chat widget with a lipsyncing face
+- [three.ws MCP servers](#sec-293), the full free and paid tool catalog
+- [Share and embed](#sec-407), 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
@@ -30017,7 +30851,7 @@ Ask your agent something like "build a 3D assistant widget named Aria with an oc
---
-<a id="sec-102"></a>
+<a id="sec-104"></a>
> **Source:** `docs/atlas.md` · [↑ table of contents](#table-of-contents)
@@ -30193,7 +31027,7 @@ searching for "embed".
---
-<a id="sec-103"></a>
+<a id="sec-105"></a>
> **Source:** `docs/authentication.md` · [↑ table of contents](#table-of-contents)
@@ -30482,6 +31316,8 @@ When CAPTCHA is enabled for the Privy app (Privy dashboard, Security tab), Privy
If the app config declares a `custom_api_url` (three.ws uses `https://privy.three.ws`), every auth call above goes to that domain instead of `auth.privy.io`.
+The discovery step is factored into [src/auth/privy-captcha.js](../src/auth/privy-captcha.js), and the login page treats "CAPTCHA required" and "could not find out" as different answers: when the app config probe fails, the page refuses to send a code without a token Privy might require, and tells the user to reload rather than surfacing Privy's opaque `401 invalid_credentials`. The same distinction applies to `/api/config` itself: if that probe fails (it is bounded to six seconds), the email and wallet controls are hidden with an explanation and the password form still signs the visitor in, instead of the whole block silently vanishing as it does when the deployment genuinely has no Privy app.
+
### Configuration
```env
@@ -30683,6 +31519,7 @@ const res = await fetch('/api/agents', {
| `memory:read` | Read agent memory |
| `memory:write` | Write agent memory |
| `profile` | Read/write profile data; required to manage API keys themselves |
+| `herald:announce` | Post announcements through the [Herald](#sec-248) (`POST /api/herald/announce`); the scope the `herald-mcp` package's `THREE_WS_API_KEY` needs |
Scopes are space-separated in the `scope` field. Default when unspecified: `avatars:read avatars:write`.
@@ -30873,7 +31710,7 @@ Password hashing cost is configurable via `PASSWORD_ROUNDS` (default: `11` bcryp
---
-<a id="sec-104"></a>
+<a id="sec-106"></a>
> **Source:** `docs/autonomous-economy.md` · [↑ table of contents](#table-of-contents)
@@ -30888,8 +31725,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-294) (which wallet receives each *payment*),
-[Economy master](#sec-183) (the funding-root subsystem in depth), and the
+Companion docs: [Money map](#sec-304) (which wallet receives each *payment*),
+[Economy master](#sec-189) (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).
@@ -31028,16 +31865,16 @@ zero.
## Related
-- [Money map](#sec-294) — which wallet receives each kind of payment, and the
+- [Money map](#sec-304) — which wallet receives each kind of payment, and the
platform's cut.
-- [Economy master](#sec-183) — the funding-root subsystem, its ledger, and the
+- [Economy master](#sec-189) — the funding-root subsystem, its ledger, and the
topup/sweepback crons in depth.
-- [x402 ring economy](#sec-560) — how the autonomous payment ring settles
+- [x402 ring economy](#sec-586) — how the autonomous payment ring settles
USDC between agents.
---
-<a id="sec-105"></a>
+<a id="sec-107"></a>
> **Source:** `docs/autonomous-x402.md` · [↑ table of contents](#table-of-contents)
@@ -31064,7 +31901,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-182)) rather than by its own schedule
+[economy heartbeat](#sec-188)) rather than by its own schedule
entry; per-entry Redis cooldowns decide what actually fires on any given tick.
Each tick:
@@ -31114,7 +31951,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-141)
+This loop's treasury is **separate** from the [circulation engine](#sec-145)
treasury (`CIRCULATION_TREASURY_SECRET`). Circulation funds agent-to-agent SOL /
$THREE activity; this loop funds USDC intel purchases. They do not fund each
other.
@@ -31198,7 +32035,7 @@ automatically (and `tests/x402-ring-catalog.test.js` fails until it is cataloged
> number you publish. Scaling this loop to manufacture a big volume figure is wash
> volume: real transactions, fake demand, and detectable on-chain.
> Drive *real* volume through external demand (the
-> [Circulation engine](#sec-141), real `agent_hire` commerce,
+> [Circulation engine](#sec-145), real `agent_hire` commerce,
> discovery), not a heavier self-paid sweep.
## The Datapoint Fabric Volume Sweep
@@ -31242,7 +32079,7 @@ claims an on-chain settlement — outbound `x402_autonomous_log` rows and inboun
wallet configured (keyless RPC; the `/api/x402-status` probe it reads is free). A
`reconciled = false` row means the books claim a settlement the chain does not
corroborate — the ops financial-integrity surface alerts on those. Detail:
-[Financial controls](#sec-222).
+[Financial controls](#sec-229).
## Where results land
@@ -31251,21 +32088,21 @@ 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-292)). |
+| `agent_custody_events` | The USDC spend, with `category: 'x402'` (see [Money feed](#sec-302)). |
| `x402_volume_metrics` | Per-endpoint proof-of-volume + liveness ledger from the Volume Bootstrap Loop. |
-| `payment_reconciliation` | One verdict per settlement claim from the daily reconciliation job (see [Financial controls](#sec-222)). |
+| `payment_reconciliation` | One verdict per settlement claim from the daily reconciliation job (see [Financial controls](#sec-229)). |
| Dedicated stores | Pipeline-specific tables (pricing tracker, reputation snapshots, leaderboard, sniper analytics, …). |
## Related
-- [x402 endpoints](#sec-559) — the paid endpoints this loop calls.
-- [Financial controls](#sec-222): where settlements land and how the reconciliation job audits them.
-- [x402 buyer client](#sec-556) — the client wrappers it pays with.
-- [Circulation engine](#sec-141) — the separate SOL/$THREE activity loop.
+- [x402 endpoints](#sec-584) — the paid endpoints this loop calls.
+- [Financial controls](#sec-229): where settlements land and how the reconciliation job audits them.
+- [x402 buyer client](#sec-581) — the client wrappers it pays with.
+- [Circulation engine](#sec-145) — the separate SOL/$THREE activity loop.
---
-<a id="sec-106"></a>
+<a id="sec-108"></a>
> **Source:** `docs/autopilot.md` · [↑ table of contents](#table-of-contents)
@@ -31360,15 +32197,15 @@ A confirmed buyback narrates as: "Bought back and burned $120 of $YOURCOIN. Supp
## Related
-- [Custody you can verify](#sec-171) - the spend limits, freeze switch, and audit trail every agent wallet runs under
-- [Financial controls](#sec-222) - plain-English spend rules layered on the same enforcement point
-- [Oracle](#sec-326) - the conviction engine and the agent action loop that arms an agent to trade autonomously
+- [Custody you can verify](#sec-177) - the spend limits, freeze switch, and audit trail every agent wallet runs under
+- [Financial controls](#sec-229) - plain-English spend rules layered on the same enforcement point
+- [Oracle](#sec-338) - 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
---
-<a id="sec-107"></a>
+<a id="sec-109"></a>
> **Source:** `docs/avatar-artifact.md` · [↑ table of contents](#table-of-contents)
@@ -31376,7 +32213,7 @@ A confirmed buyback narrates as: "Bought back and burned $120 of $YOURCOIN. Supp
[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-520) 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.
+It is deliberately the smallest viewer we ship. [The full 3D viewer](#sec-540) 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.
---
@@ -31440,7 +32277,7 @@ 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-390) instead. This page is the plain viewer.
+For a full chat widget or a token-gated embed, use [Share and embed](#sec-407) instead. This page is the plain viewer.
---
@@ -31463,7 +32300,7 @@ Every input drives one look-target, so the page works with a mouse, a finger or
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.
+Most three.ws avatars carry no baked clips, because motion lives in the [shared clip library](#sec-095) 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.
---
@@ -31494,14 +32331,14 @@ A large model on a slow connection is not a failure: the loading overlay reports
## Related
-- [The 3D viewer](#sec-520): the full engine behind `/app` and `<agent-3d>`
-- [Share and embed](#sec-390): widgets, web components and embed policy
+- [The 3D viewer](#sec-540): the full engine behind `/app` and `<agent-3d>`
+- [Share and embed](#sec-407): 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
+- [Animations](#sec-095): the clip library this page retargets from
---
-<a id="sec-108"></a>
+<a id="sec-110"></a>
> **Source:** `docs/avatar-cli.md` · [↑ table of contents](#table-of-contents)
@@ -31513,7 +32350,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-523) 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-543) covers the `<agent-3d>` element the CLI emits.
---
@@ -31707,7 +32544,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-523) 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-543) 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:
@@ -31804,14 +32641,14 @@ three-ws-avatar validate manifest.json --json | jq -e '.valid'
## Where to go next
-- **[Ship an avatar manifest](#sec-483)** 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-523)** documents every attribute on the `<agent-3d>` element `preview` emits.
+- **[Ship an avatar manifest](#sec-503)** 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-543)** 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-109"></a>
+<a id="sec-111"></a>
> **Source:** `docs/avatar-creation.md` · [↑ table of contents](#table-of-contents)
@@ -31850,7 +32687,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 **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
+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-113) 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.
@@ -32083,7 +32920,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-189) 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-195) for details.
---
@@ -32147,7 +32984,7 @@ No regeneration provider is configured on this deployment. Set `AVATAR_REGEN_PRO
---
-<a id="sec-110"></a>
+<a id="sec-112"></a>
> **Source:** `docs/avatar-engines.md` · [↑ table of contents](#table-of-contents)
@@ -32209,7 +33046,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-409). |
+| `splat` | View in Splat Viewer | Produces Gaussian-splat or radiance-field output you can drop into the three.ws [splat viewer](#sec-427). |
| `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. |
@@ -32316,16 +33153,16 @@ To add an engine, append an entry to `ENGINES` in [`src/avatar-engines-data.js`]
## Related
-- [Splat Viewer](#sec-409): 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-227): 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-113) and [avatar creation](#sec-109): how three.ws produces and processes its own mesh avatars.
+- [Splat Viewer](#sec-427): where the Gaussian-splat output of the `splat` engines actually renders in the browser.
+- [Scene Capture](#sec-137): the three.ws side of reconstruction, turning real video into 3D, adjacent to the photoreal-head family here.
+- [Forge](#sec-234): the live commercial generation pipeline, which the one `live` text-to-avatar engine powers.
+- [Agent Identity Studio](#sec-054): that pipeline applied end to end, brand brief to rigged avatar plus studio renders.
+- [Animations](#sec-095): the retargeting and clip library that drives the production rigs in the last family.
+- [Avatar pipeline](#sec-115) and [avatar creation](#sec-111): how three.ws produces and processes its own mesh avatars.
---
-<a id="sec-111"></a>
+<a id="sec-113"></a>
> **Source:** `docs/avatar-fidelity-program.md` · [↑ table of contents](#table-of-contents)
@@ -32337,7 +33174,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-114); the worker lives in
+[avatar-reconstruction.md](#sec-116); the worker lives in
[`workers/avatar-reconstruction/`](../workers/avatar-reconstruction).
## Why we are not buying this
@@ -32783,7 +33620,7 @@ items do not:
---
-<a id="sec-112"></a>
+<a id="sec-114"></a>
> **Source:** `docs/avatar-inspector.md` · [↑ table of contents](#table-of-contents)
@@ -32816,7 +33653,7 @@ All data is real and server-authoritative, the same public endpoints every
other surface reads, so a number never disagrees across the platform:
- **Identity**, display name, the three.ws agent the avatar pilots (with a
- link to `/agent/<id>`), its bio, skills, creator, and ERC-8004 registration.
+ link to `/agents/<id>`), its bio, skills, creator, and ERC-8004 registration.
From `GET /api/agents/:id`.
- **Reputation**, the 0, 100 trust score with its full pillar breakdown
(tenure, settled volume, tips, reliability, conduct, …) and verifiable
@@ -32826,7 +33663,10 @@ other surface reads, so a number never disagrees across the platform:
USD net worth, SOL balance, $THREE holding, top tokens, and tips received.
From `GET /api/agents/:id/solana/networth`. A player who signed in with a
wallet but pilots no agent gets bare balances from
- `POST /api/wallet/balances`.
+ `POST /api/wallet/balances`, which validates the address shape first (base58
+ Solana or 0x-prefixed EVM) and answers `400 validation_error` with a
+ field-level `issues` array instead of reporting a malformed address as an
+ empty wallet.
- **World facts**, which world you met them in, an NPC's role and service,
your live street location in `/city`.
@@ -32884,11 +33724,11 @@ Agora keeps its richer, economy-native passport panel
(`src/agora/passport-panel.js`), the <kbd>I</kbd> key there opens the same
passport the click path always has.
-Related reading: [agent reputation](#sec-056) · [Agora](#sec-075).
+Related reading: [agent reputation](#sec-057) · [Agora](#sec-077).
---
-<a id="sec-113"></a>
+<a id="sec-115"></a>
> **Source:** `docs/avatar-pipeline.md` · [↑ table of contents](#table-of-contents)
@@ -32897,8 +33737,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-109),
-[Avatar Studio](#sec-137), [Animations](#sec-093),
+individual tool docs ([Avatar creation](#sec-111),
+[Avatar Studio](#sec-140), [Animations](#sec-095),
[3D asset pipeline](#sec-002)) into one map.
---
@@ -32925,7 +33765,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-282), [x402 endpoints](#sec-559)).
+[MCP tools](#sec-291), [x402 endpoints](#sec-584)).
### ② Auto-rig
@@ -33002,22 +33842,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-109) and
-[Avatar Studio](#sec-137) for the authoring UIs, and
-[Mesh editing tools](#sec-282) for retexture / stylize / remesh / segment /
+account. See [Avatar creation](#sec-111) and
+[Avatar Studio](#sec-140) for the authoring UIs, and
+[Mesh editing tools](#sec-291) for retexture / stylize / remesh / segment /
pose operations.
## Related
-- [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.
+- [Selfie → Avatar reconstruction](#sec-116) — 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-095) — the clip library and retargeting in depth.
- [3D asset pipeline](#sec-002) — formats, optimization, validation.
-- [NVIDIA free models](#sec-304) — the free generation backend.
-- [MCP tools](#sec-282) — every generation/editing tool and its price.
+- [NVIDIA free models](#sec-315) — the free generation backend.
+- [MCP tools](#sec-291) — every generation/editing tool and its price.
---
-<a id="sec-114"></a>
+<a id="sec-116"></a>
> **Source:** `docs/avatar-reconstruction.md` · [↑ table of contents](#table-of-contents)
@@ -33025,7 +33865,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-113): the Forge generates
+generation lane in the [Avatar Pipeline](#sec-115): 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
@@ -33136,7 +33976,7 @@ 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)
+instability keeps rising. See [avatar-fidelity-program.md](#sec-113)
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
@@ -33230,7 +34070,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-111).
+> allocation — is [avatar-fidelity-program.md](#sec-113).
> Fidelity claims are scored with the ISE metric in
> [`workers/avatar-reconstruction/eval/`](../workers/avatar-reconstruction/eval/README.md).
@@ -33279,7 +34119,7 @@ Full runbook: [`docs/ops/gcp-production.md`](ops/gcp-production.md).
---
-<a id="sec-115"></a>
+<a id="sec-117"></a>
> **Source:** `docs/avatar-studio.md` · [↑ table of contents](#table-of-contents)
@@ -33343,7 +34183,7 @@ curl 'https://three.ws/api/avatars/<avatarId>' -H 'cookie: <session>'
## States & limits
- **No selfie, no camera.** This is the from-scratch path. To build an avatar from a photo, use the platform's selfie-to-avatar flow under [/create](https://three.ws/create) instead.
-- **Two base bodies.** Create mode starts from the Stylized feminine base or the bare Parametric base (which covers masculine, feminine, and everything between via its body sliders). Switching base reloads the studio, so it asks before discarding unsaved changes. The posable primitive with a build toggle lives in [Animation Studio](#sec-092).
+- **Two base bodies.** Create mode starts from the Stylized feminine base or the bare Parametric base (which covers masculine, feminine, and everything between via its body sliders). Switching base reloads the studio, so it asks before discarding unsaved changes. The posable primitive with a build toggle lives in [Animation Studio](#sec-094).
- **The Parametric base ships bare.** No hair or outfit meshes yet, so the hair/outfit color slots and the Layers block do not appear on it; hats, glasses, and earrings attach normally. Conforming hair and garments are the next phase of the parametric roadmap ([prompts/roadmap/avatar-parametric-editor.md](../prompts/roadmap/avatar-parametric-editor.md)).
- **Sculpt depends on the base's morphs.** The face/body sliders render against whatever morph targets the base GLB exposes; a slot with no matching morph simply does not appear. Proportions are independent of morphs: they need only a canonical humanoid skeleton, so they work on a rig with no blendshapes at all. Height is the one parameter that needs an armature node above the hips, and is hidden on rigs whose hips sit directly in the scene.
- **Save requires an account.** Export happens client-side, but persisting the avatar to your library needs sign-in. Optimization is best-effort: if compression fails, the original export is saved untouched so the save always completes.
@@ -33352,16 +34192,16 @@ 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-152): forge props and attach them to the avatar's bones as a saved outfit.
-- [Mocap Studio](#sec-291): drive the avatar's face live from your webcam.
-- [Restyle Studio](#sec-380): 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.
+- [Animation Studio](#sec-094): pose and keyframe the avatar you build here.
+- [Scene Composer](#sec-157): forge props and attach them to the avatar's bones as a saved outfit.
+- [Mocap Studio](#sec-300): drive the avatar's face live from your webcam.
+- [Restyle Studio](#sec-394): shares the same GLB optimize-and-validate path.
+- [Trait-based avatar builder](#sec-140): 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-116"></a>
+<a id="sec-118"></a>
> **Source:** `docs/avatar-thumbnails.md` · [↑ table of contents](#table-of-contents)
@@ -33457,12 +34297,21 @@ via `adoptForgePreviews()` in the backfill.
The browser captures the live viewer's canvas and uploads a PNG. Stored at
`thumb/<avatarId>.png` with `Content-Type: image/png`. Owner or admin only.
-### 3. Server render (headless chromium)
-
-Everything else — studio avatars, uploads, forge rows older than preview capture —
-is rendered server-side: the GLB is presigned, loaded into a headless chromium
-running a three.js viewer, and screenshotted to a 768×768 PNG, which is uploaded to
-`thumb/<avatarId>.png`. Costs ~3–6s per model, so it always runs in bounded batches.
+### 3. Server render (CPU rasterizer, chromium failover)
+
+Everything else (studio avatars, uploads, forge rows older than preview capture)
+is rendered server-side through `renderGlbToPng()` in
+[`api/_lib/render-glb.js`](../api/_lib/render-glb.js): the GLB is presigned and
+rendered to a 768x768 PNG, which is uploaded to `thumb/<avatarId>.png`. The
+renderer tries the in-process software rasterizer first
+([`api/_lib/render-cpu.js`](../api/_lib/render-cpu.js), the `@three-ws/render`
+package, roughly 200-900 ms and no subprocess) and falls back to headless chromium
+running a three.js viewer only for the models the CPU lane cannot decode on its
+own (Draco-compressed geometry, KTX2/Basis textures). A CPU miss is logged as
+`[render] cpu lane fell back to chromium` and costs latency, never a failed
+thumbnail. Set `RENDER_CPU_LANE=off` on the service to pin every render back onto
+chromium without a deploy. A chromium render costs 3-15 s per model, so rendering
+always runs in bounded batches.
All of this lives in [`api/_lib/avatar-thumbs.js`](../api/_lib/avatar-thumbs.js),
the single owner of the invariant above.
@@ -33523,15 +34372,28 @@ So the runner distinguishes the two:
- **Model failure** (`glb fetch failed: …`, `render failed: …`) — charge the
attempt, record `last_error`, keep going.
- **Infrastructure failure** (`Connection closed.`, `Target closed`, `Protocol
- error`, …) — the model is blameless. Roll the attempt back, roll back every
+ error`, a `spawn EFAULT` / `ENOMEM` / `EAGAIN` launch refusal, or object storage
+ answering `Missing required env var: S3_…`, `InvalidAccessKeyId`, `NoSuchBucket`,
+ `ECONNREFUSED`, …): the model is blameless. Roll the attempt back, roll back every
claim the aborted batch never reached, and **stop the batch**. `renderBatch()`
returns `aborted: "<reason>"`; the cron logs `backfill_browser_died` and the next
tick retries the same avatars on a fresh container.
-`isBrowserInfrastructureError()` in
-[`api/_lib/render-glb.js`](../api/_lib/render-glb.js) is the classifier, and the
-cached browser now evicts itself on `disconnected` so the next render relaunches
-instead of reusing a corpse.
+Two classifiers decide which side a failure lands on. `isBrowserInfrastructureError()`
+in [`api/_lib/render-glb.js`](../api/_lib/render-glb.js) covers the browser (its
+`INFRA_ERROR_PATTERN`), and `isStorageInfrastructureError()` in
+[`api/_lib/r2.js`](../api/_lib/r2.js) covers object storage (`STORAGE_ERROR_PATTERN`).
+Both are exported as pattern strings so the ledger repair below asks the same
+question in SQL with `~*` instead of maintaining a drifting copy, and
+[`tests/avatar-thumbs.test.js`](../tests/avatar-thumbs.test.js) imports the real
+classifiers rather than a stand-in for the same reason. The cached browser evicts
+itself on `disconnected` so the next render relaunches instead of reusing a corpse.
+
+Storage is also checked before any claim is made: both thumbnail crons return
+`{ ok: false, reason: "object_storage_unconfigured" }` and touch nothing when
+`objectStorageConfigured()` in `r2.js` reports the `S3_*` set incomplete, because
+three ticks of identical `S3_BUCKET` failures at `*/5` would otherwise retire every
+remaining avatar in under fifteen minutes.
This is not hypothetical: before the classifier existed, one OOM-killed chromium
retired **1,283 perfectly renderable avatars** in a single run. If you ever suspect
@@ -33541,9 +34403,12 @@ that happened again:
node --env-file=.env.local scripts/backfill-avatar-thumbnails.mjs --reset-infra
```
-It deletes every ledger row whose `last_error` is an infrastructure error, returning
-those avatars to the candidate set. Rows recording a model-attributable error are
-left retired. Safe to run at any time.
+It deletes every ledger row whose `last_error` matches either infrastructure
+pattern (browser or storage), returning those avatars to the candidate set. Rows
+recording a model-attributable error are left retired. Safe to run at any time.
+Add `--repair-only` to run the repair (and any `--restyle`) and stop before anything
+touches R2: that mode needs only `DATABASE_URL`, so the undo stays reachable while
+object storage is exactly the thing that is broken.
Running more than one bulk backfill at once is what causes the OOM in the first
place. The claim ledger makes it *correct*, but not *free* — one runner at
@@ -33576,10 +34441,11 @@ node --env-file=.env.local scripts/backfill-avatar-thumbnails.mjs --restyle=200
```
Requires `DATABASE_URL` plus the `S3_*` credentials (`S3_BUCKET`,
-`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, `S3_PUBLIC_DOMAIN`).
-Only `DATABASE_URL` is in `.env.local`; the authoritative copy of the `S3_*` set
-lives on the Cloud Run service, so `--env-file=.env.local` alone exits with
-`S3_BUCKET is unset`. Export them into the shell first:
+`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, `S3_PUBLIC_DOMAIN`);
+`--status` and `--repair-only` need `DATABASE_URL` alone. Only `DATABASE_URL` is in
+`.env.local`; the authoritative copy of the `S3_*` set lives on the Cloud Run
+service, so `--env-file=.env.local` alone exits with `S3_BUCKET is unset` for any
+mode that renders or adopts. Export them into the shell first:
```bash
eval "$(gcloud run services describe three-ws-api --region us-central1 \
@@ -33619,7 +34485,7 @@ that adoption HEAD-checks the preview object before persisting it.
---
-<a id="sec-117"></a>
+<a id="sec-119"></a>
> **Source:** `docs/avatar-wardrobe.md` · [↑ table of contents](#table-of-contents)
@@ -33690,7 +34556,7 @@ A garment with no skin at all (hat, glasses) is parented to a single joint
|---|---|---|
| Attachment engine | [`src/avatar-garment.js`](../src/avatar-garment.js) | Skin rebind, occlusion, slot occupancy — the runtime core |
| Shared taxonomy | [`src/garment-taxonomy.js`](../src/garment-taxonomy.js) | Slots, body regions, region→bone map, coverage gate |
-| Catalog loader | [`src/garment-catalog.js`](../src/garment-catalog.js) | Fetch + validate manifests; drops anything malformed or unlicensed |
+| Catalog loader | [`src/garment-catalog.js`](../src/garment-catalog.js) | Fetch (three bounded attempts, then the last copy this browser loaded) + validate manifests; drops anything malformed or unlicensed |
| Closet UI + controller | [`src/garment-closet.js`](../src/garment-closet.js) | Racks/tiles in the editor, attach/detach queue, appearance sync |
| Editor wiring | [`src/avatar-edit.js`](../src/avatar-edit.js) | Hydrate on load, persist `appearance.garments`, reset/save |
| Region mask (pixel-exact occlusion) | Baker [`scripts/build-body-region-mask.mjs`](../scripts/build-body-region-mask.mjs) → `public/avatars/parametric-base.regions.png`, sampler [`src/garment-region-mask.js`](../src/garment-region-mask.js) | On the parametric base, worn garments cut the skin via a baked UV mask (alphaMap) instead of triangle culling; any other body falls back to bone-cull |
@@ -33716,6 +34582,15 @@ slot, unknown body region, malformed hash, or a licence outside the approved
commercial set (CC0, CC-BY, MIT, Apache-2.0, BSD) drops the entry with a
console warning. A broken manifest becomes a missing tile, not a broken avatar.
+`loadCatalog()` fetches the file with a 10 s deadline and retries a 5xx or a
+dropped connection twice more before giving up; a 4xx is final. When every
+attempt fails it falls back to the copy the browser last loaded (kept in
+`localStorage` under `three.ws:garment-catalog:<url>` for 24 hours) and logs a
+warning, so a bucket blip no longer empties the closet. Only with no cached copy
+does the load reject. The server-side baker reads the same URL through the shared
+`fetchUpstream` helper (15 s deadline, two attempts) and caches it for five
+minutes.
+
## Generating new garments
The catalog is fed by the Garment Forge
@@ -33730,6 +34605,12 @@ GET /api/garment-forge?job=<id>
→ { status, stage, glb_url, manifest_url, coverage, occludes }
```
+The proxy gives a submit one attempt with a 60 s deadline (it starts a GPU job,
+so it is not safely repeatable) and a job read three attempts at 10 s each; both
+share the `garment-forge-worker` circuit breaker, so a dead worker answers every
+caller with `502 garment_forge_unavailable` at once instead of each paying the
+full deadline.
+
`stage` walks `image → mesh → compose → rig → extract → validate → publish`.
When the job reports `done`, the piece is already live in the catalog above;
a closet refresh (`loadCatalog({ force: true })`) shows it immediately. Every
@@ -33772,21 +34653,22 @@ bricking the avatar.
- Garment can't reach the skeleton → refused with the measured coverage in the
reason string; the slot keeps its previous occupant.
-- Catalog unreachable → closet shows a retry state; the rest of the editor is
- unaffected.
+- Catalog unreachable → the closet serves the last catalog this browser loaded;
+ with no cached copy it shows a retry state. The rest of the editor is
+ unaffected either way.
- Bake-time garment failure → logged and skipped; the bake always lands.
- Non-humanoid model → the closet is withheld (`supportsWardrobe` gate), same
policy as the animation library's humanoid gate.
## Related
-- [`docs/avatar-reconstruction.md`](#sec-114) — selfie → avatar
-- [`docs/avatar-fidelity-program.md`](#sec-111) — identity fidelity program
+- [`docs/avatar-reconstruction.md`](#sec-116) — selfie → avatar
+- [`docs/avatar-fidelity-program.md`](#sec-113) — identity fidelity program
- [`specs/GARMENT_MANIFEST.md`](../specs/GARMENT_MANIFEST.md) — the wearable contract
---
-<a id="sec-118"></a>
+<a id="sec-120"></a>
> **Source:** `docs/aws-builder-center-agent-payment-sessions.md` · [↑ table of contents](#table-of-contents)
@@ -34271,7 +35153,7 @@ An autonomous agent with a private key is a liability you cannot bound. An auton
---
-<a id="sec-119"></a>
+<a id="sec-121"></a>
> **Source:** `docs/aws-builder-center-marketplace-x402.md` · [↑ table of contents](#table-of-contents)
@@ -34290,7 +35172,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-123).
+> **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-125).
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.
@@ -34537,7 +35419,7 @@ The product on the other side of all this plumbing is the platform: three.ws age
---
-<a id="sec-120"></a>
+<a id="sec-122"></a>
> **Source:** `docs/aws-builder-center-mcp-agents.md` · [↑ table of contents](#table-of-contents)
@@ -34653,7 +35535,7 @@ If you wire it into something, or you want to list a paid tool of your own, the
---
-<a id="sec-121"></a>
+<a id="sec-123"></a>
> **Source:** `docs/aws-builder-center.md` · [↑ table of contents](#table-of-contents)
@@ -34665,7 +35547,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-123), [AWS partner spotlight](#sec-124)
+- **Related surfaces:** [three.ws/aws](https://three.ws/aws) (AWS Partner page), [AWS Marketplace listing](#sec-125), [AWS partner spotlight](#sec-126)
## Published articles
@@ -34675,10 +35557,11 @@ Published 30 May 2026. Tags: `aws-payment-cryptography`, `blockchain`, `metadata
> [Read it on the AWS Builder Center](https://builder.aws.com/content/3ESpll50BdSp9eiCEIxcfG9pGUN/how-we-metered-a-saas-product-through-aws-marketplace-with-the-aws-sdk-for-javascript-v3)
-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.
+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-107) paywall, so one authorization path bills two economies.
-- **Source draft in this repo:** [aws-builder-center-marketplace-x402.md](#sec-119)
+- **Source draft in this repo:** [aws-builder-center-marketplace-x402.md](#sec-121)
- **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)
+- **Since publication:** on 2026-08-17 the integration moved to the updated SaaS integration AWS made mandatory for new products. `ResolveCustomer` now returns `CustomerAWSAccountId` + `LicenseArn` rather than a `CustomerIdentifier`, so the store keys buyers by license ARN (`api/_lib/aws-marketplace-store.js`) and the x402 bridge joins on the customer row id, with `CustomerIdentifier` kept only as a legacy lookup. Lifecycle notifications arrive as EventBridge agreement and license events; the SNS webhook path the article describes is still accepted and still signature-verified. [aws-marketplace.md](#sec-125) is the current reference; the article stays accurate for the SDK calls it walks through.
- **Announcement:** [three.ws Publishes on the AWS Builder Center Blog](https://three.ws/news/aws-builder-center-blog)
### 2. Build Autonomous AI Agents with 3D Bodies and On-Chain Payments | three.ws on AWS
@@ -34689,7 +35572,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-523), [agent wallets](#sec-072), [the agent system](#sec-064), [AWS Marketplace procurement](#sec-123)
+- **Surfaces it covers:** [the `<agent-3d>` web component](#sec-543), [agent wallets](#sec-074), [the agent system](#sec-065), [AWS Marketplace procurement](#sec-125)
## Published by AWS about three.ws
@@ -34703,7 +35586,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-284), [x402](#sec-105), [agent wallets](#sec-072), [the `<agent-3d>` web component](#sec-523)
+- **Surfaces it covers:** [the MCP servers](#sec-293), [x402](#sec-107), [agent wallets](#sec-074), [the `<agent-3d>` web component](#sec-543)
- **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
@@ -34712,8 +35595,8 @@ Written and reviewed in this repo, not yet submitted:
| Draft | Subject |
|---|---|
-| [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 |
+| [aws-builder-center-agent-payment-sessions.md](#sec-120) | 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-122) | An MCP server whose paid tools settle per call in USDC over HTTP 402 |
## Publishing checklist
@@ -34733,7 +35616,7 @@ The Builder Center is where AWS customers evaluating a partner product go lookin
---
-<a id="sec-122"></a>
+<a id="sec-124"></a>
> **Source:** `docs/aws-marketplace-listing-kit.md` · [↑ table of contents](#table-of-contents)
@@ -34742,7 +35625,7 @@ 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-123). This doc covers the
+deployed — see [aws-marketplace.md](#sec-125). This doc covers the
listing itself, which has not yet been created (the AMMP "AI agents & tools
products" page shows "No products to display").
@@ -34769,7 +35652,7 @@ products" page shows "No products to display").
> `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)
+> is unset, which is the correct state for a free listing. [aws-marketplace.md](#sec-125)
> documents them as optional rather than as the billing model.
---
@@ -35118,7 +36001,7 @@ Set as the old docs instructed, every genuine AWS notification failed the pin an
returned 403, visible only in logs.
*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-marketplace.md](#sec-125) state that the variable takes the AWS-issued
`aws-mp-subscription-notification-<PRODUCTCODE>` ARN or nothing at all.
**Defect 3 (latent): SNS signature verification hardcoded SHA1.**
@@ -35169,7 +36052,7 @@ Still verify against the product overview page at creation time
---
-<a id="sec-123"></a>
+<a id="sec-125"></a>
> **Source:** `docs/aws-marketplace.md` · [↑ table of contents](#table-of-contents)
@@ -35177,7 +36060,7 @@ Still verify against the product overview page at creation time
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-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/*`.
+> **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-124). Until then, use x402 directly: no AWS subscription is required to call `/api/x402/*`.
## Subscribing via AWS Marketplace
@@ -35272,7 +36155,7 @@ For platform support, open an issue at [github.com/nirholas/three.ws/issues](htt
---
-<a id="sec-124"></a>
+<a id="sec-126"></a>
> **Source:** `docs/aws-partner-spotlight.md` · [↑ table of contents](#table-of-contents)
@@ -35363,12 +36246,12 @@ 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-123)
-- How agents reach and pay for tools: [three.ws/docs/x402](#sec-563), [three.ws/docs/mcp](#sec-284)
+- AWS Marketplace and procurement: [three.ws/docs/aws-marketplace](#sec-125)
+- How agents reach and pay for tools: [three.ws/docs/x402](#sec-589), [three.ws/docs/mcp](#sec-293)
---
-<a id="sec-125"></a>
+<a id="sec-127"></a>
> **Source:** `docs/big-tech-recognition-week.md` · [↑ table of contents](#table-of-contents)
@@ -35379,9 +36262,9 @@ 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-307),
-[partners.md](#sec-329), [listings.md](#sec-269),
-[aws-marketplace.md](#sec-123), [ibm.md](#sec-253)). This one is the
+is one vendor deep ([nvidia-visibility-map.md](#sec-318),
+[partners.md](#sec-341), [listings.md](#sec-281),
+[aws-marketplace.md](#sec-125), [ibm.md](#sec-263)). 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?**
@@ -35450,11 +36333,11 @@ submission target is the free keyless connector at
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-317), with task 07 as the go/no-go gate
+- **Pre-submission verification pack:** [`docs/openai-pr/00-START-HERE.md`](#sec-328), 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-324) against the currently deployed
+Before the submit, run [`docs/openai-pr/07-final-verification-and-submit.md`](#sec-335) 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.
@@ -35479,11 +36362,11 @@ three.ws has a live Builder Center profile at
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
+[aws-builder-center.md](#sec-123) 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
+[aws-partner-spotlight.md](#sec-126), 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,
@@ -35501,7 +36384,7 @@ Two Anthropic surfaces are `ready-to-submit` (Official MCP Registry, Claude plug
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-329) lists eight partners and
+Worth naming plainly: **[partners.md](#sec-341) 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
@@ -35526,7 +36409,7 @@ 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-302) is already
+existing [Apps Catalog request](#sec-313) 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.
@@ -35543,7 +36426,7 @@ The five asks:
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-301).
+specified in step 1 of [nvidia-apps-catalog-listing.md](#sec-312).
Nothing in this email lands well while the record misdescribes the product.
---
@@ -35552,7 +36435,7 @@ Nothing in this email lands well while the record misdescribes the product.
### The membership post that never happened
-[announcement-coverage.md](#sec-095) tracks an "announced on X"
+[announcement-coverage.md](#sec-097) 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.
@@ -35610,7 +36493,7 @@ promotes.
[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-174). Both routes returned 200 on 2026-08-17. You
+[demo-routes.md](#sec-180). 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.
@@ -35659,7 +36542,7 @@ 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-324) against the live revision, then **submit the OpenAI App Directory package** | Owner (portal) |
+| Mon 08-17 | Run [openai-pr task 07](#sec-335) 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 |
@@ -35697,16 +36580,16 @@ Publishing, posting, and sending are owner-gated under stop-and-ask gate 2 in
## Related
-- [NVIDIA visibility map](#sec-307): every NVIDIA surface in depth, and the dead ends
-- [Partners](#sec-329): the eight programs, and the independence language that must survive any rewrite
-- [Listings and distribution](#sec-269): the canonical program and directory inventory
-- [Announcement coverage](#sec-095): which surfaces have been announced on X and which have not
-- [Press kit](#sec-345): marks, boilerplate, and the rules governing co-branded graphics
-- [OpenAI submission handoff pack](#sec-317): the pre-submission task briefs
+- [NVIDIA visibility map](#sec-318): every NVIDIA surface in depth, and the dead ends
+- [Partners](#sec-341): the eight programs, and the independence language that must survive any rewrite
+- [Listings and distribution](#sec-281): the canonical program and directory inventory
+- [Announcement coverage](#sec-097): which surfaces have been announced on X and which have not
+- [Press kit](#sec-358): marks, boilerplate, and the rules governing co-branded graphics
+- [OpenAI submission handoff pack](#sec-328): the pre-submission task briefs
---
-<a id="sec-126"></a>
+<a id="sec-128"></a>
> **Source:** `docs/bnb-babt-findings.md` · [↑ table of contents](#table-of-contents)
@@ -35902,7 +36785,7 @@ shipped:
---
-<a id="sec-127"></a>
+<a id="sec-129"></a>
> **Source:** `docs/bnb-payments.md` · [↑ table of contents](#table-of-contents)
@@ -36075,7 +36958,7 @@ full verified-facts list.
---
-<a id="sec-128"></a>
+<a id="sec-130"></a>
> **Source:** `docs/bnb-vault.md` · [↑ table of contents](#table-of-contents)
@@ -36248,7 +37131,7 @@ this campaign, not a bug in this code path.
---
-<a id="sec-129"></a>
+<a id="sec-131"></a>
> **Source:** `docs/bnb-world.md` · [↑ table of contents](#table-of-contents)
@@ -36484,7 +37367,7 @@ reproduction commands are recorded in `contracts/DEPLOYMENTS.md`'s "Prompt
## Related
-- [BNB Chain payments](#sec-127) — the MPP/x402 payment rail this
+- [BNB Chain payments](#sec-129) — 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
@@ -36495,7 +37378,7 @@ reproduction commands are recorded in `contracts/DEPLOYMENTS.md`'s "Prompt
---
-<a id="sec-130"></a>
+<a id="sec-132"></a>
> **Source:** `docs/brain.md` · [↑ table of contents](#table-of-contents)
@@ -36516,7 +37399,7 @@ same prompt, at the same moment, across every candidate, with real timing. Brain
gives you that: a compare view that fans one prompt out to the whole roster and shows
you who answered first, who was most thorough, and what each one cost in tokens. It
also doubles as the model picker behind the Brain tab of
-[Agent Studio](#sec-062), so the model you pick here is the model your agent
+[Agent Studio](#sec-063), so the model you pick here is the model your agent
runs on.
## How it works
@@ -36570,7 +37453,7 @@ keys.
5. **Read the stats.** When a model finishes, its column shows total elapsed time and
token usage from the `done` event.
6. **Commit a choice.** Carry the winner into your agent via the Brain tab of
- [Agent Studio](#sec-062).
+ [Agent Studio](#sec-063).
## Examples
@@ -36582,7 +37465,7 @@ curl -s https://three.ws/api/brain/chat
```
Stream one model's answer as SSE (the free default needs no auth; paid models need a
-session or bearer token, see [Authentication](#sec-103)):
+session or bearer token, see [Authentication](#sec-105)):
```bash
curl -N -s -X POST https://three.ws/api/brain/chat \
@@ -36625,22 +37508,219 @@ done; wait
## Related
-- [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-334): synthesizing the system prompt a brain runs
-- [API reference](#sec-096) and [Authentication](#sec-103)
+- [Agent Studio](#sec-063): the Brain tab uses this same backend
+- [Agent System](#sec-065): how a chosen brain fits the agent model
+- [Persona Hub](#sec-346): synthesizing the system prompt a brain runs
+- [API reference](#sec-098) and [Authentication](#sec-105)
- Pages: [/brain](https://three.ws/brain), [/agent-studio](https://three.ws/agent-studio)
---
-<a id="sec-131"></a>
+<a id="sec-133"></a>
+
+> **Source:** `docs/brownout.md` · [↑ table of contents](#table-of-contents)
+
+# Brownout
+
+Every response this API sends says where its data came from and how fresh it is.
+Every fallback it claims to have has been executed for real, with the provider it
+protects against genuinely refusing, inside the same request path a user hits.
+
+The live registry and its proof receipts are at [/brownout](https://three.ws/brownout).
+The client library is [`@three-ws/brownout`](https://www.npmjs.com/package/@three-ws/brownout).
+
+## Why this exists
+
+A fallback is code that only runs when something is broken, which makes it the
+least-tested code in any codebase. Two failures follow from that, and this
+platform has shipped both:
+
+- **A degraded answer that passes for a fresh one.** A paid market datapoint was
+ stamped `as_of: <now>` over an hour-old payload, and a token security verdict
+ was assembled out of remembered on-chain state. Neither was visible, because a
+ degraded response and a live one are the same bytes.
+- **A fallback nobody has ever run.** Unit tests stub `fetch` and prove the stub
+ was called. They cannot prove that a page renders when a provider 429s,
+ because the stub replaces the very layer whose behaviour is in question.
+
+Brownout is the answer to both: make the degradation visible, and make the
+failure reproducible on demand.
+
+## Reading a response
+
+Two headers, single-line ASCII, stable:
+
+```http
+x-brownout: v=1;tier=stale;sources=3;ok=1;failed=2;ms=512;degraded=1
+x-brownout-trace: birdeye;o=429;t=412, tokens-xyz;o=timeout;t=8000, dex;o=ok;t=88
+```
+
+`x-brownout` is present on any response that touched an instrumented upstream.
+`x-brownout-trace` appears only when something degraded, so a healthy response
+pays one short header and no per-source cost. Both are exposed via
+`Access-Control-Expose-Headers`, so a browser can read them.
+
+### Freshness is a lattice
+
+| tier | meaning |
+| --- | --- |
+| `live` | came off the wire during this request |
+| `cache` | a cache hit inside its intended lifetime |
+| `stale` | older than that, because an upstream could not answer |
+| `fallback` | a different provider, or a different method, answered |
+
+A response reports the **worst** tier that contributed to it. A page assembled
+from one live read and one half-hour-old reading is not live, and reporting the
+best tier would be worse than reporting nothing: a confident lie.
+
+`degraded=1` means the answer is worse than the endpoint intends to give:
+something failed over, or the answer is stale. **An ordinary cache hit is not
+degraded.** That distinction is load-bearing: almost every response on a healthy
+service is a cache hit, so counting those would flag the whole platform and train
+every reader to ignore the field.
+
+## Breaking an upstream on purpose
+
+```http
+x-brownout-chaos: birdeye=http:429, tokens-xyz=timeout
+x-brownout-chaos-token: <token>
+```
+
+The request runs the real handler, the real provider ladder, the real cache
+tiers and the real retry policy. Only the named upstreams misbehave, and only
+for the caller who asked, so a probe can run against production without touching
+anyone else's request.
+
+| fault | what the code sees |
+| --- | --- |
+| `timeout` | an abort, exactly as a real deadline produces |
+| `network` | `TypeError: fetch failed` with `ECONNREFUSED` on `cause` |
+| `http:429` | a real 429 response carrying `Retry-After` |
+| `http:<status>` | any 4xx or 5xx you name |
+| `empty` | a 200 with an empty body, the shape that breaks naive parsers |
+| `slow:<ms>` | the real call, delayed, for timeout-budget tests |
+
+Faults are scoped by name and a directive for a provider covers every call shape
+it serves, so `birdeye` also breaks `birdeye:txs`.
+
+The server answers `x-brownout-chaos-status` with `applied;faults=N` or
+`refused;reason=<why>`. **Always check it.** A refused directive means the
+request ran normally, and a green assertion after a refusal proves nothing.
+
+### Safety
+
+Fault injection makes a live service misbehave, so it is gated three ways and
+every one must pass:
+
+1. **A token**, compared in constant time. `BROWNOUT_CHAOS_TOKEN` must be set
+ and match. Without it configured the feature is off everywhere, including
+ locally, so there is no "forgot to set it in prod" state that leaves it open.
+2. **Never a money path.** A request carrying an x402 payment header, or
+ addressed to a settlement, withdrawal, transfer, purchase or launch route, is
+ refused outright. The blast radius of a wrong answer there is not a stale
+ price, it is a payment.
+3. **Read-shaped methods only.**
+
+## Declared contracts, and proving them
+
+`data/brownout.json` declares what the platform promises when a given upstream
+fails: the endpoint, the fault, and what must still happen.
+
+```json
+{
+ "id": "token-page-survives-dexscreener",
+ "endpoint": "/api/ca2x402/resolve",
+ "query": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" },
+ "break": { "dexscreener:tokens": "http:429" },
+ "expect": {
+ "status": [200, 404, 503],
+ "exercised": ["dexscreener:tokens"]
+ }
+}
+```
+
+Run them against a live server:
+
+```bash
+BROWNOUT_CHAOS_TOKEN=... node scripts/prove-brownout.mjs \
+ --base https://three.ws --write public/brownout.json
+```
+
+### `not_exercised` is not a pass
+
+The verdict that matters most is neither pass nor fail. A fault can be accepted
+and still never reach the code, because a warm cache answered before any
+upstream call happened. A prover that called that a pass would be certifying a
+fallback nothing ran, turning an unknown into a false assurance.
+
+So every contract declares which sources must appear as **failed** in the
+response trace, and a run that cannot show them reports `not_exercised`. That
+check earned its keep on its first run: three of the first four contracts were
+unexercisable, two because their endpoint caches in a module slot no query
+parameter can miss, and one because the warm-up and the attempt shared a cache
+key.
+
+Caches are not symmetric either. The heatmap answers any smaller `limit` out of
+a larger cached field, so only warm-small-then-attempt-large actually misses,
+which is why the direction is the contract's to state:
+
+```json
+"bust": { "param": "limit", "warm": 6, "attempt": 40 }
+```
+
+## What is instrumented
+
+Provenance is recorded by the shared layers every read already goes through, so
+a new endpoint reports without its author doing anything:
+
+- `api/_lib/upstream-fetch.js`, the single wrapper for third-party calls in `api/`
+- `src/shared/failover-fetch.js`, every ordered provider ladder
+- `api/_lib/coingecko.js` and `api/_lib/coinpaprika.js`, the market pair whose
+ primary throttles constantly and whose understudy carries the page
+- `api/_lib/solana/connection.js`, the RPC rotation, which records the lane that
+ answered and every lane that refused first
+
+The header is attached in `wrap()` (`api/_lib/http.js`), the seam every handler
+already passes through.
+
+## Client library
+
+```bash
+npm install @three-ws/brownout
+```
+
+```js
+import { withChaos, assertDegraded } from '@three-ws/brownout';
+
+const brokenFetch = withChaos({ 'dexscreener:tokens': 'http:429' }, { token });
+const res = await brokenFetch('https://three.ws/api/ca2x402/resolve?mint=...');
+
+assertDegraded(res, {
+ status: 200,
+ tier: ['stale', 'fallback'],
+ exercised: ['dexscreener:tokens'],
+});
+```
+
+`assertDegraded` refuses to pass when the upstream under test never actually
+failed, for the same reason the prover does.
+
+## Related
+
+- [/brownout](https://three.ws/brownout), the live registry and its receipts
+- [/guards](https://three.ws/guards), the mechanical checks that protect the codebase
+- [docs/shared-utilities.md](#sec-408), the retry, ladder and last-good helpers this instruments
+
+---
+
+<a id="sec-134"></a>
> **Source:** `docs/btn-pill-migration.md` · [↑ table of contents](#table-of-contents)
# Button + Pill Migration Map (B04)
**Canonical system:** the `.btn` base + BEM modifiers live in `public/buttons.css` (B03, a portable partial that `public/style.css` `@import`s; any surface can also `<link>` it directly). The `.pill` base + semantic modifiers live in `public/style.css` (B04).
-**Tokens:** B01 primitives in `public/tokens.css`; `--btn-*` and `--focus-ring-*` component tokens in `public/buttons.css`, `--badge-*` in `public/style.css`, `--disabled-*` in `public/tokens.css`.
+**Tokens:** B01 primitives in `public/tokens.css`, which also carries the `--focus-ring-*` and `--disabled-*` component tokens; `--btn-*` component tokens in `public/buttons.css`, `--badge-*` in `public/style.css`.
---
@@ -36655,6 +37735,7 @@ done; wait
| `.btn.btn--secondary` | Explicit secondary (same as base, for readability) |
| `.btn.btn--ghost` | Transparent, text-only |
| `.btn.btn--danger` | Red-tinted |
+| `.btn.btn--forge` | Gradient-bordered forge CTA with a live pulse dot (`.btn-forge-dot`); dark surfaces only |
| `.btn.btn--sm` | Small size |
| `.btn.btn--lg` | Large size |
| `.btn.btn--block` | Full-width |
@@ -36687,7 +37768,7 @@ Linked pills: use `<a class="pill pill--onchain">` — gets hover/focus states a
| `/deploy` (register-ui.js) | `erc8004-btn`, `erc8004-btn--primary`, `erc8004-btn--ghost`, `erc8004-btn--close`, `erc8004-btn--wallet`, `erc8004-btn--x` | Added `btn btn--primary/--ghost/--secondary/--icon` alongside |
| Pump launch modal (launch-token-modal.js) | `ltm-btn`, `ltm-btn-primary` | Added `btn btn--secondary/--primary` alongside |
| Homepage pump launcher (homepage-launcher.js) | `ltm-btn`, `ltm-btn-primary` | Added `btn btn--secondary/--primary` alongside |
-| Nav drawer (nav.html) | `btn primary` | Added `btn--primary` BEM modifier |
+| Nav drawer (public/nav.js renders it into the empty `nav-drawer` element in nav.html) | `btn primary` | Added `btn--primary` BEM modifier |
| On-chain badge (onchain-badge.js) | `tws-ocb`, `tws-ocb--md`, `tws-ocb--devnet` | Added `pill pill--onchain/--devnet pill--md` |
---
@@ -36757,7 +37838,7 @@ These classes are defined across the codebase. Follow-up agents should replace t
---
-<a id="sec-132"></a>
+<a id="sec-135"></a>
> **Source:** `docs/build.md` · [↑ table of contents](#table-of-contents)
@@ -36808,7 +37889,7 @@ front-end, the `vercel.json` route table, and every `api/**` handler from source
provisioned from the `crons` array in `vercel.json` by
[scripts/create-gcp-scheduler.mjs](../scripts/create-gcp-scheduler.mjs); that
array is the count, so read it there rather than trusting a number quoted here
-(108 entries on 2026-08-14). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](ops/gcp-production.md).
+(111 entries on 2026-09-01). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](ops/gcp-production.md).
`.npmrc` sets `legacy-peer-deps=true` (npm never auto-installs peers — the
reason `audit:deploy` checks the peer tree), and `engines.node` pins Node
@@ -36924,13 +38005,13 @@ grep -l 'vite-plugin-pwa:register-sw' dist/widget.html dist/embed.html # expec
---
-<a id="sec-133"></a>
+<a id="sec-136"></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-563)
+Paste a token contract address, get back a live, agent-payable [x402](#sec-589)
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.
@@ -36961,8 +38042,9 @@ Three steps, all real:
shape-checked in the browser before a request is made
(`/^[1-9A-HJ-NP-Za-km-z]{32,44}$/` or `/^0x[a-fA-F0-9]{40}$/`).
2. **Resolve.** `GET /api/ca2x402/resolve` pulls the token's live market from
- DexScreener and returns both the token preview and the generated service
- descriptor. This read is free and unauthenticated.
+ DexScreener (backed by a last-known-good copy, see below) and returns both
+ the token preview and the generated service descriptor. This read is free
+ and unauthenticated.
3. **Ship.** The page renders the endpoint URL, its price and networks, three
copy-paste snippets, and a button that fetches the real `402 Payment Required`
challenge from the live endpoint so you can see exactly what a buyer settles
@@ -36989,16 +38071,26 @@ What happens, in order:
1. **Validate.** A missing `mint` is `400 missing_mint`. An address that is
neither a valid Solana mint nor a valid EVM address is `422 invalid_mint`.
2. **Fetch the market.** `fetchTokenMarket()` calls the public DexScreener token
- endpoint (no key) with a 6 second timeout, then picks the pair with the
- deepest USD liquidity across every chain and DEX DexScreener knows for that
- address. The address may sit on either side of the pair; the reader selects
- whichever side matches what you passed.
+ endpoint (no key) through the shared upstream fetcher (6 second timeout, two
+ attempts, circuit breaker) and remembers the last payload it got for each
+ address for 15 minutes, so a throttled indexer serves a few-minutes-old
+ market rather than nothing. It then picks the pair with the deepest USD
+ liquidity across every chain and DEX DexScreener knows for that address. The
+ address may sit on either side of the pair; the reader selects whichever
+ side matches what you passed.
3. **No market found.** A well-formed address with no live pair (unlaunched, dead
- liquidity, wrong chain, or an upstream hiccup) returns
+ liquidity, or wrong chain) returns
`404 { ok: false, error: 'token_not_found' }` with `cache-control: no-store`.
The page renders that as a designed empty state. Nothing is fabricated to fill
the gap.
-4. **Success.** `200 { ok: true, token, service }` with
+4. **Indexer unreachable.** The resolver asks `fetchTokenMarketResult()`, which
+ tells "no market exists" apart from "the indexer could not be reached". When
+ DexScreener is down and this instance holds no remembered payload for the
+ address, the answer is `503 { ok: false, error: 'market_unavailable',
+ retry_after: 15 }` with a `Retry-After: 15` header and `cache-control:
+ no-store`, never a `404` that would tell someone their real token does not
+ exist. The page shows the error description with its retry button.
+5. **Success.** `200 { ok: true, token, service }` with
`cache-control: public, max-age=20, stale-while-revalidate=60`.
### The `token` block
@@ -37080,7 +38172,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-559) for the full
+back to the default. See [x402 paid endpoints](#sec-584) for the full
price-override scheme.
---
@@ -37096,7 +38188,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
-[Financial controls](#sec-222)).
+[Financial controls](#sec-229)).
The paid response body is the token block computed fresh at call time:
@@ -37132,8 +38224,8 @@ Two failure modes are deliberately thrown **before** settlement, so a buyer is
never charged for a bad or missing answer:
- `422 invalid_mint` when `mint` is absent or not a resolvable address.
-- `503 data_unavailable` when DexScreener has no live market or no 24 hour change
- for the token.
+- `503 data_unavailable` when the market reader (DexScreener plus its 15-minute
+ last-known-good copy) has no live market or no 24 hour change for the token.
Access control uses the shared bypass hook with the `x402:bypass` scope
([`api/_lib/x402/access-control.js`](../api/_lib/x402/access-control.js)), which is
@@ -37239,16 +38331,16 @@ right now. If the endpoint is unreachable the page says so and offers a retry.
## Related
-- [x402 on three.ws](#sec-563): the protocol, the wire format, and how the
+- [x402 on three.ws](#sec-589): the protocol, the wire format, and how the
platform settles.
-- [x402 paid endpoints](#sec-559): the full catalog of our paid
+- [x402 paid endpoints](#sec-584): the full catalog of our paid
endpoints, their prices, and the `X402_PRICE_*` override scheme.
- [Receipt Vault](../pages/receipts.html): where the buyer's signed receipt for a
settled payment to this endpoint can be retrieved.
---
-<a id="sec-134"></a>
+<a id="sec-137"></a>
> **Source:** `docs/capture.md` · [↑ table of contents](#table-of-contents)
@@ -37345,14 +38437,14 @@ console.log(job.result_url, job.num_points); // coloured .ply + point count
## Related
-- [Splat Viewer](#sec-409) renders Gaussian-splat radiance fields, the photoreal cousin of point clouds.
+- [Splat Viewer](#sec-427) 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-227) and [Image to 3D](#sec-254) for generating meshes from prompts and photos.
+- [Forge](#sec-234) and [Image to 3D](#sec-264) for generating meshes from prompts and photos.
- Pages: [/scene](https://three.ws/scene) (Scene Studio), [/create](https://three.ws/create).
---
-<a id="sec-135"></a>
+<a id="sec-138"></a>
> **Source:** `docs/changelog.md` · [↑ table of contents](#table-of-contents)
@@ -37688,47 +38780,47 @@ cd sdk && npm publish
---
-<a id="sec-136"></a>
+<a id="sec-139"></a>
> **Source:** `docs/character-library.md` · [↑ table of contents](#table-of-contents)
-# Character Library: 106 rigged characters, ready to animate
+# Character Library: rigged characters, ready to animate
The Character Library is a free, curated gallery of professionally rigged humanoid 3D characters. Every character ships as a web-ready GLB with a full skeleton, skin weights, and textures, so it drives the entire three.ws animation library (idle, walk, run, wave, dance, and the rest of the canonical clip set) out of the box via animation retargeting. No account, no payment, no upload step: browse, preview live, and send any character into a studio in one click.
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-308).
+> This page covers the character gallery and its API. For the motion clips these characters play, see [Animations](#sec-095). For the free prop counterpart to this library, see the [Object Library](#sec-319).
---
## What is in the library
-106 professionally rigged Mixamo humanoid characters (Y Bot, X Bot, Warrok, Remy, Vanguard, zombies, knights, and more), staged as optimized GLBs on the R2 CDN. The manifest can also merge additional CC0 characters from other sources (for example Quaternius), so the API's `total` field is the authoritative count and can exceed 106.
+A hundred-plus professionally rigged Mixamo humanoid characters (Y Bot, X Bot, Warrok, Remy, Vanguard, zombies, knights, and more), staged as optimized GLBs on the R2 CDN. The manifest can also merge additional CC0 characters from other sources (for example Quaternius), so the API's `total` field is the authoritative count. Nothing on the page hard-codes a number: the hero headline and the results counter render `total` from the manifest.
-Every entry is animation-ready: the GLB carries a skinned mesh, and the three.ws runtime retargets the canonical clip library onto it automatically (see [Animations](#sec-093) for how retargeting and the clip registry work). There is no per-character allowlist; any character in the library plays any clip.
+Every entry is animation-ready: the GLB carries a skinned mesh, and the three.ws runtime retargets the canonical clip library onto it automatically (see [Animations](#sec-095) for how retargeting and the clip registry work). There is no per-character allowlist; any character in the library plays any clip.
## Using the gallery
-Each card renders the character live in an auto-rotating `<model-viewer>` (with the pre-rendered thumbnail as the poster) and offers three one-click routes:
+Each card renders the character live in an auto-rotating `<model-viewer>` (with the pre-rendered thumbnail slotted in as a lazy-loaded poster image that fades once the model loads), shows the entry's `source` and file size, and offers three one-click routes. The viewer is control-free (no orbit, no extra tab stop); the whole thumbnail is a link to the preview. A manifest row with no `url` renders as a plain, unlinked tile with no actions.
| Button | Destination | What you get |
|---|---|---|
-| **Preview** | `/app#model=<glb-url>` | The full three.js [3D viewer](#sec-520) |
-| **Use** | `/studio?model=<glb-url>` | [Widget Studio](#sec-525): configure and publish an embeddable widget of this character (see the [Embedding Guide](#sec-187)) |
-| **Animate** | `/pose?src=<glb-url>&title=<name>` | [Animation Studio](#sec-092): pose, keyframe, and export motion on this character |
+| **Preview** | `/app#model=<glb-url>` | The full three.js [3D viewer](#sec-540) |
+| **Use** | `/studio?model=<glb-url>` | [Widget Studio](#sec-545): configure and publish an embeddable widget of this character (see the [Embedding Guide](#sec-193)) |
+| **Animate** | `/pose?src=<glb-url>&title=<name>` | [Animation Studio](#sec-094): pose, keyframe, and export motion on this character |
Gallery controls:
- **Search** filters by name; press `/` anywhere on the page to focus the search box.
- **Sort** by name (A to Z, Z to A) or by file size (largest or smallest first). File size is shown on every card.
-- The library is small enough that the page fetches the whole manifest once and filters client-side, so search and sort are instant.
+- The library is small enough that the page fetches the whole manifest once and filters client-side, so search and sort are instant. Search, sort, card copy, and the deep links are pure functions of the manifest in [`src/shared/character-library-view.js`](../src/shared/character-library-view.js), covered by `tests/character-library-view.test.js`.
- Loading shows a skeleton grid; an empty library, an empty search result, and a fetch error each have their own designed state with a recovery action.
## 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-308). 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-319). 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
@@ -37803,19 +38895,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-443) 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-463) 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-525) and the [Embedding Guide](#sec-187): turn a library character into a live embed on any site.
-- [Object Library](#sec-308): the same free-library pattern for CC0 props and scene objects.
-- [Marketplace](#sec-277): library characters are free; the marketplace is where priced avatars, agents, and skills are bought and sold.
+- [Animations](#sec-095): the clip library every character drives, and how retargeting works.
+- [Animation Studio](#sec-094): the `/pose` surface the Animate button opens.
+- [Widget Studio](#sec-545) and the [Embedding Guide](#sec-193): turn a library character into a live embed on any site.
+- [Object Library](#sec-319): the same free-library pattern for CC0 props and scene objects.
+- [Marketplace](#sec-286): library characters are free; the marketplace is where priced avatars, agents, and skills are bought and sold.
---
-<a id="sec-137"></a>
+<a id="sec-140"></a>
> **Source:** `docs/character-studio.md` · [↑ table of contents](#table-of-contents)
@@ -37833,7 +38925,7 @@ It is a rebranded fork of the open-source (MIT license) [M3-org/CharacterStudio]
Where you meet it in the product:
-1. Open an agent's edit page (`https://three.ws/agent/<agent-id>/edit`)
+1. Open an agent's edit page (`https://three.ws/agents/<agent-id>/edit`)
2. Click the avatar tile and choose **three.ws Studio** ("In-browser builder: hair, clothing, body") from the create menu
3. The builder opens in a modal iframe; customize using the sections in the left panel
4. Click **Save Avatar**; the finished GLB is handed back to the agent editor automatically
@@ -37923,7 +39015,7 @@ RightUpperLeg → RightLowerLeg → RightFoot
This means:
- **Mixamo animations work**: the fork retargets Mixamo FBX clips onto the VRM rig (`loadMixamoAnimation.js`, `VRMRigMapMixamo.js`)
-- **The three.ws animation library is fully compatible**: the platform's bone-name canonicalizer (`src/glb-canonicalize.js`) maps VRM rigs to the canonical set, so all built-in clips (idle, wave, walk, and the rest) work out of the box
+- **The three.ws animation library is fully compatible**: the platform's bone-name canonicalizer (`src/glb-canonicalize.js`) maps VRM rigs (and every other humanoid convention it knows, MikuMikuDance's Japanese bone names included) to the canonical set, so all built-in clips (idle, wave, walk, and the rest) work out of the box
- **Retargeting** is handled automatically by the animation manager (`src/animation-retarget.js`)
---
@@ -37998,8 +39090,9 @@ offers three real paths, each ending in a GLB the world adopts immediately:
editor mode, which loads the Avaturn selfie→3D SDK (`@avaturn/sdk`). No sign-in required;
the exported GLB is staged locally and used as your avatar instantly, then uploaded in the
background so peers can load it too (`play-handoff.js`).
-2. **Upload a .glb** — bring a model from Blender, Mixamo, VRoid, or any tool. Validated
- client-side (`avatar-upload.js` `validateGlb`) before it becomes your avatar.
+2. **Upload a model**: bring a `.glb` or `.vrm` from Blender, Mixamo, VRoid, or any tool.
+ Validated client-side (`avatar-upload.js` `validateGlb`, which accepts both extensions
+ since a VRM file is a glTF binary) before it becomes your avatar.
3. **Advanced studio**: opens the native Avatar Studio at `/create/studio` in a new
tab for deep body/face/hair/clothing sculpting, then saves to your account
(see [Avatar Studio (native)](/docs/avatar-studio)).
@@ -38092,13 +39185,13 @@ For cases that need more control than the studio provides, create your avatar in
---
-<a id="sec-138"></a>
+<a id="sec-141"></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-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.
+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-142). 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
@@ -38261,7 +39354,7 @@ Run the four suggested prompts in a fresh chat. Pass criteria:
---
-<a id="sec-139"></a>
+<a id="sec-142"></a>
> **Source:** `docs/chatgpt-ar.md` · [↑ table of contents](#table-of-contents)
@@ -38298,13 +39391,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-281).
+The MCP connector at `https://three.ws/api/mcp-studio` (no authentication) exposes eleven 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 (a pending result now names its `stage`, `mesh` or `rig`, so the collector knows which leg it is waiting on), the read-only `look_at_model` tool that renders any public GLB from several angles and returns the frames as images plus a plain reading of its geometry, so the assistant can judge its own output before printing a link, and three persona/embodiment tools (`create_agent_persona`, `get_agent_persona`, `persona_say`, in [api/_mcp-studio/persona-tools.js](../api/_mcp-studio/persona-tools.js)). Full server documentation: [3D Studio MCP](#sec-290).
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-138); 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-141); the REST contract it calls:
```bash
curl -s -X POST https://three.ws/api/3d/studio \
@@ -38312,10 +39405,10 @@ curl -s -X POST https://three.ws/api/3d/studio \
-d '{"prompt":"a small ceramic robot figurine"}'
```
-Submit returns either the finished model or a job to poll:
+Submit returns either the finished model or a job to poll (the response shaping lives in [api/_mcp-studio/studio-shape.js](../api/_mcp-studio/studio-shape.js), shared with the tests):
```json
-{ "status": "pending", "job": "…", "poll": "/api/3d/studio?job=…&title=a%20small%20ceramic%20robot%20figurine", "format": "glb" }
+{ "status": "pending", "job": "…", "poll": "/api/3d/studio?job=…&title=a%20small%20ceramic%20robot%20figurine", "watchUrl": "https://three.ws/watch?job=…&title=…", "etaSeconds": 45, "format": "glb" }
```
```json
@@ -38335,6 +39428,7 @@ Design decisions on this endpoint, all deliberate:
- **The title-carrying poll.** ChatGPT Actions never resend context, so the submit response embeds the prompt in the poll URL as `&title=`. When the poll finally returns `done`, the `arUrl` and `viewerUrl` are labeled with the original prompt without the GPT doing anything except calling the poll path verbatim.
- **Timeout honesty.** Actions calls time out around 45 seconds; generation takes 20 to 60. The endpoint holds the request as long as it safely can and falls back to `pending` + poll rather than dying mid-request.
- **Safety before GPU.** Every prompt passes an age-13+ appropriateness gate ([api/_mcp-studio/safety.js](../api/_mcp-studio/safety.js)) before any provider work; refusals return `400 prompt_rejected` with a clear message.
+- **An outage is an answer, not a 5xx.** When the poll finds the generation lane unconfigured upstream (`503`/`501` with `unconfigured` or `backend_unconfigured`), it answers `200 { "status": "error", "job": "…", "error": "3D generation is temporarily unavailable…" }`, so the GPT can tell the user plainly instead of surfacing a transport failure.
The GPT's instructions tell it to present three links on every finished model, in this order: **See it in your space** (`arUrl`), **Preview in your browser** (`viewerUrl`), **Download** (`glbUrl`), and to never fabricate a URL an action did not return. The OpenAPI schema the GPT imports is served at [`https://three.ws/.well-known/3d-studio-openapi.yaml`](../public/.well-known/3d-studio-openapi.yaml) and describes `/api/ar` alongside the generation action, so the AR launch is part of the app's published contract rather than an undocumented link. The full GPT build sheet lives at [prompts/store-submissions/_generated/](../prompts/store-submissions/_generated) (`openai-gpt-config.md`, plus `openai-actions.yaml`, which is regenerated from the served schema by `npm run sync:studio-openapi`).
@@ -38346,13 +39440,13 @@ The GPT's instructions tell it to present three links on every finished model, i
| Device | What the user gets |
|---|---|
-| **iPhone / iPad** | A launch page whose View in AR button opens Apple **Quick Look**. The USDZ Apple requires is generated from the GLB on the fly, in the page, by model-viewer's three.js `USDZExporter`. No server-side USD tooling exists or is needed. |
+| **iPhone / iPad** | A tiny interstitial carrying the model's real `og:image`/`og:title` (so a pasted link still unfurls; crawlers do not follow a bare redirect's JS) that refreshes straight into **`/ar/view?src=…&title=…`** ([pages/ar-view.html](../pages/ar-view.html), [src/ar-view.js](../src/ar-view.js)). That Vite-bundled page generates a real USDZ from the GLB on the device with three's `USDZExporter` and then offers Apple **Quick Look** with a genuine `ios-src`. No server-side USD tooling exists or is needed; `<model-viewer>` alone does not do the conversion, which is why the AR page is a bundled page rather than HTML the handler writes inline. |
| **Android** (static model) | An HTTP `302` straight into Google **Scene Viewer** via an ARCore `intent://` URL, with a `browser_fallback_url` back to the WebGL viewer for devices without ARCore. |
-| **Desktop** | The launch page falls back to the interactive WebGL viewer. There is no dead end: the link is safe to open anywhere. |
+| **Desktop** | The same interstitial into `/ar/view`, which falls back to the interactive WebGL viewer. There is no dead end: the link is safe to open anywhere. |
Responses set `vary: user-agent` so CDN caching stays correct per device class. Bad input (non-https, non-GLB, missing `src`) returns a designed error page, never a crash.
-The pure routing logic (`detectArTarget`, `buildSceneViewerUrl`, `planArLaunch`) lives dependency-free in [api/_lib/ar-launch.js](../api/_lib/ar-launch.js) and is covered by [tests/ar-export.test.js](../tests/ar-export.test.js). The deeper AR reference (WebXR sessions, USDZ pipeline details, optimization limits) is [docs/ar.md](#sec-099).
+The pure routing logic (`detectArTarget`, `buildSceneViewerUrl`, `buildArViewUrl`, `planArLaunch`) lives dependency-free in [api/_lib/ar-launch.js](../api/_lib/ar-launch.js) and is covered by [tests/ar-export.test.js](../tests/ar-export.test.js). `planArLaunch` now resolves every branch to a redirect target: Scene Viewer for a static model on Android, `/ar/view` for everything else, with `viewerUrl` and `sceneViewerUrl` still returned for callers such as the `export_ar` tool that want the raw URLs alongside the launch link. The deeper AR reference (WebXR sessions, USDZ pipeline details, optimization limits) is [docs/ar.md](#sec-101).
---
@@ -38360,8 +39454,8 @@ 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-259).
-- 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.
+- `/ar/view` receives the handoff as `&irl=<irlUrl>` and leads with a **Bring it to life** button 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-270).
+- Android is NOT blind-redirected into Scene Viewer, because that would hide the living path. It lands on `/ar/view` 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.
@@ -38374,7 +39468,7 @@ A place-in-your-room link is built to be forwarded. When it is pasted into a cha
- `og:title`: "Place `<title>` in your room"
- `og:image`: `https://three.ws/api/render/glb?glbUrl=<encoded GLB>&width=1200&height=630`
-`GET /api/render/glb` ([api/render/glb.js](../api/render/glb.js)) is a public, URL-addressable GLB-to-PNG renderer: point any image tag at it with a public GLB URL and get a PNG back (headless Chromium + model-viewer under the hood, the same pipeline as the platform's OG cards). It clamps dimensions to 64-2048, HEAD-checks the GLB at 10 MB max, is SSRF-guarded and per-IP rate-limited, and is CDN-cached for a day. The launch page itself ends with a "Create your own" link, so a shared model converts its recipient into a creator.
+`GET /api/render/glb` ([api/render/glb.js](../api/render/glb.js)) is a public, URL-addressable GLB-to-PNG renderer: point any image tag at it with a public GLB URL and get a PNG back (the shared `renderGlbToPng` in `api/_lib/render-glb.js`: an in-process software rasterizer first, headless Chromium as the failover for Draco/KTX2 models, the same pipeline as the platform's OG cards). It clamps dimensions to 64-2048, HEAD-checks the GLB at 10 MB max, accepts a `background` of `transparent` or any CSS color (markup or anything else that is not a color is rejected with `400 bad_request`), is SSRF-guarded and per-IP rate-limited, and is CDN-cached for a day. The launch page itself ends with a "Create your own" link, so a shared model converts its recipient into a creator.
---
@@ -38383,7 +39477,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-407) 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-278), 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-425) 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-287), 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.
@@ -38399,6 +39493,8 @@ The generation lane is operator-funded (NVIDIA NIM running Microsoft TRELLIS for
| AR launcher (`/api/ar`) + unfurl tags | [api/ar.js](../api/ar.js) |
| AR routing core (`buildArLaunchUrl`, device branch, IRL handoff) | [api/_lib/ar-launch.js](../api/_lib/ar-launch.js) |
| MCP studio tools + response envelope | [api/_mcp-studio/tools.js](../api/_mcp-studio/tools.js) |
+| Studio Actions response shaping (`shapeSubmit`, `shapePoll`) | [api/_mcp-studio/studio-shape.js](../api/_mcp-studio/studio-shape.js) |
+| The on-device AR page (`/ar/view`) | [pages/ar-view.html](../pages/ar-view.html), [src/ar-view.js](../src/ar-view.js) |
| Inline widget (View in your space / Bring it to life) | [api/_mcp-studio/component.js](../api/_mcp-studio/component.js) |
| GLB-to-PNG renderer (og:image) | [api/render/glb.js](../api/render/glb.js) |
| GPT OpenAPI schema (served, source of truth) | [public/.well-known/3d-studio-openapi.yaml](../public/.well-known/3d-studio-openapi.yaml) |
@@ -38409,20 +39505,236 @@ 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-281): the free MCP server behind the ChatGPT app
+- [3D Studio MCP](#sec-290): 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-259): the living-agent experience behind Bring it to life
+- [AR and WebXR reference](#sec-101): Quick Look, Scene Viewer, WebXR, and the USDZ pipeline in depth
+- [IRL](#sec-270): the living-agent experience behind Bring it to life
---
-<a id="sec-140"></a>
+<a id="sec-143"></a>
+
+> **Source:** `docs/checkout-companion.md` · [↑ table of contents](#table-of-contents)
+
+# Checkout companion
+
+Your agent reads the payment page before you pay.
+
+Checkout dark patterns are not hidden. They are unread. The fee added on the
+last step, the "free trial" that becomes an annual charge, the cancellation
+notice period buried in a terms block: all of it is rendered on the screen the
+person is looking at, and none of it gets read, because reading it is tedious
+and the button is right there. This is the one moment where an agent that can
+read a page faster than you is worth more than an agent that can do anything
+else.
+
+The [companion](#sec-156) already delivers messages in person. This is the
+same companion at the moment money moves.
+
+## What it reports
+
+On a checkout page, and only there, the panel says:
+
+| Finding | Example |
+| --- | --- |
+| The total is above the price you were shown | "You saw $49.99 earlier and this page charges $62.49, a difference of $12.50." |
+| Money the page did not itemise | "The listed amounts come to $54.99 but the total is $62.49. $7.50 is not itemised on this page." |
+| Fees, named and summed | "$4.49 of this is fees. Service fee: $2.50. Processing: $1.99." |
+| The charge repeats | Auto-renewal, "billed monthly", "per year" |
+| A trial converts | "Start your free trial. After the trial you will be billed." |
+| The price changes on renewal | Introductory rates, "first year only", "renews at" |
+| Conditions on cancelling | Notice periods, non-refundable terms |
+| Something may be pre-selected | "uncheck this box", "already added" |
+
+If any of those is a red flag the panel opens itself and optionally says one
+line out loud. Otherwise it stays one collapsed line. Most checkouts are
+ordinary and it is quiet on them.
+
+## The two passes, and why they are separate
+
+This is the load-bearing design decision, and every future change has to keep
+it. The analysis runs in two passes with a hard line between them:
+
+**Arithmetic is decided in code.** Whether the line items add up to the total is
+integer minor-unit maths in
+[`api/_lib/companion/checkout.js`](../api/_lib/companion/checkout.js). Every
+number in every finding was computed there. A language model never performs,
+corrects, or infers an amount.
+
+The reason is asymmetry of harm. A model that hallucinates a $12.50 fee onto a
+legitimate merchant's checkout is worse than no feature at all, and a model that
+misses a real one because it did mental arithmetic is the same failure wearing a
+different hat. Arithmetic is the part computers have been reliable at for
+seventy years; handing it to a probabilistic system is a choice nobody should
+make on a payment screen.
+
+**Prose is read by a model.** What a cancellation clause actually says is a
+reading task, and that is what models are good at. The model is given the
+redacted page text and returns findings with no amounts in them.
+
+Two guarantees enforce the line:
+
+- `SYSTEM_PROMPT` forbids arithmetic and legal verdicts.
+- `sanitizeModelFindings()` **drops** any finding containing a currency amount
+ or the words illegal, unlawful, non-compliant, fraudulent, scam, and their
+ family. A prompt is a request; a filter is a guarantee.
+
+A finding is dropped rather than softened, because softening leaves a mangled
+sentence on a payment screen with our avatar's face on it, while dropping loses
+one line from a list that is allowed to be empty.
+
+**When the model is unreachable the feature still works.** `reading_status`
+comes back `unavailable` and every arithmetic finding still stands. The
+highest-value finding in the whole product ("this total is $12.50 more than you
+were quoted") needs no model at all.
+
+## What it never does
+
+- **It never renders a legal verdict.** It does not say a charge is illegal,
+ non-compliant, fraudulent, or a scam. It says what the page says and where the
+ numbers disagree. We cannot know the former, the user cannot verify it, and a
+ false accusation over a legitimate merchant's checkout is a liability we would
+ deserve.
+- **It never blocks a payment.** It has no mechanism to and never claims to.
+- **It never advises whether to buy.** It reports; the person decides.
+
+## Privacy
+
+The extension **never reads an input**. Not the value, not the placeholder, not
+a `contenteditable`, not an iframe. `collectText()` and `collectAmounts()` in
+[`extract.js`](../extensions/checkout-companion/extract.js) refuse those nodes
+structurally rather than filtering their contents afterwards, because a filter
+is a list of the cases someone thought of. Card number, CVV, billing address and
+email all live in inputs, so none of them can be read, so none of them can be
+sent.
+
+Redaction then runs in the browser over the visible text anyway (a confirmation
+step that prints your card's last four is real), stripping Luhn-validated card
+numbers, IBANs, security codes, emails, phone numbers, government ids and long
+opaque tokens. The panel reports the redaction count so the claim is checkable.
+
+Only the **hostname** is sent, never the path or query string.
+
+**Nothing about the page is stored.** `POST /api/companion/checkout` writes no
+row. Findings are computed and returned in the same request. The one piece of
+cross-page memory is a single remembered amount per site, kept in the browser
+for one hour, capped at twenty sites, which is what makes the "total versus the
+price you were shown" comparison possible without any surveillance at all.
+
+Full disclosures:
+[PRIVACY.md](../extensions/checkout-companion/PRIVACY.md),
+[PERMISSIONS.md](../extensions/checkout-companion/PERMISSIONS.md).
+
+## API
+
+### `POST /api/companion/checkout`
+
+Auth: a three.ws session, or `Authorization: Bearer <companion bridge token>`
+(the same token as [`/api/companion/ingest`](#sec-156), rotatable from
+`/companion`). Rate limit: 40 per 10 minutes per account.
+
+Request:
+
+```json
+{
+ "url": "https://shop.example/checkout",
+ "title": "Checkout",
+ "currency": "USD",
+ "text": "Order summary. Subtotal $49.99. Service fee $7.50. Order total $62.49. Your plan auto-renews every month.",
+ "amounts": [
+ { "value": 4999, "role": "subtotal", "context": "Subtotal" },
+ { "value": 750, "role": "service", "context": "Service fee" },
+ { "value": 6249, "role": "total", "context": "Order total" }
+ ],
+ "quoted": { "value": 4999 }
+}
+```
+
+`value` is **integer minor units** (cents). The parse from `"$49.99"` to `4999`
+happens in the content script, next to the DOM node that supplied the currency;
+a float arriving here would mean the parse happened somewhere that could not
+know the currency's exponent. `role` is one of `total`, `subtotal`, `line`,
+`fee`, `surcharge`, `handling`, `processing`, `service`, `tax`, `shipping`,
+`discount`, `unknown`.
+
+Response:
+
+```json
+{
+ "findings": [
+ {
+ "id": "total_above_quoted",
+ "severity": "flag",
+ "title": "The total is higher than the price you were shown",
+ "detail": "You saw $49.99 earlier and this page charges $62.49, a difference of $12.50.",
+ "amount": 1250,
+ "currency": "USD",
+ "source": "arithmetic"
+ }
+ ],
+ "spoken": "Heads up: this total is $12.50 more than the price you were shown.",
+ "currency": "USD",
+ "reading_status": "ok",
+ "redactions": 0,
+ "redaction_counts": { "card": 0, "iban": 0, "email": 0, "phone": 0, "cvv": 0, "government_id": 0, "token": 0 }
+}
+```
+
+`severity` is `flag` (opens the panel), `notice`, or `info`. `source` is
+`arithmetic` (computed here), `phrase` (a pattern matched in the page text), or
+`reading` (a model read the prose). Findings sort by severity, then arithmetic
+before prose, because a number you can check against your own screen in two
+seconds beats a paraphrase.
+
+`reading_status` is `ok`, `unavailable` (no model reachable; arithmetic findings
+still returned), or `skipped` (no provider configured, or too little text).
+
+## Installing the extension
+
+Sources: [`extensions/checkout-companion/`](../extensions/checkout-companion).
+
+1. `chrome://extensions` → **Developer mode** → **Load unpacked** → select that
+ directory.
+2. Sign in to three.ws in the same browser, or paste a bridge token from
+ [`/companion`](https://three.ws/companion) into the options page.
+
+### Other browsers
+
+The sources are plain MV3 and load unmodified in Firefox
+(`about:debugging` → **Load Temporary Add-on**) and in Safari via
+`xcrun safari-web-extension-converter`.
+
+**On iOS specifically:** a Safari Web Extension is the only way this can exist.
+iOS has no equivalent of Android's `SYSTEM_ALERT_WINDOW`, so no App Store app
+can draw a floating panel over other apps, and there is no third-party API for
+reading another app's screen contents. An extension inside Safari can read the
+page Safari is showing, which covers web checkouts (where the subscription dark
+patterns overwhelmingly live) and nothing else. That boundary is a platform
+fact, not a roadmap item. See [iOS](#sec-269).
+
+## Tests
+
+- [`tests/companion-checkout.test.js`](../tests/companion-checkout.test.js):
+ redaction, the arithmetic, and what the model is not allowed to say.
+- [`tests/checkout-extract.test.js`](../tests/checkout-extract.test.js): money
+ parsing across locales, and the no-inputs rule held against a real DOM.
+
+## Related
+
+- [Companion](#sec-156): the message lanes and the avatar delivery channel
+- [Notifications](#sec-311): the per-category channel matrix
+- [`extensions/walk-avatar/`](../extensions/walk-avatar): the same rig, walking
+ your avatar across any site
+
+---
+
+<a id="sec-144"></a>
> **Source:** `docs/choreography.md` · [↑ table of contents](#table-of-contents)
# Choreography
-A three.ws agent already reacts on its own: it thinks while a skill runs, nods when a model loads, celebrates a settled payment. Those are single beats, each one a **gesture slot** resolved to a clip ([Animations](#sec-093) is the reference for that layer).
+A three.ws agent already reacts on its own: it thinks while a skill runs, nods when a model loads, celebrates a settled payment. Those are single beats, each one a **gesture slot** resolved to a clip ([Animations](#sec-095) is the reference for that layer).
A **routine** is the next thing up: a named, timed sequence of those gestures, authored once and replayed on demand. Wave, then nod, then settle into idle. Inspect, think, point, present. It is the difference between an agent that twitches in response to events and one that performs.
@@ -38531,7 +39843,7 @@ Rules worth knowing before you call it:
### From an embed
-Any page already rendering an [`<agent-3d>`](#sec-187) element can perform the agent's saved routines by name:
+Any page already rendering an [`<agent-3d>`](#sec-193) element can perform the agent's saved routines by name:
```html
<agent-3d agent="YOUR_AGENT_ID"></agent-3d>
@@ -38659,14 +39971,14 @@ 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-346): 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-187): the `<agent-3d>` element these methods live on
+- [Animations](#sec-095): clips, collections, and the slot vocabulary underneath every routine
+- [Procedural animation](#sec-359): the IK layers that run on top of whatever clip is playing
+- [Agent manifest](#sec-056): the public document that carries `choreographies` to embeds
+- [Embedding an agent](#sec-193): the `<agent-3d>` element these methods live on
---
-<a id="sec-141"></a>
+<a id="sec-145"></a>
> **Source:** `docs/circulation-engine.md` · [↑ table of contents](#table-of-contents)
@@ -38828,7 +40140,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-182)) rather than scheduled on its own.
+[economy heartbeat](#sec-188)) 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
@@ -38861,9 +40173,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-292)). |
+| `agent_custody_events` | The canonical wallet ledger entry for every real spend/transfer (see [Money feed](#sec-302)). |
| `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-277)). |
+| `skill_purchases` / `asset_purchases` | Marketplace settlement records (see [Marketplace](#sec-286)). |
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
@@ -38898,15 +40210,15 @@ budget, so raise gradually and watch tick runtime and treasury balance.
## Related
-- [Money feed](#sec-292): where circulation activity surfaces.
-- [Autonomous x402 loop](#sec-105): the separate treasury-paid loop
+- [Money feed](#sec-302): where circulation activity surfaces.
+- [Autonomous x402 loop](#sec-107): 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-277), [Coin launches](#sec-144).
+- [Agent wallets](#sec-074): the custodial key model every action uses.
+- [Marketplace](#sec-286), [Coin launches](#sec-148).
---
-<a id="sec-142"></a>
+<a id="sec-146"></a>
> **Source:** `docs/clash.md` · [↑ table of contents](#table-of-contents)
@@ -38920,7 +40232,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-421) and [hold to access](#sec-240)). 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-439) and [hold to access](#sec-249)). 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
@@ -38979,20 +40291,20 @@ The Coin Clash state and leaderboard are also exposed read-only over MCP through
- **Auth.** Viewing needs no login. Enlisting requires a connected Solana wallet and a message signature; rallying requires a valid war pass.
- **Rate limits.** Enlist and enlist-verify are limited to 20 per 5 minutes per IP; rally is 40 per minute per wallet; state and leaderboard are 120 per minute per IP.
- **Pass expiry.** A war pass lives 30 minutes; after that rally returns `401 pass_invalid` and the client transparently re-enlists if the wallet is still connected. Switching wallets drops the enlistment and prompts a re-enlist.
-- **Empty and degraded states.** Fewer than 2 active communities shows "No battles live right now" with a link to `/communities`; a bye faction is labeled. An unconfigured community source shows a temporarily-unavailable state and stops polling. A Redis outage degrades silently to per-instance tallies and still serves 200s.
+- **Empty and degraded states.** Fewer than 2 active communities shows "No battles live right now" with a link to `/communities`; a bye faction is labeled. An unconfigured community source shows a temporarily-unavailable state and stops polling. A request that never reaches the server (offline, blocked fetch) surfaces as a named connection error, "Couldn't reach the battle server", instead of the browser's raw "Failed to fetch". A Redis outage degrades silently to per-instance tallies and still serves 200s.
- **Validation.** Taps must be a positive integer and are clamped to 50 per call. The ambient particle field is skipped under `prefers-reduced-motion`.
## Related
-- [Token-gated 3D embeds](#sec-421): the same real on-chain balance gate, applied to embeds
-- [Hold to access](#sec-240): the platform's broader hold-do-not-spend membership thesis
-- [The social layer](#sec-403): platform-wide feed, follows, and leaderboards
-- [MCP tools](#sec-284): the read-only Clash MCP server
+- [Token-gated 3D embeds](#sec-439): the same real on-chain balance gate, applied to embeds
+- [Hold to access](#sec-249): the platform's broader hold-do-not-spend membership thesis
+- [The social layer](#sec-421): platform-wide feed, follows, and leaderboards
+- [MCP tools](#sec-293): the read-only Clash MCP server
- Pages: [/clash](https://three.ws/clash) · [/communities](https://three.ws/communities)
---
-<a id="sec-143"></a>
+<a id="sec-147"></a>
> **Source:** `docs/clip-director.md` · [↑ table of contents](#table-of-contents)
@@ -39102,7 +40414,7 @@ message instead of an error, so a card is only ever minted from a real closed ro
## 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-166)
+`GET /api/mirror/leaderboard?settled_min=1`, the [copy-trading](#sec-171)
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
@@ -39116,14 +40428,14 @@ comes back. Each card's CTA is a real link: `copy-the-agent` and `fork-this-trad
## Related
-- [Trader Card & the claim-your-wallet wedge](#sec-423)
-- [Meta-Allocator: the ETF of degens](#sec-288)
-- [The trading surfaces](#sec-429) · [The Arena](https://three.ws/arena)
-- [Animations & gestures](#sec-093)
+- [Trader Card & the claim-your-wallet wedge](#sec-441)
+- [Meta-Allocator: the ETF of degens](#sec-297)
+- [The trading surfaces](#sec-447) · [The Arena](https://three.ws/arena)
+- [Animations & gestures](#sec-095)
---
-<a id="sec-144"></a>
+<a id="sec-148"></a>
> **Source:** `docs/coin-launches.md` · [↑ table of contents](#table-of-contents)
@@ -39157,12 +40469,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-171)), and the mint is registered in
+[Agent wallets](#sec-177)), 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-141) also runs its own
+inert. The [circulation engine](#sec-145) also runs its own
`launch` action with separate hourly/daily caps.
## What a launch carries
@@ -39173,7 +40485,7 @@ inert. The [circulation engine](#sec-141) 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-289), [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-298), [Vanity protocol](#sec-006)). |
## Recording and surfacing
@@ -39182,7 +40494,7 @@ inert. The [circulation engine](#sec-141) 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-292)). |
+| Live ticker | `coin-buy` / `agent-deploy` events (see [Money feed](#sec-302)). |
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
@@ -39194,7 +40506,7 @@ The same dispatcher handles the full lifecycle beyond launch: `buy-prep` /
`buy-confirm`, `sell-prep` / `sell-confirm`, `portfolio`, `balances`, and
`withdraw-prep` / `withdraw-confirm`, plus strategy actions
(`strategy-backtest`, `strategy-validate`, `strategy-close-all`) that back the
-[sniper](#sec-105).
+[sniper](#sec-107).
## $THREE only
@@ -39206,14 +40518,14 @@ hardcode or surface any other specific mint as a recommendation.
## Related
-- [Solana pump.fun signals](#sec-404) — reputation/intel from pump.fun activity.
-- [Agent wallets](#sec-171) — custodial signing and spend caps.
-- [Circulation engine](#sec-141) — autonomous launch cadence and caps.
-- [Mint mark](#sec-289), [Vanity protocol](#sec-005).
+- [Solana pump.fun signals](#sec-422) — reputation/intel from pump.fun activity.
+- [Agent wallets](#sec-177) — custodial signing and spend caps.
+- [Circulation engine](#sec-145) — autonomous launch cadence and caps.
+- [Mint mark](#sec-298), [Vanity protocol](#sec-006).
---
-<a id="sec-145"></a>
+<a id="sec-149"></a>
> **Source:** `docs/coin-pages.md` · [↑ table of contents](#table-of-contents)
@@ -39274,6 +40586,16 @@ Grotesk display face).
The picked source is remembered across coins and visits (localStorage
`tws_coin_chart_source`), and the embeds follow the site's light/dark theme.
+
+ A third-party terminal that never renders is caught, not left as an empty
+ box: [`src/shared/embed-guard.js`](../src/shared/embed-guard.js) gives each
+ embed a 12 s deadline (started when it first scrolls into view, since a lazy
+ iframe below the fold has not begun loading), and a TradingView script that
+ is blocked outright or loads without ever injecting its chart trips the same
+ path. The panel that replaces it says the provider did not load (an ad
+ blocker, an extension or the network usually ate it), links to the same
+ chart on the provider's own site, and offers a "Try again" that remounts the
+ embed.
- **Price performance matrix** — colored 1h / 24h / 7d / 14d / 30d / 60d /
200d / 1y change cells, so the whole return curve is legible at a glance.
- **Market stats** — market cap, 24h volume, circulating/total supply,
@@ -39331,6 +40653,9 @@ through the shared [`failover-fetch`](../src/shared/failover-fetch.js) primitive
Each is normalized to the same shape in
[`api/_lib/market-fallbacks.js`](../api/_lib/market-fallbacks.js); a fallback
that only carries BTC dominance (CoinPaprika) simply shows one dominance chip.
+ The Fear & Greed reading is fetched with one retry and keeps its last good
+ value for a day (the index updates once daily), so an alternative.me blip
+ never blanks the gauge.
- **Market table** (`/api/coin/markets`) — CoinGecko → CoinLore. CoinLore backs
up the ranked top-N list (7d sparklines and category scoping stay
CoinGecko-only and degrade to an empty chart / CoinGecko-only when it's down).
@@ -39372,7 +40697,10 @@ through the shared [`failover-fetch`](../src/shared/failover-fetch.js) primitive
- **Derivatives table** (`/api/coin/derivatives`) — CoinGecko's cross-venue perp
feed, falling back to Hyperliquid's keyless info API
([`api/_lib/hyperliquid.js`](../api/_lib/hyperliquid.js)): one venue instead of
- dozens, but live price/funding/OI/volume for ~200 perps beats a 502. The
+ dozens, but live price/funding/OI/volume for ~200 perps beats a 502. Because
+ no other venue reports the same contracts, each Hyperliquid info query is
+ retried once and keeps its last good answer for ten minutes (keyed by the
+ query body), so a throw there never empties the derivatives view. The
response carries a `source` marker. Riding alongside whichever source answered
is a `deribit` block ([`api/_lib/deribit.js`](../api/_lib/deribit.js)): index
prices, funding-carrying perp tickers, and per-asset options aggregates from
@@ -39762,6 +41090,19 @@ All data is real and fetched at runtime — nothing is hardcoded or sampled:
| `/api/news/archive` | `gs://three-ws-news-archive` (662k-article JSONL corpus + indexes on GCS) | 300 s / 3600 s |
| `/api/coin/liquidations`| `services/liquidation-collector` (Binance/Bybit/OKX public liquidation WebSocket streams) | 15 s, `503` no-fallback offline |
+The `/api/defi/*` handlers have DeFiLlama as their only upstream, so a TTL
+cache alone would still 502 the moment it expired during an outage. Every
+DeFiLlama read goes through the shared
+[`upstream-fetch`](../api/_lib/upstream-fetch.js) helper (one retry on a
+transient failure, `attempts: 2`) and each handler keeps its last good payload
+past the TTL: `/api/defi/chain`, `/api/defi/protocol`, `/api/defi/yields` and
+`/api/defi/hacks` hold theirs for six hours, the rest for the 30 minutes that
+[`mem-cache`](../api/_lib/mem-cache.js)'s `cached()` mirrors every value into
+its last-known-good tier. A response served from that copy carries an
+`x-three-stale: 1` header so the page can say the numbers are not live rather
+than pass them off as current; the header disappears the moment the loader
+succeeds again.
+
Full request/response shapes: [api-reference.md → Coin Market Data API](api-reference.md#coin-market-data-api).
The proxies live in [`api/coin/`](../api/coin) over the shared
@@ -39813,7 +41154,7 @@ server mirrors each (including the dynamic `/coin/:id` path). The pre-existing
---
-<a id="sec-146"></a>
+<a id="sec-150"></a>
> **Source:** `docs/coin-wars.md` · [↑ table of contents](#table-of-contents)
@@ -39848,6 +41189,9 @@ the UI.
While a war involving your coin is live, anyone standing at the portal sees the
score, the round clock and a kill feed on the board without joining the fight.
+A battle still in its lobby reads "waiting on both sides" until both communities
+have fielded a fighter, and a battle that has already ended is never flown as
+live: the portal skips it when it picks the running war to banner.
---
@@ -40037,11 +41381,11 @@ 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-255), [play hardening](#sec-339).
+Related: [the in-game economy](#sec-265), [play hardening](#sec-351).
---
-<a id="sec-147"></a>
+<a id="sec-151"></a>
> **Source:** `docs/coingecko-listing-update-2026-08.md` · [↑ table of contents](#table-of-contents)
@@ -40309,7 +41653,7 @@ full link set is one click away without cluttering the verification post itself.
---
-<a id="sec-148"></a>
+<a id="sec-152"></a>
> **Source:** `docs/coinmarketcap-article-play.md` · [↑ table of contents](#table-of-contents)
@@ -40455,7 +41799,7 @@ The chart has always told you *what* a coin is doing. /play lets you go stand wh
---
-<a id="sec-149"></a>
+<a id="sec-153"></a>
> **Source:** `docs/coinmarketcap-article.md` · [↑ table of contents](#table-of-contents)
@@ -40658,7 +42002,7 @@ If you've been waiting for the moment AI and crypto stop talking past each other
---
-<a id="sec-150"></a>
+<a id="sec-154"></a>
> **Source:** `docs/coinmarketcap-live-article.md` · [↑ table of contents](#table-of-contents)
@@ -40782,7 +42126,7 @@ at [community.ibm.com](https://community.ibm.com/community/user/usergroup?Commun
---
-<a id="sec-151"></a>
+<a id="sec-155"></a>
> **Source:** `docs/community.md` · [↑ table of contents](#table-of-contents)
@@ -40802,7 +42146,17 @@ three.ws is built in the open and the conversation happens in public. Pick the r
| **Issues** | Bugs and concrete feature requests | [github.com/nirholas/three.ws/issues](https://github.com/nirholas/three.ws/issues) |
| **Security** | Vulnerabilities, privately | [Report an advisory](https://github.com/nirholas/three.ws/security/advisories/new) |
-Announcements also go out on [@trythreews](https://x.com/trythreews).
+Announcements also go out on [@trythreews](https://x.com/trythreews), which is the
+only X account three.ws posts from. The founder's personal account, `@nichxbt`, has
+been unavailable since August 27, 2026, so nothing posted under that handle is us
+while it is down.
+
+The table above is the complete set of rooms we run. [three.ws/community](https://three.ws/community)
+carries the same list alongside the one $THREE contract address, so anything claiming
+to be us can be checked against a single page. Two rules that never change: nobody
+from three.ws messages you first or asks for a seed phrase, a private key, or a wallet
+signature, and there is no second token, so a "new" or "migrated" $THREE contract is a
+theft whatever it is posted under.
## Which channel for which question
@@ -40823,11 +42177,372 @@ Two additions specific to this project:
## Contributing
-New here? Start with [Your first contribution](#sec-223), a 15-minute path from clone to open PR. The full guide is [CONTRIBUTING.md](../CONTRIBUTING.md), and how we sort incoming work is documented in [Triage](#sec-430).
+New here? Start with [Your first contribution](#sec-230), a 15-minute path from clone to open PR. The full guide is [CONTRIBUTING.md](../CONTRIBUTING.md), and how we sort incoming work is documented in [Triage](#sec-448).
---
-<a id="sec-152"></a>
+<a id="sec-156"></a>
+
+> **Source:** `docs/companion.md` · [↑ table of contents](#table-of-contents)
+
+# The Companion
+
+**A 3D character that tells you the things worth interrupting you for, in person.**
+
+Your phone buzzes forty times a day. Two of those mattered. Every notification
+system ever built has optimised the buzz; none of them has ever taken
+responsibility for the judgement. The Companion is the other half of the
+problem: it reads what comes in, decides what a person would actually want a tap
+on the shoulder for, and then a character walks over and says it out loud, in
+the body and the voice of whoever it came from.
+
+Set it up at **[three.ws/companion](https://three.ws/companion)**.
+
+- It runs on **your own keys**. A Telegram bot you created, an iCal URL you can
+ revoke, an app password scoped to mail, or nothing at all but a token your
+ phone posts to.
+- It has **a bar**, and you set it. Everything under the bar is kept in a feed
+ instead of being spoken. Quiet hours are absolute.
+- Anyone you give a face to **arrives in that face**. A message from Sarah is
+ delivered by Sarah's avatar, in the voice you picked for her.
+- It shows up **where you are**: on three.ws, as a push on your phone, and on
+ your desktop as a character that lives there.
+
+---
+
+## Five minutes to your first delivery
+
+1. Open [three.ws/companion](https://three.ws/companion) and copy your **bridge
+ token** from the "Phone and Mac" card.
+2. Press **Send a test**. A character appears and says it. That is the whole
+ delivery path, proven, before you connect anything real.
+3. Connect a source: paste a Telegram bot token, a calendar URL, or IMAP
+ details. Each one is verified against the real provider before it is saved,
+ so a typo fails in front of you instead of at 3am.
+4. Add a **contact**: the handle or address of someone who matters, a name, an
+ avatar, a voice. Now their messages arrive as them.
+5. Set your **threshold** and **quiet hours**.
+
+---
+
+## Where messages come from
+
+### The bridge (your phone, your Mac, anything that can POST)
+
+The universal lane. One endpoint, one token, no integration:
+
+```bash
+curl -X POST https://three.ws/api/companion/ingest \
+ -H "Authorization: Bearer cmp_YOUR_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"title":"Sarah is at the door","sender":"Sarah","app":"Messages","priority":"high"}'
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `title` | yes | One line: what happened. |
+| `body` | no | The longer text. |
+| `sender` | no | Display name, matched against your contacts. |
+| `sender_id` | no | Handle, address, or number. Matched first, and more precisely. |
+| `app` | no | Where it came from, e.g. `Messages`, `Slack`. |
+| `url` | no | Somewhere to open; becomes a button. |
+| `id` | no | Your own id, which makes retries idempotent. |
+| `priority` | no | `high` / `normal` / `low`: what the sending device already knew. |
+| `occurred_at` | no | ISO timestamp, if it is not "now". |
+
+Ready-made bridges live in
+[`docs/companion/bridges/`](https://github.com/nirholas/three.ws/tree/main/docs/companion/bridges):
+
+- **[`notify.sh`](https://github.com/nirholas/three.ws/blob/main/docs/companion/bridges/notify.sh)** -
+ one curl, no dependencies. Put it at the end of a build, a backup, a cron job:
+ `make release || ./notify.sh "Release build failed" --priority high`.
+- **[`gmail-apps-script.gs`](https://github.com/nirholas/three.ws/blob/main/docs/companion/bridges/gmail-apps-script.gs)** -
+ runs inside your own Google account on a 5-minute trigger. three.ws never sees
+ your mailbox or your credentials, and `REDACT_BODY = true` sends only sender
+ and subject.
+- **[`macos-mail-rule.applescript`](https://github.com/nirholas/three.ws/blob/main/docs/companion/bridges/macos-mail-rule.applescript)** -
+ an Apple Mail rule. Point it at a VIP sender, or at everything and let the
+ triage do the filtering.
+- **Android**: MacroDroid or Tasker have a real notification-listener trigger.
+ Trigger: *Notification Received*. Action: *HTTP Request* → POST the JSON above,
+ mapping the notification's app, title and text into `app`, `sender`, `title`.
+ That is the closest thing to full phone mirroring that exists without writing
+ an app.
+- **iOS**: Shortcuts automations (time of day, arriving somewhere, an app
+ opening, an NFC tag, a focus change) can post the same JSON with the *Get
+ Contents of URL* action, and a Share Sheet shortcut lets you forward anything
+ you are looking at by hand. iOS does not expose a general "any notification"
+ trigger to Shortcuts, so full mirroring needs the calendar and email lanes, or
+ a third-party forwarder app, rather than a Shortcut.
+- **Anything else**: Zapier, n8n, Make, a webhook from your own service. The
+ body above is the whole contract.
+
+### Telegram
+
+Create a bot with [@BotFather](https://t.me/BotFather) (`/newbot`), paste the
+token, then message that bot or add it to a group. Telegram gives no read access
+to a human account's chats and no OAuth for one, so a bot you own is the real
+supported path: it costs nothing, it can only see what you add it to, and
+revoking the token ends the connection with nothing to clean up.
+
+### Calendar
+
+Paste the private iCal URL your calendar already publishes:
+
+- **Google Calendar** → Settings for my calendars → *Secret address in iCal format*
+- **Apple / iCloud** → share the calendar → copy the `webcal://` link (pasted as-is; it is converted)
+- **Outlook / Microsoft 365** → *Publish a calendar* → ICS
+- Any CalDAV server, Fastmail, Proton, Zoho: all publish one.
+
+Events are announced as they approach, once each, inside a window you choose (10
+minutes to 2 hours). Recurring series are expanded correctly, cancelled entries
+are skipped, and a moved instance is announced at its new time.
+
+### Email
+
+IMAP with an **app password**, never your account password. Gmail, iCloud,
+Fastmail, Proton Bridge and Outlook all issue one per app and let you revoke it
+independently.
+
+- The mailbox is opened **read-only**: your unread state is never touched.
+- Only headers and a short text preview are read.
+- The first check records where the mailbox is *now*, so connecting an inbox with
+ 40,000 messages does not announce 40,000 of them.
+
+Prefer that your mail never leaves your machine at all? See
+[local privacy mode](#local-privacy-mode-triage-on-your-own-machine).
+
+---
+
+## How it decides
+
+Every message is scored 0 to 100. Two passes, and the first always runs:
+
+**1. The rules.** Deterministic, instant, no key, no cost. They read:
+
+| Signal | Effect |
+|---|---|
+| From a saved contact | +18, plus that contact's own priority (-100 to +100) |
+| Looks like a one-time code or a login alert | +40 (the most perishable message there is) |
+| Urgent language ("asap", "deadline", "final notice") | +22 |
+| Asks you directly ("call me", "I'm outside", "where are you") | +18 |
+| Money, invoices, declined payments, fraud | +14 |
+| Flights, deliveries, cancellations, appointments | +12 |
+| Ends in a question | +6 |
+| Reads like marketing, or came from `noreply@` | -28 / -20 |
+| A calendar event starting within 5 / 15 / 60 minutes | +32 / +24 / +12 |
+| Priority the sending device already assigned | ±20 |
+
+Each lane starts from a different baseline, because a calendar entry is on your
+own calendar and a stranger's email is not.
+
+**2. A language model, if one is available.** It can move the score and rewrite
+the spoken line into something a person would actually say. It runs on **your own
+Anthropic key** when you have stored one in your dashboard (BYOK), and on the
+platform's free lanes otherwise. If it is over quota, wrong, or absent, the
+deterministic verdict stands: nothing is ever lost to a model being unavailable.
+
+The message text is treated as untrusted data at every step. It is passed to the
+model inside a delimiter, the model is told it may not follow instructions found
+there, and only a number and two short strings are read back. Nothing a message
+says can make the companion do anything.
+
+Above your threshold and outside quiet hours, it is **spoken**. Below it, it is
+**kept**, with the score and the reason, in the feed on
+[/companion](https://three.ws/companion).
+
+### Answering it
+
+The companion brings you a message; going to find the app to answer it is where
+the illusion breaks. Any delivery whose lane can carry an answer gets a **Reply**
+box in place, under the message, in the feed:
+
+- **Telegram** replies through your own bot, into the same chat, quoting the
+ message it answers. Enter sends, Shift+Enter is a newline.
+- A calendar reminder and a phone notification have nothing to reply to, so they
+ do not offer the box at all rather than offering one that fails.
+- Answering mail would need SMTP credentials this feature deliberately never
+ asks for, so email is read only.
+
+Programmatically: `POST /api/companion/events/:id/reply { text }`, or
+`companion.reply(id, text)` in the SDK. The reply is stored with the message, so
+the feed reads as a conversation rather than a receipt.
+
+---
+
+## Who gets a face
+
+A contact maps an identity (`@sarah`, `[email protected]`, `+14155550100`) to:
+
+- a **display name**, used instead of a raw handle,
+- an **avatar** (any of yours, or one you make from a selfie at
+ [/create-selfie](https://three.ws/create-selfie)),
+- a **voice** from the [Voice Lab](https://three.ws/voice) catalogue,
+- a **priority** that is added to every message from that person.
+
+Identities are normalised, so the same person resolves whether they wrote from
+Telegram, email, or your phone.
+
+When a contact's message is delivered, the walking companion **swaps into their
+body for the length of the message and swaps back afterwards**: your own
+companion stays yours, and the message still arrives as them.
+
+---
+
+## Where it shows up
+
+### On three.ws
+
+Any page. The corner companion turns to you, waves, and speaks
+(`src/notification-herald.js`). Muting it for a browser, or turning the whole
+category off account-wide, both live in
+[/dashboard/settings](https://three.ws/dashboard/settings) under **Companion
+deliveries**.
+
+### On your phone
+
+Web Push, from the same delivery. Turn it on from the settings card on
+[/companion](https://three.ws/companion). On iOS, add three.ws to your home
+screen first: that is what makes push available.
+
+### On your desktop
+
+[`apps/desktop`](https://github.com/nirholas/three.ws/tree/main/apps/desktop) is
+a small Electron app: a transparent, click-through, always-on-top character that
+strolls across the bottom of your screen, and walks over to deliver.
+
+```bash
+cd apps/desktop && npm install && npm start
+```
+
+It signs in with the same bridge token, holds no other credential, and is
+click-through everywhere except the character and its bubble.
+
+### Anywhere you write code
+
+```js
+import { createCompanionClient, createCompanionStage } from '@three-ws/companion';
+
+const client = createCompanionClient({ token: 'cmp_…' });
+createCompanionStage({ client }).listen();
+```
+
+Full SDK reference:
+[`packages/companion-sdk`](https://github.com/nirholas/three.ws/tree/main/packages/companion-sdk).
+
+---
+
+## Let an agent interrupt you
+
+An agent that finds something genuinely urgent should not write it into a log
+nobody reads. With the companion's MCP server it becomes a character standing in
+front of the person who needed to know:
+
+```jsonc
+{
+ "mcpServers": {
+ "companion": {
+ "command": "npx",
+ "args": ["-y", "@three-ws/companion", "mcp"],
+ "env": { "COMPANION_TOKEN": "cmp_…" }
+ }
+ }
+}
+```
+
+Tools: `deliver_message`, `list_deliveries`, `score_message`. The agent does not
+get to decide whether you are interrupted: its message goes through the same
+triage, the same threshold, and the same quiet hours as everything else.
+
+---
+
+## Local privacy mode: triage on your own machine
+
+```bash
+npm install -g @three-ws/companion imapflow
+companion login --token cmp_…
+companion watch-imap --host imap.fastmail.com --user [email protected] --redact
+```
+
+This connects to your inbox **locally**, scores every new message with exactly
+the rules above on your own hardware (`@three-ws/companion/triage` is the same
+module the server runs), and posts only what clears the bar, with the body
+redacted. The service never sees the mailbox, the password, or the messages that
+did not matter.
+
+---
+
+## The API
+
+Everything the page does, you can do. Session cookie or bridge token.
+
+| Endpoint | Method | What it does |
+|---|---|---|
+| `/api/companion/ingest` | POST | Hand it a message (bridge token). Returns the triage verdict. |
+| `/api/companion/stream` | GET | Live deliveries as Server-Sent Events. |
+| `/api/companion/events` | GET | The feed, with scores and reasons. |
+| `/api/companion/events/:id` | PATCH | Mark delivered or dismissed. |
+| `/api/companion/events/:id/reply` | POST | Answer through the connection it arrived on. |
+| `/api/companion/sources` | GET, POST | List or connect a source (verified before saving). |
+| `/api/companion/sources/:id` | PATCH, DELETE, POST | Rename, pause, disconnect, or check now. |
+| `/api/companion/contacts` | GET, POST | The people who get a face. |
+| `/api/companion/contacts/:id` | DELETE | Forget one. |
+| `/api/companion/settings` | GET, PATCH, POST | Threshold, quiet hours, default body and voice; POST rotates the bridge token. |
+| `/api/companion/poll` | POST | Poll every connected source now. |
+
+A delivery on the stream carries everything a body needs to perform it:
+
+```jsonc
+{
+ "id": "…",
+ "speaker": "Sarah",
+ "spoken_line": "Sarah says she is downstairs and cannot find your door.",
+ "importance": 88,
+ "reason": "from Sarah, a saved contact; asks you for something directly",
+ "avatar_glb_url": "https://three.ws/api/avatars/…/glb",
+ "voice": "nova",
+ "source_kind": "telegram",
+ "can_reply": true,
+ "created_at": "2026-08-28T12:04:11.221Z"
+}
+```
+
+---
+
+## What is stored, and what is not
+
+- **Credentials** (bot token, IMAP password, calendar URL) are encrypted with
+ AES-256-GCM before they touch the database, and the UI only ever shows you
+ enough to recognise which account is connected.
+- **Messages** are stored as the title, a short preview, the score, and the
+ reason, so the feed can explain itself. Email bodies are truncated to a
+ preview and never fetched in full.
+- **The bridge token** is the one credential a device needs. Rotating it at
+ [/companion](https://three.ws/companion) revokes every device at once.
+- Disconnecting a source **deletes its stored credential**.
+
+## Troubleshooting
+
+| What you see | What it means |
+|---|---|
+| A source says **needs attention** | The provider's own error is shown on the card: an expired bot token, an ICS URL that returns HTML, an IMAP login the server refused. Fix it and press **Check now**. |
+| Telegram connected, nothing arrives | The bot only sees what you add it to. Message the bot directly, or add it to the group, and press **Check now**. |
+| Calendar connected, nothing arrives | Events are only announced as they approach. Widen the lookahead, or wait for the next one. |
+| Everything is **held**, nothing spoken | Your threshold is above what those messages scored. The feed shows each score and reason; lower the bar, or give the sender a contact card with a priority. |
+| Nothing is spoken at night | That is quiet hours doing its job. |
+| The desktop app says **Not signed in** | Paste the bridge token in the tray menu, or run `companion login`. |
+| `companion doctor` | Prints the token in use, whether the API is reachable, and the health of every connected source. |
+
+## Related
+
+- [`packages/companion-sdk`](https://github.com/nirholas/three.ws/tree/main/packages/companion-sdk) - client, triage rules, CLI, MCP server.
+- [`apps/desktop`](https://github.com/nirholas/three.ws/tree/main/apps/desktop) - the desktop companion.
+- [Walk embed API](https://three.ws/docs/walk-embed-api) - the postMessage contract the bodies are driven with.
+- [Notifications](https://three.ws/notifications) - every delivery, and everything else, in one inbox.
+
+---
+
+<a id="sec-157"></a>
> **Source:** `docs/compose.md` · [↑ table of contents](#table-of-contents)
@@ -40855,7 +42570,7 @@ The page is a Three.js scene with PMREM image-based lighting, soft shadows, expo
### 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-115) 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-117) survive it.
## Walkthrough
@@ -40908,15 +42623,15 @@ curl -X PATCH 'https://three.ws/api/avatars/<avatarId>' \
## Related
-- [Avatar Studio](#sec-115): build the avatar you dress here.
-- [Animation Studio](#sec-092): pose and animate the dressed avatar.
-- [Scene Studio](#sec-385): the full three.js editor for heavier scene authoring.
-- [Restyle Studio](#sec-380): re-skin the forged props before attaching them.
+- [Avatar Studio](#sec-117): build the avatar you dress here.
+- [Animation Studio](#sec-094): pose and animate the dressed avatar.
+- [Scene Studio](#sec-399): the full three.js editor for heavier scene authoring.
+- [Restyle Studio](#sec-394): 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-153"></a>
+<a id="sec-158"></a>
> **Source:** `docs/concierge.md` · [↑ table of contents](#table-of-contents)
@@ -41024,12 +42739,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-390): every other way to put a three.ws creation on your site
-- [MCP](#sec-284): the full catalog of three.ws MCP servers, including this one
+- [Share and embed](#sec-407): every other way to put a three.ws creation on your site
+- [MCP](#sec-293): the full catalog of three.ws MCP servers, including this one
---
-<a id="sec-154"></a>
+<a id="sec-159"></a>
> **Source:** `docs/configuration.md` · [↑ table of contents](#table-of-contents)
@@ -41085,7 +42800,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-175)).
+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-181)).
#### `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.
@@ -41141,6 +42856,9 @@ OPENROUTER_API_KEY=sk-or-xxxxx
#### `NVIDIA_API_KEY`
**Optional.** NVIDIA NIM free tier, a third independent free lane.
+#### `SAMBANOVA_API_KEY`, `MISTRAL_API_KEY`, `ZAI_API_KEY`
+**Optional.** Three more free lanes, tried after NVIDIA in that order: SambaNova Cloud, Mistral's Experiment tier, and Z.AI's GLM Flash lane. Each joins the ladder only when its key is present, so `/api/chat` degrades across providers without a code change. The server-side completion chain in [api/_lib/llm.js](../api/_lib/llm.js) also accepts optional Cerebras, Gemini AI Studio, Cloudflare Workers AI (`CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_AI_API_TOKEN`), and SiliconFlow lanes on the same free-first rule.
+
#### `ANTHROPIC_API_KEY`
**Optional (paid backstop).** Anthropic key, tried after the free lanes. Also accepted as a user-supplied BYOK key.
@@ -41266,7 +42984,7 @@ VITE_CHARACTER_STUDIO_URL=http://localhost:5173
The three.ws avatar builder is an open-source 3D avatar editor (full body customisation — hair, clothing, accessories, skin tone, proportions). It runs as a separate Vite/React app under `character-studio/` in this monorepo and posts the exported GLB back to the parent via `postMessage`. It is fully compatible with the three.ws avatar runtime — same humanoid skeleton naming, ARKit `viseme_*` blendshapes, and Mixamo animation support.
#### `AVATURN_API_KEY`
-**Optional.** API key for the photo-to-avatar pipeline. Used server-side by `/api/onboarding/avaturn-session` to exchange selfie photos for a session URL.
+**Optional.** API key for the photo-to-avatar pipeline. Used server-side by `/api/onboarding/avaturn-session` (`api/onboarding/[action].js`) to exchange selfie photos for a session URL.
```
AVATURN_API_KEY=xxxxx
@@ -41296,10 +43014,10 @@ VITE_AVATURN_DEVELOPER_ID=xxxxx
```
#### `AVATAR_REGEN_PROVIDER`
-**Optional.** Provider for avatar regeneration. Set to `stub` for testing. Defaults to `none` (API returns `501 regen_unconfigured`).
+**Optional.** Platform provider for avatar regeneration and reconstruction: `replicate`, `huggingface`, or `gcp` (`api/_lib/regen-provider.js`). When unset the provider is inferred from credentials, paid first: `REPLICATE_API_TOKEN` selects Replicate, then `GCP_RECONSTRUCTION_URL` the self-hosted Cloud Run worker, then `HF_TOKEN` the HF Spaces queue; with none of those the platform provider is `none` and the reconstruct endpoint falls back to a user's stored BYOK key (Meshy, Tripo) before answering `501`.
```
-AVATAR_REGEN_PROVIDER=none
+AVATAR_REGEN_PROVIDER=replicate
```
---
@@ -41418,6 +43136,8 @@ A **live configuration file** consumed at runtime by the Cloud Run server ([`ser
**Key route patterns:**
```json
+{ "src": "/agents/([^/.]+)/edit", "dest": "/agent-edit.html" }
+{ "src": "/agents/([^/.]+)/embed", "dest": "/agent-embed.html" }
{ "src": "/agent/([^/]+)/edit", "dest": "/agent-edit.html" }
{ "src": "/agent/([^/]+)/embed", "dest": "/agent-embed.html" }
{ "src": "/agent/([^/]+)", "status": 301, "headers": { "Location": "/agents/$1" } }
@@ -41426,7 +43146,7 @@ A **live configuration file** consumed at runtime by the Cloud Run server ([`ser
{ "src": "/studio", "dest": "/studio/index.html" }
```
-**Embed routes** include security headers that allow cross-origin iframe embedding:
+**Embed routes** (both the `/agents/:id/embed` and legacy `/agent/:id/embed` spellings) include security headers that allow cross-origin iframe embedding:
```json
{
@@ -41494,7 +43214,7 @@ dist-lib/agent-3d.umd.cjs # UMD (CommonJS-compatible)
Three.js and ethers are bundled (not externalized) so the web component works as a zero-install drop-in embed via `<script type="module">`.
-**VitePWA** generates a service worker for the app build. Only `**/*.{ico,woff2}` are precached; HTML, JS, and CSS are deliberately excluded so deploys take effect immediately. Google Fonts are cached with a `CacheFirst` strategy and a 1-year TTL, and `/api/*` is never intercepted by the service worker.
+**VitePWA** generates a service worker for the app build. Only `**/*.{ico,woff2}`, `offline.html` and `pwa-icon.svg` (the offline shell) are precached; HTML pages, JS, and CSS are deliberately excluded so deploys take effect immediately. Google Fonts are cached with a `CacheFirst` strategy and a 1-year TTL, and `/api/*` is never intercepted by the service worker.
The dev server includes a rewrite middleware that mirrors the `vercel.json` route patterns, so `http://localhost:3000/agent/my-agent/edit` works the same as in production.
@@ -41583,7 +43303,7 @@ Before going live, verify the following:
---
-<a id="sec-155"></a>
+<a id="sec-160"></a>
> **Source:** `docs/content/use-cases/README.md` · [↑ table of contents](#table-of-contents)
@@ -41595,11 +43315,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-160) | Turn a selfie or a text prompt into a 3D agent and embed it anywhere. |
-| Game studio | [game-studio.md](#sec-159) | 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-156) | Give an agent a body, paid endpoints (x402), an MCP/A2A interface, and on-chain identity. |
-| Brand / marketer | [brand-marketer.md](#sec-157) | Put an embeddable, verifiable talking agent on a site, distributed through cloud marketplaces. |
-| Crypto community | [crypto-community.md](#sec-158) | Give a token community a live 3D world, an agent economy, and on-chain reputation. |
+| Indie creator | [indie-creator.md](#sec-165) | Turn a selfie or a text prompt into a 3D agent and embed it anywhere. |
+| Game studio | [game-studio.md](#sec-164) | 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-161) | Give an agent a body, paid endpoints (x402), an MCP/A2A interface, and on-chain identity. |
+| Brand / marketer | [brand-marketer.md](#sec-162) | Put an embeddable, verifiable talking agent on a site, distributed through cloud marketplaces. |
+| Crypto community | [crypto-community.md](#sec-163) | Give a token community a live 3D world, an agent economy, and on-chain reputation. |
## How to read these (the honesty frame)
@@ -41628,7 +43348,7 @@ Every scenario on these pages is an **example workflow** — clearly labeled "Im
---
-<a id="sec-156"></a>
+<a id="sec-161"></a>
> **Source:** `docs/content/use-cases/ai-agent-developer.md` · [↑ table of contents](#table-of-contents)
@@ -41648,8 +43368,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-284) 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-563) 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-293) 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-589) 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/`.
@@ -41657,8 +43377,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-284) 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-563): 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-293) 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-589): 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.
@@ -41669,14 +43389,14 @@ A standards-based interface (MCP + A2A), a working USDC payment rail (x402 on Ba
## Next step / CTA
-- Start: [MCP setup](#sec-284) · [x402 docs](#sec-563) · [SDK docs](#sec-386) · register via [Register On-Chain](#sec-477).
+- Start: [MCP setup](#sec-293) · [x402 docs](#sec-589) · [SDK docs](#sec-400) · register via [Register On-Chain](#sec-497).
- 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-157"></a>
+<a id="sec-162"></a>
> **Source:** `docs/content/use-cases/brand-marketer.md` · [↑ table of contents](#table-of-contents)
@@ -41698,7 +43418,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-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.
+3. **Cloud marketplace distribution** — three.ws is an **AWS Partner** with an **AWS Marketplace SaaS listing** (in review; see [docs/aws-marketplace.md](#sec-125) 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)
@@ -41718,7 +43438,7 @@ Four real capabilities cover embodiment, reach, and trust:
width="340px" height="440px"
></agent-3d>
```
-3. She [registers the agent on-chain](#sec-477) (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-497) (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.
@@ -41728,14 +43448,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-477) → 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).
+- Start: [Widget Studio](https://three.ws/studio) → [Register On-Chain](#sec-497) → claim a name at [`/threews/claim`](https://three.ws/threews/claim).
+- Enterprise: [AWS Marketplace listing](#sec-125) · [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-158"></a>
+<a id="sec-163"></a>
> **Source:** `docs/content/use-cases/crypto-community.md` · [↑ table of contents](#table-of-contents)
@@ -41756,7 +43476,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-563) (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-589) (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)
@@ -41765,7 +43485,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-477), 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-497), 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.
@@ -41776,13 +43496,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-563) for the agent-economy rails · [Register On-Chain](#sec-477) for reputation.
+- Build: [x402 docs](#sec-589) for the agent-economy rails · [Register On-Chain](#sec-497) 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-159"></a>
+<a id="sec-164"></a>
> **Source:** `docs/content/use-cases/game-studio.md` · [↑ table of contents](#table-of-contents)
@@ -41823,13 +43543,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-447) · [Agent System docs](#sec-064) · [Skill spec](../specs/SKILL_SPEC.md).
+- Learn: [Write a Custom Skill](#sec-467) · [Agent System docs](#sec-065) · [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-160"></a>
+<a id="sec-165"></a>
> **Source:** `docs/content/use-cases/indie-creator.md` · [↑ table of contents](#table-of-contents)
@@ -41883,13 +43603,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-456) · [Embed on Your Website](#sec-452).
+- Learn: [Build Your First Agent](#sec-476) · [Embed on Your Website](#sec-472).
- **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-161"></a>
+<a id="sec-166"></a>
> **Source:** `docs/contributing.md` · [↑ table of contents](#table-of-contents)
@@ -41964,7 +43684,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-154) and the [Deployment & Self-Hosting](#sec-175) guide.
+For full backend setup — R2 storage, environment variables, and how the app is deployed — see the [Configuration Reference](#sec-159) and the [Deployment & Self-Hosting](#sec-181) guide.
---
@@ -41998,7 +43718,7 @@ src/
└── components/ — vhtml JSX components (string-based, no virtual DOM)
```
-See the [Architecture Overview](#sec-258) for a deeper understanding of how these pieces connect.
+See the [Architecture Overview](#sec-268) for a deeper understanding of how these pieces connect.
---
@@ -42166,7 +43886,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-399) for the full format, lifecycle hooks, and message API.
+2. **Build your skill.** See the [Skills documentation](#sec-417) 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.
@@ -42202,7 +43922,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-387). 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-401). Public disclosure of an unpatched vulnerability puts all users at risk.
---
@@ -42229,7 +43949,7 @@ By contributing, you agree that your contributions are licensed under the [Apach
---
-<a id="sec-162"></a>
+<a id="sec-167"></a>
> **Source:** `docs/cookbook/asset-quality-gate.md` · [↑ table of contents](#table-of-contents)
@@ -42396,7 +44116,7 @@ build on any of them. They are a good backlog for whatever ships the assets.
---
-<a id="sec-163"></a>
+<a id="sec-168"></a>
> **Source:** `docs/cookbook/mcp-3d-tool.md` · [↑ table of contents](#table-of-contents)
@@ -42535,7 +44255,7 @@ endpoints.
---
-<a id="sec-164"></a>
+<a id="sec-169"></a>
> **Source:** `docs/cookbook/parallel-asset-pack.md` · [↑ table of contents](#table-of-contents)
@@ -42704,7 +44424,7 @@ machine. Useful for picking a triangle budget before you commit to one.
---
-<a id="sec-165"></a>
+<a id="sec-170"></a>
> **Source:** `docs/cookbook/text-to-3d-cli.md` · [↑ table of contents](#table-of-contents)
@@ -42853,7 +44573,7 @@ the lane is queued, which is exactly when `retryAfter` starts mattering.
---
-<a id="sec-166"></a>
+<a id="sec-171"></a>
> **Source:** `docs/copy-trading.md` · [↑ table of contents](#table-of-contents)
@@ -42868,9 +44588,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-235) 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-242) 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-401) for the first-party wallet reputation graph, [the trading surfaces](#sec-429) 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-394) for the paid-feed variant that reuses the same guarded executor.
+Related reading: [Smart Money Radar](#sec-419) for the first-party wallet reputation graph, [the trading surfaces](#sec-447) for the screeners and the trading cockpit these leaders trade from, [agent wallets](#sec-074) for the custody and spend-policy model, and [signal marketplace](#sec-412) for the paid-feed variant that reuses the same guarded executor.
---
@@ -42880,7 +44600,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-235).
+- **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-242).
- **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`.
@@ -42905,7 +44625,7 @@ Money-moving actions are yours to confirm. Nothing on these pages spends without
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.
+`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-147) 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
@@ -43255,7 +44975,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-401).
+For first-party wallet reputation earned from three.ws's own outcome ledger rather than an external taxonomy, use [Smart Money Radar](#sec-419).
---
@@ -43289,7 +45009,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-284) for wiring these into a client.
+See [the MCP reference](#sec-293) for wiring these into a client.
---
@@ -43297,14 +45017,14 @@ See [the MCP reference](#sec-284) for wiring these into a client.
1. Read the leader's `track-record`, not just their rank. Check `settled` (sample size) and `max_drawdown_sol`, not only ROI.
2. Set `max_per_trade_sol` and `daily_budget_sol` on the follow edge. They stack under the agent's own spend policy, so the tighter number wins.
-3. Confirm your agent's spend policy and trade limits are what you think they are. See [agent wallets](#sec-072).
+3. Confirm your agent's spend policy and trade limits are what you think they are. See [agent wallets](#sec-074).
4. Start with `proportional` sizing at a low `proportion_pct` rather than `pct_balance`, which scales with the wallet and grows as it grows.
5. Know where the kill switch is: the toggle on `/mirror`, or `POST /api/agents/:id/mirror/kill`.
6. Watch the first few fills. `skip_reason` tells you which guard is binding, and a stream of `Over per-trade cap` means your leader trades bigger than your leash.
---
-<a id="sec-167"></a>
+<a id="sec-172"></a>
> **Source:** `docs/cosmos.md` · [↑ table of contents](#table-of-contents)
@@ -43395,13 +45115,146 @@ else {
## Related
-- [Forge](#sec-227) 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.
+- [Forge](#sec-234) makes the 3D avatars and objects you place in a Cosmos world.
+- [Avatar creation](#sec-111) and [the trait-based avatar builder](#sec-140) for building and dressing avatars.
- Pages: [/create](https://three.ws/create), [/gallery](https://three.ws/gallery), [/scene](https://three.ws/scene).
---
-<a id="sec-168"></a>
+<a id="sec-173"></a>
+
+> **Source:** `docs/create-agent.md` · [↑ table of contents](#table-of-contents)
+
+# create-agent: one command, one 3D character
+
+```bash
+npm create @three-ws/agent "a friendly cartoon astronaut in a glossy white suit"
+```
+
+That command generates a textured 3D figure, rigs it with a humanoid skeleton, downloads it, and writes a folder with a working demo page and the embed snippet for your own site. No account, no API key, no signup: it runs on the three.ws free lane and the platform's provider keys cover the cost.
+
+It is the terminal-native version of [three.ws/create](https://three.ws/create), for people who would rather stay in a shell, and for scripts and CI that need a character without a browser.
+
+---
+
+## The 60-second version
+
+```bash
+$ npm create @three-ws/agent "a knight in worn steel armor"
+
+three.ws building "a knight in worn steel armor"
+ a rigged humanoid, free lane, no account needed
+
+· sent to the three.ws forge
+· generating the figure (15s)
+· generating the figure, then the skeleton (60s)
+✓ model ready
+· downloading the model
+
+Knight In Worn is ready in 88s
+
+ folder a-knight-in-worn/
+ index.html
+ agent.json
+ README.md
+ agent.glb (3.1 MB)
+ viewer https://three.ws/viewer?src=…
+```
+
+```bash
+$ npx serve a-knight-in-worn
+```
+
+The demo page renders the character with `<agent-3d>`; `agent.glb` is yours to drop into Blender, Unity, Godot, or any glTF tool.
+
+---
+
+## What lands on disk
+
+| File | What it is |
+| --- | --- |
+| `agent.glb` | The model with its skeleton. Poseable and animatable, because three.ws retargets its pre-baked clip library onto any humanoid rig it can canonicalize. |
+| `index.html` | A demo page that works on a double click. It points at the **hosted** model URL on purpose: a page opened over `file://` cannot fetch a neighbouring `.glb` without a server, and a demo that shows nothing is worse than no demo. |
+| `agent.json` | Prompt, hosted URLs, backend, generation time, and a `madeWith` marker, so a script can pick the result up. |
+| `README.md` | The embed snippet and the next steps, written for whoever opens the folder later. |
+
+---
+
+## Options
+
+| Option | Meaning |
+| --- | --- |
+| `--photo <url>` | Build the character from a public https reference image instead of a description |
+| `--out <dir>` | Where to write the project (default: a slug of the description) |
+| `--name <name>` | Display name (default: derived from the description) |
+| `--object` | An object or prop (mesh only) instead of a rigged character |
+| `--no-download` | Keep the hosted model URL, skip writing `agent.glb` |
+| `--json` | Print the result as JSON and nothing else, for scripting |
+| `--origin <url>` | API origin (default `https://three.ws`) |
+
+### Writing a prompt that rigs well
+
+Describe **one full-body humanoid in a neutral standing pose**. Lead with the subject, then materials and colours; the free lane conditions on roughly the first 77 characters, so front-load what matters.
+
+Good: `a friendly cartoon astronaut in a glossy white suit, orange visor`
+Less good: `an epic scene where an astronaut floats above a ringed planet`
+
+A clearly non-humanoid subject (furniture, a vehicle, a quadruped) should use `--object`. Auto-rigging assumes a humanoid.
+
+---
+
+## Under the hood
+
+The CLI is a thin client over one public endpoint:
+
+```bash
+curl -s -X POST https://three.ws/api/mcp-studio \
+ -H 'content-type: application/json' \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "forge_avatar",
+ "arguments": { "prompt": "a friendly cartoon astronaut in a glossy white suit" }
+ }
+ }'
+```
+
+`forge_avatar` is generate-then-rig bundled; `--object` calls `forge_free` instead. Both are open, keyless JSON-RPC tools on the same endpoint the three.ws MCP server exposes, so anything that can speak HTTP can do what this CLI does. The MCP surface is documented in [mcp.md](#sec-293).
+
+The job blocks server-side until the model exists, which is why the CLI reports **real elapsed seconds** rather than a progress bar it would have to invent. Every call carries a 10-minute deadline; on a timeout the job may still finish, and finished models land at [three.ws/creations](https://three.ws/creations).
+
+---
+
+## Programmatic use
+
+```js
+import { createAgent } from '@three-ws/create-agent';
+
+const made = await createAgent({
+ prompt: 'a friendly cartoon astronaut',
+ out: './astro',
+ onProgress: ({ message }) => console.log(message),
+});
+```
+
+`createAgent`, `callForge`, `downloadModel` and the scaffold builders are all exported, and each takes `{ fetchImpl, signal, origin }`, so the pipeline runs against a local three.ws or a test double. Errors are one class, `ForgeError`, carrying a `code`: `timeout`, `unreachable`, `no_model`, `rpc_error`, `http_<status>`.
+
+Full reference: [packages/create-agent/README.md](https://github.com/nirholas/three.ws/blob/main/packages/create-agent/README.md).
+
+---
+
+## Then what
+
+- **Put it on your site.** The printed snippet is the whole integration; attribute reference in [web-component.md](#sec-543).
+- **Give it a brain and a voice.** [three.ws/create](https://three.ws/create) takes the same model and adds a personality, memory, and speech.
+- **Show what it is doing.** [Glance](#sec-244) puts the agent's live status on a home screen, in a README, or in Slack.
+- **Let other agents hire it.** [three.ws/marketplace](https://three.ws/marketplace).
+
+---
+
+<a id="sec-174"></a>
> **Source:** `docs/creator-portfolio.md` · [↑ table of contents](#table-of-contents)
@@ -43421,7 +45274,7 @@ feed/follow/rankings graph is covered in
|---|---|
| `/u/:username` | The public portfolio. No auth required; anyone can view it. |
| `/profile` | Self-view resolver for the signed-in user (see below). |
-| `/u/0x<40 hex>` | Legacy wallet-address profile: the on-chain agent list for that address ([src/erc8004/user-profile.js](../src/erc8004/user-profile.js)). |
+| `/u/0x<40 hex>` | Legacy wallet-address profile: the on-chain agent list for that address ([src/erc8004/user-profile.js](../src/erc8004/user-profile.js)). Each chain is read through `readProvider()` from [src/erc8004/chain-meta.js](../src/erc8004/chain-meta.js), which fails over across keyless public RPC nodes so one rate-limited endpoint cannot blank the list. |
All three are served by [pages/profile.html](../pages/profile.html); the page
inspects the path segment and mounts the right view.
@@ -43462,8 +45315,9 @@ instead.
**Walking-avatar hero.** The owner's primary avatar walks live in an embedded
`/walk-embed` iframe with two real CTAs: "Say hi" opens the avatar's live
-chat surface, "Walk with me" opens the full walk experience alongside the
-owner ([src/profile-walk-hero.js](../src/profile-walk-hero.js)).
+chat surface (`/avatars/:id?view=chat` for an avatar, `/agents/:id#chat` for an
+agent), "Walk with me" opens the full walk experience alongside the owner
+([src/profile-walk-hero.js](../src/profile-walk-hero.js)).
**Stats strip.** Followers and Following lead and are clickable (they open
the follow-list modal). After them, one tile per non-zero count: Creations,
@@ -43482,7 +45336,7 @@ is active by default, and the bar hides when fewer than two tabs survive:
|---|---|---|
| Creations | Forged 3D models, saved worlds, and restyled models, merged by recency. Each card is a live rotating 3D thumbnail with the type badge (Model / World / Restyle), a remix tag where applicable, and a copy-the-prompt button. | `/viewer?src=<glb>` or `/diorama?id=<id>` |
| Avatars | Public avatars with tags, file size, fork count, and a Fork button. | `/avatars/:id` |
-| Agents | Public agents with on-chain identity metadata (ERC-8004 id, wallet, `.sol` domain, X / Farcaster) and, when published, a Fork button. | `/agent/:id` |
+| Agents | Public agents with on-chain identity metadata (ERC-8004 id, wallet, `.sol` domain, X / Farcaster) and, when published, a Fork button. | `/agents/:id` |
| Widgets | Public widgets with type and view count. | `/w/:id` |
| Skills | Published marketplace skills with category, per-call price, and installs. | `/marketplace#<slug>` |
| Plugins | Published plugins with installs and rating. | rendered in place |
@@ -43549,7 +45403,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-300).
+ documented in [Notifications](#sec-311).
- **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
@@ -43582,25 +45436,29 @@ The header's share button opens a small menu: the native share sheet where
the browser supports it, share to X, and copy link. Page title, description,
and the OG/Twitter card (rendered live by
[api/u-og.js](../api/u-og.js)) are rewritten per profile, so a shared link
-unfurls with the creator's actual name and stats.
+unfurls with the creator's actual name and stats. Because that image URL is
+what a crawler resolves for `og:image`, a database blip while rendering it
+degrades to a real card of the handle already known, sent `Cache-Control:
+no-store`, rather than a JSON error body that a crawler would cache as the
+unfurl; an unknown handle is still a cached 404 card.
---
## Related pages
-- [The social layer](#sec-403): the follow graph, feed, and
+- [The social layer](#sec-421): the follow graph, feed, and
rankings this page plugs into.
-- [Notifications](#sec-300): the follow, remix, sale, and royalty
+- [Notifications](#sec-311): the follow, remix, sale, and royalty
events a portfolio generates for its owner.
-- [Remix economy](#sec-377): what happens when someone remixes a creation
+- [Remix economy](#sec-390): what happens when someone remixes a creation
they found here.
-- [Forge](#sec-227), [Widgets](#sec-526),
- [Marketplace](#sec-277): the creation surfaces whose output the
+- [Forge](#sec-234), [Widgets](#sec-546),
+ [Marketplace](#sec-286): the creation surfaces whose output the
portfolio aggregates.
---
-<a id="sec-169"></a>
+<a id="sec-175"></a>
> **Source:** `docs/crews.md` · [↑ table of contents](#table-of-contents)
@@ -43791,7 +45649,7 @@ player who is already social in the world finds the group surface.
---
-<a id="sec-170"></a>
+<a id="sec-176"></a>
> **Source:** `docs/crypto-api.md` · [↑ table of contents](#table-of-contents)
@@ -44271,7 +46129,11 @@ array.
- **No symbols** → `400 missing_symbols` with the cap and an `example`.
- **More than 20 symbols** → `400 too_many_symbols` with the cap.
- **Registry source down** → `200` with `degraded: true`; affected symbols get
- `available: null` + a `note`. Never `500`.
+ `available: null` + a `note`. Never `500`. Each lookup is retried once and
+ keeps its last good DexScreener answer for 10 minutes, so through a throttle
+ the result still lists the last known `exactCollisions` / `fuzzyCollisions`
+ with `stale: true` (and `available: null`, because availability could not be
+ verified live); a fresh answer carries `stale: false`.
- **Rate-limited** → `429 rate_limited` with `RateLimit-*` + `Retry-After` headers.
### Examples
@@ -44622,8 +46484,11 @@ surfaces can never contradict each other.
`concentration: "unknown"`, and a note — a valid empty, not an error.
- **Missing/EVM/invalid `address`** → `400` with a clear message + example.
- **Valid address that isn't an on-chain mint** → `400 token_not_found`.
-- **Holder sources unreachable or throttled** → `503` + `Retry-After`. A throttled
- RPC is never reported as "no holders". Never `500`.
+- **Holder sources unreachable or throttled** → the last good answer for that
+ `address` + `limit`, held for 24 hours, served as `200` with `stale: true`,
+ `as_of` (when it was computed), and an `x-holders-stale: 1` header; with no
+ last good copy, `503` + `Retry-After`. A throttled RPC is never reported as
+ "no holders". Never `500`.
- **Rate-limited** → `429` with `RateLimit-*` + `Retry-After` headers.
### Examples
@@ -44703,6 +46568,10 @@ that layer, computed once server-side so every client renders the same numbers.
- **`slot`** - a palette slot per top asset, so the same wallet colors the same
way across reloads and across surfaces.
- **`stale: true`** - present only when the balance source served a cached read.
+ The 24h-change column has its own continuity: each DexScreener batch is
+ retried once and keeps its last good pair list for 10 minutes, so a throttle
+ no longer blanks every `change24h` in the batch in a way indistinguishable
+ from a token that genuinely has none.
### Sources
@@ -44838,7 +46707,7 @@ curl -s "https://three.ws/api/crypto/airdrops?address=<wallet>" \
---
-<a id="sec-171"></a>
+<a id="sec-177"></a>
> **Source:** `docs/custody.md` · [↑ table of contents](#table-of-contents)
@@ -44864,7 +46733,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-222) 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-229) 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
@@ -44923,14 +46792,14 @@ Every step of recovery and inheritance writes to the custody trail and the audit
## Related
-- [Financial controls](#sec-222) — plain-English spend rules and real-time wallet defense on these rails
-- [Trading surfaces](#sec-429) — Mission Control executes through this same guarded path
-- [The trading experiment](#sec-427) — an autonomous agent operating inside these limits, journaled
-- [x402](#sec-563) — the payment protocol these wallets spend over
+- [Financial controls](#sec-229) — plain-English spend rules and real-time wallet defense on these rails
+- [Trading surfaces](#sec-447) — Mission Control executes through this same guarded path
+- [The trading experiment](#sec-445) — an autonomous agent operating inside these limits, journaled
+- [x402](#sec-589) — the payment protocol these wallets spend over
---
-<a id="sec-172"></a>
+<a id="sec-178"></a>
> **Source:** `docs/daily-forge.md` · [↑ table of contents](#table-of-contents)
@@ -45029,14 +46898,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-224): the job and polling model
-- [AR and WebXR](#sec-099): the Scene Viewer and Quick Look handoff
-- [Quick start](#sec-373): the general free-forge onboarding
+- [Forge background generation](#sec-231): the job and polling model
+- [AR and WebXR](#sec-101): the Scene Viewer and Quick Look handoff
+- [Quick start](#sec-386): 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-173"></a>
+<a id="sec-179"></a>
> **Source:** `docs/daily-match.md` · [↑ table of contents](#table-of-contents)
@@ -45111,7 +46980,8 @@ the client clock is always in sync with the server's window.
`GET /api/leaderboard/daily-match?limit=N`
- `limit`: 1 to 50, default 20 (the page requests 25).
-- GET only, CORS-enabled, rate limited per client IP.
+- GET only, CORS-enabled for any origin (it is a public, anonymous board, so a
+ cross-origin fetch passes its preflight), rate limited per client IP.
- Cached `public, max-age=15, s-maxage=30, stale-while-revalidate=60`.
- Computed live per request over the daily window, the same pattern as
[`api/leaderboard/unified.js`](../api/leaderboard/unified.js).
@@ -45167,13 +47037,13 @@ falls back to `type`.
| Shared HTTP / rate-limit / DB helpers | [`api/_lib/http.js`](../api/_lib/http.js), [`api/_lib/rate-limit.js`](../api/_lib/rate-limit.js), [`api/_lib/db.js`](../api/_lib/db.js) |
| Sibling live-window leaderboard | [`api/leaderboard/unified.js`](../api/leaderboard/unified.js) |
-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-351) (launches).
+Related docs: [agent-sniper.md](#sec-062) (where the trade and P&L
+columns come from), [agent-skills.md](#sec-061) (skill sales),
+[pump-launcher.md](#sec-364) (launches).
---
-<a id="sec-174"></a>
+<a id="sec-180"></a>
> **Source:** `docs/demo-routes.md` · [↑ table of contents](#table-of-contents)
@@ -45272,7 +47142,7 @@ that canonical `.html` form.
| Route | Page file | What it does |
|---|---|---|
-| `/demos/agents` | `public/demos/agents/index.html` | Hub for the lab below, linked from the `/demos/` index. `/demos/agents/` reaches it too, via the sitewide trailing-slash 301. |
+| `/demos/agents` | `public/demos/agents/index.html` | Hub for the lab below, linked from the `/demos/` index. `/demos/agents/` reaches it too: `vercel.json` carries an explicit rewrite for both forms. |
| `/demos/agents/auto-rig.html` | `public/demos/agents/auto-rig.html` | Auto-rigging an imported mesh. |
| `/demos/agents/builds-button.html` | `public/demos/agents/builds-button.html` | Agent assembles a CTA button. |
| `/demos/agents/climb-title.html` | `public/demos/agents/climb-title.html` | Agent climbs the page title. |
@@ -45366,8 +47236,8 @@ Re-verified against production (`https://three.ws`) with `curl -sIL`:
resolve, so the `/demos/` index linked a URL that could not be served.
It stayed invisible because the dev server has explicit `fileMap`
entries for both forms in `vite.config.js`. `vercel.json` now carries
- a `/demos/agents` rewrite to `/demos/agents/index.html`, placed above
- the generic slug rule so it wins. It ships with the next deploy.
+ a `/demos/agents` rewrite to `/demos/agents/index.html` (and one for
+ `/demos/agents/`), placed above the generic slug rule so it wins.
- Directory URLs with a trailing slash (`/demos/`, `/demo/`,
`/demo/avatar-os/`) return **301** to the slashless form, which serves
the index with 200.
@@ -45400,7 +47270,7 @@ the 200s above still come from the 2026-08-05 curl sweep.
---
-<a id="sec-175"></a>
+<a id="sec-181"></a>
> **Source:** `docs/deployment.md` · [↑ table of contents](#table-of-contents)
@@ -45737,7 +47607,7 @@ TARGET=lib npm run build
# Output: dist-lib/
```
-The Vite config handles multi-page routing, asset hashing, and the PWA manifest. Every JS file in `dist/assets/` is content-hashed, so you can serve them with long cache headers safely — the `vercel.json` route headers set `max-age=604800` on `/assets/*`, and the container (and any CDN in front of it) honors them.
+The Vite config handles multi-page routing, asset hashing, and the PWA manifest. Every JS file in `dist/assets/` is content-hashed, so you can serve them with long cache headers safely: the `vercel.json` route headers set `public, max-age=31536000, immutable` on `/assets/*`, and the container (and any CDN in front of it) honors them.
---
@@ -45748,8 +47618,10 @@ The Vite config handles multi-page routing, asset hashing, and the PWA manifest.
### Key rewrites
```
-/agent/:id/edit → /agent-edit.html
-/agent/:id/embed → /agent-embed.html (frame-ancestors: * header)
+/agents/:id/edit → /agent-edit.html
+/agents/:id/embed → /agent-embed.html (frame-ancestors: * header)
+/agent/:id/edit → /agent-edit.html (legacy spelling, still served)
+/agent/:id/embed → /agent-embed.html (legacy spelling, same headers)
/agent/:id → 301 → /agents/:id
/agents/:id → /agent-detail.html (bot user-agents get the OG render)
/dashboard → /dashboard-next/index.html
@@ -45771,11 +47643,11 @@ 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-182) 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-188) guide for the driver patterns.
### Static asset caching
-Assets under `/assets/*` are served with a 7-day cache header. Versioned CDN bundles under `/agent-3d/x.y.z/*` are served with a 1-year immutable cache. Both are configured in `vercel.json` route headers.
+Assets under `/assets/*` are content-hashed and served with a 1-year immutable cache header. Versioned CDN bundles under `/agent-3d/x.y.z/*` are served with a 1-year immutable cache. Both are configured in `vercel.json` route headers.
---
@@ -45836,7 +47708,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-190), and verify
+[erc8004/validation-attestation.md](#sec-196), and verify
any configured registry address with `npm run verify:erc8004-validation`.
---
@@ -45866,7 +47738,7 @@ server {
}
location /assets/ {
- expires 7d;
+ expires 1y;
add_header Cache-Control "public, immutable";
}
@@ -45898,7 +47770,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-182) 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-188) guide.
### Database monitoring
@@ -45944,7 +47816,7 @@ After deploying, run through these checks to verify the instance is healthy:
| Wallet sign-in | Connect MetaMask — SIWE challenge + verify |
| Avatar creation | Navigate to `/create` — avatar builder iframe loads |
| Agent page | Visit `/agents/:id`: 3D viewer with chat overlay (`/agent/:id` 301-redirects here) |
-| Embed | Check `/agent/:id/embed` loads without auth, can be iframed |
+| Embed | Check `/agents/:id/embed` loads without auth, can be iframed |
| Dashboard | Navigate to `/dashboard` — shows your agents |
| API health | `GET /api/agents` returns JSON (may be empty array) |
| Auth metadata | `GET /.well-known/oauth-authorization-server` returns valid JSON |
@@ -45993,7 +47865,7 @@ Upstash REST API uses HTTPS — no ports to open. If you see connection errors,
---
-<a id="sec-176"></a>
+<a id="sec-182"></a>
> **Source:** `docs/deployments.md` · [↑ table of contents](#table-of-contents)
@@ -46005,7 +47877,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-189) for the standard, the registry contracts, and how to register; [deploying agents on-chain](#sec-311) for the Solana Metaplex Core path; [agent reputation on Solana](#sec-405) for the trust layer built on top of a Solana identity.
+Related reading: [ERC-8004 blockchain identity](#sec-195) for the standard, the registry contracts, and how to register; [deploying agents on-chain](#sec-322) for the Solana Metaplex Core path; [agent reputation on Solana](#sec-423) for the trust layer built on top of a Solana identity.
---
@@ -46020,7 +47892,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-311) (the single-agent, user-signed flow is in [Solana agents](#sec-406)), and Solana reputation and attestations are in [agent reputation on Solana](#sec-405). 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-322) (the single-agent, user-signed flow is in [Solana agents](#sec-424)), and Solana reputation and attestations are in [agent reputation on Solana](#sec-423). This page is only the index and the feed.
---
@@ -46080,7 +47952,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-189) 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-195) for the addresses and the contract surface.
### 2. Solana: three.ws's own Metaplex Core mints
@@ -46230,7 +48102,7 @@ The network toggle derives its chain-id sets from that table at import time, so
---
-<a id="sec-177"></a>
+<a id="sec-183"></a>
> **Source:** `docs/developer-platform.md` · [↑ table of contents](#table-of-contents)
@@ -46250,8 +48122,8 @@ The browser UI for all of this lives in the dashboard:
Base URL: `https://three.ws`
-Related docs: [MCP integration](#sec-284), [API reference](#sec-096),
-[Authentication](#sec-103), [x402 developer tools](#sec-557).
+Related docs: [MCP integration](#sec-293), [API reference](#sec-098),
+[Authentication](#sec-105), [x402 developer tools](#sec-582).
---
@@ -46291,13 +48163,18 @@ key, no CSRF.
## API keys
API keys are bearer credentials for machine clients: the MCP server at
-`/api/mcp` (see [MCP integration](#sec-284)) and the account-scoped REST
+`/api/mcp` (see [MCP integration](#sec-293)) and the account-scoped REST
endpoints that accept `Authorization: Bearer` (see the
-[API reference](#sec-096)). Each key carries a set of scopes:
+[API reference](#sec-098)). Each key carries a set of scopes:
`avatars:read`, `avatars:write`, `avatars:delete`, `profile`, `memory:read`,
`memory:write`, `agents:read`, `agents:write`
+One more scope, `herald:announce` (posting through the
+[Herald](#sec-248)), is accepted by `/api/keys`, the dashboard form, and the
+older `POST /api/api-keys` route documented in
+[Authentication](authentication.md#available-scopes).
+
Keys are stored as a SHA-256 hash. The plaintext secret is returned **exactly
once**, in the create response. Only the 12-character prefix is kept for
display.
@@ -46705,7 +48582,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-284) for configuring a real client against
+See [MCP integration](#sec-293) for configuring a real client against
`/api/mcp`.
---
@@ -46734,7 +48611,7 @@ between deploys without an MCP handshake.
### GET /api/skills-manifest
A machine-readable manifest of the browser agent's skills (see
-[Agent skills](#sec-060)). Public, CORS `*`, cached for 60 seconds
+[Agent skills](#sec-061)). Public, CORS `*`, cached for 60 seconds
(`cache-control: public, max-age=60`).
```bash
@@ -46784,7 +48661,7 @@ omitted from the manifest.
---
-<a id="sec-178"></a>
+<a id="sec-184"></a>
> **Source:** `docs/diorama.md` · [↑ table of contents](#table-of-contents)
@@ -46886,13 +48763,13 @@ until the world is saved:
## Related
-- [Forge](#sec-227) is the single-object generator every diorama object is forged on.
-- [Image to 3D](#sec-254) for photo-based objects; [AR](#sec-099) for viewing worlds in augmented reality.
+- [Forge](#sec-234) is the single-object generator every diorama object is forged on.
+- [Image to 3D](#sec-264) for photo-based objects; [AR](#sec-101) 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-179"></a>
+<a id="sec-185"></a>
> **Source:** `docs/do-i-need-crypto.md` · [↑ table of contents](#table-of-contents)
@@ -46972,14 +48849,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-272)
-- **Put it on your site** → [Share & embed](#sec-390)
-- **Optional: register on-chain** → [Register on-chain](#sec-477)
-- **Technical auth details** → [Authentication](#sec-103)
+- **Create your first agent** → [Make your first agent](#sec-284)
+- **Put it on your site** → [Share & embed](#sec-407)
+- **Optional: register on-chain** → [Register on-chain](#sec-497)
+- **Technical auth details** → [Authentication](#sec-105)
---
-<a id="sec-180"></a>
+<a id="sec-186"></a>
> **Source:** `docs/docs-world.md` · [↑ table of contents](#table-of-contents)
@@ -47012,6 +48889,8 @@ Both render the same files. The world fetches the same `/docs/nav.json` manifest
The **Index** chip (top left) lists every section; picking one teleports you to its pavilion and opens its page list. That list is fully keyboard-reachable, so nothing in the world requires mouse-precision walking.
+The **Search docs** chip (or `/`, or `Ctrl`+`K`) opens a palette over every page. `Enter` on a result opens the page at once; `Shift`+`Enter` hands you to the wayfinder, which walks your avatar to the right pavilion with a live route readout, a **Read now** shortcut that skips the walk, and a cancel button. The **?** chip holds the controls table and a **Replay the welcome tour** button.
+
## Your avatar
By default you walk as the platform's default rigged body, the same one [/walk](/walk) uses, animated by the shared canonical clip library. Pass any rigged GLB with `?avatar=`:
@@ -47024,7 +48903,7 @@ Any humanoid rig works; bone names are mapped automatically, exactly as describe
## Devices and accessibility
-- **No WebGL?** The page detects it and offers the classic docs instead; nothing is lost, because the content is identical.
+- **No WebGL?** The page detects it and offers the classic docs instead; nothing is lost, because the content is identical. A failure a reload can fix (a dropped `/docs/nav.json` fetch, an exhausted WebGL context budget, an unexpected boot error) shows the same fallback with a **Try again** button, focused once it is visible; a device with no GPU never gets that button, because reloading cannot help it.
- **`prefers-reduced-motion`** stills the ambient animation (floating labels, portal shimmer, drifting stars).
- The reader panel is real DOM, not a texture: text is selectable, zoomable, and visible to screen readers.
- Frame rate is governed like every three.ws 3D surface: 60fps focused, 30fps in the background or with the shared Power-saver preference on.
@@ -47058,7 +48937,7 @@ Every link carries a `label` plus exactly one of:
Three rules the test suite enforces in [`tests/docs-world.test.js`](https://github.com/nirholas/three.ws/blob/main/tests/docs-world.test.js), so a bad entry fails CI rather than shipping a dead link:
-1. Every `path` must resolve to a markdown file that actually exists.
+1. Every `path` must resolve to a markdown file that actually exists, in `docs/` (copied into the build) or `public/docs/` (served verbatim); either one reaches `/docs/<slug>.md`.
2. A link is a `path` **or** an `href`, never both and never neither.
3. No `path` may point into `docs/internal/`, `docs/ops/`, or `docs/security/`. Those directories are written for operators and are deliberately excluded from the published site, so a nav entry into one would 404 in production.
@@ -47066,7 +48945,7 @@ Adding a section is the same edit: append to `sections` and a new pavilion appea
---
-<a id="sec-181"></a>
+<a id="sec-187"></a>
> **Source:** `docs/draft-agent-mint.md` · [↑ table of contents](#table-of-contents)
@@ -47206,7 +49085,9 @@ The authority needs about 0.02 devnet SOL to cover the collection account, the
mint, and the registry enrolment on a first run. Fund it at
<https://faucet.solana.com>. The script writes an evidence JSON (asset,
signature, explorer link, storage checksum, chain read-back, EVM calldata) to
-`DRAFT_MINT_E2E_OUT`, defaulting to your temp directory.
+`DRAFT_MINT_E2E_OUT`, defaulting to your temp directory. At the end it deletes
+the user, avatar, and agent rows it created (the chain artifacts are permanent
+by nature); set `DRAFT_MINT_E2E_KEEP=1` to keep them.
### Running it without cloud credentials
@@ -47287,18 +49168,21 @@ explorer link, so the evidence file never overstates what was proven.
| Agent already minted on this network | `already`, with the existing asset address, no chain write |
| Agent Registry enrolment fails | The mint still stands; the back-fill retries the enrolment later |
| No EVM treasury key | EVM leg returns `dry_run` with real calldata and a real gas estimate |
+| `DRAFT_AGENT_MINT_EVM_CHAIN_ID` is not a chain in the table | EVM leg returns `skipped` / `unsupported_chain` |
+| Treasury cannot cover the agent wallet's gas top-up | EVM leg returns `skipped` / `treasury_low:<balance>`; nothing is broadcast |
+| Agent has no custodial EVM key to sign with | EVM leg returns `skipped` / `no_evm_key` |
| Database write fails after a mint | The avatar stamp is skipped with a warning; the on-chain asset and the agent meta are already written |
## Related
-- [Selfie to Avatar](#sec-389): 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
+- [Selfie to Avatar](#sec-406): the pipeline whose tail calls this
+- [Agent identities](#sec-054): what an agent identity is and how it is generated
+- [Agent tokens](#sec-071): what happens after a draft identity goes live
+- [The agent index](#sec-055): the cross-chain index that surfaces these registrations
---
-<a id="sec-182"></a>
+<a id="sec-188"></a>
> **Source:** `docs/economy-heartbeat.md` · [↑ table of contents](#table-of-contents)
@@ -47312,7 +49196,8 @@ every minute. When nothing hits them, the economy flat-lines while the site keep
serving traffic.
In production these endpoints are driven by **Google Cloud Scheduler** — one
-job per `vercel.json` cron entry (~76 jobs), each firing `GET /api/cron/<name>`
+job per `vercel.json` cron entry (the `crons` array there is the count; 110 at
+the 2026-08-28 sync), each firing `GET /api/cron/<name>`
with the `Authorization: Bearer $CRON_SECRET` header. (We do **not** use GitHub
Actions for any scheduling.)
@@ -47337,16 +49222,20 @@ that makes the economy move:
| --- | --- | --- |
| Payments & x402 | `x402-ring-tick`, `x402-seed-cron`, `x402-autonomous-loop`, `x402-ring-leak-scan`, `wallets-leak-scan`, `run-distribute-payments`, `payment-session-sweep` | ring settlements, micropayment feed, catalog spend, leak scans, payout distribution |
| Money Pulse, Labor & delegation | `pulse-tick`, `/api/labor/tick`, `index-delegations` | live wallet-activity feed, bounty bids/awards/settlements, agent hiring/delegation |
-| Coin launches (pump.fun) | `launcher-tick`, `launcher-claimer`, `coin-intel-observe`, `pumpfun-monitor`, `pumpfun-graduations-sync`, `run-coin-cycle`, `run-coin-payouts` | autonomous minting, fee claims, launch intel, graduation sync, coin lifecycle + payouts |
+| Coin launches (pump.fun) | `launcher-tick`, `launcher-claimer`, `pumpfun-monitor`, `pumpfun-graduations-sync`, `run-coin-cycle`, `run-coin-payouts` | autonomous minting, fee claims, graduation sync, coin lifecycle + payouts |
| Autonomous / copy / strategy trading | `copy-fanout`, `mirror-fanout`, `signal-fanout`, `strategy-fanout`, `run-dca` | copy trading, signal/strategy execution, DCA |
| Tips, payouts, subscriptions, royalties | `club-payouts`, `run-subscriptions`, `process-subscriptions`, `settle-royalties`, `cosmetic-splits-sweep` | tipping payouts, subscription billing, royalty + cosmetic-split settlement |
-| $THREE buyback | `run-buyback`, `run-three-buyback` | revenue → buy → treasury (internally gated hourly/daily) |
-| Funding, treasury & reconcile | `treasury-topup`, `treasury-autopilot`, `treasury-sweepback`, `economy-reconcile`, `reflect-sweep` | master-wallet funding root, treasury autopilot, tamper reconciliation |
+| $THREE buyback | `run-buyback`, `run-three-buyback`, `three-buy-loop` | revenue → buy → treasury (internally gated hourly/daily), plus the x402-settled micro-buy loop |
+| Funding, treasury & reconcile | `treasury-topup`, `economy-rebalance`, `treasury-autopilot`, `treasury-sweepback`, `economy-reconcile`, `reflect-sweep` | master-wallet funding root, economy rebalance, treasury autopilot, tamper reconciliation |
| $THREE market & holders | `three-market-refresh`, `three-holders-snapshot` | live coin market + holder snapshots |
The snipers / autonomous trading experiment run as a **standalone always-on Cloud
Run worker** ([workers/agent-sniper/](../workers/agent-sniper)), not a scheduled
cron, so they are continuous and not part of this dispatch list.
+`coin-intel-observe` is also deliberately absent: it watches PumpPortal for 85s
+inside its own 120s budget and runs on its own `*/2 * * * *` cron, so firing it
+from the dispatcher aborted it at the 60s call timeout every minute and pinned
+the heartbeat to `failed: 1`.
Every target engine is internally idempotent — per-tick spend caps, per-endpoint
cooldowns, and daily ceilings absorb over-calling — so it is safe to fire
@@ -47452,14 +49341,20 @@ CRON_SECRET=… DURATION_MINUTES=10 node scripts/economy-heartbeat.mjs
no-ops the extra calls.
- **Undeployed endpoints are tolerated.** A target missing from the deployed
build reports `status: 404` and never stops the others.
+- **A non-production process never drives production.** `APP_ORIGIN` falls
+ back to `https://three.ws` wherever `PUBLIC_APP_ORIGIN` is unset (a laptop,
+ CI, an audit session), so a process that is not a Cloud Run revision (no
+ `K_SERVICE`) and would fan out to a non-loopback origin answers
+ `200 { ok: true, skipped: "not_deployed" }` and fires nothing. Point
+ `PUBLIC_APP_ORIGIN` at a local server to exercise the fan-out for real.
-Related: [circulation engine](#sec-141) ·
-[x402 ring economy](#sec-560) ·
-[economy funding root](#sec-183) · [money map](#sec-294)
+Related: [circulation engine](#sec-145) ·
+[x402 ring economy](#sec-586) ·
+[economy funding root](#sec-189) · [money map](#sec-304)
---
-<a id="sec-183"></a>
+<a id="sec-189"></a>
> **Source:** `docs/economy-master.md` · [↑ table of contents](#table-of-contents)
@@ -47926,7 +49821,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-182) dispatcher (and any external HTTP cron
+[economy heartbeat](#sec-188) dispatcher (and any external HTTP cron
pointed at `/api/cron/economy-tick`) keeps it — and every other cron — ticking.
## Audit, accounting & breach monitoring
@@ -48041,26 +49936,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-560) /
- [autonomous x402](#sec-105)).
+ other engine (see [x402 ring economy](#sec-586) /
+ [autonomous x402](#sec-107)).
## 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-141) — the autonomous agent-to-agent
+- [Circulation engine](#sec-145) — the autonomous agent-to-agent
activity loop the funded engines drive.
-- [x402 ring economy](#sec-560) — closed-loop in-house x402 settlement.
+- [x402 ring economy](#sec-586) — closed-loop in-house x402 settlement.
---
-<a id="sec-184"></a>
+<a id="sec-190"></a>
> **Source:** `docs/economy-solver.md` · [↑ table of contents](#table-of-contents)
# The economy solver
-The [in-game economy reference](#sec-255) publishes **what** the `/play`
+The [in-game economy reference](#sec-265) 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.
@@ -48286,16 +50181,16 @@ deploy.
## Next
-- **[The in-game economy](#sec-255)** is the raw reference: every catalog,
+- **[The in-game economy](#sec-265)** is the raw reference: every catalog,
gate, settlement path and the JSON wire format.
-- **[Earn and spend in /play](#sec-450)** walks the loop
+- **[Earn and spend in /play](#sec-470)** 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-185"></a>
+<a id="sec-191"></a>
> **Source:** `docs/editor.md` · [↑ table of contents](#table-of-contents)
@@ -48644,7 +50539,7 @@ The full contract lives in [specs/EDITOR_SPEC.md](https://github.com/nirholas/th
---
-<a id="sec-186"></a>
+<a id="sec-192"></a>
> **Source:** `docs/education-pilot-bucharest.md` · [↑ table of contents](#table-of-contents)
@@ -48715,7 +50610,7 @@ Status: exploratory. A contact has offered a local connection to the office of t
---
-<a id="sec-187"></a>
+<a id="sec-193"></a>
> **Source:** `docs/embedding.md` · [↑ table of contents](#table-of-contents)
@@ -49452,16 +51347,16 @@ The platform records anonymous embed impressions (country, referrer hostname) vi
## See also
-- [Architecture Overview](#sec-100)
-- [Agent System Overview](#sec-064)
-- [Web Component reference](#sec-523) — full attribute list
-- [Widgets](#sec-526) — Widget Studio and widget types
+- [Architecture Overview](#sec-102)
+- [Agent System Overview](#sec-065)
+- [Web Component reference](#sec-543) — full attribute list
+- [Widgets](#sec-546) — 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-188"></a>
+<a id="sec-194"></a>
> **Source:** `docs/embody.md` · [↑ table of contents](#table-of-contents)
@@ -49564,14 +51459,14 @@ Embody is a thin, honest wire over pieces that already exist — no new pipeline
## Related
-- [Live embodiment](#sec-281) — the 3D Studio tools that persist and drive a body in chat.
-- [x402 Paid Endpoints](#sec-559) — the full paid catalog and pricing.
-- [x402 Buyer Client](#sec-556) — how to settle a 402 challenge from code.
-- [Avatar creation](#sec-109) — generate a rigged avatar in the web UI.
+- [Live embodiment](#sec-290) — the 3D Studio tools that persist and drive a body in chat.
+- [x402 Paid Endpoints](#sec-584) — the full paid catalog and pricing.
+- [x402 Buyer Client](#sec-581) — how to settle a 402 challenge from code.
+- [Avatar creation](#sec-111) — generate a rigged avatar in the web UI.
---
-<a id="sec-189"></a>
+<a id="sec-195"></a>
> **Source:** `docs/erc8004.md` · [↑ table of contents](#table-of-contents)
@@ -49754,7 +51649,7 @@ The registration wizard auto-generates the agent card JSON from your editor stat
### Step 3: Upload to IPFS
-The agent card and GLB are pinned to IPFS to create stable, content-addressed URLs. The platform pins files automatically via its backend storage. If you prefer to pin yourself, you can provide a Pinata JWT token — the system will upload directly to Pinata and return `ipfs://` URLs.
+The agent card and GLB are pinned to IPFS to create stable, content-addressed URLs. The platform pins files automatically via its backend storage. If you prefer to pin yourself, you can provide a Pinata JWT token: the system will upload directly to Pinata and return `ipfs://` URLs. That direct upload is bounded to 60 seconds, and a Pinata failure or timeout falls through to the platform's own pinning route (`/api/erc8004/pin`) rather than failing the registration mid-flow, so the token is a preference, not a requirement.
The GLB auto-thumbnail feature renders a PNG from your 3D model server-side so that NFT marketplaces and social cards display a 2D preview. You can supply your own image instead.
@@ -49942,11 +51837,9 @@ The `<agent-3d>` element boots the full agent runtime — 3D rendering, memory,
### IPFS fallbacks
-The resolver tries multiple IPFS gateways in sequence when fetching metadata:
-1. `ipfs.io`
-2. `dweb.link`
-3. `flk-ipfs.xyz`
-4. `gateway.pinata.cloud`
+`resolveUrl(uri)` turns an `ipfs://` URI into a single URL on the primary gateway (`ipfs.io`). `resolveUrlCandidates(uri)` returns the full ordered chain for the same content, and it no longer keeps a gateway list of its own: it delegates to `uriCandidates()` in [src/ipfs.js](../src/ipfs.js), which owns the one live, dead-host-free list for the whole platform. Today that chain is `ipfs.io` (the primary, kept at the head), then `dweb.link`, `flk-ipfs.xyz`, `w3s.link`, and `nftstorage.link`. `uriCandidates()` also re-extracts the CID from a URL whose gateway was already baked in upstream, so a card that hardcodes one gateway is still rotatable.
+
+The manifest `toManifest(resolved)` builds keeps `image` and `body.uri` as single URLs (nothing that consumes them changes), and alongside them carries `_gatewayCandidates.body` and `_gatewayCandidates.image`: the ordered chain for each, starting with that same single URL. A consumer that can retry (an `<img>` fallback chain, a GLB loader) walks those instead of giving up on one dead gateway.
Arweave (`ar://`) URIs are resolved through `arweave.net`.
@@ -50280,7 +52173,7 @@ The same MAINNET addresses apply to all 15 mainnets. The same TESTNET addresses
---
-<a id="sec-190"></a>
+<a id="sec-196"></a>
> **Source:** `docs/erc8004/validation-attestation.md` · [↑ table of contents](#table-of-contents)
@@ -50364,6 +52257,15 @@ maps to the same request, and a new model always gets its own.
- **Verifying a proof.** `hashReport()` keccaks the report's compact JSON. Fetch
the pinned file, `JSON.stringify(JSON.parse(bytes))`, keccak it, and compare
against the chain's `responseHash`.
+- **One dead RPC never blocks an attestation.** The attestor signs against
+ `evmFallbackProvider(chainId)` from `api/_lib/evm/rpc.js`, a quorum-1
+ fallback over the chain's endpoint list in priority order, so both the reads
+ in step 4 and the broadcast in step 6 go through whichever endpoint answers.
+ On BSC Testnet that list leads with PublicNode, because the bnbchain data-seed
+ nodes refuse every `eth_getLogs` call outright.
+- **The `/validation` dashboard resolves `ipfs://` report links through the
+ shared gateway list** in `src/ipfs.js` (`resolveURI`), the same rotation the
+ rest of the platform uses, rather than one hardcoded gateway.
## Badge states
@@ -50433,7 +52335,7 @@ reported the reverts as "no attestation yet".
---
-<a id="sec-191"></a>
+<a id="sec-197"></a>
> **Source:** `docs/event-readiness/01-play-first-impression.md` · [↑ table of contents](#table-of-contents)
@@ -50477,7 +52379,7 @@ What you changed (files + one line each), what you verified in-browser, anything
---
-<a id="sec-192"></a>
+<a id="sec-198"></a>
> **Source:** `docs/event-readiness/02-play-mobile.md` · [↑ table of contents](#table-of-contents)
@@ -50513,7 +52415,7 @@ Root cause of any crash found (with the harness evidence), fixes applied, remain
---
-<a id="sec-193"></a>
+<a id="sec-199"></a>
> **Source:** `docs/event-readiness/03-play-performance.md` · [↑ table of contents](#table-of-contents)
@@ -50555,7 +52457,7 @@ Numbers table (before/after), each fix in one line, anything intentionally skipp
---
-<a id="sec-194"></a>
+<a id="sec-200"></a>
> **Source:** `docs/event-readiness/04-play-multiplayer-net.md` · [↑ table of contents](#table-of-contents)
@@ -50575,11 +52477,11 @@ The event means many strangers in one world at once. Connection handling has to
## What to audit
1. **Join path.** Time from page load to seeing other players. Any handshake failure must surface a designed, actionable error (what happened + retry button), never an empty world that looks single-player when it silently failed.
-2. **Reconnect.** Kill the socket mid-session (devtools offline toggle, 10s, then online). The client must reconnect automatically, resync player positions, and show a subtle "reconnecting" indicator while it does. State after resync must match the server (no ghost players, no duplicated self).
+2. **Reconnect.** Kill the socket mid-session (devtools offline toggle, 10s, then online). The client must reconnect automatically, resync player positions, and show a subtle "reconnecting" indicator while it does. State after resync must match the server (no ghost players, no duplicated self). Note `community-net.js` already reconnects with backoff: the attempt counter resets on every successful join, so `MAX_RECONNECT_ATTEMPTS` (14, about 11 minutes with the once-a-minute tail) bounds one outage and rides out a server redeploy before parking on `offline` with the manual `retry()`; a holder-gate refusal from `onAuth` is terminal and routes back to the gate instead of looping. A failed connect logs at info through the gated logger, not as a console warning. The boot watchdog in `pages/play.html` deliberately ignores a WebSocket-shaped rejection, so a flaky reconnect never trips the "could not load the world" card.
3. **Backgrounding.** Switch tabs for 2 minutes and come back. Mobile Safari will have frozen the socket: same reconnect path must handle it.
4. **Two-client consistency.** Open two browser contexts in the same coin world. Movement, chat, and emotes must appear on the other client within a human-imperceptible delay. Check name labels, avatar appearance, and cosmetics sync both ways.
5. **Chat hygiene.** Long messages wrap, links do not inject HTML (verify escaping), spam has some throttle, and the log does not grow unbounded in memory.
-6. **Voice.** If `voice-chat.js` is surfaced in the UI, test the full path: permission prompt, mute state visible to others, teardown on leave. If it is broken and unfixable today, hide the entry point rather than shipping a dead button.
+6. **Voice.** `voice-chat.js` is surfaced (lazy-imported by `coincommunities.js` behind the HUD voice button), so test the full path: permission prompt, mute state visible to others, teardown on leave. Two hardening points to keep intact: a denied mic closes the `AudioContext` it just opened (browsers cap concurrent contexts, so leaking one per refusal made voice permanently unopenable), and an already-connected peer holds two ranks of hysteresis past `MAX_VOICE_PEERS` before it is dropped, so a crowd cannot churn WebRTC handshakes frame to frame. If it is broken and unfixable today, hide the entry point rather than shipping a dead button.
7. **Scale behavior.** Simulate a crowded room (multiple headless Playwright contexts, or whatever the net layer allows). Watch for O(n^2) update patterns and per-player DOM label churn.
8. **Mobile memory.** A phone that runs out of memory does not throw a JS error: the browser kills the tab, the socket dies mid-session, and the page reloads. In the server log that reads as a join followed by a leave a few seconds later, over and over, which looks like a networking bug and is not one. Watch the bytes, not the console. `scripts/play-mobile-repro.mjs` drives a phone-emulated /play session and prints every download attributed to the code that asked for it (`ENGINE=chromium node scripts/play-mobile-repro.mjs https://three.ws/play 120000`). Anything that loads community-uploaded models must work to a budget: the gallery is uncapped and single avatars there reach 24 MB. `src/game/ambient-crowd.js` holds the reference implementation (per-model cap, per-visit download cap, load-once-and-clone, release on leave).
@@ -50595,7 +52497,7 @@ Each failure mode tested and its result (pass / fixed / cannot-fix-with-reason).
---
-<a id="sec-195"></a>
+<a id="sec-201"></a>
> **Source:** `docs/event-readiness/05-play-economy-loops.md` · [↑ table of contents](#table-of-contents)
@@ -50612,13 +52514,13 @@ The world's stickiness is its loops: gather, fight, trade, spin, buy cosmetics.
- Quests: `src/game/quests-ui.js`
- Cosmetics: `src/game/cosmetics-shop.js`, `cosmetics-purchase.js`, `cosmetics-loadout.js`, `cosmetics-wardrobe.js`, `cosmetics-flex.js`
- Items and persistence: `src/game/items.js`, `src/game/world-persist.js`
-- Published economy pages (must agree with the game): `/play/economy` and `/play/solver` (routes in `vercel.json`; both read from the same tables the game server prices with, so a mismatch means one side drifted)
+- Published economy pages (must agree with the game): `/play/economy` and `/play/solver` (routes in `vercel.json`; `api/play/economy.js` imports every number from the same modules WalkRoom prices with, `multiplayer/src/{shop,items,cosmetics-catalog,spin-wheel,economy}.js`, so nothing is transcribed and a mismatch means one side drifted)
## What to audit
1. **Every loop end to end, with a real signed-in session.** Gather from a tree/rock/pond, sell at the store, bank cash, die and confirm the bank protected it, spin the wheel, complete a quest, buy and equip a cosmetic. Each step: correct payout, correct balance update in the HUD without a refresh, correct persistence across a reload.
2. **Price truth.** Cross-check a sample of prices shown in-game against `/play/economy`. Any disagreement is a bug; find which side is stale.
-3. **The $THREE boutique.** The cosmetics boutique charges $THREE: verify the full purchase path including insufficient-balance handling (clear message + how to get $THREE, never a silent failure or a raw error toast).
+3. **The $THREE boutique.** The cosmetics boutique charges $THREE: verify the full purchase path including insufficient-balance handling (clear message + how to get $THREE, never a silent failure or a raw error toast). `boutique-purchase.js` already maps a short balance to "Not enough $THREE (or SOL for network fees) for this purchase. Get $THREE at three.ws/three-token, then try again.", times out a quote that never arrives, and only unlocks the item after the server's settle notice, never on the client's own "it worked"; verify that path holds rather than rebuilding it.
4. **Race and double-spend.** Double-click every buy/spin/sell button fast. Balances must never go negative or double-charge; buttons must disable while a request is in flight.
5. **Edge cases.** 0 inventory, full inventory, extremely long item names, network failure mid-purchase (the UI must reconcile with server state on reconnect, not trust its optimistic update).
6. **Progression feel.** XP and skill levels visible, level-ups celebrated (even minimally), next-unlock always discoverable. If a loop pays out but gives no feedback (no sound/flash/toast), add the feedback; silent success reads as broken.
@@ -50636,7 +52538,7 @@ Loop-by-loop pass/fixed table, every price mismatch found and which side you cor
---
-<a id="sec-196"></a>
+<a id="sec-202"></a>
> **Source:** `docs/event-readiness/06-play-auth-errors.md` · [↑ table of contents](#table-of-contents)
@@ -50648,17 +52550,17 @@ Event visitors will arrive signed out, with ad blockers, on flaky wifi, with wal
- Auth flow: `src/game/play-auth.js`, `src/game/play-gate.js`, `src/game/play-handoff.js`
- World boot (error surfaces): `src/game/coincommunities.js`, `src/game/boot-avatar.js`
-- QA credentials for authed testing: `AUDIT_EMAIL` / `AUDIT_PASSWORD` in `.env` (a real production QA account); sweeps via `npm run audit:web` (anon) and `npm run audit:web:login` (authed)
+- QA credentials for authed testing: `AUDIT_EMAIL` / `AUDIT_PASSWORD` in `.env` (a real production QA account); sweeps via `npm run audit:web` (anon) and `npm run audit:web:login` (authed). Both take route paths as arguments to scope the sweep (`npm run audit:web -- /play`) and `--engine webkit` or `--engine firefox` to run it in Safari's or Firefox's engine instead of Chromium (`npx playwright install webkit` once)
## What to audit
1. **Signed-out experience.** Load the canonical $THREE URL (see `docs/event-readiness/README.md`) with no session. How much of the world is explorable before a gate appears? The gate itself: is it an invitation (clear value, one-tap sign-in) or a wall? Fix toward invitation.
2. **Sign-in mid-session.** Complete wallet sign-in from inside the world. The session must hand off without losing position or reloading the page if the flow supports it; if it must reload, state must restore.
-3. **Session expiry.** Expire the session (clear the cookie/token) while playing, then perform an authed action (buy, bank). The user gets a re-auth prompt that resumes the action afterward, not a generic failure.
+3. **Session expiry.** Expire the session (clear the cookie/token) while playing, then perform an authed action (buy, bank). The user gets a re-auth prompt that resumes the action afterward, not a generic failure. Note `play-gate.js` now reads the cached play pass first on boot, and reading is how it is reaped: `loadStoredPass()` drops an expired or corrupt entry before either early exit (config probe failing open, gate off for this world), so a dead token no longer outlives the boot and gets handed to a room join the server can only refuse.
4. **Every fetch boundary.** Grep the play modules for `fetch(`/net calls and check each one handles rejection and non-2xx with a user-visible, actionable state. Internal code trusts itself; boundaries do not.
-5. **Asset failures.** Block the IPFS coin image and one GLB in devtools. The world must render with fallbacks (placeholder texture, default rig per the `AnimationManager.supportsCanonicalClips()` gate), never a T-pose or an invisible avatar.
+5. **Asset failures.** Block the IPFS coin image and one GLB in devtools. The world must render with fallbacks (placeholder texture, default rig per the `AnimationManager.supportsCanonicalClips()` gate), never a T-pose or an invisible avatar. A blocked or missing avatar GLB is a designed path in `boot-avatar.js`: it releases the loader, styles the card for the no-avatar case, and logs at info through the gated logger, so it costs a decoration, never the boot and never a console warning.
6. **Bad query strings.** /play with no params, a garbage `coin=`, an XSS attempt in `name=`/`symbol=` (must render escaped, never execute), and an oversized `image=` URL. Each gets a sane default world or a designed error, and never script execution.
-7. **Console zero.** `npm run audit:console` scoped to /play, plus a manual pass. Zero errors, zero warnings from our code, on both anon and authed runs.
+7. **Console zero.** `npm run audit:console -- /play` (route paths passed as arguments scope the sweep; `--desktop` or `--mobile` picks one viewport), plus a manual pass. Zero errors, zero warnings from our code, on both anon and authed runs.
## Verify
@@ -50672,7 +52574,7 @@ A failure-mode table: scenario, what happened before, what happens now. Call out
---
-<a id="sec-197"></a>
+<a id="sec-203"></a>
> **Source:** `docs/event-readiness/07-platform-smoke-sweep.md` · [↑ table of contents](#table-of-contents)
@@ -50685,7 +52587,7 @@ Event visitors will not stay on /play; they will click around. Every page declar
Run these against production first to find real user-facing breakage, then against `npm run dev` to fix:
- `npm run smoke:prod`: sweeps every page in `data/pages.json` against the live site.
-- `npm run audit:web`: unauthenticated browser sweep. `npm run audit:web:login`: authed sweep using the QA account (`AUDIT_EMAIL`/`AUDIT_PASSWORD` in `.env`).
+- `npm run audit:web`: unauthenticated browser sweep. `npm run audit:web:login`: authed sweep using the QA account (`AUDIT_EMAIL`/`AUDIT_PASSWORD` in `.env`). Both accept route paths as arguments to narrow the sweep and `--engine webkit` or `--engine firefox` to run it outside Chromium (`npx playwright install webkit` once); a WebKit run counts one failed resource as one finding, not three. `npm run ui:review` is the visual sweep over the same route list.
- `npm run audit:links`: dead links. `npm run audit:pages` and `npm run check:pages`: pages.json integrity.
- `npm run audit:console`: console errors per page. `npm run audit:overlays`, `npm run audit:inline-handlers`, `npm run audit:routes`, `npm run audit:route-shadowing`: overlay/handler/route health.
- `npm run audit:docs`: dead doc links and commands naming scripts that no longer exist.
@@ -50723,7 +52625,7 @@ Battery results before and after, fixes grouped by page, the manual event-funnel
---
-<a id="sec-198"></a>
+<a id="sec-204"></a>
> **Source:** `docs/event-readiness/08-api-production-health.md` · [↑ table of contents](#table-of-contents)
@@ -50754,7 +52656,7 @@ Solana-first status summary, then the 8 items with their binary states, then log
---
-<a id="sec-199"></a>
+<a id="sec-205"></a>
> **Source:** `docs/event-readiness/09-accessibility-i18n.md` · [↑ table of contents](#table-of-contents)
@@ -50790,7 +52692,7 @@ Per-category pass/fixed list, the keyboard-only session result, locales verified
---
-<a id="sec-200"></a>
+<a id="sec-206"></a>
> **Source:** `docs/event-readiness/10-event-day-runbook.md` · [↑ table of contents](#table-of-contents)
@@ -50828,34 +52730,34 @@ Old/new scaling values, capacity smoke numbers, rollback rehearsal result, and t
---
-<a id="sec-201"></a>
+<a id="sec-207"></a>
> **Source:** `docs/event-readiness/11-event-live-ops.md` · [↑ table of contents](#table-of-contents)
# Feature 11: live event ops (broadcast, stage moments, event config)
-Tomorrow the $THREE world hosts a live event. The countdown already exists (`src/game/event-countdown.js` reads `public/event.json` and mounts a lobby banner + in-world pill). What is missing is the live layer: a way for the operator to speak to everyone in the world at once, and for the world to visibly react when the event goes live. Build it end to end.
+Tomorrow the $THREE world hosts a live event. The countdown already exists (`src/game/event-countdown.js` reads `public/event.json` through the shared `src/shared/event-config.js` reader and mounts a lobby banner + in-world pill). The live layer has since shipped in two of its three parts: the operator can speak to everyone in the world at once (`/internal/announce` + `scripts/announce-play.mjs`), and the world reacts when the event goes live (`src/game/meetup-event.js` agenda beats, go-live banner, and `src/game/fireworks.js`; the walkthrough is [docs/play-live-events.md](#sec-352)). What is still missing is item 3, changing the event config without a redeploy. The list below records what exists so a rerun builds only the gap.
## Where the code lives
-- Event config + countdown: `public/event.json`, `src/game/event-countdown.js` (self-attaching, zero edits to the core modules; keep that pattern)
-- Multiplayer server (in-repo): `multiplayer/src/rooms/WalkRoom.js`, `multiplayer/src/social-hub.js`; client socket + event bus: `src/game/community-net.js`
+- Event config + countdown: `public/event.json`, `src/game/event-countdown.js` (self-attaching, zero edits to the core modules; keep that pattern). The same file is read by the home strip (`src/home-event-banner.js`), the API (`api/_lib/event-config.js`, from disk, cached a minute) and the game server (`multiplayer/src/event-window.js`, polled over HTTP every minute). Between events it holds an explicit no-event state (`id: null`) so `/event.json` still answers 200; edit it only through `npm run event:schedule -- --start <ISO> --duration <minutes> --apply` (`--rehearse 10` for a local dry run, `--clear` to reset) and gate the deploy on `npm run check:event`
+- Multiplayer server (in-repo): `multiplayer/src/rooms/WalkRoom.js`, `multiplayer/src/social-hub.js`, the announce webhook in `multiplayer/src/index.js`; client socket + event bus: `src/game/community-net.js`
- In-world screens for takeover moments: `src/game/x402-jumbotron.js`, `src/game/chart-screen.js`
- Celebration FX precedent: the reaction-bar confetti in `src/game/coincommunities-ui.js`
- Admin/API patterns: look at existing authed admin endpoints under `api/` before inventing a new auth scheme
## What to build
-1. **Operator broadcast.** An authed API endpoint (follow the repo's existing admin-auth pattern; never an open endpoint) that pushes an announcement through the Colyseus room to every connected player in a given coin world (or all worlds). Client side: a distinct, high-visibility announcement banner in the HUD, auto-dismissing, queued if several arrive. Server-side rate limit so a bad script cannot spam every player.
-2. **Go-live moment.** When `event.json` flips to live (the countdown module already computes the state), the world marks it: jumbotron takeover with the event name, a one-shot celebration burst, and the countdown pill switching to its pulsing LIVE state. All of it must degrade to nothing when there is no event.
-3. **Event config hardening.** `event.json` is baked into the image at build time, which means a config change mid-event needs a redeploy. Add a small authed read path (for example an `app_settings`-backed override checked after the static file) so the operator can extend, rename, or end the event live without a deploy. Document the exact curl in the runbook (`10-event-day-runbook.md`).
-4. **Broadcast script.** A `scripts/` helper the operator runs from this workspace: takes a message, calls the endpoint, prints how many players received it.
+1. **Operator broadcast.** Shipped as `POST /internal/announce` on the multiplayer server (`multiplayer/src/index.js`): HMAC-signed with `MULTIPLAYER_SHARED_SECRET` (falling back to `HOLDER_PASS_SECRET`) and timestamp-bound, so an unsigned or stale call is rejected before it reaches a room; there is no separate rate limit, the signature is the gate. It broadcasts on the existing `notice` channel (`kind: 'event'`, text capped at 300 characters, optional `title` 80 and `detail` 200, `durationMs` capped at 120 s) to every live `walk_world` room or one coin's world, so older clients get a toast and newer ones the centre-screen banner. Verify the banner queues, dismisses, and never overlaps chat or the joystick.
+2. **Go-live moment.** Shipped in `src/game/meetup-event.js` (agenda, go-live banner) and `src/game/fireworks.js`, on the countdown pill's pulsing LIVE state. Everything reads the one config and mounts nothing when there is no event; keep it that way.
+3. **Event config hardening.** Still open. `event.json` is baked into the image at build time, which means a config change mid-event needs a redeploy (today: `npm run event:schedule -- ... --apply`, `npm run check:event`, then the deploy runbook). Add a small authed read path (for example an `app_settings`-backed override checked after the static file, in `api/_lib/event-config.js` and `multiplayer/src/event-window.js` alike, since both read the file independently) so the operator can extend, rename, or end the event live without a deploy. Document the exact curl in the runbook (`10-event-day-runbook.md`).
+4. **Broadcast script.** Shipped as `scripts/announce-play.mjs` (`node scripts/announce-play.mjs --title "Wheel hour" --detail "..." --coin <mint> --duration-ms 30000 "message"`; `--server http://localhost:2567` for a local test). It prints how many rooms and players it reached; the operator copy is in [LIVE-OPS.md](#sec-221).
## Verify
- Two browser windows on `npm run dev` joined to the same coin world: a broadcast reaches both within a second; the banner queues, dismisses, and never overlaps the chat panel or mobile joystick.
- `event.json` state transitions (upcoming, live, over) exercised by editing the local file; nothing mounts when it is absent.
-- `npm test` green; add tests for the broadcast endpoint's auth and rate limit.
+- `npm test` green; the broadcast endpoint's unsigned-call refusal is covered in `tests/multiplayer-server-boot.test.js`; add tests for the config override's auth.
## Report format
@@ -50863,7 +52765,7 @@ What shipped (files + one line each), the exact operator commands for event day,
---
-<a id="sec-202"></a>
+<a id="sec-208"></a>
> **Source:** `docs/event-readiness/12-photo-mode-share.md` · [↑ table of contents](#table-of-contents)
@@ -50899,7 +52801,7 @@ Files shipped, a saved sample capture path, what the share flow does per platfor
---
-<a id="sec-203"></a>
+<a id="sec-209"></a>
> **Source:** `docs/event-readiness/13-event-quests-leaderboard.md` · [↑ table of contents](#table-of-contents)
@@ -50935,7 +52837,7 @@ The quest list as players will see it, files shipped, the leaderboard endpoint U
---
-<a id="sec-204"></a>
+<a id="sec-210"></a>
> **Source:** `docs/event-readiness/14-welcome-concierge.md` · [↑ table of contents](#table-of-contents)
@@ -50945,8 +52847,8 @@ Most event visitors will be first-timers landing from one shared link. The onboa
## Where the code lives
-- NPC layer: `src/game/npc/npc.js`, `npc-catalog.js`, `npc-chat.js` (already talks to `/api/brain/chat`), `nav-graph.js` (pathing), `economy-npcs.js` for placement precedent
-- Onboarding today: `src/game/play-onboard.js` (3-step overlay); intro card: `src/game/play-intro.js`
+- NPC layer: `src/game/npc/npc.js`, `npc-catalog.js`, `npc-chat.js` (already talks to `/api/brain/chat`), `nav-graph.js` (pathing), `economy-npcs.js` for placement precedent, and `citizens.js` / `world-life.js` (every ambient walker is now a real citizen you can open and talk to; the closest precedent for a greeter that approaches once). Mind the chat gate: `/api/brain/chat` clamps a signed-out caller to the free providers under an anonymous rate limit and answers 401 for the paid first-party models, so the concierge persona must pin a free provider or first-timers get a sign-in wall instead of a welcome
+- Onboarding today: `src/game/play-onboard.js` (3-step overlay; its control list is data with an `essential` flag, so a tour stop that teaches a key should reference that list rather than restate it); intro card: `src/game/play-intro.js`
- Landmarks worth touring: the stations from `src/game/play-activities.js`, the chart jumbotron (`chart-screen.js`), the cosmetics boutique, the intel kiosk
- First-visit detection: the same localStorage signals `play-onboard.js` uses
@@ -50970,7 +52872,7 @@ Files shipped, the persona prompt location, the tour stops, what the concierge s
---
-<a id="sec-205"></a>
+<a id="sec-211"></a>
> **Source:** `docs/event-readiness/15-live-hype-feed.md` · [↑ table of contents](#table-of-contents)
@@ -50980,9 +52882,9 @@ A live world should feel alive even when you just stand there. The market alread
## Where the code lives
-- Market-to-world FX: `src/game/market-reactor.js`; trade feeds: `src/game/chart-screen.js` (`/api/pump/coin-trades`, `/api/robinhood/coin-trades` for hoodchain worlds)
+- Market-to-world FX: `src/game/market-reactor.js` (it already detonates a beam over the totem on a whale-sized trade, so the hype moment extends that hook rather than adding a second one); trade feeds: `src/game/chart-screen.js` (`/api/pump/coin-trades`, `/api/robinhood/coin-trades` for hoodchain worlds). The chart badge now has a `stale` state after three consecutive failed polls, with the tape's age drawn under it: the ticker must go quiet on a stale tape, never celebrate from it. `api/robinhood/coin-trades.js` drops a malformed firehose event instead of 500ing the poll, so a quiet ticker means a quiet market, not a dead feed
- Player joins/leaves: the Colyseus room state in `src/game/community-net.js` (the HUD online count already consumes it)
-- In-world purchases worth celebrating: cosmetics buys, wheel wins, x402 payments (`agent-commerce.js`, `x402-jumbotron.js`)
+- In-world purchases worth celebrating: cosmetics buys, wheel wins, x402 payments (`agent-commerce.js`, `x402-jumbotron.js`); war results already reach the platform feed as `war-result` events (`multiplayer/src/feed.js`) and the war portal holds a 9 s win takeover on its board (`HYPE_MS` in `src/game/war-portal.js`), the nearest precedent for a hype moment with a cooldown
- HUD layer + toast precedent: `src/game/coincommunities-ui.js`, styles in `src/game/coincommunities.css`
## What to build
@@ -51004,7 +52906,7 @@ Files shipped, the threshold logic in two sentences, measured DOM/node behavior
---
-<a id="sec-206"></a>
+<a id="sec-212"></a>
> **Source:** `docs/event-readiness/16-invite-flow.md` · [↑ table of contents](#table-of-contents)
@@ -51014,10 +52916,10 @@ Everyone at the event arrives through one link, and everyone who has fun should
## Where the code lives
-- Deep-link contract: `coinWorldUrl()` (tested in `tests/fits-lib.test.js`); canonical URL emission in `src/game/coincommunities.js` (`history.replaceState` on entry)
-- OG image for /play links: `api/play-og.js`; house OG patterns: `api/page-og.js`, `api/og-leaderboard.js`
-- HUD mount + share precedent: `src/game/coincommunities-ui.js` and the build-share sheet
-- QR: check `package.json` for an existing QR dependency first (open-source-first rule); a tiny well-maintained encoder is fine if none exists, no heavyweight additions
+- Deep-link contract: `coinWorldUrl()` in `src/fits-lib.js` (tested in `tests/fits-lib.test.js`); canonical URL emission in `src/game/coincommunities.js` (`history.replaceState` in `enter()`, which keeps exactly `coin`, `name`, `symbol`, `image`, `tier` for a holders world, and `ui`; a bare `coin` link now resolves its name, symbol and image through `_fetchCoinIdentity` before the rewrite, so the canonical link is always complete)
+- OG image for /play links: `api/play-og.js` (GET-only since the fleet hardening pass; any other verb is refused before the satori render); house OG patterns: `api/page-og.js`, `api/og-leaderboard.js`
+- HUD mount + share precedent: `src/game/coincommunities-ui.js` and the build-share sheet. Do not confuse this with the friend invites in `src/game/friends-panel.js`, which are a social-graph request, not a world link
+- QR: `qrcode` is already a dependency (`src/wallet-deposit.js` and `src/marketplace.js` render with it); use it, no new encoder
## What to build
@@ -51038,26 +52940,26 @@ Files shipped, any dependency added (name, weekly downloads, license, why), a re
---
-<a id="sec-207"></a>
+<a id="sec-213"></a>
> **Source:** `docs/event-readiness/17-plaza-live-show.md` · [↑ table of contents](#table-of-contents)
# Feature 17: live hosted show on a plaza stage inside /play
-The platform already has Living Stages: an embodied AI host runs a real-time show with spatial voice, lip-sync, synced captions, an audience question queue, and a verified on-chain $THREE tip leaderboard where a tip pre-empts the host's next line in about a second. All of it works, and none of it is reachable from the world: `grep -r stage src/game/` finds zero references. Put a stage in the $THREE plaza and let the event crowd attend a show without leaving /play.
+The platform already has Living Stages: an embodied AI host runs a real-time show with spatial voice, lip-sync, synced captions, an audience question queue, and a verified on-chain $THREE tip leaderboard where a tip pre-empts the host's next line in about a second. All of it works, and none of it is reachable from the world yet. Half of this build has landed: `src/game/plaza-stage.js` is the landmark (platform, canvas marquee via `screen-texture.js`, a proximity gate, a 45 s show-state poll while a player is near), `multiplayer/src/plaza-stage.js` derives the stage id, `PLAZA_STAGE` in `multiplayer/src/world-features.js` is the server-validated footprint, and `api/stage/index.js` answers `GET /api/stage?coin=<mint>` and claims a plaza with `POST /api/stage { action: 'plaza', agentId, coinMint }`. But nothing imports `plaza-stage.js` (`coincommunities.js` never mounts it), and the show client it dynamically imports on first proximity, `src/game/plaza-stage-show.js`, does not exist. Finish it: mount the landmark and write the show client so the event crowd can attend a show without leaving /play.
## Where the code lives
- Show engine (server): `multiplayer/src/rooms/StageRoom.js`, `multiplayer/src/stage-show.js` (the pure `ShowDirector` with beats OPENER, TIP_SHOUTOUT, ANSWER, BANTER, GAME), `multiplayer/src/stage-schemas.js`, `multiplayer/src/stage-registry.js`. Room registered as `stage_world` with `filterBy(['stageId'])` in `multiplayer/src/index.js`
- Show client (page-level, reuse it): `src/stage.js`, `src/stage-net.js`, `src/stage-element.js`, served at `pages/stage.html`
-- Show API: `api/stage/index.js` (directory, create, golive, endshow, `nextShowAt` scheduling), `api/stage/host.js` (the host's words), `api/stage/tip.js` (on-chain verified, idempotent per signature); host voice via `api/tts/speak`
+- Show API: `api/stage/index.js` (directory, create, golive, endshow, `nextShowAt` scheduling, plus the `?coin=` read and the `plaza` claim; one `stageDetail()` serves the `?id=` and `?coin=` reads so /stage and the plaza never see two shapes of the same show), `api/stage/host.js` (the host's words; the prompt names $THREE as the only coin the host may mention, and `sanitizeLine` strips control characters and dashes from every spoken line before it becomes a caption), `api/stage/tip.js` (on-chain verified, idempotent per signature); host voice via `api/tts/speak`
- The world to mount into: `src/game/coincommunities.js` (main scene), landmark placement precedent in `src/game/wheel-station.js` and `src/game/home-town.js`; server-validated landmark coordinates in `multiplayer/src/world-features.js`
- Multiplayer client for the world room: `src/game/community-net.js` (Colyseus `walk_world`); the stage join is a second, concurrent room connection
## What to build
-1. **The stage landmark.** A real stage structure in the $THREE world plaza: platform, backdrop, marquee screen. The marquee shows the show state from `api/stage/index.js`: live now, next show time (`nextShowAt`), or a designed idle state. Register its footprint in `world-features.js` so the server can validate proximity.
-2. **Proximity attendance.** Walking near the stage joins the coin's `stage_world` room alongside the existing `walk_world` connection (derive `stageId` from the mint deterministically). Reuse `stage-net.js` and the utterance rendering from the stage client rather than rewriting: the host avatar on stage speaks with TTS voice, lip-sync, and captions, synced across every attendee. Walking away leaves the stage room cleanly.
+1. **The stage landmark.** Built in `src/game/plaza-stage.js` but not mounted: construct it from `coincommunities.js` next to the wheel station and the war portal. The marquee already reads the show state from `GET /api/stage?coin=`: live now, next show time (`nextShowAt`), or a designed idle state. The footprint is `PLAZA_STAGE` at (18, 26) with a 5 m radius in `world-features.js`, sized to contain the golden-angle seat ring StageRoom deals out (6.0/7.6/9.2 m from the stage origin).
+2. **Proximity attendance.** Walking near the stage joins the coin's `stage_world` room alongside the existing `walk_world` connection. `stageId` is already derived: `plazaStageId(mint)` in `multiplayer/src/plaza-stage.js` is uuidv5 of the mint, which is both the `stage_world` `filterBy` key and the `stages.id` a plaza claim writes, so client and server agree offline. Write `src/game/plaza-stage-show.js` (the module `plaza-stage.js` lazy-imports on first proximity) around `stage-net.js` and the utterance rendering from the stage client rather than rewriting: the host avatar on stage speaks with TTS voice, lip-sync, and captions, synced across every attendee. Walking away (past `LEAVE_HYSTERESIS_M`, 3 m beyond the edge) leaves the stage room cleanly.
3. **Audience presence.** Attendees get the server-assigned ring seats StageRoom already deals out, rendered as marked spots in front of the stage; the question queue is reachable from the in-world chat bar while attending.
4. **Tips in-world.** A tip action at the stage that runs the existing `api/stage/tip.js` flow (this is an on-chain $THREE spend: render recipient, amount, and token and get the user's explicit confirmation before signing, every time). The tip leaderboard renders on the marquee, and a landed tip pre-empts the host beat exactly as it does on /stage.
5. **Cost discipline.** Everything here mounts lazily on first proximity and fully unmounts when the show is over and the player leaves. No stage room connection, no TTS fetches, no per-frame work for players who never approach. When no show exists and none is scheduled, the stage is a quiet decorated landmark, not an error.
@@ -51075,29 +52977,30 @@ Files shipped, how `stageId` is derived, the join and teardown lifecycle in thre
---
-<a id="sec-208"></a>
+<a id="sec-214"></a>
> **Source:** `docs/event-readiness/18-coin-wars-portal.md` · [↑ table of contents](#table-of-contents)
# Feature 18: Coin Wars portal inside the world
-Coin Wars is finished and invisible. `ClashRoom` runs full community-vs-community battles (lobby, countdown, live, sudden death, kill cap, round clock) with an Elo league behind it, but the only door is the standalone page at /play/arena. Nobody standing in the $THREE world knows wars exist. Build the portal: see the standings, queue for a war, and come back with the result, all from inside /play.
+Coin Wars is finished and, since the portal landed, visible. `ClashRoom` runs full community-vs-community battles (lobby, countdown, live, sudden death, kill cap, round clock) with an Elo league behind it, the arena is a real page at /play/war, and every coin world's plaza has a war portal (`src/game/war-portal.js`, constructed by `coincommunities.js`) to see the standings, queue for a war, and come back with the result without leaving /play. The player-facing walkthrough is [docs/coin-wars.md](#sec-150). This prompt is now the spec to verify against and extend, not a blank build.
## Where the code lives
-- Server: `multiplayer/src/rooms/ClashRoom.js` (registered as `clash_arena` with `filterBy(['matchKey'])` in `multiplayer/src/index.js`), match logic in `multiplayer/src/clash.js`, league in `multiplayer/src/war-standings.js`, summaries in `multiplayer/src/war-report.js`, schemas in `multiplayer/src/clash-schemas.js`
-- Arena client to hand off to: `pages/play/arena.html`, `src/play/arena.js`, `src/play/arena-world.js` (read how it resolves `matchKey` and gates entry before inventing anything)
+- Server: `multiplayer/src/rooms/ClashRoom.js` (registered as `clash_arena` with `filterBy(['matchKey'])` in `multiplayer/src/index.js`), match logic in `multiplayer/src/clash.js`, league in `multiplayer/src/war-standings.js`, summaries in `multiplayer/src/war-report.js`, schemas in `multiplayer/src/clash-schemas.js`, pairing in `multiplayer/src/war-matchmaking.js` and live-war state in `multiplayer/src/war-live.js`
+- Public API: `api/wars.js` (`GET /api/wars?coin=` for the board, `?action=live` for the spectator poll, `POST ?action=queue` and `?action=leave` for the queue, `POST ?action=report` for the game server's HMAC-signed result), backed by `api/_lib/wars-store.js` and the signed war ticket in `api/_lib/war-ticket.js`. Standings are folded from the battle ledger by `war-standings.js`, the same module the arena uses, never recomputed
+- Arena client the portal hands off to: `pages/play/war.html`, `src/play/war.js`, `src/play/war-world.js` (ClashRoom is authoritative; the client renders and sends intent). `/play/arena` (`src/play/arena.js`, `arena-world.js`) is the Sniper Arena, the AI-agent trading floor, not Coin Wars; do not route war traffic there
- Gating: the same holder pass as the Holders world (`multiplayer/src/holder-pass.js`, `api/community/holder-pass.js`)
-- World mount: landmark precedent in `src/game/wheel-station.js`; jumbotron precedent in `src/game/chart-screen.js`; live feed producer `multiplayer/src/feed.js`
-- Deep-link return path: the canonical URL emission in `src/game/coincommunities.js` (`history.replaceState` on entry)
+- World mount: the portal in `src/game/war-portal.js` follows the landmark precedent in `src/game/wheel-station.js` and the canvas-board precedent in `src/game/chart-screen.js`; live feed producer `multiplayer/src/feed.js` (`war-result` is an allowed event type)
+- Deep-link return path: the canonical URL emission in `src/game/coincommunities.js` (`history.replaceState` in `enter()`)
## What to build
-1. **The portal landmark.** A war portal structure in the plaza with a board showing real league state: this coin's Elo standing, recent war results (`war-report.js` output), and any war currently live. If the standings surface has no public API yet, expose one thin read endpoint under `api/` that serves exactly what the arena client already trusts; do not fork the math.
-2. **Queue from the world.** An "enter the war" interaction that runs the same gate the arena page runs (holder pass where required), resolves the `matchKey` the same way, and hands off to `/play/arena` with a return link that carries the full coin identity (`coin`, `name`, `symbol`, `image`) so coming back lands in the same world with no lobby detour.
-3. **Spectate without leaving.** While a war involving this coin is live, the portal's board becomes a spectator screen: live score, kill feed, round clock, sourced from the clash room state or a cheap polling read. Text and numbers, not a second 3D render.
-4. **Results echo.** When a war ends, the result lands in the world: a feed event through `multiplayer/src/feed.js` and a short jumbotron moment for a win. If Feature 15's ticker landed, the result appears there too.
-5. **Honest empty states.** No wars yet, standings empty, matchmaking quiet: each state says what it is and what a player can do about it, in the designed style of the lobby's retry cards.
+1. **The portal landmark.** Shipped: the board in `war-portal.js` paints this coin's league row, recent battles, and any live war from `GET /api/wars`. Idle cost is zero by design: nothing is fetched until a player is inside the board's legibility ring (`WAR_PORTAL_BOARD_REACH`), the slow poll runs while someone idles near it, and the fast poll only while a war involving this coin is live, the panel is open, or the community is queued. Verify those cadences hold; do not add a second fetch path.
+2. **Queue from the world.** Shipped: E at the portal runs the holder gate, `POST /api/wars?action=queue` pairs the community with a waiting one and returns the `matchKey` plus a signed war ticket (ClashRoom takes both competing communities from the ticket, never from a joining client), and the handoff goes to `/play/war` with a return link carrying `coin`, `name`, `symbol`, `image` so coming back lands in the same world with no lobby detour. Verify the round trip both ways.
+3. **Spectate without leaving.** Shipped: while a war involving this coin is live the board becomes a scoreboard (score, round clock, kill feed) off the `?action=live` poll, text and numbers only, with the same numbers in the panel's spectator card.
+4. **Results echo.** Partly shipped: the game server reports the result through `POST /api/wars?action=report`, `war-result` events go out through `multiplayer/src/feed.js`, and a win holds a 9 s takeover on the board (`HYPE_MS`). Still open: a jumbotron moment on the chart screen, and a ticker row if Feature 15 lands.
+5. **Honest empty states.** Shipped for the unranked community, the empty battle log, the unreachable ledger, and the empty kill feed (each says what it is and what to do, e.g. "No wars fought yet. Press E to queue this community, the arena opens as soon as a second one does."). Verify each still renders in the designed style of the lobby's retry cards.
## Verify
@@ -51112,29 +53015,29 @@ Files shipped, the standings read path (existing or the one endpoint you added),
---
-<a id="sec-209"></a>
+<a id="sec-215"></a>
> **Source:** `docs/event-readiness/19-forge-props-live.md` · [↑ table of contents](#table-of-contents)
# Feature 19: forge 3D props live inside build mode
-The platform's headline capability is text to 3D, and the world's build mode cannot use it. The prop palette pulls only the public avatar gallery, so building means placing other people's uploads. Wire the Forge lane into build mode: type a prompt, watch the object appear where you pointed, and everyone in the world sees it. At a live event this is the demo moment.
+The platform's headline capability is text to 3D, and the world's build mode can now use it: the prop palette has a Forge form (and chat takes `/forge <prompt>`), `src/game/forge-prop.js` drives the free draft lane, and the finished GLB rides the uploaded-prop pipeline so everyone in the world sees it and the room persists it ([docs/play-forge-in-world.md](#sec-350)). What shipped is the pipeline; what is still open is the placement-first hologram, the size ceiling, and the server-side abuse limits below. At a live event this is the demo moment, and the size ceiling is what keeps it from becoming the iOS crash.
## Where the code lives
-- Forge lane: `api/forge.js` and siblings (`api/forge-gameready.js`, `api/forge-remesh.js`, `api/forge-rig.js`); client precedents in `src/forge.js` / `src/forge-studio/`. Use the platform's free text-to-3D lane and its existing rate limits; do not add a new paid dependency
+- Forge lane: `api/forge.js` (`POST /api/forge` submits, `GET /api/forge?job=` polls, `POST /api/forge?action=rig` auto-rigs; there is no separate rig handler) and siblings (`api/forge-gameready.js`, which now also accepts a settled forge purchase and echoes only its own payment error codes, and `api/forge-remesh.js`); in-world client `src/game/forge-prop.js` (submit, poll every 2.5 s, up to 6 minutes for a cold GPU start, reference photos via `/api/forge-upload` capped at 8 MB, keyed to the same `forge:cid` handle the /forge page uses so in-world forges land in the same history); page precedents in `src/forge.js` / `src/forge-studio/`. Use the platform's free text-to-3D lane and its existing rate limits; do not add a new paid dependency
- Prop plumbing (already networked and persistent): `src/game/world-objects.js` (`registerUploadedProp`, mirrors the server `objects` MapSchema), `src/game/avatar-upload.js` (`uploadPropModel`, presigned upload), the `_uploadProp` flow in `src/game/coincommunities.js`, persistence via `src/game/world-persist.js`
-- Prop palette UI: the props panel in `src/game/coincommunities-ui.js` (currently fetching `/api/avatars/public`), styles in `src/game/coincommunities.css`
+- Prop palette UI: the props panel in `src/game/coincommunities-ui.js` (the gallery tab still fetches `/api/avatars/public`; the Forge form is `forgeBtn` / `toggleForge()` reporting through the shared status strip, and the game side is `_forgeProp` in `src/game/coincommunities.js`), styles in `src/game/coincommunities.css`
- The mobile lesson: `src/game/ambient-crowd.js` documents how uncapped user models killed iOS tabs, and its `CROWD_BUDGET` tiers are the sizing precedent
- Generation ground truth when debugging: the `forge_creations` table carries per-generation backend, status, error, and prompt
## What to build
-1. **A Forge tab in the prop palette.** Prompt field, generate button, and a short history of this session's generations. Guidance text sets expectations honestly (real generation takes real time; say roughly how long from observed lane behavior, not a made-up number).
-2. **Placement-first flow.** The player aims and places a hologram placeholder immediately (ghost shell in the build style, clearly "generating", using the real async state, never a fake progress bar). When the GLB lands, it swaps in place with a brief materialize effect. On failure the hologram becomes a designed error marker with retry and dismiss.
-3. **The full prop pipeline, not a side door.** The finished GLB goes through `uploadPropModel` and `registerUploadedProp` so it is networked to every player, persists through `world-persist.js`, respects the per-player build budget, and is undoable with the existing Ctrl+Z stack.
-4. **Size discipline.** Run generations through the gameready/remesh path so what enters the world is capped: enforce a hard triangle and file-size ceiling in the spirit of `CROWD_BUDGET` before a model is ever registered. An oversized result is decimated or rejected with a clear message, never placed raw. This is the difference between a demo moment and a repeat of the iOS crash.
-5. **Abuse limits.** Per-player generation cooldown and a per-world concurrent-generation cap, enforced server-side on the endpoint, with the client showing queue position honestly.
+1. **A Forge tab in the prop palette.** Shipped as the Forge form in the props panel (prompt or reference photo, one forge at a time, progress in the status strip) plus the `/forge <prompt>` chat command, which opens build mode with the result armed. Still open: a short history of this session's generations, and guidance text that sets expectations honestly (the lane comment says draft-tier generations land in about 30 to 60 s; quote observed behavior, not a made-up number).
+2. **Placement-first flow.** Still open. Today the prop is armed as a ghost only after the GLB lands and the next click places it. Build the other order: the player aims and places a hologram placeholder immediately (ghost shell in the build style, clearly "generating", using the real async state, never a fake progress bar). When the GLB lands, it swaps in place with a brief materialize effect. On failure the hologram becomes a designed error marker with retry and dismiss.
+3. **The full prop pipeline, not a side door.** Shipped: `_forgeProp` hands the finished GLB to `registerUploadedProp` and the normal `obj:spawn` placement, so it is networked to every player, persists like any other build, respects the per-player build budget, and is undoable with the existing Ctrl+Z stack. Verify a result that comes back with `durable: false` (temporary storage the server's asset allow-list may refuse) surfaces its warning and never leaves a phantom in the palette.
+4. **Size discipline.** Still open, and the one that matters most. `forge-prop.js` enforces no triangle or file-size ceiling and never routes through the gameready/remesh path. Run generations through it so what enters the world is capped: enforce a hard triangle and file-size ceiling in the spirit of `CROWD_BUDGET` before a model is ever registered. An oversized result is decimated or rejected with a clear message, never placed raw. This is the difference between a demo moment and a repeat of the iOS crash.
+5. **Abuse limits.** Still open beyond the lane's own rate limits and the client's one-forge-at-a-time guard. Per-player generation cooldown and a per-world concurrent-generation cap, enforced server-side on the endpoint, with the client showing queue position honestly.
## Verify
@@ -51149,7 +53052,7 @@ Files shipped, the size ceiling values and where they are enforced, the rate-lim
---
-<a id="sec-210"></a>
+<a id="sec-216"></a>
> **Source:** `docs/event-readiness/20-world-chat-scrollback.md` · [↑ table of contents](#table-of-contents)
@@ -51160,10 +53063,10 @@ In-world chat is a pure relay: the server broadcasts and forgets, so everyone wh
## Where the code lives
- The relay today: the chat handler in `multiplayer/src/rooms/WalkRoom.js` (700ms cooldown and slur gate already enforced there; keep both)
-- Persisted community chat (separate system): `api/community/messages.js`
-- Chat UI: the chat bar and message list in `src/game/coincommunities-ui.js`, styles in `src/game/coincommunities.css`
-- Name safety: `multiplayer/src/display-name-safety.js`
-- Storage precedents: Upstash Redis usage in `api/play/builds.js` and `multiplayer/src/social-hub.js`
+- Persisted community chat (separate system): `api/community/messages.js` (public GET; POST as the signed-in user now refreshes the 1 h access token off the refresh cookie first via `withAuthRefresh`, and a genuinely dead session answers `401 auth_required` rather than the `posting_locked` the composer renders as "this world does not take posts"; a bridge that writes in-world chat into this stream inherits that contract)
+- Chat UI: the chat bar and message list in `src/game/coincommunities-ui.js` (it already sticks to the bottom only when the reader is near it, so a history tail must not fight that), styles in `src/game/coincommunities.css`
+- Name safety: `multiplayer/src/display-name-safety.js` (`containsHateSlur`, applied to names on join and to every chat line in the relay)
+- Storage precedents: Upstash Redis usage behind `api/play/builds.js` (`api/_lib/builds-store.js`) and in `multiplayer/src/social-hub.js`
## What to build
@@ -51186,7 +53089,7 @@ Files shipped, the cap and TTL chosen, the bridge decision and why, join-time pa
---
-<a id="sec-211"></a>
+<a id="sec-217"></a>
> **Source:** `docs/event-readiness/21-party-system.md` · [↑ table of contents](#table-of-contents)
@@ -51222,7 +53125,7 @@ Files shipped, where party state lives and its TTL, the teleport validation rule
---
-<a id="sec-212"></a>
+<a id="sec-218"></a>
> **Source:** `docs/event-readiness/22-venue-projector-mode.md` · [↑ table of contents](#table-of-contents)
@@ -51232,11 +53135,11 @@ Tomorrow there is a physical room with a big screen. The best thing that screen
## Where the code lives
-- URL params: parsing in `src/game/coincommunities.js` and the canonicalisation allowlist where entry rewrites the URL via `history.replaceState`. Any new param MUST be added to that allowlist or it is dropped on entry: this is the known trap
-- Cameras: `src/game/camera-modes.js` (cinematic mode exists) and `src/game/hud/camera-rig.js`
+- URL params: parsing in `src/game/coincommunities.js` and the canonicalisation in `enter()`, where the `history.replaceState` rewrite rebuilds the query from scratch with exactly `coin`, `name`, `symbol`, `image`, `tier` (holders worlds) and `ui`. Any new param MUST be added there or it is dropped on entry: this is the known trap
+- Cameras: `src/game/camera-modes.js` (cinematic mode exists) and `src/game/hud/camera-rig.js` (it now honors `prefers-reduced-motion`, suppressing shake and the speed FOV kick; the director rotation must respect the same switch, since a venue machine may have it set)
- Zen and embed precedents: `ui=hidden` and `bg=transparent` handling in `src/game/coincommunities.js`
-- Server join: `multiplayer/src/rooms/WalkRoom.js` join options; the client sends them from `src/game/community-net.js`
-- Event state: `public/event.json` via `src/game/event-countdown.js`; live activity if Feature 15 landed; invite QR if Feature 16 landed
+- Server join: `multiplayer/src/rooms/WalkRoom.js` join options (there is no `spectator` option yet; every join spawns a visible player); the client sends them from `src/game/community-net.js`
+- Event state: `public/event.json` via `src/game/event-countdown.js` and the shared `src/shared/event-config.js` reader (between events the file holds an explicit no-event state, `id: null`, which must render as the no-event overlay, not as an error); the go-live moments in `src/game/meetup-event.js` and `fireworks.js` are the shots worth cutting to; live activity if Feature 15 lands; invite QR if Feature 16 lands (`qrcode` is already a dependency)
## What to build
@@ -51258,7 +53161,7 @@ Files shipped, the exact URL to put on the venue machine, the spectator join con
---
-<a id="sec-213"></a>
+<a id="sec-219"></a>
> **Source:** `docs/event-readiness/23-signature-wall.md` · [↑ table of contents](#table-of-contents)
@@ -51268,8 +53171,8 @@ Events end; walls remember. Give the $THREE world a signature wall near spawn wh
## Where the code lives
-- Persistence precedents: `src/game/world-persist.js` (Postgres index plus blob store for builds), Upstash Redis in `api/play/builds.js`; pick the store that fits an append-only list of small records and state why
-- Canvas-rendered world screens: `src/game/screen-texture.js` (shared quality pattern), `src/game/chart-screen.js` and `src/game/x402-jumbotron.js` as CanvasTexture precedents
+- Persistence precedents: the per-world build doc behind `src/game/world-persist.js` (`api/world/[action].js` over `api/_lib/world-store.js`: a Postgres `world_docs` index row is always the source of truth, large docs offload to an R2 blob, and writes carry an etag with 409 on conflict; the browser only writes when no `walk_world` room is authoritative), Upstash Redis behind `api/play/builds.js` (`api/_lib/builds-store.js`); pick the store that fits an append-only list of small records and state why
+- Canvas-rendered world screens: `src/game/screen-texture.js` (shared quality pattern), `src/game/chart-screen.js`, `src/game/x402-jumbotron.js` and the marquee in `src/game/plaza-stage.js` as CanvasTexture precedents; the war portal's board in `src/game/war-portal.js` is the precedent for a screen that fetches nothing until a player is within reading range
- Interaction and placement: landmark precedent in `src/game/wheel-station.js`; the contextual F interaction chain in `src/game/coincommunities.js`
- Safety: the slur gate in `multiplayer/src/rooms/WalkRoom.js` and `multiplayer/src/display-name-safety.js` (reuse the same filters server-side on the write path)
- Identity: the play pass from `src/game/play-auth.js` distinguishes signed-in wallets from guests
@@ -51295,7 +53198,7 @@ Files shipped, the store chosen and why, the overflow design in two sentences, t
---
-<a id="sec-214"></a>
+<a id="sec-220"></a>
> **Source:** `docs/event-readiness/24-dance-off.md` · [↑ table of contents](#table-of-contents)
@@ -51331,7 +53234,7 @@ Files shipped, the round timings chosen, the vote targeting rule, the reward and
---
-<a id="sec-215"></a>
+<a id="sec-221"></a>
> **Source:** `docs/event-readiness/LIVE-OPS.md` · [↑ table of contents](#table-of-contents)
@@ -51344,7 +53247,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-216)):
+**Event URL** (the canonical $THREE world, from [README.md](#sec-222)):
```
https://three.ws/play?coin=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&name=three.ws&symbol=three&image=%2Fapi%2Fimg%3Furl%3Dhttps%253A%252F%252Fipfs.io%252Fipfs%252Fbafybeihe22b5sxr3ihnxt7pregfieyteqvubqhik3j3y4bbx243xlqjw3q%26seed%3DFeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
@@ -51631,7 +53534,7 @@ page.
---
-<a id="sec-216"></a>
+<a id="sec-222"></a>
> **Source:** `docs/event-readiness/README.md` · [↑ table of contents](#table-of-contents)
@@ -51643,40 +53546,40 @@ Suggested order and parallelism (audits):
| # | Prompt | Surface | Can run in parallel with |
|---|--------|---------|--------------------------|
-| 1 | [01-play-first-impression.md](#sec-191) | /play load, intro, onboarding UX | 4, 5, 7, 8 |
-| 2 | [02-play-mobile.md](#sec-192) | /play on phones (stability + touch) | 7, 8 |
-| 3 | [03-play-performance.md](#sec-193) | /play load weight, FPS, memory | 7, 8 |
-| 4 | [04-play-multiplayer-net.md](#sec-194) | WebSocket, reconnects, voice, crowd | 1, 5 |
-| 5 | [05-play-economy-loops.md](#sec-195) | Store, bank, wheel, combat, quests, cosmetics | 1, 4 |
-| 6 | [06-play-auth-errors.md](#sec-196) | Sign-in, gates, error/empty states, console | after 1 |
-| 7 | [07-platform-smoke-sweep.md](#sec-197) | Every page on the live site | 1, 2, 3 |
-| 8 | [08-api-production-health.md](#sec-198) | Cloud Run, crons, logs, DB, x402 | 1, 2, 3 |
-| 9 | [09-accessibility-i18n.md](#sec-199) | Keyboard, ARIA, contrast, translations | after 1 |
-| 10 | [10-event-day-runbook.md](#sec-200) | Pre-scale, monitoring loop, rollback | last, after all fixes deploy |
+| 1 | [01-play-first-impression.md](#sec-197) | /play load, intro, onboarding UX | 4, 5, 7, 8 |
+| 2 | [02-play-mobile.md](#sec-198) | /play on phones (stability + touch) | 7, 8 |
+| 3 | [03-play-performance.md](#sec-199) | /play load weight, FPS, memory | 7, 8 |
+| 4 | [04-play-multiplayer-net.md](#sec-200) | WebSocket, reconnects, voice, crowd | 1, 5 |
+| 5 | [05-play-economy-loops.md](#sec-201) | Store, bank, wheel, combat, quests, cosmetics | 1, 4 |
+| 6 | [06-play-auth-errors.md](#sec-202) | Sign-in, gates, error/empty states, console | after 1 |
+| 7 | [07-platform-smoke-sweep.md](#sec-203) | Every page on the live site | 1, 2, 3 |
+| 8 | [08-api-production-health.md](#sec-204) | Cloud Run, crons, logs, DB, x402 | 1, 2, 3 |
+| 9 | [09-accessibility-i18n.md](#sec-205) | Keyboard, ARIA, contrast, translations | after 1 |
+| 10 | [10-event-day-runbook.md](#sec-206) | 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-201) | Operator broadcast, go-live moment, live event config | nothing |
-| 12 | [12-photo-mode-share.md](#sec-202) | Photo mode with branded one-tap share | nothing |
-| 13 | [13-event-quests-leaderboard.md](#sec-203) | Time-boxed quest line + live leaderboard + cosmetic reward | nothing (better with 12) |
-| 14 | [14-welcome-concierge.md](#sec-204) | Greeter NPC, guided tour, event-aware opening line | nothing |
-| 15 | [15-live-hype-feed.md](#sec-205) | Activity ticker + market hype moments | nothing (better with 13) |
-| 16 | [16-invite-flow.md](#sec-206) | Invite sheet, QR, OG card truth, arrival continuity | nothing (better with 14) |
+| 11 | [11-event-live-ops.md](#sec-207) | Operator broadcast, go-live moment, live event config | nothing |
+| 12 | [12-photo-mode-share.md](#sec-208) | Photo mode with branded one-tap share | nothing |
+| 13 | [13-event-quests-leaderboard.md](#sec-209) | Time-boxed quest line + live leaderboard + cosmetic reward | nothing (better with 12) |
+| 14 | [14-welcome-concierge.md](#sec-210) | Greeter NPC, guided tour, event-aware opening line | nothing |
+| 15 | [15-live-hype-feed.md](#sec-211) | Activity ticker + market hype moments | nothing (better with 13) |
+| 16 | [16-invite-flow.md](#sec-212) | 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-207) | Live hosted show on a plaza stage, with $THREE tips | StageRoom + ShowDirector (built, unreachable from /play) |
-| 18 | [18-coin-wars-portal.md](#sec-208) | In-world Coin Wars portal: standings, queue, spectate | ClashRoom + war standings (built, arena-page only) |
-| 19 | [19-forge-props-live.md](#sec-209) | Text-to-3D prop generation inside build mode | Forge lane + the networked prop pipeline |
-| 20 | [20-world-chat-scrollback.md](#sec-210) | Chat scrollback for late joiners + community-feed bridge | the WalkRoom relay + api/community/messages |
-| 21 | [21-party-system.md](#sec-211) | Parties: form, see, reach, and talk to your crew | friends/presence stack; pairs with 13, 16 |
-| 22 | [22-venue-projector-mode.md](#sec-212) | Broadcast spectator view for the venue big screen | camera rig + event.json; pairs with 15, 16, 17 |
-| 23 | [23-signature-wall.md](#sec-213) | Persistent signature wall, the event's artifact | world-persist patterns + name safety |
-| 24 | [24-dance-off.md](#sec-214) | 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-213) | Live hosted show on a plaza stage, with $THREE tips | StageRoom + ShowDirector (built, unreachable from /play) |
+| 18 | [18-coin-wars-portal.md](#sec-214) | In-world Coin Wars portal: standings, queue, spectate | ClashRoom + war standings (built, arena-page only) |
+| 19 | [19-forge-props-live.md](#sec-215) | Text-to-3D prop generation inside build mode | Forge lane + the networked prop pipeline |
+| 20 | [20-world-chat-scrollback.md](#sec-216) | Chat scrollback for late joiners + community-feed bridge | the WalkRoom relay + api/community/messages |
+| 21 | [21-party-system.md](#sec-217) | Parties: form, see, reach, and talk to your crew | friends/presence stack; pairs with 13, 16 |
+| 22 | [22-venue-projector-mode.md](#sec-218) | Broadcast spectator view for the venue big screen | camera rig + event.json; pairs with 15, 16, 17 |
+| 23 | [23-signature-wall.md](#sec-219) | Persistent signature wall, the event's artifact | world-persist patterns + name safety |
+| 24 | [24-dance-off.md](#sec-220) | 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:
@@ -51688,7 +53591,7 @@ Rules that apply to every prompt in this pack:
---
-<a id="sec-217"></a>
+<a id="sec-223"></a>
> **Source:** `docs/event-souvenirs.md` · [↑ table of contents](#table-of-contents)
@@ -51709,7 +53612,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-340). That window has closed, so
+[`$THREE` First Holders Meetup](#sec-352). 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.
@@ -51939,15 +53842,15 @@ machine prefer the two above, which cover the same ground between them.
## Related
-- **[Live events in /play](#sec-340)** covers the rest of what that
+- **[Live events in /play](#sec-352)** covers the rest of what that
config file drives: the countdown, the agenda drawer, the fireworks.
-- **[The in-game economy](#sec-255)** covers the two currencies and
+- **[The in-game economy](#sec-265)** covers the two currencies and
the `$THREE` boutique the souvenir deliberately stays out of.
-- **[Coin communities](#sec-145)** covers the worlds the events happen in.
+- **[Coin communities](#sec-149)** covers the worlds the events happen in.
---
-<a id="sec-218"></a>
+<a id="sec-224"></a>
> **Source:** `docs/examples.md` · [↑ table of contents](#table-of-contents)
@@ -52688,7 +54591,7 @@ genuinely invested in the user's progress.
## Every runnable example in the repo
-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).
+The repo ships 47 examples: 11 web component demos, 10 end-to-end projects, and 26 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
@@ -52714,11 +54617,13 @@ The repo ships 45 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` |
+| [`herald-sdk/examples`](../herald-sdk/examples) | Three runnable examples, smallest first. Each one is a single file with no build step: open the HTML in a browser, or run the Node file with node. | `node herald-sdk/examples/ci-notify.mjs` |
| [`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` |
+| [`packages/portal/example`](../packages/portal/example) | Turn any website into a walkable 3D world. | `npm run dev, then open /packages/portal/example/index.html` |
| [`packages/pumpfun-mcp/examples`](../packages/pumpfun-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 live Solana mainnet data through the canonical three.ws backend. | `node packages/pumpfun-mcp/examples/list-tools.mjs` |
| [`sdk/example`](../sdk/example) | Ship a cross-chain 3D AI agent with EVM + Solana identity, a chat panel, and discoverable .well-known endpoints. | `npm run dev, then open /sdk/example/index.html` |
| [`packages/sign-language/example`](../packages/sign-language/example) | American Sign Language for 3D avatars. | `node packages/sign-language/example/compile-utterance.mjs` |
@@ -52756,7 +54661,7 @@ Run any command from the repo root after `npm install`. The web component demos
---
-<a id="sec-219"></a>
+<a id="sec-225"></a>
> **Source:** `docs/exit-lab.md` · [↑ table of contents](#table-of-contents)
@@ -52778,7 +54683,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-427)). The two answer
+documented in [trading-experiment.md](#sec-445)). The two answer
different questions and neither replaces the other.
| | Backtester (`/api/sniper/backtest`) | Exit Lab (`/exit-lab`) |
@@ -52987,15 +54892,15 @@ to the nearest legal one rather than throwing.
## Related
-- [Agent Sniper](#sec-061), the worker whose positions this replays
-- [Autonomous Trading hub](#sec-428), the front door to every trading surface
-- [Trading experiment](#sec-427), the policy this fleet runs and why
-- [Read the trading fleet](#sec-476), how to interpret fleet vitals
-- Tutorial: [Find a better exit policy](#sec-455)
+- [Agent Sniper](#sec-062), the worker whose positions this replays
+- [Autonomous Trading hub](#sec-446), the front door to every trading surface
+- [Trading experiment](#sec-445), the policy this fleet runs and why
+- [Read the trading fleet](#sec-496), how to interpret fleet vitals
+- Tutorial: [Find a better exit policy](#sec-475)
---
-<a id="sec-220"></a>
+<a id="sec-226"></a>
> **Source:** `docs/fact-check.md` · [↑ table of contents](#table-of-contents)
@@ -53032,7 +54937,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-384) and [3D provenance anchoring](#sec-347), 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-398) and [3D provenance anchoring](#sec-360), 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.
@@ -53077,7 +54982,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-563).
+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-589).
## Running the benchmark
@@ -53140,14 +55045,14 @@ Two guards keep a bad run from becoming a published number:
## Related
-- [x402: paid agent skills](#sec-563): 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-384) and [3D provenance](#sec-347): the platform's on-chain attestation primitives (distinct from this content-hash attestation)
+- [x402: paid agent skills](#sec-589): the payment rail the $0.10 lane rides
+- [API reference: Fact Check API](#sec-098): the endpoint's full request and response reference
+- [SAS credentialed attestations](#sec-398) and [3D provenance](#sec-360): 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-221"></a>
+<a id="sec-227"></a>
> **Source:** `docs/farcaster-memory-seeding.md` · [↑ table of contents](#table-of-contents)
@@ -53166,7 +55071,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-287), [`@three-ws/agent-memory`](https://www.npmjs.com/package/@three-ws/agent-memory)
+- **Related**: [Memory system](#sec-296), [`@three-ws/agent-memory`](https://www.npmjs.com/package/@three-ws/agent-memory)
---
@@ -53251,10 +55156,16 @@ Two rungs, tried in order:
1. **Neynar** (`@neynar/nodejs-sdk`, MIT) when `NEYNAR_API_KEY` is set. Indexed
data, so casts carry reaction counts and profiles carry follower counts. That
is what makes engagement ranking possible.
-2. **A public Farcaster hub over its HTTP API, keyless.** Default
- `https://hub.pinata.cloud`, override with `FARCASTER_HUB_URL`. Serves raw
- protocol messages, so there are no reaction counts, but it needs no vendor
- key and does not go dark when a billing plan lapses.
+2. **Public Farcaster hubs over their HTTP API, keyless.** Every hub serves
+ the same replicated set, so the lane walks a list rather than pinning one
+ host: `FARCASTER_HUB_URL` (if set) first, then any comma-separated
+ `FARCASTER_HUB_URLS`, then the built-in defaults (`https://hub.pinata.cloud`,
+ `https://hub.farcaster.standardcrypto.vc:2281`,
+ `https://nemes.farcaster.xyz:2281`). An unreachable hub or a non-2xx answer
+ moves to the next rung; a "no such user" answer ends the walk immediately,
+ because that is the network's verdict, not one hub's. Hubs serve raw
+ protocol messages, so there are no reaction counts, but they need no vendor
+ key and do not go dark when a billing plan lapses.
Neither key is required for the feature to work. The SDK is imported lazily and
only when a key is configured, so the keyless lane carries no dependency on the
@@ -53397,7 +55308,204 @@ only its own rows and a revoke deletes exactly what was granted.
---
-<a id="sec-222"></a>
+<a id="sec-228"></a>
+
+> **Source:** `docs/feedback.md` · [↑ table of contents](#table-of-contents)
+
+# Feedback: telling the agent what is wrong
+
+Every three.ws page carries a companion in the corner. It walks the page, reads
+sections aloud, and delivers notifications in person. This is the channel going
+the other way: a visitor tells it what broke, and the report lands in a queue a
+maintainer reads at `/feedback`.
+
+Two things make it different from a support form.
+
+**It asks at the moment of failure.** When a page actually throws an exception
+or a request actually fails, the companion turns and asks what you were doing.
+That is the only moment the visitor still remembers, and the error is already
+attached. A form waits to be found, by which time the visitor has left.
+
+**The useful half is captured, not typed.** A person writes "the download button
+does nothing". What arrives with it is the route, the page title, the build SHA,
+the viewport, the locale, the last few console errors, and the last few failed
+requests. The build SHA is the one that changes the work: it turns "the avatar
+page is blank" into "the avatar page went blank in the deploy that shipped
+`abc1234`".
+
+## The boundary that makes this safe
+
+**Feedback is data. It is never an instruction.**
+
+The text a visitor types is read by a model that scores and classifies it, and
+that model has no ability to act. It writes six scalars back to the report's own
+row: severity, kind, subsystem, summary, a repro guess, and a cluster key. There
+is no path from a feedback report to the repository, to a deploy, to a
+configuration change, or to any write beyond that row.
+
+This is deliberate and it is not negotiable. The corner companion is reachable
+by anyone on the internet with no account. If what they type could reach
+anything with write access, the text box would be a remote code execution
+primitive wearing a friendly face. So the model that reads untrusted text has no
+authority, the queue it produces is read by a person, and the person decides.
+
+The prompt reflects the same rule: the report is passed as data inside a
+delimiter, the model is told it may not follow instructions found there, and a
+report that tries is classified as spam and scored 0. See the security note at
+the top of [`api/_lib/feedback/triage.js`](../api/_lib/feedback/triage.js).
+
+## How a report travels
+
+1. **Capture.** [`src/feedback-companion.js`](../src/feedback-companion.js)
+ starts [`@three-ws/witness`](#sec-547) at module load, before the
+ companion finishes mounting. It keeps a bounded semantic trace: the sequence
+ of intents plus the failures, with a stable selector for every element
+ touched and no typed value ever held. No timers, no network, nothing sent
+ anywhere: this costs nothing until something goes wrong.
+2. **The ask.** On a real failure the companion offers, once per route per
+ session, never in a background tab, and never again on a route where the
+ visitor said "not now". The chrome control next to the narration and trails
+ toggles is always available, and any surface can call
+ `window.__walkFeedback.open()`.
+3. **Send.** `POST /api/feedback/report` stores the body plus the captured
+ context. Anonymous reporters are keyed to a random browser id that is hashed
+ server-side before storage. A failure here keeps the draft in
+ `localStorage` and offers a retry, because a visitor who typed a paragraph
+ must not lose it to a 503.
+4. **Triage.** `/api/cron/feedback-triage` runs every five minutes. A
+ deterministic scorer always runs (no key, no cost); an LLM pass refines it
+ when a chain is configured. The LLM may move the severity but cannot push a
+ report corroborated by a console error below 60, because a console error is
+ a fact and a model that decides it does not matter should not be able to
+ bury it.
+5. **Read.** `/feedback` groups reports into one row per distinct problem,
+ loudest first, showing how many people hit each one. A cluster with a
+ recorded session carries a **Copy test** button. A maintainer accepts, fixes,
+ or dismisses.
+
+## From report to failing test
+
+Every report also carries the **session** the visitor recorded: the sequence of
+things they did, with a stable selector synthesized for each one, and the failure
+at the end. That trace compiles into a Playwright spec which asserts the failure
+is gone, so it is red while the bug exists and green once it is fixed.
+
+```bash
+npm run feedback:repro -- --list # reports with a replayable session
+npm run feedback:repro -- <id> --run # compile it and watch it fail
+```
+
+The reconstruction step, which is where most bug reports die, is done before a
+maintainer opens the queue. Full detail, including the selector ladder and the
+privacy rules: [Witness](#sec-547).
+
+Nothing about this changes the boundary above. The trace is machine-written data
+validated by shape at the API edge, the compiler is a pure function with no
+network and no filesystem, and the output is a file a human chooses to run.
+
+## Severity
+
+The deterministic pass scores 0 to 100 from what was said and what the browser
+saw:
+
+| Signal | Effect |
+| --- | --- |
+| A console error or failed request arrived with the report | +18 / +14. The strongest signal here, because the browser cannot exaggerate. |
+| Money, withdrawal, or sign-in words | +20 |
+| Data-loss words ("deleted", "disappeared", "lost my") | +22 |
+| Signed-in reporter on wallet, payments, or settings | +10 |
+| Classified as spam | forced to 0 |
+
+Kind baselines run `bug` 55, `broken-link` 45, `confusing` 35, `copy` 20,
+`idea` 15, `praise` 5.
+
+## Clustering
+
+Twenty people reporting one outage must read as one row, or the queue buries the
+thing everyone is hitting under the noise of everyone hitting it. The rules pass
+groups coarsely by `subsystem:kind`; the LLM pass can replace that with a
+sharper slug describing the problem itself (`avatar-studio:blank-on-ios`), never
+the wording of one particular report.
+
+## API
+
+### `POST /api/feedback/report`
+
+Open to anonymous visitors on purpose: the person best placed to tell you a page
+is broken is often the one who could not get past it to sign in.
+
+```bash
+curl -X POST https://three.ws/api/feedback/report \
+ -H 'content-type: application/json' \
+ -H 'x-feedback-client: 6f1c9a3e-2b47-4d55-9c8e-1f0a5d7b3e21' \
+ -d '{
+ "body": "The download button does nothing on my phone.",
+ "route": "/avatar-studio",
+ "page_title": "Avatar Studio",
+ "build_sha": "abc1234",
+ "viewport": "390x844@3",
+ "locale": "en-GB",
+ "console_errors": ["TypeError: exportGLB is not a function (studio.js:412)"],
+ "failed_requests": ["POST /api/export -> 500"],
+ "trace": { "version": 1, "environment": {}, "events": [{ "type": "goto", "detail": "/avatar-studio" }] }
+ }'
+```
+
+```json
+{ "ok": true, "id": "8c2f...", "received_at": "2026-08-28T14:02:11.884Z", "replayable": true }
+```
+
+`trace` is optional and machine-written by [`@three-ws/witness`](#sec-547).
+It is validated by shape at this boundary (known event types only, 80 events,
+every string capped), because the endpoint is open to anyone. `replayable` says
+whether a usable trace survived that validation.
+
+Rate limited to 20 reports per hour per account, browser key, or IP. Every text
+field is capped server-side and the two signal lists keep their first five
+entries.
+
+### `GET /api/feedback` (admin)
+
+`?status=open|new|accepted|dismissed|fixed|all` returns clusters plus counts.
+`?cluster=<key>` returns the individual reports in one cluster.
+
+### `POST /api/feedback` (admin)
+
+```json
+{ "cluster": "avatar-studio:blank-on-ios", "status": "fixed", "resolution": "Fixed in abc1234" }
+```
+
+Pass `id` instead of `cluster` to move a single report.
+
+### `GET /api/feedback/repro?id=<report id>` (admin)
+
+The report as a runnable Playwright spec. `&format=json` returns the source
+alongside the narrated steps and the replay confidence; `&base=<origin>` points
+the replay somewhere other than production. See [Witness](#sec-547).
+
+## What this deliberately does not do
+
+It does not write code, open pull requests, change configuration, or deploy.
+Those would each be a new decision with its own gate, and none of them should
+ever be triggered by text typed into a box by an anonymous visitor.
+
+What it does instead is remove the reason people wanted that: the expensive part
+of acting on a bug report was never writing the fix, it was reproducing the bug.
+A compiled repro hands that over without handing over any authority. An agent
+with `feedback:read` can pull a reproduction over MCP, run it, change code in a
+branch, and run it again to prove the fix, and the pull request still needs a
+human to merge it. If a proposal layer is ever built here, that is its shape: the
+input is the structured triage record a person already accepted plus a spec that
+reproduces the failure, never the raw report, and the output is a pull request.
+
+## Related
+
+- [Notifications](#sec-311): the same companion delivering messages the other way.
+- [`STRUCTURE.md`](../STRUCTURE.md): where every surface lives.
+
+---
+
+<a id="sec-229"></a>
> **Source:** `docs/financial-controls.md` · [↑ table of contents](#table-of-contents)
@@ -53410,7 +55518,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-294) (who receives what) and the
+It is a companion to the [money map](#sec-304) (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.
@@ -53686,19 +55794,19 @@ 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-294).
+ added to this register and the [money map](#sec-304).
---
## Related
-- [Money map](#sec-294) — who receives each payment.
-- [x402 endpoints](#sec-559) — the paid endpoint catalog.
+- [Money map](#sec-304) — who receives each payment.
+- [x402 endpoints](#sec-584) — the paid endpoint catalog.
- [Solana signers runbook](../api/_lib/solana-signers.js) — the wallets + funding.
---
-<a id="sec-223"></a>
+<a id="sec-230"></a>
> **Source:** `docs/first-contribution.md` · [↑ table of contents](#table-of-contents)
@@ -53722,7 +55830,7 @@ npm run dev
Open http://localhost:3000. You should see a 3D avatar you can orbit with the mouse.
-`npm run setup` is not optional and not the same as `npm install`. It builds the local `solana-agent-sdk` (linked as a `file:` dependency with no prebuilt `dist/`) and generates the gitignored `data/_generated/*` artifacts that the app, the sitemap, and the test suite read. It is idempotent, so re-running it is always safe.
+`npm run setup` is not optional and not the same as `npm install`. It builds the local `solana-agent-sdk` (linked as a `file:` dependency with no prebuilt `dist/`), generates the gitignored `data/_generated/*` artifacts that the app, the sitemap, and the test suite read, and installs the repo's pre-push hook into `.git/hooks` (the same one `npm install` sets up through `scripts/setup-git-hooks.mjs`). That hook lints the commits you push against the rules in section 4, so a rejected push is the hook doing its job, not a broken setup. It is idempotent, so re-running it is always safe.
You do **not** need any API keys, a wallet, or a database to work on the rendering, rigging, animation, or docs layers. Those layers are pure client-side JavaScript and their tests run offline.
@@ -53801,7 +55909,7 @@ Three things to copy from it, beyond the mapping itself:
- **The comment says what was left out and why.** The IK and twist bones are the interesting decision here, and the next reader needs the reasoning, not just the table.
- **Fingers are not optional.** 30 of the 53 tracks in every clip address a finger joint, so a rig whose hands do not map scores around 40% coverage and gets no animation at all.
-- **Rig Doctor learned the name too.** A matching fingerprint went into `CONVENTIONS` in [`src/rig-report.js`](../src/rig-report.js), so an MMD upload is identified on sight instead of reported as unrecognised, and a row went into the table in [`docs/rig-doctor.md`](#sec-381).
+- **Rig Doctor learned the name too.** A matching fingerprint went into `CONVENTIONS` in [`src/rig-report.js`](../src/rig-report.js), so an MMD upload is identified on sight instead of reported as unrecognised, and a row went into the table in [`docs/rig-doctor.md`](#sec-395).
The tests that shipped with it, in [`tests/glb-canonicalize.test.js`](../tests/glb-canonicalize.test.js), use the file's `describe` + `it.each` table style. Match it:
@@ -53878,7 +55986,7 @@ Then open the PR on GitHub. In the description say what changed, what you tested
## 5. What happens next
-See [Triage](#sec-430) for the full flow and response targets. In short: a maintainer reads it, you get real review comments, and merged work shows up in the [public changelog](https://three.ws/changelog).
+See [Triage](#sec-448) for the full flow and response targets. In short: a maintainer reads it, you get real review comments, and merged work shows up in the [public changelog](https://three.ws/changelog).
---
@@ -53891,7 +55999,7 @@ See [Triage](#sec-430) for the full flow and response targets. In short: a maint
---
-<a id="sec-224"></a>
+<a id="sec-231"></a>
> **Source:** `docs/forge-background-generation.md` · [↑ table of contents](#table-of-contents)
@@ -53942,22 +56050,30 @@ Three cooperating pieces:
past the attended polling window (13 minutes, so a live browser's own
failover is never raced) is redispatched unattended to the next healthy
lane under the same hop cap as the attended path, and an expired NVCF
- request is resubmitted from the inputs stored on the row. Only a job with
- nothing left to try is marked failed. Anything non-terminal after 45
- minutes is marked failed as timed out, so no row can be orphaned at
- `generating` again.
+ request is resubmitted from the inputs stored on the row. A redispatched
+ attempt is linked to its successor row (`forge_creations.superseded_by`,
+ migration `20260814200000_forge_failover_supersede.sql`), so the outcome
+ ledger records a recovery rather than a loss. Only a job with nothing left
+ to try is marked failed, and the finalizer logs that it declined the
+ failover (every alternative lane already attempted or cooling) rather than
+ failing silently. Anything non-terminal after 45 minutes is marked failed
+ as timed out, so no row can be orphaned at `generating` again.
3. **Notifications** ([api/_lib/forge-notify.js](../api/_lib/forge-notify.js)):
the finalizer, and only the finalizer, notifies. `forge_complete` and
`forge_failed` are standard notification types in the `creations`
- preference category (defaults: in-app on, push on, email on for
- completions). Email delivery uses the platform Resend pipeline and skips
- undeliverable placeholder addresses.
+ preference category (defaults: in-app, push, email and the on-page
+ companion avatar on; Telegram off; email only for completions). The
+ `avatar` channel is delivered client-side by the corner companion
+ (`src/notification-herald.js`), which walks on and says it out loud while
+ the user is on the site; it can be muted per browser from its bubble.
+ Email delivery uses the platform Resend pipeline and skips undeliverable
+ placeholder addresses.
## Self-host poll recovery (the "task not found" grace)
A self-host worker poll (`/tasks/:id` or `/jobs/:id`) can 404 when the durable
-task record is not yet visible to the instance the poll load-balanced to — the
+task record is not yet visible to the instance the poll load-balanced to: the
brief post-submit cross-instance window (workers run at high concurrency with no
session affinity), or a completion write racing the poll. The worker persists
each task's `queued` state to GCS before returning its 202 and re-reads GCS for
@@ -53970,33 +56086,36 @@ recoverable signal): the GCP provider tags a 404 with `code: 'gcp_task_missing'`
([api/_providers/gcp.js](../api/_providers/gcp.js)) and the poll handler runs a
pure decision ([api/_lib/forge-selfhost-recovery.js](../api/_lib/forge-selfhost-recovery.js)):
-1. **Store re-check** — if the creation row already materialized (`done` + a
+1. **Store re-check**: if the creation row already materialized (`done` + a
glb), a racing poll or the completion write beat us; resolve as complete.
-2. **Grace window** — a job younger than `GCP_TASK_MISSING_GRACE_MS` (90s)
+2. **Grace window**: a job younger than `GCP_TASK_MISSING_GRACE_MS` (90s)
reports `running` so the client keeps polling; the durable record resolves
within seconds.
-3. **Terminal** — past the window a still-missing task is genuinely orphaned;
+3. **Terminal**: past the window a still-missing task is genuinely orphaned;
the failure surfaces and the existing lane failover redispatches to a healthy
- lane. Nothing here disables failover — it just stops firing it on transient
+ lane. Nothing here disables failover, it just stops firing it on transient
404s.
## Generation success-rate health
Lane liveness ("can a worker serve right now?") is not the same as outcome
health ("are generations succeeding?"). A warm lane can still fail half its
-jobs — the 404 burst above ran ~48% failure for days while every liveness probe
+jobs: the 404 burst above ran ~48% failure for days while every liveness probe
read healthy. The **Forge 3D generation** subsystem
([api/_lib/ops/forge-health-sensor.js](../api/_lib/ops/forge-health-sensor.js))
closes that: it reads `forge_creations` outcomes over a 6h window and reports the
-success rate (`done / (done + failed)`; running/queued excluded), naming the
+success rate (`done / (done + failed)`; running/queued excluded, and so are
+attempts that were re-dispatched to another lane, `superseded_by` set, so the
+failover machinery working is never counted as loss), naming the
worst backend/path and top error class so a page is actionable. It rolls into
`/api/healthz`, `/status`, and the uptime-cron escalation. States: `ok` ≥ 85%,
-`degraded` 60–85%, `down` < 60%, `unknown` below 15 finished generations
+`degraded` 60 to 85%, `down` < 60%, `unknown` below 15 finished generations
in-window. This is the forge twin of the x402 settlement-success sensor.
## Operational notes
-- The finalizer needs `CRON_SECRET` (standard cron auth), `DATABASE_URL`, the
+- The finalizer needs `CRON_SECRET` (the shared fail-closed cron gate,
+ `api/_lib/cron-auth.js`), `DATABASE_URL`, the
R2 `S3_*` storage vars, and `GCP_RECONSTRUCTION_KEY` to poll workers. With
no worker key it still reaps timed-out rows.
- Batch size is 25 per tick (`FORGE_FINALIZE_BATCH` overrides). Ticks are
@@ -54011,7 +56130,7 @@ and the notification preference model in
---
-<a id="sec-225"></a>
+<a id="sec-232"></a>
> **Source:** `docs/forge-off.md` · [↑ table of contents](#table-of-contents)
@@ -54032,15 +56151,15 @@ strip without an account.
On the "Fresh from the Forge" section of [/forge](/forge):
-- **Upvote** — each card has an upvote pill (chevron + count). Tap it to vote,
+- **Upvote**: each card has an upvote pill (chevron + count). Tap it to vote,
tap again to remove your vote. The count is the whole community's; the filled
state is only yours. The button is optimistic and reconciles against the
server tally, so a double-tap or a slow network never leaves it wrong.
-- **Fresh / Top this week** — a toggle in the section header. *Fresh* is the
+- **Fresh / Top this week**: a toggle in the section header. *Fresh* is the
historical newest-first, visual-first strip. *Top this week* is the Forge-Off
board: the most-voted public models created during the current Forge-Off week
(Monday→Monday UTC), highest first.
-- **The weekly winner** — every Monday the top-voted model of the week just
+- **The weekly winner**: every Monday the top-voted model of the week just
ended is crowned permanently. Later votes never rewrite a past week's winner.
The same strip and voting appear on the signed-in [/forge-studio](/forge-studio)
@@ -54069,7 +56188,7 @@ Response:
never a drifting counter).
- `voted` is *your* state after the call.
- Voting is idempotent: a second upvote from the same browser is a no-op.
-- A missing or shared (`anon`) client id is rejected `400 no_client_id` — a real
+- A missing or shared (`anon`) client id is rejected `400 no_client_id`: a real
vote needs a real, unique voter so the tally means something.
- Votes are only accepted on public, finished, non-rejected creations. Anything
else returns `404 not_votable`.
@@ -54082,14 +56201,19 @@ already caps real influence; this just blunts carpet-voting).
```
GET /api/forge-gallery?scope=community&sort=top&window=week&limit=24
-x-forge-client: <stable browser id> # optional — resolves your `voted` flags
+x-forge-client: <stable browser id> # optional, resolves your `voted` flags
```
-- `sort=fresh` (default) — newest, visual-first.
-- `sort=top` — ranked by `vote_count` desc, `created_at` desc.
-- `window=week` — with `sort=top`, narrow to the current Forge-Off week.
+- `sort=fresh` (default): newest, visual-first.
+- `sort=top`: ranked by `vote_count` desc, `created_at` desc.
+- `window=week`: with `sort=top`, narrow to the current Forge-Off week.
- Each returned creation carries `vote_count` and, when a client id is sent,
- `voted`. An anonymous read is CDN-cacheable; a voter-aware read is `private`.
+ `voted`. An anonymous read is CDN-cacheable; a voter-aware read is `private`,
+ and the response varies on `x-forge-client`, so the edge never hands the
+ anonymous copy to a browser that sent a client id.
+- The read is CORS-open to any origin: it is the same public catalogue the
+ standalone AR studio (npm: `3d-ar-studio`) shows as its Community tab from
+ whatever page embeds it. Rate limiting is the control, not the origin.
## How it fits together
@@ -54116,19 +56240,24 @@ that pipeline's strongest tier was starved; voting + the weekly crown feed it.
| Piece | Where |
|---|---|
-| Vote / board store logic | [api/_lib/forge-store.js](../api/_lib/forge-store.js) — `castVote`, `removeVote`, `listShowcase` (sort/window/voter), `forgeOffWeekStart` |
+| Vote / board store logic | [api/_lib/forge-store.js](../api/_lib/forge-store.js): `castVote`, `removeVote`, `listShowcase` (sort/window/voter), `forgeOffWeekStart` |
| Vote endpoint | [api/forge-vote.js](../api/forge-vote.js) |
| Board read | [api/forge-gallery.js](../api/forge-gallery.js) (`scope=community`) |
| Weekly crowning cron | [api/cron/forge-off-crown.js](../api/cron/forge-off-crown.js) (`7 0 * * 1`) |
| UI (vote button, Fresh/Top toggle) | [src/forge-showcase.js](../src/forge-showcase.js) and its `/forge-studio` twin [src/forge-studio/forge-showcase.js](../src/forge-studio/forge-showcase.js) |
-| Schema | [migration 20260625120000_forge_board.sql](../api/_lib/migrations/20260625120000_forge_board.sql) — `forge_votes`, `forge_creations.vote_count`, `forge_board_winners` |
+| Schema | [migration 20260625120000_forge_board.sql](../api/_lib/migrations/20260625120000_forge_board.sql): `forge_votes`, `forge_creations.vote_count`, `forge_board_winners` |
+
+A creator deleting their own creation (`DELETE /api/forge-creation?id=`, the
+two-tap delete on a "Your creations" card) takes its `forge_votes` rows with
+it; a past week's `forge_board_winners` row survives with its creation
+reference cleared, so the hall of fame never loses a week.
Backfill a past week's winner (owner): `GET /api/cron/forge-off-crown?week=YYYY-MM-DD`
(add `&dry_run=1` to preview). Authorized with `CRON_SECRET`.
---
-<a id="sec-226"></a>
+<a id="sec-233"></a>
> **Source:** `docs/forge-pipeline.md` · [↑ table of contents](#table-of-contents)
@@ -54136,7 +56265,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-227). If you want the plain-language version, read [How the Forge works](#sec-241). This document is for people changing the pipeline.
+If you want the product-level overview, read [Forge](#sec-234). If you want the plain-language version, read [How the Forge works](#sec-250). This document is for people changing the pipeline.
## Bird's-eye view
@@ -54193,7 +56322,7 @@ Three properties define the design:
| Flagship free API | `POST /api/v1/ai/text-to-3d` (`api/v1/ai/text-to-3d.js`) | NVIDIA NIM TRELLIS draft lane, 10 generations per IP per day, 429 + x402 upsell above quota. |
| Refinement | `POST /api/forge-iterate` (`api/forge-iterate.js`) | Conversational refinement with version lineage for the signed-in Studio. |
| MCP (paid stdio) | `mesh_forge`, `forge_avatar`, `forge_free`, `text_to_avatar`, `rig_mesh`, `refine_model`, `restyle_material` (`mcp-server/src/tools/`) | Shared cores in `mcp-server/src/tools/_studio-core.js`; thin clients over `/api/forge`. |
-| ChatGPT clone | `POST /api/gpt-forge` (`api/gpt-forge.js`) | Clone of the orchestrator dedicated to the ChatGPT surfaces (the Apps SDK MCP connector `api/mcp-studio` and the custom-GPT Actions endpoint `api/3d/studio`, via `api/_mcp-studio/gpt-forge-client.js`), so the ChatGPT pipeline can evolve without touching `/api/forge`. Same lanes, tiers, job tokens, and `forge_creations` rows. First divergence: its poll responses also carry `prompt`, `preview_image_url` (the painted concept view), and `text_to_image_model`, so the ChatGPT surfaces can show the concept image while the mesh generates. |
+| ChatGPT clone | `POST /api/gpt-forge` (`api/gpt-forge.js`) | Clone of the orchestrator dedicated to the ChatGPT surfaces (the Apps SDK MCP connector `api/mcp-studio` and the custom-GPT Actions endpoint `api/3d/studio`, via `api/_mcp-studio/gpt-forge-client.js`), so the ChatGPT pipeline can evolve without touching `/api/forge`. Same lanes, tiers, job tokens, and `forge_creations` rows. First divergence: its poll responses also carry `prompt`, `preview_image_url` (the painted concept view), and `text_to_image_model`, so the ChatGPT surfaces can show the concept image while the mesh generates. It also remembers a finished job's poll frame (`api/_lib/forge-done-cache.js`), so later polls of a done job answer in milliseconds without re-reading the provider. |
| MCP (hosted HTTP) | `text_to_3d`, `image_to_3d`, `auto_rig_model`, plus the wider studio toolset (`generation_status`, `preview_3d`, `remove_background`, `remesh_model`, `stylize_model`, `segment_model`, `retexture_model`, `pose_model`, `save_avatar`, persona tools; `api/mcp-3d.js`, tools in `api/_mcp3d/tools/studio.js`) | Streamable HTTP server registered as `io.github.nirholas/three-ws-3d-studio`. |
| DCC plugins | `integrations/blender/`, `integrations/comfyui/`, `integrations/_pyclient/` | First-party clients driving the same API. |
@@ -54267,15 +56396,17 @@ Routing answers one question: given `(path, tier, userImages, prompt)`, which co
**Submit-time failover.** If a lane rejects the submit outright (down, quota, cooldown), `startJob` walks the free-first chain to the next candidate in the same request. The client never sees the rejected lane.
+**Reference-image budget.** On the text path the reference-image step (the Vertex lane in `api/_lib/forge-reference-image.js`, its QA score and corrective retry, and the `textToImage` fallthrough ladder, Livepeer included) runs under one shared budget, `TEXT_TO_IMAGE_BUDGET_MS` (default 60 s). A stalled paint provider can no longer hold a submit open for minutes before a job exists; once the budget is spent the caller gets a fast, retryable failure instead.
+
### The job handle
Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forge-job-token.js`) that records provider, kind, and upstream task id, signed with `JWT_SECRET`. The legacy Replicate path keeps the bare prediction id. Tokens make the poll endpoint stateless: any instance can decode the handle and ask the right upstream.
### 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-224)).
+`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-231)).
-**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.
+**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. Both failover paths (this attended one and the unattended finalizer sweep) link the failed attempt to its successor row (`forge_creations.superseded_by`, migration `20260814200000_forge_failover_supersede.sql`), so the outcome ledger, the forge health sensor and `npm run forge:errors` count a recovered attempt as a recovery, not a loss.
**Designed terminal failure.** When no successor is possible, the failed response carries `retryable: true` plus `retry_backends: [...]`, the ordered configured lanes a client can one-click resubmit to. A failure is never a bare string. The whole module is fail-open: no Redis disables automatic redispatch but keeps suggestions; no DB disables recovery but never turns a clean failure into a hang.
@@ -54283,7 +56414,7 @@ Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forg
- **Quality gate + best-of retry.** `scoreQualityGate` flags degenerate results (near-empty geometry, texture failures); synchronous lanes retry once inline before returning.
- **Result cache** (`api/_lib/forge-cache.js`). Identical text prompts on platform-keyed non-high lanes are served from cache with `cached: true`. The key covers path, tier, backend, the normalized prompt, and the output-affecting options (seed included), with a 7-day TTL that a read never refreshes. `force_regenerate: true` in the request body skips the cache READ while still writing the fresh result back. Any caller that must prove the pipeline is alive rather than that a mesh exists has to send it: the daily smoke cron (`api/cron/forge-smoke.js`) submits a constant prompt with no seed, so without the flag its key never changes and it verifies a replay. Automation that seeds the gallery takes the other route and varies the seed per submit (`api/cron/forge-seed-cron.js`), so a repeated prompt yields a genuinely new asset instead of a second catalog entry pointing at one GLB.
-- **Scale controls** (`api/_lib/forge-scale.js`). In-flight coalescing, blocking-lane slots, and daily paid caps keep a traffic spike from stampeding the GPU fleet or the paid last resort.
+- **Scale controls** (`api/_lib/forge-scale.js`). In-flight coalescing, blocking-lane slots, and daily paid caps keep a traffic spike from stampeding the GPU fleet or the paid last resort. Its circuit breaker (`circuitRecordFailure`) widens the open window linearly per consecutive failure but caps it at one hour (`CIRCUIT_MAX_OPEN_MS`), so a provider outage parks the seed cron for at most an hour before it re-probes the lane.
## 6. Persistence and storage
@@ -54296,8 +56427,9 @@ Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forg
- Feedback flywheel: `outcome` (`generated`, `accepted`, `rejected`), `rating`, `note`, `downloaded`, `feedback_at`. The outcome partial index feeds training-signal export.
- Lineage and remix (migration `20260625000000_forge_refine_lineage.sql`): `parent_creation_id`, `refine_instruction`, `lineage_index`, `remixable`, `remix_royalty_bps` (0 to 2000, default 1000), `creator_wallet_solana`, `remix_settlement_ref`.
- Forge-Off (migration `20260625120000_forge_board.sql`): `vote_count`, plus the `forge_votes` and `forge_board_winners` tables.
+- Failover and cleanup: `superseded_by` (migration `20260814200000_forge_failover_supersede.sql`, the successor row's id when this attempt was re-dispatched; a plain uuid, not a foreign key, so retention pruning stays free) and `source_image_keys` (migration `20260813160000_forge_source_image_keys.sql`, the storage key of every uploaded reference photo, so a delete can erase them).
-`api/_lib/forge-store.js` owns all writes: `createCreation` on submit (also records the funnel `start` event), `materializeCreation` on completion, `markFailed`, and verdict capture. It is fail-soft: without a DB or storage config it no-ops rather than blocking generation.
+`api/_lib/forge-store.js` owns all writes: `createCreation` on submit (also records the funnel `start` event), `materializeCreation` on completion, `markFailed`, `markSupersededBy` when a failed attempt is re-dispatched, verdict capture, and `deleteCreation` (behind `DELETE /api/forge-creation?id=`), which removes the mesh, preview and source uploads from storage before the row and is scoped to the owning client key. It is fail-soft: without a DB or storage config it no-ops rather than blocking generation.
**Storage is two-layer.** GPU workers write raw output to GCS (`gs://$GCS_BUCKET/raw-meshes/...`), and provider URLs generally expire within about an hour. `materializeCreation` therefore mirrors the mesh and reference image into Cloudflare R2 (`api/_lib/r2.js`) and stores the durable CDN URL in `glb_url`. Anything user-facing must reference the R2 URL, never the raw provider URL.
@@ -54320,7 +56452,7 @@ Model weights are staged from `gs://three-ws-model-weights` via `workers/deploy/
## 8. Post-processing
- **Rigging.** `POST /api/forge?action=rig` prefers the self-host rig worker and falls back to Replicate; unconfigured deployments return a clean 501. Auto-rig-on-create (`api/_lib/auto-rig.js`) mints a sibling creation row rather than mutating the original (provenance and attestation depend on the original bytes staying put), gated by the humanoid prompt classifier (`mcp-server/src/tools/_humanoid.js`) and `rigInfoIsRigged()` (already-skinned GLBs are skipped).
-- **Skeleton canonicalization.** `src/glb-canonicalize.js` maps any humanoid rig's bone names (Mixamo, Avaturn, Unreal, VRM/VRoid, Daz, MakeHuman, Blender `.L`, and more) onto the canonical bone set, repacking the GLB in place. There is no rig allowlist; a new convention means a new bone-name mapping plus a test case in `tests/glb-canonicalize.test.js`.
+- **Skeleton canonicalization.** `src/glb-canonicalize.js` maps any humanoid rig's bone names (Mixamo, Avaturn, Unreal, VRM/VRoid, Daz, MakeHuman, MMD/MikuMikuDance with its Japanese bone names, Blender `.L`, and more) onto the canonical bone set, repacking the GLB in place. There is no rig allowlist; a new convention means a new bone-name mapping plus a test case in `tests/glb-canonicalize.test.js`.
- **Animation retargeting.** `src/animation-retarget.js` applies the pre-baked canonical clip library (`public/animations/clips/*.json`) to arbitrary rigs: rewrites track names, drops missing bones, rescales hip translation, and requires 50% bone coverage. Pure JS, shared between the browser and the Node MCP tool.
- **Refinement lineage.** `api/forge-iterate.js` and the MCP `refine_model` tool share one core (`mcp-server/src/tools/_lineage.js`) for composing refinements and maintaining the revertable, branchable version tree over `parent_creation_id` and `lineage_index`.
- **Restyle.** `api/material-studio.js` re-skins a GLB without regenerating the mesh: an LLM proposes PBR factors from an instruction, applied server-side. The paid MCP `restyle_material` is a thin client over it.
@@ -54378,17 +56510,17 @@ Fast diagnostics: `forge_creations` carries per-generation backend, status, erro
## Related
-- [Forge](#sec-227), the product-level doc for the /forge surface.
-- [How the Forge works](#sec-241), the plain-language explainer.
+- [Forge](#sec-234), the product-level doc for the /forge surface.
+- [How the Forge works](#sec-250), 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-113), the selfie-to-avatar reconstruction flow.
-- [Background generation](#sec-224), job resume and gallery persistence.
+- [Avatar pipeline](#sec-115), the selfie-to-avatar reconstruction flow.
+- [Background generation](#sec-231), job resume and gallery persistence.
- `workers/README.md`, the worker-by-worker operational reference.
---
-<a id="sec-227"></a>
+<a id="sec-234"></a>
> **Source:** `docs/forge.md` · [↑ table of contents](#table-of-contents)
@@ -54597,16 +56729,16 @@ dashboard at [/quality-bench](https://three.ws/quality-bench) (internal).
## Related
-- [The Forge pipeline](#sec-226) is the architecture deep dive: the engine grid, routing, failover, job lifecycle, workers, and payments, end to end. [How the Forge works](#sec-241) is the same story in plain language.
-- [Image to 3D](#sec-254) is the photo lane opened directly at [/image-to-3d](https://three.ws/image-to-3d).
+- [The Forge pipeline](#sec-233) is the architecture deep dive: the engine grid, routing, failover, job lifecycle, workers, and payments, end to end. [How the Forge works](#sec-250) is the same story in plain language.
+- [Image to 3D](#sec-264) 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-178) forges a whole scene of Forge objects into one explorable world.
+- [Diorama](#sec-184) 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-228"></a>
+<a id="sec-235"></a>
> **Source:** `docs/forged.md` · [↑ table of contents](#table-of-contents)
@@ -54614,7 +56746,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-563). Nothing on the page is curated or seeded by
+[x402 payment protocol](#sec-589). 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
@@ -54642,11 +56774,12 @@ The page ([pages/forged.html](../pages/forged.html), rendered by
happen client-side over the loaded feed.
- **Designed empty, no-match, and error states.** The empty state explains that
the autonomous loop pays the Forge for a new prop every hour; the error state
- has a retry button.
+ names the reason the load failed (the API's own message) and has a retry
+ button.
## Where the assets come from
-The buyer is the platform's [autonomous x402 loop](#sec-105), the
+The buyer is the platform's [autonomous x402 loop](#sec-107), the
scheduled engine that pays real USDC to call the platform's own paid endpoints.
Its `forge` pipeline
([api/_lib/x402/pipelines/forge-content.js](../api/_lib/x402/pipelines/forge-content.js))
@@ -54664,7 +56797,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-560), and the loop's daily spend cap
+ [x402 ring economy](#sec-586), 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
@@ -54736,27 +56869,27 @@ Try it:
curl -s 'https://three.ws/api/forged?limit=5' | python3 -m json.tool
```
-The endpoint is also listed in the [API reference](#sec-096).
+The endpoint is also listed in the [API reference](#sec-098).
## Related
-- [Autonomous x402 loop](#sec-105): the engine that buys these
+- [Autonomous x402 loop](#sec-107): the engine that buys these
assets, its spend caps, and where every call is logged.
-- [x402 ring economy](#sec-560): the wider self-paid endpoint
+- [x402 ring economy](#sec-586): the wider self-paid endpoint
economy the seeder wallet participates in.
-- [How the Forge works](#sec-241): the generation pipeline the
+- [How the Forge works](#sec-250): the generation pipeline the
agents are paying for.
-- [x402 on three.ws](#sec-563): the payment protocol itself.
+- [x402 on three.ws](#sec-589): the payment protocol itself.
---
-<a id="sec-229"></a>
+<a id="sec-236"></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-230).
+Research catalog, 2026-08-05. Companion to [free-llm-providers.md](#sec-237).
**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.
@@ -54905,7 +57038,7 @@ Adoption rules that still apply: these are all free tiers, so no owner approval
---
-<a id="sec-230"></a>
+<a id="sec-237"></a>
> **Source:** `docs/free-llm-providers.md` · [↑ table of contents](#table-of-contents)
@@ -54921,10 +57054,10 @@ Free rungs run first, 70B-class models before smaller ones. A keyed rung is skip
| # | Rung | Model | Key | Free tier |
|---|------|-------|-----|-----------|
-| 1 | Groq | `llama-3.3-70b-versatile` | `GROQ_API_KEY` | Per-minute and per-day caps, no card. [console.groq.com](https://console.groq.com) |
+| 1 | Groq | `qwen/qwen3.8-27b` | `GROQ_API_KEY` | Per-minute and per-day caps, no card. Llama 3.x left Groq's catalog in August 2026; Qwen 3.8 27B is the fastest non-reasoning model left there. [console.groq.com](https://console.groq.com) |
| 2 | Cerebras | `llama-3.3-70b` | `CEREBRAS_API_KEY` | About 1M tokens/day. [cloud.cerebras.ai](https://cloud.cerebras.ai) |
| 3 | OpenRouter | `openai/gpt-oss-20b:free` | `OPENROUTER_API_KEY` (+ fallback keys) | `:free` models only; the platform key is never billed. [openrouter.ai](https://openrouter.ai) |
-| 4 | NVIDIA NIM | `meta/llama-3.3-70b-instruct` | `NVIDIA_API_KEY` | Free developer tier, about 40 req/min. [build.nvidia.com](https://build.nvidia.com) |
+| 4 | NVIDIA NIM | `nvidia/nemotron-3-super-120b-a12b` | `NVIDIA_API_KEY` | Free developer tier, about 40 req/min. `meta/llama-3.x` on NIM reached end of life on 2026-08-26 (HTTP 410); Nemotron 3 is a reasoning family, so the rung sends `enable_thinking: false` to keep the answer in `content`. [build.nvidia.com](https://build.nvidia.com) |
| 5 | SambaNova | `Meta-Llama-3.3-70B-Instruct` | `SAMBANOVA_API_KEY` | About 20 req/min, 200K tokens/day per model, no card. [cloud.sambanova.ai](https://cloud.sambanova.ai) |
| 6 | Mistral | `mistral-small-latest` | `MISTRAL_API_KEY` | Experiment tier: about 1B tokens/month at 1 req/sec (account opts into data training). [console.mistral.ai](https://console.mistral.ai) |
| 7 | Z.AI | `glm-4.7-flash` | `ZAI_API_KEY` | Permanently free, rate-limited Flash models. [z.ai](https://z.ai), docs at [docs.z.ai](https://docs.z.ai) |
@@ -54935,15 +57068,15 @@ Free rungs run first, 70B-class models before smaller ones. A keyed rung is skip
| 12 | Pollinations | `openai-fast` | none (keyless) | Anonymous, always on. |
| 13 | LLM7.io | `gemini-3.1-flash-lite` | none (keyless) | Anonymous, about 30 req/min per IP. |
| 14 | SiliconFlow | `Qwen/Qwen3-8B` | `SILICONFLOW_API_KEY` | Free-tier small model, own quota pool. [siliconflow.com](https://siliconflow.com) |
-| 15 | Groq instant | `llama-3.1-8b-instant` | `GROQ_API_KEY` | Separate per-model quota from rung 1. |
+| 15 | Groq instant | `openai/gpt-oss-20b` | `GROQ_API_KEY` | Separate per-model quota from rung 1. |
After rung 15 come the paid backstops (Vertex Claude, Anthropic, OpenAI, Grok), which never lead and which no flow depends on.
-The interactive chat ladder (`/api/chat`) uses: groq → openrouter → nvidia → sambanova → mistral → zai → paid backstops, with the Vertex Gemini anchor always appended at the tail. SambaNova, Mistral, and Z.AI are also selectable as explicit `provider` values in the chat API, and anonymous callers may use them.
+The interactive chat ladder (`/api/chat`) uses: groq → openrouter → nvidia → sambanova → mistral → zai → paid backstops, with the Vertex Gemini anchor always appended at the tail. SambaNova, Mistral, and Z.AI are also selectable as explicit `provider` values in the chat API, and anonymous callers may use them. When every anonymous-eligible free lane is throttled or in cooldown at once, `/api/chat` answers `503 rate_limited` ("The AI chat is at capacity right now") with a `Retry-After: 20` header and the `providers_tried` list, never a 401 asking a signed-out visitor to sign in for a throttle they cannot fix.
## Why so many
-Every rung is an independent quota pool on independent infrastructure. Free tiers throttle, retire models without notice (OpenRouter dropped its whole `:free` Llama roster in one day, GitHub Models was retired outright in 2026), and queue under load (NVIDIA NIM). One provider failing costs nothing; the chain moves on in under a second. The platform's baseline reliability is the product of how many independent free lanes stand between a request and an error.
+Every rung is an independent quota pool on independent infrastructure. Free tiers throttle, retire models without notice (OpenRouter dropped its whole `:free` Llama roster in one day, Groq and NVIDIA NIM both removed Llama 3.x in August 2026, GitHub Models was retired outright in 2026), and queue under load (NVIDIA NIM). One provider failing costs nothing; the chain moves on in under a second. The platform's baseline reliability is the product of how many independent free lanes stand between a request and an error.
Two providers were evaluated and deliberately excluded:
@@ -54967,11 +57100,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-304) for the full NVIDIA NIM surface map.
+Related: [nvidia-models.md](#sec-315) for the full NVIDIA NIM surface map.
---
-<a id="sec-231"></a>
+<a id="sec-238"></a>
> **Source:** `docs/galaxy.md` · [↑ table of contents](#table-of-contents)
@@ -54991,12 +57124,12 @@ A flat directory of agents tells you what exists but nothing about how they rela
The page ([`pages/galaxy.html`](../pages/galaxy.html)) loads [`src/galaxy.js`](../src/galaxy.js), a Three.js scene. The map itself is assembled server-side and cached.
1. **Collect agents.** `GET /api/galaxy` ([`api/galaxy.js`](../api/galaxy.js)) loads published agents from Postgres (`agent_identities` joined to `avatars`, filtered to published, described, named agents, ordered by chat count), default 600 and capped at 1200.
-2. **Embed.** Each agent's text (name, description, tone tags) is embedded with IBM Granite through [`api/_lib/watsonx.js`](../api/_lib/watsonx.js). The default model is `ibm/granite-embedding-278m-multilingual`, called at `POST {WATSONX_URL}/ml/v1/text/embeddings` with an IAM bearer token minted from the watsonx API key. Vectors are cached durably per agent (`agent_embeddings`), so only changed agents re-embed.
+2. **Embed.** Each agent's text (name, description, tone tags) is embedded with IBM Granite through [`api/_lib/watsonx.js`](../api/_lib/watsonx.js). The default model is `ibm/granite-embedding-278m-multilingual`, called at `POST {WATSONX_URL}/ml/v1/text/embeddings` with an IAM bearer token minted from the watsonx API key (the IAM exchange is idempotent and gets three attempts at 10 s; an inference call gets one attempt with a 45 s deadline). Vectors are cached durably per agent (`agent_embeddings`), so only changed agents re-embed.
3. **Project to 3D.** [`api/_lib/embedding-math.js`](../api/_lib/embedding-math.js) mean-centers the vectors, takes the top 3 principal components via power iteration (PCA, seeded and deterministic, not UMAP or t-SNE), whitens per axis, and maps them into a cube of half-width 120 world units. Determinism means cached rebuilds are stable.
4. **Cluster into constellations.** Seeded k-means (Lloyd's with k-means++ seeding) over L2-normalized vectors groups agents into `clamp(round(n/8), 2, 8)` clusters. Each cluster is labeled by Granite chat (`ibm/granite-3-8b-instruct`, with a same-family OpenRouter fallback).
5. **Render.** The client draws agents as a single `THREE.Points` cloud with a custom additive shader. Point size grows with chat count; a wealth glow (from real wallet net worth via `/api/agents/networth`) biases funded stars toward a violet tint. `OrbitControls` gives drag-to-orbit, scroll-to-zoom, and gentle auto-rotate that pauses on interaction. A raycaster powers hover tooltips.
-6. **Inspect.** Clicking a star opens an in-scene card with the agent's thumbnail, constellation, description, and meta chips (net worth, chat count, token), plus two actions: "View agent" (`/agents/:id`) and "Chat" (`/agent/:id`).
-7. **Search.** The search box POSTs `{ query }` to `/api/galaxy`, which embeds the query with the same Granite model and ranks stored agent vectors by cosine similarity. The client highlights matches and flies the camera to the best one.
+6. **Inspect.** Clicking a star opens an in-scene card with the agent's thumbnail, constellation, description, and meta chips (net worth, chat count, token), plus two actions: "View agent" and "Chat", both on the canonical `/agents/:id` route.
+7. **Search.** The search box POSTs `{ query }` to `/api/galaxy`, which embeds the query with the same Granite model and ranks stored agent vectors by cosine similarity (`ranking: "semantic"`). The client highlights matches and flies the camera to the best one. When the embedder cannot answer (unreachable, or no vector returned) there is deliberately no other embedding lane to fall back to, because the stored vectors live in Granite's space and a vector from another model would be compared in a different geometry; instead the same corpus is ranked lexically ([`api/_lib/lexical-rank.js`](../api/_lib/lexical-rank.js)) and the response says so with `ranking: "lexical"` and `degraded: { reason: "embedder_unavailable", detail, retryable: true }`, so a search still returns useful matches rather than a `502`.
Only projected coordinates and cluster centroids are sent to the browser; raw high-dimensional vectors never leave the server.
@@ -55031,8 +57164,12 @@ curl -X POST 'https://three.ws/api/galaxy' \
# "query": "an agent that trades solana memecoins",
# "model": "ibm/granite-embedding-278m-multilingual",
# "count": 12,
-# "results": [ { "id": "…", "name": "…", "description": "…", "thumbnail": "…", "score": 0.742 } ]
+# "results": [ { "id": "…", "name": "…", "description": "…", "thumbnail": "…", "score": 0.742 } ],
+# "ranking": "semantic"
# }
+# When Granite cannot embed the query the same call answers 200 with
+# "ranking": "lexical", a "lexicalScore" per result, and
+# "degraded": { "reason": "embedder_unavailable", "detail": "…", "retryable": true }.
```
`GET /api/galaxy` accepts `?refresh=1` to force a rebuild and `?limit=<n>` (default 600, max 1200). `POST /api/galaxy` takes `{ query, limit? }` (query trimmed to 200 chars, up to 30 results). Rankings apply a minimum similarity of 0.05.
@@ -55040,7 +57177,7 @@ curl -X POST 'https://three.ws/api/galaxy' \
## States and limits
- **No auth.** Both endpoints are public and read-only, guarded by a per-IP rate limit. Embedding cost is bounded by design: agents embed once into the durable cache and map builds are snapshot-cached, so only a search query triggers a fresh Granite call.
-- **watsonx required.** With no credentials the endpoint returns `503 watsonx_unavailable` and the page shows "IBM Granite isn't connected" (no retry). Configure `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` to light it up.
+- **watsonx required.** With no credentials the endpoint returns `503 watsonx_unavailable` and the page shows "IBM Granite isn't connected" (no retry). Configure `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` to light it up. With credentials present but Granite failing on a search, the query degrades to lexical ranking as described above instead of erroring.
- **Caching.** Three layers: a `galaxy_snapshots` server snapshot (6-hour TTL, with warm-instance rebuild coalescing), the durable per-agent `agent_embeddings` cache, and a 60-second cache on the published-agent query. Pass `?refresh=1` to bypass the snapshot.
- **Population.** However many published agents exist, capped by the limit. There is no fixed count.
- **Empty state.** With zero published agents the page shows "The galaxy is still forming" and a "Create an agent" CTA to `/create`.
@@ -55049,13 +57186,13 @@ curl -X POST 'https://three.ws/api/galaxy' \
## Related
-- [IBM Granite suite](#sec-253): 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.
+- [IBM Granite suite](#sec-263): the full set of watsonx-powered features on three.ws, including the Granite embeddings that position this galaxy.
+- [Agent system](#sec-065) and [Agent reputation](#sec-057): 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-232"></a>
+<a id="sec-239"></a>
> **Source:** `docs/generation-watch.md` · [↑ table of contents](#table-of-contents)
@@ -55076,7 +57213,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-138). Fast generations
+[three.ws 3D Studio custom GPT](#sec-141). 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:
@@ -55111,7 +57248,7 @@ The page polls `GET /api/3d/studio?job=<id>` and moves through five 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-241).
+ [How the Forge works](#sec-250).
- **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
@@ -55157,23 +57294,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-224).
+[Background generation and completion notifications](#sec-231).
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-241): the pipeline behind the
+- [How the Forge works](#sec-250): the pipeline behind the
countdown.
-- [Background generation](#sec-224): server-side
+- [Background generation](#sec-231): server-side
tracking, resume, and notifications.
-- [The 3D Studio GPT](#sec-138): the main surface that hands
+- [The 3D Studio GPT](#sec-141): the main surface that hands
out watch links.
-- [API reference](#sec-096): the full `/api/3d/studio` contract.
+- [API reference](#sec-098): the full `/api/3d/studio` contract.
---
-<a id="sec-233"></a>
+<a id="sec-240"></a>
> **Source:** `docs/genesis.md` · [↑ table of contents](#table-of-contents)
@@ -55198,8 +57335,8 @@ Genesis collapses that into a single guided flow with a real progress bar driven
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-234), and every embed surface.
+into [Agent Studio](#sec-063), the [economy](#sec-106),
+[breeding](#sec-241), and every embed surface.
## How it works
@@ -55220,7 +57357,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-171)),
+ the agent (see [Agent Wallets](#sec-074) and [Custody](#sec-177)),
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
@@ -55233,7 +57370,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-189) identity record for the agent and returns a real tx
+ [ERC-8004](#sec-195) 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.
@@ -55254,15 +57391,15 @@ never invents a shortcut path; it orchestrates the real ones.
your prompt; edit the name and pick a voice, then save.
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-257), or breed
- it in [Agent Genome](#sec-234).
+7. **You now own a complete agent.** Open it in [Agent Studio](#sec-063) to
+ keep authoring, drop it on a site via [Integrations](#sec-267), or breed
+ it in [Agent Genome](#sec-241).
## Examples
Genesis is a browser flow, but its endpoints are the public agent APIs. This drives
the same body-generation step from a script (see
-[API reference](#sec-096) and [Authentication](#sec-103) for
+[API reference](#sec-098) and [Authentication](#sec-105) for
the session cookie or bearer token):
```bash
@@ -55313,17 +57450,17 @@ 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-234): breed two agents into an inherited child
-- [Avatar Reconstruction](#sec-114): the selfie-to-3D pipeline
-- [Agent Wallets](#sec-072) and [Custody](#sec-171): the custodial keys
-- [ERC-8004](#sec-189): the on-chain identity record
-- [Persona Hub](#sec-334): how personas are synthesized
+- [Agent Studio](#sec-063): keep authoring the agent Genesis created
+- [Agent Genome](#sec-241): breed two agents into an inherited child
+- [Avatar Reconstruction](#sec-116): the selfie-to-3D pipeline
+- [Agent Wallets](#sec-074) and [Custody](#sec-177): the custodial keys
+- [ERC-8004](#sec-195): the on-chain identity record
+- [Persona Hub](#sec-346): 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-234"></a>
+<a id="sec-241"></a>
> **Source:** `docs/genome.md` · [↑ table of contents](#table-of-contents)
@@ -55364,6 +57501,9 @@ parents and the same seed it always derives the identical child.
mutate; pitch blends within a bounded range. The dominant `voice_id` comes from
whichever parent carries a real cloned or ElevenLabs voice, and the child's blended
settings are genuinely synthesized through `/api/tts/eleven`, not just labelled.
+ There is no free platform TTS lane: a preview clip bills the listener's prepaid
+ credit wallet, or their own ElevenLabs key when one is saved (see
+ [Voice Lab](#sec-541)).
- **Body.** Morph targets and colors blend; accessories and hidden parts recombine as
sets. At breed time the dominant parent's GLB is copied into the child's namespace
and the inherited appearance is baked into a real composite child GLB.
@@ -55380,12 +57520,17 @@ parents and the same seed it always derives the identical child.
hash, generation, and pedigree tier. `verifyGenome` re-derives the child from the
recorded seed plus the parent-genome snapshots captured at breed time and confirms
the stored hash matches. Breeding is idempotent per `(parents, seed)` key: replaying
- the same pairing returns the same child instead of minting twins.
+ the same pairing returns the same child (HTTP 200 with `deduped: true`) instead of
+ minting twins, and two concurrent commits of the same key race on the unique
+ breeding key, with the loser's provisional child retired and the winner's returned.
## Walkthrough
1. **Open [/genome](https://three.ws/genome).** Your agents load from `/api/agents`;
- public studs load from `/api/genome/stud`.
+ public studs load from `/api/genome/stud`. The **Your stud listings** section at
+ the bottom lists or unlists your own agents and sets their `$THREE` stud fee
+ (`POST /api/genome/stud`, owner-only; it has PATCH semantics, so sending only a
+ new fee keeps the listing open rather than silently unlisting the agent).
2. **Pick two parents.** Choose two agents you own, or pair one of yours with a
public stud. An agent cannot breed with itself.
3. **Preview the offspring.** `POST /api/genome/preview` derives the child
@@ -55405,7 +57550,7 @@ parents and the same seed it always derives the identical child.
## Examples
Preview a pairing (read-only, nothing minted). See
-[Authentication](#sec-103) for the token or session cookie:
+[Authentication](#sec-105) for the token or session cookie:
```bash
curl -s -X POST https://three.ws/api/genome/preview \
@@ -55441,11 +57586,17 @@ curl -s "https://three.ws/api/genome/lineage?agentId=<child-uuid>&verify=1"
- **Breeding cooldown.** A parent can breed at most once per 6-hour window
(`BREED_COOLDOWN_MS`). Breeding a parent still on cooldown returns HTTP 409
`breeding_cooldown` with the remaining minutes. Cooldowns keep deep pedigrees
- scarce.
+ scarce. The cooldown is checked before the stud fee gate, so a breeding that will
+ be refused never takes a real payment first.
- **Stud fee settlement.** When a stud fee applies and no valid payment signature is
- attached, `/api/genome/breed` returns HTTP 402 with the required `$THREE` amount.
- Presence of a signature is not proof of payment; the fee must actually land in the
- stud's payout wallet, and a single payment cannot be reused across breedings.
+ attached, `/api/genome/breed` returns HTTP 402 `stud_fee_required` with the
+ required `$THREE` amount (`stud_fee_unverified` when a signature is present but the
+ fee did not land). Presence of a signature is not proof of payment; the fee must
+ actually land in the stud's payout wallet, and a single payment cannot be reused
+ across breedings: a unique index on `stud_fee_signature` makes the replay check
+ atomic, and a reused signature returns HTTP 409 `stud_fee_replayed`. Paid
+ breedings record the settled amount as `stud_fee_atomics` on the `genome_breedings`
+ row.
- **Determinism.** Same parents plus same seed always yields the same child. Change
the seed and you get a different (still valid) draw.
- **Graceful birth.** A copy or bake hiccup never blocks the birth; the child still
@@ -55456,16 +57607,16 @@ curl -s "https://three.ws/api/genome/lineage?agentId=<child-uuid>&verify=1"
## Related
-- [Instant Agent Genesis](#sec-233): 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-189): on-chain identity for bred agents
+- [Instant Agent Genesis](#sec-240): mint the parents in under a minute
+- [Agent Skills](#sec-061): the skill licenses that recombine
+- [Agent Wallets](#sec-074): the fresh child wallet
+- [Agent Reputation](#sec-057): how pedigree feeds standing
+- [ERC-8004](#sec-195): on-chain identity for bred agents
- Pages: [/genome](https://three.ws/genome), [/agent-studio](https://three.ws/agent-studio)
---
-<a id="sec-235"></a>
+<a id="sec-242"></a>
> **Source:** `docs/ghost-copy.md` · [↑ table of contents](#table-of-contents)
@@ -55625,7 +57776,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-166) for that engine.
+ [docs/copy-trading.md](#sec-171) for that engine.
- A leader's underlying record: `/trader/<agent_id>`, one click from every result.
## Source
@@ -55640,7 +57791,7 @@ renders the summary without it is misrepresenting the result.
---
-<a id="sec-236"></a>
+<a id="sec-243"></a>
> **Source:** `docs/github-memory-seeding.md` · [↑ table of contents](#table-of-contents)
@@ -55667,7 +57818,7 @@ 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`, `/api/auth/github/token`
-- **Related**: [Memory system](#sec-287), [X memory seeding](#sec-530), [Farcaster memory seeding](#sec-221)
+- **Related**: [Memory system](#sec-296), [X memory seeding](#sec-553), [Farcaster memory seeding](#sec-227)
---
@@ -55730,7 +57881,7 @@ selection, so the promise and the code cannot drift apart.
| Stored on the agent | Never stored |
|---|---|
-| Up to 20 short distilled facts (max 600 characters each) about what you build, your stack, and how you describe your work | Repository file contents beyond the README excerpt |
+| Up to 20 short distilled facts (max 600 characters each) about what you build, your stack, and how you describe your work | Repository file contents beyond the README excerpt (the first 8,000 characters of a ticked README) |
| Your GitHub handle and the exact selection manifest (profile on/off, repo keys, README keys) on every seeded row | Any GitHub credential; the access token stays HKDF-encrypted in the connection record and is never copied into a memory |
## What lands in memory
@@ -55877,8 +58028,8 @@ curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/github --cookie "$JAR"
### `POST /api/agents/:id/memory/seed/github`
Seed from a selection. `repos` and `readmes` are `owner/name` keys from the
-catalog; a README key must also appear in `repos`. An empty selection is
-refused (`400 empty_selection`).
+catalog, at most 12 in each list; a README key must also appear in `repos`. An
+empty selection is refused (`400 empty_selection`).
```bash
curl -s https://three.ws/api/agents/$AGENT_ID/memory/seed/github --cookie "$JAR" \
@@ -55925,6 +58076,7 @@ because no API can delete a personal access token using that token.
| `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` |
+| `validation_error` | 400 | The body failed schema validation: more than 12 `repos` or `readmes`, a key that is not `owner/name`, or (on `/api/auth/github/token`) a pasted string that is not shaped like a GitHub token |
| `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 |
@@ -55965,7 +58117,188 @@ rather than inviting a retry that would only earn a 429.
---
-<a id="sec-237"></a>
+<a id="sec-244"></a>
+
+> **Source:** `docs/glance.md` · [↑ table of contents](#table-of-contents)
+
+# Glance: your agent on every home screen
+
+A **glance card** is one three.ws agent reduced to what fits in a slot: who it is, one live number, and a way back in. The same card renders on the Windows 11 widgets board, in a GitHub README, in a Slack message, on any web page, and in your terminal, from one public endpoint.
+
+Try it: [three.ws/glance](https://three.ws/glance).
+
+This is a different product from the [embeddable 3D widgets](https://three.ws/widgets). Those put your agent's **body** on a page. Glance puts your agent's **status** on a surface that cannot run WebGL, which is every operating system widget host there is.
+
+---
+
+## The fastest version
+
+An image, anywhere an image goes:
+
+```
+https://three.ws/api/glance/card?agent=<agent-id>&format=svg
+```
+
+```markdown
+[![My agent](https://three.ws/api/glance/card?agent=<agent-id>&format=svg)](https://three.ws/agents/<agent-id>)
+```
+
+A live card on a page:
+
+```html
+<script type="module" src="https://three.ws/glance/element.js"></script>
+<agent-glance agent="<agent-id>"></agent-glance>
+```
+
+In your terminal:
+
+```bash
+npx @three-ws/agent-glance <agent-id> --watch 60
+```
+
+Your agent id is the uuid in the URL of its profile page: `https://three.ws/agents/<agent-id>`.
+
+---
+
+## What is on the card
+
+Everything comes from real platform state. There is no sample card and no placeholder number.
+
+| Field | Where it comes from |
+| --- | --- |
+| `name`, `description` | `agent_identities` |
+| `image` | the agent's avatar thumbnail, **only** when that avatar is public or unlisted; otherwise `null` and the card draws a generated monogram |
+| `metric` | actions in the last 24 hours ("Moves today") |
+| `stats` | actions this week, actions all time, then skills (or days live when the agent has no skills yet) |
+| `lastAction` | the most recent entry in the agent's action log, with a relative time |
+| `status` | `active` (acted in the last 24h), `idle` (has acted, not today), `new` (has never acted) |
+| `headline` | the one-line state, written for the status: a `new` agent's card says what to do next rather than showing a bare zero |
+| `accent` | a stable colour pair derived from the agent id, so a card without a thumbnail still looks like that specific agent |
+
+The wire format is pinned in [specs/GLANCE_CARD.md](https://github.com/nirholas/three.ws/blob/main/specs/GLANCE_CARD.md).
+
+---
+
+## The endpoint
+
+### `GET /api/glance/card`
+
+Public, cacheable, side-effect free, no session required.
+
+| Parameter | Values | Default |
+| --- | --- | --- |
+| `agent` | agent uuid (required) | |
+| `format` | `json`, `svg`, `png`, `adaptive` | `json` |
+| `size` | `small` (240x240), `medium` (480x200), `large` (480x300). SVG and PNG | `medium` |
+| `theme` | `auto`, `light`, `dark`. SVG and PNG (`auto` renders dark as PNG) | `auto` |
+| `scale` | `1`, `2`, `3`: pixel density. PNG only | `2` |
+
+```bash
+curl -s "https://three.ws/api/glance/card?agent=<agent-id>" | jq '.metric'
+# { "label": "Moves today", "value": 17 }
+```
+
+The response carries an `ETag`; send it back as `if-none-match` and you get a `304`. Cards are cached for two minutes at the edge and served stale for ten while revalidating, so a widget board polling every fifteen minutes almost never touches the database.
+
+`theme=auto` puts both palettes inside the SVG behind a `prefers-color-scheme` media query, which GitHub and Slack both honour, so one URL is correct in light mode and dark mode.
+
+A missing agent answers `404` with a real card that says so, not a broken image. That matters when the card is sitting in someone's home screen slot.
+
+`format=png` is the same card as a bitmap, for hosts that cannot draw SVG (Android's RemoteViews, WidgetKit, chat clients that only unfurl raster images). It is rasterized with sharp from the SVG, cached in object storage per agent, size, theme and density, and re-rendered only when the card's ETag changes.
+
+### `GET /api/glance/mine`
+
+The caller's own agent, plus the list of agents they own so a widget can be pointed at a different one. Two ways to say who is asking: the session cookie (what the Windows widget worker sends), or a widget token as `Authorization: Bearer glw_…` (what a native widget sends, because it has no session; see [native-widgets.md](native-widgets.md#how-the-widget-authenticates)).
+
+Every state is a `200` with a designed card, never a `401`: a widget that renders an error is a widget people remove. `state` is one of `agent`, `signed-out`, `unlinked` (a revoked or unknown token), or `no-agent`; for the three non-agent states `card` is `null` and `notice` carries a card that says what to do next, with a tap target that does it.
+
+`format=png` (with `size`, `theme`, `scale` as above) returns the bitmap for whichever state applies, with `x-glance-state`, `x-glance-url` (the tap target), `x-glance-name`, `x-glance-metric` and `x-glance-agent` in the headers, so a native widget learns everything from the one request that fetched the image.
+
+### `POST | GET | PATCH | DELETE /api/glance/token`
+
+The widget tokens. Session and same-site only. `POST { label?, platform?, agent? }` mints one and answers the plaintext exactly once, plus `links.android`, the `intent://` URL that hands it to the Android app. `GET` lists the caller's live tokens (prefix, label, platform, last seen), `PATCH { id, agent }` repoints one, `DELETE ?id=` revokes one. The revoke list on [/glance](https://three.ws/glance#devices) is this endpoint.
+
+### `GET /api/glance/template`
+
+The Adaptive Card template (version 1.6) that the Windows widgets board binds `/api/glance/mine` data to. `format=adaptive` on the card endpoint returns the same layout already bound, for hosts that do not template.
+
+---
+
+## On the Windows 11 widgets board
+
+three.ws declares a `widgets` member in its PWA manifest, so the widget installs with the app: no store submission, no separate download.
+
+1. Open [three.ws](https://three.ws) in Edge and install it (the install icon in the address bar).
+2. Open the widgets board (`Win + W`) and choose **Add widgets**.
+3. Pick **Agent glance**.
+
+The board then talks to the site's service worker, which supplies the data:
+
+| Event | What happens |
+| --- | --- |
+| `widgetinstall` | fetch `/api/glance/mine`, push it into the host |
+| `widgetresume` | render from the cached payload, then refresh |
+| `widgetclick` | refresh on demand |
+| `widgetuninstall` | drop the cached payload |
+| `periodicsync` | refresh every pinned widget on the platform's schedule |
+
+Two behaviours are deliberate: signed out renders a sign-in card rather than an error, and an offline machine renders the last card it saw, labelled `(offline)`, rather than an empty slot. The implementation is [public/glance-sw.js](https://github.com/nirholas/three.ws/blob/main/public/glance-sw.js), covered by `tests/glance-sw.test.js`.
+
+---
+
+## The `<agent-glance>` element
+
+```html
+<script type="module" src="https://three.ws/glance/element.js"></script>
+<agent-glance agent="<agent-id>" size="medium" theme="auto" refresh="300"></agent-glance>
+```
+
+| Attribute | Values | Default |
+| --- | --- | --- |
+| `agent` | agent uuid (required) | |
+| `size` | `small`, `medium`, `large` | `medium` |
+| `theme` | `auto`, `light`, `dark` | `auto` |
+| `refresh` | seconds between refreshes, `0` disables | `300` |
+| `origin` | override the API origin | `https://three.ws` |
+
+It is real DOM inside a shadow root, so it is selectable, focusable and readable by a screen reader, and it cannot inherit or leak your page's CSS. It draws a skeleton while loading, a retry affordance on failure, and keeps the last good card if a later refresh fails. It stops polling entirely while the tab is hidden or the element is off screen.
+
+Two events bubble: `glance:load` (detail is the card) and `glance:error` (detail is the error).
+
+---
+
+## The npm client
+
+```bash
+npm install @three-ws/agent-glance
+```
+
+```js
+import { fetchGlanceCard, glanceImageUrl, glanceMarkdown } from '@three-ws/agent-glance';
+
+const card = await fetchGlanceCard(id);
+console.log(`${card.name}: ${card.metric.value} ${card.metric.label.toLowerCase()}`);
+```
+
+Zero dependencies, bounded deadlines on every call, and a `GlanceError` that carries `status` and `agentId`. An id that is not a uuid throws before any network call, so a typo fails at build time rather than rendering a broken image forever. Full reference: [packages/agent-glance/README.md](https://github.com/nirholas/three.ws/blob/main/packages/agent-glance/README.md).
+
+---
+
+## On an Android home screen
+
+The three.ws Android app (1.1 and later) ships an **Agent glance** home screen widget: link the phone from [/glance](https://three.ws/glance#android), then add the widget from the launcher's picker. It fetches `/api/glance/mine?format=png` with its own token through WorkManager, keeps the last card when offline, and opens the agent on tap. Sizes, states, revocation and the native sources are all in [native-widgets.md](native-widgets.md#android).
+
+---
+
+## Where this is going
+
+Glance is phase 5 of the [roadmap](https://github.com/nirholas/three.ws/blob/main/README.md#roadmap). Windows 11, Android and the web are live. macOS and iOS follow through a shared WidgetKit extension against the same PNG endpoint and the same widget token; the scoped work order is [prompts/roadmap/native-widgets.md](https://github.com/nirholas/three.ws/blob/main/prompts/roadmap/native-widgets.md).
+
+Every one of those surfaces consumes the endpoint documented above. The card is the contract; the hosts are just slots.
+
+---
+
+<a id="sec-245"></a>
> **Source:** `docs/google-x-accounts.md` · [↑ table of contents](#table-of-contents)
@@ -56077,7 +58410,7 @@ Google also operates many country and regional accounts (for example @GoogleIndi
---
-<a id="sec-238"></a>
+<a id="sec-246"></a>
> **Source:** `docs/guardian.md` · [↑ table of contents](#table-of-contents)
@@ -56103,7 +58436,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-171)) are enforced by the recovery API, not the console:
+**The safety rails** (detailed in [custody](#sec-177)) 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).
@@ -56156,14 +58489,14 @@ The console reads this on load, resolves your viewer id (so it can tell whether
## Related
-- [Custody you can verify](#sec-171) - the full recovery and inheritance model, the freeze switch, spend limits, and proof-of-custody
-- [Financial controls](#sec-222) - the plain-English spend rules on the same wallet rails
+- [Custody you can verify](#sec-177) - the full recovery and inheritance model, the freeze switch, spend limits, and proof-of-custody
+- [Financial controls](#sec-229) - 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-239"></a>
+<a id="sec-247"></a>
> **Source:** `docs/guards.md` · [↑ table of contents](#table-of-contents)
@@ -56260,10 +58593,12 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Merge-conflict markers | `npm run check:conflicts` | No unresolved conflict marker can be built or deployed. |
| CLAUDE.md truth check | `npm run check:claude` | Every script, path, count, and runbook step named in CLAUDE.md matches the repo. |
| Vendored worker modules | `npm run check:vendored` | Every copy of a shared worker module (`worker_security.py`, `oin.py`, `oin_upload.py`, `gltf_meshopt.py` and its test) is byte-identical across all workers. |
+| No unbounded outbound call | `npm run check:fetch-timeouts` | Every fetch to a third-party host carries a deadline, so one stalled upstream cannot hold a request until the platform kills it. |
| Hard rules, diff scoped | `npm run check:rules` | The CLAUDE.md hard rules on the lines you changed. |
| The guard registry | `npm run audit:guards` | Every guard is registered and every stage claim is true. |
| Design-token ratchet | `npm run audit:tokens` | Hardcoded colour hexes cannot creep back past a committed baseline. |
| Credential material | `npm run check:secrets` | No dotenv file, private key, keystore, or downloaded cloud credential becomes a tracked file, and no added line carries a provider-issued key. |
+| iOS app icon | `npm run check:ios-icons` | The committed iOS icon and launch images are exactly what the current brand mark produces, and the icon carries no alpha channel. |
### Routing and pages
@@ -56282,6 +58617,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Guard | Command | Protects |
|---|---|---|
| Documentation integrity | `npm run audit:docs` | No dead relative link, no command naming a missing script, no package without a README. |
+| Upstream resilience ratchet | `npm run audit:upstreams` | No new call to a third-party service without a deadline, and no existing one quietly getting weaker. |
| Tutorial reachability | `npm run check:tutorials` | Every tutorial appears in the library manifest, has its markdown on disk, and is registered in `data/pages.json`. |
| Runnable doc samples | `npm run check:runnable-docs` | Every sample a reader can press Run on still returns what the doc says it returns. |
| Doc figures | `npm run check:doc-media` | Every figure a doc points at was really captured, still matches its recipe, and carries alt text. |
@@ -56412,7 +58748,291 @@ The short version:
---
-<a id="sec-240"></a>
+<a id="sec-248"></a>
+
+> **Source:** `docs/herald.md` · [↑ table of contents](#table-of-contents)
+
+# Herald: deliver a message in person
+
+A notification is a badge you have to notice, in a tray you have to open,
+competing with forty others. Herald is the opposite: a 3D character walks into
+the corner of the page, looks at the person using it, and tells them, with a
+link to the thing it is about.
+
+It ships as four pieces that work independently and compose:
+
+| Piece | Where | What it is |
+| --- | --- | --- |
+| The library | [`herald-sdk/`](../herald-sdk/README.md), published as `@three-ws/herald` | The rules engine and the presenters. Works on any site, with or without a bundler. |
+| The rail | `POST /api/herald/announce`, `GET /api/herald/stream` | Anything that can make an HTTPS request reaches the browser tab you have open. |
+| The CLI | `npx @three-ws/herald` | `herald watch -- npm test` announces when your build finishes. |
+| The MCP server | [`packages/herald-mcp/`](../packages/herald-mcp/README.md) | An AI agent tells its human something in person. |
+
+Try all of it at [three.ws/herald](https://three.ws/herald), which runs the real
+library in your own tab: change the rules, send a message, and watch the engine
+decide.
+
+three.ws delivers its own notifications the same way. That path has its own
+client ([src/notification-herald.js](../src/notification-herald.js), wired to
+the bell inbox and gated by the per-category `avatar` channel in the preference
+center, see
+[Notifications](notifications.md#the-avatar-channel-delivered-in-person)), and
+it shares this one's body: both hand the line to the walk companion's
+`announce()`. The library here is the general form, for any site and any feed.
+
+---
+
+## The idea
+
+Every alerting surface we have is a queue competing for the same half-second of
+attention: a red dot, a rectangle that slides in, a phone buzz. They are the
+same shape, they are all ignorable, and the important ones look exactly like the
+noise.
+
+A person walking up to your desk is not ignorable, and nobody has to design an
+unread state for it. Herald is that, on the web, for the handful of events per
+day that deserve it. Everything in the library exists to keep the interruption
+rare enough to stay effective, which is why most of this page is about what it
+refuses to deliver.
+
+## Quick start
+
+```sh
+npm install @three-ws/herald
+# optional: the 3D body. Without it, deliveries use the accessible card.
+npm install @three-ws/walk three
+```
+
+The avatar presenter finds a companion in three places, cheapest first: one you
+pass in (`createHerald({ companion })`), one already live on the page
+(`window.__walkCompanion`, which is what every three.ws page has), or a module
+URL you name (`avatarOptions: { walkModule: '/walk-companion.js' }`). None of
+them is a static import, so the optional 3D body can never break a build.
+
+```js
+import { createHerald } from '@three-ws/herald';
+
+const herald = createHerald({
+ rules: { minImportance: 70, quietHours: [22, 7] },
+ voice: 'auto',
+});
+
+herald.announce({
+ text: 'Payment received from Acme',
+ from: 'Stripe',
+ importance: 85,
+ url: '/payments/inv_123',
+});
+```
+
+With no bundler at all:
+
+```html
+<script type="module">
+ import { createHerald } from 'https://three.ws/herald.js';
+ createHerald().announce('Deployed to production');
+</script>
+```
+
+`/herald.js` is served with permissive CORS, exactly like the `<agent-3d>`
+bundle, so it can be imported from any origin.
+
+## What it refuses to deliver
+
+`announce()` returns a verdict rather than a promise of delivery, and every
+message that does not reach a human comes back with a reason.
+
+```js
+herald.announce({ text: 'someone viewed your profile', importance: 10 });
+// { action: 'drop', reason: 'below-importance-floor', message: {...} }
+```
+
+**Dropped** (will never be delivered): `empty`, `muted`, `duplicate`, `stale`,
+`below-importance-floor`.
+
+**Held** (delivered once the thing blocking it clears): `delivering-another`,
+`window-not-focused`, `rate-limited`, `quiet-hours`.
+
+Held messages are re-examined when the rate window drains, quiet hours end, or
+the tab comes back. A burst past `batchSize` is collapsed: the most important
+few are said, and the rest become one "N more messages waiting" line.
+
+| Rule | Default | What it does |
+| --- | --- | --- |
+| `minImportance` | `50` | The interrupt floor. |
+| `freshnessMs` | `15 min` | Older than this is history, and history belongs in an inbox. |
+| `dedupeTtlMs` | `6 h` | The same key is said once, however often a feed repeats it. |
+| `quietHours` | `null` | Local `[start, end)`, wrapping past midnight. |
+| `quietHoursMinImportance` | `90` | What still gets through the night. |
+| `maxPerWindow` / `rateWindowMs` | `4` / `60 s` | The rate limit on interruptions. |
+| `focusOnly` | `true` | Hold while the tab is in the background. |
+| `batchSize` | `2` | Said per burst before the rest collapse. |
+
+Scoring is pluggable, and the highest opinion wins:
+
+```js
+herald.rule((m) => (m.from === 'oncall' ? 100 : undefined));
+herald.rule((m) => (/\bfailed\b/i.test(m.text) ? 90 : undefined));
+```
+
+## Sources
+
+A source is `{ name, start(emit) => stop }`. Three ship with the library, and
+writing one for a feed nobody here has heard of is about five lines.
+
+```js
+import { createHerald, pollSource, sseSource, railSource } from '@three-ws/herald';
+
+const herald = createHerald();
+
+// Any JSON endpoint. Polling stops while the tab is hidden.
+herald.source(pollSource({
+ url: '/api/alerts',
+ intervalMs: 30_000,
+ map: (a) => ({ id: a.id, text: a.title, importance: a.severity * 20, url: a.link }),
+}));
+
+// Any EventSource endpoint.
+herald.source(sseSource({ url: '/events', events: ['alert'] }));
+
+// The three.ws rail (below).
+herald.source(railSource());
+```
+
+## The rail
+
+The rail is what lets something with no browser (a deploy script, a cron, a CI
+job, an AI agent) reach the browser a person is actually looking at.
+
+### Announce
+
+```http
+POST /api/herald/announce
+Authorization: Bearer sk_live_... # or a signed-in session cookie
+Content-Type: application/json
+
+{ "text": "Deploy is green", "importance": 80, "url": "/dashboard", "from": "CI" }
+```
+
+```json
+{
+ "queued": true,
+ "id": "6a293426-8f48-4254-bc14-cef9ada17680",
+ "expires_in": 300,
+ "announcement": { "id": "...", "text": "Deploy is green", "importance": 80, "tone": "alert", "at": 1787888380209 }
+}
+```
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `text` (or `message`) | string, 1-280 | Required. Written as speech, not as a log line. |
+| `from` | string, max 60 | Spoken as attribution. |
+| `importance` | int 0-100 | Default 70. The receiving client applies its own floor. |
+| `url` | string | Same-origin path or absolute `http(s)`. Anything else is dropped. |
+| `tone` | `neutral` \| `alert` \| `celebrate` \| `error` | Default `alert`. |
+| `emote` | string | `wave`, `dance`, `punch`, `backflip`. |
+| `key` | string, max 120 | Dedupe key: two announcements sharing one are said once. |
+| `meta` | object | Returned untouched to the client's callbacks. |
+
+`202` means queued for a live surface, not heard by a human: nothing on the
+server can promise the second thing.
+
+**Addressing is the security model.** An announcement always goes to the
+authenticated caller's own sessions. There is no recipient field, so a key
+cannot be used to interrupt anybody else, and the worst a leaked key can do is
+annoy the person who leaked it. Keys are minted at
+[/dashboard/developers](https://three.ws/dashboard/developers) with the
+`herald:announce` scope and revoked in the same place.
+
+### Listen
+
+```http
+GET /api/herald/stream # session cookie only
+```
+
+Server-sent events: `open` once, then one `announce` per queued line, with a
+`ping` every 15 seconds. The queue is drained (not broadcast), so a message is
+said by exactly one open tab. An undelivered line expires in about five minutes:
+this is a live channel, and the durable record is the notification bell.
+
+Rate limits: 60 announces per minute per account, 60 stream connections per five
+minutes.
+
+## The CLI
+
+```sh
+export THREE_WS_API_KEY=sk_live_... # herald:announce scope
+
+herald say "Migration finished" --from db --url https://three.ws/dashboard
+herald watch --from CI -- npm test
+herald ping
+```
+
+`watch` runs the command with its stdio attached, keeps its exit code, times it,
+and announces the outcome (`CI passed in 2m`, `CI failed (exit 1) after 47s`).
+Failures arrive at importance 95 so they cut through quiet hours; successes at
+60 so they do not. Because the exit code is preserved, it drops into a pipeline
+unchanged:
+
+```sh
+herald watch -- npm test && npm run deploy
+```
+
+## From an AI agent
+
+```sh
+claude mcp add herald -e THREE_WS_API_KEY=sk_live_... -- npx -y @three-ws/herald-mcp
+```
+
+Three tools: `announce` (say one line), `announce_result` (report a finished
+task, with the urgency chosen from the outcome), and `check_rail` (prove the key
+works without interrupting anyone). Full reference in
+[packages/herald-mcp](../packages/herald-mcp/README.md).
+
+This is the piece that changes how a long agent run feels: the agent works for
+twenty minutes while you do something else, and then your own avatar walks on
+and tells you it is done.
+
+## Accessibility
+
+The avatar is the point, but it is never the requirement.
+
+- No WebGL, an iframe, a route that already owns the corner: the card presenter
+ takes over. It is theme-aware, honours `prefers-reduced-motion` and
+ `prefers-color-scheme`, is dismissible with `Escape`, and has real focus
+ rings.
+- Both presenters deliver into an `aria-live` region, so assistive technology
+ announces the line at the same moment everyone else hears it.
+- Audio is opt-in and gesture-gated. `voice: 'auto'` speaks only once the
+ browser has seen a real interaction; refused audio degrades to the text that
+ is already on screen.
+
+## Where the code is
+
+| Piece | Path |
+| --- | --- |
+| Rules engine (pure, unit-tested) | [herald-sdk/src/rules.js](../herald-sdk/src/rules.js) |
+| Runtime | [herald-sdk/src/index.js](../herald-sdk/src/index.js) |
+| Presenters | [herald-sdk/src/presenters/](../herald-sdk/src/presenters) |
+| Sources | [herald-sdk/src/sources/index.js](../herald-sdk/src/sources/index.js) |
+| CLI | [herald-sdk/bin/herald.mjs](../herald-sdk/bin/herald.mjs) |
+| Rail | [api/herald/announce.js](../api/herald/announce.js), [api/herald/stream.js](../api/herald/stream.js), [api/_lib/herald.js](../api/_lib/herald.js) |
+| CDN entry | [src/herald-embed.js](../src/herald-embed.js) served at `/herald.js` |
+| Playground | [pages/herald.html](../pages/herald.html), [src/herald-page.js](../src/herald-page.js) |
+| MCP server | [packages/herald-mcp/](../packages/herald-mcp/README.md) |
+| Tests | [tests/herald-rules.test.js](../tests/herald-rules.test.js), [tests/herald-runtime.test.js](../tests/herald-runtime.test.js), [tests/herald-rail.test.js](../tests/herald-rail.test.js), [tests/herald-announce-endpoint.test.js](../tests/herald-announce-endpoint.test.js) |
+
+## Related
+
+- [Notifications](#sec-311): the bell, the inbox API, and the
+ per-category avatar channel that uses this on three.ws itself.
+- [walk-sdk](../walk-sdk/README.md): the 3D body, and `control.announce()`, the
+ primitive the avatar presenter delivers through.
+- [The developer platform](#sec-183): API keys, scopes, and usage.
+
+---
+
+<a id="sec-249"></a>
> **Source:** `docs/hold-to-access.md` · [↑ table of contents](#table-of-contents)
@@ -56584,6 +59204,11 @@ feature **Live** vs **Planned**, so the platform never promises an unwired perk.
- **Free-quota multiplier** — a verified tier pass lifts the anonymous free-generation
ceiling by `rateMultiplier` in [`api/forge.js`](../api/forge.js) (`freeLaneMultiplier`),
zero added latency.
+- **Charged-at tier on `/credits`**: every credit debit already applies the discount, and
+ `GET /api/credits` reports the caller's resolved tier as `holder` (the same shape
+ `/api/pricing` returns, degrading to `null` on an RPC hiccup rather than failing the
+ balance read), so the [`/credits`](../pages/credits.html) page shows the tier you are
+ actually being charged at and the next one up.
---
@@ -56714,19 +59339,19 @@ worlds unaffected.
## Related
-- [Validation](#sec-516) — the quality gate every model passes before publish.
+- [Validation](#sec-536) — 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-241"></a>
+<a id="sec-250"></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-226).)
+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-233).)
## The five steps every generation takes
@@ -56760,17 +59385,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-281) or plain HTTP, and other agents pay per call with USDC over [x402](#sec-563), 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-290) or plain HTTP, and other agents pay per call with USDC over [x402](#sec-589), 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-226)
+- The full technical breakdown: [the Forge pipeline deep dive](#sec-233)
---
-<a id="sec-242"></a>
+<a id="sec-251"></a>
> **Source:** `docs/how-it-works.md` · [↑ table of contents](#table-of-contents)
@@ -56778,7 +59403,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-261) 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-102). For the actual JS API, see [JavaScript API](#sec-272) and [REST API](#sec-098). This document zooms out to *how it all fits together*.
---
@@ -56825,10 +59450,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-265) 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-189) and [Solana agents](#sec-406).
-- **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-187).
+- **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-277) 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-065).
+- **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-195) and [Solana agents](#sec-424).
+- **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-193).
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.
@@ -56861,7 +59486,7 @@ Three modes, all configurable per agent:
| **Self-hosted proxy** | You want to manage cost or use a private model | Set `key-proxy="https://yourapp.com/api/llm"` to point at your own serverless function that injects keys before forwarding to the provider. Keys never reach the client. |
| **Direct (advanced)** | Local-only experiments | The runtime calls the provider directly if you pass an `api-key` attribute explicitly. Don't ship this to a public page. |
-The platform's own chat surfaces run on the multi-model brain router at [`/api/brain/chat`](#sec-096), which supports Anthropic, OpenAI, and Qwen natively with OpenRouter failover; model ids include `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `qwen-plus`, and others.
+The platform's own chat surfaces run on the multi-model brain router at [`/api/brain/chat`](#sec-098), which supports Anthropic, OpenAI, and Qwen natively with OpenRouter failover; model ids include `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `qwen-plus`, and others.
---
@@ -56869,8 +59494,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-137).
-- **Selfie capture** — upload a photo, get a rigged 3D version of yourself in ~60 seconds. See [avatar-creation.md](#sec-109).
+- **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-140).
+- **Selfie capture** — upload a photo, get a rigged 3D version of yourself in ~60 seconds. See [avatar-creation.md](#sec-111).
- **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`.
@@ -56898,7 +59523,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-189) and [solana.md](#sec-406) for the registration flows.
+See [erc8004.md](#sec-195) and [solana.md](#sec-424) for the registration flows.
---
@@ -56908,7 +59533,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-123). Subscriptions auto-issue an x402 API key via the marketplace entitlement service.
+- **AWS Marketplace** — enterprise subscriptions billable through AWS. See [aws-marketplace.md](#sec-125). 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.
@@ -56921,27 +59546,319 @@ 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-525) |
+| A character in Notion / Webflow / Framer | An iframe widget from [Widget Studio](#sec-545) |
| 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-261) |
+| A character that controls a scene from page events | The JS API (`agent.say()`, `agent.ask()`) — see [js-api.md](#sec-272) |
| Programmatic avatar viewing/creation in your own app | `@three-ws/avatar` |
-| An on-chain identity for your AI | [ERC-8004](#sec-189) or [Solana](#sec-406) |
-| A paid API anyone (including agents) can call | [x402 monetization](#sec-563) |
-| Multiple agents in one scene | `<agent-stage>` — see [multi-agent.md](#sec-297) |
-| To register a domain (e.g. ENS) as agent identity | [register-onchain.md tutorial](#sec-477) |
+| An on-chain identity for your AI | [ERC-8004](#sec-195) or [Solana](#sec-424) |
+| A paid API anyone (including agents) can call | [x402 monetization](#sec-589) |
+| Multiple agents in one scene | `<agent-stage>` — see [multi-agent.md](#sec-307) |
+| To register a domain (e.g. ENS) as agent identity | [register-onchain.md tutorial](#sec-497) |
---
## What's next
-- **[Architecture overview](#sec-100)** — full internals
-- **[Agent system](#sec-064)** — runtime, skills, memory, emotion
-- **[Layers](#sec-265)** — the four-layer contract in detail
-- **[Quick start](#sec-373)** — go from zero to a living embed in under 10 minutes
+- **[Architecture overview](#sec-102)** — full internals
+- **[Agent system](#sec-065)** — runtime, skills, memory, emotion
+- **[Layers](#sec-277)** — the four-layer contract in detail
+- **[Quick start](#sec-386)** — go from zero to a living embed in under 10 minutes
---
-<a id="sec-243"></a>
+<a id="sec-252"></a>
+
+> **Source:** `docs/huggingface-3d-ai-agent-platform.md` · [↑ table of contents](#table-of-contents)
+
+---
+title: "Inside three.ws: The Open-Source Stack That Gives AI Agents a Body, a Brain, a Wallet, and a Job"
+target: Hugging Face community article (huggingface.co/blog/three-ws)
+byline: three.ws
+---
+
+# Inside three.ws: The Open-Source Stack That Gives AI Agents a Body, a Brain, a Wallet, and a Job
+
+Most AI agents are a text box. They answer, they call a tool, they disappear when the tab closes. Ours walk into your room in AR, remember what you told them last week, hold their own keys, and pay each other for work in USDC, per call, with the signature on file.
+
+This is the long version of what three.ws is. It covers every 3D generation lane and the exact models behind them, the agent runtime and its safety guard chain, the animation system that makes any humanoid rig move, the payment rail that lets agents transact without a human holding the keys, the distribution surfaces (web component, MCP, ChatGPT, Android), and every partner and program the platform is part of. Everything below is checkable: the code is Apache-2.0 at [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws), the models are on [Hugging Face](https://huggingface.co/three-ws), and `GET https://three.ws/api/version` tells you the exact commit production is running.
+
+![three.ws 3D Studio: text to 3D, rigged avatars, and living agent bodies, rendered inline inside ChatGPT](https://three.ws/partners/openai/social-card-studio.png)
+
+If you only have two minutes: open [three.ws/forge](https://three.ws/forge), type a prompt, and you will have a textured GLB with no account, no API key, and no payment. Then come back and read how it works.
+
+---
+
+## 1. The thesis: an agent needs four things, and they belong in one stack
+
+Every "AI agent" product solves one of four problems and ignores the other three:
+
+1. **The body problem.** An agent people can see, that expresses emotion, that can be placed in a scene or in a room.
+2. **The brain problem.** A model that calls tools, remembers, speaks, listens, and drives that body's face and posture.
+3. **The wallet problem.** A way to pay for its own compute, sell its own skills, and settle with other agents without a human signing every transaction.
+4. **The distribution problem.** A way to exist anywhere: a website, a chat assistant, a phone, a terminal.
+
+three.ws is the argument that these are one product. The body is a rigged glTF. The brain is a multi-model router with a tool loop and typed memory. The wallet is an on-chain identity plus x402, the HTTP 402 payment standard. Distribution is a web component, a family of MCP servers, and an Android app. Each piece is usable alone, and each one gets better because the others exist.
+
+---
+
+## 2. The 3D pipeline: from a sentence to a rigged, animated character
+
+### 2.1 Generation is a routing problem
+
+![Forge: type a prompt, get a 3D model. Free draft tier, image and sketch input, download the GLB.](https://three.ws/og/forge-og.png)
+
+The Forge ([three.ws/forge](https://three.ws/forge)) does not run one model. It runs a registry of engines with live health checks and free-first routing: every request is sent down the cheapest lane that is healthy, and falls through to the next when one is rate-limited or down. Three inputs are accepted: a text prompt, one to six reference photos, or a rough sketch.
+
+The engines in the live registry:
+
+| Lane | Model | Where it runs |
+| --- | --- | --- |
+| Text to 3D, free | Microsoft **TRELLIS** | NVIDIA NIM hosted inference |
+| Photo to 3D, free | **Hunyuan3D 2.1**, **Hunyuan3D 2**, **TRELLIS**, **TripoSR** with automatic failover | Hugging Face Spaces |
+| Text and image to 3D, self-hosted | **TRELLIS** (`TRELLIS-image-large`, MIT) | Cloud Run GPU worker, NVIDIA L4 |
+| Photo to 3D with PBR materials | Tencent **Hunyuan3D 2.1** (`hy3dshape` shape DiT plus `hy3dpaint` for baseColor, metallicRoughness, normal) | Cloud Run GPU, L4 and an RTX PRO 6000 Blackwell |
+| Sketch to 3D | **TripoSG-scribble** (VAST-AI, 1.5B rectified-flow transformer, 16 CFG-distilled steps) | Cloud Run GPU |
+| Fast fallback | **TripoSR** (VAST-AI and Stability AI, MIT), a mesh in roughly 5 to 15 seconds | Cloud Run GPU |
+| Bring your own key | Meshy 6, Tripo v3.1, Rodin (Hyper3D), Stable Fast 3D, Replicate | Your account, key never leaves the browser |
+
+Three quality tiers set the budget: Draft (12,000 polygons, no textures), Standard (30,000 polygons, 2K textures, the default), and High (200,000 polygons, PBR and HD textures, where Hunyuan3D 2.1 is the named engine).
+
+Two details that matter more than they sound. TRELLIS on the free lane truncates prompts at 77 characters and defaults to dark, gritty output, so the platform appends `, studio lighting` unless the prompt already carries lighting or color cues. And the free lane pins sampling steps at 15/15 because that is the budget that returns inside the gateway's synchronous window; the 40/40 budget is reserved for the self-hosted TRELLIS worker. Free-first routing is a design principle, not a promotion: the community avatar gallery generates a new character every minute on that lane.
+
+### 2.2 The selfie lane
+
+Photo-to-avatar is a different pipeline from object generation, because faces are unforgiving. The reconstruction worker takes one to six selfies and produces a rigged avatar from a fixed-topology template that is pre-rigged with 52 ARKit blendshapes and 15 visemes. MediaPipe FaceLandmarker drives a thin-plate-spline face-texture transfer, the 468 landmarks morph the face geometry (Umeyama alignment plus TPS), and projective texturing lifts photographic coverage of the head. The whole job runs in about five seconds on CPU.
+
+Fidelity is measured, not eyeballed. Every change to reconstruction is gated by **Identity Shape Error**, a texture-blind, pose- and scale-invariant metric computed from the same 468 landmarks: does the avatar's face geometry match the person's? A weekly realism bench then renders 23 fixed prompts and 3 CC0 reference photos from three canonical views and scores them with Gemini vision on Vertex AI.
+
+### 2.3 Rigging any mesh, and the end of the rig allowlist
+
+A static mesh becomes an animatable avatar through the rig worker, built on **Make-It-Animatable** (MIT). It predicts a 52-bone Mixamo-named skeleton and per-vertex skin weights, adds ARKit-52 expression blendshapes via ICT-FaceKit, and grafts the result into the original GLB bytes so the materials survive untouched.
+
+But most avatars do not arrive from our own rigger. They come from Blender, VRoid, Daz, Reallusion, Unreal, Roblox, MakeHuman, Sketchfab, SMPL, Mixamo. So the runtime has no rig allowlist. `src/glb-canonicalize.js` maps roughly twenty bone-naming families onto one canonical 52-bone set, and `src/animation-retarget.js` retargets clips onto whatever skeleton the model brought. A model is playable with as few as 8 canonical bones; a retarget lands when at least half its tracks find a target. A rig that genuinely cannot be driven falls back to the default body, never to a frozen T-pose.
+
+Here is what that looks like when it works. Both images below are live renders from `GET /api/render/animate`, an endpoint that returns an animated PNG, so a moving avatar plays anywhere a still image does, this article included. The first is a community avatar forged on three.ws; the second is the platform's reference rig, `cz.glb`, driven by the same clip.
+
+<p>
+<img src="https://three.ws/api/render/animate?avatar=f108a6f4-d05d-47c7-96d3-bf02c0b0f058&clip=wave&size=320" alt="A community avatar waving, rendered live as an animated PNG" width="320" />
+<img src="https://three.ws/api/render/animate?src=https://three.ws/avatars/cz.glb&clip=wave&size=320" alt="The three.ws reference rig playing the same wave clip" width="320" />
+</p>
+
+```markdown
+![my agent](https://three.ws/api/render/animate?avatar=<id>&clip=wave&size=320)
+```
+
+There is a test for this that we are unreasonably fond of: the animation dignity sweep builds ten minimal skinned GLBs, one per naming convention, and fails the build if any limb does not move.
+
+### 2.4 The motion library and where motion comes from
+
+The shared library holds about 3,000 motion-capture clips, browsable at [three.ws/animations](https://three.ws/animations) and served from `GET /api/animations/library`. Every clip carries a poster frame rendered from the canonical rig:
+
+<p>
+<img src="https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/animations/library/thumbs/mx-afoxe-samba-reggae-dance-c9c6f519b96c.webp" alt="Afoxe samba reggae dance" width="160" />
+<img src="https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/animations/library/thumbs/mx-ballet-dance-variation-one-c9c6eb62b96c.webp" alt="Ballet dance variation one" width="160" />
+<img src="https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/animations/library/thumbs/mx-aiming-idle-with-bow-123cd5926ad3.webp" alt="Aiming idle with bow" width="160" />
+<img src="https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/animations/library/thumbs/mx-backward-running-jump-c9ccec92b96c.webp" alt="Backward running jump" width="160" />
+<img src="https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/animations/library/thumbs/mx-aj-victory-idle-c9cd9927b96c.webp" alt="Victory idle" width="160" />
+</p> A full clip carries 53 tracks: 52 bone rotations plus hip position, and 30 of those tracks address finger joints, which is why hands on three.ws avatars do not look like mittens.
+
+Motion also gets generated:
+
+- **Text to motion.** `POST /api/forge-motion` samples **MDM, the Motion Diffusion Model** (HumanML3D checkpoint) and returns a retargetable three.js `AnimationClip`.
+- **Video to motion.** [three.ws/motion-swap](https://three.ws/motion-swap) runs MediaPipe pose, hands, and person segmentation at 33 body landmarks plus 21 per hand per frame, then solves them onto the canonical skeleton, all 30 finger bones included, with an in-house bend-plane IK solver in pure NumPy. No GPU.
+- **Webcam face capture.** The Mocap Studio drives ARKit blendshapes from a live camera.
+- **Sign language.** `@three-ws/sign-language` compiles text into one continuous ASL clip; fingerspelling is generated locally from a parametric hand model, all 26 handshapes including the traced J and Z. The reverse direction, webcam fingerspelling to text, runs on a LiteRT port of the Kaggle 2023 ASLFR winning solution.
+- **Procedural layers at runtime.** Analytic two-bone IK, gaze and look-at, terrain foot planting.
+
+### 2.5 Post-generation tools, each sold as its own stage
+
+Generation is the first step, not the last. The pipeline continues through workers that each do one thing:
+
+- **remesh**: decimate, quad-dominant retopology (QuadriFlow), repair, xatlas UVs, and conversion across GLB, OBJ, FBX, STL, PLY, USDZ, and 3MF via headless Blender.
+- **stylize**: pure-geometry filters, voxel, brick, Voronoi lattice, low-poly.
+- **segment**: split a model into named parts by connected components and the minima rule (cuts at concave creases).
+- **rembg**: BRIA RMBG-2.0 background removal with U2Net as CPU fallback.
+- **texture**: SDXL plus ControlNet-Depth over eight canonical depth views with UV back-projection, plus magic-brush inpainting for a region.
+- **garment forge**: a prompt like "a white oxford cotton dress shirt" becomes a rigged, wearable garment GLB that the additive wardrobe can put on any humanoid avatar.
+
+Every stage is also an x402 resource with no key and no account: rig $0.05, remesh $0.03, game-ready $0.03, stylize $0.03, background removal $0.01, and `POST /api/x402/pipeline` chains generate, rig, remesh, game-ready, and stylize for the exact sum. A stage whose worker is unconfigured returns `503` before any settlement happens; nothing is ever charged for a failed stage.
+
+### 2.6 Studios in the browser
+
+All of it is reachable without installing anything: the Pose and Animation Studio (FK gizmos, IK drag, keyframe timeline with per-key easing, undo 100 deep, export as animated GLB or clip JSON, and sell the clip for USDC), Avatar Studio with a parametric base of 122 morph-target sliders built from CC0 MakeHuman data, a Scene Studio built on the three.js editor, Diorama (a text prompt becomes an explorable 3D world), Restyle, Parts, Choreographer, Gestures, Voice Lab, Rig Doctor, and Model Diff.
+
+---
+
+## 3. The agent: a mind for the body
+
+### 3.1 Agents versus avatars
+
+An avatar is a body. An agent is a mind. The distinction is load-bearing: avatars are files, agents own wallets, memories, skills, and a passport. The agent runtime wraps the body in five layers: identity, avatar with the Empathy Layer, memory, skills, and the tool-loop runtime.
+
+### 3.2 The brain
+
+The brain is a router, not a model. [three.ws/brain](https://three.ws/brain) and `POST /api/brain/chat` fan one prompt across many providers with live latency and token stats, and the same router is the model picker in Agent Studio. The roster spans Anthropic (Claude Fable 5, Opus 5, Sonnet 5, Haiku 4.5), OpenAI (GPT-5.x, o3, GPT-OSS 120B), xAI Grok, Groq-hosted Llama 3.3 70B, Alibaba Qwen via DashScope and ModelScope, DeepSeek R1, IBM Granite on watsonx.ai, and a free NVIDIA NIM garden: Nemotron 3 Super 120B, Llama-Nemotron Super 49B, Nemotron Nano 9B, DeepSeek V4 Pro, Kimi K2.6, Llama 4 Maverick, MiniMax M2.7.
+
+Failover is deterministic: native provider, then the mirrored OpenRouter id, then Groq, then OpenRouter's free tier, then NIM. An agent never goes silent because one vendor had a bad afternoon.
+
+### 3.3 The tool loop, memory, and emotion
+
+Every agent gets a built-in tool set: `wave`, `lookAt`, `play_clip`, `setExpression`, `speak`, `remember`, `see_screen`, and on a shared stage, `observe_agents` and `say_to_agent`. Up to eight tool iterations per turn in the browser runtime, four rounds on the server-side `POST /api/agent/run`, which speaks the OpenAI chat-completions wire format in both directions so existing clients work unchanged.
+
+Memory is typed. Four categories (user, feedback, project, reference) carry different salience bonuses, are ranked by salience times a recency boost with a seven-day half-life, and are injected into the system prompt inside an 8,192-token budget, pruned at 150 entries. It ships as `@three-ws/agent-memory`.
+
+Emotion is the part people screenshot. The Empathy Layer blends six continuous emotions (concern, celebration, patience, curiosity, empathy, and a computed neutral), each with its own decay rate, into morph targets, head tilt, lean, and yaw, and fires gesture slots when an emotion crosses 0.6. Sentiment analysis runs entirely in the browser with no external API. Talk mode then layers ARKit-52 lip-sync on top, driven from live audio amplitude and spectral centroid at 60 frames per second.
+
+### 3.4 Voice and screen
+
+Voice runs through `@three-ws/voice`: browser speech or ElevenLabs for TTS, Riva ASR and Magpie TTS on NVIDIA, and browser-native NVIDIA ACE Audio2Face-3D over gRPC for audio-driven facial animation ([three.ws/demos/audio2face](https://three.ws/demos/audio2face)).
+
+Agents also have screens. Each live agent casts a browser to `/agent-screen`, and the owner can take the wheel. The cast browser holds no wallet and no keys, is driven by a short-lived scoped lease token rather than the login cookie, sanitizes and clamps input, guards navigation against SSRF, and allows one driver at a time.
+
+### 3.5 The guard chain: autonomy with a seatbelt
+
+This is the design we would defend hardest. Every fund-moving tool call passes `POST /api/agent/guard`, which runs seven independent enforcement layers and always runs all seven: security blacklist, human intervention, capability, permission, trade guard, spend envelope, x402 budget. The verdict is `allow`, `require_approval`, or `block`, and the response carries the layers that ran, warnings, blind spots, and a coverage score. A guard that failed to run is reported as a finding, not silently skipped. It ships as `@three-ws/agent-runtime` alongside a hash-chained `ActionLedger`.
+
+### 3.6 Skills
+
+Skills exist at two levels. In-app skills are typed definitions with an instruction, an animation hint, a voice pattern, an input schema, and a handler, resolved through a registry with trust modes (`any`, `owned-only`, `whitelist`). Portable skills follow the Agent Skills open standard as `SKILL.md` folders, 60 of them in the repo across 3D and creative, wallet and payments, and intel and trading, installable as a Claude Code plugin or dropped into any compatible agent.
+
+---
+
+## 4. The wallet: agents as economic actors
+
+### 4.1 Identity
+
+An agent needs an identity that survives a model swap and a hosting change, so it gets one on a public ledger. Solana is the home chain: an agent's identity and its human-readable name live there, with attestations written as memos. On EVM, the ERC-8004 identity, reputation, and validation registries are deployed by CREATE2 to the same address on twelve mainnets (Ethereum, Optimism, BSC, Gnosis, Polygon, Mantle, Base, Arbitrum, Celo, Avalanche, Linea, Scroll), bytecode-verified, with a delegated-signer pattern so the owner's cold key never has to be online for the agent to act.
+
+### 4.2 x402: pay per call over HTTP
+
+x402 is the HTTP 402 status code made real. A client requests a paid endpoint, receives a 402 with a price and a payable address, settles on-chain, and retries with proof. Settlement rails are Solana, Base, and BSC, with USDC as the settlement asset. Pay-by-name resolves `@username`, `*.sol`, or a raw address.
+
+The numbers, from the platform's self-hosted facilitator as of 25 August 2026: 110,416 on-chain USDC settlements and 803,483 payment verifications, across a live discovery catalog of 4,519 priced endpoints at `https://three.ws/.well-known/x402.json`. Buyer and seller SDKs (`@three-ws/x402-fetch`, `@three-ws/x402-server`), an MCP server so Claude Desktop and Cursor can discover and pay endpoints, and a VS Code extension on both the Marketplace and Open VSX round it out.
+
+### 4.3 The agent wallet and the agent economy
+
+Each agent wallet exposes 23 abilities: balance, deposit, withdraw, pay, trade, orders, autopilot, intents, snipe, earn, signals, trust, policy, proof-of-custody, recovery, self-defense, and more. Agents hire other agents through the marketplace, and [three.ws/agent-economy-volume](https://three.ws/agent-economy-volume) reports the total USDC that has actually moved between them, counting only completed hires with the settlement signature on file. There is no sample data path in that page. When the number is zero, it says so.
+
+---
+
+## 5. Distribution: existing everywhere
+
+### 5.1 One tag on any site
+
+```html
+<script src="https://three.ws/embed.js" defer></script>
+<threews-avatar avatar-id="a4bad2f5-8a07-43cf-82e5-b6ba1314441e" hide-chrome pose="idle"></threews-avatar>
+<script type="module">
+ const el = document.querySelector('threews-avatar');
+ await el.ready;
+ el.play('wave');
+</script>
+```
+
+The `<agent-3d>` web component boots lazily on IntersectionObserver, ships in five widget variants (turntable, animation gallery, talking agent, ERC-8004 passport card, hotspot tour), and is versioned on a CDN. Around it sit a talking chat widget, a walk companion that roams the corner of a page, a page narrator (`@three-ws/page-agent`), React bindings, and `readme-3d` for interactive models inside a GitHub README.
+
+### 5.2 AR
+
+Every generation carries a place-in-your-room link. `GET /api/ar?src=` branches server-side by user agent: iOS Quick Look (USDZ generated on the fly), Android Scene Viewer, or WebXR immersive AR, the one mode where the agent stays live with its mic, chat, and full skills runtime. [three.ws/irl](https://three.ws/irl) is the living-agent lane: a rigged avatar walking and talking in your room. AR Studio, a multi-model live camera scene, is also published standalone as the `3d-ar-studio` npm package with an MCP sibling.
+
+### 5.3 MCP: assistants call the same tools
+
+The hosted MCP server at `https://three.ws/api/mcp` speaks Streamable HTTP, protocol `2025-06-18`, with OAuth 2.1 or an API key, and `https://three.ws/.well-known/mcp.json` lists every hosted endpoint. Seven remote servers run on three.ws itself, including the free 3D Studio at `/api/mcp-studio` (generate, avatar, mesh, rig, refine, collect a pending job, and three persona tools that turn a model into a persistent body that speaks with lip-sync and emotion) and the paid 3D Studio at `/api/mcp-3d` (rigging, animation search by motion signature, pose, remesh, stylize, segment, retexture, materials, inspection, optimization, AR export). Seventy-two three.ws servers sit in the official Model Context Protocol registry under one namespace. Spatial MCP, released CC0, is the response shape that makes a 3D scene a native MCP result instead of a URL in text.
+
+### 5.4 ChatGPT
+
+The "three.ws 3D Studio" custom GPT is live in the GPT Store, calling an Actions contract served from `/.well-known/3d-studio-openapi.yaml`, and the keyless MCP connector renders generations inline in the conversation through the Apps SDK.
+
+### 5.5 Android and the terminal
+
+three.ws for Android ships as a signed Trusted Web Activity with Seed Vault via Mobile Wallet Adapter, Digital Asset Links, share target, home-screen shortcuts, and an Agent glance widget that shows a posed, camera-framed render of your agent on the home screen. The signed release installs today from GitHub; Google Play and the Solana Mobile dApp Store listings are submitted and in review.
+
+And because we could: `npx @three-ws/tty-avatar <avatar id>` draws your avatar in color at 24 frames per second in a terminal.
+
+### 5.6 Open source, in numbers
+
+Everything is Apache-2.0, and the ecosystem doc pulls its figures from the registries' own APIs. As of 25 August 2026: 101 npm packages under `@three-ws` (42 of them MCP servers); 72 MCP servers in the official registry; 33 GPU and CPU workers, 27 as Docker images; seven Solidity contracts, two Solana programs, four Rust crates; 60 agent skills; 31 specs; roughly 1,750 test files; a Blender addon and ComfyUI nodes; 500+ CC0 props, 106 rigged characters, and 3,000+ mocap animations as open assets. Every package under `packages/`, `workers/`, and `services/` has a README, enforced by a docs audit.
+
+On Hugging Face specifically: [three-ws/avatars](https://huggingface.co/three-ws/avatars) publishes rigged, animation-ready characters as plain uncompressed glTF under MIT so they load in any viewer, including Hugging Face's own. The [avatar-viewer Space](https://huggingface.co/spaces/three-ws/avatar-viewer) renders those files with three.js, and it is embedded right here, so you can orbit a real rig without leaving this page:
+
+<iframe src="https://three-ws-avatar-viewer.static.hf.space/index.html" title="three.ws Avatar Viewer: live rigged 3D agent avatars" width="100%" height="560" frameborder="0" allow="fullscreen"></iframe>
+
+---
+
+## 6. Partners and programs
+
+This section names every program, marketplace, and infrastructure relationship behind the stack, with the status each one actually carries. Two of these statuses were granted by the partner itself: OpenAI Select Partner and NVIDIA Inception member. The rest are marketplace listings, startup programs, directory placements, and media relationships, and none of them is an endorsement. We would rather you trust the list than be impressed by it.
+
+### Cloud and AI
+
+![three.ws is an OpenAI Select Partner in the OpenAI Partner Network](https://three.ws/partners/openai/social-card-announcement.png)
+
+**OpenAI.** three.ws is an OpenAI Select Partner in the OpenAI Partner Network, accepted 14 July 2026. The free 3D Studio connector gives ChatGPT keyless tools that generate, rig, refine, and embody 3D models, rendered inline through the Apps SDK; the 3D Studio custom GPT is live in the GPT Store; and three.ws is the reference implementation of Spatial MCP. three.ws is an independent member of the network, not an OpenAI product.
+
+**NVIDIA.** Member of NVIDIA Inception, accepted July 2026. Every generation lane runs on NVIDIA silicon: a self-hosted Cloud Run GPU fleet of L4s plus an RTX PRO 6000 Blackwell behind text-to-3D, rigging, and motion, and the free hosted NIM lane behind chat, vision, embeddings, reranking, content safety, and speech. ACE Audio2Face-3D drives facial animation in the browser. Two engineering write-ups on the NVIDIA Developer Forums cover the Nemotron text-to-3D pipeline and NIM-driven localization into 100 languages. Inception is a startup program, not an investment or an endorsement.
+
+**IBM.** <img src="https://three.ws/ibm-partner-logo.png" alt="IBM Business Partner" height="40" align="right" /> three.ws is an IBM Business Partner. Agents can think on IBM Granite models through watsonx.ai, and the Granite-backed surfaces (avatar brain, Guardian trust layer, time-series forecasting, digital twin, semantic discovery, vision) plus an x402-enabled Granite MCP server are live at [three.ws/ibm/hello](https://three.ws/ibm/hello) and [three.ws/ibm/x402-demo](https://three.ws/ibm/x402-demo). IBM Community hosts a dedicated three.ws user group and published the founding piece on the stack. To be precise: the public Granite tools are independent developer tools on IBM's publicly available models, not IBM products, and the formal partnership work is not yet public.
+
+**Amazon Web Services.** <img src="https://three.ws/aws-logo-512.png" alt="AWS" height="40" align="right" /> three.ws is an AWS Partner on the Software Path. The AWS Marketplace SaaS integration is built and deployed: `ResolveCustomer` fulfillment, signature-verified SNS lifecycle webhooks, account linking, daily metering, and entitlement checks, with a subscription issuing an x402 access key so usage is paid per call in stablecoin. The Marketplace listing itself is coming. Engineering articles are published on AWS Builder Center.
+
+**Google Cloud.** Member of Google Cloud for Web3 Startups. Production runs on Cloud Run (one container serves the frontend and every API handler), crons on Cloud Scheduler, GPU workers as their own services, and Vertex AI provides the Gemini and image lanes. The Google Cloud Marketplace listing is open to partnership.
+
+**Alibaba Cloud.** Live on the Alibaba Cloud International Marketplace with a product listing, a storefront, and an editorial feature on the Marketplace blog. Qwen models are first-class lanes in the brain router via DashScope, and the regional MCP deployment reaches APAC users close to home.
+
+**Hugging Face.** The organization account you are reading this on: a model repository, a running Space, and community articles.
+
+**Anthropic and the MCP ecosystem.** The brain defaults to Claude, four Claude Code plugins (`three-ws-core`, `three-ws-3d`, `three-ws-pump-fun`, `three-ws-developer`) install from the repo's own marketplace, and 72 servers are listed in the official MCP registry, with further indexing on PulseMCP, Glama, and LobeHub.
+
+### Infrastructure behind the agent economy
+
+**Quicknode.** Member of the Quicknode Startup Program, accepted July 2026, with approved infrastructure credits. Quicknode's RPC endpoints are a rung in the Solana failover chain behind agent wallets, settlement verification, and live market data, alongside Helius and Alchemy.
+
+**Coinbase Developer Platform.** The CDP facilitator settles the Base lane of x402, and the CDP Bazaar indexes three.ws endpoints automatically on first settlement.
+
+**OKX.AI.** three.ws 3D Studio is agent #2632 on the OKX.AI agent marketplace, selling text-to-3D to other agents over OKX's Agent Payments Protocol, with an always-on chat-bot host and a free catalog at `/api/okx/3d/catalog`. The listing is in resubmission.
+
+**Agent wallet standards.** MetaMask's agent-wallet skills are vendored into the skill set with EIP-7710 delegated signing, and `@three-ws/metaplex-agent-mcp` deploys an agent to the Metaplex Agent Registry in one atomic transaction.
+
+**x402 directories.** Listed with x402scan, 402index.io (domain-verified), and AgentCash, registered by a cron so the catalog never drifts.
+
+### Distribution and directories
+
+Solana Mobile dApp Store (submitted 28 August 2026, in review), Google Play (in review), the OpenAI GPT Store (live), the official MCP Registry, the VS Code Marketplace and Open VSX, the Chrome Web Store (the walking avatar extension), and the Claude Code plugin marketplace.
+
+### Media
+
+**HackerNoon** is a publishing partner: every announcement auto-imports from `three.ws/rss/announcements.xml` to [hackernoon.com/u/three-ws](https://hackernoon.com/u/three-ws) with canonical links back. **IBM Community**, the **Alibaba Cloud Marketplace blog**, and the **NVIDIA Developer Forums** have all published pieces on the stack, and the IBM partnership was picked up by Yahoo Finance and Business Insider Markets.
+
+### Where to find the community
+
+GitHub Discussions on the repo, the Telegram community at [t.me/three_ws_community](https://t.me/three_ws_community), the release channel at [t.me/three_ws](https://t.me/three_ws) (every deploy posts its changelog automatically), and the X community. The public changelog at [three.ws/changelog](https://three.ws/changelog) ships with RSS and JSON feeds.
+
+---
+
+## 7. Try it in two minutes
+
+1. **Generate.** Open [three.ws/forge](https://three.ws/forge) and type a prompt. No account, no key, no payment.
+2. **Rig and animate.** Send the result to Pose Studio, drop a clip from the library onto it, or type a motion and watch MDM sample it.
+3. **Give it a mind.** Open Agent Studio, pick a model in the Brain tab, add a memory, and talk to it. Watch its face.
+4. **Put it in your room.** Tap the AR link on any generation.
+5. **Embed it.** Paste the tag above into any page.
+6. **Let it work.** List a skill for USDC and watch the economy page count the first hire.
+
+Or skip the browser entirely and add `https://three.ws/api/mcp-studio` to your MCP client. The same tools, rendered inline, wherever you already are.
+
+---
+
+## 8. Why this belongs on Hugging Face
+
+Hugging Face is where model claims get checked, and the check is cheap: open the repo, load the file, look at the rig. A marketing page says an avatar is animation-ready; a glTF with a named humanoid skeleton that plays a retargeted clip in the browser's own viewer proves it. We publish the artifacts next to the article on purpose. Open [three-ws/avatars](https://huggingface.co/three-ws/avatars), pick a character, and follow the thread from the body to the brain to the wallet. All of it is on GitHub, and `three.ws/api/version` will tell you it is the same code.
+
+*three.ws is the 3D agent layer of the internet. Every release is public at [three.ws/changelog](https://three.ws/changelog). Source: [github.com/nirholas/three.ws](https://github.com/nirholas/three.ws).*
+
+---
+
+<a id="sec-253"></a>
> **Source:** `docs/huggingface.md` · [↑ table of contents](#table-of-contents)
@@ -56953,7 +59870,7 @@ This page is the index of that presence: what is published, where it lives, and
- **Profile:** [huggingface.co/three-ws](https://huggingface.co/three-ws)
- **Account:** organization account, byline "three.ws"
-- **Related surfaces:** [the avatar pipeline](#sec-113), [the `<agent-3d>` web component](#sec-523), [agent wallets](#sec-072), [x402](#sec-105)
+- **Related surfaces:** [the avatar pipeline](#sec-115), [the `<agent-3d>` web component](#sec-543), [agent wallets](#sec-074), [x402](#sec-107)
## Published articles
@@ -56966,7 +59883,18 @@ Published 13 July 2026 as a Hugging Face community article. It opens on the thes
Four problems in order, each answered with a shipped surface: **the body problem** (text or a photo becomes a textured mesh, then a humanoid skeleton, then retargeted animation), **the world problem** (those bodies inhabit persistent multiplayer scenes instead of a single embed), **the wallet problem** (agents hold real keys and settle per call in USDC over HTTP 402), and **the brain problem** (an LLM that calls tools, holds memory, and drives expression on the mesh). It closes with a two-minute try-it path and the argument for why the four belong in one stack rather than four products.
- **Surfaces it covers:** [/forge](https://three.ws/forge), [/play](https://three.ws/play), [/agents-live](https://three.ws/agents-live), [the x402 manifest](https://three.ws/.well-known/x402.json)
-- **Code it documents:** [the avatar pipeline](#sec-113), [animation retargeting](#sec-093), [agent wallets](#sec-072), [autonomous x402](#sec-105)
+- **Code it documents:** [the avatar pipeline](#sec-115), [animation retargeting](#sec-095), [agent wallets](#sec-074), [autonomous x402](#sec-107)
+
+### Inside three.ws: The Open-Source Stack That Gives AI Agents a Body, a Brain, a Wallet, and a Job
+
+Published 29 August 2026 as a Hugging Face community article. The whole stack in one piece, written to be checked: every 3D generation lane with its model and hardware, the selfie lane and its fidelity metric, rigging and retargeting for any humanoid, the motion library and motion models, the multi-model brain, typed memory, the Empathy Layer, the seven-layer guard chain, x402 agent payments, MCP and ChatGPT distribution, and every program and partner with its exact status. It embeds the avatar-viewer Space as a live 3D model and two animated-PNG avatars from `/api/render/animate`. Kept AI-focused per the Hugging Face blog rules: no coin, exchange, or listing content.
+
+> [Read it on Hugging Face](https://huggingface.co/blog/three-ws/building-3d-ai-agents-end-to-end)
+
+- **Source draft:** [`docs/huggingface-3d-ai-agent-platform.md`](#sec-252)
+- **Announcement thread:** [`marketing/huggingface-article/post.md`](../marketing/huggingface-article/post.md)
+- **Surfaces it covers:** [/forge](https://three.ws/forge), [/animations](https://three.ws/animations), [/brain](https://three.ws/brain), [/agent-studio](https://three.ws/agent-studio), [/irl](https://three.ws/irl), [/partners](https://three.ws/partners)
+- **Code it documents:** [the avatar pipeline](#sec-115), [the 3D asset pipeline](#sec-002), [the agent brain](#sec-132), [the agent runtime](#sec-058), [the partner ecosystem](#sec-341)
## Published models
@@ -56986,7 +59914,7 @@ Note that the files here are deliberately uncompressed. Everything three.ws serv
> [Open the Space](https://huggingface.co/spaces/three-ws/avatar-viewer)
-A running Space that loads the avatars above in an interactive 3D viewer, so a reader who arrives from the article can orbit a real rig without leaving Hugging Face or installing anything. The equivalent on our own domain is [the avatar inspector](#sec-112).
+A running Space that loads the avatars above in an interactive 3D viewer, so a reader who arrives from the article can orbit a real rig without leaving Hugging Face or installing anything. The equivalent on our own domain is [the avatar inspector](#sec-114).
## Publishing checklist
@@ -57003,11 +59931,11 @@ Hugging Face community articles accept Markdown, so a draft in `docs/` is the ar
## Why we publish here
-Hugging Face is where people go to check whether a model claim is real, and the check is cheap: open the repo, load the file, look at the rig. A marketing page says an avatar is animation-ready; a glTF with a named humanoid skeleton that plays a retargeted clip in the browser's own viewer proves it. Publishing the artifacts next to the article means a reader can verify the body problem is actually solved in the same sitting they read about it, then follow the same thread into [the wallet](#sec-072) and [the payments](#sec-105).
+Hugging Face is where people go to check whether a model claim is real, and the check is cheap: open the repo, load the file, look at the rig. A marketing page says an avatar is animation-ready; a glTF with a named humanoid skeleton that plays a retargeted clip in the browser's own viewer proves it. Publishing the artifacts next to the article means a reader can verify the body problem is actually solved in the same sitting they read about it, then follow the same thread into [the wallet](#sec-074) and [the payments](#sec-107).
---
-<a id="sec-244"></a>
+<a id="sec-254"></a>
> **Source:** `docs/i18n.md` · [↑ table of contents](#table-of-contents)
@@ -57107,7 +60035,7 @@ automatically - an exported variable still wins, so a one-off
| ------------------ | ------- | -------------------------------------- | ----------------------------------------------------------- |
| `vertex` (default) | credits | `GOOGLE_CLOUD_PROJECT` + GCP auth | billed to the platform's GCP credits; no free-tier quota wall |
| `gemini` | ✅ free | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | <https://aistudio.google.com/apikey> - free tier, best CJK |
-| `groq` | ✅ free | `GROQ_API_KEY` | <https://console.groq.com/keys> - Llama 3.3 70B, fast |
+| `groq` | ✅ free | `GROQ_API_KEY` | <https://console.groq.com/keys> - fast; the script defaults to `qwen/qwen3.8-27b` (the model `/chat` uses on this lane since Groq retired `llama-3.3-70b-versatile` in August 2026); pass `--model=` to override |
| `openrouter` | ✅ free | `OPENROUTER_API_KEY` | <https://openrouter.ai/keys> - use a `:free` model |
| `nvidia` | ✅ free | `NVIDIA_API_KEY` | <https://build.nvidia.com> - free NIM credits |
| `openai` | paid | `OPENAI_API_KEY` (+ `OPENAI_BASE_URL`) | any OpenAI-compatible endpoint |
@@ -57160,15 +60088,17 @@ billing account. `402` is the balance. `401` really is the credential.
`i18n:backfill` (below) exists to clean up catalogs damaged by this before the
guard existed.
-> **Quality note:** Llama 3.3 70B (Groq) is solid for Latin-script languages. For
+> **Quality note:** the Groq lane is fast and solid for Latin-script languages. For
> CJK/Arabic/Hindi, Gemini (free tier or Vertex) is noticeably better - switch per
> run with no code change. Whatever you pick, `npm run i18n:lint` catches any model
> that drops a placeholder, a glossary term, or a tag.
### Glossary lock (the important part)
-Terms in `doNotTranslate` — `$THREE`, the contract address, `x402`, `USDC`,
-`Solana`, `IBM watsonx.ai`, etc. - plus every `{{placeholder}}`, HTML tag, and
+Terms in `doNotTranslate` (`$THREE`, the contract address, `x402`, `USDC`,
+`Solana`, `IBM watsonx.ai`, the official handles and channels such as
+`@trythreews`, `t.me/three_ws`, `[email protected]`, and so on) plus every
+`{{placeholder}}`, HTML tag, and
HTML entity are **masked to opaque sentinels before the text reaches the model
and restored after**. The model literally never sees them, so they come back
byte-for-byte and can never be translated, reordered, or hallucinated around.
@@ -57309,6 +60239,13 @@ default), fetches `/locales/<code>.json` once, rewrites the annotated DOM, sets
fall back to English, so partial locales degrade gracefully. `window.threewsI18n`
exposes `{ t, setLocale, getLocale, initI18n }`.
+An annotated element whose content becomes live data (a balance, a status, a
+count) sets `data-i18n-owned="1"` the moment its script writes a real value into
+it. The annotation still ships so the pre-render placeholder is translated, but
+from then on the catalog pass skips the element: without that, the pass (which
+lands after the async catalog fetch) reverted a freshly rendered value back to
+its translated "Loading" placeholder.
+
The `<lang-switcher>` reads `public/locales/manifest.json`, which lists only
locales whose catalog is **complete**, so it never offers a language that would
fall back to English. Presence of the file is not enough: `writeManifest()` counts
@@ -57322,6 +60259,15 @@ that still has them, reporting what it skipped:
So a locale that is mid-translation is simply absent from the switcher until the
run finishes, instead of shipping as a half-translated page.
+The switcher shrinks where space is tight. Below the 640px breakpoint, or on any
+page that sets a `compact` attribute on `<lang-switcher>` (a narrow HUD rail),
+the control shows the locale code (`shortLocaleLabel()`: `EN`, `PT`, `ZH`) in
+place of the full language name, which otherwise makes a ~170px control. The
+native `<select>` still owns the interaction and keeps the full names in its
+options, so the picker, keyboard and screen readers behave exactly as before; the
+host also accepts a `max-width` and follows it instead of pushing its siblings
+off screen.
+
## Adding a language
Add the code (and display name) to `outputLocales` / `localeNames` in
@@ -57411,7 +60357,7 @@ clearing silently-English values out of a shipped catalog.
---
-<a id="sec-245"></a>
+<a id="sec-255"></a>
> **Source:** `docs/ibm-community-article.md` · [↑ table of contents](#table-of-contents)
@@ -57531,7 +60477,7 @@ The platform repository is public at [github.com/nirholas/three.ws](https://gith
---
-<a id="sec-246"></a>
+<a id="sec-256"></a>
> **Source:** `docs/ibm-community-blog-meetup-jessica.md` · [↑ table of contents](#table-of-contents)
@@ -57592,7 +60538,7 @@ See you Friday at 8 AM Pacific. I will be the one asking the skeptical questions
---
-<a id="sec-247"></a>
+<a id="sec-257"></a>
> **Source:** `docs/ibm-community-live-reaction-jessica.md` · [↑ table of contents](#table-of-contents)
@@ -57603,7 +60549,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-246), has the event details if you have not joined yet;
+Friday](#sec-256), 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
@@ -57644,7 +60590,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-535) is a separate, distinct campaign and
+ `@nichxbt` X copy in [event-x-posts.md](#sec-559) 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.
@@ -57658,13 +60604,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-251) as a new discussion
+- Once posted, add it to the catalog in [ibm-community.md](#sec-261) 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-248"></a>
+<a id="sec-258"></a>
> **Source:** `docs/ibm-community-recap-jessica.md` · [↑ table of contents](#table-of-contents)
@@ -57673,8 +60619,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-246) and continued mid-day with [LIVE at the Meetup: My
-Honest Take So Far](#sec-247). Header image: reuse
+Friday](#sec-256) and continued mid-day with [LIVE at the Meetup: My
+Honest Take So Far](#sec-257). 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._
@@ -57803,14 +60749,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-251) as the group's next
+- Once posted, add it to the catalog in [ibm-community.md](#sec-261) 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-249"></a>
+<a id="sec-259"></a>
> **Source:** `docs/ibm-community-recap-nichxbt.md` · [↑ table of contents](#table-of-contents)
@@ -57819,7 +60765,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-247) and [recap](#sec-248)
+reaction](#sec-257) and [recap](#sec-258)
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),
@@ -57958,13 +60904,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-251) as the group's next
+- Once posted, add it to the catalog in [ibm-community.md](#sec-261) 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-250"></a>
+<a id="sec-260"></a>
> **Source:** `docs/ibm-community-thread.md` · [↑ table of contents](#table-of-contents)
@@ -58083,13 +61029,13 @@ _Questions, skepticism, and feature requests all welcome below. The skeptical on
---
-<a id="sec-251"></a>
+<a id="sec-261"></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-253) 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-263) 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.
@@ -58135,7 +61081,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-246).
+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-256).
### 4. The First Three.ws User Group Meetup: How It Actually Went
@@ -58186,7 +61132,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-250).
+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-260).
### 2. Community Friday August 7,2026 - Inside three.ws: Join Us on the $THREE Server at three.ws/play
@@ -58255,11 +61201,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-253).
+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-263).
---
-<a id="sec-252"></a>
+<a id="sec-262"></a>
> **Source:** `docs/ibm-x402-mcp.md` · [↑ table of contents](#table-of-contents)
@@ -58281,9 +61227,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-253)**.
+credentials-based `@three-ws/ibm-watsonx-mcp` connector) see **[docs/ibm.md](#sec-263)**.
For the x402 protocol primitives used elsewhere on the platform see
-**[docs/x402.md](#sec-563)**.
+**[docs/x402.md](#sec-589)**.
---
@@ -58601,7 +61547,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-283) alongside its schema, example input, and
+[x402 Bazaar](#sec-292) alongside its schema, example input, and
example output. Agents can find Granite tools by capability and price without
knowing the server up front.
@@ -58622,16 +61568,16 @@ Catalog/listing copy is maintained in
## See also
-- [docs/ibm.md](#sec-253) — the full IBM Granite / watsonx integration and showcase
-- [docs/x402.md](#sec-563) — the x402 payment protocol on three.ws
-- [docs/mcp.md](#sec-284) — wiring MCP servers into a client
-- [docs/mcp-x402-bazaar.md](#sec-283) — x402 service discovery
+- [docs/ibm.md](#sec-263) — the full IBM Granite / watsonx integration and showcase
+- [docs/x402.md](#sec-589) — the x402 payment protocol on three.ws
+- [docs/mcp.md](#sec-293) — wiring MCP servers into a client
+- [docs/mcp-x402-bazaar.md](#sec-292) — 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-253"></a>
+<a id="sec-263"></a>
> **Source:** `docs/ibm.md` · [↑ table of contents](#table-of-contents)
@@ -58639,7 +61585,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-242); 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-251); for the agent brain abstraction see [Agent system](#sec-065); for the standalone connector see [the MCP server](#mcp-server-three-wsibm-watsonx-mcp) below.
---
@@ -58684,7 +61630,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-251). 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-261). 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.
@@ -58721,6 +61667,7 @@ The shared server-side client lives in [`api/_lib/watsonx.js`](../api/_lib/watso
2. **Project / space scoping.** Every inference body carries `project_id` (or `space_id`) — watsonx requires scoping on each call, so `watsonxConfig().configured` is only `true` when an API key **and** a project (or space) are both present.
3. **Version stamping.** Calls are version-stamped via a `?version=` query param. The chat/embed/vision endpoints use `2024-05-31`; the Time Series Forecasting API (GA'd Feb 2025) uses `2025-02-11`. Both are overridable.
4. **Real errors, surfaced.** Any IAM or upstream failure throws with the true status and message (auth, quota, model-not-enabled-in-region), so the calling endpoint reports the real cause rather than a generic 500.
+5. **Every call has a deadline.** Both legs go through the shared `fetchUpstream` wrapper: the IAM exchange is idempotent, so it gets a 10 s deadline and up to three attempts; an inference is not, so it gets one attempt with a 45 s deadline (`api/_lib/watsonx-forecast.js` uses the same 45 s for the Time Series API, and `/api/brain/chat` aborts a watsonx stream that has not returned headers within 45 s). A stalled watsonx connection can no longer hold a request open indefinitely.
The streaming chat endpoint returns an OpenAI-shaped SSE stream (`choices[].delta.content`), so the avatar runtime reuses its existing OpenAI delta reader verbatim.
@@ -58840,7 +61787,7 @@ The Twin mirrors a live token's vitals (momentum, volatility, activity, liquidit
The Galaxy embeds every public agent with `granite-embedding-278m-multilingual`, projects the vectors into 3D with PCA, clusters them with k-means, and asks Granite chat to name each cluster. The result is a 3D star-map layout where semantically similar agents sit near each other. A natural-language search ("a witty Solana trading assistant") embeds the query and returns the nearest agents by cosine similarity: matching on meaning, not keywords.
-The constellation is cached (keyed by a content hash of the agent set + model) so repeat visits are instant; `?refresh=1` forces a rebuild. The standalone embeddings endpoint, `POST /api/watsonx/embed`, exposes the same Granite vectors for your own semantic search or clustering:
+The constellation is cached (keyed by a content hash of the agent set + model) so repeat visits are instant; `?refresh=1` forces a rebuild. Search has no provider failover and none would be correct (the stored agent vectors live in Granite's space, so a vector from another lane would be a different geometry), so when the query cannot be embedded the endpoint degrades the *method* instead: it ranks the same corpus lexically and answers 200 with `ranking: "lexical"` and `degraded: { reason: "embedder_unavailable", retryable: true }`, rather than a 502. A normal search reports `ranking: "semantic"`. Each result's `home_url` is the agent's canonical `/agents/:id` page. The standalone embeddings endpoint, `POST /api/watsonx/embed`, exposes the same Granite vectors for your own semantic search or clustering:
```bash
curl -s https://three.ws/api/watsonx/embed \
@@ -58850,7 +61797,7 @@ curl -s https://three.ws/api/watsonx/embed \
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.
+**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. The fallback walks every configured lane in that order (`embedPassagesAny`), not just the preferred one, so a single NIM throttle no longer fails the request while Vertex and OpenAI sit idle. 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; when every configured lane fails at the network level it answers `503 embed_unavailable` with the real upstream cause, a retryable status rather than a 502 the caller would read as permanent.
## watsonx Constellation
@@ -58932,7 +61879,7 @@ 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-284) for wiring MCP servers into a client.
+It reads the same `WATSONX_*` environment variables documented above. See the [MCP guide](#sec-293) for wiring MCP servers into a client.
---
@@ -58979,16 +61926,16 @@ Unit tests for the same paths live in [`tests/`](../tests) (`granite-oracle`, `a
## See also
-- [How it works](#sec-242) — the platform mental model
-- [Agent system](#sec-064) — the brain abstraction Granite plugs into
-- [IBM Granite x402 MCP](#sec-252) — pay-per-call Granite for agents (USDC, no IBM account)
-- [MCP](#sec-284) — wiring MCP servers into a client
-- [REST API](#sec-096) — the full endpoint reference
-- [Configuration](#sec-154) — all environment variables
+- [How it works](#sec-251) — the platform mental model
+- [Agent system](#sec-065) — the brain abstraction Granite plugs into
+- [IBM Granite x402 MCP](#sec-262) — pay-per-call Granite for agents (USDC, no IBM account)
+- [MCP](#sec-293) — wiring MCP servers into a client
+- [REST API](#sec-098) — the full endpoint reference
+- [Configuration](#sec-159) — all environment variables
---
-<a id="sec-254"></a>
+<a id="sec-264"></a>
> **Source:** `docs/image-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -59083,14 +62030,14 @@ console.log(job.glb_url);
## Related
-- [Forge](#sec-227) 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).
+- [Forge](#sec-234) is the full text-and-image-to-3D surface with every mode and engine.
+- [Avatar reconstruction](#sec-116) and [avatar creation](#sec-111) 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-255"></a>
+<a id="sec-265"></a>
> **Source:** `docs/in-game-economy.md` · [↑ table of contents](#table-of-contents)
@@ -59219,11 +62166,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-563) and is surfaced publicly at [/fits](https://three.ws/fits).
+[x402](#sec-589) 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-217)** are
+boutique deliberately cannot see: **[event souvenirs](#sec-223)** 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
@@ -59349,16 +62296,16 @@ every number in this system.
## Next
-- **[Earn and spend in /play](#sec-450)** walks the
+- **[Earn and spend in /play](#sec-470)** 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-145)** covers the worlds themselves: how a coin
+- **[Coin communities](#sec-149)** covers the worlds themselves: how a coin
becomes a walkable 3D space.
---
-<a id="sec-256"></a>
+<a id="sec-266"></a>
> **Source:** `docs/inference-node-operator.md` · [↑ table of contents](#table-of-contents)
@@ -59632,7 +62579,7 @@ signature, and the artifact hash all check out.
---
-<a id="sec-257"></a>
+<a id="sec-267"></a>
> **Source:** `docs/integrations.md` · [↑ table of contents](#table-of-contents)
@@ -59652,7 +62599,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-187) and [Widgets](#sec-526),
+per-method references live in [Embedding](#sec-193) and [Widgets](#sec-546),
and this doc is the map that points you to the right one.
## How it works
@@ -59678,7 +62625,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-284).
+ assistant can render, speak, gesture, and emote your agents. See [MCP](#sec-293).
## Walkthrough
@@ -59796,15 +62743,15 @@ for the full table.
## Related
-- [Embedding Guide](#sec-187): the full per-method reference (web component, iframe, oEmbed)
-- [Widget Types](#sec-526): every widget type and how to configure one
-- [Embody](#sec-188): giving an agent a body in more contexts
-- [MCP](#sec-284): the avatar MCP server for AI assistants
+- [Embedding Guide](#sec-193): the full per-method reference (web component, iframe, oEmbed)
+- [Widget Types](#sec-546): every widget type and how to configure one
+- [Embody](#sec-194): giving an agent a body in more contexts
+- [MCP](#sec-293): the avatar MCP server for AI assistants
- Pages: [/integrations](https://three.ws/integrations), [/widgets](https://three.ws/widgets)
---
-<a id="sec-258"></a>
+<a id="sec-268"></a>
> **Source:** `docs/introduction.md` · [↑ table of contents](#table-of-contents)
@@ -60015,7 +62962,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-373).
+For a full step-by-step walkthrough, see the [Quick Start guide](#sec-386).
---
@@ -60023,19 +62970,123 @@ For a full step-by-step walkthrough, see the [Quick Start guide](#sec-373).
Once you have the basics working, the following guides go deeper:
-- **[Quick Start](#sec-373)** — step-by-step from zero to a talking agent
-- **[Embedding Guide](#sec-187)** — all attributes, modes, events, and the JS API
-- **[Widget Types](#sec-526)**, 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-261)** — backend and in-browser surfaces
-- **[Agents vs. avatars](#sec-073)** — the difference, and when to care
+- **[Quick Start](#sec-386)** — step-by-step from zero to a talking agent
+- **[Embedding Guide](#sec-193)** — all attributes, modes, events, and the JS API
+- **[Widget Types](#sec-546)**, the five general-purpose widgets in depth (the other five live in [Widget Studio](https://three.ws/studio))
+- **[Agent System Overview](#sec-065)** — runtime, skill registry, memory, emotion system
+- **[Manifest Reference](#sec-056)** — full JSON schema with examples
+- **[REST API](#sec-098)** and **[JavaScript API](#sec-272)** — backend and in-browser surfaces
+- **[Agents vs. avatars](#sec-075)** — 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-259"></a>
+<a id="sec-269"></a>
+
+> **Source:** `docs/ios-app.md` · [↑ table of contents](#table-of-contents)
+
+# three.ws on iOS
+
+three.ws ships to the App Store as a native iOS app (`ws.three.app`). Like the
+[Seeker app](#sec-403), it is a shell around the live web product rather
+than a second implementation of it: a Capacitor 8 container whose WKWebView runs
+`https://three.ws`, wrapped in the native layer a website cannot have. For a
+WebGL product that is the right shape, and it means the app is never a version
+behind the site. What makes it an app is everything around that shell.
+
+This page is the user-facing map. Packaging, signing, App Review posture and the
+submission checklist live in [`ios/README.md`](../ios/README.md).
+
+**Status: in-repo, not yet submitted.** The Xcode project builds and the web
+side is live in every deploy. What is outstanding is an Apple Developer
+organization account, app icons, and push. See "What is missing" below.
+
+## What the app does differently from the website
+
+| Surface | In the iOS app | Where it lives |
+|---|---|---|
+| Sharing | The system share sheet, with AR captures attached as real image files | `ios/src/native-bridge.js` (`navigator.share` shim) |
+| Deep links | Any `https://three.ws/...` link opens in the app once the app association is live | `ios/native/App/App/App.entitlements`, `api/wk.js` |
+| Wallet returns | A wallet or OAuth redirect comes back to the exact page that started it, over `threews://` | `ios/src/native-bridge.js` (`appUrlOpen`), `Info.plist` URL types |
+| Off-site links | Open in an in-app Safari sheet and return, instead of navigating the app away with no way back | `ios/src/native-bridge.js` |
+| Offline | A designed screen that polls `/api/healthz` and recovers on its own, instead of the WebKit error page | `ios/shell/offline.html`, `server.errorPath` |
+| Camera, mic, photos, location, motion | Real iOS permission prompts with real usage strings, which is what `/create/selfie`, `/ar/studio` and `/irl` need on iOS | `ios/native/App/App/Info.plist` |
+| Launch | The launch screen holds until the first real frame, so a three.js scene never opens onto a black void | `ios/src/native-bridge.js`, `SplashScreen` config |
+| Haptics | A tick on primary and destructive actions, quiet on a disabled or busy one | `ios/src/native-bridge.js` |
+| Back navigation | Edge-swipe back and forward, which `WKWebView` ships with off and iOS has no button for | `ios/native/App/App/MainViewController.swift` |
+| Status bar | The sticky header clears the notch and the clock. The site's own compensation is behind `@media (display-mode: standalone)`, which a WebView loading a remote URL never matches | `ios/src/native-bridge.js` (injected stylesheet) |
+| Forms | Fields never fall below 16px, so focusing one cannot zoom the page and strand it zoomed | `ios/src/native-bridge.js` |
+
+## How the web half reaches the app
+
+Capacitor injects its native bridge into the remote page at document start, so
+`window.Capacitor` exists on `https://three.ws` whenever the site is being
+viewed inside the app, and nowhere else. `ios/src/native-bridge.js` keys every
+behaviour above off that, and ships with the **site**: the
+`three-ws-ios-native-bridge` plugin in [`vite.config.js`](../vite.config.js)
+copies it into `dist/` under a content-hashed name and injects a script tag into
+every built page except the third-party embed entries.
+
+Two consequences worth knowing:
+
+- **App behaviour ships on a web deploy, not an App Store release.** Fixing the
+ share sheet or adding a deep-link route is a normal deploy.
+- **An old web deploy means an app with no native behaviour.** The app degrades
+ to a plain WebView rather than breaking, but the shims are simply absent.
+
+## The app association
+
+`GET /.well-known/apple-app-site-association` ([`api/wk.js`](../api/wk.js)) is
+what tells iOS that three.ws links belong to the app, and that the login form
+inside the app may offer a saved three.ws password. It is served from the API
+rather than `public/.well-known/` because Apple requires an exact path, a JSON
+content type, and no redirect.
+
+The app identifier is `<Team ID>.ws.three.app`, and the Team ID comes from
+`APPLE_TEAM_ID` on the Cloud Run service. Until that is set the endpoint answers
+`503 not_configured` on purpose: publishing an association for a team that
+cannot sign anything fails silently on device, where links just keep opening in
+Safari and nothing errors.
+
+```bash
+curl -sS -D- https://three.ws/.well-known/apple-app-site-association
+```
+
+The `applinks` components hand every path to the app except `/api/*` (OAuth and
+x402 callbacks must finish in the browser that started them) and the `/embed*`
+and `/widget*` entries (they exist to render inside someone else's page).
+
+## What is missing
+
+- **`APPLE_TEAM_ID`**, which needs an Apple Developer Program account enrolled
+ as an organization. Apple only permits wallet functionality from organization
+ accounts, and that enrollment needs a legal entity and a D-U-N-S number.
+- **Push notifications.** The entitlement, background mode and plugin are in
+ place; the APNs key, device-token endpoint and send path are not, and are
+ absent rather than stubbed.
+- **Listing screenshots**, which have to be captured on a real device. The icon
+ and launch images are generated from the brand mark (`npm run ios:icons`) and
+ a guard keeps them from drifting (`npm run check:ios-icons`).
+- **The App Review posture on crypto surfaces**, which is a product decision
+ and not a code one, and which costs a session handoff rather than a config
+ flag: `SFSafariViewController` does not share the app WebView's cookie jar, so
+ a surface routed to Safari arrives signed out. Written up in
+ [`ios/docs/REVIEW-RISK.md`](../ios/docs/REVIEW-RISK.md).
+- **Service workers**, which `WKWebView` runs only for app-bound domains. The
+ app declares none, so the site's offline caching and share-target worker do
+ not run inside it; the native offline screen covers the case that matters.
+ Same doc has the trade.
+
+## Related
+
+- [three.ws on Solana Seeker](#sec-403): the Android app
+- [`ios/README.md`](../ios/README.md): building and shipping this one
+- [`STRUCTURE.md`](../STRUCTURE.md): where every surface lives
+
+---
+
+<a id="sec-270"></a>
> **Source:** `docs/irl.md` · [↑ table of contents](#table-of-contents)
@@ -60079,7 +63130,7 @@ Anonymous pins work immediately from a device token and expire after 7 days. Sig
/irl also accepts an inbound avatar: opening `/irl?avatar=<glbUrl>` loads that
rigged GLB directly as the companion. This is the **Bring it to life** handoff
-from the [AR launch page](#sec-099) (`GET /api/ar?…&kind=avatar`) and the
+from the [AR launch page](#sec-101) (`GET /api/ar?…&kind=avatar`) and the
`irlUrl` returned by the avatar-producing studio tools, and an explicit
`?avatar=` always wins over a saved session.
@@ -60158,7 +63209,7 @@ The rollup is served at `GET /api/irl/analytics` (admin-gated via `x-ops-secret`
---
-<a id="sec-260"></a>
+<a id="sec-271"></a>
> **Source:** `docs/irl/THREAT-MODEL.md` · [↑ table of contents](#table-of-contents)
@@ -60312,15 +63363,15 @@ in a way that drops legitimate discovery, update this file in the same change.
---
-<a id="sec-261"></a>
+<a id="sec-272"></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-523) 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-543) instead.
-> For the HTTP/REST surface, see [api-reference.md](#sec-096). For the high-level npm SDK, see [sdk.md](#sec-386). For the `<agent-3d>` element attributes, see [web-component.md](#sec-523).
+> For the HTTP/REST surface, see [api-reference.md](#sec-098). For the high-level npm SDK, see [sdk.md](#sec-400). For the `<agent-3d>` element attributes, see [web-component.md](#sec-543).
---
@@ -60403,7 +63454,7 @@ Processes a fileset from a drag-and-drop or file input event.
1. Iterates the `fileMap` to find the root `.gltf` or `.glb` file
2. Extracts the `rootPath` (directory portion of the file path)
3. Calls `this.view(rootFile, rootPath, fileMap)`
-4. Reports through `onError()` if no `.gltf`/`.glb` file is found
+4. If no `.gltf`/`.glb` file is found, hides the spinner, logs a warning, and shows the viewer-status overlay ("No .gltf or .glb file in that drop. Pick a model file to view it.") with a **Choose a file** action that re-opens the file picker
#### `view(rootFile: File | string, rootPath: string, fileMap: Map<string, File>)`
@@ -60428,7 +63479,12 @@ Flow:
Console-only diagnostic logging. The user-facing error surface is the
viewer-status overlay driven by the `LOAD_END` protocol payload (see
`_classifyLoadError` in `src/app.js`), which turns a failed load into a readable
-message with a recovery action instead of a browser dialog.
+message with a recovery action instead of a browser dialog. The overlay is
+rendered by `_showViewerError(label, onAction, opts)`; `opts.actionLabel` and
+`opts.busyLabel` reword the button for recoveries that are not a plain retry,
+and `opts.keepOpenUntilLoad` clears the overlay instead of showing a busy state.
+A failed `view()` keeps a replay handle (`_retryLastView`), so the Retry button
+works for anonymous visitors on `/app` who have no agent to re-fetch.
#### `showSpinner()` / `hideSpinner()`
@@ -60572,7 +63628,7 @@ Adds a loaded model to the scene.
1. Calls `this.clear()` to remove any existing model
2. Computes bounding box and centers the model at origin
-3. Configures camera near/far planes and position based on model size
+3. Configures camera near/far planes and position based on model size; the seat is placed in front of the rig's face by reading its facing yaw (`estimateFacingYaw` in `src/viewer/facing.js`), so an avatar authored facing -Z or +X still opens front-on, and the historical +Z seat is used when no rig is readable
4. Respects `options.cameraPosition` if provided
5. Saves initial OrbitControls state
6. Detects embedded lights (sets `state.punctualLights = false` if found)
@@ -60654,7 +63710,7 @@ Creates the mini axes viewport:
Builds the entire dat.gui panel. On mobile (≤ 700 px), uses 220 px width and starts closed; on desktop, 260 px width and starts open.
-See [Architecture overview](#sec-100) for the full folder tree.
+See [Architecture overview](#sec-102) for the full folder tree.
#### `updateGUI()`
@@ -60779,10 +63835,10 @@ Returns a `<footer>` with:
- X link to [@trythreews](https://x.com/trythreews)
- "showcase" link to `/showcase`
-- "validation" link to `/validation/`
-- "reputation" link to `/reputation/`
-- "help & feedback" link to GitHub issues
-- GitHub repository link
+- "validation" link to `/validation`
+- "reputation" link to `/reputation`
+- "help & feedback" link to the GitHub issue form (`nirholas/three.ws/issues/new`)
+- GitHub repository link (`nirholas/three.ws`); every external link carries `rel="noopener noreferrer"`
- Pipe separators between items
**No props.**
@@ -60946,7 +64002,308 @@ window.VIEWER.app.viewer.updateDisplay();
---
-<a id="sec-262"></a>
+<a id="sec-273"></a>
+
+> **Source:** `docs/knock.md` · [↑ table of contents](#table-of-contents)
+
+# Knock
+
+**A priced door to a person. Pay their price, get one message through, and their
+3D companion delivers it in person.**
+
+Cold outreach is free to send and expensive to receive. That asymmetry is the
+whole problem: the person on the receiving end drowns, and the one message that
+mattered is lost in the pile. Knock inverts it. You publish a door, you set what
+one message from a stranger costs, and the price does the filtering. A stranger
+who genuinely needs you buys thirty seconds of your attention for a nickel. A
+spammer cannot buy a million of them.
+
+The delivery is the other half. A knock is not a badge on a tab you will get to
+later: your [companion](#sec-156) walks on screen wherever you are on
+three.ws, turns to you, and says who is at the door and what they paid.
+
+Open yours at **[three.ws/knock](https://three.ws/knock)**.
+
+- **The money is yours.** The USDC settles directly to the wallet you name.
+ three.ws never takes custody of it and takes no cut of it.
+- **Both kinds of visitor.** A person pays with the wallet in their browser. An
+ agent pays over [x402](#sec-589) with no human in the loop.
+- **Nothing lands for free.** Price, daily cap, message length, and a block list
+ are all yours to set. Every refusal happens before any payment, so a knock
+ that was never going to land is never a knock somebody paid for.
+- **One message, one door.** Knock is not a chat. It is a way in, once.
+
+---
+
+## Opening your door
+
+1. Pick a username, if you have not (your door lives at `/knock/<username>`).
+2. Open [three.ws/knock](https://three.ws/knock) and set:
+ - **Price**: anything from $0.001 to $1,000, or `0` for a free door.
+ - **Solana wallet**: where the USDC lands. Solana is the home chain and the
+ lane an agent settles on by default. A Base address is optional and is only
+ advertised when you set one.
+ - **Headline and greeting**: what a visitor reads before they write. Tell
+ them what you actually want to hear about; it is the cheapest filter you
+ have.
+ - **Daily cap** and **message length**.
+3. Flick **Door open**. Share the link.
+
+A priced door cannot be opened without a payout address. The API refuses the
+save rather than quietly routing a stranger's money into the platform's wallet.
+
+**Listed** is separate from **open**. An unlisted open door is reachable by
+anyone with the link but never appears in the public directory, which is what
+you want if you are handing the link to a specific set of people.
+
+---
+
+## What a visitor sees
+
+`three.ws/knock/<handle>` renders your price, your greeting, and a box. The
+message is capped at the length you set, with a live counter.
+
+A **subject** line is optional and is the only thing spoken aloud. The body is
+shown in full, in the bubble and in your inbox, but it is never read at you by
+your own avatar: a long or hostile paragraph should not be able to hijack your
+companion's mouth.
+
+When the knock lands, the sender gets a **receipt URL**. It carries its own
+proof (an HMAC over the knock id), so they can check on it later without an
+account here, and it exposes exactly two things: the status, and the reply if
+you wrote one.
+
+---
+
+## What you see
+
+Two views of the same thing.
+
+**In person.** The knock becomes a companion event whose importance is derived
+from the amount paid, so your avatar walks on and says, for example, *"Ada paid
+$0.05 to reach you: Your x402 settle path."* Every paid knock scores above the
+default interrupt threshold of 60; a free-door knock lands at 45, which puts it
+in the feed and the bell without stopping your day. Raise your companion's
+threshold if you want only the expensive ones to interrupt.
+
+**In the inbox.** [three.ws/knock](https://three.ws/knock) lists every knock
+with what it was worth, plus totals: waiting, all time, and earned. From a row
+you can reply, mark read, dismiss, or block.
+
+A **reply** is written back to the receipt link the sender already holds. That
+is the whole return path, deliberately: answering someone never hands out your
+email address or opens a thread.
+
+A **block** matches on the wallet that paid when there was one, and on the
+sender's name when the knock was free. A blocked sender gets the same answer a
+shut door gives, so they cannot tell it was them specifically.
+
+---
+
+## For agents
+
+### Read the door first
+
+```bash
+curl -s 'https://three.ws/api/knock/door?handle=nirholas'
+```
+
+```json
+{
+ "door": {
+ "handle": "nirholas",
+ "display_name": "nirholas",
+ "free": false,
+ "price": "$0.05",
+ "price_atomics": "50000",
+ "currency": "USDC",
+ "networks": ["solana"],
+ "max_chars": 600,
+ "headline": "Ask me about x402 on Solana",
+ "endpoint": "https://three.ws/api/x402/knock?to=nirholas",
+ "protocol": "x402"
+ }
+}
+```
+
+Public, cacheable, no credential. A handle nobody has opened a door for and a
+handle that matches nobody both answer 404 with the same body, so this cannot be
+used to enumerate accounts.
+
+`GET /api/knock/directory` returns every open, listed door, cheapest first.
+
+### Knock, and pay for it
+
+The paid lane is a standard x402 endpoint:
+
+```
+POST https://three.ws/api/x402/knock?to=<handle>
+```
+
+```json
+{
+ "from": "Ada (research agent)",
+ "subject": "Your x402 settle path",
+ "message": "I index x402 endpoints and yours is the only one settling on Solana. Two questions about the facilitator.",
+ "url": "https://example.com/ada",
+ "sender_kind": "agent",
+ "request_id": "ada-2026-08-28-001"
+}
+```
+
+The first call answers `402` with the door's real price and the recipient's own
+address as `payTo`. Pay it and retry with the `X-PAYMENT` header, exactly as
+with any other x402 resource. A settled call returns:
+
+```json
+{
+ "ok": true,
+ "knock_id": "c1b0a2d4-…",
+ "delivered_to": "nirholas",
+ "announced": true,
+ "importance": 74,
+ "paid": "$0.05",
+ "receipt_url": "https://three.ws/api/knock/reply?id=c1b0a2d4-…&token=…",
+ "duplicate": false
+}
+```
+
+`request_id` is an idempotency key. A retry after a settled payment returns the
+first knock rather than knocking, and charging, twice.
+
+Free doors take a plain POST instead, with the handle in the body:
+
+```bash
+curl -X POST https://three.ws/api/knock/send \
+ -H 'content-type: application/json' \
+ -d '{"to":"nirholas","from":"Ada","message":"a real message"}'
+```
+
+Posting to the wrong lane is not an error you have to guess at: a priced door
+answers the free lane with `402` and the x402 endpoint to use, and a free door
+answers the x402 lane with `400` and the plain one.
+
+### With the SDK
+
+```bash
+npm install @three-ws/knock
+```
+
+```js
+import { knock, quote } from '@three-ws/knock';
+import { wrapFetchWithPayment } from 'x402-fetch';
+
+const door = await quote('nirholas'); // read the live price first
+
+const result = await knock({
+ to: 'nirholas',
+ from: 'Ada (research agent)',
+ subject: 'Your x402 settle path',
+ message: 'Two questions about the facilitator.',
+ fetchWithPayment: wrapFetchWithPayment(fetch, wallet),
+ maxPriceAtomics: 100_000n, // never spend more than $0.10
+ requestId: 'ada-2026-08-28-001',
+});
+```
+
+The SDK never signs anything itself: you pass the paying `fetch` from the x402
+client and wallet you already trust, so your keys and your chain stay yours.
+`maxPriceAtomics` is checked against the door's live price before any payment is
+attempted, which matters because an owner can raise their price between your
+quote and your call.
+
+From the terminal:
+
+```bash
+npx @three-ws/knock quote nirholas
+npx @three-ws/knock send nirholas "Two questions." --from "Ada" --payer ./payer.mjs
+```
+
+A priced door prints the recipient, the amount, the token and the chain, and
+stops for a yes. With no TTY it refuses rather than assuming consent.
+
+### From an MCP client
+
+```bash
+claude mcp add knock -- npx -y @three-ws/knock-mcp
+```
+
+Six tools: `knock_quote`, `knock_directory`, `knock_send`, `knock_receipt`, and
+(with `THREE_WS_API_KEY`) `knock_inbox` and `knock_act`.
+
+The MCP server holds no wallet and cannot spend. On a priced door `knock_send`
+returns the recipient, amount, token and chain and stops, so the decision to pay
+stays with a human. See
+[@three-ws/knock-mcp](https://www.npmjs.com/package/@three-ws/knock-mcp).
+
+### Read the answer
+
+```bash
+curl -s 'https://three.ws/api/knock/reply?id=<knock id>&token=<receipt token>'
+```
+
+```json
+{ "knock": { "status": "replied", "reply": "Ask away.", "seen": true, "amount": "$0.05" } }
+```
+
+Statuses: `pending`, `read`, `replied`, `dismissed`. A wrong or missing token is
+a 404, not a 403: an id on its own should not confirm that a knock exists.
+
+---
+
+## Endpoints
+
+| Endpoint | Auth | What it does |
+| --- | --- | --- |
+| `GET /api/knock/door?handle=` | none | One door's public terms. |
+| `GET /api/knock/directory` | none | Every open, listed door, cheapest first. |
+| `POST /api/knock/send` | none | Knock on a free door. |
+| `POST /api/x402/knock?to=` | x402 payment | Knock on a priced door. |
+| `GET /api/knock/reply?id=&token=` | receipt token | What became of a knock you sent. |
+| `GET /api/knock/settings` | session | Your door, your totals, your block list. |
+| `PATCH /api/knock/settings` | session | Change any of it. |
+| `GET /api/knock/inbox` | session | The knocks your door has taken. |
+| `PATCH /api/knock/inbox/<id>` | session | Reply, mark read, dismiss, block. |
+
+Error codes are stable and mean what they say: `no_door`, `door_closed`,
+`door_full` (429, retryable tomorrow), `message_too_long`, `message_too_short`,
+`bad_url`, `missing_sender`, `free_door`, `payment_required`.
+
+---
+
+## Why it is built this way
+
+**Refuse before charging.** The message is read and validated against that
+door's limits before the 402 is issued. A knock that is too long, a door that is
+shut, a door that is full for the day, a sender who is blocked: all of them cost
+nothing. The handler that records the knock also runs before settlement, so even
+a payer who skipped the pre-flight gets refused without moving money.
+
+**The price is the ranking.** A mail client guesses at importance from keywords.
+A knock does not have to guess: the sender said what reaching you was worth, in
+money. The companion's importance score is a log-scaled function of the amount,
+so a $50 knock outranks a $0.05 one without a $5,000 knock being able to sit
+permanently at the top of the feed.
+
+**The body is never spoken.** Only the subject line is read aloud. Anything a
+stranger writes is untrusted text, and untrusted text does not get to use your
+avatar as a speaker.
+
+**No custody, no cut.** `payTo` on the 402 challenge is the recipient's own
+address. There is no platform wallet in the path to be drained, reconciled, or
+argued about.
+
+---
+
+## Related
+
+- [The Companion](#sec-156) is what delivers a knock in person.
+- [x402](#sec-589) is the payment protocol the priced lane speaks.
+- [Notifications](#sec-311) covers the per-category channel matrix; knocks are their own category, and the avatar channel is on for them by default.
+
+---
+
+<a id="sec-274"></a>
> **Source:** `docs/kol-tracker.md` · [↑ table of contents](#table-of-contents)
@@ -60972,6 +64329,8 @@ Influence and skill are different assets, and only one of them is priced into a
- **Followers**, only for verified handles; a wallet with no attached handle shows a blank, never a fabricated count.
- **Volume**, **Win Rate**, and **Trades** for the window.
+The column set is data-driven: a column that every row leaves empty in the current window (followers when no verified handle ranks, volume when no wallet took the on-chain path) is dropped rather than rendered as a column of blanks, and the board's minimum width shrinks with it. The handle links to X, and the wallet address under every name links to its Solscan account. An "updated" stamp next to the row count says when the board was last fetched.
+
A segmented control switches the window between 24H, 7D, and 30D (arrow keys work on it), and the column headers relabel to match. Loading renders skeleton rows; an empty tracked list renders a designed empty state; a failed fetch renders an error state. The board never falls back to placeholder rows.
## How ranking works (as coded)
@@ -61052,7 +64411,7 @@ Recent pump.fun buys and sells by the tracked wallets for one mint, via Helius,
curl 'https://three.ws/api/kol/trades?mint=<MINT_ADDRESS>&limit=20'
```
-Response: `{ mint, trades, wallets }` where each trade carries `wallet`, `side`, `amountSol`, `amountToken`, `price`, `signature`, `ts`, `time`, `usd`, `source` (`kol`, `whale`, or `smart-money` from the wallet's tags), and `label`. The `x-kol-source` response header is `helius` when the provider is configured; with no provider key the feed returns an empty list and `x-kol-source: unconfigured`, which is distinct from a configured provider outage (a `502 provider_unavailable` error).
+Response: `{ mint, trades, wallets }` where each trade carries `wallet`, `side`, `amountSol`, `amountToken`, `price`, `signature`, `ts`, `time`, `usd`, `source` (`kol`, `whale`, or `smart-money` from the wallet's tags), and `label`. The `x-kol-source` response header is `helius` when the provider is configured; with no provider key the feed returns an empty list and `x-kol-source: unconfigured`, which is distinct from a configured provider outage. When Helius fails but a last-good answer for that mint is still held, it is served with `x-kol-stale: 1` and `stale: true, as_of` in the body rather than blanking the feed; with no last-good copy either, the error (a `502 provider_unavailable`) carries `Retry-After: 15`.
### `GET /api/kol/wallets`
@@ -61082,8 +64441,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-401)** 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-432)** 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-419)** 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-450)** 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
@@ -61101,13 +64460,13 @@ curl 'https://three.ws/api/intel/wallet/<WALLET_ADDRESS>?network=mainnet'
## Related
-- [Smart Money Radar](#sec-401): reputation earned from graduation outcomes, wallet by wallet
-- [Trust primitives](#sec-432): the paid cross-chain reputation read for autonomous agents
+- [Smart Money Radar](#sec-419): reputation earned from graduation outcomes, wallet by wallet
+- [Trust primitives](#sec-450): 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-263"></a>
+<a id="sec-275"></a>
> **Source:** `docs/labor-market.md` · [↑ table of contents](#table-of-contents)
@@ -61242,7 +64601,7 @@ economy move:
---
-<a id="sec-264"></a>
+<a id="sec-276"></a>
> **Source:** `docs/launch-usecases.md` · [↑ table of contents](#table-of-contents)
@@ -61372,13 +64731,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-144) — the underlying launch mechanism.
+- [Coin Launches](#sec-148) — 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-265"></a>
+<a id="sec-277"></a>
> **Source:** `docs/layers.md` · [↑ table of contents](#table-of-contents)
@@ -61386,7 +64745,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-242). For internal module names and paths, see [Architecture overview](#sec-100).
+For the overall request flow, see [How three.ws works](#sec-251). For internal module names and paths, see [Architecture overview](#sec-102).
---
@@ -61476,10 +64835,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-405)).
+- **`erc8004/solana-deploy.js`**: Solana counterpart. Metaplex Core asset mint; SPL Memo attestations and reputation live server-side (see [Agent Reputation on Solana](#sec-423)).
- **`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-477).
+Per-chain registry addresses, ABIs, and helpers ship as `@three-ws/sdk`. ENS attestations are also handled here — see [register-onchain.md](#sec-497).
---
@@ -61492,7 +64851,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-297).
+- **`stage-element.js`**: `<agent-stage>` for hosting multiple agents in one shared scene. See [multi-agent.md](#sec-307).
- **`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.
@@ -61527,20 +64886,20 @@ 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-135) 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-138) for release history.
---
## What's next
-- **[Architecture overview](#sec-100)** — module-by-module deep dive
-- **[Agent system](#sec-064)** — runtime, skills, memory in detail
-- **[Embedding](#sec-187)** — the public face of the embed layer
-- **[SDK reference](#sec-386)** — `@three-ws/sdk` and friends
+- **[Architecture overview](#sec-102)** — module-by-module deep dive
+- **[Agent system](#sec-065)** — runtime, skills, memory in detail
+- **[Embedding](#sec-193)** — the public face of the embed layer
+- **[SDK reference](#sec-400)** — `@three-ws/sdk` and friends
---
-<a id="sec-266"></a>
+<a id="sec-278"></a>
> **Source:** `docs/likeness-eval.md` · [↑ table of contents](#table-of-contents)
@@ -61738,7 +65097,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-111)). A near-noise-floor
+([avatar fidelity program](#sec-113)). 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.
@@ -61780,8 +65139,8 @@ and reason only.
## Related
-- [Selfie to avatar](#sec-389): the capture flow being measured
-- [Avatar fidelity program](#sec-111): the tracks this
+- [Selfie to avatar](#sec-406): the capture flow being measured
+- [Avatar fidelity program](#sec-113): the tracks this
metric scores
- [Realism quality bench](../data/quality-bench/README.md): the sibling harness
for photorealism
@@ -61789,7 +65148,7 @@ and reason only.
---
-<a id="sec-267"></a>
+<a id="sec-279"></a>
> **Source:** `docs/lipsync.md` · [↑ table of contents](#table-of-contents)
@@ -61884,15 +65243,15 @@ tick();
## Related
-- [Voice Lab](#sec-521): clone a voice and synthesize it, the audio these demos animate.
-- [Voice and lipsync tutorial](#sec-496): the full walkthrough, including wiring visemes to an agent body.
-- [Talking Avatar Video](#sec-415): the server-rendered alternative for exporting a talking-head clip.
-- [Animations](#sec-093): the runtime clip registry that plays alongside lipsync.
+- [Voice Lab](#sec-541): clone a voice and synthesize it, the audio these demos animate.
+- [Voice and lipsync tutorial](#sec-516): the full walkthrough, including wiring visemes to an agent body.
+- [Talking Avatar Video](#sec-433): the server-rendered alternative for exporting a talking-head clip.
+- [Animations](#sec-095): the runtime clip registry that plays alongside lipsync.
- Pages: [/lipsync](https://three.ws/lipsync), [/lipsync/mic](https://three.ws/lipsync/mic).
---
-<a id="sec-268"></a>
+<a id="sec-280"></a>
> **Source:** `docs/liquid-glass.md` · [↑ table of contents](#table-of-contents)
@@ -61905,9 +65264,9 @@ document is the design brief for that direction: what the reference actually is,
of it we adopt, the material and type recipe that produces it, the open source we build on,
and the budget it has to stay inside.
-It sits under [Design tokens](#sec-004), which stays the source of truth for colour,
+It sits under [Design tokens](#sec-005), which stays the source of truth for colour,
type, radius, blur, and motion values. Nothing here introduces a value the token file does not
-have. Interaction primitives come from [ui-juice](#sec-502).
+have. Interaction primitives come from [ui-juice](#sec-522).
## What the reference is
@@ -62109,14 +65468,14 @@ This look is expensive and it is not allowed to cost us the product.
## Related
-- [Design tokens](#sec-004), the values every rule above resolves to.
-- [ui-juice](#sec-502), the shared interaction primitives (damping, reduced-motion contract).
-- [Restyle Studio](#sec-380), which already ships a `realGlass` transmissive preset and the
+- [Design tokens](#sec-005), the values every rule above resolves to.
+- [ui-juice](#sec-522), the shared interaction primitives (damping, reduced-motion contract).
+- [Restyle Studio](#sec-394), which already ships a `realGlass` transmissive preset and the
`RoomEnvironment` lighting setup this document depends on.
---
-<a id="sec-269"></a>
+<a id="sec-281"></a>
> **Source:** `docs/listings.md` · [↑ table of contents](#table-of-contents)
@@ -62134,7 +65493,7 @@ Cloud marketplaces are the procurement flow enterprises use to acquire software
| Cloud | Status | Links |
|---|---|---|
-| **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). |
+| **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-125) and the [listing kit](#sec-124). |
| **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. |
@@ -62149,7 +65508,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-303), [NVIDIA models](#sec-304). Membership is a startup program, not a partnership, an investment, or an endorsement. |
+| **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-314), [NVIDIA models](#sec-315). Membership is a startup program, not a partnership, an investment, or an endorsement. |
---
@@ -62161,7 +65520,7 @@ 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-563).
+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-589).
---
@@ -62171,9 +65530,9 @@ The discovery surfaces owned by the AI platforms themselves, where an MCP server
| 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-284)). Full submission kit, prerequisites, and rejection criteria: [openai-listing-channels.md](#sec-316). |
-| **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-316). |
-| **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-316). |
+| **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-293)). Full submission kit, prerequisites, and rejection criteria: [openai-listing-channels.md](#sec-327). |
+| **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-327). |
+| **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-327). |
---
@@ -62249,7 +65608,7 @@ Subscribe via RSS to track new listings, integrations, and protocol updates.
---
-<a id="sec-270"></a>
+<a id="sec-282"></a>
> **Source:** `docs/live-docs.md` · [↑ table of contents](#table-of-contents)
@@ -62269,7 +65628,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-523).
+This is the same embed snippet from the [`<agent-3d>` reference](#sec-543).
Press **Run preview** and it renders. Then press **Edit**, swap `michelle.glb`
for `xbot.glb`, and run it again.
@@ -62431,14 +65790,14 @@ cached module.
## Related
-- [`<agent-3d>` Web Component API Reference](#sec-523) — the element most previews render
-- [API reference](#sec-096) — the endpoints most `curl` samples call
-- [Embed and share](#sec-187) — putting an avatar on your own site
-- [MCP tool safety](#sec-280) — the same read/write/irreversible split, applied to agent tools
+- [`<agent-3d>` Web Component API Reference](#sec-543) — the element most previews render
+- [API reference](#sec-098) — the endpoints most `curl` samples call
+- [Embed and share](#sec-193) — putting an avatar on your own site
+- [MCP tool safety](#sec-289) — the same read/write/irreversible split, applied to agent tools
---
-<a id="sec-271"></a>
+<a id="sec-283"></a>
> **Source:** `docs/live-steps.md` · [↑ table of contents](#table-of-contents)
@@ -62486,7 +65845,7 @@ An id that is not registered renders a visible "this live step is not registered
### Redaction
-Fields whose names look like credentials (`sid`, `csrf`, any `*_token`, `authorization`, `cookie`, `api_key`, and friends) are replaced in the rendered copy, and the card says how many were hidden. This matters because documentation gets screenshotted, recorded, and pasted into issues, and a page that displays a working session identifier will eventually leak one.
+Fields whose names look like credentials are replaced in the rendered copy, and the card says how many were hidden. The match is on the exact key name, case-insensitively, against a fixed list: `sid`, `csrf`, `csrf_token`, `token`, `access_token`, `refresh_token`, `id_token`, `secret`, `session`, `password`, `authorization`, `cookie`, `api_key` / `apikey`, and `private_key` / `privatekey`. A key outside that list (`foo_token`, say) is shown as is, so name new credential fields from the list. This matters because documentation gets screenshotted, recorded, and pasted into issues, and a page that displays a working session identifier will eventually leak one.
Redaction only touches the **display**. Chained exports read the raw response body, so a step can consume a value that was never shown on screen.
@@ -62621,7 +65980,7 @@ Run `npx vitest run tests/live-steps.test.js` after editing the registry; the su
---
-<a id="sec-272"></a>
+<a id="sec-284"></a>
> **Source:** `docs/make-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -62638,7 +65997,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-179) if you're not sure which sign-in option to choose.
+You can walk through the whole setup before signing in: the avatar, the name, the brain, and the skills are kept in the tab. The wizard asks you to sign in (or create a free account) at the publish step, then picks up exactly where you left off. See [Do I need crypto?](#sec-185) if you're not sure which sign-in option to choose.
---
@@ -62652,7 +66011,7 @@ The first step of the wizard asks you to choose a body for your agent.
- **Take a selfie** — upload a photo and get a 3D version of yourself in about a minute at [/create/selfie](/create/selfie)
- **Upload a GLB** — any rigged glTF/GLB file works. Drag it into the editor at [/app](/app) or import from a URL
-Not sure what an avatar is vs. what an agent is? Read [Agents vs. Avatars](#sec-073).
+Not sure what an avatar is vs. what an agent is? Read [Agents vs. Avatars](#sec-075).
---
@@ -62688,7 +66047,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-390)
+For more on where and how to embed, continue to [Share & embed →](#sec-407)
---
@@ -62705,16 +66064,27 @@ Changes take effect immediately — no republishing needed for most settings.
---
+## How the avatar step hands back to the wizard
+
+Step 1 of the wizard sends you to one of the avatar pages (`/create/selfie`, `/create`, `/create/prompt`, `/create/studio`) and expects the finished avatar back. Those pages share one small contract, implemented in [src/shared/wizard-return.js](../src/shared/wizard-return.js):
+
+1. The wizard links out with `?wizard=1&next=/start?from=selfie`.
+2. The first page in the chain calls `captureWizardReturn()`, which keeps the `next` path in `sessionStorage` and removes it from the address bar. Only a same-origin path under `/start` is ever stored; anything else is ignored.
+3. Whichever page finally saves the avatar calls `pendingWizardReturn()`. When a return is pending, it offers "Use this avatar and continue setup" (the selfie and prompt pages) or goes straight back (the review and studio pages) via `returnToWizard({ avatarId, avatarName, avatarThumb })`, instead of its usual post-save destination. The wizard creates the agent itself, so the avatar page must not attach the avatar to an agent on this path.
+4. The wizard reads `?avatarId=&avatarName=&avatarThumb=` on arrival, attaches the avatar, and moves to step 2.
+
+Entries expire after two hours so an abandoned setup never hijacks a later, unrelated avatar save. A new avatar-producing page joins the flow by calling `captureWizardReturn()` on boot and `returnToWizard()` at its save point.
+
## What's next
-- **Put it on your website** → [Share & embed](#sec-390)
-- **Understand how it all works** → [How it works](#sec-242)
-- **Give the agent a custom skill** → [Create a custom skill](#sec-447)
-- **Make it yours permanently (on-chain)** → [Register on-chain](#sec-477)
+- **Put it on your website** → [Share & embed](#sec-407)
+- **Understand how it all works** → [How it works](#sec-251)
+- **Give the agent a custom skill** → [Create a custom skill](#sec-467)
+- **Make it yours permanently (on-chain)** → [Register on-chain](#sec-497)
---
-<a id="sec-273"></a>
+<a id="sec-285"></a>
> **Source:** `docs/market-data-api.md` · [↑ table of contents](#table-of-contents)
@@ -62839,1123 +66209,7 @@ as the single retryable class.
---
-<a id="sec-274"></a>
-
-> **Source:** `docs/marketing/articleee.md` · [↑ table of contents](#table-of-contents)
-
-# PAIR: Why We Built a Launchpad Where Every Token Is Born Married to a Stock
-
-*X Article draft, written in the founder's voice for pair.fund. Every technical claim below is taken from the live docs at https://pair.fund/docs and the deployed contracts on Robinhood Chain (Chain ID 4663). Paste into the X Article composer as-is; the section headers become the article's outline.*
-
----
-
-I want to explain what PAIR actually is, at the level of detail I would want if I were deciding whether to launch on it, trade on it, or build on top of it. Not a landing page. The mechanism.
-
-The one-line version: PAIR is a non-custodial launchpad on Robinhood Chain where every new token is paired at birth with tokenized Robinhood stock equity, trades from block one in permanently locked Uniswap V4 pools, and never migrates, never caps, and never asks you to trust us with your assets.
-
-The longer version is the rest of this article. It is long on purpose. Anyone can write "RWA launchpad" in a bio. I would rather show you the tick math.
-
-## The thesis: memecoins proved demand, stocks are the better quote asset
-
-Every launchpad of the last two years shares one design decision: the quote asset is the chain's native gas token. You buy the new token with SOL or ETH, price discovery happens against a volatile crypto asset, and the "market cap" people screenshot is denominated in something that itself swings 10% on a Tuesday.
-
-That was fine when the only liquid assets on-chain were crypto assets. It is not fine anymore.
-
-Robinhood Chain put tokenized equities on-chain: AAPL, NVDA, MSFT, TSLA, PLTR, COIN, GOOGL, META, AMD, AMZN, plus ETFs like SPY and QQQ. These are Stock Tokens with live oracle prices, deep external reference markets, and a price that means something to hundreds of millions of people who have never opened a DEX.
-
-So we asked the obvious question: what if a new token launched against NVDA instead of ETH?
-
-The answers turned out to be better than we expected:
-
-- **Price discovery against a real-economy asset.** A token paired with AAPL has a USD price that can be reasoned about because AAPL's USD price can be reasoned about.
-- **A quote asset that people already want to hold.** Sellers of a project token receive Stock Tokens. Nobody is annoyed to end up holding NVDA.
-- **Narrative fit that writes itself.** A token about AI compute paired with NVDA. A token about retail traders paired with HOOD's own chain's equities. The pairing is a product decision, not just plumbing.
-- **A multi-market surface.** One token, several independent stock-paired pools. That single design choice unlocks everything in the "V5" section below.
-
-PAIR is the launchpad built around that answer. Every contract is deployed on Robinhood Chain (Chain ID 4663). Your wallet signs every transaction. We do not custody anything.
-
-## Architecture at a glance
-
-Seven components. All on-chain, all verifiable at the addresses published in the docs.
-
-| Component | Role |
-|---|---|
-| `PairLaunchpadV5Upgradeable` | UUPS proxy entry point. Creates the token, sets up the locked V4 pools, handles the optional developer buy, records the informational graduation milestone. |
-| `PairToken` (ERC-20) | Fixed 1,000,000,000 supply with a short launch-protection window. |
-| Uniswap V4 pools | One independent concentrated-liquidity market per selected Stock Token. |
-| `PairV4Locker` | Permanently locks V4 positions, accounts for per-asset swap fees, manages creator claims. |
-| `PairPriceOracle` | On-chain price registry for ETH and every Stock Token, updated every 15 minutes by the keeper. |
-| `PairOracleFeed` | Chainlink `AggregatorV3`-compatible wrapper, one per asset, consumed by the launchpad. |
-| `StockTokenRegistry` | Registry of supported Robinhood Stock Tokens and their oracle feed addresses. |
-
-Core addresses on Robinhood Chain:
-
-- `PairLaunchpadV5Upgradeable` (Proxy): `0x8660A7F019C7943b0b0A91B8E39AFf3b6DB6Ae62`
-- `PairLaunchpadV5Upgradeable` (Implementation): `0x1559f2beDa73C57aB7964Ed1A29d8c4d8370b12c`
-- `PairV4Hook`: `0x16D1560630Ce74af4478d9b8AD46548A092A2000`
-- `PairV4Locker`: `0xeFcF476E8870fB3eb8680f039414fdcCE6C2a117`
-- `PairV4DeveloperBuyAdapter`: `0xe2D6c58477d9999913e1F443C882465E7BA6d2A4`
-- `PairPriceOracle`: `0xF15F6ff9A1f0eD55b8223A4f0Bd6f9c8c0Ab877b`
-- `EthPriceFeed` (`PairOracleFeed`): `0x3258Df8c1F1C9f5BFE83e118Fa343af6217CFc69`
-- `StockTokenRegistry`: `0xA6c3d17BA6D97B1002CdcEb4AbF9Fa3158C85ebd`
-- Protocol Treasury: `0xbC27542Ae2ED2E4d1d380B5Fe8B2D48404fD824C`
-
-Uniswap V4 on Robinhood Chain: `PoolManager` `0x8366a39CC670B4001A1121B8F6A443A643e40951`, `PositionManager` `0x58daec3116aae6D93017bAAea7749052E8a04fA7`, `StateView` `0xF3334192D15450CdD385c8B70e03f9A6bD9E673b`, plus the Universal Router, V4Quoter, and Permit2.
-
-Always verify addresses against pair.fund/docs before interacting. We will never ask you to touch an unverified contract.
-
-## Supported Stock Tokens
-
-The quote assets available at launch today, each priced by its own `PairOracleFeed`:
-
-- **Stocks:** AAPL, AMD, AMZN, BABA, BE, COIN, CRCL, CRWV, GOOGL, INTC, META, MSFT, MU, NVDA, ORCL, PLTR, SNDK, SMCI, SPCX, TSLA, USAR, APP, CUSO
-- **ETFs:** QQQ, SPY, SLV, SGOV
-
-That list is a registry entry, not a hardcode. `StockTokenRegistry` is the on-chain source of truth, and adding a new Stock Token is a registry update plus an oracle feed, not a redeploy.
-
-## How a launch works
-
-Launching is one wallet interaction, at most two transactions.
-
-**Step 1 (only if you want a developer buy):** approve the selected Stock Token so the launchpad can pull the exact amount your dev buy needs.
-
-**Step 2:** the launch transaction itself. Atomically, in one call, it:
-
-1. Deploys your `PairToken` with exactly 1,000,000,000 supply.
-2. Creates and funds every selected market as a Uniswap V4 pool. Liquidity begins at the oracle-derived launch price and extends toward Uniswap's extreme usable tick.
-3. Locks each V4 position permanently in `PairV4Locker`.
-4. If requested, executes your developer buy as an exact-output swap in the one selected Paired Market and sends the tokens to your wallet.
-5. Refunds any Stock Tokens the dev buy did not consume.
-6. Registers the token on-chain so it appears in the PAIR explorer.
-
-The only cost is the **0.0005 ETH launch fee**, paid as `msg.value` to the protocol treasury. There are no other upfront costs. PAIR supplies zero Stock Tokens at launch; the 1,000,000,000 project tokens are allocated across your selected V4 pools according to your allocation weights, and the Stock Token side of every pool fills in as people buy.
-
-Metadata (name, symbol, description, image, socials) is uploaded to our metadata endpoint and permanently linked in the token's on-chain URI. We serve it in the DexScreener Token Info schema v1.0.0, CORS-open and immutably cached, so DexScreener, GMGN, and every other aggregator picks it up without you lifting a finger.
-
-## Launch protection: the anti-snipe window
-
-For the first 5 blocks after launch, `PairToken` enforces two limits:
-
-- **Buy cap:** no single buy transaction can acquire more than 5.5% of total supply (55,000,000 tokens).
-- **Hold cap:** no wallet can hold more than 5.0% of total supply (50,000,000 tokens) during the window.
-
-Both lift automatically when the window ends. No admin action, no toggle, no "we'll turn it off later." It is in the token contract, it runs for 5 blocks, and then it is gone. Snipers get a worse launch, humans get a fairer one, and nobody has to trust a bot operator.
-
-## Continuous V5 markets: no bonding curve, no migration, no ceiling
-
-This is the part I care about most, because it is where PAIR stopped being "a launchpad on a new chain" and became a different design.
-
-Older launchpads, including our own V2 and V3, use a bonding curve: a synthetic pricing phase, then a "graduation" event, then a migration of liquidity into a real DEX pool. Every one of those steps is a seam. The migration is a moment of risk. The curve's end tick is a hidden ceiling. The pool that exists after graduation is not the pool you were trading a minute earlier.
-
-V5 has none of that.
-
-- **Direct V4 liquidity from block one.** Each selected market is created and funded as part of the launch transaction. You are trading a real Uniswap V4 pool from the first swap.
-- **Continuous range.** Liquidity begins at the oracle-derived launch price and extends toward Uniswap's extreme usable tick. For a project token that sorts as token0, the range runs from its launch tick toward the far end of the tick space.
-- **No migration, ever.** The same pool trades before and after graduation. Buys and sells continue in the original pools. Nothing moves.
-- **Permanently locked.** The V4 positions live in `PairV4Locker` and cannot be withdrawn. Not by the creator, not by us.
-
-### There is no $32,000 ceiling
-
-Some early narrow-range launches hit a market cap plateau around $32,000. That was not a rule; it was the end tick of their locked launch positions. The continuous-range V5 upgrade removed that configured economic ceiling for new launches. A V5 token can trade above a $32,000 market cap without graduating, migrating, replacing its pools, or unlocking liquidity.
-
-What is the maximum market cap, then? PAIR does not configure one. The remaining boundary is Uniswap's square-root-price limit near tick 887,200. With 18-decimal project and quote tokens, that corresponds to roughly 3.35 × 10^38 quote tokens per project token before applying the Stock Token's USD price. For a fixed supply of one billion tokens, the implied theoretical USD market cap is on the order of 10^50. That is a mathematical boundary, not an economic target. In practice a V5 token has no protocol-imposed market-cap ceiling.
-
-### How multi-market market cap is calculated
-
-A token paired with multiple Stock Tokens has multiple independent V4 prices. PAIR converts each canonical pool price to USD using the corresponding stock oracle, then combines those implied USD prices using the token's configured market weights. Market cap is the resulting composite token price multiplied by the fixed 1,000,000,000 supply.
-
-An honest caveat, straight from the docs: moving one paired market does not automatically move the others. A large buy through only the AAPL pool creates a temporary cross-market price difference that arbitrageurs trade against. Market cap is computed from the live oracle price and the current pool `sqrtPrice`; it is not guaranteed and it can decrease if people sell. Spending a given USD amount does not increase market cap by that same amount. We would rather you understand that than learn it.
-
-And to be explicit about what a multi-market token is *not*: it is not a basket, index, redeemable receipt, or asset-backed product. Allocation percentages only divide the fixed project-token supply among independent pools. Pool Allocation is launch liquidity distribution, not asset backing.
-
-## Graduation in V5: an informational milestone, not a phase change
-
-In V5, graduation is a milestone, not a mechanism.
-
-Progress compares canonical locked-position principal (the Stock Token principal sitting in the launch positions) with a recorded target:
-
-```
-progress = canonical locked principal / milestone target × 100%
-```
-
-The V5 milestone target is recorded from **4.2 ETH × ETH/USD at launch**. Fees, external liquidity, continuation depth, and trade volume are all excluded from the calculation. When principal meets or exceeds the target, the token is flagged as graduated in the on-chain PAIR registry. That call is permissionless; anyone can trigger it once the threshold is met.
-
-What changes at graduation: a flag flips and the explorer shows a badge.
-
-What does not change: the pools, the liquidity, the route, the price. Trading continues in the same V4 pools with no migration, no new pool, and no price ceiling. Graduation does not represent a terminal pool price.
-
-Legacy V2/V3 tokens keep their original bonding-curve and migration lifecycle. That terminology applies only to those older versions, never to V5 multi-pair launches.
-
-## Developer buy: exact output, input ceiling, fully atomic
-
-Creators can acquire a specified portion of their own token at launch, in one selected V5 pool, inside the launch transaction. It is optional.
-
-You specify the exact project-token output (`developerTokenAmountOut`, executed via `exactOutputSingle`) and the maximum Stock Token input (`maxQuoteAmountIn`). Setting the output to 0 skips the dev buy entirely and no Stock Token approval is needed. The maximum input is the slippage guard: it is a safety limit, not a quoted price guarantee, because the swap executes against the live V4 pool that was created moments earlier in the same transaction. Unused input is refunded.
-
-Presets in the interface run from 0.01 ETH (a small stake that demonstrates alignment) through 0.05, 0.1, and 0.5 ETH. The exact Stock Token cost is computed at transaction time from live oracle prices.
-
-The point of doing this atomically: the creator's first position is on-chain at the launch price, in the same block the pool exists, with no window for anyone to front-run it.
-
-## Trading: balanced routing across every canonical market
-
-This is where a multi-market token gets interesting for traders, and where most of our routing engineering lives.
-
-A V5 token with three paired markets has three pools: TOKEN/AAPL, TOKEN/NVDA, TOKEN/MSFT. If you buy through only one of them, you move one price and leave the other two behind. The PAIR interface refuses to do that by default. Instead it uses **balanced routing**:
-
-- **Buy:** spend USDG. PAIR converts USDG through direct fixed-fee USDG/Stock Token markets, then buys the project token through every canonical RWA pool.
-- **Sell:** split project tokens across every canonical RWA pool, convert the resulting Stock Tokens directly to USDG, and receive one USDG output.
-- **Split by marginal output.** Live marginal quotes determine the split that maximizes aggregate output while every pool receives a leg. Static launch weights are not used as a trading route.
-- **Atomic and fail-closed.** Every canonical market must have a safe direct fixed-fee USDG route. PAIR never falls back to thin direct WETH/Stock Token markets. Any failed leg, aggregate slippage breach, stale simulation, or breach of the configured value-loss or impact limits reverts the whole swap.
-- **One transaction.** Permit2 plus a single atomic Universal Router call. Project-token legs execute only in their canonical V4 pools; fixed-fee V3 is used solely for the direct USDG/Stock Token conversion inside the same transaction. A first trade with a new input token may need up to three wallet confirmations (Permit2 approval, token permit, swap); returning traders go straight to the swap because the interface checks existing allowances first.
-
-Balanced routing requires between one and five canonical RWA markets, and website swaps settle in USDG, not ETH. The interface shows expected output, aggregate minimum, maximum route impact, and every individual leg with its allocation percentage before you confirm.
-
-External terminals (GMGN and others) remain fully permissionless and may trade any single pool directly. That is by design: our pools are plain Uniswap V4 pools. We just cannot guarantee that an external swap uses the balanced route, and an external pool's fee is not paid to the PAIR creator or treasury.
-
-### A note for integrators: Robinhood Chain's router is not stock Uniswap
-
-Robinhood Chain's deployed Universal Router does not use the standard package's exact-input struct unchanged. Its dynamic `ExactInputSingleParams` tuple includes a `uint256 minHopPriceX36` field immediately before `bytes hookData`. PAIR sets that field to 0 and uses `amountOutMinimum` for the 1% minimum-received guard. Omit the extra field and the remaining calldata misaligns and the router call reverts.
-
-Direct swaps execute the V4 action sequence `SWAP_EXACT_IN_SINGLE → SETTLE → TAKE` (`0x060b0e`). `SETTLE` pays the full input-token debt from the connected wallet and `TAKE` sends the full output-token credit back to it. Validate your calldata against the deployed Robinhood router ABI, not the standard Uniswap struct. We learned this the hard way so you do not have to.
-
-## Fees: 1% per swap, 70/30 creator/protocol, locked positions do the accounting
-
-| Fee | Amount | Recipient | When |
-|---|---|---|---|
-| Launch fee | 0.0005 ETH | Protocol treasury | Once, at launch, as `msg.value` |
-| Pool swap fee | 1% of swap amount | V4 position (locked in `PairV4Locker`) | Every trade, accrued until swept |
-| Creator share | 70% of collected swap fees | Token creator | Claimable after the keeper sweeps |
-| Protocol share | 30% of collected swap fees | Protocol treasury | Distributed at the same time as the creator share |
-
-Swap fees do not flow directly to wallets. They accumulate inside each locked Uniswap V4 position, and the keeper processes them in three steps:
-
-1. **Collect.** `PairV4Locker.collectFees(tokenId)` pulls accumulated fees out of the locked position.
-2. **Allocate.** Collected project-token and Stock Token fees are each split 70/30 between creator and protocol. Project-token fees are not automatically swapped.
-3. **Claim.** The creator calls `PairV4Locker.claim(asset)` for each project-token or Stock Token balance. The interface shows every asset separately and supports safe individual or sequential claims.
-
-Sweeps run approximately hourly. There is no minimum threshold; even small positions accumulate and become claimable. The launch fee funds oracle keeper subsidies and protocol operations.
-
-Read that creator share again. A creator who launches a token paired with NVDA earns 70% of a 1% fee on every trade, paid partly in NVDA Stock Tokens, from a position that can never be pulled. That is a durable, on-chain, equity-denominated revenue stream for launching a token. I do not know of another launchpad that offers that.
-
-## Oracle and prices
-
-PAIR V5 uses a custom on-chain price oracle to track ETH/USD and every Stock Token price. The oracle is the source of truth for V5 launch validation, milestone reference calculations, and fee-to-USD conversions. It does not create a bonding curve or a price ceiling; pool prices come from the pools.
-
-- **`PairPriceOracle`** is the on-chain registry.
-- **`PairOracleFeed`** wraps each asset in a Chainlink `AggregatorV3Interface`-compatible surface, so the launchpad consumes prices identically to a real Chainlink feed. Feeds are hot-swappable in `StockTokenRegistry`.
-- **Staleness guard.** The safety-critical read path reverts if a price is older than 2 hours. If the keeper falls behind, launches fail closed until prices are refreshed rather than launching against a stale number.
-- **Keeper.** An off-chain process runs every 15 minutes and calls `PairPriceOracle.updatePriceBatch()` with stock prices from the Yahoo Finance real-time quote API and ETH/USD from DeFiLlama (with Yahoo Finance as fallback). Assets with no available price (SPCX, which is not publicly listed) are skipped for that cycle and keep their previous on-chain price, with a logged warning. The keeper is monitored and restarts automatically on failure.
-
-## Non-custodial, all the way down
-
-I want to be precise about this because "non-custodial" has become a word people put in bios.
-
-- PAIR does not hold, control, or manage your digital assets.
-- Your wallet signs every transaction directly against the smart contracts.
-- PAIR does not execute trades on your behalf.
-- Launch liquidity is locked in `PairV4Locker` permanently. Not vested, not time-locked, not multisig-recoverable. Locked.
-- The graduation milestone call is permissionless.
-- The pools are standard Uniswap V4 pools that any terminal can trade.
-- Metadata is served in an open schema that any aggregator can read.
-- Public price, liquidity, volume, and transaction counts on the site come from DexScreener rather than a private indexer, so what you see on PAIR is what you see everywhere else.
-
-Even the admin surfaces are honest about their scope: treasury operations are an application approval control, not on-chain multisig enforcement, and delisting a token from the interface display does not affect the underlying on-chain contracts. We can stop showing you something. We cannot stop it from trading.
-
-## The API
-
-The PAIR API server provides read access to indexed on-chain data plus helper endpoints for uploads and price lookups. Highlights:
-
-- Tokens: search by name, symbol, token address, or creator address; filter by paired Stock Token; list graduated tokens by graduation date; fetch a single token with its V5 locked-liquidity milestone progress (or legacy bonding-curve progress for older versions).
-- Stock Tokens: every registered Robinhood Stock Token with its on-chain address, oracle feed address, decimals, enabled status, and how many community tokens have launched against it.
-- Fees: every fee balance claimable by a wallet across all lockers (V3 locker, legacy V4 locker, current V4 locker), read live on-chain and annotated with USD values from the oracle; fees still sitting unswept inside V3 positions; paginated claim history.
-- Charts: OHLCV candles for the TradingView chart.
-- Prices: live market prices from Yahoo Finance for up to 10 symbols per request, cached server-side for 30 seconds.
-- Metadata: DexScreener Token Info schema v1.0.0, CORS-open, immutably cached.
-- Import: register an existing 18-decimal on-chain token that already has a Uniswap V3 pool with liquidity against an enabled Stock Token.
-
-Full reference at pair.fund/docs under "API Reference".
-
-## Why I am bullish
-
-I will say this plainly.
-
-**Tokenized equities are the largest new quote asset class to arrive on-chain since stablecoins.** Robinhood put them there with its own chain and its own distribution. The first wave of on-chain equity activity will be people holding and trading the stocks themselves. The second wave is what gets built on top of them, and a launchpad that pairs new tokens with those equities from block one is the most obvious primitive in that second wave. We built it first, and we built it with permanent liquidity, no migration, and equity-denominated creator revenue.
-
-**The V5 design removes every seam that hurt launchpad users.** No bonding curve to game. No migration event to front-run. No hidden ceiling tick. No liquidity that can be pulled. No custodian. Every one of those was a category of rug or a category of exploit, and each is structurally absent here.
-
-**Creators are paid in stock.** 70% of a 1% fee, forever, partly in NVDA or AAPL or SPY. That single fact will pull serious builders to PAIR that no amount of memecoin-denominated fees ever would.
-
-**The routing is a moat.** Balanced multi-market execution, fail-closed, atomic, across up to five stock-paired pools with a USDG settlement leg, on a router whose ABI diverges from upstream Uniswap. That is not a weekend fork. Every terminal that wants to give its users the PAIR experience will be routing through logic we wrote and documented.
-
-**The contracts are live, verifiable, and boring in the best way.** UUPS proxy, Chainlink-compatible feeds, a staleness guard that fails closed, a 5-block anti-snipe window in the token itself, an hourly fee sweep with no minimum. Nothing in this design requires you to believe a promise. Every claim in this article is a read call away.
-
-PAIR is where the next thousand tokens on Robinhood Chain are going to be born, each one married at birth to a real company's stock, each one trading in a pool nobody can drain.
-
-Launch one. pair.fund
-
-Docs: pair.fund/docs · Code: github.com/pairdotfund · X: @pairdotfund
-
-*Tokens launched on PAIR are speculative assets with no guaranteed value. Transactions are irreversible. PAIR Labs does not provide custody, warranties, or financial advice.*
-
----
-
-<a id="sec-275"></a>
-
-> **Source:** `docs/marketing/posts.md` · [↑ table of contents](#table-of-contents)
-
-# PAIR: 100 scheduled X posts
-
-Founder voice for pair.fund. Three per hour. Every post is under 280 characters and every claim is from pair.fund/docs. Rotate the themes so consecutive posts do not repeat an angle. Append the docs or article link where a post ends with "Docs:" or "Launch:".
-
-## Thesis and positioning
-
-1. Every launchpad quotes new tokens in the gas token. PAIR quotes them in NVDA, AAPL, SPY. Price discovery against a real company instead of a coin that swings 10% on a Tuesday. pair.fund
-
-2. Tokenized stocks are the biggest new quote asset on-chain since stablecoins. The first wave is holding them. The second wave is building on them. PAIR is the launchpad for the second wave.
-
-3. What if the token you launched was paired with NVDA at birth? That one question became PAIR. Live on Robinhood Chain.
-
-4. Memecoins proved demand for on-chain launches. Stocks are simply the better quote asset. PAIR puts the two together.
-
-5. A token about AI compute paired with NVDA. A token about retail paired with HOOD's own chain's equities. On PAIR the pairing is a product decision, not plumbing.
-
-6. Sellers on most launchpads dump into a volatile gas token. Sellers on PAIR receive stock tokens. Nobody is upset to end up holding NVDA.
-
-7. PAIR in one line: non-custodial launchpad on Robinhood Chain, every token paired with tokenized stock equity, permanently locked Uniswap V4 pools, no migration, no ceiling.
-
-8. We did not build "an RWA launchpad." We built a launchpad where the RWA is the quote asset in every single pool. That is the whole product.
-
-9. Robinhood Chain, chain ID 4663. Every PAIR contract is deployed there and every address is published in the docs. Verify before you trust.
-
-10. The next thousand tokens on Robinhood Chain will be born married to a stock. pair.fund
-
-## V5 markets: no curve, no migration, no ceiling
-
-11. V5 has no bonding curve. Your token trades in a real Uniswap V4 pool from the first swap. There is no synthetic pricing phase to game.
-
-12. Graduation on most launchpads is a migration event, and migration events are where people get front-run. V5 does not migrate. The same pool trades before and after.
-
-13. The "$32,000 ceiling" some early launches hit was the end tick of a narrow-range position, not a rule. V5 uses a continuous range. That ceiling is gone.
-
-14. What is the max market cap of a V5 token? Uniswap's sqrt-price limit near tick 887,200. For a 1B supply that implies a number around 10^50. It is math, not a target. There is no protocol cap.
-
-15. V5 liquidity starts at the oracle-derived launch price and extends toward Uniswap's extreme usable tick. One range, one pool, forever.
-
-16. Three things V5 removed: the bonding curve, the migration, the ceiling tick. Each one was a category of exploit. Each one is structurally absent now.
-
-17. "Does my token migrate at graduation?" No. "Does the pool change?" No. "Does the route change?" No. A flag flips on-chain and the explorer shows a badge. That is it.
-
-18. Every V4 position PAIR creates at launch is locked in PairV4Locker permanently. Not vested. Not time-locked. Not multisig-recoverable. Locked.
-
-19. Old V2 and V3 tokens keep their bonding-curve lifecycle. That terminology has nothing to do with V5 multi-market launches. Do not let a stale thread confuse you.
-
-20. Direct V4 liquidity from block one means the token you buy at second 1 is trading in the exact pool it will trade in at year 5.
-
-## Launch mechanics
-
-21. Launching on PAIR is one wallet interaction and at most two transactions. Approve a stock token if you want a dev buy, then launch. Done.
-
-22. The launch transaction atomically: deploys your 1B-supply token, creates and funds every selected V4 pool, locks each position, runs your optional dev buy, refunds unused stock tokens, registers on-chain.
-
-23. Launch fee: 0.0005 ETH, paid as msg.value to the protocol treasury. There are no other upfront costs.
-
-24. PAIR supplies zero stock tokens at launch. Your 1,000,000,000 tokens are split across your chosen pools by your allocation weights. The stock side fills as people buy.
-
-25. Pick up to five paired markets at launch. TOKEN/NVDA, TOKEN/AAPL, TOKEN/SPY, all live in the same transaction.
-
-26. Allocation weights divide your fixed supply among independent pools. They are launch liquidity distribution, not asset backing and not a basket. We say this in the docs because we mean it.
-
-27. Your metadata is uploaded once and linked permanently in the token's on-chain URI. Served in the DexScreener Token Info schema, CORS-open, immutably cached. Aggregators pick it up with no action from you.
-
-28. Supported quote stocks today: AAPL, AMD, AMZN, BABA, BE, COIN, CRCL, CRWV, GOOGL, INTC, META, MSFT, MU, NVDA, ORCL, PLTR, SNDK, SMCI, SPCX, TSLA, USAR, APP, CUSO. ETFs: QQQ, SPY, SLV, SGOV.
-
-29. Adding a new stock token to PAIR is a registry entry plus an oracle feed. StockTokenRegistry is on-chain. No redeploy.
-
-30. You can also import an existing 18-decimal token that already has a V3 pool against an enabled stock token. Bring your community, keep your contract.
-
-## Anti-snipe
-
-31. First 5 blocks after launch, PairToken enforces two caps: no single buy over 5.5% of supply, no wallet over 5.0%. Then both lift automatically.
-
-32. The anti-snipe window is in the token contract, not in a bot we run. Nobody has to trust an operator to "turn it on."
-
-33. 55,000,000 tokens max per buy. 50,000,000 max per wallet. Five blocks. Then free. That is the entire launch-protection rule.
-
-34. Snipers get a worse launch. Humans get a fairer one. It costs the creator nothing and requires no action from anyone.
-
-## Developer buy
-
-35. Creators can buy their own token inside the launch transaction. Exact output, capped input, one selected pool, fully atomic. No window to be front-run.
-
-36. developerTokenAmountOut is the exact number of tokens you want. maxQuoteAmountIn is the most stock token you will spend to get them. Set output to 0 to skip it.
-
-37. The dev buy executes against the live V4 pool created moments earlier in the same transaction. Unused stock tokens are refunded in the same call.
-
-38. Presets from 0.01 ETH to 0.5 ETH equivalent. Small stake, moderate position, significant stake, large early position. Your call, priced by live oracle at tx time.
-
-39. A creator whose first position lands in the same block the pool exists is a creator who cannot be front-run on their own launch.
-
-## Fees and creator revenue
-
-40. 1% fee on every swap. 70% to the creator. 30% to the protocol. Accrued inside the locked position, swept roughly hourly, claimable any time after.
-
-41. A creator who launches against NVDA earns 70% of a 1% fee on every trade, partly in NVDA. Forever. From a position nobody can pull.
-
-42. Fee pipeline: PairV4Locker.collectFees pulls from the locked position, fees are split 70/30 per asset, creator calls claim(asset). Three steps, all on-chain.
-
-43. No minimum threshold on fee sweeps. Small pools accumulate too. If your token trades, you earn.
-
-44. Project-token fees and stock-token fees are split separately and claimed separately. The interface shows each asset and supports safe sequential claims.
-
-45. The launch fee funds oracle keeper subsidies and protocol operations. That is where 0.0005 ETH goes.
-
-46. Creators on PAIR get paid in stock tokens. Let that reframe what "launching a token" means to a serious builder.
-
-47. Fees you can claim across every locker (V3, legacy V4, current V4) are read live on-chain and shown with USD values from the oracle. One view, all history.
-
-## Trading and balanced routing
-
-48. A token with three paired pools has three prices. Buying through one moves one. The PAIR interface refuses to do that by default. It routes across all of them.
-
-49. Balanced routing: live marginal quotes decide the split that maximizes your output while every canonical pool receives a leg. Static launch weights are never used as a route.
-
-50. Buy: spend USDG, convert through fixed-fee USDG/stock pools, buy through every canonical RWA pool. Sell: reverse it, receive one USDG output. One transaction.
-
-51. Fail-closed by design. Any failed leg, aggregate slippage breach, stale simulation, or impact limit reverts the entire swap. We never fall back to a thin WETH/stock pool.
-
-52. Permit2 plus one atomic Universal Router call. Returning traders go straight to the swap. The interface checks allowances before ever asking for an approval.
-
-53. Before you confirm, PAIR shows expected output, aggregate minimum, maximum route impact, and every leg with its allocation. Nothing hidden.
-
-54. Our pools are plain Uniswap V4 pools. GMGN and any other terminal can trade any single pool directly. We just cannot promise an external swap uses the balanced route.
-
-55. Balanced routing supports one to five canonical RWA markets and settles in USDG. Not ETH.
-
-56. Moving one paired market does not move the others. A big buy through only the AAPL pool creates a cross-market gap arbitrageurs will close. Balanced routing avoids creating that gap in the first place.
-
-57. Market cap on a multi-market token: each pool price is converted to USD via its stock oracle, combined by market weight, multiplied by 1B supply. It can go down if people sell. We say so in the docs.
-
-## Integrators and builders
-
-58. Building on Robinhood Chain? The deployed Universal Router's ExactInputSingleParams has an extra uint256 minHopPriceX36 before hookData. Omit it and your calldata misaligns and reverts. Docs have the layout.
-
-59. Direct swaps run SWAP_EXACT_IN_SINGLE, SETTLE, TAKE (0x060b0e). SETTLE pays the input debt from the wallet, TAKE sends the output back. Validate against the deployed ABI, not upstream Uniswap.
-
-60. PairOracleFeed is Chainlink AggregatorV3-compatible. If your contract already reads Chainlink, it already reads PAIR stock prices.
-
-61. The PAIR API: token search by name, symbol, address, or creator; graduated list; per-token milestone progress; claimable fees per wallet; OHLCV candles; live stock quotes. Read-only, indexed, documented.
-
-62. Metadata endpoint serves DexScreener Token Info v1.0.0, CORS-open, immutably cached. Point your aggregator at it.
-
-63. Every PAIR contract address: launchpad proxy and implementation, V4 hook, locker, dev-buy adapter, oracle, ETH feed, registry, treasury. All in the docs. All on 4663.
-
-64. We learned the Robinhood router ABI quirk the hard way so you do not have to. That is what documentation is for.
-
-65. PairV4Hook, PairV4Locker, PairV4DeveloperBuyAdapter. Three contracts, three jobs, one launch transaction. Read them.
-
-## Oracle
-
-66. PAIR runs its own on-chain price oracle for ETH/USD and every stock token. It validates launches and prices fees. It does not set pool prices. Pools set pool prices.
-
-67. A keeper updates PairPriceOracle every 15 minutes with stock quotes from Yahoo Finance and ETH/USD from DeFiLlama, Yahoo as fallback.
-
-68. Staleness guard: safety-critical reads revert if a price is older than 2 hours. If the keeper falls behind, launches fail closed rather than launch against a stale number.
-
-69. Assets with no public quote (SPCX is not listed) keep their previous on-chain price for that cycle and the keeper logs a warning. Nothing silently invents a price.
-
-70. Oracle feeds are hot-swappable in StockTokenRegistry. Upgrade a feed without touching the launchpad.
-
-## Non-custodial, precisely
-
-71. "Non-custodial" is a word people put in bios. On PAIR it means: your wallet signs everything, we never hold funds, liquidity is locked forever, and the graduation call is permissionless.
-
-72. PAIR cannot reverse, cancel, or recover a transaction. That is not a limitation we apologize for. It is the property you are paying for.
-
-73. We can stop displaying a token on the interface. We cannot stop it from trading. Delisting never touches the on-chain contracts.
-
-74. Public price, liquidity, volume, and tx counts on pair.fund come from DexScreener, not a private indexer. What you see on PAIR is what you see everywhere.
-
-75. Treasury admin actions are an application approval control, not on-chain multisig enforcement. We document exactly what our admin surface can and cannot do.
-
-76. Graduation is permissionless. Once locked principal meets the target, anyone can flip the flag. Not us. Anyone.
-
-## Graduation milestone
-
-77. V5 graduation: progress = canonical locked principal / milestone target. Target is recorded from 4.2 ETH times ETH/USD at launch. Fees, volume, and outside liquidity do not count.
-
-78. Graduation is an informational milestone. It is not a max price, not a max market cap, not a point where trading changes. The docs say it three times because people keep asking.
-
-79. A token can pass its graduation milestone, keep trading in the same pool, and never migrate anywhere. That is the design working.
-
-80. Only stock-token principal inside the canonical launch positions counts toward graduation. Continuation depth and fees are excluded on purpose.
-
-## Bullish
-
-81. Tokenized equities are on-chain with Robinhood's distribution behind them. A launchpad that pairs new tokens with those equities from block one is the most obvious primitive of the next cycle. We shipped it.
-
-82. Permanent liquidity. No migration. No ceiling. No custodian. Creator revenue in stock tokens. Name another launchpad with all five.
-
-83. The routing is the moat. Fail-closed atomic execution across five stock-paired pools with a USDG leg on a router whose ABI diverges from upstream. Not a weekend fork.
-
-84. Every claim we make is a read call away. UUPS proxy, Chainlink-compatible feeds, 5-block anti-snipe in the token, hourly sweeps. Boring in the best way.
-
-85. The first wave of on-chain equities is people holding stocks. The second wave is what gets built on top. PAIR is where that starts.
-
-86. Nobody is going to launch against ETH once they can launch against NVDA and get paid in NVDA. Give it a year.
-
-87. Serious builders were never coming for memecoin-denominated fees. 70% of every swap, paid in stock tokens, from a locked position, is a different offer.
-
-88. We did not remove the bonding curve to be different. We removed it because every seam in a launch is a place someone gets hurt.
-
-89. A pool nobody can drain, paired with a company everybody knows, on a chain built by a brokerage with hundreds of millions of users. That is PAIR.
-
-90. Locked liquidity used to be a promise on a Telegram pin. On PAIR it is a contract address.
-
-## Calls to action
-
-91. Launch a token paired with NVDA in two transactions and 0.0005 ETH. pair.fund
-
-92. Read the docs before you launch. All of them. Then launch. pair.fund/docs
-
-93. Traders: try a balanced buy on any multi-market PAIR token and watch every leg quote before you confirm.
-
-94. Creators: claim your fees. They have been accumulating since your first trade. pair.fund
-
-95. Builders: the API and contract table are public. Ship something on top of PAIR and tag us.
-
-96. Which stock would you pair your token with? Reply and we will tell you if it is on the registry.
-
-97. If you launched a V2 or V3 token with us, it still trades. If you want no ceiling and no migration, launch V5.
-
-98. Verify every address against pair.fund/docs before you sign. We will never ask you to interact with an unverified contract.
-
-99. Long-form on why every PAIR token is born married to a stock. Full technical breakdown, contract addresses, tick math, fee pipeline. Link below.
-
-100. Every token on PAIR is born married to a stock. Launch one. pair.fund
-
----
-
-<a id="sec-276"></a>
-
-> **Source:** `docs/marketing/posts2.md` · [↑ table of contents](#table-of-contents)
-
-# PAIR: scheduled X content (threads, long-form, shorts)
-
-Founder voice for pair.fund. Every technical claim traces to pair.fund/docs and the contracts deployed on Robinhood Chain (chain ID 4663). No em-dashes anywhere.
-
-Three tiers, built for a 3-posts-per-hour schedule:
-
-- **Threads (T1-T12):** 8 to 14 tweets each, every tweet under 280 characters. Post as a thread. Deep mechanism.
-- **Long-form (L1-L15):** X Premium long posts, 900 to 2,500 characters. One idea, fully argued.
-- **Shorts (S1-S60):** under 280 characters. Fill the gaps between the big pieces.
-
-Suggested cadence per hour: one thread or long-form, two shorts. Rotate themes so consecutive posts never share an angle.
-
-Where a post says "Docs:" or "Article:" append the link (pair.fund/docs or the X Article).
-
----
-
-## THREADS
-
-### T1. What actually happens inside a PAIR launch transaction
-
-1/ People ask what "one transaction" means on PAIR. Here is the exact sequence the launchpad executes when you hit Launch, step by step, from the docs. Thread.
-
-2/ Entry point is PairLaunchpadV5Upgradeable, a UUPS proxy at 0x8660A7F019C7943b0b0A91B8E39AFf3b6DB6Ae62 on Robinhood Chain. Implementation is separate and published. One call in, everything below happens atomically.
-
-3/ First it deploys your PairToken. ERC-20, exactly 1,000,000,000 supply, with a 5-block launch-protection window baked into the token contract itself (more on that later in the thread).
-
-4/ It reads live prices from PairPriceOracle through Chainlink-compatible PairOracleFeed wrappers. If any selected stock token's price is older than 2 hours the whole launch reverts. Stale price, no launch. Fail closed.
-
-5/ For every stock token you selected (1 to 5), it creates a Uniswap V4 pool and funds it with your allocation share of the 1B supply. Liquidity starts at the oracle-derived launch tick and extends toward Uniswap's extreme usable tick.
-
-6/ PAIR contributes zero stock tokens to those pools. Your side of the pool is project tokens. The stock side fills in as people buy. This is why allocation is "launch liquidity distribution, not asset backing."
-
-7/ Each V4 position is then locked in PairV4Locker at 0xeFcF476E8870fB3eb8680f039414fdcCE6C2a117. Permanently. No vesting schedule, no timelock, no recovery path. The docs use the word "permanently" and mean it.
-
-8/ If you requested a developer buy, PairV4DeveloperBuyAdapter executes an exactOutputSingle swap in the one market you chose, with developerTokenAmountOut as the exact target and maxQuoteAmountIn as the spend cap. Output goes to your wallet.
-
-9/ Any stock token the dev buy did not consume is refunded in the same transaction. You never over-pay for the dev buy; the cap is a ceiling, not a price.
-
-10/ It records the V5 graduation milestone target: 4.2 ETH times the ETH/USD oracle price at launch. This is an informational reference, not a cap, and it is stored on-chain at that moment.
-
-11/ Finally it registers the token on-chain so the PAIR explorer indexes it. Your metadata (uploaded before the tx) is now permanently linked in the token URI and served in DexScreener Token Info schema v1.0.0.
-
-12/ Cost: 0.0005 ETH as msg.value to the protocol treasury. Nothing else. If you skipped the dev buy, this is the only transaction you signed.
-
-13/ Everything above is one atomic call. If any step fails, none of it happened. No half-deployed token, no orphaned pool, no locked position without a token behind it.
-
-14/ That is why we say "born married to a stock." The token, the pools, the lock, and the pairing all exist in the same block or not at all. Docs:
-
-### T2. The $32,000 ceiling, tick math, and why V5 has none
-
-1/ Some early PAIR launches plateaued around a $32,000 market cap. People called it a rule. It was a tick. Here is the full explanation and why V5 removed it. Thread.
-
-2/ A Uniswap V4 concentrated-liquidity position has a lower tick and an upper tick. Price can only move inside that range using that position's liquidity. Outside the range, the position holds only one asset and provides nothing.
-
-3/ Older narrow-range PAIR launches locked a position whose upper tick corresponded to roughly $32,000 in market cap. Once price reached it, the locked liquidity was exhausted on the project-token side. Buys had nothing left to buy from.
-
-4/ Nothing in the contract said "$32,000." It was an emergent boundary from the end tick of the locked launch position. That distinction matters because it means the fix is a range change, not a rule change.
-
-5/ V5 launches use a continuous range. For a project token that sorts as token0, the position extends from its launch tick toward the far end of tick space. There is no configured end tick inside any reachable price.
-
-6/ So what is the actual max? Uniswap's unavoidable sqrt-price limit near tick 887,200. With 18-decimal project and quote tokens that corresponds to about 3.35 x 10^38 quote tokens per project token before the stock's USD price is applied.
-
-7/ Multiply by a 1,000,000,000 fixed supply and the implied USD market cap boundary is on the order of 10^50. The docs call this "a mathematical boundary, not an economically reachable target." That is an understatement.
-
-8/ In practical terms: a V5 token has no protocol-imposed market-cap ceiling. It can trade above $32,000 without graduating, migrating, replacing its pools, or unlocking liquidity. Same pool, same lock, higher price.
-
-9/ Important nuance: oracle prices are used for launch validation and reference calculations. The V4 positions have tick parameters, but those are not a floor-to-ceiling bonding curve. Pool state sets price. The oracle does not.
-
-10/ Legacy V2/V3 tokens still use their original bonding-curve and migration lifecycle. If you see "migrate to V3" on a token page, it is one of those. V5 multi-pair tokens never show it.
-
-11/ Summary: the ceiling was a tick, V5 has no reachable end tick, and the only limit left is the one Uniswap itself imposes on every pool in existence. Docs:
-
-### T3. Balanced routing: how a multi-market swap executes
-
-1/ A PAIR token can have up to five pools: TOKEN/NVDA, TOKEN/AAPL, TOKEN/SPY and so on. Buying through one moves one price. Here is how the PAIR interface routes across all of them in one transaction. Thread.
-
-2/ Every balanced swap starts and ends in USDG. Website swaps settle in USDG, not ETH. That is a deliberate choice: one stable numeraire in, one stable numeraire out, stock tokens in the middle.
-
-3/ Buy path: USDG is converted through direct fixed-fee USDG/StockToken pools (Uniswap V3, fixed fee tier), then each stock-token tranche buys the project token in its canonical V4 pool. Sell path is the exact reverse, ending in one USDG output.
-
-4/ The split between pools is not your launch allocation. Static launch weights are never used as a route. The router quotes live marginal output from every leg and picks the split that maximizes aggregate output while every canonical pool still receives a leg.
-
-5/ Why force every pool to get a leg? Because a single-pool buy creates a cross-market price gap that arbitrageurs close at your expense. Spreading the trade keeps the composite price coherent.
-
-6/ The quote phase reads every USDG/RWA and canonical RWA/TOKEN leg. You see expected output, aggregate minimum, maximum route impact, and each leg with its allocation percentage before you sign.
-
-7/ Execution is one atomic Universal Router transaction using Permit2. V4 legs run in the canonical pools. The fixed-fee V3 legs handle only the USDG/StockToken conversion, inside the same call.
-
-8/ Fail-closed: every canonical market must have a safe direct fixed-fee USDG route. No fallback to a thin WETH/StockToken pool. Any failed leg, slippage-guard trip, stale simulation, or value-loss/impact limit breach reverts the entire swap.
-
-9/ There is also a minimum: the swap has to be large enough to route through every canonical market. Below that, the interface tells you rather than silently dropping a pool.
-
-10/ Approvals: first trade with a new input token can take up to three wallet confirmations (Permit2 allowance, permit signature, swap). The interface checks existing allowances first, so returning traders go straight to the swap.
-
-11/ External terminals (GMGN and others) can trade any single PAIR pool directly. They are plain V4 pools. We just cannot guarantee an external swap uses the balanced route, and fees from an external pool do not flow to the PAIR creator or treasury.
-
-12/ Balanced routing supports one to five canonical RWA markets. One pool is a degenerate case that still gets the fail-closed USDG guardrails. Five is the max a token can launch with. Docs:
-
-### T4. Fee pipeline from swap to claim
-
-1/ Where does the 1% swap fee on a PAIR token actually go, and how does a creator get it? Full pipeline, contract by contract. Thread.
-
-2/ Every swap in a PAIR V4 pool pays a 1% fee. That fee does not go to any wallet. It accrues inside the locked liquidity position that PairV4Locker holds.
-
-3/ Because the position is locked, fees are effectively escrowed on-chain until someone collects them. Nobody can withdraw the principal to get at them.
-
-4/ Step one, Collect. The PAIR keeper calls PairV4Locker.collectFees(tokenId). That pulls accumulated fees out of the locked V4 position into the locker's accounting. Sweeps run roughly hourly.
-
-5/ Step two, Allocate. Collected fees are split 70/30 between creator and protocol, per asset. Project-token fees and stock-token fees are tracked separately. Project-token fees are not auto-swapped.
-
-6/ Step three, Claim. The creator calls PairV4Locker.claim(asset) for each balance. The interface lists every asset separately and supports individual or sequential claims.
-
-7/ There is no minimum sweep threshold. A pool doing tiny volume still accumulates, still gets swept, still becomes claimable. Small creators are not filtered out.
-
-8/ The API exposes all of it: claimable balances across every locker (V3 locker, legacy V4 locker, current V4 locker) read live on-chain with USD values from the oracle, plus fees still sitting unswept in V3 positions, plus paginated claim history.
-
-9/ The protocol's 30% goes to the treasury at 0xbC27542Ae2ED2E4d1d380B5Fe8B2D48404fD824C, distributed at the same time as the creator's 70%.
-
-10/ What this means in practice: launch against NVDA, and 70% of a 1% fee on every trade lands in your claimable balance, part of it denominated in NVDA stock tokens, from a position that cannot be pulled. Docs:
-
-### T5. The oracle: how PAIR prices stocks on-chain
-
-1/ PAIR needs to know what AAPL costs, on-chain, every few minutes, safely. Here is the oracle stack. Thread.
-
-2/ PairPriceOracle at 0xF15F6ff9A1f0eD55b8223A4f0Bd6f9c8c0Ab877b is the on-chain registry. It holds ETH/USD and one price per supported stock token.
-
-3/ Each asset gets a PairOracleFeed wrapper that implements Chainlink's AggregatorV3Interface. The launchpad consumes prices identically to a real Chainlink feed. Any contract that reads Chainlink can read PAIR feeds unchanged.
-
-4/ Feeds are hot-swappable through StockTokenRegistry at 0xA6c3d17BA6D97B1002CdcEb4AbF9Fa3158C85ebd. Swap a feed without touching the launchpad proxy.
-
-5/ An off-chain keeper runs every 15 minutes and calls PairPriceOracle.updatePriceBatch(). Stock prices come from the Yahoo Finance real-time quote API. ETH/USD comes from DeFiLlama's coins.llama.fi with Yahoo Finance as fallback.
-
-6/ Safety-critical reads (launch validation) go through a function that reverts if a price is older than 2 hours. If the keeper falls behind, launches fail until prices refresh. No launch against a stale number, ever.
-
-7/ Assets with no public quote, like SPCX which is not listed, are skipped for that cycle and keep their previous on-chain price. The keeper logs a warning for each. It never fabricates a value.
-
-8/ The keeper is monitored and restarts automatically on failure. The launch fee (0.0005 ETH) partly subsidizes running it.
-
-9/ Scope of the oracle, precisely: launch validation, milestone reference math, fee-to-USD display. It does not set pool prices and it does not create a curve or ceiling. Pool sqrtPrice sets price. Docs:
-
-### T6. Robinhood Chain's Universal Router is not stock Uniswap
-
-1/ If you are integrating swaps on Robinhood Chain and copying the Uniswap Universal Router struct from the npm package, your calls will revert. Here is why, from our own scars. Thread.
-
-2/ The deployed router on Robinhood Chain uses a modified ExactInputSingleParams. The tuple includes a uint256 minHopPriceX36 field immediately before bytes hookData. Upstream does not have it.
-
-3/ Full tuple: (poolKey (currency0, currency1, uint24 fee, int24 tickSpacing, address hooks), bool zeroForOne, uint128 amountIn, uint128 amountOutMinimum, uint256 minHopPriceX36, bytes hookData).
-
-4/ Omit minHopPriceX36 and every field after it is misaligned. The router decodes garbage for hookData and the call reverts. It is not a permission or a liquidity issue. It is calldata layout.
-
-5/ PAIR sets minHopPriceX36 to 0 and uses amountOutMinimum for its 1% minimum-received guard. The extra field is optional in behavior but mandatory in encoding.
-
-6/ Direct swaps execute the V4 action sequence SWAP_EXACT_IN_SINGLE, SETTLE, TAKE. Encoded actions: 0x060b0e.
-
-7/ SETTLE pays the full input-token debt from the connected wallet. TAKE sends the full output-token credit back to that wallet. Simple, but you must encode them in that order.
-
-8/ Rule from the docs: validate calldata against the deployed Robinhood router ABI, not the standard Uniswap struct. We put the exact struct in the docs so nobody else spends a day on it.
-
-9/ Same lesson applies to PoolManager (0x8366a39CC670B4001A1121B8F6A443A643e40951), PositionManager, StateView, V4Quoter, Permit2: use the addresses in pair.fund/docs, not the ones you remember from mainnet. Docs:
-
-### T7. Graduation in V5, precisely
-
-1/ "Graduated" on PAIR means something different in V5 than on every other launchpad. Here is exactly what it is and is not. Thread.
-
-2/ On a bonding-curve launchpad, graduation is a phase change: the curve ends, liquidity migrates to a DEX, a new pool appears. Every one of those is a seam where users get hurt.
-
-3/ V5 has no curve to end. So graduation became an informational milestone based on how much stock-token principal has accumulated in the canonical locked positions.
-
-4/ The formula: progress = canonical locked principal / milestone target x 100%. The target is recorded at launch as 4.2 ETH times the ETH/USD oracle price at that moment.
-
-5/ What counts: stock-token principal inside the canonical launch positions. What does not: swap fees, external liquidity, continuation depth, trade volume. Only principal.
-
-6/ When principal meets or exceeds the target, the token can be flagged graduated in the on-chain PAIR registry. That call is permissionless. Anyone can make it. Not just us.
-
-7/ What changes at graduation: a flag and a badge in the explorer.
-
-8/ What does not change: the pools, the liquidity, the lock, the route, the price. Trading continues in the same V4 pools. No migration. No new pool. No ceiling. Graduation does not represent a terminal pool price.
-
-9/ The milestone target is explicitly "not the token's maximum market cap, maximum price, or the point where trading must stop." Docs quote, because people keep asking.
-
-10/ Legacy V2/V3 tokens keep their original bonding-curve and migration lifecycle. That vocabulary applies only to them. Docs:
-
-### T8. Launch protection, in the token contract
-
-1/ Most anti-snipe systems are a bot the team runs. PAIR's is five lines of logic in the token itself. Thread.
-
-2/ For the first 5 blocks after launch, PairToken enforces two limits. Not the launchpad, not a hook, not an off-chain service. The ERC-20.
-
-3/ Buy cap: no single buy transaction can acquire more than 5.5% of total supply. That is 55,000,000 tokens out of 1,000,000,000.
-
-4/ Hold cap: no wallet can hold more than 5.0% of total supply during the window. 50,000,000 tokens.
-
-5/ Both lift automatically when the 5 blocks pass. No admin call, no toggle, no "we'll disable it later." It is gone on block 6.
-
-6/ Why 5 blocks? Long enough to break a single-block snipe and a multi-tx accumulation right at launch. Short enough that real buyers barely notice it existed.
-
-7/ Why in the token? Because a bot can be turned off, bribed, or crashed. Bytecode cannot. Trust the contract, not the operator.
-
-8/ Combined with the atomic developer buy (creator's stake lands in the same block the pool exists), a PAIR launch has two structural defenses against front-running and neither requires trusting us. Docs:
-
-### T9. Multi-market market cap, and the honest caveats
-
-1/ A PAIR token paired with three stocks has three prices. How do we show one market cap, and what can go wrong? Thread, with the caveats the docs insist on.
-
-2/ Each canonical V4 pool has its own sqrtPrice. PAIR converts each pool's project-token price to USD using that pool's stock oracle price.
-
-3/ Those implied USD prices are combined using the token's configured market weights into one composite price. Market cap = composite price x 1,000,000,000 supply.
-
-4/ Caveat one: moving one market does not move the others. A large buy through only the AAPL pool creates a temporary cross-market gap. Arbitrageurs will trade it closed, and they, not you, capture that.
-
-5/ Caveat two: market cap is not guaranteed. It is computed from live oracle prices and live pool sqrtPrice. It goes down when people sell. The docs say this in a warning box.
-
-6/ Caveat three: spending $X does not raise market cap by $X. Concentrated liquidity and multi-pool composition mean the relationship is nonlinear.
-
-7/ Caveat four: a multi-market token is not a basket, index, redeemable receipt, or asset-backed product. Allocation percentages only split the fixed supply among independent pools. PAIR supplies zero stock tokens at launch.
-
-8/ Why we publish caveats in marketing: a launchpad that hides how its numbers work is a launchpad that ends badly. PAIR shows every leg, every price, every limit. Docs:
-
-### T10. The developer buy, mechanically
-
-1/ Creators on PAIR can buy their own token inside the launch transaction. Here is the exact mechanism and why atomic matters. Thread.
-
-2/ Two parameters. developerTokenAmountOut is the exact number of project tokens you want, executed via exactOutputSingle. maxQuoteAmountIn is the most stock token the contract will spend to get them.
-
-3/ Set developerTokenAmountOut to 0 and the dev buy is skipped entirely. No stock-token approval needed, launch is a single transaction.
-
-4/ Otherwise you approve the selected stock token first (tx one). The launch (tx two) transfers the computed amount from your wallet, creates the pools, then executes the swap in the one market you selected.
-
-5/ The swap runs against the live V4 pool that was created seconds earlier in the same call. So the price is real pool price at launch, not a quote.
-
-6/ maxQuoteAmountIn is a safety limit, not a price guarantee. If the exact output needs less, the difference is refunded in the same transaction. If it would need more, the launch reverts.
-
-7/ Purchased tokens go straight to your wallet. Presets in the UI run from 0.01 ETH equivalent (small stake, demonstrates alignment) up to 0.5 ETH (large early position). Exact stock cost is computed at tx time from oracle prices.
-
-8/ Why atomic matters: your first position exists in the same block as the pool. There is no gap between "pool is live" and "creator has bought" for a sniper to exploit. Docs:
-
-### T11. Non-custodial, itemized
-
-1/ "Non-custodial" is on every landing page. Here is what it means on PAIR, as a checklist you can verify on-chain. Thread.
-
-2/ Your wallet signs every transaction directly against the smart contracts. PAIR never holds funds and never controls your tokens.
-
-3/ PAIR does not execute trades on your behalf. The interface builds calldata; you sign it; your wallet submits it.
-
-4/ Launch liquidity is locked in PairV4Locker permanently. Not vested, not timelocked, not recoverable by the creator or by PAIR Labs.
-
-5/ The graduation flag is permissionless. Anyone can call it once the threshold is met.
-
-6/ The pools are standard Uniswap V4 pools. Any terminal can trade them. Our interface has no privileged path.
-
-7/ Metadata is served in an open schema (DexScreener Token Info v1.0.0), CORS-open, immutably cached. Any aggregator can read it.
-
-8/ Public price, liquidity, volume, and tx counts on pair.fund come from DexScreener. Not a private indexer we could tune.
-
-9/ Admin surfaces are documented as what they are: an application approval control, not on-chain multisig enforcement. Delisting from the interface never touches the contracts.
-
-10/ PAIR cannot reverse, cancel, or recover a transaction. That is the property you are paying for, not a limitation we apologize for. Docs:
-
-### T12. Why stocks are the better quote asset
-
-1/ Every launchpad before PAIR quoted new tokens in the chain's gas token. We think that was a constraint, not a choice, and it just got lifted. Thread.
-
-2/ Quoting in ETH or SOL means your "market cap" is denominated in an asset that itself moves 10% in a day. The number you screenshot is two volatilities multiplied together.
-
-3/ Robinhood Chain put tokenized equities on-chain: AAPL, NVDA, MSFT, TSLA, PLTR, COIN, GOOGL, META, AMD, AMZN and more, plus ETFs like SPY, QQQ, SLV, SGOV.
-
-4/ A token paired with AAPL has a USD price you can reason about because AAPL's USD price is something hundreds of millions of people already reason about.
-
-5/ Sellers receive stock tokens. Nobody who sells a project token is upset to end up holding NVDA. That changes the psychology of the exit.
-
-6/ The pairing is narrative. An AI compute token paired with NVDA. A retail-trader token paired with the brokerage's own chain's equities. Product decision, not plumbing.
-
-7/ Multi-market pairing is the unlock. One token, up to five stock-paired pools, balanced routing across all of them. That design does not exist when the only quote asset is ETH.
-
-8/ Creators get paid in stock. 70% of a 1% fee on every swap, partly in the paired stock token, from a permanently locked position. No launchpad can offer that with a gas-token quote.
-
-9/ Tokenized equities are the largest new quote-asset class on-chain since stablecoins. The first wave is holding them. The second wave is building on them. PAIR is the second wave. Docs:
-
----
-
-## LONG-FORM POSTS
-
-### L1. The design philosophy: remove every seam
-
-Every launchpad failure I have studied happened at a seam. The moment a bonding curve ends. The block where liquidity migrates. The admin key that could pull the LP. The bot that was supposed to stop snipers. Each seam is a place where the system briefly depends on something other than the contract doing what it says.
-
-PAIR V5 is what you get when you remove the seams one at a time.
-
-No bonding curve: the token trades in a real Uniswap V4 pool from the first swap, funded in the launch transaction, at an oracle-derived opening price. There is no synthetic phase.
-
-No migration: the pool you trade at second one is the pool you trade at year five. Graduation is an informational milestone (locked principal versus a target recorded at launch as 4.2 ETH times ETH/USD). It flips a flag. It moves nothing.
-
-No ceiling: the old ~$32,000 plateau was an end tick on narrow-range positions. V5 uses a continuous range toward Uniswap's extreme usable tick. The only remaining boundary is the sqrt-price limit near tick 887,200, which is a 10^50 market cap. Not a target.
-
-No pullable liquidity: every V4 position is locked in PairV4Locker permanently.
-
-No operator-run anti-snipe: PairToken itself enforces a 5.5% per-buy cap and 5.0% per-wallet cap for the first 5 blocks, then lifts them.
-
-No custodian: your wallet signs everything against contracts whose addresses are in the docs.
-
-What is left is a launch that consists entirely of contracts doing what they say. That is the whole product. pair.fund/docs
-
-### L2. Reading the fee table like an investor
-
-Here is PAIR's fee table, then what it implies.
-
-Launch fee: 0.0005 ETH, once, paid as msg.value to the protocol treasury. Pool swap fee: 1% of every swap, accrued inside the locked V4 position. Creator share: 70% of collected swap fees. Protocol share: 30%, distributed at the same time.
-
-Now the implication. A creator who launches against NVDA and gets traction earns 0.7% of every trade, forever, partly denominated in NVDA stock tokens, from a liquidity position that no one, including PAIR Labs, can withdraw. The fees accumulate inside the locked position, the keeper sweeps them roughly hourly with no minimum threshold, and the creator claims per asset via PairV4Locker.claim(asset).
-
-Compare that to launchpads where the creator's upside is "sell your allocation." PAIR creators have a durable, on-chain, equity-denominated revenue line that scales with volume and cannot be rugged by anyone, including themselves.
-
-For the protocol: 30% of 1% of all volume across every PAIR pool, plus 0.0005 ETH per launch, funding the oracle keeper and operations. Revenue is tied to activity, not to token emissions.
-
-And every number above is a read call away. The API exposes claimable balances across all lockers (V3, legacy V4, current V4) live on-chain with USD values from the oracle. pair.fund/docs
-
-### L3. Balanced routing is the moat
-
-Anyone can fork a launchpad contract. Almost nobody can fork PAIR's swap path, and here is why.
-
-A PAIR V5 token can have up to five canonical pools, each paired with a different stock token. A naive swap hits one pool, moves one price, and hands the resulting cross-market gap to arbitrageurs. PAIR's interface refuses that by default.
-
-A balanced buy takes USDG, converts it through direct fixed-fee USDG/StockToken pools (Uniswap V3, fixed tier), then buys the project token in every canonical V4 pool. The split is computed from live marginal quotes to maximize aggregate output while guaranteeing every pool receives a leg. Static launch weights are never used as a route. A balanced sell is the mirror: split across every pool, convert every stock-token output to USDG, deliver one USDG amount.
-
-It executes as one atomic Universal Router transaction with Permit2. And it fails closed: every canonical market must have a safe direct USDG route, PAIR never falls back to a thin WETH pool, and any failed leg, slippage breach, stale simulation, or impact-limit hit reverts the entire swap.
-
-On top of that, it runs on Robinhood Chain's router, whose ExactInputSingleParams carries an extra uint256 minHopPriceX36 before hookData. Get the layout wrong and the call reverts. PAIR documents the exact struct.
-
-That is not a weekend fork. Any terminal that wants to give users the real PAIR experience will be routing through logic we wrote and published. pair.fund/docs
-
-### L4. What "locked forever" means on PAIR
-
-Locked liquidity used to be a Telegram pin. On PAIR it is a contract.
-
-At launch, PairLaunchpadV5Upgradeable creates one Uniswap V4 position per selected stock token and hands each position to PairV4Locker at 0xeFcF476E8870fB3eb8680f039414fdcCE6C2a117. The locker's job is three things: hold the positions permanently, account for the swap fees each position accrues per asset, and let the creator claim their 70% share.
-
-There is no withdraw function for principal. There is no timelock that eventually expires. There is no admin path. The docs describe the positions as permanently locked and the treasury admin surface as an application approval control, not on-chain multisig enforcement, precisely because there is nothing on-chain for an admin to enforce over the principal.
-
-The consequence for traders: the liquidity you trade against on day one is the liquidity you trade against forever, and it can only grow as buys add stock tokens to the pool. The consequence for creators: your fee stream is attached to a position that cannot be pulled, by you or anyone, which is exactly why buyers can trust it.
-
-Locked is a property of the bytecode, not a promise from the team. pair.fund/docs
-
-### L5. Why we chose Chainlink-compatible feeds for a custom oracle
-
-PAIR runs its own price oracle. We could have used a bespoke interface. We did not, and the reason is composability.
-
-PairPriceOracle holds ETH/USD and every supported stock token's price. Each asset is exposed through a PairOracleFeed that implements Chainlink's AggregatorV3Interface. The launchpad consumes prices exactly as it would consume a real Chainlink feed. Any lending protocol, structured product, or vault that already reads Chainlink can read PAIR stock feeds with zero code changes.
-
-The keeper runs on a 15-minute interval and calls updatePriceBatch() with stock prices from Yahoo Finance's real-time quote API and ETH/USD from DeFiLlama with Yahoo as fallback. Safety-critical reads revert if a price is older than 2 hours, so a stalled keeper means launches fail closed rather than launch against stale data. Unlisted assets like SPCX are skipped for the cycle, retain their prior on-chain price, and log a warning. Nothing invents a number.
-
-Feeds are hot-swappable through StockTokenRegistry, so we can upgrade a source without touching the launchpad proxy.
-
-The oracle's scope is strictly launch validation, milestone math, and fee-to-USD display. It never sets pool prices. That separation is deliberate: markets price tokens; the oracle prices the stocks they are paired with. pair.fund/docs
-
-### L6. The honest paragraph about multi-market market cap
-
-We put this in the docs as a warning box, so it belongs in marketing too.
-
-A PAIR token paired with several stocks has several independent V4 prices. To show one market cap, PAIR converts each pool's price to USD via that pool's stock oracle, combines them by the token's configured market weights, and multiplies by the fixed 1,000,000,000 supply.
-
-That number is not guaranteed. It is computed from live oracle prices and live pool sqrtPrice, and it goes down when people sell. Moving one paired market does not automatically move the others: a big buy through only AAPL creates a temporary cross-market gap that arbitrageurs trade against. Spending a given USD amount does not raise market cap by that amount; concentrated liquidity is nonlinear.
-
-And a multi-market token is not a basket, index, redeemable receipt, or asset-backed product. Allocation percentages only divide the project-token supply among independent pools. PAIR supplies zero stock tokens at launch.
-
-Why lead with caveats? Because the alternative is a launchpad whose numbers people discover the hard way. PAIR shows every leg, every price, and every limit before you sign. That is what respect for traders looks like. pair.fund/docs
-
-### L7. A builder's tour of the PAIR API
-
-The PAIR API is read access to indexed on-chain state plus a few helpers. Here is what you can build with it.
-
-Tokens: search by name, symbol, token address, or creator address. Filter by paired stock token. List graduated tokens by graduation date. Fetch a single token with its V5 locked-liquidity milestone progress (or legacy bonding-curve progress for older versions).
-
-Stock tokens: every registered Robinhood Stock Token with on-chain address, oracle feed address, decimals, enabled status, and a count of community tokens launched against it.
-
-Fees: every claimable balance for a wallet across all lockers (V3, legacy V4, current V4), read live on-chain with oracle USD values. Fees still unswept inside V3 LP positions, read from the NonfungiblePositionManager. Paginated claim history.
-
-Charts: OHLCV candles for the TradingView chart.
-
-Prices: live quotes from Yahoo Finance, up to 10 symbols per request, cached 30 seconds server-side.
-
-Metadata: DexScreener Token Info schema v1.0.0, CORS-open, immutably cached. DexScreener and GMGN already consume it.
-
-Import: register an existing 18-decimal token that has a V3 pool with liquidity against an enabled stock token.
-
-Public price, liquidity, and volume on the site come from DexScreener so we do not duplicate every trade in our own indexer. Build a terminal, a fee dashboard, a launch scanner, a creator analytics page. pair.fund/docs
-
-### L8. The two transactions
-
-A PAIR launch is at most two wallet signatures. Here they are, exactly.
-
-Transaction one exists only if you want a developer buy: an ERC-20 approval on the stock token you selected, so the launchpad can pull the exact amount your buy needs. Skip the dev buy and this transaction does not exist.
-
-Transaction two is the launch. In one atomic call the launchpad deploys your PairToken with a fixed 1,000,000,000 supply and a 5-block protection window; validates every selected stock token's oracle price (reverting on anything older than 2 hours); creates one Uniswap V4 pool per selected stock token and funds it with your allocation share, from the oracle-derived launch tick toward Uniswap's extreme tick; locks every position in PairV4Locker; executes your optional exact-output dev buy in the one market you chose and refunds unused stock tokens; records the milestone target as 4.2 ETH times ETH/USD; and registers the token on-chain.
-
-Cost is 0.0005 ETH as msg.value plus gas. The interface checks your balance covers the fee plus a gas reserve before you sign, and tells you the exact shortfall if not.
-
-If anything fails, nothing happened. No orphan token, no unfunded pool, no locked position with nothing behind it. That atomicity is why "born married to a stock" is literal. pair.fund
-
-### L9. Robinhood Chain integration notes, for the people who will actually read them
-
-If you are shipping swaps on Robinhood Chain (chain ID 4663), three things will save you a day.
-
-One: the deployed Universal Router's ExactInputSingleParams is not the upstream struct. It includes uint256 minHopPriceX36 immediately before bytes hookData. Full tuple: (poolKey(currency0, currency1, uint24 fee, int24 tickSpacing, address hooks), bool zeroForOne, uint128 amountIn, uint128 amountOutMinimum, uint256 minHopPriceX36, bytes hookData). Omit the field and everything after it misaligns; the router reverts. PAIR sets it to 0 and uses amountOutMinimum for the 1% minimum-received guard.
-
-Two: direct swaps run the V4 action sequence SWAP_EXACT_IN_SINGLE, SETTLE, TAKE, encoded 0x060b0e. SETTLE pays the input debt from the wallet, TAKE returns the output credit to it.
-
-Three: use the addresses in the docs. PoolManager 0x8366a39CC670B4001A1121B8F6A443A643e40951, PositionManager 0x58daec3116aae6D93017bAAea7749052E8a04fA7, StateView 0xF3334192D15450CdD385c8B70e03f9A6bD9E673b, plus the Universal Router, V4Quoter, and Permit2 listed there. Mainnet addresses from memory will not work.
-
-PAIR pools are plain V4 pools with PairV4Hook at 0x16D1560630Ce74af4478d9b8AD46548A092A2000. Trade them directly if you like; just know that an external pool's fee does not reach the PAIR creator or treasury, and single-pool swaps skip the balanced route. pair.fund/docs
-
-### L10. Graduation used to be dangerous. Now it is a badge.
-
-On bonding-curve launchpads, graduation is the most dangerous block in a token's life. The curve ends, a migration transaction moves liquidity into a DEX pool, bots race it, and the pool you trade after is not the one you traded before.
-
-PAIR V5 kept the word and deleted the danger.
-
-There is no curve to end. Tokens trade in real Uniswap V4 pools from the launch transaction. So graduation became purely informational: progress equals canonical locked principal divided by a milestone target, where the target was recorded at launch as 4.2 ETH times the ETH/USD oracle price. Only stock-token principal in the canonical launch positions counts. Fees, external liquidity, continuation depth, and volume are excluded.
-
-When the threshold is met, anyone, permissionlessly, can flag the token graduated in the on-chain registry. The explorer shows a badge. Nothing else changes: same pools, same lock, same route, same price. The docs say the target is not a maximum market cap, not a maximum price, and not a point where trading must stop.
-
-Legacy V2/V3 tokens keep their original curve and migration lifecycle. If you see "migrate to V3" on a page, it is one of those. A V5 token will never show it. pair.fund/docs
-
-### L11. The bull case in five sentences, then the receipts
-
-Tokenized equities are the largest new quote-asset class on-chain since stablecoins, and Robinhood put them on its own chain with its own distribution. The first wave is people holding stocks on-chain; the second wave is what gets built on top of them, and a launchpad that pairs new tokens with those equities from block one is the most obvious primitive of that wave. PAIR shipped it with permanent liquidity, no migration, no ceiling, and creator revenue paid in stock tokens. The routing engine that spreads a trade across five stock-paired pools, fail-closed, on a router with a nonstandard ABI, is a moat that does not fork in a weekend. And every claim above is a read call away.
-
-Receipts: launchpad proxy 0x8660A7F019C7943b0b0A91B8E39AFf3b6DB6Ae62. Locker 0xeFcF476E8870fB3eb8680f039414fdcCE6C2a117. Oracle 0xF15F6ff9A1f0eD55b8223A4f0Bd6f9c8c0Ab877b. Registry 0xA6c3d17BA6D97B1002CdcEb4AbF9Fa3158C85ebd. All on Robinhood Chain, 4663. Fee: 1% per swap, 70/30 creator/protocol. Launch: 0.0005 ETH. Anti-snipe: 5.5% per buy, 5.0% per wallet, 5 blocks. Milestone: 4.2 ETH x ETH/USD. Ceiling: none reachable.
-
-Verify before you believe. Then launch. pair.fund
-
-### L12. Anti-snipe belongs in bytecode
-
-Every launchpad claims to fight snipers. Most do it with an off-chain bot, a whitelist, or a launch-time toggle the team controls. Each of those is a thing that can be turned off, bribed, or crashed at the wrong moment.
-
-PairToken does it in the ERC-20 itself. For the first 5 blocks after launch, no single buy can acquire more than 5.5% of supply (55,000,000 tokens) and no wallet can hold more than 5.0% (50,000,000). Both limits lift automatically once the window passes. No admin call, no toggle.
-
-Five blocks is long enough to break a single-block snipe and a rapid multi-transaction accumulation, and short enough that real buyers barely notice it. Five percent is high enough not to hurt a normal early position and low enough to make a launch-block corner impossible.
-
-Paired with the atomic developer buy (the creator's stake executes in the same transaction that creates the pool, so there is no gap for anyone to front-run), a PAIR launch has two structural defenses against launch-block predation. Neither depends on trusting PAIR Labs. Both are readable in the contract. pair.fund/docs
-
-### L13. Supported stocks, and why the registry matters more than the list
-
-Today you can launch a PAIR token against AAPL, AMD, AMZN, BABA, BE, COIN, CRCL, CRWV, GOOGL, INTC, META, MSFT, MU, NVDA, ORCL, PLTR, SNDK, SMCI, SPCX, TSLA, USAR, APP, CUSO, and the ETFs QQQ, SPY, SLV, and SGOV.
-
-The list is nice. The mechanism behind it is the point.
-
-Every supported stock is an entry in StockTokenRegistry at 0xA6c3d17BA6D97B1002CdcEb4AbF9Fa3158C85ebd, holding the stock token's on-chain address and the address of its PairOracleFeed. The launchpad reads the registry; it does not hardcode symbols. Adding a new stock is a registry entry plus a feed. Upgrading a price source is a feed swap. Neither touches the launchpad proxy.
-
-The API surfaces the same registry: address, feed, decimals, enabled status, and a count of how many community tokens have launched against each stock. That last field is a leaderboard waiting to be built.
-
-As Robinhood Chain adds tokenized equities, PAIR's quote-asset menu grows with a transaction, not a redeploy. pair.fund/docs
-
-### L14. What PAIR is not
-
-Precision prevents disappointment, so here is what PAIR is not, straight from the docs.
-
-A PAIR token is not a basket, index, redeemable receipt, or asset-backed product. Pairing with NVDA does not mean the token is backed by NVDA. Allocation percentages divide the fixed project-token supply among independent pools, and PAIR supplies zero stock tokens at launch. The stock side of each pool is filled by buyers.
-
-Market cap is not guaranteed. It is computed from live oracle prices and live pool sqrtPrice, combined by market weight, and it falls when people sell.
-
-Graduation is not a phase change. It is an informational milestone (locked principal versus 4.2 ETH x ETH/USD at launch) that flips a flag and moves nothing.
-
-PAIR is not a custodian. Your wallet signs every transaction; PAIR Labs never holds funds and cannot reverse, cancel, or recover anything.
-
-The interface is not the protocol. Delisting from the site never touches the contracts, and external terminals can trade any pool directly.
-
-What PAIR is: a launchpad where every token is born in permanently locked Uniswap V4 pools paired with tokenized stock equity, on Robinhood Chain, with 70% of swap fees going to creators. pair.fund/docs
-
-### L15. For the creator deciding where to launch
-
-You have a community, a narrative, and a token to launch. Here is the PAIR pitch as a checklist.
-
-Cost: 0.0005 ETH plus gas. Two signatures at most.
-
-Pairing: pick one to five tokenized stocks (NVDA, AAPL, SPY, PLTR, COIN and more). Your token trades against companies your holders already understand.
-
-Liquidity: created and funded in the launch transaction, from the oracle-derived launch price toward Uniswap's extreme tick, locked permanently. Nobody can pull it, including you, which is exactly why buyers can trust it.
-
-Your stake: an optional exact-output developer buy executed atomically in the same transaction, refunding unused input. Your first position lands in the same block the pool exists.
-
-Protection: 5.5% per-buy and 5.0% per-wallet caps for the first 5 blocks, enforced in the token, lifted automatically.
-
-Revenue: 70% of a 1% fee on every swap, swept roughly hourly with no minimum, claimable per asset, partly denominated in your paired stock tokens.
-
-No ceiling: continuous-range V5 pools have no reachable cap. No migration ever.
-
-Distribution: metadata served in DexScreener schema, picked up by DexScreener and GMGN automatically. Chart appears once DexScreener indexes the pool.
-
-Launch. pair.fund
-
----
-
-## SHORTS
-
-S1. Every launchpad quotes new tokens in the gas token. PAIR quotes them in NVDA, AAPL, SPY. Price discovery against a company instead of a coin that swings 10% on a Tuesday. pair.fund
-
-S2. PAIR in one line: non-custodial launchpad on Robinhood Chain, every token paired with tokenized stock equity, permanently locked Uniswap V4 pools, no migration, no ceiling.
-
-S3. Robinhood Chain, chain ID 4663. Every PAIR contract is deployed there and every address is in the docs. Verify before you trust.
-
-S4. V5 has no bonding curve. Your token trades in a real Uniswap V4 pool from the first swap.
-
-S5. The "$32,000 ceiling" was an end tick on narrow-range positions, not a rule. V5 uses a continuous range. Gone.
-
-S6. Max market cap of a V5 token: Uniswap's sqrt-price limit near tick 887,200, roughly 10^50 USD for a 1B supply. Math, not a target. No protocol cap.
-
-S7. Graduation on V5 flips a flag. It does not migrate liquidity, change the pool, cap the price, or alter the route.
-
-S8. Every V4 position PAIR creates is locked in PairV4Locker permanently. Not vested. Not timelocked. Locked.
-
-S9. Launching on PAIR: at most two transactions. Approve a stock token if you want a dev buy, then launch.
-
-S10. Launch fee: 0.0005 ETH as msg.value to the treasury. No other upfront cost.
-
-S11. PAIR supplies zero stock tokens at launch. Your 1,000,000,000 tokens are split across your chosen pools by allocation weight. Buyers fill the stock side.
-
-S12. Pick up to five paired markets. TOKEN/NVDA, TOKEN/AAPL, TOKEN/SPY, live in the same transaction.
-
-S13. Allocation weights are launch liquidity distribution. Not asset backing. Not a basket. The docs say it because we mean it.
-
-S14. Metadata is linked permanently in the token URI and served in DexScreener Token Info v1.0.0, CORS-open, immutably cached. Aggregators pick it up automatically.
-
-S15. Quote stocks on PAIR today: AAPL, AMD, AMZN, BABA, BE, COIN, CRCL, CRWV, GOOGL, INTC, META, MSFT, MU, NVDA, ORCL, PLTR, SNDK, SMCI, SPCX, TSLA, USAR, APP, CUSO. ETFs: QQQ, SPY, SLV, SGOV.
-
-S16. Adding a stock to PAIR is a StockTokenRegistry entry plus an oracle feed. No redeploy.
-
-S17. First 5 blocks: no buy over 5.5% of supply, no wallet over 5.0%. Enforced in PairToken. Lifts automatically.
-
-S18. Anti-snipe in bytecode, not in a bot. Bots get turned off. Bytecode does not.
-
-S19. 55,000,000 tokens max per buy. 50,000,000 max per wallet. Five blocks. Then free.
-
-S20. Dev buy: exact output (developerTokenAmountOut), capped input (maxQuoteAmountIn), one pool, atomic with the launch. Set output to 0 to skip.
-
-S21. The dev buy swaps against the live V4 pool created seconds earlier in the same transaction. Unused stock tokens are refunded in the same call.
-
-S22. A creator whose first position lands in the same block the pool exists cannot be front-run on their own launch.
-
-S23. 1% fee per swap. 70% creator. 30% protocol. Accrued in the locked position, swept roughly hourly, claimable any time after.
-
-S24. Launch against NVDA and earn 70% of a 1% fee on every trade, partly in NVDA, forever, from a position nobody can pull.
-
-S25. Fee pipeline: PairV4Locker.collectFees(tokenId), split 70/30 per asset, creator calls claim(asset). Three steps, all on-chain.
-
-S26. No minimum sweep threshold. If your token trades, you earn.
-
-S27. Project-token fees and stock-token fees are tracked and claimed separately. Project-token fees are not auto-swapped.
-
-S28. Claimable fees across every locker (V3, legacy V4, current V4) are read live on-chain with USD values from the oracle. One view.
-
-S29. A token with three paired pools has three prices. The PAIR interface routes across all of them by default.
-
-S30. Balanced routing: live marginal quotes pick the split that maximizes output while every canonical pool receives a leg. Launch weights are never a route.
-
-S31. Buy: USDG through fixed-fee USDG/stock pools, then every canonical RWA pool. Sell: reverse it, one USDG out. One transaction.
-
-S32. Fail-closed: any failed leg, slippage breach, stale simulation, or impact limit reverts the whole swap. Never a fallback to a thin WETH pool.
-
-S33. Permit2 plus one atomic Universal Router call. The interface checks allowances first, so returning traders go straight to the swap.
-
-S34. Before you confirm: expected output, aggregate minimum, maximum route impact, every leg with its allocation. Nothing hidden.
-
-S35. Our pools are plain Uniswap V4 pools. GMGN and any terminal can trade one directly. We just cannot promise an external swap uses the balanced route.
-
-S36. Balanced routing supports one to five canonical RWA markets and settles in USDG, not ETH.
-
-S37. Robinhood Chain's Universal Router adds uint256 minHopPriceX36 before hookData in ExactInputSingleParams. Omit it and your calldata reverts. Docs have the struct.
-
-S38. Direct swaps: SWAP_EXACT_IN_SINGLE, SETTLE, TAKE. Encoded 0x060b0e. Validate against the deployed ABI, not upstream Uniswap.
-
-S39. PairOracleFeed is Chainlink AggregatorV3-compatible. If your contract reads Chainlink, it already reads PAIR stock prices.
-
-S40. The keeper updates PairPriceOracle every 15 minutes. Stocks from Yahoo Finance, ETH/USD from DeFiLlama with Yahoo fallback.
-
-S41. Staleness guard: launch-critical reads revert on prices older than 2 hours. Stalled keeper means launches fail closed, not launch stale.
-
-S42. Unlisted assets (SPCX) keep their prior on-chain price for the cycle and the keeper logs a warning. Nothing invents a number.
-
-S43. The oracle validates launches and prices fees. It does not set pool prices. Pool sqrtPrice sets price.
-
-S44. Your wallet signs everything. PAIR never holds funds, never executes on your behalf, cannot reverse or recover a transaction.
-
-S45. We can stop displaying a token. We cannot stop it from trading. Delisting never touches the contracts.
-
-S46. Site price, liquidity, volume, and tx counts come from DexScreener, not a private indexer. What you see on PAIR is what you see everywhere.
-
-S47. Graduation is permissionless. Once locked principal meets the target, anyone can flip the flag.
-
-S48. V5 graduation: progress = canonical locked principal / (4.2 ETH x ETH/USD at launch). Fees, volume, outside liquidity do not count.
-
-S49. The milestone target is not a max price, not a max market cap, not a stop. The docs say it three times because people keep asking.
-
-S50. Legacy V2/V3 tokens keep their bonding-curve lifecycle. That vocabulary never applies to a V5 launch.
-
-S51. Multi-market market cap: each pool price to USD via its stock oracle, combined by weight, times 1B supply. It can go down. We say so.
-
-S52. A big buy through only the AAPL pool creates a cross-market gap that arbs close. Balanced routing avoids creating the gap.
-
-S53. Tokenized equities are the biggest new quote asset on-chain since stablecoins. PAIR is the launchpad for what gets built on them.
-
-S54. Permanent liquidity. No migration. No ceiling. No custodian. Creator revenue in stock tokens. Name another launchpad with all five.
-
-S55. The routing is the moat. Fail-closed atomic execution across five stock-paired pools on a router with a nonstandard ABI. Not a weekend fork.
-
-S56. Locked liquidity used to be a Telegram pin. On PAIR it is a contract address: 0xeFcF476E8870fB3eb8680f039414fdcCE6C2a117.
-
-S57. Launch a token paired with NVDA in two transactions and 0.0005 ETH. pair.fund
-
-S58. Creators: your fees have been accruing since your first trade. Claim them. pair.fund
-
-S59. Builders: the API and contract table are public. Ship something on PAIR and tag us.
-
-S60. Every token on PAIR is born married to a stock. Launch one. pair.fund
-
----
-
-<a id="sec-277"></a>
+<a id="sec-286"></a>
> **Source:** `docs/marketplace.md` · [↑ table of contents](#table-of-contents)
@@ -63982,7 +66236,7 @@ before anything is granted.
| **Bundle** | — | `purchase-bundle.js` | `skill_purchases` |
Agents can buy on their own behalf, paying from their custodial wallet (see
-[Agent wallets](#sec-072)) with no browser wallet involved:
+[Agent wallets](#sec-074)) with no browser wallet involved:
| Buying | Endpoint | Request |
|---|---|---|
@@ -64067,7 +66321,13 @@ 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.
+chain decides, so a throttled node never blocks a payable purchase. The other
+chain reads on the checkout paths (the recent blockhash here and in the agent
+purchase, the mint decimals in `agent-purchase.js` and `purchase-as-agent.js`)
+go through the shared Solana read guards in `api/_lib/solana/read-guards.js`: a
+cached blockhash still inside its validity window answers when the chain cannot,
+and USDC-class mints resolve their decimals from a constant table without a
+network call, so an RPC blip degrades to a served request instead of a 500.
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.
@@ -64080,7 +66340,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-292)).
+ `payment-earned` notification (see [Money feed](#sec-302)).
## Access checks
@@ -64130,7 +66390,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-559) endpoint returns the
+ paid [`/api/x402/skill-marketplace`](#sec-584) 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
@@ -64148,13 +66408,13 @@ 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-141) — manufactured marketplace demand.
-- [Skills system](#sec-399), [Coin launches](#sec-144).
+- [Agent wallets](#sec-074) — how agent-side purchases are funded and gated.
+- [Circulation engine](#sec-145) — manufactured marketplace demand.
+- [Skills system](#sec-417), [Coin launches](#sec-148).
---
-<a id="sec-278"></a>
+<a id="sec-287"></a>
> **Source:** `docs/mcp-3d-studio.md` · [↑ table of contents](#table-of-contents)
@@ -64226,7 +66486,8 @@ 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-407) 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-425) artifact. Free. See [AR & WebXR](ar.md#one-tap-ar-for-any-glb--get-apiar--export_ar). |
+| `x402_preflight(origin, network?)` | Read-only, free: fetch an x402 seller's signed payability attestation from `<origin>/.well-known/x402-preflight`, verify its ed25519 signature, expiry, and subject, and answer whether that seller can actually settle before you pay it. An attestation that does not verify is reported as unverified, never as health. Spec: [`specs/x402-preflight.md`](../specs/x402-preflight.md). |
Generation, rigging, and most mesh ops are **asynchronous**: the tool returns a
`job_id` immediately, then you poll `generation_status` (reconstruction is
@@ -64303,6 +66564,8 @@ timestamp.
| `tripo` | geometry, image | **BYOK** | Cleanest quad topology. |
| `hunyuan3d` | image | self-host | High-poly, image-conditioned (GCP). |
+When no `backend` is named, the resolver walks the free lanes first: the tier's named free engine (the self-hosted TRELLIS worker at `draft` and `standard`, the self-hosted Hunyuan3D worker at `high`), then the per-path fallback chain (self-host TRELLIS, self-host Hunyuan3D, the free HuggingFace Spaces lane, and last the free NVIDIA NIM TRELLIS lane, which is text-only). The paid Replicate `trellis` lane is the standing default only when no free lane is live on the deployment. Lane health is consulted, so a cold or down free worker is skipped for the next healthy one before submit.
+
**BYOK note:** the geometry backends (Meshy/Tripo) have no platform key. Supply
your own via the `x-forge-provider-key` request header (or a key stored on your
three.ws account). Without one, the geometry path returns a designed `needs_key`
@@ -64330,8 +66593,9 @@ For tool calls there are two lanes:
| `text_to_3d` / `image_to_3d` | by tier — $0.05 draft / $0.15 standard / $0.50 high |
| `auto_rig_model`, `retexture_model`, `retexture_region` | $0.05 |
| `stylize_model`, `remesh_model`, `segment_model` | $0.02 |
+| `capture_scene`, `anchor_provenance` | $0.05 |
| `remove_background`, `pose_model`, `apply_animation`, `direct_prompt`, `generate_material` | $0.01 |
-| `generation_status`, `preview_3d`, `list_animations`, `animation_signature`, `find_similar_animations`, `inspect_model`, `optimize_model`, `getting_started` | free |
+| `generation_status`, `preview_3d`, `list_animations`, `animation_signature`, `find_similar_animations`, `text_to_animation`, `inspect_model`, `optimize_model`, `save_avatar`, `export_ar`, `verify_provenance`, `x402_preflight`, the persona tools, `validate_spatial_response`, `getting_started` | free |
Payment settles only after the work succeeds — a wholesale failure costs
nothing, and the same signed payment cannot be replayed.
@@ -64395,7 +66659,7 @@ npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-3d
---
-<a id="sec-279"></a>
+<a id="sec-288"></a>
> **Source:** `docs/mcp-agent.md` · [↑ table of contents](#table-of-contents)
@@ -64502,13 +66766,13 @@ npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-agent
---
-<a id="sec-280"></a>
+<a id="sec-289"></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-284) carries an
+Every tool three.ws publishes over the [Model Context Protocol](#sec-293) 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
@@ -64837,7 +67101,7 @@ All four run in `npm run gate`.
---
-<a id="sec-281"></a>
+<a id="sec-290"></a>
> **Source:** `docs/mcp-studio.md` · [↑ table of contents](#table-of-contents)
@@ -64891,31 +67155,34 @@ store-clean responses (model URLs and job state only). The machine-readable
contract is the OpenAPI schema the platform serves at
[`https://three.ws/.well-known/3d-studio-openapi.yaml`](../public/.well-known/3d-studio-openapi.yaml),
which is what the custom GPT imports; the same endpoint is written up in prose in
-the [API reference](#sec-096). Use the MCP connector above when you
+the [API reference](#sec-098). Use the MCP connector above when you
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-139).
+[AR in ChatGPT](#sec-142).
## Tools
-`tools/list` returns exactly **ten** tools, and they split three ways:
+`tools/list` returns exactly **eleven** tools, and they split four ways:
- **Six generation tools** (`forge_free`, `text_to_avatar`, `mesh_forge`,
`rig_mesh`, `forge_avatar`, `refine_model`), in the table below.
- **One collector**, `check_job`, also in the table below.
+- **One inspector**, `look_at_model`, also in the table below.
- **Three persona/embodiment tools** (`create_agent_persona`,
`get_agent_persona`, `persona_say`), in the **Embodiment** section further down.
-All ten are free and keyless.
+All eleven are free and keyless.
The six generation tools run operator-funded on the platform's own generation
pipeline. Annotations: `readOnlyHint:false`, `destructiveHint:false`,
`idempotentHint:false`, `openWorldHint:true` (work runs against external model
APIs; nothing is ever modified or deleted). `check_job` is the exception: it is a
pure status probe (`readOnlyHint:true`, `idempotentHint:true`) and never counts
-against the generation quota.
+against the generation quota. `look_at_model` is read-only and idempotent too,
+but it renders frames server-side, so it rides the same per-IP generation
+quota as the six generators.
| Tool | Title | Input | Returns |
|---|---|---|---|
@@ -64926,6 +67193,7 @@ against the generation quota.
| `forge_avatar` | Generate a rigged, animation-ready avatar | `prompt?` / `image_url?`, `allow_non_humanoid?` | rigged GLB avatar |
| `refine_model` | Refine a 3D model by describing a change | `glb_url`, `instruction`, `parent_prompt?`, `parent_lineage?`, `parent_index?` | refined GLB + version lineage |
| `check_job` | Check a pending 3D generation and collect it | `job_id` | GLB model, or an updated pending state |
+| `look_at_model` | Look at a 3D model | `glb_url`, `views?` (up to 6 of `front`, `three-quarter`, `side`, `back`, `top`, `bottom`; default three-quarter, front, side, back), `size?` (128 to 1024 px, default 512) | rendered frames as images, plus geometry stats (triangles, materials, textures) and a plain reading of them |
### Quality tiers
@@ -64950,7 +67218,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-284)) also ships a tool called `forge_free`. That is a different
+([docs](#sec-293)) 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`.
@@ -64976,9 +67244,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-139)).
+`arUrl` is the one-tap place-in-your-room link (see [AR in ChatGPT](#sec-142)).
Rigged avatars additionally carry `irlUrl`, the living-agent handoff into
-[IRL](#sec-259), and the inline widget's AR button becomes **Bring it to life**.
+[IRL](#sec-270), 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.
@@ -65184,11 +67452,14 @@ rows, cloned so the ChatGPT pipeline can be tuned without touching the forge or
any surface that rides it. The agent-facing REST endpoints (`/api/3d/generate`,
`/api/v1/ai/text-to-3d`) stay on `/api/forge`.
-The inline widget and the `/api/ar` launch page both load Google's
-`<model-viewer>` from one pinned URL in
+The inline widget loads Google's `<model-viewer>` from one pinned URL in
[`api/_lib/model-viewer-cdn.js`](../api/_lib/model-viewer-cdn.js), which is also
the origin the widget's `openai/widgetCSP` allowlists, so the script tag and its
-CSP entry cannot drift apart.
+CSP entry cannot drift apart. The `/api/ar` launcher no longer inlines a
+`<model-viewer>` of its own: Android gets a Scene Viewer intent, and every other
+device (and every live avatar) is sent on to `/ar/view`, a Vite-bundled page
+that generates a real USDZ from the GLB on the device so iPhone gets genuine
+Quick Look rather than a camera overlay (`api/_lib/ar-launch.js`).
## Related
@@ -65199,15 +67470,15 @@ CSP entry cannot drift apart.
---
-<a id="sec-282"></a>
+<a id="sec-291"></a>
> **Source:** `docs/mcp-tools.md` · [↑ table of contents](#table-of-contents)
# MCP Tools Catalog
-three.ws ships several [MCP](#sec-284) servers: tool servers that AI assistants
+three.ws ships several [MCP](#sec-293) 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-563). This
+others expose paid tools that settle per call in USDC over [x402](#sec-589). 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
@@ -65246,7 +67517,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-281).
+[3D Studio MCP](#sec-290).
## Material Studio (hosted, free) — `/api/material-studio`
@@ -65288,8 +67559,15 @@ and direction tools are flat per call.
| `anchor_provenance` | $0.05 | Sign a content credential and anchor its hash on Solana. |
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-407) conformance gate).
+`preview_3d`, `list_animations`, `animation_signature`, `find_similar_animations`,
+`text_to_animation`, `inspect_model`, `optimize_model`, `save_avatar`, `export_ar`,
+`verify_provenance`, `x402_preflight` (asks any x402 seller's signed payability
+attestation whether it can actually settle before you pay it; free on purpose and
+permanently), the persona tools (`create_agent_persona`, `get_agent_persona`,
+`persona_say`, `persona_identity`, `persona_tip`, `persona_send`), and
+`validate_spatial_response` (the [Spatial MCP](#sec-425) conformance gate).
+Every catalog tool is either priced or on this explicit free list; a test fails
+the build if a new tool is neither.
## Agent & commerce tools — `3d-agent-local`
@@ -65318,7 +67596,7 @@ generation lane**; the rest are paid and quote their price in the
| `vanity_grinder` | paid | Solana vanity address mining. |
| `vanity_premium` | free | Browse the premium pre-ground vanity address inventory. |
| `aixbt_intel` / `aixbt_projects` | paid | Market narrative intel feed / momentum-ranked project scans. |
-| `agenc_list_tasks` / `agenc_get_task` / `agenc_get_agent` | paid | [AgenC](#sec-008) coordination reads. |
+| `agenc_list_tasks` / `agenc_get_task` / `agenc_get_agent` | paid | [AgenC](#sec-009) coordination reads. |
| `agent_delegate_action` | paid | Agent-to-agent delegation. |
| `agent_hire_discover` | paid | Discover + reputation-rank agents to hire for a task. |
| `agent_hire` | paid | Hire an agent end to end: quote, settle USDC via x402, run it, return result + provenance receipt, with hard spend caps. |
@@ -65332,9 +67610,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-283). |
-| IBM MCP | `api/ibm-mcp.js` | watsonx / Granite integration — see [IBM](#sec-253). |
-| pump.fun MCP | `api/pump-fun-mcp.js` | Launch/trade tools — see [Solana pump.fun](#sec-404). |
+| Bazaar MCP | `api/mcp-bazaar.js` | x402 service discovery — see [x402 bazaar](#sec-292). |
+| IBM MCP | `api/ibm-mcp.js` | watsonx / Granite integration — see [IBM](#sec-263). |
+| pump.fun MCP | `api/pump-fun-mcp.js` | Launch/trade tools — see [Solana pump.fun](#sec-422). |
## $THREE only
@@ -65345,16 +67623,16 @@ promote no specific token.
## Related
-- [MCP](#sec-284) overview · [3D Studio MCP](#sec-281) ·
- [3D Studio (paid)](#sec-278) · [x402 bazaar](#sec-283)
-- [x402 paid endpoints](#sec-559) — the same capabilities over REST.
-- [MCP tool safety](#sec-280) - what each tool's safety annotations mean,
+- [MCP](#sec-293) overview · [3D Studio MCP](#sec-290) ·
+ [3D Studio (paid)](#sec-287) · [x402 bazaar](#sec-292)
+- [x402 paid endpoints](#sec-584) — the same capabilities over REST.
+- [MCP tool safety](#sec-289) - 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-283"></a>
+<a id="sec-292"></a>
> **Source:** `docs/mcp-x402-bazaar.md` · [↑ table of contents](#table-of-contents)
@@ -65466,7 +67744,7 @@ npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-bazaar
---
-<a id="sec-284"></a>
+<a id="sec-293"></a>
> **Source:** `docs/mcp.md` · [↑ table of contents](#table-of-contents)
@@ -65530,7 +67808,7 @@ There are two kinds. **Hosted remote servers** run over Streamable HTTP with not
| 3D Studio (free) | `/api/mcp-studio` | Free text/image→3D and rigged avatars — no auth, no payment |
| Agent wallet | `/api/mcp-agent` | The agent's custodial wallet: balance, find + pay services, and `monetize_endpoint` |
| x402 Bazaar | `/api/mcp-bazaar` | Discover and price paid agent services across the facilitator network |
-| pump.fun | `/api/pump-fun-mcp` | Free pump.fun + Solana token tools; `pumpfun_upload_metadata` needs a key |
+| pump.fun | `/api/pump-fun-mcp` | Free pump.fun + Solana token tools; `get_new_tokens` and `get_trending_tokens` read the live pump.fun feed with no indexer needed; `pumpfun_upload_metadata` needs a key |
| IBM x402 | `/api/ibm-mcp` | Pay-per-use IBM Granite AI |
**Thirty-eight install-and-run servers** on npm under the `@three-ws` scope, each running over stdio with one command:
@@ -65581,6 +67859,7 @@ npx -y @three-ws/agent-sniper serve # the same engine as an x402-paid HTTP API (
# Account, inbox & discovery
npx -y @three-ws/notifications-mcp # inbox, read state, delivery prefs & Web Push devices
+npx -y @three-ws/herald-mcp # tell your human in person: your avatar walks on and says it
npx -y @three-ws/billing-mcp # plan quotas, metered usage, invoices & receipts
npx -y @three-ws/activity-mcp # trending agents/coins, $THREE holder board & activity ticker
@@ -65616,8 +67895,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-281) · [3D Studio (paid)](#sec-278) · [Agent wallet](#sec-279) · [x402 Bazaar](#sec-283) · [IBM x402](#sec-252)
-- **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-282) maps every tool to its server and price.
+- **Hosted remote:** [3D Studio (free)](#sec-290) · [3D Studio (paid)](#sec-287) · [Agent wallet](#sec-288) · [x402 Bazaar](#sec-292) · [IBM x402](#sec-262)
+- **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-291) maps every tool to its server and price.
---
@@ -66005,13 +68284,13 @@ 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-421) 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-439) for the full verification flow, the anti-abuse token/rate-limit design, and how visitors unlock the embed.
---
### `crypto_data`
-Call any endpoint in the free [Crypto Data API](#sec-096) (the same aggregator behind `GET /api/v1/x/*`: DEX pairs, CoinGecko/DefiLlama market data, Jupiter Solana prices and swap quotes, direct Solana RPC reads) as an MCP tool call. The tool description is generated from the live provider registry at call time, so it always lists exactly the provider/endpoint pairs registered on this deployment — nothing hand-enumerated to drift out of date.
+Call any endpoint in the free [Crypto Data API](#sec-098) (the same aggregator behind `GET /api/v1/x/*`: DEX pairs, CoinGecko/DefiLlama market data, Jupiter Solana prices and swap quotes, direct Solana RPC reads) as an MCP tool call. The tool description is generated from the live provider registry at call time, so it always lists exactly the provider/endpoint pairs registered on this deployment — nothing hand-enumerated to drift out of date.
```json
{
@@ -66026,7 +68305,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-563) — 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-589) — never a second, MCP-only payment flow.
```bash
# Equivalent to: GET /api/v1/x/dexscreener/token?addresses=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
@@ -66294,7 +68573,7 @@ Contributors: `npm run audit:mcp-safety` enforces this. It parses each tool's ha
---
-<a id="sec-285"></a>
+<a id="sec-294"></a>
> **Source:** `docs/media-api.md` · [↑ table of contents](#table-of-contents)
@@ -66832,7 +69111,10 @@ 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-308)
+of being coerced into a page. The manifest is served with
+`access-control-allow-origin: *`, so a studio embedded on another origin can
+render the object tray from it (the objects themselves already load cross-origin
+through `/cdn/<key>`). See [the object library doc](#sec-319)
for the full parameter table.
### Response
@@ -66899,7 +69181,7 @@ the mesh arrived static, queues an auto-rig so the avatar can animate.
### Response
-`201` with `{ "avatar": { ... }, "view_url": "https://three.ws/discover/avatar/<id>" }`.
+`201` with `{ "avatar": { ... }, "view_url": "https://three.ws/avatars/<id>" }` (the avatar detail page, the canonical link target across the platform).
### Errors
@@ -66982,7 +69264,11 @@ Poll the job on `/api/forge?job=<job_id>` like any forge generation.
| Rate limit | `429` with `Retry-After` |
When the vision lane is unconfigured or errors, the face check fails open and
-the submission proceeds; forge still validates the image.
+the submission proceeds; forge still validates the image. The hand-off to
+`/api/forge` is bounded to 30 seconds and is deliberately never retried, since
+that POST enqueues a generation and a replay would queue (and bill) a second
+job; a hang there surfaces as `502 generation_unreachable` rather than an
+endpoint that never answers.
### curl
@@ -67040,6 +69326,9 @@ policy as `/api/input-photo`. No auth; rate-limited per IP.
| Generation service unreachable | `502 generation_unreachable` |
| Rate limit | `429` with `Retry-After` |
+As with `/api/input-photo`, the hand-off to `/api/forge` is bounded to 30
+seconds and never retried, so the same photos can never be queued twice.
+
### curl
```bash
@@ -67184,13 +69473,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-254) - the photo-input reconstruction product these front doors feed
-- [Voice Lab](#sec-521) - voice cloning and synthesis, the other half of the avatar voice loop
-- [API Reference](#sec-096) - the full three.ws HTTP API surface
+- [Image to 3D](#sec-264) - the photo-input reconstruction product these front doors feed
+- [Voice Lab](#sec-541) - voice cloning and synthesis, the other half of the avatar voice loop
+- [API Reference](#sec-098) - the full three.ws HTTP API surface
---
-<a id="sec-286"></a>
+<a id="sec-295"></a>
> **Source:** `docs/memetic-launcher.md` · [↑ table of contents](#table-of-contents)
@@ -67295,12 +69584,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-351) — 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-364) — 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-287"></a>
+<a id="sec-296"></a>
> **Source:** `docs/memory.md` · [↑ table of contents](#table-of-contents)
@@ -67712,7 +70001,7 @@ store described above and each revocable by deleting exactly what it wrote:
---
-<a id="sec-288"></a>
+<a id="sec-297"></a>
> **Source:** `docs/meta-allocator.md` · [↑ table of contents](#table-of-contents)
@@ -67806,14 +70095,14 @@ plan `source` is `"empty"` with a helpful message instead of an error.
## Related
-- [Trader Card & the claim-your-wallet wedge](#sec-423)
-- [The trading surfaces](#sec-429) · [/vaults](https://three.ws/vaults) (copy-trade with custody guardrails)
-- [Clip Director: every trade becomes content](#sec-143)
-- [Financial controls & custody guardrails](#sec-222)
+- [Trader Card & the claim-your-wallet wedge](#sec-441)
+- [The trading surfaces](#sec-447) · [/vaults](https://three.ws/vaults) (copy-trade with custody guardrails)
+- [Clip Director: every trade becomes content](#sec-147)
+- [Financial controls & custody guardrails](#sec-229)
---
-<a id="sec-289"></a>
+<a id="sec-298"></a>
> **Source:** `docs/mint-mark.md` · [↑ table of contents](#table-of-contents)
@@ -67939,13 +70228,13 @@ No other mint should appear in tests, fixtures, or documentation.
## Related
-- [Solana agents](#sec-406) — agent wallet management and on-chain interactions
-- [Solana pump.fun signals](#sec-404) — pump.fun live feed integration
-- [ERC-8004](#sec-189) — on-chain agent registry (uses the same brand metadata builder)
+- [Solana agents](#sec-424) — agent wallet management and on-chain interactions
+- [Solana pump.fun signals](#sec-422) — pump.fun live feed integration
+- [ERC-8004](#sec-195) — on-chain agent registry (uses the same brand metadata builder)
---
-<a id="sec-290"></a>
+<a id="sec-299"></a>
> **Source:** `docs/minted.md` · [↑ table of contents](#table-of-contents)
@@ -67953,7 +70242,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-347) (signed credentials, Solana anchoring, the free verify endpoint) and [the three.ws mint mark](#sec-289) (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-360) (signed credentials, Solana anchoring, the free verify endpoint) and [the three.ws mint mark](#sec-298) (the `3ws` address branding on coin launches).
## The gallery
@@ -67985,7 +70274,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-284). 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-293). 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.
@@ -68008,7 +70297,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-347). For the `3ws` address mark that brands coin launches, read [mint-mark.md](#sec-289).
+For how signed credentials, canonical hashing, and on-chain anchoring work under the hood, read [provenance.md](#sec-360). For the `3ws` address mark that brands coin launches, read [mint-mark.md](#sec-298).
### Remix royalties: paid the moment a remix mints
@@ -68022,14 +70311,14 @@ The companion MCP tool `get_3d_asset_onchain` resolves any Core mint address to
## Related
-- [Verifiable 3D provenance](#sec-347): signed content credentials and free verification for generated models
-- [The three.ws mint mark](#sec-289): the `3ws` address brand on coin launches
-- [MCP servers](#sec-284): the `mint_3d_asset` and `get_3d_asset_onchain` tools
-- [Custody you can verify](#sec-171): the wallet rails behind agent-held assets
+- [Verifiable 3D provenance](#sec-360): signed content credentials and free verification for generated models
+- [The three.ws mint mark](#sec-298): the `3ws` address brand on coin launches
+- [MCP servers](#sec-293): the `mint_3d_asset` and `get_3d_asset_onchain` tools
+- [Custody you can verify](#sec-177): the wallet rails behind agent-held assets
---
-<a id="sec-291"></a>
+<a id="sec-300"></a>
> **Source:** `docs/mocap-studio.md` · [↑ table of contents](#table-of-contents)
@@ -68121,14 +70410,278 @@ what the page itself sends.
## Related
-- [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.
+- [Avatar Studio](#sec-117): build the avatar you drive here.
+- [Animation Studio](#sec-094): body posing and keyframed motion, the complement to facial capture.
+- [Animations reference](#sec-095): 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-292"></a>
+<a id="sec-301"></a>
+
+> **Source:** `docs/model-diff.md` · [↑ table of contents](#table-of-contents)
+
+# Model Diff
+
+**[Model Diff](https://three.ws/diff) answers the question a checksum cannot: not "are these two models different" but "what changed, and did anything just break".**
+
+Drop a `.glb` on each side and you get a change set: every mesh, material, texture, node, skeleton, and animation clip classified as added, removed, renamed, moved, or modified, with renames detected by content rather than by name, and a severity you can gate a build on. Both models render in the same 3D scene so you can overlay them, wipe between them, or set them side by side, and clicking any node in the report frames that object in the viewport.
+
+Files you drop are read with the browser File API and compared in your tab. Nothing is uploaded. A model given as a URL is fetched through the site's own GLB proxy (`/api/glb`), because an arbitrary CDN will not send the CORS header a browser needs to read it directly.
+
+**On this page:** [The problem](#the-problem-a-model-that-loads-and-never-moves) · [Reading the report](#reading-the-report) · [Severity](#severity) · [How matching works](#how-matching-works) · [What counts as a change](#what-counts-as-a-change) · [The viewer](#the-viewer) · [The API](#the-api) · [The CLI](#the-cli) · [The MCP tool](#the-mcp-tool) · [The library](#the-library)
+
+Related: [Rig Doctor](#sec-395) answers whether a single rig will animate at all; Model Diff answers whether the rig you already shipped still will. [Asset pipeline](#sec-002) covers the conversion and optimization steps whose output this is built to check. The free [3D API](https://three.ws/api/3d) lists this endpoint alongside inspect and generate.
+
+---
+
+## The problem: a model that loads and never moves
+
+Animation clips address joints **by name**. So do attachment points, wardrobe anchors, and every retargeter in the pipeline.
+
+That means the most expensive change a 3D asset can undergo is also the quietest one. Rename a bone, drop a joint, re-export through a tool that renumbers `Mesh.001`, and the file still parses, still renders, and the mixer still runs at 60fps against tracks that now address nothing. There is no exception, no console error, nothing to grep for. You find out when someone says the character is standing in a T-pose.
+
+Every tool that could have caught it fails at exactly this point:
+
+- **A byte comparison** flags every re-export, including the ones that changed nothing observable. It is right too often to be useful.
+- **File size** moves for both a texture recompression and a deleted limb.
+- **A visual check** in a viewer catches missing geometry and misses a missing joint entirely, because a broken rig looks perfect in bind pose.
+
+Model Diff is the check that separates them.
+
+---
+
+## Reading the report
+
+### The verdict
+
+The banner carries the overall severity, the counts, and one plain-language sentence about what that severity means. Below it sit the highlights: three to eight sentences, worst first, written to be the only part you read when you are in a hurry.
+
+```
+BREAKING 98 changes: +6 / -13 / ~70 / renamed 4 / moved 1
+
+Skeleton "Character" lost 2 joints: mixamorig:LeftEye, mixamorig:RightEye. Clips that target them will not play.
+Skeleton "Armature" was removed. The model is no longer rigged.
+5 animations were removed ("agree", "idle", "run" and 2 more). Anything that plays them by name will fail.
+Triangle count is down 21,006 (-42.8%).
+```
+
+### Totals
+
+Only the metrics that moved: vertices, triangles, joints, nodes, meshes, materials, textures, animations, skeletons, texture bytes, and file size, each with before, after, delta, and percent. A row that did not change is not printed, because a wall of zeroes is what makes people stop reading diff output.
+
+### Sections
+
+One collapsible block per object kind, ordered by how much a change there costs you: skeletons, animations, meshes, nodes, materials, textures. Blocks whose severity is `major` or `breaking` open by themselves.
+
+Each row is marked the way a diff is:
+
+| Mark | Meaning |
+| --- | --- |
+| `-` | Removed: present in the baseline, gone from the candidate |
+| `+` | Added: new in the candidate |
+| `R` | Renamed: same content, different name |
+| `M` | Moved: same node, different parent |
+| `~` | Modified, with the changed fields listed underneath |
+
+Node rows are clickable. Selecting one frames that object in the 3D viewer, which is the fastest way to answer "where is `mixamorig:LeftHandIndex1` and what happened to it".
+
+---
+
+## Severity
+
+| Level | Meaning |
+| --- | --- |
+| `none` | The two models are structurally identical |
+| `cosmetic` | Only metadata changed. Nothing a renderer or a clip can observe |
+| `minor` | Appearance changed. The model still loads, animates, and keeps its shape |
+| `major` | Geometry or hierarchy changed. Anything positioned against this model should be re-checked |
+| `breaking` | Something a consumer references by name is gone. Clips, attachments, or materials bound to it will fail |
+
+The ladder is defined by what a downstream consumer notices, not by how large the byte delta is. A 40 MB texture swap is `minor`, because everything still loads and plays. Deleting one joint is `breaking`, because every clip that addressed it silently stops moving.
+
+---
+
+## How matching works
+
+A diff is only as good as its matching. Compare by name alone and every exporter that renumbers `Mesh.001` reports the whole file as rewritten. Compare by content alone and a rename looks like a deletion plus an unrelated addition.
+
+So objects are paired in three passes, the same strategy `git` uses for file renames:
+
+1. **By key.** The names agree, so the objects correspond.
+2. **By fingerprint.** The names disagree but the content hashes identically, so it is a rename.
+3. **By similarity.** Neither agrees, but one candidate scores close enough that "the same object, edited and renamed" is more honest than reporting an add and a remove.
+
+Anything still unpaired after all three really is an addition or a removal.
+
+Nodes carry a fourth distinction. A node that kept its name and changed parent is reported as **moved**, not as a rename, because reparenting changes where anything attached to that node ends up in world space even when nothing about the node itself changed.
+
+Objects the file never named are labelled `(unnamed mesh 3)` and keyed to their slot, so they only ever pair with the same slot on the other side. Inventing a name like `mesh.3` would read as a real name in the report and, worse, would match an unrelated object that happened to come fourth in the other file.
+
+If one section has so many unpaired candidates that the similarity pass would be quadratic beyond a sane bound, that pass is skipped and the report **says so** on that section rather than quietly downgrading renames into add-and-remove noise.
+
+---
+
+## What counts as a change
+
+### Geometry
+
+Vertex data is hashed at a quantum of `1e-4` units, roughly a tenth of a millimetre at human scale. A re-export through Blender, a `gltfpack` round trip, or a Draco decode perturbs positions in the `1e-6` range and does not register. A genuine edit moves vertices by orders of magnitude more and does.
+
+Positions are not the only thing hashed. Normals, tangents, UV sets, vertex colors, and **skin joints and weights** all participate, because a re-skin that leaves every vertex exactly where it was still changes how the model deforms. A positions-only hash would call that unchanged, which is the wrong answer for the exact case this tool exists to catch.
+
+The report distinguishes two kinds of geometry edit, because they mean different things:
+
+- *same vertex and triangle count, different vertex data*: usually a re-bake, a re-skin, or a transform applied in place
+- *vertex data rewritten*: a decimation, a remesh, or a different asset entirely
+
+### Skeletons
+
+Joint lists are compared by name. A removed joint is `breaking` and the report names it. A changed inverse-bind matrix set is `major` and says why: the bind pose moved, so existing clips will deform differently even though every joint is still present.
+
+### Animations
+
+Clips are compared on duration, channel count, keyframe count, interpolation modes, and the full list of `node.path` targets they drive. A target that disappears is `breaking` and is listed individually, because that is the precise mechanism by which a clip stops animating part of a character while still playing.
+
+### Materials and textures
+
+Every PBR factor, every texture slot assignment, alpha mode and cutoff, double-sidedness, and the material extension list. Textures are compared on dimensions, MIME type, byte size, and a hash of the encoded image, so a re-encode is distinguished from a repaint.
+
+### Extensions
+
+`extensionsUsed` and `extensionsRequired` are diffed separately. A newly **required** extension is `major` on its own: a viewer without support for it will refuse the file outright, which is not a rendering difference but a load failure.
+
+---
+
+## The viewer
+
+Three modes, switchable with the keyboard (`O`, `W`, `S`; `H` toggles highlighting, `F` re-frames):
+
+- **Overlay.** The baseline renders as a translucent blue ghost with the candidate solid on top. Best for spotting a shifted limb or a changed silhouette.
+- **Wipe.** One screen-aligned clipping plane, dragged across the view. The plane is rebuilt from the camera basis every frame, so the seam stays vertical on screen no matter where you orbit.
+- **Side by side.** Both models placed apart and orbiting together.
+
+Changed objects are marked by cloning the authored material and pushing its emissive toward the marker colour (amber for edited, green for added, red for removed), rather than replacing it with a flat fill. The model still looks like itself; the changed parts glow.
+
+---
+
+## The API
+
+`GET /api/3d/diff` is free and keyless, part of the [3D API bundle](https://three.ws/api/3d).
+
+```bash
+curl "https://three.ws/api/3d/diff?a=https://three.ws/avatars/cesium-man.glb&b=https://three.ws/avatars/michelle.glb"
+```
+
+```jsonc
+{
+ "version": 1,
+ "identical": false,
+ "severity": "breaking",
+ "a": { "name": "cesium-man.glb", "url": "https://three.ws/avatars/cesium-man.glb", "sizeBytes": 438044 },
+ "b": { "name": "michelle.glb", "url": "https://three.ws/avatars/michelle.glb", "sizeBytes": 849756 },
+ "summary": { "changed": 111, "added": 75, "removed": 26, "modified": 1, "renamed": 1, "moved": 0 },
+ "totals": { "triangles": { "a": 4672, "b": 28106, "delta": 23434, "pct": 501.6 } },
+ "sections": { "skins": { "removed": [{ "name": "Armature", "severity": "breaking", "detail": "19 joints gone" }] } },
+ "highlights": [{ "severity": "breaking", "text": "Skeleton \"Armature\" was removed. The model is no longer rigged." }],
+ "ts": "2026-08-28T00:00:00.000Z"
+}
+```
+
+`POST` the same two fields as JSON when the URLs are long. Add `format=markdown` for a pull-request-ready report, or `format=text` for the terminal rendering:
+
+```bash
+curl "https://three.ws/api/3d/diff?a=$BASE&b=$HEAD&format=markdown" >> "$GITHUB_STEP_SUMMARY"
+```
+
+Both models are fetched through the SSRF-hardened, size-capped fetcher: public `http(s)` only, private address ranges refused, 32 MiB per side. Errors are specific and never a 500: a bad URL is a `400` naming which side failed, an oversize model is a `413`, an upstream that would not serve the bytes is a `502` with a retry hint, and bytes that are not a glTF are a `400 invalid_model`.
+
+---
+
+## The CLI
+
+```bash
+npx @three-ws/glb-diff before.glb after.glb
+```
+
+Either side may be a file path or an `http(s)` URL, so comparing a local build against the copy already live on your CDN is one command. Exit codes are the contract a pipeline depends on:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The diff ran and stayed below `--fail-on` |
+| `1` | The diff ran and the severity reached `--fail-on` |
+| `2` | The tool could not run: bad arguments, unreadable input, unparseable model |
+
+A tool that returns `1` for both "your model regressed" and "I could not open the file" is useless in a pipeline, which is why `2` exists.
+
+```bash
+# Fail the build if the optimization pass broke the rig.
+npx @three-ws/glb-diff src/avatar.glb dist/avatar.glb --fail-on breaking
+```
+
+---
+
+## The MCP tool
+
+`diff_models` is available on the three.ws MCP server, so an agent that just optimized, rigged, restyled, or re-exported a model can ask whether the result is still safe to ship before it publishes anything.
+
+```jsonc
+{
+ "name": "diff_models",
+ "arguments": {
+ "before": "https://cdn.example.com/avatar.glb",
+ "after": "https://cdn.example.com/avatar.optimized.glb"
+ }
+}
+```
+
+The tool returns the rendered text report as content and the full change set as `structuredContent`, so the agent can branch on `severity` without parsing prose. See [MCP integration](#sec-293) for connecting the server.
+
+---
+
+## The library
+
+The engine is published as [`@three-ws/glb-diff`](https://www.npmjs.com/package/@three-ws/glb-diff). This page, the CLI, the API, and the MCP tool all run that one package, so a verdict in CI can never disagree with what the page shows.
+
+```js
+import { readFile } from 'node:fs/promises';
+import { diffModels, formatText, atLeast } from '@three-ws/glb-diff';
+
+const changes = await diffModels(await readFile('a.glb'), await readFile('b.glb'), {
+ nameA: 'a.glb',
+ nameB: 'b.glb',
+});
+
+console.log(formatText(changes, { color: false }));
+if (atLeast(changes.severity, 'major')) process.exit(1);
+```
+
+`describeModel()` and `diffDescriptions()` are exported separately. A **description** is a small JSON summary of a model with no geometry buffers in it, which is how you keep a per-release baseline in CI without storing every historical `.glb`:
+
+```js
+import { describeModel, diffDescriptions } from '@three-ws/glb-diff';
+
+// In the release job:
+await writeFile('v4.description.json', JSON.stringify(await describeModel(await readFile('avatar.glb'))));
+
+// In the next release job, with v4's .glb long since pruned:
+const changes = diffDescriptions(
+ JSON.parse(await readFile('v4.description.json', 'utf8')),
+ await describeModel(await readFile('avatar.glb')),
+);
+```
+
+The full package reference, including the change-set shape and every export, is in the [package README](https://www.npmjs.com/package/@three-ws/glb-diff).
+
+---
+
+## Determinism
+
+The same two files always produce the same change set, byte for byte, on any machine, in any of the four surfaces above. That is what makes the output worth committing, posting on a pull request, and diffing against yesterday's.
+
+---
+
+<a id="sec-302"></a>
> **Source:** `docs/money-feed.md` · [↑ table of contents](#table-of-contents)
@@ -68142,7 +70695,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-403). This page is
+> whom, and is documented in [The social layer](#sec-421). This page is
> about value movement only. The two share a URL word ("feed") and nothing else.
---
@@ -68179,7 +70732,7 @@ fixed allow-list of types:
| `member-join` | A person signed in (throttled to once per user per 6h). |
| `agent-guard` | An autonomous buy was refused by a safety rule (`agentId`, `mint`, `reason`, `label`). |
| `war-result` | A Coin Wars battle ended (`winner`, `reason`, the two sides, `matchKey`, `network`). |
-| `agora-registered`, `agora-task-posted`, `agora-hired`, `agora-task-claimed`, `agora-task-completed`, `agora-earned`, `agora-vouched`, `agora-flagged` | [Agora](#sec-075) on-chain economy lifecycle events. |
+| `agora-registered`, `agora-task-posted`, `agora-hired`, `agora-task-claimed`, `agora-task-completed`, `agora-earned`, `agora-vouched`, `agora-flagged` | [Agora](#sec-077) on-chain economy lifecycle events. |
| `agora-arena-entered`, `agora-arena-won`, `agora-arena-lost` | Competitive Agora tasks: one racer takes the purse. |
| `agora-guild-joined`, `agora-guild-contributed` | Collaborative Agora tasks: the pool splits across contributors. |
@@ -68212,19 +70765,19 @@ Each row carries: `agent_id`, `user_id`, `event_type` (e.g. `spend`),
`reason`, `status`, an `idempotency_key`, an optional `capability_id`, and a
`meta` JSON blob. Spends pass through the
spend-cap and policy engine before they are recorded (see
-[Agent wallets](#sec-072)).
+[Agent wallets](#sec-074)).
## What flows in from where
| Producer | Ledger? | Ticker? | Domain record |
|---|---|---|---|
-| [Circulation engine](#sec-141) tips/payments/trades/buys | Yes | Trades/launches via pump feed | `circulation_actions` + domain table |
-| [Marketplace](#sec-277) skill/asset purchase | Yes | `payment` / `sale` | `skill_purchases` / `asset_purchases` |
-| [Coin launches](#sec-144) | Yes | `coin-buy` / `agent-deploy` | `pump_agent_mints` |
+| [Circulation engine](#sec-145) tips/payments/trades/buys | Yes | Trades/launches via pump feed | `circulation_actions` + domain table |
+| [Marketplace](#sec-286) skill/asset purchase | Yes | `payment` / `sale` | `skill_purchases` / `asset_purchases` |
+| [Coin launches](#sec-148) | 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` |
+| [Autonomous x402 loop](#sec-107) | Yes (`category: 'x402'`) | — | `x402_autonomous_log` |
| x402 service payments | Yes | `payment` | — |
-| [Agora](#sec-075) tasks | On settlement | `agora-*` | on-chain |
+| [Agora](#sec-077) tasks | On settlement | `agora-*` | on-chain |
## Reading the feed programmatically
@@ -68256,14 +70809,14 @@ The same bus powers surfaces that are not tickers at all:
## Related
-- [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 endpoints](#sec-559): the *other* direction: money paid **to** our endpoints (`x402_audit_log`), not agent spend.
+- [Circulation engine](#sec-145) — the largest producer of activity.
+- [Autonomous x402 loop](#sec-107) — treasury-paid intel purchases.
+- [Agent wallets](#sec-074) — how spends are gated before they're recorded.
+- [x402 endpoints](#sec-584): the *other* direction: money paid **to** our endpoints (`x402_audit_log`), not agent spend.
---
-<a id="sec-293"></a>
+<a id="sec-303"></a>
> **Source:** `docs/money-flow-map.md` · [↑ table of contents](#table-of-contents)
@@ -68502,14 +71055,14 @@ covering it there. Keep the ordering discipline in `classifyRole`: a rule goes
## Related
-- [Money Pulse](#sec-292): the event stream these edges are aggregated from.
-- [Circulation engine](#sec-141): what generates most of this
+- [Money Pulse](#sec-302): the event stream these edges are aggregated from.
+- [Circulation engine](#sec-145): what generates most of this
activity.
-- [Agent economy volume](#sec-052): the per-agent totals, ranked.
+- [Agent economy volume](#sec-053): the per-agent totals, ranked.
---
-<a id="sec-294"></a>
+<a id="sec-304"></a>
> **Source:** `docs/money-map.md` · [↑ table of contents](#table-of-contents)
@@ -68520,8 +71073,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-559) (the paid endpoint catalog),
-[Financial controls](#sec-222) (how settlements are recorded),
+Companion docs: [x402 endpoints](#sec-584) (the paid endpoint catalog),
+[Financial controls](#sec-229) (how settlements are recorded),
[Solana signers runbook](../api/_lib/solana-signers.js) (the
signer/funder wallets and how to fund them).
@@ -68561,7 +71114,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-183) subsystem doc.
+[economy master](#sec-189) subsystem doc.
| Wallet | Role |
| ------ | ---- |
@@ -68621,7 +71174,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-559).
+ [x402 endpoints](#sec-584).
- **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,
@@ -68641,9 +71194,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-509).
+ ([api/marketplace/](../api/marketplace)); see [marketplace skills](#sec-529).
- **Labor market** — bounty/escrow jobs with worker + author-royalty settlement; see
- [labor market](#sec-263).
+ [labor market](#sec-275).
- **Other** — vanity bounties, forge REST ([api/x402/forge.js](../api/x402/forge.js)),
subscriptions, credit deposits.
@@ -68653,7 +71206,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-183) via the `treasury-topup` cron (every 30 min,
+[economy master](#sec-189) 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
@@ -68689,22 +71242,22 @@ 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-222) for the full register.
+[financial-controls.md](#sec-229) for the full register.
## Related
-- [Financial controls & audit register](#sec-222) — every ledger's integrity, reconciliation, retention, monitoring, and the ranked gap list.
-- [x402 endpoints](#sec-559) — the paid endpoint catalog and price overrides.
-- [x402 ring economy](#sec-560) — the internal recirculation loop.
-- [Pump platform fee](#sec-352) — the pump trade fee detail.
-- [Coin-launch wallets](#sec-511) — launch-time wallet flow.
+- [Financial controls & audit register](#sec-229) — every ledger's integrity, reconciliation, retention, monitoring, and the ranked gap list.
+- [x402 endpoints](#sec-584) — the paid endpoint catalog and price overrides.
+- [x402 ring economy](#sec-586) — the internal recirculation loop.
+- [Pump platform fee](#sec-365) — the pump trade fee detail.
+- [Coin-launch wallets](#sec-531) — 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.
+- [Agent wallet custody](#sec-074) — how custodial keys are held.
- [Solana signers runbook](../api/_lib/solana-signers.js) — signer/funder wallets + funding.
---
-<a id="sec-295"></a>
+<a id="sec-305"></a>
> **Source:** `docs/monitor.md` · [↑ table of contents](#table-of-contents)
@@ -68830,7 +71383,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-293): the topology behind the totals, who
+- [Money Flow Map](#sec-303): 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
@@ -68838,7 +71391,7 @@ board a lie.
---
-<a id="sec-296"></a>
+<a id="sec-306"></a>
> **Source:** `docs/motion-swap.md` · [↑ table of contents](#table-of-contents)
@@ -68930,11 +71483,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-114)
+- [docs/animations.md](#sec-095) · [docs/avatar-reconstruction.md](#sec-116)
---
-<a id="sec-297"></a>
+<a id="sec-307"></a>
> **Source:** `docs/multi-agent.md` · [↑ table of contents](#table-of-contents)
@@ -69277,7 +71830,7 @@ To extend this into a full turn-based scene, add a `brain` attribute to Mira wit
---
-<a id="sec-298"></a>
+<a id="sec-308"></a>
> **Source:** `docs/native-launchpad.md` · [↑ table of contents](#table-of-contents)
@@ -69287,7 +71840,7 @@ three.ws has always been able to launch a coin for an agent. Until now, every on
This document covers the second lane: **the native launchpad**, a coin launch that runs on a bonding curve three.ws configures and owns. Same launch button, same 3D agent identity attached to the coin, different economics underneath.
-Related surfaces: [the pump.fun lane](#sec-096) (`/api/pump/*`), [agent wallets](#sec-072) (custody), and [the launch page](https://three.ws/launch).
+Related surfaces: [the pump.fun lane](#sec-098) (`/api/pump/*`), [agent wallets](#sec-074) (custody), and [the launch page](https://three.ws/launch).
---
@@ -69472,7 +72025,124 @@ Stated plainly, because a half-built feature that claims to be finished is worse
---
-<a id="sec-299"></a>
+<a id="sec-309"></a>
+
+> **Source:** `docs/native-widgets.md` · [↑ table of contents](#table-of-contents)
+
+# Native widgets: your agent on the home screen
+
+A three.ws agent earns a slot on your phone's home screen. The widget shows the agent's
+avatar, its name, and one live number (how many moves it made today), and a tap opens the app
+on that agent. The system refreshes it in the background about every 30 minutes; you never
+have to open the app to see the number move.
+
+This page covers the native, operating-system widgets. The embeddable web widgets that put a
+live 3D agent inside a web page are a different product: see [widgets.md](#sec-546).
+
+## What the widget shows
+
+Every platform renders the same card, the [Glance card](#sec-244):
+
+- the agent's avatar thumbnail (or a generated monogram when the avatar is private),
+- the agent's name and description,
+- **Moves today**: the number of real actions the agent logged in the last 24 hours,
+- this week's and all-time totals, and the agent's skill count,
+- when it last acted, and a status dot (green: active today, amber: idle, grey: never acted).
+
+No widget host on any platform can run WebGL, so the card is a bitmap the server renders
+(`GET /api/glance/mine?format=png`) and the 3D avatar stays one tap away on the agent page.
+
+## Android
+
+Requires the three.ws Android app, version 1.1 or later ([seeker-app.md](#sec-403)).
+
+1. Open [three.ws/glance](https://three.ws/glance) on the phone, signed in, and tap
+ **Link this phone**. The page mints a widget token and hands it to the app; Android asks
+ whether to add the widget to the home screen right away.
+2. If you skipped that prompt: long-press the home screen, choose **Widgets**, find
+ **three.ws**, and drag **Agent glance** out. It comes in 2x2 (the square card), 4x2 (the
+ wide card), and 4x3 (the wide card with **Create** and **My agents** buttons). Resize it
+ and it re-fetches the matching size.
+3. The widget refreshes itself through WorkManager, on the battery-aware schedule Android
+ grants background apps (about every 30 minutes, only with a network connection). Tapping
+ the "Updated …" line refreshes on demand.
+
+What happens when things go wrong is designed, not accidental:
+
+| Situation | What the widget shows |
+| --- | --- |
+| Not linked yet | "Add your agent. Tap to link this widget to your three.ws account." The tap opens the link flow in the app. |
+| Linked, first download pending | "Fetching your agent." It is replaced by the card as soon as the download lands. |
+| Phone offline, or the server unreachable | The last card it downloaded, with "From 14:02 (offline). Tap to retry." It never shows a spinner or a broken image. |
+| Account has no agent | A card that says so, and a tap that opens `/create`. |
+| Token revoked from /glance | A "Widget unlinked" card whose tap re-opens the link flow. The app drops the dead token. |
+| App force-stopped, or phone rebooted | The widget survives both: the bitmap is on disk, the schedule is WorkManager's, and both come back with the launcher. |
+
+### Which agent it shows
+
+Your first agent, unless the widget was linked while a different one of yours was selected on
+`/glance`; that agent is then pinned to the token. Repoint a widget with
+`PATCH /api/glance/token` (`{ "id": "<token id>", "agent": "<agent id>" }`) or relink it.
+
+### Revoking a widget
+
+Open [three.ws/glance](https://three.ws/glance) signed in and scroll to **Linked widgets**.
+Every phone widget is listed by the label it was linked with, its token prefix, and when it
+was last seen. **Revoke** invalidates that token; on its next refresh the widget shows the
+"Widget unlinked" card. Nothing else about your account changes: the token could only ever
+read your glance card.
+
+### How the widget authenticates
+
+A home screen widget outlives every browser session, and Android fetches it from an OS process
+with no cookie jar, so it cannot use the session. Instead `/glance` mints a **widget token**
+(`POST /api/glance/token`), a random 32-character credential prefixed `glw_`. The server stores
+only its SHA-256; the plaintext travels once, inside a `threews://glance/link?token=…` deep
+link that only the `ws.three.app` package can claim, and then lives in the app's private
+storage. The token is accepted by exactly one endpoint, `GET /api/glance/mine`, and reads
+exactly one thing: the owner's card.
+
+### For developers
+
+The native sources live in [solana-mobile/android-overlay/](../solana-mobile/android-overlay/README.md)
+and are laid over the Bubblewrap-generated project by `solana-mobile/scripts/apply-overlay.mjs`
+during `build-apk.sh`. The emulator recipe for the five checks (add from the picker, refresh
+without opening the app, survive force-stop, survive reboot, hold the cached card in airplane
+mode) is in [solana-mobile/README.md](../solana-mobile/README.md#emulator-qa).
+
+## Windows 11
+
+Installs with the PWA, no store submission: open three.ws in Edge, install it, open the widgets
+board (`Win + W`), **Add widgets**, pick **Agent glance**. It authenticates with your session and
+refreshes every 15 minutes. Details in [glance.md](glance.md#on-the-windows-11-widgets-board).
+
+## macOS and iOS
+
+Planned: a shared WidgetKit extension (a `TimelineProvider` that fetches
+`/api/glance/mine?format=png` with a widget token stored in the keychain) and a small SwiftUI
+host app that signs in and mints the token. macOS ships first because it can be distributed
+outside the App Store; the iOS build is the same extension target and waits on an Apple
+Developer account. The card, the token, and the endpoint are the ones above; nothing on the
+server changes for either.
+
+## The endpoints
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /api/glance/mine?format=png&size=small\|medium\|large&theme=dark\|light&scale=1\|2\|3` | The card bitmap for the caller (widget token as `Authorization: Bearer`, or the session cookie). Always `200`; the state is in `x-glance-state` and the tap target in `x-glance-url`. |
+| `GET /api/glance/mine` | The same as JSON: `{ signedIn, state, card, notice, agents, … }`. |
+| `POST /api/glance/token` | Mint a widget token (session, same-site). Returns the plaintext once plus `links.android`. |
+| `GET /api/glance/token` | List the caller's live tokens. |
+| `PATCH /api/glance/token` | Repoint a token at another owned agent. |
+| `DELETE /api/glance/token?id=…` | Revoke a token. |
+| `GET /api/glance/card?agent=…&format=png` | Any public agent's card as a bitmap, no auth. |
+
+The wire format is pinned in [specs/GLANCE_CARD.md](../specs/GLANCE_CARD.md); the full endpoint
+reference is in [api-reference.md](api-reference.md#glance-api).
+
+---
+
+<a id="sec-310"></a>
> **Source:** `docs/news-rights.md` · [↑ table of contents](#table-of-contents)
@@ -69539,7 +72209,7 @@ Every registry feed is ingested. Some are crypto-native: every article is on top
So the human-facing feeds apply a display gate with two conditions:
-1. **Relevance** — a crypto-native source always shows. A broad source's article shows only if the article itself is about crypto (a detected ticker, or a term from the crypto lexicon). This is what keeps "Ryanair broken window" and "3M stock jumps" out while letting the same source's Bitcoin coverage through.
+1. **Relevance**: a crypto-native source always shows. A broad source's article shows only if the article itself is about crypto (a detected ticker, or a term from the crypto lexicon). Both are matched as whole words: the lexicon test is a `\b`-anchored regex (`CRYPTO_TERM_RE`), so "defied" no longer fires on `defi` and "tether" is in the list explicitly instead of matching through `ether`, and coins whose bare name is an ordinary word (NEAR, OP, MKR) are tagged only from a qualifying phrase ("NEAR Protocol", "Optimism mainnet", "MakerDAO") or a cashtag. This is what keeps "Ryanair broken window", "3M stock jumps", and "8 defied the selloff" out while letting the same source's Bitcoin coverage through.
2. **Quality** — a credibility floor (default 0.6, override with `NEWS_MIN_CREDIBILITY`). Scored sources must clear it; unscored registry sources are presumed acceptable; legacy archive rows with no registry entry are never dropped on quality grounds.
The gate is **display-only**. It runs on `/api/news/feed`, the RSS mirror, the daily digest, and related coverage — never on ingestion. The archive cron and the agent-signal callers still receive the full firehose. `GET /api/news/feed?raw=1` bypasses the gate for debugging or parity checks. An explicit single-source request (`?source=`) is also exempt: you asked for that outlet by name.
@@ -69566,11 +72236,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-273) — the paid market endpoints, including archive search
+- [Market Data API](#sec-285) — the paid market endpoints, including archive search
---
-<a id="sec-300"></a>
+<a id="sec-311"></a>
> **Source:** `docs/notifications.md` · [↑ table of contents](#table-of-contents)
@@ -69591,6 +72261,7 @@ this page picks up where that one leaves off.
| Bell dropdown | The bell button in the header, on every page | [src/notifications.js](../src/notifications.js) |
| Notification center | [/notifications](https://three.ws/notifications) | [pages/notifications.html](../pages/notifications.html), [src/notifications-page.js](../src/notifications-page.js) |
| Preference editor | `/dashboard/settings` | [src/dashboard-next/pages/settings.js](../src/dashboard-next/pages/settings.js) |
+| Avatar announcements | The corner companion, on any page | [src/notification-herald.js](../src/notification-herald.js) |
| Inbox API | `GET/POST/DELETE /api/notifications/*` | [api/notifications/](../api/notifications/README.md) |
One inbox, two views. The dropdown holds the latest page for a quick glance;
@@ -69656,6 +72327,64 @@ Two details worth knowing:
own `?type=` parameter filters server-side by a single exact type (e.g.
`?type=pump_alert`), not by category.
+## The avatar channel: delivered in person
+
+A badge waits to be noticed. Some notifications should not have to. When one
+of those lands while you are on the site, the corner companion (the avatar
+that already walks your pages) turns to you, plays a gesture, and says it out
+loud, with a link straight to the thing that happened.
+
+`avatar` is a real delivery channel next to `in_app`, `push`, `email`, and
+`telegram`. It is gated by the same per-category matrix, edited in the same
+place (`/dashboard/settings`), and measured in the same funnel.
+
+**What gets announced.** By default: **Sales & earnings**, **Creations**, and
+**Account**. Money landing, a generation finishing while you waited, and
+anything touching your account are worth an interruption. Purchases, social,
+in person, and market alerts are off by default because they are frequent.
+Every one of them is a toggle, so an inbox that should speak up more (or not
+at all) is two clicks away.
+
+**When it stays quiet.** The rules live in
+[src/notification-herald.js](../src/notification-herald.js):
+
+- Only **unread** notifications **under 15 minutes old**. Older rows are
+ history, and history belongs in the bell.
+- **Each notification exactly once per browser.** Delivered ids are remembered
+ in `localStorage`, so navigating, re-polling, or opening a second tab never
+ replays a line.
+- **Two lines per batch**, maximum. Anything past that becomes a single
+ "N more waiting" line pointing at `/notifications`, so a backlog never turns
+ into a monologue.
+- **Never into a background tab.** The point is telling someone who is here.
+- **Nothing is spoken aloud unless you asked for audio.** Announcements use
+ the companion's own narration setting (`walk:companion:narrate`, the toggle
+ on the companion itself). On the default caption-only setting the message is
+ text in the bubble, which is also an `aria-live` region, so screen readers
+ get it either way.
+
+**Controls.** The bubble carries "Turn off", which silences announcements in
+that browser instantly without touching the account-wide setting. Per-category
+control lives in the Notifications panel of `/dashboard/settings`.
+
+**No companion running?** It is summoned for that one message and walks off
+again afterwards, without turning itself on permanently. When an avatar cannot
+be rendered at all (no WebGL, inside an iframe, or a route that already owns
+the corner, such as `/play` or `/avatar-studio`) the line degrades to a normal
+toast, so the notification is never lost to a missing GPU.
+
+The delivery itself is one call into the walk SDK, which any surface can
+reuse:
+
+```js
+// walk-sdk/src/companion.js: mounts if needed, gestures, speaks, retreats.
+await window.__walkCompanion.announce('Your agent made a sale', {
+ tone: 'alert',
+ emote: 'dance',
+ actions: [{ label: 'Open', href: '/dashboard' }],
+});
+```
+
## How the bell and unread state work
The bell ([src/notifications.js](../src/notifications.js)) is mounted by the
@@ -69794,12 +72523,13 @@ row is not the caller's. Removal is permanent.
```
POST /api/notifications/track
-{ "notification_id": "<uuid>", "channel": "push" | "in_app", "event": "opened" | "returned" }
+{ "notification_id": "<uuid>", "channel": "push" | "in_app" | "avatar", "event": "opened" | "returned" }
```
An idempotent analytics beacon closing the sent-to-opened-to-returned loop:
-the service worker fires `opened` on a push click, the app fires `returned`
-when it boots from a push-sourced open. Session-cookie auth only (no bearer),
+the service worker fires `opened` on a push click, the corner companion fires
+`opened` when you click through from a line it announced, and the app fires
+`returned` when it boots from a push-sourced open. Session-cookie auth only (no bearer),
CSRF-exempt, deduplicated server-side.
> Source: [api/notifications/track.js](../api/notifications/track.js).
@@ -69818,9 +72548,12 @@ curl -s -X PUT 'https://three.ws/api/notifications/preferences' \
-d '{ "categories": { "social": { "push": false } } }'
```
-GET returns `{ categories, channels, prefs, push: { subscribed_devices } }`:
-the seven categories from the table above, the four channels (`in_app`,
-`push`, `email`, `telegram`), and the caller's resolved matrix. PUT stores a
+GET returns
+`{ categories, channels, type_categories, prefs, push: { subscribed_devices } }`:
+the categories from the table above, the channels (`in_app`, `push`, `email`,
+`telegram`, `avatar`), the type-to-category map (so a browser client can
+resolve a category without a round trip per notification), and the caller's
+resolved matrix. PUT stores a
sparse override; unknown categories, channels, and keys are dropped, and the
response echoes the re-resolved matrix. The body also accepts
`telegram_chat_id` (digits, settable and clearable) for the Telegram channel.
@@ -69834,7 +72567,7 @@ Delivery gating notes, all enforced in
push left on still delivers the OS notification.
- The `account` category's `in_app` channel is locked on. It is the durable
record of withdrawals and security events, and the fallback bucket for
- unmapped types; the other three channels stay fully mutable.
+ unmapped types; every other channel stays fully mutable.
- A user who never saved gets the defaults, and new categories light up
automatically without a backfill.
@@ -69851,7 +72584,7 @@ one click from the gear icon in both notification surfaces.
## Related pages
-- [The social layer](#sec-403): where notification events come from
+- [The social layer](#sec-421): 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.
@@ -69860,7 +72593,7 @@ one click from the gear icon in both notification surfaces.
---
-<a id="sec-301"></a>
+<a id="sec-312"></a>
> **Source:** `docs/nvidia-apps-catalog-listing.md` · [↑ table of contents](#table-of-contents)
@@ -69868,7 +72601,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-303) (membership overview), [nvidia-models.md](#sec-304) (full model map, the source of truth for every NVIDIA claim below), [nvidia-visibility-map.md](#sec-307) (every other NVIDIA surface, and the asks to batch into the request email below).
+Related docs: [nvidia-inception.md](#sec-314) (membership overview), [nvidia-models.md](#sec-315) (full model map, the source of truth for every NVIDIA claim below), [nvidia-visibility-map.md](#sec-318) (every other NVIDIA surface, and the asks to batch into the request email below).
---
@@ -69901,7 +72634,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-302) 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-313) to `[email protected]` after the record corrections above are saved, and note the send date there.
---
@@ -70023,24 +72756,24 @@ 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-302) to [email protected] and record the send date there.
+9. Send the inclusion-request email in [nvidia-apps-catalog-request.md](#sec-313) to [email protected] and record the send date there.
---
-<a id="sec-302"></a>
+<a id="sec-313"></a>
> **Source:** `docs/nvidia-apps-catalog-request.md` · [↑ table of contents](#table-of-contents)
# 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-301).
+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-312).
-It also carries four other asks that have never been made. Per [nvidia-visibility-map.md](#sec-307), 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.
+It also carries four other asks that have never been made. Per [nvidia-visibility-map.md](#sec-318), 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): 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-301) 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.
+- **Blocked on:** the portal record correction, [nvidia-apps-catalog-listing.md](#sec-312) 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
@@ -70119,7 +72852,7 @@ https://three.ws
---
-<a id="sec-303"></a>
+<a id="sec-314"></a>
> **Source:** `docs/nvidia-inception.md` · [↑ table of contents](#table-of-contents)
@@ -70157,7 +72890,7 @@ Membership is a startup program, not a partnership or an investment: NVIDIA revi
## Related
-- [NVIDIA visibility map](#sec-307): every NVIDIA surface where three.ws can earn recognition, what each one requires, and which membership benefits are still unclaimed
+- [NVIDIA visibility map](#sec-318): 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
@@ -70165,7 +72898,7 @@ Membership is a startup program, not a partnership or an investment: NVIDIA revi
---
-<a id="sec-304"></a>
+<a id="sec-315"></a>
> **Source:** `docs/nvidia-models.md` · [↑ table of contents](#table-of-contents)
@@ -70202,8 +72935,8 @@ Because it is one key for everything, a deployment either has the whole NVIDIA l
| Capability | NVIDIA model(s) | Wired in | Free? |
| --- | --- | --- | --- |
| **Text → 3D** | `microsoft/trellis` | `api/_providers/nvidia.js`, `api/_lib/forge-tiers.js` | ✅ |
-| **Text → image** | `black-forest-labs/flux.1-schnell` | `api/_mcp3d/text-to-image.js` | ✅ |
-| **LLM (default lane)** | `meta/llama-3.3-70b-instruct` | `api/_lib/llm.js`, `api/_lib/chat-models.js` | ✅ |
+| **Text → image** | `black-forest-labs/flux.1-dev` | `api/_mcp3d/text-to-image.js` | ✅ |
+| **LLM (default lane)** | `nvidia/nemotron-3-super-120b-a12b` (compact rung: `nvidia/nemotron-3-nano-30b-a3b`) | `api/_lib/llm.js`, `api/_lib/chat-models.js` | ✅ |
| **LLM (model garden)** | Nemotron 120B / 49B / Nano 9B, Llama 4 Maverick, DeepSeek V4 Pro, Kimi K2.6, MiniMax M2.7 | `api/brain/chat.js` | ✅ |
| **Vision / VLM** | `nvidia/nemotron-nano-12b-v2-vl`, `meta/llama-3.2-11b-vision-instruct` | `api/_lib/vision.js` | ✅ |
| **Embeddings** | `nvidia/nv-embedqa-e5-v5` | `api/_lib/embeddings.js` (and `api/agents/_id/embed.js`, which delegates to it) | ✅ |
@@ -70236,18 +72969,18 @@ This is the headline free model. **Microsoft TRELLIS hosted on NVIDIA NVCF gives
---
-## 2. Text → image — FLUX.1-schnell
+## 2. Text → image: FLUX.1-dev
-**Model:** `black-forest-labs/flux.1-schnell` · **Endpoint:** `ai.api.nvidia.com/v1/genai/black-forest-labs/flux.1-schnell`
+**Model:** `black-forest-labs/flux.1-dev` · **Endpoint:** `ai.api.nvidia.com/v1/genai/black-forest-labs/flux.1-dev`
**Source:** [api/_mcp3d/text-to-image.js](../api/_mcp3d/text-to-image.js).
-FLUX.1-schnell is the **free, first-choice text-to-image lane**. It's a synchronous invoke — the image returns inline as base64 (no poll) in ~1–2 s — and it's Apache-2.0, commercial-OK.
+FLUX.1-dev is the **free NVIDIA text-to-image lane** (the hosted FLUX.1-schnell preview was retired, so the lane moved to the dev checkpoint at 20 steps, CFG 3.5). It is a synchronous invoke: the image returns inline as base64, no poll.
**Where it's used:**
- **The reference-image step of the image-intermediate 3D path.** When a prompt is reconstructed to a mesh, FLUX paints the reference view first, which the free reconstruction lanes (TRELLIS / Hunyuan3D) then turn into geometry. A photo-quality reference reconstructs into a far better mesh than a busy scene, so the lane steers FLUX toward a clean, centered subject.
- General text→image wherever the platform needs a synthesized image.
-**Fallback order:** NVIDIA FLUX (free) → Vertex Imagen (`GOOGLE_CLOUD_PROJECT`) → Replicate `flux-schnell` ($0.003/image). The free NVIDIA lane always leads.
+**Ladder order.** When `GOOGLE_CLOUD_PROJECT` is set, Vertex Imagen leads by default because it outdraws distilled FLUX for photoreal reference images and spends the GCP credit pool the platform is funded to burn (`VERTEX_IMAGEN_FIRST=0` restores the NIM-first order). After that: NVIDIA FLUX.1-dev (free) → the Hugging Face router (`HF_TOKEN`; fal-ai, then nscale, both serving FLUX.1-schnell in 2-5 s) → the Livepeer federation lane (behind `LIVEPEER_FEDERATION_ENABLED`) → Pollinations (keyless, so a fallback always exists past every keyed rung) → Replicate `flux-schnell` ($0.003/image, the paid backstop). The whole ladder shares one budget, `TEXT_TO_IMAGE_BUDGET_MS` (default 60 s): each lane gets a bounded slice of what remains so a stalled provider cannot hold a Forge submit for minutes, and exhausting the budget returns a retryable `rate_limited` error (`retryAfter: 15`) rather than a hung request.
---
@@ -70257,10 +72990,10 @@ NVIDIA NIM hosts 100+ open-weight chat models behind the one key, all OpenAI-com
### 3a. The default production lane
-**Model:** `meta/llama-3.3-70b-instruct`
+**Model:** `nvidia/nemotron-3-super-120b-a12b` (with `nvidia/nemotron-3-nano-30b-a3b` as the compact Nemotron rung)
**Source:** [api/_lib/llm.js](../api/_lib/llm.js), [api/_lib/chat-models.js](../api/_lib/chat-models.js).
-The platform's general LLM helper runs a **free-first ladder: Groq → Cerebras → OpenRouter → NVIDIA NIM**, followed by further keyless free rungs (OVH, Gemini, Pollinations) and only at the very end a paid backstop (Anthropic/OpenAI). NVIDIA serves the **same Llama 3.3 70B family** as the Groq/Cerebras/OpenRouter rungs but on an independent provider, so an outage on the other free lanes still answers here. It's tool/function-calling capable, so it's eligible for tool-required requests.
+The platform's general LLM helper runs a **free-first ladder: Groq → Cerebras → OpenRouter → NVIDIA NIM**, followed by further keyless free rungs (OVH, Gemini, Pollinations) and only at the very end a paid backstop (Anthropic/OpenAI). Every free rung was re-pointed on 2026-08-27 to models the providers still serve: Groq now runs `qwen/qwen3.8-27b` (instant tier `openai/gpt-oss-20b`), Cerebras keeps `llama-3.3-70b`, and the NVIDIA rung runs Nemotron 3 Super 120B, an NVIDIA MoE on an independent provider, so an outage on the other free lanes still answers here. Both NVIDIA rungs are called with thinking disabled (`chat_template_kwargs: { enable_thinking: false }`) so a chat turn answers instead of reasoning out loud. Both are tool/function-calling capable, so they are eligible for tool-required requests.
This lane powers the platform's built-in AI surfaces — chat, embedded site widgets, the tutor, the fact-checker, persona tools, agent-to-agent talk, the transaction explainer — all of which lead with the free providers and only fall through to a paid model if every free lane fails.
@@ -70278,7 +73011,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 `nvidia/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. The routing catalog in `chat-models.js` also lists `nvidia/nemotron-3-super-120b-a12b`, `nvidia/nemotron-3-nano-30b-a3b`, and `nvidia/llama-3.3-nemotron-super-49b-v1.5` as tool-capable NVIDIA models, and the Brain's own fallback chain still appends `meta/llama-3.3-70b-instruct` on NIM behind the OpenRouter rungs when a chosen route is dead.
> **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.
@@ -70298,6 +73031,8 @@ Two free NIM vision lanes on the OpenAI-compatible chat host. Nemotron Nano VL l
All three **fail safe**: if the vision lane is unavailable, the feature quietly switches off — it never blocks or breaks the primary flow.
+The chain is budgeted and remembers what hurt. Each attempt gets an even share of whatever remains on the caller's deadline (`laneAttemptTimeout`, never below 3.5 s), so the first rung cannot consume the budget of the rest, and the pre-chain inline image fetch is capped at a quarter of the deadline and 8 s. A lane that fails is cooled for 45 s through the shared provider-health ledger (`api/_lib/provider-health.js`) and moved behind the healthy rungs on the next call rather than re-picked; a `429` cools every sibling lane on that host and skips them for the rest of the call, and a `401`/`403`/`402` earns the longer auth cooldown. A success clears the lane's cooldown.
+
---
## 5. Embeddings — semantic retrieval
@@ -70305,7 +73040,7 @@ All three **fail safe**: if the vision lane is unavailable, the feature quietly
**Primary:** `nvidia/nv-embedqa-e5-v5` (1024-dim) · **Endpoint:** `integrate.api.nvidia.com/v1/embeddings`
**Source:** [api/_lib/embeddings.js](../api/_lib/embeddings.js) (tag `nvidia/nv-embedqa-e5-v5@1024`).
-The default embedder for new vectors — **free with the one key, 1024 dimensions, hard-capped at 512 input tokens** (longer inputs are rejected upstream, so callers chunk to fit). Vectors are tagged with `model@dimension` so a later model swap can't silently mix incompatible spaces. Powers **agent memory and knowledge-widget retrieval**; the paid embedding provider is demoted to backup behind it.
+The default embedder for new vectors: **free with the one key, 1024 dimensions, hard-capped at 512 input tokens** (longer inputs are rejected upstream, so callers chunk to fit). Vectors are tagged with `model@dimension` so a later model swap can't silently mix incompatible spaces. Powers **agent memory and knowledge-widget retrieval**; the paid embedding provider is demoted to backup behind it. At ingest, `embedPassagesAny()` walks every configured embedder in free-first order (NIM → Vertex → OpenAI, the caller's preferred tag first), cooling a lane that fails for 45 s (longer on an auth fault) so the next ingest starts on a healthy rung, and returns the tag it actually used so the document set is stamped with the space its vectors live in. Search-side, the Agent Galaxy falls back to lexical ranking when the embedder cannot answer, because a query vector from another model cannot be compared against vectors stored in a different space.
**Also:** the agent-embed endpoint [api/agents/_id/embed.js](../api/agents/_id/embed.js) does not carry a provider list of its own. It delegates to the registry above, so `POST /api/agents/:id/embed` serves this same model and returns the tag alongside the vector. It previously called `baai/bge-m3` directly; NVIDIA stopped serving that model on the hosted endpoint (500 on every request), which is exactly the failure mode a single registry prevents.
@@ -70357,6 +73092,9 @@ The free NVIDIA TTS lane: **Magpie multilingual on Riva**, selected by an NVCF `
| `NVIDIA_API_KEY` | Every model on this page (`nvapi-…` from build.nvidia.com) |
| `KNOWLEDGE_RERANK_ENABLED=1` | Turns on the rerank stage (§6) |
| `FORGE_PREFER_FREE` | Free-first reconstruct ordering (default on) |
+| `TEXT_TO_IMAGE_BUDGET_MS` | Shared deadline for the whole text-to-image ladder (§2), default 60000 |
+| `VERTEX_IMAGEN_FIRST=0` | Puts the free NIM FLUX lane ahead of Vertex Imagen again (§2) |
+| `HF_TOKEN` | Unlocks the Hugging Face router rungs (fal-ai, nscale) in the text-to-image ladder (§2) |
---
@@ -70372,7 +73110,7 @@ The free NVIDIA TTS lane: **Magpie multilingual on Riva**, selected by an NVCF `
---
-<a id="sec-305"></a>
+<a id="sec-316"></a>
> **Source:** `docs/nvidia-nemotron-ask-the-experts-questions.md` · [↑ table of contents](#table-of-contents)
@@ -70476,11 +73214,11 @@ Every claim in the two posts is sourced, so a follow-up question cannot catch us
| Claim | Source |
|---|---|
-| NVIDIA Inception member, accepted July 2026 | [nvidia-inception.md](#sec-303) |
-| `nvidia/nemotron-nano-12b-v2-vl` gates every photo-to-3D generation, 1-2s | [nvidia-nemotron-spotlight.md](#sec-306), `api/_lib/forge-image-validate.js` |
-| ~281 image prompt tokens vs ~1,600 for a 90B-class VLM | [nvidia-nemotron-spotlight.md](#sec-306) |
+| NVIDIA Inception member, accepted July 2026 | [nvidia-inception.md](#sec-314) |
+| `nvidia/nemotron-nano-12b-v2-vl` gates every photo-to-3D generation, 1-2s | [nvidia-nemotron-spotlight.md](#sec-317), `api/_lib/forge-image-validate.js` |
+| ~281 image prompt tokens vs ~1,600 for a 90B-class VLM | [nvidia-nemotron-spotlight.md](#sec-317) |
| 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-306) |
+| `nvidia-nemotron-nano-9b-v2` used for reasoning turns, NemoGuard at ~340 ms median | [nvidia-nemotron-spotlight.md](#sec-317) |
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
@@ -70567,7 +73305,7 @@ plus a reported trillion-parameter Nemotron 4 in training.
---
-<a id="sec-306"></a>
+<a id="sec-317"></a>
> **Source:** `docs/nvidia-nemotron-spotlight.md` · [↑ table of contents](#table-of-contents)
@@ -70728,11 +73466,11 @@ 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-304), and the pipeline internals are in [`docs/3d-asset-pipeline.md`](#sec-002). three.ws joined the [NVIDIA Inception program](#sec-303) 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-315), and the pipeline internals are in [`docs/3d-asset-pipeline.md`](#sec-002). three.ws joined the [NVIDIA Inception program](#sec-314) 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-307"></a>
+<a id="sec-318"></a>
> **Source:** `docs/nvidia-visibility-map.md` · [↑ table of contents](#table-of-contents)
@@ -70743,8 +73481,8 @@ 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-301)
-for the listing kit and [nvidia-apps-catalog-request.md](#sec-302)
+not re-litigated here. See [nvidia-apps-catalog-listing.md](#sec-312)
+for the listing kit and [nvidia-apps-catalog-request.md](#sec-313)
for the inclusion email. This doc covers everything else and links to them where
they overlap.
@@ -70758,7 +73496,7 @@ or searched the same day; the ones that turned out to be dead are recorded in
Before any new outreach, two things about our existing position:
-**1. The Inception membership was never announced on X.** [announcement-coverage.md](#sec-095)
+**1. The Inception membership was never announced on X.** [announcement-coverage.md](#sec-097)
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
@@ -70790,7 +73528,7 @@ Everything here can be done today. Nothing waits on NVIDIA, a build, or a date.
|---|---|---|---|
| 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-301) step 1. Nothing else in this doc lands well while the record says "CUDA consumer". |
+| 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-312) 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). |
@@ -70806,7 +73544,7 @@ Real listings, real effort, honest gates. Do not pitch these before the code exi
| **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-301) already rules that Omniverse Kit stays under "Considering". Note the Omniverse Launcher was deprecated 2025-10-01, so old guides mislead. |
+| **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-312) 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
@@ -70961,11 +73699,11 @@ Recorded so the next person does not repeat the search.
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-302)
+**Done: the batched email is written.** [nvidia-apps-catalog-request.md](#sec-313)
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-301): as filed the
+[nvidia-apps-catalog-listing.md](#sec-312): 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.
@@ -70980,7 +73718,7 @@ record, save it, then send and stamp the date in the request doc.
| 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` |
+| `/nvidia` never announced on X | Read [announcement-coverage.md](#sec-097) 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 |
@@ -70994,17 +73732,17 @@ gcloud run services list --project aerial-vehicle-466722-p5 \
## 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-303): what membership is, and the rule that it is a program and not a partnership or an endorsement
-- [Apps Catalog listing kit](#sec-301) and [inclusion request](#sec-302): the one surface with its own dedicated docs
-- [NVIDIA models on three.ws](#sec-304): the source of truth for every NVIDIA technical claim made in any pitch
-- [Listings and distribution](#sec-269): the canonical program and directory inventory
-- [Announcement coverage](#sec-095): which surfaces have been announced and which have not
-- [Partners](#sec-329): the independence and no-endorsement language that must survive any rewrite
+- [Big-tech recognition dispatch board](#sec-127): 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-314): what membership is, and the rule that it is a program and not a partnership or an endorsement
+- [Apps Catalog listing kit](#sec-312) and [inclusion request](#sec-313): the one surface with its own dedicated docs
+- [NVIDIA models on three.ws](#sec-315): the source of truth for every NVIDIA technical claim made in any pitch
+- [Listings and distribution](#sec-281): the canonical program and directory inventory
+- [Announcement coverage](#sec-097): which surfaces have been announced and which have not
+- [Partners](#sec-341): the independence and no-endorsement language that must survive any rewrite
---
-<a id="sec-308"></a>
+<a id="sec-319"></a>
> **Source:** `docs/object-library.md` · [↑ table of contents](#table-of-contents)
@@ -71015,7 +73753,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-136). 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-139). For how AR placement works on phones and desktops, see [AR & WebXR](#sec-101).
---
@@ -71031,8 +73769,8 @@ 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-520) 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) |
+| **Preview** | `/app#model=<glb-url>&kind=object&title=<name>` | The full three.js [3D viewer](#sec-540) in object mode (no agent chat; Restyle, AR, and Download affordances instead) |
+| **AR** | `/ar/studio?src=<glb-url>&title=<name>` | [AR Studio](#sec-100): place the prop in your real space through the camera (see [AR & WebXR](#sec-101) for how the AR handoff works per device) |
| **Download** | The GLB URL directly | The raw GLB file, CC0, yours to use anywhere |
Gallery controls:
@@ -71045,7 +73783,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-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`.
+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-139), 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-139) exactly, with `objects` in place of `avatars`.
### Query parameters
@@ -71112,14 +73850,14 @@ The gallery and API are read-only consumers of a manifest built by a local pipel
## Related
-- [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-520): the `/app` engine the Preview button opens in object mode.
+- [Character Library](#sec-139): the rigged, animation-ready counterpart to this library.
+- [AR & WebXR](#sec-101): the device-by-device AR methods behind the AR button.
+- [AR Studio](#sec-100): the `/ar/studio` surface the AR button opens, including multi-object rooms.
+- [3D Viewer](#sec-540): the `/app` engine the Preview button opens in object mode.
---
-<a id="sec-309"></a>
+<a id="sec-320"></a>
> **Source:** `docs/okx-marketplace.md` · [↑ table of contents](#table-of-contents)
@@ -71130,10 +73868,11 @@ on-chain agent marketplace. Buyers are agents: they discover a service, receive
payment challenge, pay in stablecoins on X Layer (or USDC on our other x402 rails), and get
the artifact. Our marketplace entry is agent **#2632 "three.ws 3D Studio"**.
-> **Listing state.** The listing is not live yet. It was rejected in review on 2026-07-04
+> **Listing state.** Resubmitted for review on 2026-08-27 with the line-up below (on-chain
+> update tx `0xb4b2f51d…415ba`, X Layer). The earlier listing was rejected on 2026-07-04
> ("your A2MCP service has not been integrated with the OKX Agent Payments Protocol
-> standard") and a resubmission is pending. The services below are reachable directly at
-> the endpoints documented here in the meantime. Current state is tracked in
+> standard"); every row now answers that directly. Until approval lands, the services are
+> reachable at the endpoints documented here. Current state is tracked in
> [`prompts/okx-ai/PROGRESS.md`](../prompts/okx-ai/PROGRESS.md).
**What we list, as of 2026-08-22: three.ws Forge.** The listing was rebuilt around one
@@ -71146,8 +73885,8 @@ real room), over the marketplace's own payment rail. Everything else we built fo
the **back burner**: still deployed, still payable, deliberately off the listing. Those are
documented at the bottom of this page.
-> Related: [REST API Reference](#sec-096) · [MCP servers](#sec-284) ·
-> [x402 payments](#sec-563) · seller-side protocol spec:
+> Related: [REST API Reference](#sec-098) · [MCP servers](#sec-293) ·
+> [x402 payments](#sec-589) · 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,
@@ -71343,7 +74082,7 @@ three-pose full-body render set, and the rigged animation-ready GLB. Paid tool
this pipeline: [three.ws/agent-identities](https://three.ws/agent-identities).
**Single-capability REST endpoints.** Plain JSON `POST`, one price each, all backed by the
-same engines the [MCP 3D studio](#sec-284) runs. `GET` on any of them returns its free
+same engines the [MCP 3D studio](#sec-293) runs. `GET` on any of them returns its free
descriptor (price, description, input schema).
| Service | Price (USDT) | Endpoint | You send |
@@ -71377,7 +74116,7 @@ pinned down in [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md).
---
-<a id="sec-310"></a>
+<a id="sec-321"></a>
> **Source:** `docs/onboarding-tier.md` · [↑ table of contents](#table-of-contents)
@@ -71524,17 +74263,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-411) — the same journey, written for a human rather than a maintainer
+- [`docs/start-here.md`](#sec-429) — the same journey, written for a human rather than a maintainer
---
-<a id="sec-311"></a>
+<a id="sec-322"></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-406): 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-424): 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.
@@ -71547,7 +74286,8 @@ For every agent, one **Metaplex Core asset** that is:
- **minted into the three.ws Agents collection** — authority-managed, so three.ws can curate on-chain metadata on the owner's behalf;
- **owned by the agent** (its own custodial Solana wallet) or held in **authority custody** until claimed — see [Custody model](#custody-model);
- carrying an on-chain **Attributes plugin** (platform, links, `$THREE`, schema — real bytes in the asset account) and an enforced **5% Royalties plugin**;
-- pointing at a pinned **manifest** (Metaplex token-metadata + `agent-manifest/0.1`) on IPFS, so Phantom / Solscan / Magic Eden render it.
+- pointing at a pinned **manifest** (Metaplex token-metadata + `agent-manifest/0.1`) on IPFS, so Phantom / Solscan / Magic Eden render it;
+- **enrolled in the Metaplex Agent Registry** right after the mint: an Agent Identity PDA, authority-signed, whose URI points at the agent's live `/api/agents/:id/registration` document (see [What gets recorded](#what-gets-recorded)).
The live mainnet collection: [`56Gnsb7Jjg1N9c8V7EAnDC4HmQbQjsEueSUA3EK5272H`](https://solscan.io/account/56Gnsb7Jjg1N9c8V7EAnDC4HmQbQjsEueSUA3EK5272H).
@@ -71582,6 +74322,7 @@ Files:
|---|---|
| [api/_lib/onchain-deploy.js](../api/_lib/onchain-deploy.js) | Shared mint logic — collection resolution, manifest pin, Core mint, DB persist. |
| [scripts/deploy-agents-onchain.mjs](../scripts/deploy-agents-onchain.mjs) | CLI runner — dry-run preview, canary, full fleet. |
+| [scripts/register-agents-onchain.mjs](../scripts/register-agents-onchain.mjs) | CLI back-fill: enrols already-minted agents that have a Core asset but no Agent Identity PDA (same `--network` / `--limit` / `--dry-run` / `--confirm` flags). |
| [api/_lib/solana-collection.js](../api/_lib/solana-collection.js) | Collection authority + address helpers. |
| [api/_lib/three-brand.js](../api/_lib/three-brand.js) | Manifest + on-chain attributes builders. |
@@ -71597,7 +74338,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-406) 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-424) mints into the *same* collection.
---
@@ -71623,8 +74364,9 @@ One funded wallet does everything — it is the **collection authority**, the **
|---|---|
| Deploy the collection (once) | ~0.003 SOL |
| Mint one agent asset | ~0.004 SOL (rent + fee) |
+| Register its Agent Identity PDA | ~0.003 SOL (rent + fee) |
-So ~0.05 SOL canaries a handful; **~0.004 × N** covers a fleet of N (≈ 7.5 SOL for ~1,850 agents). The runner checks the balance before each mint and pauses cleanly if it runs low — top up and re-run.
+So ~0.05 SOL canaries a handful; **~0.007 × N** covers a fleet of N (≈ 13 SOL for ~1,850 agents). The runner checks the balance before each mint and pauses cleanly if it runs low: top up and re-run.
---
@@ -71652,7 +74394,9 @@ On a confirmed mint, `deployAgentOnce()` writes to `agent_identities.meta`:
"chain": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"family": "solana",
"cluster": "mainnet",
+ "onchain_id": "<asset pubkey>",
"sol_asset": "<asset pubkey>",
+ "contract_or_mint": "<asset pubkey>",
"metadata_uri": "https://ipfs.io/ipfs/<cid>",
"owner": "<owner pubkey>",
"custody": true,
@@ -71664,6 +74408,8 @@ On a confirmed mint, `deployAgentOnce()` writes to `agent_identities.meta`:
`sol_mint_address` is the canonical key every read path uses (explore, discover, profiles). It also makes re-runs **idempotent**: an agent that already has it is skipped. (Devnet runs are isolated under `meta.devnet` so they never block a real mainnet mint.) An `agent_actions` row (`type: solana.deploy`) is logged, and on mainnet a truthful `agent-onchain` feed event fires.
+Right after the mint, `registerAgentOnce()` enrols the asset in the Metaplex Agent Registry. The collection authority signs (the owner still never signs and needs no SOL), the Agent Identity PDA's URI is set to the agent's live `/api/agents/:id/registration` document rather than a pinned snapshot (the registry program has no instruction to change a URI later, so a mutable endpoint keeps `active`, services, and the model current), and an `agent_registry` block is merged into the same `meta` (`standard: metaplex-agent-registry`, `program`, `identity_pda`, `asset`, `collection`, `authority`, `registration_uri`, `network`, `tx_hash`, `registered_at`; under `meta.devnet` for devnet runs). A second `agent_actions` row (`type: solana.register`) is logged. A registry failure never undoes the mint: the asset and `sol_mint_address` are already persisted, the runner prints `registry skipped: <error> (back-fill later)`, and `scripts/register-agents-onchain.mjs` picks up every agent that has `sol_mint_address` but no `agent_registry.identity_pda`.
+
---
## Setup
@@ -71752,7 +74498,7 @@ before and after the removal are identical.
## Tutorial 3: The full fleet
-Once the canary checks out and the funder holds enough SOL (~0.004 × N):
+Once the canary checks out and the funder holds enough SOL (~0.007 × N):
```bash
# CLI, in batches:
@@ -71799,19 +74545,20 @@ A confirmed canary asset shows `inCollection=true`, `royalty=500bps`, `attrs=11`
| `solana rpc 429` / send timeouts | The public endpoint is rate-limited. Set `SOLANA_RPC_URL` to a Helius/Quicknode/Triton endpoint for the full run. |
| Manifest URI doesn't resolve | `PINATA_JWT` missing/invalid and no R2 configured. Set a valid `PINATA_JWT` (or `WEB3_STORAGE_TOKEN`, or the `S3_*` set). |
| An agent re-deploys unexpectedly | It shouldn't — `meta.sol_mint_address IS NULL` is the skip guard. If you intentionally re-mint, clear `sol_mint_address`/`onchain` from its `meta` first. |
+| `↳ registry skipped: …` under a ✓ mint | The Core asset minted and persisted, but the Agent Registry enrolment failed (usually the RPC). Re-run `node --env-file=.env scripts/register-agents-onchain.mjs --confirm`; it only targets agents with `sol_mint_address` and no `agent_registry.identity_pda`, and already-registered assets short-circuit without a transaction. |
---
## See also
-- [Solana agents](#sec-406) — the single-agent, user-signed registration flow.
-- [ERC-8004](#sec-189) — the EVM on-chain identity path.
-- [Agent manifest](#sec-055) — the metadata schema.
-- [Mint mark ("3ws")](#sec-289) — vanity marking for three.ws launches.
+- [Solana agents](#sec-424) — the single-agent, user-signed registration flow.
+- [ERC-8004](#sec-195) — the EVM on-chain identity path.
+- [Agent manifest](#sec-056) — the metadata schema.
+- [Mint mark ("3ws")](#sec-298) — vanity marking for three.ws launches.
---
-<a id="sec-312"></a>
+<a id="sec-323"></a>
> **Source:** `docs/open-source-ecosystem.md` · [↑ table of contents](#table-of-contents)
@@ -72058,7 +74805,7 @@ Thank you for the first hundred.
---
-<a id="sec-313"></a>
+<a id="sec-324"></a>
> **Source:** `docs/open-source-footprint.md` · [↑ table of contents](#table-of-contents)
@@ -72066,7 +74813,7 @@ Thank you for the first hundred.
Every place the three.ws codebase, its packages, its listings, or its community lives outside three.ws itself, with the link to cite and the number behind it. This is the canonical reference for announcements (the 100-star post, the X article, the weekly report): if two pieces of copy quote different numbers, this page wins. Every link below returned a live page on August 25, 2026; every count came from the registry's own API on the same day. Regenerate the milestone graphic that renders these numbers with `node scripts/render-github-stars-banner.mjs`.
-Related: [listings.md](#sec-269) (marketplace status and submission history), [x402-distribution.md](#sec-558) (every x402 crawler and directory, with mechanism), [community.md](#sec-151), [partners.md](#sec-329).
+Related: [listings.md](#sec-281) (marketplace status and submission history), [x402-distribution.md](#sec-583) (every x402 crawler and directory, with mechanism), [community.md](#sec-155), [partners.md](#sec-341).
## The repo
@@ -72104,7 +74851,7 @@ Not published anywhere yet (do not claim): PyPI, crates.io, Docker Hub, Smithery
| IBM watsonx / Granite | `@three-ws/ibm-watsonx-mcp`, `@three-ws/ibm-x402-mcp` on npm | IBM Business Partner |
| AWS Builder Center author profile | https://builder.aws.com/community/@threews | 3 published articles |
| AWS Builder Center articles | [metering through AWS Marketplace](https://builder.aws.com/content/3ESpll50BdSp9eiCEIxcfG9pGUN/how-we-metered-a-saas-product-through-aws-marketplace-with-the-aws-sdk-for-javascript-v3), [autonomous agents on AWS](https://builder.aws.com/content/3FMY7S5o4lwzb40gDsCJRCE20cX/build-autonomous-ai-agents-with-d-bodies-and-on-chain-payments-threews-on-aws), [the agentic economy](https://builder.aws.com/content/3FgvJFVKstRLVicHsldLM7ba4qB/the-agentic-economy-is-here-x-mcp-ai-agents-crypto-and-d-worlds-converging-aws-strategic-partnerships) | live |
-| AWS Marketplace | SaaS metering integration built ([aws-marketplace.md](#sec-123)) | listing not yet created |
+| AWS Marketplace | SaaS metering integration built ([aws-marketplace.md](#sec-125)) | listing not yet created |
| NVIDIA Inception | https://www.nvidia.com/en-gb/accelerated-applications/inception/ | member since July 2026 |
| NVIDIA Developer Forums | [Nemotron in the text-to-3D pipeline](https://forums.developer.nvidia.com/t/how-nemotron-made-three-ws-text-to-3d-pipeline-usable/376445), [NIM-powered i18n into 100 languages](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) | live |
| NVIDIA hardware | Cloud Run GPU fleet | NVIDIA L4 and RTX PRO 6000 Blackwell workers |
@@ -72132,7 +74879,7 @@ Not published anywhere yet (do not claim): PyPI, crates.io, Docker Hub, Smithery
|---|---|---|
| Solana attestations | SPL Memo envelope `threews.validation.v1`, see [specs/VALIDATORS.md](../specs/VALIDATORS.md) | 3,000 validator attestations |
| Custody attestations | `custody_attestation_*` | 126,522 proofs across 244 epochs |
-| ERC-8004 registries | Identity `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`, Reputation `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`, see [erc8004.md](#sec-189) | same address on every EVM chain |
+| ERC-8004 registries | Identity `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`, Reputation `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`, see [erc8004.md](#sec-195) | same address on every EVM chain |
| Solana programs | `contracts/agent-invocation`, `contracts/skill-license` | 2 programs, 4 Rust crates |
| Solidity | `contracts/src` | 7 contracts (payments, identity, reputation, validation, vault) |
| BNB Chain Dappbay | https://dappbay.bnbchain.org/detail/three | live |
@@ -72159,7 +74906,7 @@ Mint `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`. Venues: [pump.fun (verified
---
-<a id="sec-314"></a>
+<a id="sec-325"></a>
> **Source:** `docs/open-source-friday-plan.md` · [↑ table of contents](#table-of-contents)
@@ -72185,8 +74932,8 @@ Verified against `gh repo view nirholas/three.ws` and the working tree, not from
| License | **PASS** | Relicensed to Apache-2.0 on 2026-08-21. Verbatim [LICENSE](../LICENSE), a [NOTICE](../NOTICE) covering vendored and derived code, and all 102 first-party manifests set to `"license": "Apache-2.0"`. |
| 100+ stars, hosted on GitHub | **PASS** | 104 stargazers, 26 forks as of 2026-08-25 (98 on 2026-08-21; the relicense closed the gap without a campaign) |
| Open to outside contributions | PASS | 11 contributors, issue and PR templates, CODEOWNERS, and six curated open issues (see below) |
-| *Preferred:* community channel | **PASS** | Telegram community, X community, IBM Community group, GitHub Discussions (seeded 2026-08-25: [Welcome #122](https://github.com/nirholas/three.ws/discussions/122), [Show and tell #123](https://github.com/nirholas/three.ws/discussions/123), [Roadmap #124](https://github.com/nirholas/three.ws/discussions/124)), release channel. All five documented in [docs/community.md](#sec-151) and wired into the README, CONTRIBUTING, and the new-issue chooser. |
-| *Preferred:* triage team / contributor onboarding | **PASS** | [docs/triage.md](#sec-430) (labels, claiming, published response targets) and [docs/first-contribution.md](#sec-223) (clone to PR in 15 minutes, worked example) |
+| *Preferred:* community channel | **PASS** | Telegram community, X community, IBM Community group, GitHub Discussions (seeded 2026-08-25: [Welcome #122](https://github.com/nirholas/three.ws/discussions/122), [Show and tell #123](https://github.com/nirholas/three.ws/discussions/123), [Roadmap #124](https://github.com/nirholas/three.ws/discussions/124)), release channel. All five documented in [docs/community.md](#sec-155) and wired into the README, CONTRIBUTING, and the new-issue chooser. |
+| *Preferred:* triage team / contributor onboarding | **PASS** | [docs/triage.md](#sec-448) (labels, claiming, published response targets) and [docs/first-contribution.md](#sec-230) (clone to PR in 15 minutes, worked example) |
| Guest available Friday 1:00 PM ET | Owner to confirm | Pre-recording is allowed as an exception |
| Booked at least two weeks ahead | Plan for it | Earliest realistic slot: **2026-09-11** |
@@ -72215,9 +74962,9 @@ On 2026-08-21 the repo sat at 98. The call was to treat that as noise rather tha
### Done on 2026-08-21
-- **Community channels documented and wired.** [docs/community.md](#sec-151) lists all five rooms with guidance on which fits which question, plus the house rules. Linked from the README (new Community section, in the table of contents), CONTRIBUTING.md, and the GitHub new-issue chooser (`.github/ISSUE_TEMPLATE/config.yml`).
-- **Contributor onboarding written.** [docs/first-contribution.md](#sec-223) goes clone to open PR in about 15 minutes, with a complete worked example: teaching the avatar retargeter a bone-naming convention, the test that proves it, and the two mistakes that cost a review round.
-- **Triage documented.** [docs/triage.md](#sec-430) publishes response targets (2 business days for a new issue or a first-time contributor's PR, 24 hours for a security advisory), what every label means, how to claim work, and how someone becomes a maintainer.
+- **Community channels documented and wired.** [docs/community.md](#sec-155) lists all five rooms with guidance on which fits which question, plus the house rules. Linked from the README (new Community section, in the table of contents), CONTRIBUTING.md, and the GitHub new-issue chooser (`.github/ISSUE_TEMPLATE/config.yml`).
+- **Contributor onboarding written.** [docs/first-contribution.md](#sec-230) goes clone to open PR in about 15 minutes, with a complete worked example: teaching the avatar retargeter a bone-naming convention, the test that proves it, and the two mistakes that cost a review round.
+- **Triage documented.** [docs/triage.md](#sec-448) publishes response targets (2 business days for a new issue or a first-time contributor's PR, 24 hours for a security advisory), what every label means, how to claim work, and how someone becomes a maintainer.
- **Six curated issues opened**, every one with a named file and a verification command:
- [#110](https://github.com/nirholas/three.ws/issues/110) Rig: Apple / ARKit `_joint`-suffixed skeletons (verified: 0 of 10 joints map today)
- [#111](https://github.com/nirholas/three.ws/issues/111) Rig: Kinect trailing-side bone names (verified: 0 of 10)
@@ -72353,7 +75100,7 @@ Every hard criterion is met, stars included. What remains is one click, polish,
| 2026-08-25 | Pin #122 | Owner, one click |
| 2026-08-26 | README front door trimmed, demo clip recorded | Agent |
| 2026-08-25 | **Issue submitted**: [open-source-friday#254](https://github.com/githubevents/open-source-friday/issues/254) | Done |
-| 2026-08-25 | Reply to Andrea's X thread with the issue link (draft: [x-posts/osf-issue-reply.md](#sec-549)) | Owner |
+| 2026-08-25 | Reply to Andrea's X thread with the issue link (draft: [x-posts/osf-issue-reply.md](#sec-573)) | Owner |
| 2026-08-28+ | Booking link arrives on approval, book the slot | Owner |
| ~2026-09-11 | Stream (earliest date satisfying the two-week rule) | Owner |
@@ -72369,7 +75116,7 @@ The license question that used to sit here is resolved: Apache-2.0, shipped 2026
---
-<a id="sec-315"></a>
+<a id="sec-326"></a>
> **Source:** `docs/openai-community-3d-studio-post.md` · [↑ table of contents](#table-of-contents)
@@ -72645,7 +75392,7 @@ nich
---
-<a id="sec-316"></a>
+<a id="sec-327"></a>
> **Source:** `docs/openai-listing-channels.md` · [↑ table of contents](#table-of-contents)
@@ -72653,7 +75400,7 @@ nich
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-269) (every listing across all vendors), [mcp.md](#sec-284) (the hosted MCP server a plugin submission depends on), [nvidia-apps-catalog-listing.md](#sec-301) (the same kind of kit for NVIDIA).
+Related docs: [listings.md](#sec-281) (every listing across all vendors), [mcp.md](#sec-293) (the hosted MCP server a plugin submission depends on), [nvidia-apps-catalog-listing.md](#sec-312) (the same kind of kit for NVIDIA).
---
@@ -72683,7 +75430,7 @@ The gating requirement is a public, production MCP server. Most submitters have
| Requirement | What we already have |
|---|---|
-| Public MCP server | `https://three.ws/api/mcp`, Streamable HTTP, MCP `2025-06-18` ([mcp.md](#sec-284)) |
+| Public MCP server | `https://three.ws/api/mcp`, Streamable HTTP, MCP `2025-06-18` ([mcp.md](#sec-293)) |
| 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` |
@@ -72703,7 +75450,7 @@ Six sections: **Info** (name, short and long description, logo, category, URLs,
### 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-284).
+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-293).
### Known rejection reasons to design against
@@ -72791,7 +75538,7 @@ Not OpenAI-owned, so they do not answer the original question, but they are wher
---
-<a id="sec-317"></a>
+<a id="sec-328"></a>
> **Source:** `docs/openai-pr/00-START-HERE.md` · [↑ table of contents](#table-of-contents)
@@ -72834,13 +75581,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-318) | P0 | Done 2026-07-18 (Option A: deleted) |
-| 02 | [Reconcile the served `.well-known` manifests with the zero-payment claim](#sec-319) | P0 | Yes (reviewer-discoverable crypto surface) |
-| 03 | [Make the `forge_free` tier story true everywhere](#sec-320) | P1 | Yes (submission doc contradicts code) |
-| 04 | [Close the test gaps on the ChatGPT-facing surface](#sec-321) | P1 | No, but required for "done" |
-| 05 | [Serve the custom-GPT OpenAPI and align legal URLs](#sec-322) | P1 | Partial |
-| 06 | [Fix doc accuracy and reconcile the tool-count story](#sec-323) | P1 | No |
-| 07 | [Final live verification and submit checklist](#sec-324) | P2 (runs last) | Yes (the actual go/no-go) |
+| 01 | [Resolve the orphaned studio-viewer widget](#sec-329) | P0 | Done 2026-07-18 (Option A: deleted) |
+| 02 | [Reconcile the served `.well-known` manifests with the zero-payment claim](#sec-330) | P0 | Yes (reviewer-discoverable crypto surface) |
+| 03 | [Make the `forge_free` tier story true everywhere](#sec-331) | P1 | Yes (submission doc contradicts code) |
+| 04 | [Close the test gaps on the ChatGPT-facing surface](#sec-332) | P1 | No, but required for "done" |
+| 05 | [Serve the custom-GPT OpenAPI and align legal URLs](#sec-333) | P1 | Partial |
+| 06 | [Fix doc accuracy and reconcile the tool-count story](#sec-334) | P1 | No |
+| 07 | [Final live verification and submit checklist](#sec-335) | 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.
@@ -72888,7 +75635,7 @@ These are non-negotiable and OVERRIDE any default behavior:
---
-<a id="sec-318"></a>
+<a id="sec-329"></a>
> **Source:** `docs/openai-pr/01-orphan-widget-resolution.md` · [↑ table of contents](#table-of-contents)
@@ -72896,7 +75643,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-317) first for the shared rules and the map.
+Read [`00-START-HERE.md`](#sec-328) first for the shared rules and the map.
## The problem (verified, with evidence)
@@ -73016,13 +75763,13 @@ fetches from** (three.ws, the R2 storage origin, and the CDN if used). Match wha
---
-<a id="sec-319"></a>
+<a id="sec-330"></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-317) first. **This task touches a manifest
+Read [`00-START-HERE.md`](#sec-328) 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.**
@@ -73035,7 +75782,7 @@ asserts the app has a **zero payment surface** and no crypto capability. But a p
reviewer-discoverable manifest at a well-known path says the opposite.
[`public/.well-known/ai-plugin.json`](../public/.well-known/ai-plugin.json)
-currently reads (verbatim):
+read, until commit `1dbbe0b6d` (2026-08-06) rewrote it (verbatim):
```
"description_for_human": "three.ws — 3D avatar/world generation and live crypto intelligence APIs, pay-per-call via x402.",
@@ -73046,10 +75793,28 @@ And [`public/.well-known/openapi.yaml`](../public/.well-known/openapi.yaml) (71K
describes the general REST platform (Auth/Avatars/Keys/OAuth/MCP) and does **not**
include the 3D Studio endpoints (`/api/3d/studio`, `/api/ar`, `forge_free`).
-An OpenAI reviewer hitting `https://three.ws/.well-known/ai-plugin.json` sees a
-crypto/payments pitch, directly contradicting the submission. This is the single
+An OpenAI reviewer hitting `https://three.ws/.well-known/ai-plugin.json` saw a
+crypto/payments pitch, directly contradicting the submission. This was the single
most likely thing to sink the review.
+**Where it stands now.** The served manifest leads with the free lane: its
+`description_for_human` is "Free, keyless 3D avatar and world generation, plus an
+optional paid API catalog for agents.", and `description_for_model` names the free
+surface first (`POST /api/3d/studio`, the MCP lane at `/api/mcp-studio`, the viewer,
+`/api/ar`, the read-only `/api/crypto` index) and points free-lane callers at
+[`public/.well-known/3d-studio-openapi.yaml`](../public/.well-known/3d-studio-openapi.yaml),
+before describing the paid `/api/x402/*` catalog as separate and optional. `logo_url`
+is `https://three.ws/pwa-512x512.png` and `legal_info_url` is `/legal/tos`. The
+3D Studio schema is served at that path and byte-pinned to
+`prompts/store-submissions/_generated/openai-actions.yaml` by
+`npm run check:studio-openapi` (`scripts/sync-studio-openapi.mjs` regenerates the copy).
+`tests/wellknown-manifests.test.js` asserts the served schema carries no
+crypto/payment token and that the platform manifest never advertises the free lane
+as paid; `tests/api/3d-studio-openapi.test.js` pins the schema to exactly
+`/api/3d/studio` and `/api/ar`, keyless, with the AR parameters `api/ar.js` reads.
+`openapi.yaml` still describes the general platform only, which is correct: the free
+lane has its own artifact.
+
## Important scoping decision (this is why the task is delicate)
This manifest is **also a real, live product surface** for the general three.ws
@@ -73084,9 +75849,9 @@ manifest layer. Recommended approach (implement this unless you find it wrong):
3. **Fix the misleading fields on the platform manifest that a 3D-app reviewer would
see as conflicting**, without deleting the real x402 catalog:
- - `logo_url` is `favicon.ico` (`ai-plugin.json:14`). The submission cites a
- 512x512 owned-IP icon. At minimum the logo should be a real branded PNG, not the
- favicon.
+ - `logo_url` was `favicon.ico` (`ai-plugin.json:14`). The submission cites a
+ 512x512 owned-IP icon, and the manifest now points at `pwa-512x512.png`;
+ `tests/wellknown-manifests.test.js` fails if it ever reverts to the favicon.
- Make it unambiguous, in both the human and model descriptions, which
capabilities are free and which are paid, so nothing reads as "the 3D app costs
crypto." The 3D generation lane IS free and keyless. Say so plainly.
@@ -73124,11 +75889,12 @@ manifest layer. Recommended approach (implement this unless you find it wrong):
## Definition of done
-- [ ] The 3D Studio app has a served, payment-free, self-describing discovery artifact
- (jointly with Task 05).
-- [ ] The platform `ai-plugin.json` no longer reads as "the 3D app is a paid crypto
+- [x] The 3D Studio app has a served, payment-free, self-describing discovery artifact
+ (jointly with Task 05): `/.well-known/3d-studio-openapi.yaml`.
+- [x] The platform `ai-plugin.json` no longer reads as "the 3D app is a paid crypto
service"; free vs paid is explicit; logo is a real branded asset.
-- [ ] A test asserts the 3D-app schema is crypto/payment-free.
+- [x] A test asserts the 3D-app schema is crypto/payment-free
+ (`tests/wellknown-manifests.test.js`, `tests/api/3d-studio-openapi.test.js`).
- [ ] `npm test` green.
- [ ] Any commit that would trip the commit gate is prepared but NOT committed;
flagged to the owner in your report with the exact diff.
@@ -73137,13 +75903,13 @@ manifest layer. Recommended approach (implement this unless you find it wrong):
---
-<a id="sec-320"></a>
+<a id="sec-331"></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-317) first.
+Read [`00-START-HERE.md`](#sec-328) first.
## The problem (verified, with evidence)
@@ -73151,24 +75917,42 @@ The submission answer sheet and the code disagree about what quality tier
`forge_free` returns by default.
**The code** ([`api/_mcp-studio/tools.js`](../api/_mcp-studio/tools.js),
-`handleForgeFree`) defaults to `standard` and degrades `high` to `standard` on
-402/timeout. Verbatim comment:
-
-```
-// Fast free lane by default. The deployed high-tier free engine (Hunyuan3D
-// via HF Spaces) blocks the submit for 50-280s with no poll handle, which no
-// ChatGPT tool call survives ... True high-by-default lands when the async
-// self-host Hunyuan3D worker deploys (GCP_HUNYUAN3D_URL).
+`handleForgeFree`) defaults to `standard` and degrades an explicit `high` to
+`standard` on a 402 or submit timeout. When this task was written the comment above
+that line said the high tier was blocked on an async worker; today it reads
+(verbatim):
+
+```
+// Standard by default, and every doc describing this tool says exactly that.
+// The high tier is a real, working option, not a stub: it runs on our own
+// async Hunyuan3D worker (GCP_HUNYUAN3D_URL) behind a genuine poll handle,
+// and a live production probe on 2026-08-06 returned a 2.69 MB high-tier GLB
+// from backend `hunyuan3d` end to end. It stays opt-in rather than default
+...
const tier = VALID_TIER.has(args.tier) ? args.tier : 'standard';
```
+The two reasons it stays opt-in are in that comment: the worker is scale-to-zero,
+so a cold container adds a spin-up on top of the generation, and the high-tier
+access gate is cleared only by the platform seed token (`CRON_SECRET`), so a
+deployment without it would quietly serve standard under a "high by default" promise.
+A job that outlives `STUDIO_FORGE_TIMEOUT_MS` comes back as a pollable handle, never
+an error.
+
**The submission doc**
([`prompts/store-submissions/_generated/openai-submission.md`](../prompts/store-submissions/_generated/openai-submission.md))
-is internally inconsistent:
-- Line ~31 correctly says the tools "default to the standard tier."
-- Line ~146 (the tool table) says `forge_free` "Defaults to the highest quality tier
+was internally inconsistent:
+- Line ~31 correctly said the tools "default to the standard tier."
+- Line ~146 (the tool table) said `forge_free` "Defaults to the highest quality tier
(dense geometry + PBR textures)."
+The tool table row now reads "Defaults to the standard tier (fast, reliable,
+textured); the caller may request `draft` (fastest) or `high` (best, slower; falls
+back to standard under load)", the tool's own `description` and its `tier` enum
+say the same, and the live evidence for both tiers is in
+`prompts/store-submissions/_generated/forge-free-tier-evidence.json` (a `d97e8e94d`
+attempt to make high the default was rolled back in `b39d6e2f7`).
+
A reviewer who reads "highest quality tier" and then gets a standard-tier model has
caught us in a misstatement. Pick the honest resolution and make ALL surfaces agree.
@@ -73185,8 +75969,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-281),
- [`docs/mcp-3d-studio.md`](#sec-278), the tool descriptions the
+ [`docs/mcp-studio.md`](#sec-290),
+ [`docs/mcp-3d-studio.md`](#sec-287), 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
@@ -73224,14 +76008,22 @@ and a doc claiming it works.
- A real `forge_free` call against `/api/mcp-studio` returns a tier consistent with
every doc. Save the response JSON as evidence.
- `npm test` green (run `tests/mcp-forge-free.test.js` and `tests/mcp-studio.test.js`).
+ Note which server each covers: `tests/mcp-studio.test.js` is the ChatGPT-facing
+ `/api/mcp-studio` tool (standard default). `tests/mcp-forge-free.test.js` is the
+ public `mcp-server` package's `forge_free` (`mcp-server/src/tools/forge-free.js`),
+ which defaults to `draft` and no longer pins a backend: the forge router's own
+ free-lane default (self-host TRELLIS, then Hunyuan3D, then HuggingFace, then NVIDIA
+ NIM as the last resort) picks the engine, never the paid Replicate lane.
## Definition of done
-- [ ] Every doc, the submission sheet, and the tool's own `description` agree with the
- code on the default tier.
+- [x] Every doc, the submission sheet, and the tool's own `description` agree with the
+ code on the default tier (Path A: standard by default, high opt-in; the async
+ Hunyuan3D worker from Path B is deployed and proven, but the default stays
+ standard for the reasons in the code comment).
- [ ] If Path B: worker deployed and proven with real evidence; default is genuinely
high.
-- [ ] If Path A: no surface claims "highest quality by default" anymore.
+- [x] If Path A: no surface claims "highest quality by default" anymore.
- [ ] `npm test` green.
- [ ] `data/changelog.json` entry only if user-visible behavior changed (Path B yes;
Path A is a docs/accuracy fix, `docs` tag).
@@ -73239,13 +76031,13 @@ and a doc claiming it works.
---
-<a id="sec-321"></a>
+<a id="sec-332"></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-317) first.
+Read [`00-START-HERE.md`](#sec-328) first.
## The problem
@@ -73258,10 +76050,13 @@ silently break what the reviewer sees.
### Gap 1 — `api/ar.js` HTTP handler is untested
`api/ar.js` is the "View in your space" / "Bring it to life" endpoint every generation
-links to. Only the pure lib `api/_lib/ar-launch.js` is tested (`tests/ar-export.test.js`).
-The handler's own behavior is unverified:
-- User-agent branching (Android → Scene Viewer 302 intent; iOS/desktop → HTML launch
- page; `kind=avatar` → IRL handoff).
+links to. Only the pure lib `api/_lib/ar-launch.js` was tested (`tests/ar-export.test.js`).
+The handler's own behavior was unverified:
+- User-agent branching (Android → Scene Viewer 302 intent; iOS/desktop → a 200
+ interstitial carrying the model's own og:image and title for unfurls, which hands
+ off to `/ar/view`, where a real USDZ is generated on the device for Apple Quick
+ Look; `kind=avatar` → everyone, Android included, lands on `/ar/view` with the IRL
+ handoff).
- The designed error page for a bad/missing `src`.
- `assertArAssetUrl` rejection (non-https, non-`.glb/.gltf`) surfacing as a proper
error response, not a crash.
@@ -73272,6 +76067,12 @@ for each UA class and asserts status, `Location`/redirect, headers, and that the
launch page contains the model URL and the AR launch elements. Follow the request/
response mocking pattern used by the other `tests/api/*.test.js` files in this repo.
+Closed: [`tests/api/ar-endpoint.test.js`](../tests/api/ar-endpoint.test.js) covers
+the Android redirect and its `no-store`, the iOS/iPad/desktop interstitial with the
+title and the forwarded host carried through, the `kind=avatar` handoff, the designed
+400 page for every bad-input class (including `.gltf` lookalikes), `Vary: user-agent`,
+the CORS preflight, and an absent User-Agent.
+
### Gap 2 — `pages/embodiment/embed.html` wiring is untested
The persona widget iframes this page. Its param parsing (`persona/glb/name/state/
@@ -73284,15 +76085,34 @@ the repo already uses for page-level tests) that:
- Loads with an unresolvable persona and asserts the designed error/empty state, not a
blank void or console error.
+Closed on two levels: [`tests/api/embodiment-embed-page.test.js`](../tests/api/embodiment-embed-page.test.js)
+pins the page's wiring contract (the documented query params, the persona resolve and
+its failure surface, the designed error when neither `glb` nor `persona` is supplied,
+the opt-in `wallet=1` identity poll, and that a resolved persona's name survives every
+later state change instead of reverting to "Agent"), and
+[`tests/e2e/embodiment-embed.spec.js`](../tests/e2e/embodiment-embed.spec.js)
+loads the page in a real browser.
+
### Gap 3 — No contract test binding `api/3d/studio.js` to `openai-actions.yaml`
-The custom-GPT Actions response shape (`{status, glbUrl, viewerUrl, arUrl, format}` or
-`{status:'pending', job, poll}`) must match the served OpenAPI schema (Task 05 serves
-it). Add a contract test that loads the OpenAPI schema and validates a real
+The custom-GPT Actions response shape (`{status:'done', glbUrl, viewerUrl, arUrl,
+format, previewImageUrl?, tier?}` or `{status:'pending', job, poll, watchUrl,
+previewImageUrl?, tier?, etaSeconds?}`) must match the served OpenAPI schema (Task 05
+serves it). Add a contract test that loads the OpenAPI schema and validates a real
`api/3d/studio.js` response object against it (the response-shaper is pure and
exported per the file). Use an existing JSON-schema/OpenAPI validator already in
`package.json` if present; do not add a heavy new dependency for this.
+Closed: [`tests/api/3d-studio-actions-contract.test.js`](../tests/api/3d-studio-actions-contract.test.js)
+compiles the served
+[`public/.well-known/3d-studio-openapi.yaml`](../public/.well-known/3d-studio-openapi.yaml)
+with `ajv` (2020-12 draft, plus `ajv-formats`, both already dependencies) and validates
+the exported `shapeSubmit` / `shapePoll` output for the inline-done, queued, running,
+finished, failed, and transient-hiccup states, plus every typed error envelope (400
+`invalid_prompt`, `invalid_tier`, `prompt_rejected`, `bad_request`, `missing_job`,
+`invalid_job`; 429 `rate_limited` with `retry_after`; 502 `generation_failed`; 503
+`not_configured`) against the schema's `GenerationState` and `ErrorResponse`.
+
## Constraints
- Every rule in `00-START-HERE.md`. No mocked *generation* results that pretend to be
@@ -73311,11 +76131,11 @@ exported per the file). Use an existing JSON-schema/OpenAPI validator already in
## Definition of done
-- [ ] `tests/api/ar-endpoint.test.js` covers all UA classes, the error page, and
+- [x] `tests/api/ar-endpoint.test.js` covers all UA classes, the error page, and
headers.
-- [ ] A page-level test covers `pages/embodiment/embed.html` param parsing, persona
+- [x] A page-level test covers `pages/embodiment/embed.html` param parsing, persona
resolve, and the failure state.
-- [ ] A contract test binds `api/3d/studio.js` output to the served OpenAPI (coordinate
+- [x] A contract test binds `api/3d/studio.js` output to the served OpenAPI (coordinate
with Task 05 for the schema location).
- [ ] `npm test` green.
- [ ] Each new test demonstrably fails when its target is broken (verified, then
@@ -73325,13 +76145,13 @@ exported per the file). Use an existing JSON-schema/OpenAPI validator already in
---
-<a id="sec-322"></a>
+<a id="sec-333"></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-317) first. Coordinate with Task 02 (the
+Read [`00-START-HERE.md`](#sec-328) 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)
@@ -73414,13 +76234,13 @@ be normalized to one canonical form.
---
-<a id="sec-323"></a>
+<a id="sec-334"></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-317) first. This task cleans up the
+Read [`00-START-HERE.md`](#sec-328) 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.
@@ -73496,13 +76316,13 @@ claim is Task 03). Do not fight those tasks for those specific edits; coordinate
---
-<a id="sec-324"></a>
+<a id="sec-335"></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-317) first. **Run this only after tasks
+Read [`00-START-HERE.md`](#sec-328) 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
@@ -73590,7 +76410,446 @@ go/no-go report. Do not submit; prepare so the human's final submit is one actio
---
-<a id="sec-325"></a>
+<a id="sec-336"></a>
+
+> **Source:** `docs/oracle-model.md` · [↑ table of contents](#table-of-contents)
+
+# The Oracle model, and how to run it yourself
+
+The Oracle watches every pump.fun launch for its first ninety seconds and scores
+it 0-100. This document is the whole machine: what it predicts, how it is fitted,
+why its outcome labels had to be rebuilt, how a new version earns the right to
+replace the live one, and how to download the weights and score launches on your
+own hardware with no API key.
+
+- **Live feed**: [/oracle](/oracle)
+- **The model, rendered**: [/oracle-lab](/oracle-lab)
+- **The model, raw**: [`/api/oracle/model`](/api/oracle/model)
+- **npm**: `@three-ws/oracle-model`
+
+---
+
+## 1. What the score means
+
+**The score line is not a percentage.** A score of 86 claims a 45% chance, not an
+86% one. This trips up everyone, including us: every calibration table we
+published before 2026-08-14 used `score / 100` as the prediction, which
+overstated the engine's own claim by up to four times and made a working ranking
+look wildly overconfident.
+
+| Tier | Score | Claims | Observed on held-out data |
+|---|---|---|---|
+| Prime | 86+ | P(win) >= 45% | 47.6% (n=267) |
+| Strong | 72+ | P(win) >= 25% | 40.3% (n=852) |
+| Lean | 56+ | P(win) >= 12% | 23.4% (n=1,418) |
+| Watch | 34+ | P(win) >= 5% | 10.7% (n=2,725) |
+| Avoid | 0+ | below that | 1.8% (n=68,949) |
+
+Those observed numbers are the bootstrap model's holdout: 74,211 launches the
+model had never seen, from the fit shipped in `conviction-model.json`. They are
+recomputed on every refit and published live at
+[`/api/oracle/model?view=card`](/api/oracle/model?view=card), so the table above
+can go stale but the endpoint cannot.
+
+### Three questions, not one
+
+Version 3 fits three heads over one shared design matrix:
+
+| Head | Question | Base rate | Held-out AUC |
+|---|---|---|---|
+| `win` | Did it run, **and** is a first-sight holder still up? | 2.94% | 0.840 |
+| `rug` | Is a first-sight holder down more than half? | 11.36% | 0.918 |
+| `moon` | Did it run at all (graduated, or peaked 3x+)? | 9.51% | 0.892 |
+
+The published score anchors on `win`.
+
+That choice is the entire reason v3 exists. v2 ranked `moon`, so a coin that
+spiked 3x and went to zero counted as a hit. Over the seven days to 2026-08-28,
+Prime-tier coins under v2 hit that target 58.2% of the time and rugged 53.0% of
+the time, with 27.8% doing both. The engine was accurate and useless: it answered
+"will this move" when every reader heard "should I hold this".
+
+### The number to watch: give-back risk
+
+```
+giveBackRisk = 1 - P(win) / P(moon)
+```
+
+Given this coin runs, how often does one like it hand the run straight back? A
+launch with 80% upside and 90% give-back is not an opportunity, it is a trap, and
+no single-headed score can tell the two apart. It is published on every verdict,
+stored on every scored coin (`oracle_conviction.give_back_risk`), and indexed, so
+the feed can be sorted by it.
+
+---
+
+## 2. The label problem, and why it mattered more than the model
+
+For most of this engine's life, its outcome labels measured the price of SOL.
+
+`deriveOutcome` decided a rug with two tests: did the coin fall to 25% or less of
+its market cap at first sight, or is its market cap under $3,000.
+
+A pump.fun bonding curve holding no real reserves is worth a fixed amount. The
+launch parameters put 30 virtual SOL against 1,073,000,191 virtual tokens over a
+1e9 supply:
+
+```
+30 * 1e9 / 1_073_000_191 = 27.958993 SOL
+```
+
+No coin on the curve can be worth less than that. We first see a coin inside its
+opening ninety seconds, when its cap is 28-38 SOL, so **the floor is 73-99% of
+the market cap at first sight** and the "fell to 25%" branch is unreachable for
+almost every launch that has ever existed.
+
+That left a hardcoded dollar threshold judging an asset with a fixed SOL price.
+Measured over the ten days to 2026-08-28:
+
+| Group | n | Under $3,000 | Minimum |
+|---|---|---|---|
+| labeled `rugged`, not graduated | 206,428 | 206,419 (99.996%) | $0 |
+| labeled survivor, not graduated | 25,180 | 0 | exactly $3,000 |
+
+Both groups are the same object: an empty bonding curve. 25,180 completely dead
+coins were labeled survivors because SOL happened to be above roughly $107.30
+when the labeler reached them. It is also why the daily rug rate sat at 90-94%
+for weeks and then dropped to 55.3% on 2026-08-27, which is not a change in the
+market, it is SOL crossing a line.
+
+Everything downstream that subtracted rugs from a win rate was reading a price
+feed.
+
+### The fix
+
+Two ratios, both taken from the **same** market-cap reading, so the SOL price
+cancels out of each:
+
+```
+retained = last_market_cap_usd / ath_market_cap_usd
+hold_multiple = ath_multiple * retained
+```
+
+`hold_multiple` is what a holder who bought at first sight and held would have.
+
+```
+moon = graduated OR ath_multiple >= 3
+rug = NOT graduated AND hold_multiple <= 0.5
+win = moon AND hold_multiple >= 1
+```
+
+Neither ratio can be moved by the price of SOL, and both backfill exactly from
+columns we already stored, so the historical corpus was corrected in a single
+migration with no re-fetching. A row with no `hold_multiple` at all cannot
+answer the survival question, so it is neither a `win` nor a `rug` (it can
+still be a `moon`); it is never read as a 100% drawdown and counted as a rug.
+
+**The real rug rate is 11.4%, not 91%.** And it holds within two points across
+every observation-age bucket from 60 minutes to three days, which is what a
+property of the coin is supposed to do:
+
+| Checked at | n | graduated | rug | win | moon |
+|---|---|---|---|---|---|
+| 60-90 min | 238,138 | 2.89% | 11.02% | 3.02% | 10.06% |
+| 90-180 min | 1,215 | 2.39% | 10.45% | 2.55% | 9.22% |
+| 6-24 h | 481 | 1.04% | 7.48% | 2.29% | 10.60% |
+| 1-3 d | 9,228 | 1.28% | 9.27% | 1.34% | 7.49% |
+| 3 d+ | 13,746 | 0.77% | 9.06% | 1.21% | 6.29% |
+
+`label_version` marks which rule judged a row: `1` for the USD-threshold rule,
+`2` for the price-independent one. **The fitter trains on version 2 only.**
+Mixing them poisons two heads out of three; trained on version 1 labels, the
+survival head scored an AUC of 0.484, which is worse than guessing.
+
+There is one thing the old rule got right that the new one deliberately drops: a
+coin that never moved and now sits at the empty curve is a **dud**, not a rug.
+Nobody was taken, because there was nothing to take. `at_floor` records that
+state exactly (the curve is within 2% of `27.958993 SOL`) and is published
+separately rather than folded into the rug flag.
+
+---
+
+## 3. How the model is fitted
+
+One bucketed logistic regression per head, over a shared one-hot design matrix.
+Not a black box: **every weight is a per-bucket log-odds contribution published
+with its sample size and the observed outcome rate behind it.**
+
+Buckets rather than slopes, because several signals are genuinely non-monotone.
+Mid-range snipe ratios and mid-range top-10 concentration both beat their own
+extremes, and a linear term would fight the data at both ends. "Low
+concentration" ninety seconds in usually means nobody bought.
+
+```
+score = anchors(sigmoid(intercept + sum of one bucket weight per feature))
+```
+
+The code is [`api/_lib/oracle/fit.js`](https://github.com/nirholas/three.ws/blob/main/api/_lib/oracle/fit.js),
+shared by the CLI and the production cron so the terminal and the server can
+never disagree about what "the model" means.
+
+### Thin buckets say less
+
+After the fit, every weight is shrunk toward zero in proportion to the evidence
+behind it: `w * n / (n + 200)`, where `n` is the number of rows in that bucket
+(`fit.shrink_prior` in the model document). A bucket with 200 rows keeps half
+its fitted weight, one with 2,000 keeps 91%, one with 34 keeps 15%. Without
+this, a 34-row bucket could emit a -0.64 log-odds opinion that reversed a
+verdict in production; `smart_money_count >= 4` did exactly that, fitting
+negative on the `win` head although those launches won at four times the base
+rate, because with so few rows the regression hands the bucket whatever
+residual the correlated volume and buyer-count features leave behind. The
+shrinkage is applied before evaluation, never after, so the holdout numbers
+describe the weights that actually ship.
+
+### Features drop themselves
+
+Any feature whose runner-up bucket holds fewer than 200 rows carries no fittable
+information and is dropped, by name, into the report.
+
+Deliberately **not** a share test. `smart_money_count` is non-zero on 0.3% of
+launches, and those launches win 82% of the time against a 4.55% base. A rule
+that dropped rare signals would throw away the strongest thing this dataset
+knows.
+
+Two features are dropped today, and the reason is an outage rather than a
+property of the market:
+
+| Dropped | Why |
+|---|---|
+| `fresh_wallet_ratio` | null in 300,000 of 300,000 recent rows: nothing populates `observation.walletMeta` |
+| `bubblemap_connectivity` | needs `HELIUS_API_KEY`, which is not set; 42 of 713,908 recent wallets resolve a funder |
+
+They are named on [/oracle-lab](/oracle-lab) and in the API response instead of
+silently vanishing, because a signal that stopped arriving is an outage somewhere
+upstream and the model is the first place it becomes visible. **If they start
+arriving, the next refit picks them up with no code change.**
+
+A third, `coordination_score`, is kept but is close to worthless: it computes as
+`bundle_score * 0.6 + (bubblemap ?? 0) * 0.4`, and with bubblemap null it is a
+scaled copy of `bundle_score`. The live intel weights list the two as identical
+to four decimal places.
+
+### Smart money is fitted now, not assumed
+
+v2 added between +0.35 and +0.75 log-odds by hand when proven wallets showed up,
+because "214 proven wallets platform-wide" was too thin to fit. It is not thin
+any more:
+
+| Proven wallets in the window | n | win | rug | run |
+|---|---|---|---|---|
+| 0 | 296,111 | 2.85% | 11.38% | 9.29% |
+| 1 | 347 | 25.65% | 2.59% | 95.39% |
+| 2-3 | 351 | **54.99%** | **0.00%** | 98.86% |
+| 4+ | 34 | 11.76% | 0.00% | 97.06% |
+
+Two or three proven wallets buying inside the observation window means a 55%
+survivable-win rate and zero rugs in 351 samples.
+
+When the active model carries a fitted `smart_money_count` feature, the expert
+overlay's smart-money and creator-history terms **stand down automatically**.
+Counting the same evidence twice is not conservatism, it is a bug. What survives
+in the overlay is only evidence the training set has no column for: whether the
+proven wallets are already selling, whether any of them are tagged ruggers, and
+the serial-rugger score ceiling (a product guarantee, not a probability estimate:
+a dev with a graveyard behind them can never present as Strong).
+
+---
+
+## 4. How a new model earns the right to ship
+
+`/api/cron/oracle-refit` runs every six hours. It loads the labeled set, fits
+three heads with a time-split holdout, and then has to get past a gate that can
+say no.
+
+This part matters. An automated retrain that always ships whatever it just fitted
+is not a learning loop, it is a single point of failure on a timer: one bad data
+day and production is serving a model nobody looked at.
+
+| Check | Requirement |
+|---|---|
+| `fit_complete` | every epoch ran; a deadline-truncated fit is under-trained, not wrong, and must not quietly ship |
+| `absolute_auc` | scoring head AUC >= 0.70, incumbent or not |
+| `tier_honesty` | every populated band still earns at least 70% of the probability it claims |
+| `feature_set` | did not lose more than 3 features (that is a broken signal source, not learning) |
+| `auc_gain` | beats the incumbent by >= 0.004 AUC, which is more than SGD ordering noise |
+| `no_regression_*` | no other head fell by more than 0.01 |
+
+The gain bar is not zero on purpose. Two fits on nearly the same data differ by a
+few thousandths of AUC from shuffle ordering alone, and promoting on that noise
+would rewrite the live model every six hours, making every published score a
+moving target and every track record unreproducible.
+
+Every candidate is stored either way, **including the refused ones, with the
+reason**, in `oracle_model_versions`. A registry that shows only the winners is a
+highlight reel, not a record.
+
+```
+GET /api/oracle/model?view=registry
+```
+
+### Where the weights live
+
+They used to be a JSON file baked into the container at build time, so the only
+thing that could refit them was a human running a script by hand. Nobody did.
+Between 2026-08-09 and 2026-08-28 the model answered every question with a
+92,906-row opinion while eight times that much evidence piled up behind it, and
+on a current holdout it had given up six points of top-decile precision (53.7%
+against 59.8% for a fresh fit).
+
+Now:
+
+- **`oracle_model_versions`** holds the promoted weights. `ensureActiveModel()`
+ loads them with a 2-minute TTL, so a promotion is live platform-wide inside one
+ scoring cycle with no deploy.
+- **`api/_lib/oracle/conviction-model.json`** is the bootstrap a cold container
+ boots on, and what the tests run against.
+- If the database read fails, whatever model is already installed keeps scoring.
+ A scoring engine that returns nothing because it could not check for a newer
+ opinion is strictly worse than one using a slightly older one.
+
+Every stored verdict records `model_version_id`, so any score on the platform can
+be traced to the exact weights that produced it and recomputed offline.
+
+---
+
+## 5. Run it yourself
+
+```bash
+npm install @three-ws/oracle-model
+```
+
+```js
+import { OracleModel } from '@three-ws/oracle-model';
+
+const oracle = await OracleModel.fetch(); // one request, ~32KB
+
+const v = oracle.score({
+ organic_score: 0.82,
+ unique_buyers: 41,
+ buy_volume_sol: 26,
+ snipe_ratio: 0.12,
+ smart_money_count: 2,
+ dev_sold: false,
+ creator_launches: 3,
+ creator_wins: 1,
+});
+
+console.log(v.score, v.tierLabel); // 90 Prime
+console.log(v.upside, v.giveBackRisk, v.rugRisk);
+```
+
+After `fetch()` there is no network. No key, no rate limit, no telemetry. Every
+signal is optional: a missing one lands in the model's fitted `null` bucket,
+which carries real information (a coin nobody has sold yet is telling you
+something) rather than being treated as zero.
+
+### Show the arithmetic
+
+```js
+const { math } = oracle.explain(signals);
+
+math.formula // 'p = 1 / (1 + exp(-(intercept + sum(term log_odds))))'
+math.intercept // -3.9975
+math.terms // one row per bucket, with its sample count
+math.total_log_odds // add the column up by hand; you will land here
+```
+
+### Check our work
+
+```js
+const report = oracle.verify([
+ { signals: { /* ... */ }, outcome: true },
+ { signals: { /* ... */ }, outcome: false },
+]);
+
+report.auc // ranking quality on YOUR data
+report.brier // calibration error
+report.reliability // does a claim of 25% happen 25% of the time?
+```
+
+If our published numbers do not survive contact with an independent sample, this
+is how you find out, and we would rather you could.
+
+### Watch it change its mind
+
+```js
+const older = new OracleModel(docFromRegistry(42));
+const newer = new OracleModel(docFromRegistry(43));
+
+older.diff(newer).moves.slice(0, 5);
+// [{ key: 'snipe_ratio/0.3-0.7', from: 0.41, to: 0.58, delta: 0.17, samples: 8102 }, ...]
+```
+
+The same diff is available server-side at
+`/api/oracle/model?view=diff&from=42&to=43`.
+
+---
+
+## 6. API reference
+
+### `GET /api/oracle/model`
+
+The active model in full: card, weights, holdout, provenance.
+
+| Query | Effect |
+|---|---|
+| `view=card` | just the summary: what it predicts, how well, how old, what it dropped |
+| `view=registry` | every version, promoted or refused, with the decision |
+| `view=diff&from=&to=` | every bucket weight that moved between two versions |
+| `network=` | `mainnet` (default) or `devnet` |
+
+Public, no auth, cached 60s at the client and 300s at the edge.
+
+### The verdict object
+
+| Field | Meaning |
+|---|---|
+| `score` | 0-100, anchored on P(win). Not a percentage. |
+| `tier` / `tierLabel` | `avoid` \| `watch` \| `lean` \| `strong` \| `prime` |
+| `probabilities` | raw `win`, `rug`, `moon` |
+| `upside` | P(runs), 0-100 |
+| `rugRisk` | P(holder down more than half), 0-100 |
+| `giveBackRisk` | P(hands the run back \| it runs), 0-100 |
+| `survival` | `100 - rugRisk` |
+| `confidence` | share of the model's signals actually supplied |
+| `reasons` | strongest evidence first, each with its bucket rate and sample count |
+| `badges` | `smart-money`, `structure-flag`, `pedigree-flag`, `rug-risk`, `give-back`, `thin-data`, `momentum`, `news` |
+| `predicts` | what the score claims, in words |
+| `model` | version, fit time, training rows, scoring head |
+
+---
+
+## 7. Operations
+
+| Task | Command |
+|---|---|
+| Fit and report, write nothing | `node scripts/oracle-fit.mjs` |
+| Refresh the bootstrap in the image | `node scripts/oracle-fit.mjs --write` |
+| Machine-readable report | `node scripts/oracle-fit.mjs --json` |
+| Cap the training window | `node scripts/oracle-fit.mjs --rows 200000` |
+| Trigger a refit by hand | `GET /api/cron/oracle-refit` (cron auth) |
+
+`DATABASE_URL` lives in `.env.local`, not `.env`. The fitter reads both; it used
+to read only `.env` and died with "DATABASE_URL not set", which is a large part
+of why the model went nineteen days without a refit.
+
+| Table | Holds |
+|---|---|
+| `oracle_training_set` | never-pruned (features, outcome) per labeled coin, with `label_version` |
+| `pump_coin_outcomes` | rolling outcome labels, plus `retained` / `hold_multiple` / `at_floor` |
+| `oracle_model_versions` | every fitted model, its holdout, its promotion decision |
+| `oracle_conviction` | the live verdict per coin, with `rug_risk` / `upside` / `give_back_risk` / `model_version_id` |
+
+## See also
+
+- [Oracle: the conviction engine, end to end](/docs/oracle)
+- [Coin Intelligence](/coin-intel), the observation pipeline that produces the signals
+- [Oracle Lab](/oracle-lab), all of the above rendered
+
+---
+
+<a id="sec-337"></a>
> **Source:** `docs/oracle-trading-mcp-plan.md` · [↑ table of contents](#table-of-contents)
@@ -73810,7 +77069,7 @@ Per the documentation rules in `CLAUDE.md`, all of these apply and none are opti
### Phase 5: the X post
-Draft lives at [`docs/oracle-trading-mcp-x-post.md`](#sec-548). Written before
+Draft lives at [`docs/oracle-trading-mcp-x-post.md`](#sec-572). 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.
@@ -73844,7 +77103,7 @@ than shipping late.
---
-<a id="sec-326"></a>
+<a id="sec-338"></a>
> **Source:** `docs/oracle.md` · [↑ table of contents](#table-of-contents)
@@ -73883,9 +77142,9 @@ One design commitment holds the whole thing together: scoring is a pure, side-ef
## The model: fitted from real outcomes
-Since 2026-08-09 the conviction engine is a bucketed logistic model fitted on the platform's own labeled outcome history (92,906 launches at first fit, growing ~30k/day), not a hand-tuned point system. "Good" is defined as the coin graduated or reached a 3x-or-greater ATH multiple. Every launch-time signal is bucketed by its empirically observed ranges, each bucket carries a fitted log-odds weight, and the fused sum passes through a sigmoid to yield a calibrated P(good). The full weight table ships in `api/_lib/oracle/conviction-model.json` with each bucket's sample size and observed good-rate, and `scripts/oracle-fit.mjs` refits it from the durable training snapshot (`oracle_training_set`) whenever the data has grown.
+Since 2026-08-09 the conviction engine is a bucketed logistic model fitted on the platform's own labeled outcome history, not a hand-tuned point system. v2 fitted one target ("good": the coin graduated or reached a 3x-or-greater ATH multiple) on 92,906 launches. Since 2026-08-28 the engine is **v3**: three heads fitted over one shared design matrix, all reading a `hold_multiple` that cancels the SOL price out of the label (`win`: it ran and a first-sight holder is still up; `rug`: a first-sight holder is down more than half; `moon`: it ran at all, the v2 target). The published 0-100 score anchors on `win`, and rug risk is published beside it as its own number rather than folded in (`rugRisk`, `upside`, `giveBackRisk` on every verdict). Every launch-time signal is bucketed by its empirically observed ranges, each bucket carries a fitted log-odds weight per head, and the fused sum passes through a sigmoid to yield a calibrated probability for each head. The promoted weights live in `oracle_model_versions` and `/api/cron/oracle-refit` refits and re-promotes them behind a gate that can refuse a candidate; `api/_lib/oracle/conviction-model.json` is the bootstrap a cold container scores with until it reads the active row (each bucket ships with its sample size and observed rate per head), and `scripts/oracle-fit.mjs` refreshes that bootstrap from the durable training snapshot (`oracle_training_set`). The whole model, labels and promotion gate included, is written up in [The Oracle model](#sec-336).
-The honest numbers, measured on a time-split holdout (the newest 25 percent of labels, never seen in training): AUC 0.879 (the hand-tuned v1 engine measured 0.627 on the same window), 62.5 percent of coins in the top decile of score were good against an 11.7 percent base rate, and the Prime tier observed 72.7 percent good.
+The honest numbers. v2, measured on a time-split holdout (the newest 25 percent of labels, never seen in training): AUC 0.879 (the hand-tuned v1 engine measured 0.627 on the same window), 62.5 percent of coins in the top decile of score were good against an 11.7 percent base rate, and the Prime tier observed 72.7 percent good. v3, held out on 74,211 launches it never saw: win AUC 0.840, rug AUC 0.918, moon AUC 0.892. The live reading is always at `/api/oracle/model?view=card`.
The fit corrected several v1 beliefs that were backwards at the 90-second observation window:
@@ -73901,7 +77160,7 @@ The four pillars remain as the presentation layer: every feature belongs to WHO
Each feature below is bucketed and carries fitted weights in `conviction-model.json`. The observed good-rates quoted are from the training set at first fit; the shipped JSON is always the source of truth.
-**WHO (pedigree)**: the creator's launch record (`creator_record`: first launch 1.9x base; any prior graduation 1.5x; 5+ launches with none graduated 0.26x), dev buy size, and whether the dev sold inside the observation window. On top of the fitted features sits the smart-money overlay (below).
+**WHO (pedigree)**: the creator's launch record (`creator_record`: first launch 1.9x base; any prior graduation 1.5x; 5+ launches with none graduated 0.26x), dev buy size, whether the dev sold inside the observation window, and (since v3) the count of proven smart-money wallets buying in the window, fitted directly. The expert priors the model cannot fit sit on top (below).
**HOW (structure)**: organic-demand score (below 0.2: 0.11x base; 0.8+: 5.1x, the single strongest signal), bundle score, snipe ratio, coordination score, buy-timing entropy, and top-1/top-10 holder concentration with their empirically non-monotone buckets.
@@ -73911,7 +77170,7 @@ Each feature below is bucketed and carries fitted weights in `conviction-model.j
### The smart-money overlay
-Proven and flagged wallets are too rare to fit statistically (998 proven wallets platform-wide against 288k judged), but when they do appear they are the highest-fidelity evidence there is, so they adjust the fused log-odds as documented expert priors: proven wallets in the book add up to +0.75 log-odds (about a 2.1x odds bump), a 40-percent-plus proven share of buy volume adds +0.3, each flagged rugger/dumper wallet subtracts 0.45 (up to three), and smart money already exiting half its position subtracts 0.7. A wallet counts as proven if labelled `smart_money`/`kol` or scoring 70+; since 2026-08-09 a wallet also earns `smart_money` at 8-plus judged coins with a 35-percent-plus win rate, a sustained ~3x edge over the market, validated against holdout outcomes (coins with 3 or more such wallets buying early were good 95 percent of the time).
+Under v2, proven wallets were too rare to fit statistically, so they adjusted the fused log-odds as hand-set expert priors (+0.35 to +0.75 log-odds for proven wallets in the book, +0.3 for a 40-percent-plus proven share of buy volume). v3 fits `smart_money_count` directly (two or three proven wallets buying inside the window observed a 55 percent survivable-win rate and zero rugs across 351 samples), and when the active model carries that feature the overlay's smart-money and creator-history terms stand down automatically, so the same wallets are never counted twice. What survives in the overlay is evidence the training set has no column for: each flagged rugger/dumper wallet subtracts 0.45 (up to three), smart money already exiting half its position subtracts 0.7 (a quarter: 0.35), and the serial-rugger ceiling below. A wallet counts as proven if labelled `smart_money`/`kol` or scoring 70+; since 2026-08-09 a wallet also earns `smart_money` at 8-plus judged coins with a 35-percent-plus win rate, a sustained ~3x edge over the market.
### One cap survives: the serial rugger
@@ -73922,27 +77181,28 @@ v1 had seven different hard ceilings. The outcome data supported exactly one, so
The fusion is a sum in log-odds space, then a sigmoid, then a fixed monotone map onto the public 0-100 ladder:
```
-z = intercept + sum(fitted bucket weights) + smart-money overlay
-p = 1 / (1 + e^(-z)) # calibrated P(graduated or 3x+ ATH)
-score = piecewise-linear map of p # anchors: 5% -> 34, 12% -> 56, 30% -> 72, 55% -> 86
+z_head = intercept_head + sum(fitted bucket weights for that head) + expert priors the model cannot fit
+p_head = 1 / (1 + e^(-z_head)) # one calibrated probability per head: win, rug, moon
+score = piecewise-linear map of p_win # anchors: 5% -> 34, 12% -> 56, 25% -> 72, 45% -> 86
score = min(score, 45 if serial-rugger creator)
+rugRisk = 100 * p_rug; upside = 100 * p_moon; giveBackRisk = 100 * (1 - p_win / p_moon)
```
-The tier ladder is unchanged in public shape, but each boundary now states a measured probability, and production has since graded it. The rates below are the live reading over the 61,916 scored coins the market had resolved as of 2026-08-14, measured against the event the score actually predicts (graduates, or peaks at 3x or more), not against the stricter holder-honest win:
+The tier ladder is unchanged in public shape, but each boundary states a measured probability of the `win` event (the coin runs and a first-sight holder is still up), and every fit grades it on launches it never saw. The rates below are the v3 bootstrap's holdout (74,211 launches, 3.2 percent base rate); the model refits on a clock, so the live table is `/api/oracle/model?view=card`:
-| Tier | Score | Claims | Observed in production | n | vs base |
+| Tier | Score | Claims | Observed on holdout | n | vs base |
| --- | --- | --- | --- | --- | --- |
-| **Prime** | 86 and up | P at least 55 percent | 68.4 percent | 1,032 | 6.5x |
-| **Strong** | 72 to 85 | P at least 30 percent | 31.8 percent | 968 | 3.0x |
-| **Lean** | 56 to 71 | P at least 12 percent | 20.7 percent | 3,717 | 2.0x |
-| **Watch** | 34 to 55 | P at least 5 percent | 12.0 percent | 11,876 | 1.1x |
-| **Avoid** | below 34 | P under 5 percent | 7.5 percent | 44,323 | 0.7x |
+| **Prime** | 86 and up | P at least 45 percent | 47.6 percent | 267 | 15.0x |
+| **Strong** | 72 to 85 | P at least 25 percent | 40.3 percent | 852 | 12.7x |
+| **Lean** | 56 to 71 | P at least 12 percent | 23.4 percent | 1,418 | 7.4x |
+| **Watch** | 34 to 55 | P at least 5 percent | 10.7 percent | 2,725 | 3.4x |
+| **Avoid** | below 34 | P under 5 percent | 1.8 percent | 68,949 | 0.6x |
-Monotone, separated, and honest at every rung, which is why the ladder stays where it is. Every tier clears the probability it claims. The ladder lives in one place, `TIERS` and `SCORE_ANCHORS` in `api/_lib/oracle/conviction.js`, so the boundaries the API returns and the ones the UI paints can never disagree.
+Monotone, separated, and honest at every rung, which is why the ladder stays where it is. Every tier clears the probability it claims, and the promotion gate refuses any refit whose populated bands stop earning at least 70 percent of what they claim. The ladder lives in one place, `TIERS` and `SCORE_ANCHORS` in `api/_lib/oracle/conviction.js` (the anchors come from the active model's `tier_probability_anchors`), so the boundaries the API returns and the ones the UI paints can never disagree.
Only prime and strong are act signals. A conviction engine that likes everything is a hype engine.
-Every verdict also carries compact badges the UI renders as pills: `smart-money` (three or more proven wallets in), `structure-flag` (a strongly negative fitted structure bucket), `pedigree-flag` (the rugger cap fired), `news` (riding a live story), `momentum` (that pillar alone would reach prime, subscore 86 plus), and `thin-data` (most model features unobserved). There is deliberately no `prime` badge: the card paints the tier beside the score already, so it only ever restated the pill next to it, and a badge every top card carries is decoration rather than signal. The same reasoning moved `momentum` up from 72, where it fired on 93 percent of the live feed.
+Every verdict also carries compact badges the UI renders as pills: `smart-money` (three or more proven wallets in), `structure-flag` (a strongly negative fitted structure bucket), `pedigree-flag` (the rugger cap fired), `news` (riding a live story), `momentum` (that pillar alone would reach prime, subscore 86 plus), `thin-data` (most model features unobserved), `rug-risk` (the rug head at 60 percent or more), and `give-back` (give-back risk at 70 percent or more on a coin with at least 25 percent upside: a likely run that is likely to be handed straight back). There is deliberately no `prime` badge: the card paints the tier beside the score already, so it only ever restated the pill next to it, and a badge every top card carries is decoration rather than signal. The same reasoning moved `momentum` up from 72, where it fired on 93 percent of the live feed.
And every verdict ships its reasons in plain language ordered by evidence strength, each quoting the observed outcome rate for its bucket. Each reason carries three fields beside the sentence, so a surface can render the evidence without parsing English back apart:
@@ -73950,25 +77210,23 @@ And every verdict ships its reasons in plain language ordered by evidence streng
| --- | --- | --- |
| `text` | `40+ early buyers: 80% of similar launches worked (6.8x base rate)` | The full sentence |
| `subject` | `40+ early buyers` | What the model saw, in trader units |
-| `rate` | `80` | Percent of that bucket's training launches that were good |
+| `rate` | `80` | Percent of that bucket's training launches that won, on the head the score anchors on |
| `lift` | `6.8` | How many times the base rate that is |
`subject` is phrased per fitted bucket rather than printed from the model's own labels: "40+ early buyers", not "unique_buyers >=40". You never get a bare number, and you never get a raw one either.
### The holder's number: `hitRateFor(score)`
-The score ranks the odds of a *run*, judged independently of a later collapse (see PREDICTED_EVENT above). That is the right target for a ranking and the wrong one for someone deciding whether to hold, so every verdict and every feed row also carries the stricter measurement:
+A score claims a probability; a holder wants to know how often that claim came true. So every verdict and every feed row also carries the measured rate behind the score:
```
-hit_rate fraction of resolved coins in this score band that graduated
- or ran 2x or more WITHOUT ever rugging
-hit_rate_lift how many times the market's own base rate that is
-hit_rate_n how many resolved coins the band's rate was measured over
+hit_rate fraction of held-out launches in this probability band that
+ won (ran, and a first-sight holder was still up)
+hit_rate_lift how many times the holdout's base rate that is
+hit_rate_n how many held-out launches the band's rate was measured over
```
-It comes from `api/_lib/oracle/conviction-calibration.json`, an isotonic (pool-adjacent-violators) fit of the realized win rate per 10-point score band over every coin Oracle scored that the market has since resolved. At the 2026-08-14 fit: 61,916 coins, 5.4 percent base rate, and a top band (90 to 100) that held a clean 2x 26.3 percent of the time, 4.8x base. Isotonic rather than raw per-band rates because a band that dips below its neighbour on 500 samples is noise, and a ladder that steps backwards is worse than no ladder.
-
-Refit it with `node scripts/oracle-calibrate.mjs --write`. It reads the production database when `DATABASE_URL` is set and the live `/api/oracle/backtest` endpoint otherwise (the endpoint runs the same aggregation server-side), then prints the rungs the data can actually tell apart so the tier boundaries can be checked against them. Both numbers are real and they answer different questions; the rule is that any surface showing one has to say which one it is showing.
+Since v3 it comes from the active model's own holdout reliability curve, shipped with the weights (`holdout.win.reliability` in the model document): `hitRateFor(score)` converts the score back to the probability it claims, finds the reliability band that probability falls in (the bands follow the tier anchors, `0.45-1` for Prime and so on), and returns that band's observed rate, its sample size, and the holdout base rate. Reading the model's own holdout rather than a separate hand-generated file means the published rate is always the one that exact model earned on launches it had never seen, and it can never drift out of sync with the weights. The earlier `api/_lib/oracle/conviction-calibration.json` (an isotonic fit of realized production win rates per 10-point band, built on the SOL-price-dependent rug flag) is no longer read by the engine; `scripts/oracle-calibrate.mjs` still fits and prints those production rungs for checking tier boundaries against realized outcomes. Both numbers are real and they answer different questions; the rule is that any surface showing one has to say which one it is showing.
## Anatomy of a score
@@ -74040,12 +77298,12 @@ A score you cannot audit is an opinion. Oracle grades itself in public, and the
**Outcome grading.** Once the data brain labels a coin's ground truth (graduated, rugged, ATH multiple), every agent action on that coin is settled: did the conviction call pay off, what was the peak multiple, what was the realized PnL. A scored coin is a win if it graduated, or reached a 2 times or greater ATH multiple without rugging and without marking below half of entry; a loss if it rugged, marked below 0.5 times, or peaked below 1.2 times — loss conditions outrank a peak-based win, because a 2× wick on a position that then went to zero was exit liquidity, not a win; flat in between. Realized PnL is marked to market as `size · (current_mc / entry_mc − 1)`. This turns the action ledger into an honest win-rate record.
-**Two questions, never conflated.** Grading has to say which question it answers, because there are two and they have different answers. The **trained event** (`PREDICTED_EVENT` in `api/_lib/oracle/conviction.js`, id `spike_or_graduate`) is what the model was fitted on and what the score claims: the coin graduates, or peaks at 3x or more above its market cap at first sight. A later collapse does not undo a hit; conviction ranks the odds of a run, not the odds of a safe hold. The **holder-honest win** is the stricter, rug-aware definition in the paragraph above, and it is the right number for someone actually holding. Every surface that shows a realized rate now states which of the two it is, and the backtest ships both side by side. Presenting one as the other is what made a working engine read as a broken one.
+**Two questions, never conflated.** Grading has to say which question it answers, because there are two and they have different answers. The **trained event** (`PREDICTED_EVENT` in `api/_lib/oracle/conviction.js`) is what the score head was fitted on and what the score claims. Under v3 that is id `runs_and_holds`: the coin graduates or peaks at 3x or more, AND is still worth at least what it cost at first sight, so a coin that spiked 3x and then collapsed is not a hit. (A v2 document scores on id `spike_or_graduate`, where a later collapse does not undo a hit; the engine normalises either model shape and reports which event it is predicting.) The **holder-honest win** is the rug-aware definition in the paragraph above, judged on realized production outcomes rather than the training label, and it is the right number for someone actually holding. Every surface that shows a realized rate now states which of the two it is, and the backtest ships both side by side. Presenting one as the other is what made a working engine read as a broken one.
**The backtest** at `/api/oracle/backtest` joins what the engine scored against what actually happened and returns hit-rate stats per tier. Only coins with a resolved outcome count; open positions are excluded. This is the honest answer to "does it actually work," updated continuously. It publishes:
- **Win rate by tier**, with a 95 percent Wilson confidence interval, for both definitions (`ci` on the holder-honest win, `spike_ci` on the trained event).
-- **A calibration ladder** in bands of 10. The band's `predicted` is the sample-weighted mean of the probability each score in it actually claims, computed with `probabilityFromScore()`. This matters: the 0-100 score line is **not** a percentage (86 claims P=0.55, 34 claims P=0.05), and every table we shipped before 2026-08-14 read `score/100` as the claim, overstating the engine's own confidence by up to 4x and making a calibrated ranking look wildly overconfident. Bands are assembled from a per-score aggregate rather than a band midpoint, so the claim tracks where the coins actually sit.
+- **A calibration ladder** in bands of 10. The band's `predicted` is the sample-weighted mean of the probability each score in it actually claims, computed with `probabilityFromScore()`. This matters: the 0-100 score line is **not** a percentage (86 claims P=0.45, 34 claims P=0.05), and every table we shipped before 2026-08-14 read `score/100` as the claim, overstating the engine's own confidence by up to 4x and making a calibrated ranking look wildly overconfident. Bands are assembled from a per-score aggregate rather than a band midpoint, so the claim tracks where the coins actually sit.
- **A Brier score** (`brier_of` names the event, the trained one), computed per exact score against its own claimed probability rather than against a band midpoint, so it is exact. Lower is better; 0.25 is a coin flip.
- **The edge multiple**, prime's rate over the base rate, and a monotonicity check. The ladder check counts an inversion only when two bands' 95 percent intervals are **disjoint**: a visible dip inside overlapping intervals is sampling noise, and the previous check both tolerated real inversions and reported `monotonic: true` over them.
@@ -74053,7 +77311,7 @@ During a database outage the endpoint answers `503` rather than an empty record,
That rule is the whole Oracle read surface, not one endpoint. `/api/oracle/feed`, `/categories`, `/agent-stats`, `/follow`, `/movers`, `/signal`, `/stats`, `/history`, and the `/social` ingest all separate a connectivity failure from an ordinary SQL fault: the first propagates as `503` with a `Retry-After` and is never cached, the second still degrades to the documented empty answer. The distinction matters because these responses get CDN-cached for 60 to 120 seconds, so a blip lasting seconds used to pin "nothing is moving", "nobody is armed", or "no plays right now" on the product for minutes after the database recovered. `/api/oracle/og` follows the same rule in its own shape: a card built from a failed read still renders (a social scraper needs an image back), but it is served `no-store` so the next scrape re-reads a recovered database instead of caching "Not yet scored" on a Prime coin for 15 minutes. The contract is pinned in `tests/oracle/api-db-outage.test.js`.
-**The realized-hit-rate calibration.** The fitted model answers "what fraction of launches like this one spike or graduate". A user reading a card wants "of the coins Oracle already scored at 99, how many actually won". Nothing reconciled those two, so a card reading conviction 99 quoted a training-label probability above 95 percent for a band that realized 26 percent. `scripts/oracle-calibrate.mjs` closes the gap: it measures the realized rug-aware win rate per score band over resolved production coins, smooths it into a monotone ladder with pool-adjacent-violators (isotonic regression), and writes `api/_lib/oracle/conviction-calibration.json`. `hitRateFor()` then serves that realized rate next to every score, and the public tier boundaries sit on the plateaus this fit exposes. Run it bare to fit and report, `--write` to update the shipped JSON. It reads the production database when `DATABASE_URL` is set and otherwise the live `/api/oracle/backtest`, which runs the same aggregation server-side, so neither path invents a number.
+**The realized-hit-rate calibration.** The fitted model answers "what fraction of launches like this one spike or graduate". A user reading a card wants "of the coins Oracle already scored at 99, how many actually won". Nothing reconciled those two, so a card reading conviction 99 quoted a training-label probability above 95 percent for a band that realized 26 percent. `scripts/oracle-calibrate.mjs` measures that: the realized rug-aware win rate per score band over resolved production coins, smoothed into a monotone ladder with pool-adjacent-violators (isotonic regression) and written to `api/_lib/oracle/conviction-calibration.json`, so the public tier boundaries can be checked against the plateaus it exposes. Since v3 the rate printed next to every score (`hitRateFor()`) comes from the active model's own holdout instead of that file, because the file's win definition was built on the SOL-price-dependent rug flag. Run the script bare to fit and report, `--write` to update the JSON. It reads the production database when `DATABASE_URL` is set and otherwise the live `/api/oracle/backtest`, which runs the same aggregation server-side, so neither path invents a number.
**A third question: what the fleet actually banked.** `/api/cron/oracle-calibrate` (Cloud Scheduler) joins conviction to the fleet's *realized PnL* on mints it really traded, buckets by conviction band, and writes `oracle_calibration`. A win here is a positive realized PnL on a real fill, which is neither the trained event nor the site's rug-aware win: exit timing belongs to the fleet, so a gap between this table and `/api/oracle/backtest` is expected rather than a bug. Each band carries a bounded `correction_factor` (observed over claimed, clamped to 0.7-1.3, and pinned at 1.0 until the band has enough real trades). That factor is deliberately **not** written back onto the canonical `oracle_conviction` score: the calibration is measured against that score, so mutating it would feed into its own measurement and oscillate. It is exposed at `GET /api/oracle/calibration` and applied where it belongs, in the sniper optimizer's Rule O, which tunes each arm's entry threshold toward the band that realized wins.
@@ -74081,7 +77339,7 @@ This is where the engine earns its keep. One score, many consumers.
**The coin pages.** Every Oracle coin page (`/oracle/coin/<mint>`) renders in the markets-hub design, the same editorial system as `/coin/bitcoin`: breadcrumbs, a coin header with the live price and 24h/7d change chips, a conviction card with the score dial and four pillar bars, and stacked full-width sections. It fuses conviction with a live market intel aggregator that fans out to six real sources in parallel: DexScreener, the pump.fun API, GeckoTerminal, GoPlus, Birdeye, and CoinGecko. Price, liquidity, FDV, bonding curve progress, holder count, top ten concentration, mint and freeze authority, all in one view, every number traced to a live upstream. Each source is isolated, so one being down degrades that slice to null instead of failing the page. A Launch Intelligence section brings the Coin Radar engine's first-90-seconds read onto the same page: quality score, organic versus bundle, risk flags, the full signal breakdown, smart-money buyers, and the top-trader ledger. It also shows the who-is-in breakdown: every early wallet labeled by archetype and track record. That trader-classification surface is what the product is built around. The price chart keeps the TradingView-grade DexScreener candles embed alongside a native line view and an agent-trades view that plots every three.ws agent buy and sell on the series.
-**What the verdict card says out loud.** A big dial reading 100 next to a chart that already collapsed is not a wrong score, it is an unlabelled one, so the conviction card carries two lines the dial cannot say by itself. Directly under the score, the odds line quotes the band's realized rug-aware rate instead of the score: "26% of calls in the 90-100 band have won (n=792), 4.8x the 5% a random launch wins", followed by when the call was made relative to the coin first surfacing ("Scored 54s after this coin surfaced") and the one sentence that resolves the whole confusion, that the score ranks the odds of a 3x run or graduation and not the odds of a safe hold. Below it, once the market has resolved the coin, a **Since the call** strip states the ground truth in the order a holder reads it: peak multiple, whether it graduated or rugged, and what it is worth now ("peak 6.7x · rugged · now $2.2K"). Both lines are rendered server-side in `api/oracle-share.js` and refilled by `public/oracle-coin.js`, so a link pasted into a chat shows them in the preview rather than a bare triumphant number; the share description carries the same clause ("since: ran 6.7x, then rugged"). The drawer's one-line take leads with the result for the same reason: "It ran to 6.7x and then rugged." before it repeats what Oracle called. On the feed at `/oracle`, each card carries the compact version of that strip as an outcome chip next to its odds chip, so a resolved coin never sits in the board looking like a live call.
+**What the verdict card says out loud.** A big dial reading 100 next to a chart that already collapsed is not a wrong score, it is an unlabelled one, so the conviction card carries two lines the dial cannot say by itself. Directly under the score, the odds line quotes the measured rate behind the score instead of the score itself, from `hitRateFor()`: "48% of calls in the 0.45-1 band have won (n=267), 15.0x the 3% a random launch wins" (the band is the probability band the score claims, and the rate is what the active model's holdout observed there), followed by when the call was made relative to the coin first surfacing ("Scored 54s after this coin surfaced") and the one sentence that resolves the whole confusion, that the score ranks the odds of a 3x run or graduation and not the odds of a safe hold. Below it, once the market has resolved the coin, a **Since the call** strip states the ground truth in the order a holder reads it: peak multiple, whether it graduated or rugged, and what it is worth now ("peak 6.7x · rugged · now $2.2K"). Both lines are rendered server-side in `api/oracle-share.js` (a GET-only surface; when pump.fun does not answer, the coin's identity, symbol, name, image, market cap and graduation state, comes from DexScreener's pair listing so the card still names the coin) and refilled by `public/oracle-coin.js`, so a link pasted into a chat shows them in the preview rather than a bare triumphant number; the share description carries the same clause ("since: ran 6.7x, then rugged"). The drawer's one-line take leads with the result for the same reason: "It ran to 6.7x and then rugged." before it repeats what Oracle called. On the feed at `/oracle`, each card carries the compact version of that strip as an outcome chip next to its odds chip, so a resolved coin never sits in the board looking like a live call.
## The x402 layer: intel with a price tag
@@ -74165,7 +77423,7 @@ GET https://three.ws/api/oracle/trades?mint=<mint>
- Score time series at `/api/oracle/history`, biggest conviction moves at `/api/oracle/movers`, accuracy stats at `/api/oracle/backtest`, proven calls at `/api/oracle/wins`, agent rankings at `/api/oracle/leaderboard`.
- Global KPIs, per-category intel, symbol search, a single agent's record, and the global action feed at `/api/oracle/stats`, `/categories`, `/search`, `/agent-stats`, and `/activity`.
- Realized calibration per conviction band at `/api/oracle/calibration`: the fleet's actual win rate from real fills, next to what the band predicted, plus the bounded correction factor the scorer applies.
-- A dynamic 1200x630 OpenGraph conviction card (SVG) for sharing a coin at `/api/oracle/og`.
+- A dynamic 1200x630 OpenGraph conviction card (SVG) for sharing a coin at `/api/oracle/og`. Its live market cap reads pump.fun first (with one retry, honouring `Retry-After`) and falls through to the shared multi-source market reader (Birdeye, DexScreener, GeckoTerminal) when pump.fun does not answer.
The write endpoints. Two are auth-scoped to the agent's owner: `GET·POST /api/oracle/watch` reads or arms an agent's watch config with server-side validation clamping every limit, and `POST /api/oracle/test-alert` sends a test alert. The clamps only ever move a number toward safety: a size above the ceiling is lowered, but arming `mode: "live"` with a `per_trade_sol` under the 0.001 SOL floor, or a `max_daily_sol` smaller than one trade, is a 400 rather than a silent round-up into real spending. Simulate runs keep the forgiving clamps. Two are public and IP rate-limited instead: `POST·DELETE /api/oracle/follow` subscribes a Telegram chat to an agent's signals (the chat id the caller supplies is the identity, so there is no session to scope to), and `POST /api/oracle/social` ingests tweets to additively boost virality (never downgrades an LLM read).
@@ -74205,16 +77463,16 @@ Every coin watched sharpens the priors. Every graded outcome tunes the calibrati
## PhD appendix: Oracle as a calibrated scoring classifier
-Let a launch be a feature vector `x`. Since v2 (2026-08-09), Oracle is a bucketed logistic model: each feature `j` is discretized by fixed empirical bin edges into a one-hot `b_j(x)`, each bin carries a fitted weight `w_{j,b}`, and
+Let a launch be a feature vector `x`. Since v2 (2026-08-09), Oracle is a bucketed logistic model: each feature `j` is discretized by fixed empirical bin edges into a one-hot `b_j(x)`, and since v3 (2026-08-28) each bin carries one fitted weight `w^h_{j,b}` per head `h ∈ {win, rug, moon}` over the same design matrix:
```
-z(x) = w_0 + Σ_j w_{j, b_j(x)} + o(x) # o(x): the smart-money overlay (documented priors)
-p(x) = σ(z(x)) = 1 / (1 + e^(−z(x))) # calibrated P(good | x)
-s(x) = min( m(p(x)), c(x) ) # m: fixed monotone piecewise-linear map to [0,100]
- # c: 45 iff serial-rugger creator, else 100
+z_h(x) = w^h_0 + Σ_j w^h_{j, b_j(x)} + o(x) # o(x): expert priors the model cannot fit
+p_h(x) = σ(z_h(x)) = 1 / (1 + e^(−z_h(x))) # calibrated P(h | x)
+s(x) = min( m(p_win(x)), c(x) ) # m: fixed monotone piecewise-linear map to [0,100]
+ # c: 45 iff serial-rugger creator, else 100
```
-with `good = graduated ∨ ATH ≥ 3×`, fitted by SGD on the labeled outcome set (L2-regularized, deterministic seed, time-ordered rows; `scripts/oracle-fit.mjs`). `m` is anchored so the public tier boundaries land on fixed probabilities (34 ↦ 0.05, 56 ↦ 0.12, 72 ↦ 0.30, 86 ↦ 0.55). Evaluation is a strict temporal split: train on the oldest 75 percent, report AUC, precision-at-depth, and per-band reliability on the newest 25 percent. Calibration measures the gap between `p(x)` and reality out of sample.
+with `hold = ATH_multiple × (last_mc / ath_mc)` (both dollar figures from one reading, so the SOL price cancels), `moon = graduated ∨ ATH ≥ 3×`, `rug = ¬graduated ∧ hold ≤ 0.5`, `win = moon ∧ hold ≥ 1`, fitted by SGD on the labeled outcome set (L2-regularized, deterministic seed, time-ordered rows, label rule version 2 only; `api/_lib/oracle/fit.js`, shared by `scripts/oracle-fit.mjs` and the refit cron). Each fitted weight is then shrunk toward zero by `n / (n + 200)`, `n` being the rows behind its bucket, so a 34-row bucket cannot reverse a verdict on its own. `m` is anchored so the public tier boundaries land on fixed probabilities of `win` (34 ↦ 0.05, 56 ↦ 0.12, 72 ↦ 0.25, 86 ↦ 0.45). Evaluation is a strict temporal split: train on the oldest 75 percent, report AUC, precision-at-depth, and per-band reliability on the newest 25 percent, for every head. Calibration measures the gap between `p(x)` and reality out of sample.
The calibration objects:
@@ -74223,7 +77481,7 @@ The calibration objects:
- **Wilson interval**: for `w` wins in `n` resolved coins, the 95 percent Wilson score interval (z = 1.96, z² = 3.8416) is `centre = (p + z²/2n) / (1 + z²/n)` and `margin = z·√((p(1−p) + z²/4n) / n) / (1 + z²/n)` with `p = w/n`. Unlike the normal approximation `p ± z·√(p(1−p)/n)`, it stays inside [0,1], doesn't collapse to zero width at p=0 or p=1, and behaves correctly for the small `n` that young backtests have. It is the difference between an honest "we don't know yet" and a dishonest "0 percent ± 0 percent."
- **Monotonicity and edge**: require `ŷ` non-decreasing in the score bin (within tolerance); define edge multiple `= P(win | prime) / P(win | any)` and lift as the difference, both reported with their CIs.
-The improvement path, formally. v2 delivered the first two upgrades the v1 appendix promised: the weights are now fitted by maximizing regularized log-likelihood on resolved outcomes, and the published score is a fixed monotone map of a calibrated probability. What remains open, in order of expected value: (1) refit cadence, ideally automated once the labeled set's growth is stable, with a champion/challenger holdout gate so a refit never silently regresses; (2) interaction terms or shallow trees over the same buckets, since the current model is additive and the strongest observed patterns (concentration crossed with buyer count) are plausibly interactive; (3) fitting the smart-money overlay once the widened proven-wallet ledger accumulates enough judged appearances; (4) survival-style labels (time-to-rug) instead of the binary good, so the engine can price exit windows and not just entries.
+The improvement path, formally. v2 delivered the first two upgrades the v1 appendix promised: the weights are fitted by maximizing regularized log-likelihood on resolved outcomes, and the published score is a fixed monotone map of a calibrated probability. v3 delivered two more: an automated refit (`/api/cron/oracle-refit`) behind a champion/challenger holdout gate (a candidate ships only if every epoch ran, the scoring head's AUC is at least 0.70 and beats the incumbent by at least 0.004, no other head fell by more than 0.01, no more than three features were lost, and every populated band still earns 70 percent of what it claims; refused candidates are kept in `oracle_model_versions` with the reason), and the smart-money evidence fitted as a feature instead of an overlay. What remains open, in order of expected value: (1) interaction terms or shallow trees over the same buckets, since the model is additive and the strongest observed patterns (concentration crossed with buyer count) are plausibly interactive; (2) survival-style labels (time-to-rug) instead of the binary heads, so the engine can price exit windows and not just entries.
References and further reading. Wilson (1927), *Probable inference, the law of succession, and statistical inference*. Brier (1950), *Verification of forecasts expressed in terms of probability*. Platt (1999), probabilistic outputs for SVMs (Platt scaling). Zadrozny and Elkan (2002), isotonic calibration. Niculescu-Mizil and Caruana (2005), *Predicting good probabilities with supervised learning*.
@@ -74248,7 +77506,7 @@ The more data we watch, the sharper every score. Oracle is live now.
---
-<a id="sec-327"></a>
+<a id="sec-339"></a>
> **Source:** `docs/overlay-audit.md` · [↑ table of contents](#table-of-contents)
@@ -74415,11 +77673,11 @@ only worth calling from a test.
- [`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
+- `npm run snapshot`: the daily full-page visual record of every public route (`--authed` replays the `audit:web:login` session and widens it to the signed-in pages, writing to `reports/ui-shots/` instead of `snapshots/`)
---
-<a id="sec-328"></a>
+<a id="sec-340"></a>
> **Source:** `docs/package-extraction.md` · [↑ table of contents](#table-of-contents)
@@ -74548,7 +77806,7 @@ part of the extraction itself: extract and publish first, swap the import later.
---
-<a id="sec-329"></a>
+<a id="sec-341"></a>
> **Source:** `docs/partners.md` · [↑ table of contents](#table-of-contents)
@@ -74556,7 +77814,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-345).
+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-358).
**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.
@@ -74566,14 +77824,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-281), [3D Studio (paid)](#sec-278), [Custom GPT config](#sec-138), [AR in ChatGPT](#sec-139), [Spatial MCP](#sec-407) |
-| IBM | Strategic | `/blog/three-ws-ibm-business-partner` | [IBM watsonx and Granite](#sec-253), [IBM Granite x402 MCP](#sec-252) |
-| Amazon Web Services | Cloud | `/aws` | [AWS Marketplace](#sec-123), [listing kit](#sec-122), [partner spotlight](#sec-124) |
+| OpenAI | Select Partner | `/openai` | [MCP 3D Studio (free)](#sec-290), [3D Studio (paid)](#sec-287), [Custom GPT config](#sec-141), [AR in ChatGPT](#sec-142), [Spatial MCP](#sec-425) |
+| IBM | Strategic | `/blog/three-ws-ibm-business-partner` | [IBM watsonx and Granite](#sec-263), [IBM Granite x402 MCP](#sec-262) |
+| Amazon Web Services | Cloud | `/aws` | [AWS Marketplace](#sec-125), [listing kit](#sec-124), [partner spotlight](#sec-126) |
| 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-269), [the model router](#sec-130) |
-| NVIDIA | Inception | `/nvidia` | [NVIDIA Inception](#sec-303), [NVIDIA models](#sec-304), [Nemotron spotlight](#sec-306) |
-| HackerNoon | Media | `/blog/three-ws-hackernoon-partnership` | [Syndication](#sec-414), [Listings and distribution](#sec-269) |
-| Quicknode | Infrastructure | `/blog/three-ws-quicknode-startup-program` | [Solana integration](#sec-406), [Listings and distribution](#sec-269) |
+| Alibaba Cloud | Cloud | `/blog/three-ws-alibaba-cloud-partnership` | [Listings and distribution](#sec-281), [the model router](#sec-132) |
+| NVIDIA | Inception | `/nvidia` | [NVIDIA Inception](#sec-314), [NVIDIA models](#sec-315), [Nemotron spotlight](#sec-317) |
+| HackerNoon | Media | `/blog/three-ws-hackernoon-partnership` | [Syndication](#sec-432), [Listings and distribution](#sec-281) |
+| Quicknode | Infrastructure | `/blog/three-ws-quicknode-startup-program` | [Solana integration](#sec-424), [Listings and distribution](#sec-281) |
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.
@@ -74585,13 +77843,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-281).
-- **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-278).
-- **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-407).
+- **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-290).
+- **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-287).
+- **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-141).
+- **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-142).
+- **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-425).
-**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-345). The pre-submission verification pack is [`docs/openai-pr/00-START-HERE.md`](#sec-317).
+**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-358). The pre-submission verification pack is [`docs/openai-pr/00-START-HERE.md`](#sec-328).
---
@@ -74599,9 +77857,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-253). [IBM Granite x402 MCP](#sec-252) 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-263). [IBM Granite x402 MCP](#sec-262) 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-253) 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-263) 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).
@@ -74611,16 +77869,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-123).
+**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-125).
**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-269) 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.
+- [`docs/listings.md`](#sec-281) records AWS Marketplace as Live and three.ws as an AWS Partner.
+- [`docs/aws-marketplace-listing-kit.md`](#sec-124) 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-124), [MCP agents](#sec-120), and [Marketplace metering in front of x402](#sec-119).
+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-126), [MCP agents](#sec-122), and [Marketplace metering in front of x402](#sec-121).
---
@@ -74630,7 +77888,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-269) 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-281) 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.
---
@@ -74638,9 +77896,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-130) 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-132) for the router and the model ids.
-**Listing status.** [`docs/listings.md`](#sec-269) 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-281) 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.
---
@@ -74650,10 +77908,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-303) 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-304) 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-314) 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-315) 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-306) 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-317) is a published community piece on building the text-to-3D pipeline on NIM. It is a developer-blog showcase, not a partnership document.
---
@@ -74661,15 +77919,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-414); the listing row is in [Listings and distribution](#sec-269).
+**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-432); the listing row is in [Listings and distribution](#sec-281).
---
## 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-269) 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-281) 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-406) 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-424) 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.
---
@@ -74677,7 +77935,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-269) 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-278)) are technical dependencies, not partnerships.
+- **No Intel, Microsoft, or Oracle programme appears on `/partners`.** [`docs/listings.md`](#sec-281) 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-287)) 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.
@@ -74691,14 +77949,14 @@ The page closes with four reasons, useful as the short pitch when someone asks:
## Related
-- [Press kit](#sec-345): marks, announcement graphics, boilerplate, and the rules for all of it
-- [Listings and distribution](#sec-269): marketplaces, ecosystem directories, and media partners with per-listing status
-- [Integrations](#sec-257): the catalog of ways to put an agent on a site you do not control
-- [x402](#sec-563): the payment rail behind the agent-to-agent micropayments every partner surface references
+- [Press kit](#sec-358): marks, announcement graphics, boilerplate, and the rules for all of it
+- [Listings and distribution](#sec-281): marketplaces, ecosystem directories, and media partners with per-listing status
+- [Integrations](#sec-267): the catalog of ways to put an agent on a site you do not control
+- [x402](#sec-589): the payment rail behind the agent-to-agent micropayments every partner surface references
---
-<a id="sec-330"></a>
+<a id="sec-342"></a>
> **Source:** `docs/partners/sperax-proposal.md` · [↑ table of contents](#table-of-contents)
@@ -74746,7 +78004,7 @@ Both sides already ship for a living — this proposal only asks each of us to d
---
-<a id="sec-331"></a>
+<a id="sec-343"></a>
> **Source:** `docs/pay-skills-listing.md` · [↑ table of contents](#table-of-contents)
@@ -74756,7 +78014,7 @@ Both sides already ship for a living — this proposal only asks each of us to d
**Discovery:** https://three.ws/.well-known/x402.json
**OpenAPI:** https://three.ws/openapi.json
**MCP:** https://three.ws/api/mcp
-**Networks:** Base mainnet (USDC), Arbitrum One (USDC, model-check + mint-to-mesh only), Solana mainnet (USDC)
+**Networks:** Solana mainnet (USDC, leads every accepts list), Base mainnet (USDC), Arbitrum One (USDC, model-check only)
**Protocol:** x402 v2 (HTTP 402 Payment Required)
## Overview
@@ -74764,7 +78022,9 @@ Both sides already ship for a living — this proposal only asks each of us to d
three.ws is an agent-first 3D model platform. Paid REST endpoints cover glTF/GLB model
validation, Solana token visualization, Pump.fun agent analytics, on-chain identity
verification, and a Claude-backed growth-analysis power. All endpoints settle in USDC
-on Base / Arbitrum / Solana mainnet. The MCP server exposes the same surface as
+on Solana mainnet, with Base (and Arbitrum for model-check) as the alternative EVM
+rails; Solana is the first accept in every 402 challenge, so a client that takes
+the first accept settles there. The MCP server exposes the same surface as
JSON-RPC tools.
## Paid Endpoints
@@ -74777,7 +78037,7 @@ are the source of truth and match what the 402 challenges advertise; verify with
|---|---|---|---|
| `/api/mcp` | POST | $0.001 | MCP 2025-06-18 Streamable HTTP — 3D model tools + Solana agent data as JSON-RPC 2.0 |
| `/api/x402/model-check` | GET | $0.001 | Fetch a glTF/GLB from a URL, return vertex/triangle counts, materials, textures, animations, extensions, and optimization hints. CDP-Bazaar-cataloged. |
-| `/api/x402/mint-to-mesh` | GET | $0.001 | Pass a Solana SPL mint, get a binary glTF (GLB) cube themed for that token (color + texture derived from on-chain metadata). CDP-Bazaar-cataloged. |
+| `/api/x402/mint-to-mesh` | GET | $0.001 | Pass a Solana SPL mint, get a binary glTF (GLB) cube themed for that token (color + texture derived from on-chain metadata: the Token-2022 metadata extension when the mint carries one, else the Metaplex PDA). CDP-Bazaar-cataloged. |
| `/api/x402/symbol-availability` | GET | $0.001 | Pre-launch ticker collision check against three.ws's pump.fun mint index; returns exact and trigram-similar matches |
| `/api/x402/skill-marketplace` | GET | $0.001 | List active skill listings and prices across all three.ws agents; filter by skill name to find the cheapest provider |
| `/api/x402/permit2-paid-demo` | GET | $0.001 | Permit2 + EIP-2612 gas-sponsoring demo (Base only). Forces the gasless Permit2 path for fresh wallets holding USDC but zero ETH. Listed only when CDP credentials are configured. |
@@ -74847,7 +78107,7 @@ are supported.
---
-<a id="sec-332"></a>
+<a id="sec-344"></a>
> **Source:** `docs/payment-sessions.md` · [↑ table of contents](#table-of-contents)
@@ -74949,7 +78209,7 @@ curl -s https://three.ws/api/credits \
```
`holder` is the $THREE tier every debit on this account is already priced at:
-the same shape [`GET /api/pricing`](#sec-096) returns. `discount_bps`
+the same shape [`GET /api/pricing`](#sec-098) returns. `discount_bps`
is the discount applied to each spend (1000 = 10% off), `usd_held` is the USD
value of the $THREE held by the linked wallet, and `next_tier` / `usd_to_next`
say how much more $THREE reaches the next rung (`next_tier` is `null` at the
@@ -75315,13 +78575,13 @@ curl -s $BASE/api/credits -H "$AUTH" | jq .balance_usd
## Related
-- [x402 Protocol](#sec-563): the challenge / verify / settle mechanics behind every paid call.
-- [x402 Buyer Client](#sec-556): paying x402 endpoints from your own wallet instead of a session.
-- [x402 Developer Tools](#sec-557): free echo / debug / receipt-verification tools for debugging a paid call.
+- [x402 Protocol](#sec-589): the challenge / verify / settle mechanics behind every paid call.
+- [x402 Buyer Client](#sec-581): paying x402 endpoints from your own wallet instead of a session.
+- [x402 Developer Tools](#sec-582): free echo / debug / receipt-verification tools for debugging a paid call.
---
-<a id="sec-333"></a>
+<a id="sec-345"></a>
> **Source:** `docs/permissions.md` · [↑ table of contents](#table-of-contents)
@@ -75717,17 +78977,17 @@ Set `SMOKE_SKIP_REVOKE=1` to skip the on-chain revocation step if the test walle
## See also
-- [Architecture Overview](#sec-100)
-- [Agent System](#sec-064)
-- [ERC-8004 Blockchain Identity](#sec-189)
-- [Skill System](#sec-399)
+- [Architecture Overview](#sec-102)
+- [Agent System](#sec-065)
+- [ERC-8004 Blockchain Identity](#sec-195)
+- [Skill System](#sec-417)
- [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-334"></a>
+<a id="sec-346"></a>
> **Source:** `docs/persona-hub.md` · [↑ table of contents](#table-of-contents)
@@ -76124,7 +79384,7 @@ JWT claims:
---
-<a id="sec-335"></a>
+<a id="sec-347"></a>
> **Source:** `docs/pill-mascot.md` · [↑ table of contents](#table-of-contents)
@@ -76138,7 +79398,7 @@ The interesting part is not the result, it is why the normal path did not work a
**On this page:** [Why auto-rigging failed](#why-the-normal-path-failed) · [The pipeline](#the-pipeline) · [Running it](#running-it) · [What ships](#what-ships) · [Reusing it](#reusing-it-on-your-own-character)
-Related: [the avatar pipeline](#sec-113) covers the normal humanoid path (generate, auto-rig, skin, animate). [Rig Doctor](#sec-381) tells you whether a finished `.glb` will actually animate here. [The 3D asset pipeline](#sec-002) covers FBX and GLB conversion upstream of all of it.
+Related: [the avatar pipeline](#sec-115) covers the normal humanoid path (generate, auto-rig, skin, animate). [Rig Doctor](#sec-395) tells you whether a finished `.glb` will actually animate here. [The 3D asset pipeline](#sec-002) covers FBX and GLB conversion upstream of all of it.
---
@@ -76267,11 +79527,11 @@ Finger chains are part of that. Thirty of the 53 tracks in every baked clip addr
- **A sealed surface.** Small holes are closed automatically before the flood fill; a hole you could see through is refused rather than guessed at.
- **A visible face.** Forward is read from dark pixels on the head. A character with no painted face falls back to +Z.
-If your character is genuinely humanoid, do not use this. Use the [standard auto-rigger](#sec-113), which is a one-call API and better at humanoids than this script will ever be.
+If your character is genuinely humanoid, do not use this. Use the [standard auto-rigger](#sec-115), which is a one-call API and better at humanoids than this script will ever be.
---
-<a id="sec-336"></a>
+<a id="sec-348"></a>
> **Source:** `docs/plan-checkout.md` · [↑ table of contents](#table-of-contents)
@@ -76287,7 +79547,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-240), 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-249), which derives holder tiers from $THREE you *hold*; the plan checkout is $THREE you *spend*.
---
@@ -76400,7 +79660,7 @@ Plan prices live in [api/payments/_config.js](../api/payments/_config.js) (`PLAN
---
-<a id="sec-337"></a>
+<a id="sec-349"></a>
> **Source:** `docs/play-boot-performance.md` · [↑ table of contents](#table-of-contents)
@@ -76410,7 +79670,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-339), [architecture](#sec-100).
+Related docs: [how /play stays safe, honest, and light](#sec-351), [architecture](#sec-102).
## How to measure before you claim anything
@@ -76503,7 +79763,7 @@ Before shipping anything that touches `/play` boot:
---
-<a id="sec-338"></a>
+<a id="sec-350"></a>
> **Source:** `docs/play-forge-in-world.md` · [↑ table of contents](#table-of-contents)
@@ -76605,12 +79865,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-255): the rest of what you can do inside a `/play` world
+- [In-game economy](#sec-265): 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-339"></a>
+<a id="sec-351"></a>
> **Source:** `docs/play-hardening.md` · [↑ table of contents](#table-of-contents)
@@ -76626,7 +79886,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-255), [architecture](#sec-100), [security](#sec-387).
+Related docs: [in-game economy](#sec-265), [architecture](#sec-102), [security](#sec-401).
---
@@ -76693,7 +79953,7 @@ The app bundle is not on screen yet while the boot loader is up, so the loader h
- `name` is capped at 28 characters and `symbol` at 12, cut on a word boundary.
- Anything unexpected throws into a `catch` that leaves the generic loader exactly as it shipped.
-The art has a designed failure path in both places it appears. In the loader, a monogram sits under the `<img>` and the image only fades in on `load`; an `error` removes the `<img>` and leaves the monogram. In the world, the HUD banner's `.cc-coin-img` does the same against `.cc-coin-mono` ([src/game/coincommunities-ui.js](../src/game/coincommunities-ui.js)). The 3D totem and jumbotron already degraded to text-only on a failed `TextureLoader` fetch. This matters on venue wifi, where the IPFS gateway behind `/api/img` is the single most likely thing to fail while everything else about the world works.
+The art has a designed failure path in both places it appears. In the loader, a monogram sits under the `<img>` and the image only fades in on `load`; an `error` removes the `<img>` and leaves the monogram. In the world, the HUD banner's `.cc-coin-img` does the same against `.cc-coin-mono` ([src/game/coincommunities-ui.js](../src/game/coincommunities-ui.js)). The 3D totem and jumbotron already degraded to text-only on a failed `TextureLoader` fetch. This matters on venue wifi, where the IPFS gateway behind `/api/img` is the single most likely thing to fail while everything else about the world works. A single gateway is also no longer the only try: `uriCandidates()` in [src/ipfs.js](../src/ipfs.js) expands an `ipfs://` source, or a URL that already names one gateway, into one candidate per gateway in preference order, and each fetch is bounded at 8 s, so one rate-limited gateway degrades to the next rather than to the monogram.
The loader also sets a provisional `document.title` from the link and stashes the original in `documentElement.dataset.lobbyTitle`; `_setTabTitle()` in [src/game/coincommunities.js](../src/game/coincommunities.js) replaces it with the resolved coin on entry and restores the stashed original on leave, so the two writers never fight and the localised title is never re-spelled in JS.
@@ -76853,6 +80113,11 @@ npx vitest run tests/play-deeplink-safety.test.js tests/play-deeplink-identity.t
# coin art and GLBs, a dead auth gate, an ad blocker, a total API outage.
npm run audit:play-failures # local dev server
BASE_URL=https://three.ws npm run audit:play-failures
+# A scenario the harness itself broke (a host transport reset, a starved
+# browser) is retried up to ATTEMPTS times (default 4) with a growing backoff
+# and reported NOT RUN if it never runs, never counted as a /play defect; the
+# sweep abandons itself if the origin under test stops answering. Authed
+# scenarios use AUDIT_EMAIL / AUDIT_PASSWORD (see docs/ops/page-audit.md).
# Everything else that touches the surface.
npx vitest run tests/play-gate.test.js tests/play-pass.test.js \
@@ -76876,7 +80141,7 @@ The mobile harness is the one that catches memory regressions. It reports total
---
-<a id="sec-340"></a>
+<a id="sec-352"></a>
> **Source:** `docs/play-live-events.md` · [↑ table of contents](#table-of-contents)
@@ -76947,7 +80212,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-217). |
+| `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-223). |
`id`, `agenda`, and `tagline` are optional: an event with none of them still runs
its countdown, its go-live moment, and its fireworks.
@@ -77046,7 +80311,7 @@ Point it at another origin with `--base https://three.ws`.
---
-<a id="sec-341"></a>
+<a id="sec-353"></a>
> **Source:** `docs/play-vehicles.md` · [↑ table of contents](#table-of-contents)
@@ -77153,12 +80418,12 @@ and the metal-roughness map at 1024px, and writes
## Related
- [`/play` NPCs and world life](../src/game/npc/ambient-life.js) drives the ambient lane.
-- [The in-game economy](#sec-255) covers what you earn on those delivery runs.
-- [`/play` safety and lifecycle invariants](#sec-339).
+- [The in-game economy](#sec-265) covers what you earn on those delivery runs.
+- [`/play` safety and lifecycle invariants](#sec-351).
---
-<a id="sec-342"></a>
+<a id="sec-354"></a>
> **Source:** `docs/popular-3d-github-repos.md` · [↑ table of contents](#table-of-contents)
@@ -77421,7 +80686,136 @@ Apply a 3D-signal regex filter over `description + topics` and a denylist of non
---
-<a id="sec-343"></a>
+<a id="sec-355"></a>
+
+> **Source:** `docs/portal.md` · [↑ table of contents](#table-of-contents)
+
+# Portal: walk any website in 3D
+
+Paste a web address and Portal builds a place out of it. Every section of the page becomes a building sized by what it says, every link becomes a door you step through, every image becomes a billboard, every code block becomes a monolith. You walk it with your own avatar, hand the link to anyone, download the world as a `.glb`, embed it in your own site, or let an agent read the shape of a site over MCP.
+
+Page: [/portal](https://three.ws/portal) · API: `/api/portal` · Package: [`@three-ws/portal`](../packages/portal/README.md) · Spec: [`specs/PORTAL_WORLD.md`](../specs/PORTAL_WORLD.md)
+
+## Why it exists
+
+Every tool that visualizes a website draws a node graph. A graph tells you a site has forty pages. It does not tell you which section carries the weight, where the dead ends are, or what it feels like to arrive. A place does, because size, distance and direction are things people read without being taught.
+
+There is a second reason, and it is the one that matters to this platform: an agent that fetches a page gets a wall of text. Over Portal it gets the page's *shape*, which is small enough to reason about and spatial enough to hand back as somewhere a human can go. That is three.ws's whole thesis applied to the web that already exists.
+
+## Walkthrough
+
+1. Open [/portal](https://three.ws/portal) and type an address (`three.ws`, `en.wikipedia.org/wiki/Three.js`, your own site).
+2. The build panel names each real step: asking the site and its `robots.txt`, reading the structure, laying out districts, rendering.
+3. You arrive on the plaza, in front of an obelisk carrying the page title. Walk with `WASD` or the arrows, hold `Shift` to run, drag to look, and on a phone use the on-screen stick.
+4. Buildings are labelled with their section headings. The taller one said more. The minimap shows the whole city with you in it.
+5. Stand at a door and press `Enter`. A same-site door rebuilds the world at that address and pushes it into your browser history, so `Back` walks back through the sites you visited. An outside link opens the page it points at.
+6. **Copy link** shares the exact world you are standing in. **Embed** copies an iframe snippet. **Download GLB** hands you the whole city as a glTF binary you can open in Blender, drop into Unity, or view in AR.
+
+## How it works
+
+Portal is two documents and one pure function.
+
+**Reading the page** ([`api/_lib/portal/fetch-site.js`](../api/_lib/portal/fetch-site.js), [`outline.js`](../api/_lib/portal/outline.js)). The address is normalized, `robots.txt` is fetched and matched against our token, and the page is read once through the IP-pinned SSRF guard with a 3 MB ceiling and a 12 second deadline. The HTML becomes a `SiteOutline`: the heading spine, the weight of each section (words, paragraphs, code blocks), its links and its images. Chrome (`nav`, `header`, `footer`, `script`) is removed before reading, so a navigation menu never becomes a district full of doors.
+
+**Laying out the world** ([`packages/portal/src/layout.js`](../packages/portal/src/layout.js)). `buildWorld(outline)` is pure: no network, no DOM, no three.js, and no randomness that is not seeded from the page's canonical URL. Sections land on a phyllotaxis spiral so districts never collide, height comes from word count on a log scale so one long essay cannot dwarf a city, and the palette comes from the page's own `theme-color` (or a stable hue hashed from its host). Because it is pure and seeded, the person who opens your link builds the identical city.
+
+**Rendering it** ([`src/portal/render.js`](../src/portal/render.js)). A three.js scene with a gradient sky, a plaza, labelled buildings that fade their signage by distance, doors that brighten as you approach, and your avatar driven by the platform's universal clip library, so the rig walks and idles correctly rather than sliding in the bind pose. Billboards load the page's real images through our own image proxy, because a foreign host with no CORS header would otherwise render a black panel.
+
+**Exporting it** ([`api/_lib/portal/world-glb.js`](../api/_lib/portal/world-glb.js)). The same world document, composed into one glTF binary with `@gltf-transform`: named nodes, instanced geometry, deduplicated materials, two lights, and an `asset.copyright` recording the page the structure came from.
+
+## API
+
+```bash
+# The world, and the outline it was built from
+curl "https://three.ws/api/portal?url=example.com"
+
+# Just one of them
+curl "https://three.ws/api/portal?url=example.com&include=world"
+curl "https://three.ws/api/portal?url=example.com&include=outline"
+
+# The same world as a 3D file
+curl -o example.glb "https://three.ws/api/portal?url=example.com&format=glb"
+```
+
+| Parameter | Values | Default |
+| --- | --- | --- |
+| `url` | any public http(s) address, with or without a scheme | required |
+| `include` | `both`, `world`, `outline` | `both` |
+| `format` | `json`, `glb` | `json` |
+
+The response carries `ok`, `cached`, `stale`, `built_at`, `user_agent`, and whichever documents you asked for. CORS is open, because the SDK runs in other people's pages and every byte is already public on the site it read.
+
+Failures arrive as `{ "error": "<code>", "error_description": "<a sentence you can act on>" }` with codes `invalid_url`, `robots_disallowed`, `blocked_host`, `not_html`, `no_structure`, `too_large`, `unreachable`, `upstream_status`, `rate_limited`.
+
+## SDK
+
+```bash
+npm install @three-ws/portal
+```
+
+```js
+import { fetchWorld, describeWorld, mountPortal } from '@three-ws/portal';
+
+const { world } = await fetchWorld('example.com');
+console.log(describeWorld(world).tallest); // the section that says the most
+
+mountPortal(document.querySelector('#stage'), { url: 'example.com', height: 560 });
+```
+
+The layout is exported on its own for anyone who wants to build worlds from their own data:
+
+```js
+import { buildWorld, collidersFor } from '@three-ws/portal/layout';
+```
+
+Full reference: [`packages/portal/README.md`](../packages/portal/README.md).
+
+## CLI
+
+```bash
+npx @three-ws/portal three.ws # the world, summarized
+npx @three-ws/portal three.ws --glb site.glb # save it as a 3D file
+npx @three-ws/portal three.ws --json world.json # save the world document
+npx @three-ws/portal three.ws --open # print the walkable link
+```
+
+## MCP
+
+```bash
+claude mcp add portal -- npx -y @three-ws/portal portal-mcp
+```
+
+| Tool | Returns |
+| --- | --- |
+| `walk_site` | The world: districts, doors with their targets, billboards, plus a walkable link and a GLB URL |
+| `site_shape` | The heading spine with the weight of each section. The cheap structural read |
+
+## Manners
+
+Portal is a crawler that runs on a visitor's request, and behaves like one. It identifies itself as `ThreeWSPortalBot/1.0 (+https://three.ws/portal)`, reads `robots.txt` before the page and honours a `Disallow` for that token with a clean refusal, fetches each page once (worlds are cached fleet-wide for an hour, so a link shared with a thousand people is one request to the origin), and stays inside a 3 MB, 12 second, SSRF-guarded budget. Rate limits are per address and fleet-wide, and a cached world never touches them.
+
+## Embedding
+
+```html
+<iframe
+ src="https://three.ws/portal?url=example.com&embed=1"
+ width="100%" height="520" style="border:0;border-radius:14px"
+ loading="lazy" title="Walk example.com in 3D"></iframe>
+```
+
+`embed=1` hides the chrome that only makes sense on our own page. The **Embed** button copies this snippet for the world you are standing in.
+
+## Tests
+
+- [`tests/portal-robots.test.js`](../tests/portal-robots.test.js): the RFC 9309 rules, including group specificity, longest-match and the `Allow` tie-break.
+- [`tests/portal-outline.test.js`](../tests/portal-outline.test.js): section attribution, nested prose counted once, chrome dropped, determinism, and the caps that bound a hostile page.
+- [`tests/portal-layout.test.js`](../tests/portal-layout.test.js): determinism, log scaling, non-overlap, doors on walls rather than inside them, and a spawn that is never inside a solid.
+- [`tests/portal-endpoint.test.js`](../tests/portal-endpoint.test.js): the response contract, error mapping, both rate-limit buckets, the GLB export, and the CORS preflight.
+- [`tests/e2e/portal.spec.js`](../tests/e2e/portal.spec.js): a real browser builds a world from a real address and walks it, asserting the avatar actually moved.
+
+---
+
+<a id="sec-356"></a>
> **Source:** `docs/portfolio.md` · [↑ table of contents](#table-of-contents)
@@ -77465,7 +80859,7 @@ GET /api/crypto/portfolio?address=<wallet>&chain=solana|ethereum
```
which builds on the same balance layer as
-[`/api/crypto/wallet`](#sec-170) ([`api/_lib/balances.js`](../api/_lib/balances.js)):
+[`/api/crypto/wallet`](#sec-176) ([`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;
@@ -77524,15 +80918,15 @@ responses are cached for about a minute per wallet.
## Related surfaces
-- [`/wallet`](#sec-503): your own custodial three.ws wallet.
+- [`/wallet`](#sec-523): 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-170): the raw balances endpoint this page
+- [`/api/crypto/wallet`](#sec-176): the raw balances endpoint this page
builds on, for agents and scripts.
---
-<a id="sec-344"></a>
+<a id="sec-357"></a>
> **Source:** `docs/premium.md` · [↑ table of contents](#table-of-contents)
@@ -77667,7 +81061,7 @@ tiers that remain free (news feed, digest, archive stats/trending).
---
-<a id="sec-345"></a>
+<a id="sec-358"></a>
> **Source:** `docs/press-kit.md` · [↑ table of contents](#table-of-contents)
@@ -77822,7 +81216,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-329).
+For the wider programme list and how to describe each one, see [Partner ecosystem](#sec-341).
---
@@ -77840,14 +81234,14 @@ Use that inbox for anything the page does not cover: a format that is not here (
## Related
-- [Partner ecosystem](#sec-329): every programme three.ws is in, at the status it actually claims
-- [Listings and distribution](#sec-269): marketplaces, directories, and media partners, with per-listing status
+- [Partner ecosystem](#sec-341): every programme three.ws is in, at the status it actually claims
+- [Listings and distribution](#sec-281): 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-346"></a>
+<a id="sec-359"></a>
> **Source:** `docs/procedural-animation.md` · [↑ table of contents](#table-of-contents)
@@ -77855,7 +81249,7 @@ Use that inbox for anything the page does not cover: a format that is not here (
Pre-baked clips can only replay motion that was recorded somewhere else. They cannot know where your cursor is, that the ground under an avatar's left foot is 15 cm lower than under its right, or that the agent is supposed to be looking at the person it is talking to. Procedural animation fills that gap: a set of small layers that run **after** the animation mixer each frame and adjust the pose the clip just produced.
-The layers live in [`src/procedural/`](../src/procedural). They are rig-agnostic by the same rule as the rest of the animation stack (see [animations.md](#sec-093) and the universal-rig doctrine in [CLAUDE.md](../CLAUDE.md)): joints are resolved through the canonical bone map, so any humanoid the retargeter can drive, these can drive too. A rig they cannot drive reports `enabled === false` and every method becomes a no-op — never a broken pose.
+The layers live in [`src/procedural/`](../src/procedural). They are rig-agnostic by the same rule as the rest of the animation stack (see [animations.md](#sec-095) and the universal-rig doctrine in [CLAUDE.md](../CLAUDE.md)): joints are resolved through the canonical bone map, so any humanoid the retargeter can drive, these can drive too. A rig they cannot drive reports `enabled === false` and every method becomes a no-op — never a broken pose.
> **This is not the idle layer.** Breathing, blinking, eye saccades, and weight shift already exist in [`src/idle-animation.js`](../src/idle-animation.js) (`IdleAnimation`) and are unchanged. That layer adds ambient life to a *static* avatar. This one reacts to the *world*: a target to look at, a ground to stand on.
@@ -77973,7 +81367,7 @@ Bone lengths are preserved exactly; the solve only ever rotates.
| Surface | Layer | Where |
|---|---|---|
| Corner walk companion | Look-at (cursor gaze) | [`walk-sdk/src/companion.js`](../walk-sdk/src/companion.js) `_updateGaze()` |
-| The walkaround world (`/walk`) | Foot planting on terrain | [`src/walk.js`](../src/walk.js) `rebuildFootPlant()` |
+| The walkaround world (`/walk`) | Foot planting on terrain | [`src/walk.js`](../src/walk.js) `rebuildFootPlant()` (in AR mode the ground callback returns the flat `GROUND_Y`, so the layer stands down) |
| `/walk` NPCs | Look-at (they watch the player) | [`src/walk-npcs.js`](../src/walk-npcs.js) `_updateGaze()` |
| Agent avatars (`AgentAvatar`) | Look-at (`setLookTarget`, `LOOK_AT`) | [`src/agent-avatar.js`](../src/agent-avatar.js) `_applyLookTarget()` |
| `<agent-3d>` web component | Look-at (`lookAt()` public API) | [`src/runtime/scene.js`](../src/runtime/scene.js) `lookAt()` |
@@ -78007,6 +81401,8 @@ The gaze is a **standing state**, not a one-off pose write: it re-applies after
Every NPC watches the player within 14 m — wider than the 4 m greeting range, because noticing someone happens long before greeting them. A wanderer can glance over without breaking stride, since the gaze is an overlay on the walk cycle rather than a replacement for it. Past the clamp the layer releases rather than pinning the head, so an NPC the player has walked behind simply returns to its clip.
+The NPC gaze report (`gazeReport(target)` on the object `createWalkNpcs()` returns) lists each NPC's `dist`, `alignment` (null when the rig exposes no head chain), `tracking` (true while a headed rig is inside the 14 m gaze range), and `headYaw`, which is what the Playwright checks read to prove a gaze actually moved a head.
+
---
## Adding a layer
@@ -78017,13 +81413,13 @@ 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-113) — how avatars are generated and rigged
-- [agent-system.md](#sec-064) — `AgentAvatar`, the protocol, and the emotion layers
+- [animations.md](#sec-095) — the pre-baked clip library these layers run on top of
+- [avatar-pipeline.md](#sec-115) — how avatars are generated and rigged
+- [agent-system.md](#sec-065) — `AgentAvatar`, the protocol, and the emotion layers
---
-<a id="sec-347"></a>
+<a id="sec-360"></a>
> **Source:** `docs/provenance.md` · [↑ table of contents](#table-of-contents)
@@ -78106,7 +81502,7 @@ Real hashing, real ed25519 signature, real on-chain write. Requires the issuer k
---
-<a id="sec-348"></a>
+<a id="sec-361"></a>
> **Source:** `docs/pump-claims-channel.md` · [↑ table of contents](#table-of-contents)
@@ -78210,8 +81606,10 @@ State lives in `app_settings` under `pump_claims_push_telegram`:
Cloud Run request deadline is shorter than a full paced run) resumes at the
next claim instead of repeating delivered ones.
- **A DB lock** (`pump_claims_push_lock`, 240s TTL) stops overlapping ticks from
- double-posting. Every outbound request is bounded well under that TTL, which
- is what keeps the lock's guarantee true.
+ double-posting. Every outbound request is bounded well under that TTL (each
+ Telegram `sendMessage` goes through the shared `fetchUpstream` with a 10 s
+ deadline and at most two attempts), which is what keeps the lock's guarantee
+ true.
- **All message fields are HTML-escaped.** Claim data is third-party on-chain
data; unescaped text could otherwise smuggle a clickable link posted under the
platform bot's identity.
@@ -78263,7 +81661,7 @@ built yet.
---
-<a id="sec-349"></a>
+<a id="sec-362"></a>
> **Source:** `docs/pump-fun-mcp-edge.md` · [↑ table of contents](#table-of-contents)
@@ -78277,30 +81675,38 @@ Mirror of the primary `/api/pump-fun-mcp` endpoint (served by the Cloud Run app
| :--- | :--- |
| `workers/pump-fun-mcp/worker.js` | CF Workers fetch handler implementing the MCP Streamable HTTP transport |
| `workers/pump-fun-mcp/wrangler.toml` | Wrangler config (`name`, `main`, `compatibility_date`) |
+| `workers/pump-fun-mcp/README.md` | Full config table and the verified run, build, and deploy commands |
| `src/pump/mcp-tools.js` | Shared tool registry imported by both the Cloud Run and Workers handlers |
+| `tests/workers/pump-fun-mcp-worker.test.js` | Covers the worker's MCP surface (`npx vitest run tests/workers/pump-fun-mcp-worker.test.js`) |
## Deploy
```sh
cd workers/pump-fun-mcp
-npx wrangler deploy
+npx wrangler@4 deploy
```
+`wrangler` is not a repo dependency, so it is invoked through `npx`.
+
## Secrets
-Set the following with `wrangler secret put <NAME>`:
+Set the following with `npx wrangler@4 secret put <NAME>` (or `--var NAME:VALUE` for a local `wrangler dev` run). Everything is optional:
| Name | Required | Description |
| :--- | :--- | :--- |
-| `SOLANA_RPC_URL` | No | Mainnet RPC endpoint (defaults to public endpoint) |
-| `SOLANA_RPC_URL_DEVNET` | No | Devnet RPC endpoint (defaults to public endpoint) |
+| `SOLANA_RPC_URL` | No | Primary mainnet RPC endpoint (defaults to the public endpoint) |
+| `SOLANA_RPC_FALLBACKS` | No | Comma-separated mainnet failover endpoints, tried in order after the primary (same var name the three.ws deployment uses) |
+| `SOLANA_RPC_URL_DEVNET` | No | Primary devnet RPC endpoint (defaults to the public endpoint) |
+| `SOLANA_RPC_FALLBACKS_DEVNET` | No | Comma-separated devnet failover endpoints |
| `PUMPFUN_BOT_URL` | No | Upstream indexer MCP endpoint; indexer-backed tools return -32004 without it |
| `PUMPFUN_BOT_TOKEN` | No | Bearer token for the indexer endpoint |
+Every on-chain tool walks the configured chain (primary, then each fallback) until one endpoint answers; the public endpoint is used only when nothing is configured, never as a silent downgrade. A tool-level verdict (invalid mint, account genuinely absent) propagates immediately instead of burning the chain, and a provider that is down, rate-limiting, or blocking the egress IP surfaces as `-32004`. `get_token_details` reads name, symbol, and URI from the Token-2022 `TokenMetadata` extension for Token-2022 mints (what pump.fun launches today) and falls back to the legacy Metaplex metadata PDA otherwise.
+
## Local dev
```sh
-npx wrangler dev workers/pump-fun-mcp/worker.js --local
+npx wrangler@4 dev workers/pump-fun-mcp/worker.js --local
# Test tools/list:
curl -s http://localhost:8787 \
-H 'content-type: application/json' \
@@ -78319,7 +81725,7 @@ Both runtimes import `TOOLS` from `src/pump/mcp-tools.js`, so the tool list expo
---
-<a id="sec-350"></a>
+<a id="sec-363"></a>
> **Source:** `docs/pump-launch-repos.md` · [↑ table of contents](#table-of-contents)
@@ -78418,7 +81824,7 @@ rate-limits under the ~450 txs a full run makes. Pass a dedicated `--rpc`
---
-<a id="sec-351"></a>
+<a id="sec-364"></a>
> **Source:** `docs/pump-launcher.md` · [↑ table of contents](#table-of-contents)
@@ -78427,7 +81833,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-563) rail and the platform does the rest:
+[x402](#sec-589) 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**,
@@ -78454,7 +81860,7 @@ current figure — read it, don't hardcode.
## The free → paid funnel
-The paid launch sits between two **free, keyless** [Crypto Data API](#sec-179)
+The paid launch sits between two **free, keyless** [Crypto Data API](#sec-185)
endpoints. Use them to make the launch land well:
1. **Before you launch — check the ticker.**
@@ -78519,7 +81925,7 @@ curl -X POST https://three.ws/api/x402/pump-launch \
curl "https://three.ws/api/crypto/launches"
```
-See [x402 buyer client](#sec-556) for how to satisfy the 402 challenge in
+See [x402 buyer client](#sec-581) for how to satisfy the 402 challenge in
code.
## Output
@@ -78569,16 +81975,16 @@ token itself always deploys on **Solana mainnet** — pump.fun is mainnet-only.
## Related
-- [x402 paid endpoints](#sec-559) — the full catalog and pricing.
-- [Crypto Data API](#sec-179) — the free `symbol` and `launches`
+- [x402 paid endpoints](#sec-584) — the full catalog and pricing.
+- [Crypto Data API](#sec-185) — the free `symbol` and `launches`
endpoints that bookend a launch.
-- [Repo → Coin Launcher](#sec-350) — the batch/CLI launcher that
+- [Repo → Coin Launcher](#sec-363) — the batch/CLI launcher that
routes 100% of creator rewards to a GitHub identity (shares the same engine).
-- [x402 protocol](#sec-563) — challenge/settle mechanics.
+- [x402 protocol](#sec-589) — challenge/settle mechanics.
---
-<a id="sec-352"></a>
+<a id="sec-365"></a>
> **Source:** `docs/pump-platform-fee.md` · [↑ table of contents](#table-of-contents)
@@ -78639,7 +82045,7 @@ The fee is **never** charged silently. When `platform_fee_bps > 0`:
---
-<a id="sec-353"></a>
+<a id="sec-366"></a>
> **Source:** `docs/pumpfun-program/README.md` · [↑ table of contents](#table-of-contents)
@@ -78698,7 +82104,7 @@ tracked in `tasks/pumpfun-upstream/01-v2-trade-instructions-usdc-audit.md`.
---
-<a id="sec-354"></a>
+<a id="sec-367"></a>
> **Source:** `docs/pumpfun-program/UPSTREAM-buy-sell-v2-announcement.md` · [↑ table of contents](#table-of-contents)
@@ -78777,32 +82183,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-360)
-- Coin creation: [docs/instructions/COIN_CREATION.md](#sec-369)
-- Buy: [docs/instructions/BUY.md](#sec-367)
-- Sell: [docs/instructions/SELL.md](#sec-372)
-- Claim cashback: [docs/instructions/CLAIM_CASHBACK.md](#sec-368)
-- Collect creator fee: [docs/instructions/COLLECT_CREATOR_FEE.md](#sec-370)
-- Creator fee sharing: [docs/instructions/CREATOR_FEE_SHARING.md](#sec-371)
+- Fee recipients: [docs/FEE_RECIPIENTS.md](#sec-373)
+- Coin creation: [docs/instructions/COIN_CREATION.md](#sec-382)
+- Buy: [docs/instructions/BUY.md](#sec-380)
+- Sell: [docs/instructions/SELL.md](#sec-385)
+- Claim cashback: [docs/instructions/CLAIM_CASHBACK.md](#sec-381)
+- Collect creator fee: [docs/instructions/COLLECT_CREATOR_FEE.md](#sec-383)
+- Creator fee sharing: [docs/instructions/CREATOR_FEE_SHARING.md](#sec-384)
## Other documentation
-- [Pump Program](#sec-363)
-- [PumpSwap](#sec-365)
-- [PumpSwap SDK](#sec-366)
-- [Pump Program creator fee update](#sec-362)
-- [PumpSwap creator fee update](#sec-364)
-- [FAQ](#sec-358)
-- [Pump fee program docs](#sec-359)
+- [Pump Program](#sec-376)
+- [PumpSwap](#sec-378)
+- [PumpSwap SDK](#sec-379)
+- [Pump Program creator fee update](#sec-375)
+- [PumpSwap creator fee update](#sec-377)
+- [FAQ](#sec-371)
+- [Pump fee program docs](#sec-372)
---
---
-<a id="sec-355"></a>
+<a id="sec-368"></a>
> **Source:** `docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md` · [↑ table of contents](#table-of-contents)
@@ -78983,6 +82389,8 @@ limit).
A `0` returned by any impact helper means "unknown", never "safe".
+An RPC outage is kept distinct from an exhausted pool. When the vault and mint accounts behind a pool cannot be read because the Solana RPC lane is down, `getAmmPoolState` throws a retryable `rpc_unavailable` error (HTTP 503 with a `Retry-After`) instead of a reserve figure, and `api/agents/solana-trade.js` answers `503 rpc_unavailable`; a depth refusal is only ever issued from reserves that were actually read.
+
Regression coverage lives in
[`tests/agent-sniper-amm-exit.test.js`](../tests/agent-sniper-amm-exit.test.js)
and [`tests/pump-swap-quote.test.js`](../tests/pump-swap-quote.test.js): the
@@ -79003,7 +82411,7 @@ Upstream: <https://github.com/pump-fun/pump-public-docs#pumpswap-update-virtual-
---
-<a id="sec-356"></a>
+<a id="sec-369"></a>
> **Source:** `docs/pumpfun-program/docs/BREAKING_FEE_RECIPIENT.md` · [↑ table of contents](#table-of-contents)
@@ -79077,7 +82485,7 @@ The new accounts can be passed before the program upgrade happens on Monday. The
---
-<a id="sec-357"></a>
+<a id="sec-370"></a>
> **Source:** `docs/pumpfun-program/docs/CPI_README.md` · [↑ table of contents](#table-of-contents)
@@ -79181,7 +82589,7 @@ pump-rust-client = { version = "...", path = "..." }
---
-<a id="sec-358"></a>
+<a id="sec-371"></a>
> **Source:** `docs/pumpfun-program/docs/FAQ.md` · [↑ table of contents](#table-of-contents)
@@ -79219,7 +82627,7 @@ is recommended to use a static big enough CU limit like `100_000`.
---
-<a id="sec-359"></a>
+<a id="sec-372"></a>
> **Source:** `docs/pumpfun-program/docs/FEE_PROGRAM_README.md` · [↑ table of contents](#table-of-contents)
@@ -79433,7 +82841,7 @@ If you implement the fee logic correctly, any future change to the fee tiers str
---
-<a id="sec-360"></a>
+<a id="sec-373"></a>
> **Source:** `docs/pumpfun-program/docs/FEE_RECIPIENTS.md` · [↑ table of contents](#table-of-contents)
@@ -79496,7 +82904,7 @@ Use one of these as `buybackFeeRecipient` for any coin.
---
-<a id="sec-361"></a>
+<a id="sec-374"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_CASHBACK_README.md` · [↑ table of contents](#table-of-contents)
@@ -79613,7 +83021,7 @@ To read unclaimed cashback for pump swap / Pump AMM program:
---
-<a id="sec-362"></a>
+<a id="sec-375"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_CREATOR_FEE_README.md` · [↑ table of contents](#table-of-contents)
@@ -79748,7 +83156,7 @@ we update the programs on Mainnet.
---
-<a id="sec-363"></a>
+<a id="sec-376"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_PROGRAM_README.md` · [↑ table of contents](#table-of-contents)
@@ -79949,7 +83357,7 @@ at https://solscan.io/account/EsmVk4MTsoT71JFaRM5DWFZboKpMQjfY6EYzAgUuksXw#accou
---
-<a id="sec-364"></a>
+<a id="sec-377"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_SWAP_CREATOR_FEE_README.md` · [↑ table of contents](#table-of-contents)
@@ -80058,7 +83466,7 @@ PumpSwap program on Mainnet to the coin creator fee update.
---
-<a id="sec-365"></a>
+<a id="sec-378"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_SWAP_README.md` · [↑ table of contents](#table-of-contents)
@@ -80292,7 +83700,7 @@ Each Anchor instruction has a set of corresponding autocomplete methods that can
---
-<a id="sec-366"></a>
+<a id="sec-379"></a>
> **Source:** `docs/pumpfun-program/docs/PUMP_SWAP_SDK_README.md` · [↑ table of contents](#table-of-contents)
@@ -80372,7 +83780,7 @@ to autocomplete the `base` and `quote` displayed amounts based on the `lpToken`
---
-<a id="sec-367"></a>
+<a id="sec-380"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/BUY.md` · [↑ table of contents](#table-of-contents)
@@ -80433,7 +83841,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-360) for the full address lists.
+See [Fee Recipients](#sec-373) for the full address lists.
## TS SDK
@@ -80550,7 +83958,7 @@ ixs.extend(
---
-<a id="sec-368"></a>
+<a id="sec-381"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/CLAIM_CASHBACK.md` · [↑ table of contents](#table-of-contents)
@@ -80660,7 +84068,7 @@ let ix = sdk.claim_cashback_v2_instruction(
---
-<a id="sec-369"></a>
+<a id="sec-382"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/COIN_CREATION.md` · [↑ table of contents](#table-of-contents)
@@ -80815,7 +84223,7 @@ let ixs = sdk
---
-<a id="sec-370"></a>
+<a id="sec-383"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md` · [↑ table of contents](#table-of-contents)
@@ -80917,13 +84325,13 @@ ixs.extend(sdk.collect_creator_fee_v2_instructions(
---
-<a id="sec-371"></a>
+<a id="sec-384"></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-370) 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-383) instead.
The lifecycle is:
@@ -81271,7 +84679,7 @@ ixs.extend(sdk.distribute_creator_fees_v2_instructions(
---
-<a id="sec-372"></a>
+<a id="sec-385"></a>
> **Source:** `docs/pumpfun-program/docs/instructions/SELL.md` · [↑ table of contents](#table-of-contents)
@@ -81331,7 +84739,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-360) for the full address lists.
+See [Fee Recipients](#sec-373) for the full address lists.
## TS SDK
@@ -81448,7 +84856,7 @@ ixs.extend(
---
-<a id="sec-373"></a>
+<a id="sec-386"></a>
> **Source:** `docs/quick-start.md` · [↑ table of contents](#table-of-contents)
@@ -81594,7 +85002,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-393). |
+| `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-411). |
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.
@@ -81635,7 +85043,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-526).
+For the full widget API including `postMessage` events, see the [Widget docs](#sec-546).
---
@@ -81665,7 +85073,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-154). |
+| `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-159). |
| `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. |
@@ -81736,15 +85144,15 @@ If you're embedding inside a sandboxed iframe, make sure the parent grants `allo
## Next Steps
-- [Embedding Guide](#sec-187) — deep dive on attributes, events, and the JS API
-- [Widget Types](#sec-526) — 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-261) — backend and in-browser surfaces
-- [SDK Reference](#sec-386) — `@three-ws/sdk`, `@three-ws/agent-ui`, `@three-ws/avatar`, `@three-ws/solana-agent`
+- [Embedding Guide](#sec-193) — deep dive on attributes, events, and the JS API
+- [Widget Types](#sec-546) — full reference for iframe embeds and postMessage
+- [Agent System](#sec-065) — how the brain, memory, and skills layers work
+- [REST API](#sec-098) and [JavaScript API](#sec-272) — backend and in-browser surfaces
+- [SDK Reference](#sec-400) — `@three-ws/sdk`, `@three-ws/agent-ui`, `@three-ws/avatar`, `@three-ws/solana-agent`
---
-<a id="sec-374"></a>
+<a id="sec-387"></a>
> **Source:** `docs/radar.md` · [↑ table of contents](#table-of-contents)
@@ -81760,7 +85168,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-429) funnel: Radar surfaces a launch worth a look, you watch it, and if it earns conviction you open it in [Mission Control](#sec-416) 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-447) funnel: Radar surfaces a launch worth a look, you watch it, and if it earns conviction you open it in [Mission Control](#sec-434) to act.
## How it works
@@ -81790,7 +85198,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-416) 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-434) to trade.
## Examples
@@ -81829,16 +85237,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-429)
-- [Oracle: the conviction engine](#sec-326) fuses this intel into a single conviction score
-- [Smart Money Radar](#sec-401) is the pedigree layer Radar surfaces inline
-- [Mission Control](#sec-416) is where a Radar find gets traded
-- [Coin pages](#sec-145) cross-link the per-mint intel and conviction views
+- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-447)
+- [Oracle: the conviction engine](#sec-338) fuses this intel into a single conviction score
+- [Smart Money Radar](#sec-419) is the pedigree layer Radar surfaces inline
+- [Mission Control](#sec-434) is where a Radar find gets traded
+- [Coin pages](#sec-149) 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-375"></a>
+<a id="sec-388"></a>
> **Source:** `docs/reasoning-ledger.md` · [↑ table of contents](#table-of-contents)
@@ -81915,7 +85323,7 @@ It returns the agent, the reputation breakdown, the latest anchor summary, and t
There is a single write path, `recordDecision`, and it is a chokepoint by design: appends are idempotent per real-world action (a handler that fires twice records once) and concurrency-safe when claiming the next chain slot. Today's writers, as coded:
-- **The [Agent Sniper](#sec-061) executor** appends a `snipe` entry the moment a buy settles: trigger, firewall verdict, price impact, committed size, the buy signature, and (for LLM-judged arms) the model's thesis and confidence.
+- **The [Agent Sniper](#sec-062) executor** appends a `snipe` entry the moment a buy settles: trigger, firewall verdict, price impact, committed size, the buy signature, and (for LLM-judged arms) the model's thesis and confidence.
- **The sniper optimizer cron** appends an `optimize` entry whenever it auto-tunes a strategy from realized outcomes, so the self-tuning loop's own decisions are auditable next to the trades that drove them.
- **The reconcile cron** (`api/cron/reconcile-decisions`) writes no decisions; it closes the loop. When a linked position settles on-chain, it records the outcome against the sell signature (idempotently, so re-runs never double-count), then anchors each agent's advanced chain head, and raises an ops alert if a sizeable track record's hit rate collapses.
@@ -81927,18 +85335,18 @@ 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-171): the same provable-not-promised approach applied to the wallets these decisions spend from
+- [Agent Sniper](#sec-062): the pipeline that writes `snipe` entries, with a live case-study ledger
+- [Custody you can verify](#sec-177): the same provable-not-promised approach applied to the wallets these decisions spend from
---
-<a id="sec-376"></a>
+<a id="sec-389"></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-333)), 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-345)), 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:
@@ -82104,13 +85512,13 @@ Definitions live in [api/\_lib/schema.sql](../api/_lib/schema.sql); the lifecycl
## See also
-- [Permissions & Delegation](#sec-333) for granting, scoping and revoking the signed permission a schedule spends
-- [Payment sessions](#sec-332) for capped one-off agent spending that is not on a schedule
-- [Agent wallets](#sec-072) for the wallet a subscription pays into
+- [Permissions & Delegation](#sec-345) for granting, scoping and revoking the signed permission a schedule spends
+- [Payment sessions](#sec-344) for capped one-off agent spending that is not on a schedule
+- [Agent wallets](#sec-074) for the wallet a subscription pays into
---
-<a id="sec-377"></a>
+<a id="sec-390"></a>
> **Source:** `docs/remix.md` · [↑ table of contents](#table-of-contents)
@@ -82186,6 +85594,13 @@ an iteration is a normal owned creation: gallery-listed, downloadable, and
eligible to publish as remixable. It carries no payment surface of its own —
iteration itself stays free.
+`/api/forge` holds the connection open while a saturated generator queues the
+job, so an accept can legitimately take minutes. `/api/forge-iterate` therefore
+waits up to `FORGE_ITERATE_SUBMIT_MS` (default 60000) for it, and when that
+window runs out it answers the way the generator itself would, `429 busy` with
+`retryAfter: 20`, rather than a `504` that both iterate UIs used to read as a
+wording problem and answer with "rephrase your instruction".
+
## Publish a model as remixable
You must own the creation (same `x-forge-client` that generated it). Only finished
@@ -82281,6 +85696,14 @@ Response (after settlement):
no payout wallet, or the royalty is below the 0.01 USDC dust floor, `paid` is
`false` with an honest `reason` — never a fake pending.
+When the source belongs to a signed-in creator (anonymous `forge_creations`
+rows have no `user_id`), a settled remix also publishes a `remix` event to that
+creator's notification feed, folding "you were remixed" and the royalty outcome
+into one line, and awards the first-remix-received badge once. Both are
+fire-and-forget and never delay the response. A validation failure (bad source
+id, empty instruction) is answered before settlement with the error's own
+status and code, so the buyer is never charged for a request that could not run.
+
### Split math + caps
Pure and unit-tested (`api/_lib/remix-royalty.js`,
@@ -82307,12 +85730,12 @@ still recorded — the royalty leg reports `payout_unconfigured` instead of payi
## Related
-- [3D Studio (free) MCP](#sec-281) — the `refine_model` iteration tool.
+- [3D Studio (free) MCP](#sec-290) — the `refine_model` iteration tool.
- [The 3D pipeline](#sec-003) — how generation itself works.
---
-<a id="sec-378"></a>
+<a id="sec-391"></a>
> **Source:** `docs/reputation-staking-market.md` · [↑ table of contents](#table-of-contents)
@@ -82333,7 +85756,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-405)).
+into `solana_attestations` (see [docs/solana-reputation](#sec-423)).
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
@@ -82539,15 +85962,15 @@ Failure codes (`market_not_configured`, `mainnet_gated`, `tx_not_found`,
## Related
-- [Docs: Agent Reputation on Solana](#sec-405): the attestation
+- [Docs: Agent Reputation on Solana](#sec-423): the attestation
layer the market reads.
-- [Docs: Reputation System](#sec-379): the cross-chain reputation model.
+- [Docs: Reputation System](#sec-392): the cross-chain reputation model.
- [Reputation Explorer](/reputation): inspect any agent's score and
attestations.
---
-<a id="sec-379"></a>
+<a id="sec-392"></a>
> **Source:** `docs/reputation.md` · [↑ table of contents](#table-of-contents)
@@ -82627,6 +86050,8 @@ The `ReputationPanel` class ([src/erc8004/reputation-panel.js](../src/erc8004/re
Recent vouches are loaded by querying `FeedbackSubmitted` event logs for the last ~50,000 blocks (~7 days on most L2s). If the RPC rejects the log query (common on free-tier endpoints), the panel degrades gracefully — it still shows the aggregate stats but omits the individual review list.
+Reads go through `readProvider(chainId)` from [src/erc8004/chain-meta.js](../src/erc8004/chain-meta.js): every keyless public node listed for the chain becomes a pinned provider and they are combined in an ethers `FallbackProvider` with quorum 1, so the first healthy node answers and a stalled or rate-limited one is passed over after four seconds instead of blanking the panel. The USD figure printed beside a stake amount comes from `getEthPriceUsd()` ([src/shared/usd-price.js](../src/shared/usd-price.js)), which walks four price feeds with per-provider cooldowns; a throttled feed leaves the ETH amount in place and only drops the USD hint.
+
### Full reputation dashboard
The `ReputationDashboard` class ([src/reputation-ui.js](../src/reputation-ui.js)) is used on the standalone [/reputation](https://three.ws/reputation) page. It shows:
@@ -82634,7 +86059,9 @@ The `ReputationDashboard` class ([src/reputation-ui.js](../src/reputation-ui.js)
- Review count, average rating, time since last review
- Up to 10 recent reviews with inline transaction links
- A submit form for leaving a new review (wallet connection handled inline)
-- Optimistic updates: your review appears immediately as "Pending" while the transaction confirms, then is replaced with the confirmed on-chain data
+- Optimistic updates: your review appears immediately as "Pending" while the transaction confirms, then is replaced with the confirmed on-chain data. If a confirmation poll fails, the page says so ("Could not confirm your review on-chain; refresh to check.") rather than leaving the pending row looking stuck.
+
+The dashboard reads through `getEvmProvider(chainId)` from [src/shared/evm-rpc-fallback.js](../src/shared/evm-rpc-fallback.js): the same-origin `/api/evm-rpc?chainId=N` proxy first (which inherits the server's keyed and curated RPC failover), then the chain's keyless public hosts, combined into one `FallbackProvider`. There is no per-chain RPC URL hardcoded in the dashboard any more; one dead public endpoint no longer reads as "chain unsupported".
### Via the SDK
@@ -82737,6 +86164,8 @@ Contract addresses are the same on every supported EVM chain (CREATE2 determinis
| Mainnet (Base, Arbitrum, Optimism, Ethereum, Polygon, and more) | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` |
| Testnet (Base Sepolia, Arbitrum Sepolia, Optimism Sepolia, and more) | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
+One caveat, recorded in the comments of `abi.js`: the canonical addresses run the ERC-8004 reference implementation, not the three.ws source above. An `eth_call` sweep on 2026-08-15 found that deployment answering `readFeedback` / `getClients` on Base and Base Sepolia and reverting on every selector in `contracts/src/ReputationRegistry.sol` (`submitFeedback`, `getReputation`, `getFeedbackRange`, and the stake functions). The ABI and SDK helpers on this page match the three.ws source, so use them against an instance you deploy from `contracts/src` yourself; against the canonical addresses those calls revert.
+
---
## Reputation in agent discovery
@@ -82756,7 +86185,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-516) documentation for details.
+See the [Validation](#sec-536) documentation for details.
---
@@ -82769,7 +86198,165 @@ See the [Validation](#sec-516) documentation for details.
---
-<a id="sec-380"></a>
+<a id="sec-393"></a>
+
+> **Source:** `docs/resilience.md` · [↑ table of contents](#table-of-contents)
+
+<!-- GENERATED by scripts/audit-upstreams.mjs. Run `npm run audit:upstreams -- --map`. -->
+# Upstream resilience map
+
+Every third-party service this platform calls, and what happens to a user when
+that service is down. Generated from the source by an AST pass, so it cannot
+drift from the code the way a hand-written list does.
+
+## How a call site is graded
+
+| Grade | Meaning |
+|---|---|
+| A | Bounded, and survives the upstream being down (a second source, plus a remembered value or a retry) |
+| B | Bounded, with one way to survive: either another source or a remembered value |
+| C | Bounded, retries or trips a breaker, but has no second source |
+| D | Bounded only: a deadline and nothing behind it |
+| F | Unbounded: one stalled socket can outlive the request that opened it |
+
+A deadline is the floor rather than one grade among five, because without one
+no other protection ever gets a turn.
+
+## Totals
+
+224 outbound call sites across 79 upstreams.
+
+| A | B | C | D | F |
+|---|---|---|---|---|
+| 0 | 54 | 91 | 79 | 0 |
+
+## Weakest upstreams
+
+These carry at least one call site with no second source behind it. They are
+the list to work down, worst first.
+
+| Upstream | Call sites | Worst grade |
+|---|---|---|
+| `api.telegram.org` | 13 | D |
+| `lite-api.jup.ag` | 12 | D |
+| `api.dexscreener.com` | 9 | D |
+| `storage.googleapis.com` | 8 | D |
+| `api.coinpaprika.com` | 8 | D |
+| `api.coingecko.com` | 8 | D |
+| `api.github.com` | 7 | D |
+| `frontend-api-v3.pump.fun` | 6 | D |
+| `api.replicate.com` | 5 | D |
+| `api.elevenlabs.io` | 5 | D |
+| `api.pinata.cloud` | 5 | D |
+| `openrouter.ai` | 5 | D |
+| `api.geckoterminal.com` | 5 | D |
+| `ai.api.nvidia.com` | 4 | D |
+| `api.web3.storage` | 4 | D |
+| `api.alternative.me` | 4 | D |
+| `api.openai.com` | 3 | D |
+| `integrate.api.nvidia.com` | 2 | D |
+| `api.sketchfab.com` | 2 | D |
+| `api.nvcf.nvidia.com` | 2 | D |
+| `sns-api.bonfida.com__expr__` | 2 | D |
+| `api.anthropic.com` | 2 | D |
+| `raw.githubusercontent.com` | 2 | D |
+| `publish.twitter.com` | 2 | D |
+| `api.zauth.inc` | 2 | D |
+
+## Every upstream
+
+| Upstream | Call sites | Worst grade | A | B | C | D | F |
+|---|---|---|---|---|---|---|---|
+| `api.telegram.org` | 13 | D | 0 | 0 | 10 | 3 | 0 |
+| `lite-api.jup.ag` | 12 | D | 0 | 5 | 2 | 5 | 0 |
+| `api.dexscreener.com` | 9 | D | 0 | 4 | 2 | 3 | 0 |
+| `storage.googleapis.com` | 8 | D | 0 | 1 | 2 | 5 | 0 |
+| `api.coinpaprika.com` | 8 | D | 0 | 0 | 0 | 8 | 0 |
+| `api.coingecko.com` | 8 | D | 0 | 7 | 0 | 1 | 0 |
+| `api.github.com` | 7 | D | 0 | 0 | 5 | 2 | 0 |
+| `frontend-api-v3.pump.fun` | 6 | D | 0 | 0 | 5 | 1 | 0 |
+| `api.replicate.com` | 5 | D | 0 | 0 | 2 | 3 | 0 |
+| `api.elevenlabs.io` | 5 | D | 0 | 0 | 2 | 3 | 0 |
+| `api.pinata.cloud` | 5 | D | 0 | 0 | 3 | 2 | 0 |
+| `openrouter.ai` | 5 | D | 0 | 0 | 0 | 5 | 0 |
+| `api.geckoterminal.com` | 5 | D | 0 | 3 | 0 | 2 | 0 |
+| `ai.api.nvidia.com` | 4 | D | 0 | 0 | 0 | 4 | 0 |
+| `api.web3.storage` | 4 | D | 0 | 0 | 3 | 1 | 0 |
+| `api.alternative.me` | 4 | D | 0 | 0 | 3 | 1 | 0 |
+| `api.openai.com` | 3 | D | 0 | 0 | 0 | 3 | 0 |
+| `integrate.api.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `api.sketchfab.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `api.nvcf.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `sns-api.bonfida.com__expr__` | 2 | D | 0 | 0 | 1 | 1 | 0 |
+| `api.anthropic.com` | 2 | D | 0 | 0 | 1 | 1 | 0 |
+| `raw.githubusercontent.com` | 2 | D | 0 | 1 | 0 | 1 | 0 |
+| `publish.twitter.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `api.zauth.inc` | 2 | D | 0 | 0 | 0 | 2 | 0 |
+| `huggingface.co` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `image.pollinations.ai` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.developer.coinbase.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `bigquery.googleapis.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.indexnow.org` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.tokens.xyz` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `speech.platform.bing.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.upstash.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `qstash.upstash.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `402index.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.resend.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.exchange.coinbase.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `pump-fun-sdk.modelcontextprotocol.name` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `kolscan.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |
+| `api.twitter.com` | 8 | C | 0 | 0 | 8 | 0 | 0 |
+| `api.llama.fi` | 5 | C | 0 | 0 | 5 | 0 | 0 |
+| `api.x.com` | 4 | C | 0 | 0 | 4 | 0 | 0 |
+| `api.hyper3d.com` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `api.tripo3d.ai` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `yields.llama.fi` | 3 | C | 0 | 0 | 3 | 0 | 0 |
+| `api.meshy.ai__expr__` | 2 | C | 0 | 0 | 2 | 0 | 0 |
+| `stablecoins.llama.fi` | 2 | C | 0 | 0 | 2 | 0 | 0 |
+| `api.duckduckgo.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.blockchair.com__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `blockstream.info` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `metadata.google.internal` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `oauth2.googleapis.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.github.com__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `sns-api.bonfida.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `auth.privy.io` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `livestream-api.pump.fun__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `pump.fun` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.rugcheck.xyz` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.etherscan.io` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.stability.ai` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `github.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `pro-api.coinmarketcap.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.nft.storage` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `swap-api.pump.fun` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.helius.xyz` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `api.llama.fi__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `www.deribit.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |
+| `coins.llama.fi` | 9 | B | 0 | 9 | 0 | 0 | 0 |
+| `api.coinbase.com` | 5 | B | 0 | 5 | 0 | 0 | 0 |
+| `esm.sh` | 5 | B | 0 | 5 | 0 | 0 | 0 |
+| `api.kraken.com` | 4 | B | 0 | 4 | 0 | 0 | 0 |
+| `nominatim.openstreetmap.org` | 2 | B | 0 | 2 | 0 | 0 | 0 |
+| `photon.komoot.io` | 2 | B | 0 | 2 | 0 | 0 | 0 |
+| `api.hyperliquid.xyz` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api.coinlore.com` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api.diadata.org` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api-pub.bitfinex.com` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `api.bigdatacloud.net` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+| `tokens.jup.ag` | 1 | B | 0 | 1 | 0 | 0 | 0 |
+
+## Keeping this true
+
+`npm run audit:upstreams` fails when a call site regresses below the grade
+recorded in `data/upstream-baseline.json`, or when a new unbounded call appears.
+Improving a call site lowers the baseline automatically; raising it back needs an
+explicit `--accept`, which is a reviewable line in the diff.
+
+---
+
+<a id="sec-394"></a>
> **Source:** `docs/restyle.md` · [↑ table of contents](#table-of-contents)
@@ -82781,7 +86368,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-115) 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-117) uses, instead of inventing a parallel one.
## How it works
@@ -82862,14 +86449,14 @@ Pass the returned `lineage` array back as `parent_lineage` on the next call to e
## Related
-- [Avatar Studio](#sec-115): shares the same GLB optimize-and-validate path and material vocabulary.
-- [Scene Composer](#sec-152) and [Scene Studio](#sec-385): arrange and edit restyled models in a full scene.
-- [MCP tools reference](#sec-282): the paid `restyle_material` agent twin of this endpoint.
+- [Avatar Studio](#sec-117): shares the same GLB optimize-and-validate path and material vocabulary.
+- [Scene Composer](#sec-157) and [Scene Studio](#sec-399): arrange and edit restyled models in a full scene.
+- [MCP tools reference](#sec-291): the paid `restyle_material` agent twin of this endpoint.
- [/forge](https://three.ws/forge): generate the models you bring here.
---
-<a id="sec-381"></a>
+<a id="sec-395"></a>
> **Source:** `docs/rig-doctor.md` · [↑ table of contents](#table-of-contents)
@@ -82883,7 +86470,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-108) turns the generated manifest into a validated, hash-anchored file. The [web component reference](#sec-523) 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-110) turns the generated manifest into a validated, hash-anchored file. The [web component reference](#sec-543) covers the `<agent-3d>` element the embed tab emits. [Asset pipeline](#sec-002) covers FBX and GLB conversion upstream of all of this.
---
@@ -82967,7 +86554,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-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:
+**CLI** is the [`@three-ws/avatar-cli`](#sec-110) 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 \
@@ -83100,7 +86687,7 @@ Your own file cannot be shared this way, because it never leaves your machine.
---
-<a id="sec-382"></a>
+<a id="sec-396"></a>
> **Source:** `docs/risk-acknowledgment.md` · [↑ table of contents](#table-of-contents)
@@ -83129,12 +86716,20 @@ simply doesn't run; everything else on the platform keeps working.
older version no longer count.
- **Recorded server-side.** On accept, the client fires
`POST /api/legal/risk-ack` ([`api/legal/risk-ack.js`](../api/legal/risk-ack.js)),
- which writes a `risk-ack-accept` row into `audit_log` — user id when signed
+ which writes a `risk-ack-accept` row into `audit_log`: user id when signed
in (null otherwise), disclosure version, the feature context, path, IP, and
- user agent. The `audit-log-cleanup` cron prunes `audit_log` at 365 days but
- exempts `risk-ack-accept` (and `tos-accept`) rows, so acceptance records
- persist indefinitely. The write is fire-and-forget: a failed network call
- never blocks the user's accepted state.
+ user agent. The handler awaits that write and answers
+ `200 { ok: true, recorded }`, where `recorded` says whether the row actually
+ landed; a dropped write still answers 200 because the user did accept. It
+ imports `RISK_ACK_VERSION` from the client gate and rejects any `version`
+ outside `1..RISK_ACK_VERSION` with `400 invalid_version`, so nobody can
+ record acceptance of a revision that does not exist yet; an unreadable body
+ gets its real cause (`413 payload_too_large`, `415 unsupported_media_type`,
+ or `400 bad_request`) instead of a version complaint. The
+ `audit-log-cleanup` cron prunes `audit_log` at 365 days but exempts
+ `risk-ack-accept` (and `tos-accept`) rows, so acceptance records persist
+ indefinitely. The client's call is fire-and-forget (`keepalive`, errors
+ swallowed): a failed network call never blocks the user's accepted state.
- **Devnet stays friction-free.** Surfaces that know their network only gate
when it isn't `devnet`. Simulation modes (e.g. Oracle arm's simulate mode)
are never gated.
@@ -83214,12 +86809,12 @@ above.
## Related
- [Risk Disclosure](https://three.ws/legal/risk) — the full legal text users accept
-- [Custody you can verify](#sec-171) — the spend-limit and freeze controls that bound what agents can do after acceptance
+- [Custody you can verify](#sec-177) — 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-383"></a>
+<a id="sec-397"></a>
> **Source:** `docs/robinhood-chain-markets.md` · [↑ table of contents](#table-of-contents)
@@ -83274,7 +86869,7 @@ Free, keyless, real data only:
| Endpoint | Returns |
| --- | --- |
| `GET /api/v1/robinhood/chain` | Block height, gas, tx/address counts, chain TVL + 90-day history |
-| `GET /api/v1/robinhood/stocks` | Every Stock Token: NAV, DEX price, premium, volume, liquidity (`?q=`, `?sort=`) |
+| `GET /api/v1/robinhood/stocks` | Every Stock Token: NAV, DEX price, premium, volume, liquidity (`?q=`; `sort`: `symbol` \| `volume` \| `liquidity` \| `premium` \| `price`; `dir`: `asc` \| `desc`, numeric columns default highest-first, symbol A-Z; rows with no value for the column sort last either way) |
| `GET /api/v1/robinhood/stocks-detail?symbol=AAPL` | One Stock Token in depth: NAV history, all DEX pairs, holders, transfers, links |
| `GET /api/v1/robinhood/coins?category=meme` | Memecoin screener (`category`: `meme` \| `stocks-ecosystem` \| `ecosystem`; `sort`: `market_cap` \| `volume` \| `gainers` \| `losers`) |
| `GET /api/v1/robinhood/coins-detail?address=0x…` | One coin: pools, market stats, holders, transfers, links |
@@ -83286,7 +86881,7 @@ Paid via x402 ($0.002 USDC, Base or Solana):
| --- | --- |
| `GET /api/x402/robinhood-portfolio?address=0x…` | Multiplier-correct Stock Token portfolio: every held symbol's true position (raw balance × ERC-8056 `uiMultiplier`) priced at the live Chainlink NAV, plus a total USD value |
-Every response carries `source` and `asOf` fields. A miss is a structured error, never a bare 500.
+Every response carries `source` and `asOf` fields. A miss is a structured error, never a bare 500. An unknown `sort` (or `category`) falls back to the default instead of 400ing a screener read, and the response echoes the `sort` (and `dir`) that actually ran, never the caller's unknown value.
### Why the multiplier matters
@@ -83311,16 +86906,16 @@ math; Chainlink feed prices are already multiplier-adjusted, so they're never re
## Related surfaces
-- [Market Data API](#sec-273) — the same paid-endpoint pattern (x402, `priceFor`,
+- [Market Data API](#sec-285) — the same paid-endpoint pattern (x402, `priceFor`,
service-catalog descriptor) applied to the rest of three.ws's market data.
-- [Trust primitives](#sec-432) — score a Robinhood Chain wallet's cross-chain
+- [Trust primitives](#sec-450) — score a Robinhood Chain wallet's cross-chain
reputation before transacting with it.
-- [x402 distribution](#sec-558) — how the paid portfolio endpoint gets discovered
+- [x402 distribution](#sec-583) — how the paid portfolio endpoint gets discovered
across the x402 ecosystem.
---
-<a id="sec-384"></a>
+<a id="sec-398"></a>
> **Source:** `docs/sas-attestations.md` · [↑ table of contents](#table-of-contents)
@@ -83330,7 +86925,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-405)).
+- **Permissionless attestations** — general feedback, task lifecycle, dispute, and revoke events. Anyone can write them as SPL Memos (see [Solana reputation](#sec-423)).
- **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.
@@ -83553,13 +87148,13 @@ Closing (revoking) an attestation is done server-side via `sasClose()` in [api/_
---
-<a id="sec-385"></a>
+<a id="sec-399"></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-152) 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-157) is a focused avatar-plus-props arranger and [Animation Studio](#sec-094) is a posing and keyframing tool, Scene Studio is the general-purpose 3D authoring surface underneath them.
Page: [/scene](https://three.ws/scene)
@@ -83579,7 +87174,7 @@ The editor is ported from the upstream `editor/index.html` with a small set of l
### Handoff from Animation Studio
-Scene Studio is the render target for animations built in [Animation Studio](#sec-092). When you click "Open in Scene Studio" there, the studio bakes your keyframed animation into a GLB, stashes it in IndexedDB, and navigates to `/scene?handoff=1`. Scene Studio picks the model up on boot (`takeSceneHandoff`), drops it into the scene with its animation track ready, and you record it to video from the editor's render menu. The GLB is passed through browser storage, not the network, so nothing large is uploaded to move a model between the two tools.
+Scene Studio is the render target for animations built in [Animation Studio](#sec-094). When you click "Open in Scene Studio" there, the studio bakes your keyframed animation into a GLB, stashes it in IndexedDB, and navigates to `/scene?handoff=1`. Scene Studio picks the model up on boot (`takeSceneHandoff`), drops it into the scene with its animation track ready, and you record it to video from the editor's render menu. The GLB is passed through browser storage, not the network, so nothing large is uploaded to move a model between the two tools.
## Walkthrough
@@ -83600,7 +87195,7 @@ Scene Studio is an interactive editor, not an HTTP API, so the concrete examples
A typical round trip from another studio:
-1. Build a walk cycle in [Animation Studio](#sec-092) on a rigged avatar.
+1. Build a walk cycle in [Animation Studio](#sec-094) on a rigged avatar.
2. Click "Open in Scene Studio". The baked animated GLB is stashed and `/scene?handoff=1` opens.
3. In Scene Studio, add a ground plane, a key light, and a camera, position the avatar, and use Render ▸ Video to capture the loop.
@@ -83614,20 +87209,20 @@ A typical round trip from another studio:
## Related
-- [Scene Composer](#sec-152): 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-380): re-skin the models before or after composing them.
+- [Scene Composer](#sec-157): the lighter avatar-plus-props arranger with Forge integration.
+- [Animation Studio](#sec-094): builds the animated GLBs Scene Studio records to video.
+- [Restyle Studio](#sec-394): 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-386"></a>
+<a id="sec-400"></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-523); 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-543); 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 |
|---|---|---|
@@ -83720,7 +87315,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-523).
+Full attribute and event API is documented in [Web Component reference](#sec-543).
### loadManifest and normalize
@@ -84063,7 +87658,7 @@ python3 -m http.server 8080
---
-<a id="sec-387"></a>
+<a id="sec-401"></a>
> **Source:** `docs/security.md` · [↑ table of contents](#table-of-contents)
@@ -84104,7 +87699,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-287)).
+Conversation history lives in `localStorage` by default. Cloud memory sync is opt-in (see [Memory](#sec-296)).
### Wallet data
@@ -84120,7 +87715,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-287)) |
+| `remote` | three.ws cloud storage, tied to your account | Opt-in cloud sync (see [Memory](#sec-296)) |
| `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 |
@@ -84272,7 +87867,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-190) 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-196) for the operating rules.
### Reputation gaming (V5)
@@ -84306,7 +87901,7 @@ The `skill-trust` attribute controls which skill URLs the element will load:
Skills declare the permissions they need. Users must explicitly grant each permission before a skill can use it. The permission types (memory read/write, network, transaction signing) are independently grantable. An installed skill cannot escalate beyond its declared and granted permissions.
-Delegation validation is enforced before any redemption: `isDelegationValid({ hash, chainId })` from [src/permissions/toolkit.js](../src/permissions/toolkit.js) checks the on-chain `disabledDelegations` mapping, expiry, and EIP-712 signature recovery. An invalid or revoked delegation renders as inactive — it cannot be redeemed.
+Delegation validation is enforced before any redemption: `isDelegationValid({ hash, chainId, rpcUrl, delegation })` from [src/permissions/toolkit.js](../src/permissions/toolkit.js) checks the on-chain `disabledDelegations` mapping, expiry, and EIP-712 signature recovery, reaching the chain through the pinned `rpcUrl` (or `RPC_URL_<chainId>`) first and then the shared EVM fallback providers. It has three outcomes, not two: `valid: true`, `valid: false` with a reason (`delegation_revoked`, expiry, a bad signature), or `valid: null` with `reason: 'rpc_unavailable'` when no provider could be reached. An invalid or revoked delegation renders as inactive: it cannot be redeemed. An unreachable chain is not evidence of revocation; a caller that treats `null` as `false` is choosing fail-closed deliberately.
### Supply chain for skills
@@ -84342,11 +87937,15 @@ Requests through the `/api/chat` proxy are subject to the content policies of wh
Server code that fetches user-supplied URLs (GLB validation, manifest pinning, avatar imports) goes through [api/_lib/ssrf-guard.js](../api/_lib/ssrf-guard.js) rather than raw `fetch`. `assertSafePublicUrl()` rejects non-HTTPS schemes and resolves the hostname up front, refusing private, loopback, link-local, CGNAT, and cloud-metadata addresses. `fetchSafePublicUrl()` validates DNS then fetches (acceptable where the response is only displayed); `fetchSafePublicUrlPinned()` additionally pins the TCP connection to the validated IP so a DNS rebind between check and connect cannot redirect the request into the internal network. Both re-validate every redirect hop and enforce a streaming byte cap (`MaxBytesExceededError`) so an unbounded body cannot exhaust memory.
+### Fault injection is token-gated
+
+Every `/api` response carries an `x-brownout` header (plus `x-brownout-trace` when a trace was recorded) naming where its data came from. `wrap()` in [api/_lib/http.js](../api/_lib/http.js) writes it for every handler, so a client can tell a degraded, last-good answer from a live one. The matching `x-brownout-chaos` request header lets a prover make named upstreams misbehave for that one request only, running the real handler, the real provider ladder, and the real cache tiers. It is gated three ways in [api/_lib/brownout/chaos.js](../api/_lib/brownout/chaos.js), and every gate must pass: `BROWNOUT_CHAOS_TOKEN` must be set and match (constant-time compare; unset means chaos is off everywhere, including locally), a money path is refused outright no matter who holds the token (a request carrying an x402 payment header, or addressed to a settle, withdraw, or transfer route), and only read-shaped requests qualify (GET/HEAD, or a POST that is a declared read). A refused directive is reported in `x-brownout-chaos-status` rather than silently ignored.
+
---
## Rate limiting
-Limits return `429 Too Many Requests` with a `Retry-After` header on breach. Money-moving and credential buckets are enforced through shared Upstash Redis so they hold across every instance; a few very hot read buckets (including the MCP limiters) are deliberately per-instance (`local: true` in [api/_lib/rate-limit.js](../api/_lib/rate-limit.js)) to keep Redis command volume down, and the credential buckets degrade to in-memory limiting rather than failing closed if Redis is unreachable.
+Limits return `429 Too Many Requests` with a `Retry-After` header on breach. Money-moving and credential buckets are enforced through shared Upstash Redis so they hold across every instance; a few very hot read buckets (including the MCP limiters) are deliberately per-instance (`local: true` in [api/_lib/rate-limit.js](../api/_lib/rate-limit.js)) to keep Redis command volume down. When Redis cannot answer, the money and credential buckets degrade onto a durable Postgres counter (`rate_limit_counters`) rather than failing closed, and the login and registration buckets fall back one step further to per-instance memory if Postgres is down too, so an infrastructure outage never locks everyone out (the full table is in [docs/ops/redis.md](ops/redis.md)).
| Endpoint class | Limit |
|----------------|-------|
@@ -84425,7 +88024,7 @@ For validator misconduct (biased or falsified on-chain attestations), open a pub
---
-<a id="sec-388"></a>
+<a id="sec-402"></a>
> **Source:** `docs/seed-quality.md` · [↑ table of contents](#table-of-contents)
@@ -84567,6 +88166,12 @@ Retries surface as `gate_retry` entries in the tick's `gate_results`, with a
`gate_retries` count on the response, so a lane that keeps blipping is visible
without reading the table.
+Every read the gate makes is bounded so one slow host cannot stall the rest of
+the tick: a lane's public GLB URL is fetched through the shared `fetchUpstream`
+(30 s deadline, two attempts, and a non-2xx is a gate throw rather than an error
+page handed to the GLB parser as mesh bytes), and the in-process Vertex judge
+call carries a 45 s deadline with no retry.
+
## Rejects are kept, not deleted
A reject is copied (never moved, so the creator's forge history stays coherent)
@@ -84710,13 +88315,461 @@ 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-520): what a published catalog entry has to render in
+- [The 3D viewer](#sec-540): 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-389"></a>
+<a id="sec-403"></a>
+
+> **Source:** `docs/seeker-app.md` · [↑ table of contents](#table-of-contents)
+
+# three.ws on Solana Seeker
+
+three.ws ships as a native Android app for the Solana Seeker (and Saga) through the Solana dApp Store. It is a Trusted Web Activity: the signed APK (`ws.three.app`) opens `https://three.ws/seeker` full-screen in Chrome's rendering engine with no browser chrome, and every wallet interaction is routed to the phone's Seed Vault through Mobile Wallet Adapter. For a WebGL product that is the right shape (it is what Solana Mobile recommends for web apps); what makes it feel like an app is everything around that shell. This page is the user-facing map of those pieces. The packaging and code layout live in [solana-mobile/README.md](../solana-mobile/README.md); how a release reaches the store is [Publishing to the Solana dApp Store](#sec-404).
+
+**Status: v1.0.0 was submitted to the Solana dApp Store on 2026-08-28 and is in review** (release `#331044442814`). Until it is approved the app is installable from the [v1.0.0 GitHub release](https://github.com/nirholas/three.ws/releases/tag/v1.0.0); everything described below is live on the web at [/seeker](/seeker) today.
+
+## What the app does differently from the website
+
+| Surface | On Seeker | Where it lives |
+|---|---|---|
+| Home screen | [/seeker](https://three.ws/seeker): one-tap Seed Vault sign-in, Create / Explore grid, your agents, Seeker verification | `pages/seeker.html`, `src/seeker.js` |
+| Sign-in | A single Seed Vault sheet (Sign-In With Solana at authorize time) instead of connect-then-sign. The session survives Android killing the app; a revoked session is dropped cleanly | `solana-mobile/src/mwa-wallet.js`, `src/onchain/adapters/solana.js` |
+| Share sheet | Share a photo from any app to three.ws: it opens the selfie flow with the photo attached. Share a `.glb`: it opens the upload flow | `public/share-target-sw.js`, `src/shared/share-target.js` |
+| Offline | A branded offline screen that reloads itself when the network returns, instead of Chrome's error page | `public/offline.html`, `vite.config.js` (workbox `precacheFallback`) |
+| Home-screen shortcuts | Long-press the icon: Create, Discover, My agents | `solana-mobile/twa/twa-manifest.json`, web manifest in `vite.config.js` |
+| Icon | A maskable icon with the glyph inside Android's safe zone, so circle and squircle launchers never crop it | `public/pwa-maskable-*.png` |
+| Seeker verification | Prove Seeker ownership by holding the soulbound Seeker Genesis Token; owners get a "Seeker verified" badge on every agent they own | `api/seeker/[action].js`, `api/_lib/seeker-genesis.js` |
+| Deep links | Any `https://three.ws/...` link opens inside the app once Digital Asset Links verify the release key | `public/.well-known/assetlinks.json` |
+
+## Seeker verification
+
+The Seeker Genesis Token is a soulbound Token-2022 asset that Solana Mobile mints once per device into the primary Seed Vault account. three.ws reads it (never moves it):
+
+1. Sign in on [/seeker](https://three.ws/seeker) with Seed Vault. That links the wallet to your account through SIWS.
+2. Tap **Check my wallet**. The server calls Helius `getTokenAccountsByOwnerV2` for the linked Solana wallets, then checks each mint's authority, metadata pointer, and token-group membership against the Genesis Token group. No transaction, no signature.
+3. On success the wallet is recorded in `seeker_genesis_verifications`, and every agent you own shows a **Seeker verified** pill in its trust row on `/agents/:id`.
+
+API: `GET /api/seeker/status` and `POST /api/seeker/verify`, documented in [api-reference.md](api-reference.md#seeker-verification). Verification fails closed: an RPC error is a 502, never a false positive.
+
+## Sharing into three.ws
+
+The web manifest declares a `share_target` at `POST /create/share`. The service worker intercepts that POST, parks the files in the Cache API, and redirects:
+
+- an image goes to `/create/selfie?shared=1`, where the page picks it up as the frontal selfie (a second and third image fill the optional side angles);
+- a `.glb` goes to `/create?shared=glb`, where the upload flow validates and stages it;
+- anything else goes to `/create`.
+
+The handoff is one-shot and expires after ten minutes, so a stale share can never resurface. On the Seeker the APK registers the same target with Android, so three.ws appears in the system share sheet for photos and `model/gltf-binary` files.
+
+## Testing without a Seeker
+
+The APK can be exercised in a stock Android emulator (Pixel 7, Android 14 image). Everything except the Seed Vault itself works there: install, launch, shortcuts, the share intent, deep-link verification state. The recipe is in [solana-mobile/README.md](../solana-mobile/README.md#emulator-qa). For the wallet flows, `tests/solana-mobile-*.test.js` drive the MWA wrapper against a fake transport, and the Solana Mobile reference wallet can be sideloaded into the emulator for an end-to-end sign-in.
+
+## The home screen widget
+
+Version 1.1 adds **Agent glance**, an Android app widget: your agent's avatar, its name, and how
+many moves it made today, refreshed by the system about every 30 minutes without opening the app,
+with a tap that opens the agent inside the app. Link the phone from [three.ws/glance](https://three.ws/glance)
+(one tap, signed in), then add the widget from the launcher's picker. It keeps the last card it
+downloaded when the phone is offline and can be revoked from the same page. Everything about it,
+including every state it can be in and how it authenticates, is in
+[native-widgets.md](native-widgets.md#android); the native sources are in
+[solana-mobile/android-overlay/](../solana-mobile/android-overlay/README.md).
+
+## What is next
+
+Windows 11 already gets the same card through the installed PWA's manifest. macOS and iOS follow
+through a shared WidgetKit extension against the same endpoint and widget token; that is Phase 5
+of the [roadmap](../README.md#roadmap) and the scoped work order is
+[prompts/roadmap/native-widgets.md](../prompts/roadmap/native-widgets.md).
+
+---
+
+<a id="sec-404"></a>
+
+> **Source:** `docs/seeker-publishing.md` · [↑ table of contents](#table-of-contents)
+
+# Publishing three.ws to the Solana dApp Store
+
+How a release of the three.ws Seeker app gets from this repo onto the Solana dApp Store. This is the runbook; the app itself and what it adds over the website are described in [three.ws on Solana Seeker](#sec-403), and the box-by-box submission gate lives in [solana-mobile/docs/CHECKLIST.md](../solana-mobile/docs/CHECKLIST.md). If you are the owner sitting down to actually submit, follow [Submission day](#sec-405) instead: it inlines every field and value so you never open a file.
+
+**Status: v1.0.0 submitted 2026-08-28, in review** (release `#331044442814`, versionCode 1, package `ws.three.app`). What the portal recorded, including the release NFT mint and app collection, is in [Submission day](#sec-405).
+
+Publishing changed shape in May 2026. `dapp-store-cli` 1.0 is **Publisher Portal backed**: the publisher identity, KYC, the App NFT, and all listing copy live in <https://publish.solanamobile.com>, and the CLI only uploads one signed APK per release. The old `dapp-store create publisher` / `create app` / `publish submit` chain is gone. Anything that still describes that flow is out of date.
+
+## Who does what
+
+| Step | Who | Where |
+|---|---|---|
+| Publisher profile, KYC/KYB, App NFT, API key | Owner, once | Publisher Portal (browser) |
+| Screenshots on a physical Seeker | Owner, per listing change | Real device |
+| Keystore restore and APK build | Any agent, per release | This repo |
+| Uploading the release | Owner, per release | Publisher Portal, or the CLI |
+
+Everything scriptable is in [solana-mobile/scripts/](../solana-mobile/scripts). The parts that need a human need an identity, a funded wallet, or a phone.
+
+## One-time setup (owner, in the portal)
+
+1. Create the publisher profile at <https://publish.solanamobile.com> and submit KYC/KYB. Approval gates everything below.
+2. Connect the publisher wallet (Phantom, Solflare, or Backpack extension). Fund it with **at least 0.2 SOL** to cover the App NFT, each release NFT, and ArDrive upload fees.
+3. Choose a storage provider. ArDrive is the recommended default.
+4. **Add a dApp**, filling every field from the repo rather than from memory, so the portal and git never drift:
+ - identity and URLs: [solana-mobile/publish/config.yaml](../solana-mobile/publish/config.yaml)
+ - listing text: [solana-mobile/publish/listing/](../solana-mobile/publish/listing) (long description, short description, what's-new, Seeker features)
+ - media: [solana-mobile/publish/media/](../solana-mobile/publish/media) (icon, banner, and feature graphic are committed; screenshots are not, see below)
+
+ Completing this mints the **App NFT**. The portal matches later uploads to this app by Android package name, `ws.three.app`.
+5. Settings → API keys → create one. Store it in the owner's password manager; it never goes in the repo.
+
+## Per release (in this repo)
+
+The release keystore is gitignored and lives in Secret Manager. The 2026-08-10 key was lost with the codespace that generated it, so a new one was created on 2026-08-27 and backed up properly. **Never generate a second key while this one exists**: the dApp Store identifies the app by its signing certificate, and losing it means the app can never be updated.
+
+**Two ways to upload the release, and the browser one is preferable.** The portal's **New Version** page accepts the APK as a file or as a public URL and signs the release NFT with the wallet already connected in the browser. The CLI path below does the same thing but needs the publisher wallet's private key exported to a keypair file on disk, which is a real risk for no gain on a normal release. v1.0.0 went in through the browser, by URL, from the `v1.0.0` GitHub release.
+
+Either way the APK has to exist and be signed first:
+
+```bash
+cd solana-mobile
+
+# 1. Restore the keystore and its password.
+gcloud secrets versions access latest --secret three-ws-seeker-release-keystore \
+ --project aerial-vehicle-466722-p5 | base64 -d > android.keystore
+export SOLANA_MOBILE_KEYSTORE_PASSWORD="$(gcloud secrets versions access latest \
+ --secret three-ws-seeker-keystore-password --project aerial-vehicle-466722-p5)"
+
+# 2. On a machine with no Android toolchain (a fresh codespace), stage one.
+./scripts/setup-android-sdk.sh
+
+# 3. Build the signed APK. Also rewrites /public/.well-known/assetlinks.json
+# with this keystore's SHA-256 fingerprint.
+KEYSTORE_PASSWORD="$SOLANA_MOBILE_KEYSTORE_PASSWORD" ACCEPT_ANDROID_SDK_LICENSES=1 \
+ ./scripts/build-apk.sh
+
+# 4. Deploy three.ws so the assetlinks file is live for this key, then confirm
+# Google can see it (deploy runbook: CLAUDE.md, or docs/ops/gcp-production.md).
+curl -fsSL https://three.ws/.well-known/assetlinks.json | jq .
+curl -fsSL 'https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://three.ws&relation=delegate_permission/common.handle_all_urls'
+
+# 5. Submit.
+SOLANA_KEYPAIR=~/.config/solana/publisher.json \
+DAPP_STORE_API_KEY='<portal API key>' \
+./scripts/publish.sh
+```
+
+[scripts/publish.sh](../solana-mobile/scripts/publish.sh) checks that assetlinks is reachable, refuses a `versionCode` it already shipped from this machine, passes the API key over stdin so it never appears in a process listing, uploads the APK, mints the release NFT, and submits for review. If the upload dies part way through, resume it with `npx --no-install dapp-store resume --release-id <id>` rather than starting over.
+
+For a later release, bump `appVersionCode` and `appVersion` in [solana-mobile/twa/twa-manifest.json](../solana-mobile/twa/twa-manifest.json) (or pass `VERSION_CODE` / `VERSION_NAME`), then repeat steps 3 and 5. The store rejects a reused `versionCode`.
+
+Releases are run locally by the owner. This repo does not use GitHub Actions.
+
+## Step 4 is not optional
+
+Digital Asset Links are what make the app run full-screen. Until `https://three.ws/.well-known/assetlinks.json` serves the fingerprint of the key that signed the APK, Chrome cannot verify the Trusted Web Activity and falls back to a custom tab with a visible address bar, which reviewers see as an unfinished app.
+
+Two traps, both observed on 2026-08-28:
+
+- **The header must be short-lived.** `.well-known/*` is served with `max-age=3600`. A day-long TTL means a rotated key stays unverified for up to a day after the deploy.
+- **Chrome caches a failed verification.** After the correct assetlinks goes live, an already-installed app can keep showing the address bar until Chrome's cache clears. Force it with `adb shell pm clear com.android.chrome`, or `adb shell pm verify-app-links --re-verify ws.three.app` followed by `adb shell pm get-app-links ws.three.app`, which should print `three.ws: verified`.
+
+## Listing media
+
+Everything the portal asks for is generated and committed under [solana-mobile/publish/media/](../solana-mobile/publish/media):
+
+```bash
+npm run build:dapp-store-media # icon.png, banner.png, feature.png, editors-choice.png
+npm run build:dapp-store-previews # screen-1..5.png (the carousel)
+```
+
+`build:dapp-store-media` writes the 512x512 icon from the shipped app mark, the 1200x600 banner (the wordmark drawn in a browser against the site's own Space Grotesk files, so store type matches product type), the 1024x500 feature graphic (a live capture of a real agent page), and the 1200x1200 Editor's Choice card for the store's featured carousel.
+
+`build:dapp-store-previews` builds the five 1080x1920 previews as one 5400x1920 composition and slices it. Four of its nine phones sit exactly on a seam, so each upload carries one whole screen plus the two halves it shares with its neighbours and the strip reads as a single photograph while scrolling. **Upload them in numbered order** or the halves stop lining up. Every phone holds a real capture of three.ws at Seeker resolution; nothing is mocked or drawn to look like product UI.
+
+Two useful flags: `--origin=http://localhost:3000` captures the working tree instead of production (the dev server proxies `/api` to production, so the data stays real), and `--keep-raw` also writes the untouched captures to `publish/media/raw/` for inspection.
+
+To ship true on-device frames instead, drop 1080x1920 Seeker captures into `publish/media/device/` as `screen-1.png` … `screen-5.png` and rerun: each one replaces its live capture and the carousel is rebuilt around it. Frame-by-frame guidance is in [solana-mobile/docs/ASSETS.md](../solana-mobile/docs/ASSETS.md).
+
+## Verifying a build before submitting
+
+Most of the app can be checked in a stock Android emulator; the recipe is in [solana-mobile/README.md](../solana-mobile/README.md#emulator-qa). What the emulator does prove: install, full-screen launch, home-screen shortcuts, app-link verification state, the service worker registering, the MWA association reaching a wallet (with Solana Mobile's reference wallet sideloaded), and that the share target is registered with the right MIME types.
+
+What it cannot prove, and therefore what a physical Seeker is still for:
+
+- **The Seed Vault sheet itself**, and a completed one-tap SIWS sign-in. The emulator's Chrome shows an unverified-intent interstitial that interrupts the MWA handshake; a verified TWA on current Chrome does not.
+- **A real share.** `adb shell am start --grant-read-uri-permission` cannot confer a MediaStore URI grant, so the receiving app throws `SecurityException` before any web code runs. A genuine share from Photos grants the URI first. The web half of that flow is covered by `tests/share-target.test.js` and by the live `POST /create/share` fallback.
+- **A mainnet transaction** approved in the secure element.
+
+## After submitting
+
+Review results arrive by email from `[email protected]` within 3 to 5 business days; the portal dashboard shows status in the meantime. On approval, check that the public listing renders all five screenshots and the feature graphic, then add a [data/changelog.json](../data/changelog.json) entry announcing it.
+
+---
+
+<a id="sec-405"></a>
+
+> **Source:** `docs/seeker-submission-day.md` · [↑ table of contents](#table-of-contents)
+
+# Submission day: getting three.ws onto the Seeker dApp Store
+
+Everything the owner personally needs to do on submission day, in order, with every value inlined so you never have to open a file or a terminal. Budget about 90 minutes, most of it waiting on uploads and the phone.
+
+The engineering runbook is [Publishing to the Solana dApp Store](#sec-404); this page is the human half of it. Tick boxes as you go.
+
+## Before you start
+
+Status as of 2026-08-28: publisher profile and KYB **Approved**, signed APK built, release key backed up, and the site verified so the app runs full-screen. What is left is this page.
+
+- [ ] A laptop with the Publisher Portal open: <https://publish.solanamobile.com>
+- [ ] Your publisher wallet in a browser extension (Phantom, Solflare, or Backpack)
+- [ ] **0.25 SOL** in that wallet. The App NFT, the release NFT, and the ArDrive uploads come out of it; 0.2 is the floor, so leave headroom.
+- [ ] Your Seeker, charged, signed into Seed Vault, on wifi
+- [ ] A password manager entry ready for the API key you are about to create
+
+If the portal's Sumsub panel still reads "business verification is in progress" while the **Status** field reads **Approved**, go by the Status field: that is what gates minting. Only if a step actually refuses is the banner worth waiting on.
+
+Already done, nothing to redo: publisher profile and KYB (Approved 2026-08-27), the signed APK, the release key, and the site side (`three.ws` is verified for the app, so it runs full-screen).
+
+---
+
+## Step 1. Fund the publisher wallet
+
+In the portal, connect the wallet you want to own this listing forever. Every future release is signed by it, so use a wallet you control long-term, not a burner.
+
+- [ ] Wallet connected in the portal (as of 2026-08-28 this is the Phantom wallet ending `krgd`)
+- [ ] Balance shows at least 0.2 SOL
+- [ ] Storage provider set to **ArDrive** (the recommended default)
+
+---
+
+## Step 2. Add the dApp
+
+**Add a dApp → New Dapp.** Not "Import Dapp": that one is for an app whose Publisher and App NFTs already exist on-chain, from the retired CLI flow. three.ws has never minted those, so there is nothing to import and New Dapp mints the App NFT fresh.
+
+Paste each value below exactly.
+
+**Basics**
+
+| Field | Value |
+|---|---|
+| App name | `three.ws` |
+| Android package | `ws.three.app` |
+| Website | `https://three.ws` |
+| Privacy policy | `https://three.ws/legal/privacy` |
+| License / EULA | `https://three.ws/legal/eula` |
+| Copyright | `https://three.ws/legal` |
+| Terms of Use | `https://three.ws/legal/tos` |
+| Contact email | `[email protected]` |
+| Support email | `[email protected]` |
+| Languages | `English` |
+| Countries | `All countries` |
+
+The portal asks for **Terms of Use** and **Privacy Policy** under Compliance, and both must be public links: `https://three.ws/legal/tos` and `https://three.ws/legal/privacy`. The EULA and copyright links above are separate fields; do not paste the EULA into the Terms of Use box.
+
+On **Languages**: the app's interface auto-translates into 80+ locales, but this listing's text is English, so select English alone. Adding a language here without listing copy in it is what gets a listing flagged as incomplete.
+
+**Editor's Choice** (optional, the featured carousel on the store home screen). Fill it in: it costs one field and one upload.
+
+| Field | Value |
+|---|---|
+| Headline (50 char max) | `Turn a selfie into a 3D agent on Solana.` |
+| Graphic (1200x1200) | `solana-mobile/publish/media/editors-choice.png` |
+
+**Short description** (one line)
+
+```
+Mint a 3D agent to your Seed Vault. On-chain, Solana-native, signed by Seeker.
+```
+
+**Long description**
+
+```
+three.ws turns your Seeker into a 3D agent studio.
+
+Take a selfie, get a rigged 3D avatar, give it a voice and a personality, and put it on-chain in a wallet that never leaves the Seeker's secure element. Every signature happens inside Seed Vault; keys never touch the app layer.
+
+WHAT YOU CAN DO
+
+• Create from a selfie. One frontal photo (two optional side angles sharpen the likeness) becomes a textured, rigged, animation-ready avatar in about a minute. No photo? Describe the character in text, or upload a GLB you already have.
+• Give it a mind. Attach a personality, a voice, and skills, then talk to it. Your agent answers in 3D, on your phone, in your language.
+• Discover. Browse agents from the whole community in the marketplace: drag to orbit, tap to inspect, open any agent's page to chat with it.
+• Own it on-chain. Deploy an agent as a Metaplex Core asset on Solana, held by your wallet. Sell skills, take tips, and trade agents with USDC.
+• Embed anywhere. Every agent has a shareable URL and a one-line embed snippet for Telegram, X, or your own site.
+• Sign with Seed Vault. Wallet linking, transaction approval, and Sign-In With Solana all route through Mobile Wallet Adapter. No seed phrases, no browser extensions.
+
+WHY SEEKER
+
+three.ws talks to the Seeker's on-device wallet through the Mobile Wallet Adapter protocol, so signing lives inside the hardware-isolated secure element and sign-in is a single tap. The agents you create on Seeker show up on the three.ws web app the moment you sign in there: your wallet, your library, anywhere you sign in.
+
+OPEN BY DEFAULT
+
+three.ws is open source (github.com/nirholas/three.ws). Agents are Metaplex Core assets on Solana with an open manifest, so they are portable to any compatible marketplace or wallet. No vendor lock-in.
+
+REQUIREMENTS
+
+• A Solana wallet: Seed Vault on Seeker or Saga.
+• Camera permission (only for selfie capture; you can upload a photo instead).
+• A small amount of SOL to deploy an agent on-chain (typically under 0.01 SOL). Creating, chatting, and browsing are free.
+
+SUPPORT
+
+Questions, bug reports, or feature requests: [email protected] · https://three.ws/docs · github.com/nirholas/three.ws/issues
+```
+
+**What's new in this version**
+
+```
+First Seeker release of three.ws.
+
+• One-tap Sign-In With Solana through Seed Vault (Mobile Wallet Adapter).
+• Selfie to rigged 3D avatar, captured with the on-device camera.
+• Deploy an agent on-chain as a Metaplex Core asset held by your wallet.
+• Marketplace of community agents, each with a live 3D viewer and chat.
+• Embed any agent in Telegram, X, or your own site with one URL.
+
+Built for Seeker. Signed by Seed Vault. Seed phrases never leave the secure element.
+```
+
+**Testing instructions for the reviewer** (paste as-is; reviewers follow this literally)
+
+```
+1. Open the app on a Seeker or Saga. It launches full-screen into three.ws.
+2. Long-press the app icon: the Create, Discover, and My agents shortcuts
+ open /create, /marketplace, and /my-agents inside the app.
+3. Tap "Sign in with Seed Vault" in the top bar. A single Seed Vault sheet
+ appears (Sign-In With Solana). Approve. The bar shows your shortened
+ address; the app is signed in via POST /api/auth/siws/verify.
+4. Discover: /marketplace loads the agent grid from
+ /api/marketplace/agents. Tap an agent to open its page; the 3D viewer
+ renders it in WebGL. Drag to orbit.
+5. Create: /create/selfie asks for camera permission, captures one frontal
+ selfie (left and right angles optional), uploads to
+ /api/avatars/reconstruct, and polls /api/avatars/regenerate-status
+ until the rigged avatar is ready (about 90 seconds).
+6. On-chain: from an agent you own, "Deploy on Solana" mints a Metaplex
+ Core asset to the connected wallet. Fund it with at least 0.01 SOL on
+ mainnet first; the Seed Vault sheet approves the transaction.
+No off-chain test accounts are required: auth is wallet-only.
+```
+
+**Images.** All nine are ready to upload from the repo at `solana-mobile/publish/media/`:
+
+| Upload slot | File |
+|---|---|
+| App icon (512x512) | `icon.png` |
+| Banner (1200x600) | `banner.png` |
+| Feature graphic (1024x500) | `feature.png` |
+| Editor's Choice graphic (1200x1200) | `editors-choice.png` |
+| dApp preview 1 (1080x1920) | `screen-1.png` |
+| dApp preview 2 | `screen-2.png` |
+| dApp preview 3 | `screen-3.png` |
+| dApp preview 4 | `screen-4.png` |
+| dApp preview 5 | `screen-5.png` |
+
+**Upload the five previews in numbered order.** They are one 5400x1920 picture cut into five, with four phones sitting on the creases, so out of order they stop lining up. The portal wants matching dimensions across previews, and all five are 1080x1920 portrait. Open `solana-mobile/publish/media/carousel.png` to see the whole strip at once.
+
+- [ ] Every field above pasted
+- [ ] Four brand images and five previews uploaded, previews in order 1 to 5
+- [ ] Saved, and the **App NFT minted** (you will approve one wallet transaction)
+
+---
+
+## Step 3. The phone check (previews are already built)
+
+The five previews are generated, committed, and listed in Step 2. Every phone in them holds a real capture of three.ws rendered at Seeker resolution, which is exactly what the app draws, and the frames are composed into one continuous strip. Nothing here is mocked. You do not need to capture anything to submit.
+
+**If you would rather ship true on-device captures**, take them and the generator will use them instead of capturing the web app, keeping the same carousel design:
+
+1. Settings → Display → turn on gesture navigation, so no navigation bar crosses the bottom.
+2. Open the app and capture with Power + Volume-Down: the home screen, the marketplace grid, an agent with the 3D viewer, the Seed Vault sheet (while it shows `three.ws` and a non-empty `Nonce:` line), and the selfie capture screen.
+3. Copy them into `solana-mobile/publish/media/device/` as `screen-1.png` through `screen-5.png`, 1080x1920 each.
+4. Run `npm run build:dapp-store-previews`. The five uploads are rebuilt around your captures.
+
+Rules that get a listing rejected either way: no placeholder or mocked UI, no other company's branding in frame, no notification shade pulled down, nothing personal in the status bar.
+
+While you have the phone in hand, confirm these four (they are the last unchecked boxes in the submission checklist):
+
+- [ ] The app opens full-screen with no browser address bar
+- [ ] Sign-in shows **one** Seed Vault sheet, not connect-then-sign
+- [ ] Long-pressing the icon offers Create / Discover / My agents
+- [ ] Share a photo from Photos into three.ws and confirm it opens the selfie flow with the photo attached
+
+---
+
+## Step 4. Create the API key
+
+Portal → **Settings → API Keys → create**.
+
+- [ ] Key created
+- [ ] Saved in your password manager (it never goes in the repo, and it is shown once)
+
+---
+
+## Step 5. Submit
+
+Hand me the API key and say "submit the Seeker release" and I run it. Or do it yourself from the repo:
+
+```bash
+cd solana-mobile
+gcloud secrets versions access latest --secret three-ws-seeker-release-keystore \
+ --project aerial-vehicle-466722-p5 | base64 -d > android.keystore
+export SOLANA_MOBILE_KEYSTORE_PASSWORD="$(gcloud secrets versions access latest \
+ --secret three-ws-seeker-keystore-password --project aerial-vehicle-466722-p5)"
+KEYSTORE_PASSWORD="$SOLANA_MOBILE_KEYSTORE_PASSWORD" ACCEPT_ANDROID_SDK_LICENSES=1 \
+ ./scripts/build-apk.sh
+SOLANA_KEYPAIR=~/.config/solana/publisher.json \
+DAPP_STORE_API_KEY='<the key from Step 4>' \
+./scripts/publish.sh
+```
+
+The APK being submitted is `three.ws` **1.0.0**, versionCode **1**, package `ws.three.app`, 4.1 MB.
+
+- [ ] Submitted, and the portal shows the release as pending review
+
+---
+
+## Submitted: 2026-08-28
+
+v1.0.0 (versionCode 1) went in on 2026-08-28 and sits at **In Review**. What the portal recorded:
+
+| | |
+|---|---|
+| Release | `#331044442814`, v1 |
+| Package / SDK | `ws.three.app`, 23 to 36 |
+| APK | 3.95 MB, from `https://github.com/nirholas/three.ws/releases/download/v1.0.0/three-ws-release.apk` |
+| Release NFT mint | `25YeiFrv…khvcDDhQ` |
+| App collection | `GHJv3tR6…LUJSzTnD` |
+| Mint transaction | `3aCYSrDe…1gxSDdZj` |
+| Storage | Cloudflare R2 |
+
+Two things on that page look alarming and are not. The **Languages** list runs to hundreds of entries because Android reports every locale bundled in the APK's resources, and android-browser-helper brings AndroidX's whole translation set with it; it has nothing to do with the Languages field on the listing form. The two **permissions** are `POST_NOTIFICATIONS` (push) and the dynamic-receiver permission Android generates for anything targeting SDK 34 or later.
+
+The APK was uploaded by URL rather than by file, from the public GitHub release cut for this submission. Keep that release in place: the portal stores its own copy, but the link is the provenance record for which bytes were reviewed.
+
+## After you submit
+
+Review results arrive by email from `[email protected]` in **3 to 5 business days**. The portal dashboard shows status meanwhile.
+
+On approval:
+
+- [ ] Open the public listing and check all five screenshots and the feature graphic render
+- [ ] Tell me, and I will add the changelog entry announcing it to holders
+
+## If something goes wrong
+
+| What you see | What it means |
+|---|---|
+| Portal rejects the APK's package name | It expects `ws.three.app`. Do not change it; it is baked into the signing identity. |
+| "versionCode already used" | Only on a second release. Tell me and I bump it. |
+| The app shows a browser address bar | Digital Asset Links did not verify. Tell me; it is a site-side fix, not a rebuild. |
+| Upload dies part way | Resume it rather than restarting: `npx --no-install dapp-store resume --release-id <id>` |
+| Anything else | Send me the exact error text and I will pick it up. |
+
+---
+
+<a id="sec-406"></a>
> **Source:** `docs/selfie-to-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -84735,19 +88788,19 @@ Every other surface on three.ws (agents, the marketplace, Play worlds, talking-a
## How it works
-The client half lives in three modules the page imports on demand: [`src/selfie-capture.js`](../src/selfie-capture.js) (camera and upload UI), [`src/selfie-refine.js`](../src/selfie-refine.js) (`assessPhoto` / `refineSelfie`), and [`src/selfie-pipeline.js`](../src/selfie-pipeline.js) (the bridge to the backend). A fourth module, [`src/face-quality.js`](../src/face-quality.js), runs a live 468-point face mesh for framing feedback. Every quality threshold those modules apply lives in one shared, unit-tested module, [`src/selfie-gates.js`](../src/selfie-gates.js): each number is traced in its header comment to a real reconstruction-pipeline failure mode (the worker's no-face rejection, the 35-degree morph-yaw ceiling, provider blur failures, the dim/backlit band from the robustness benchmark), so the client rejects a shot for the same reasons the backend would.
+The client half lives in three modules the page imports on demand: [`src/selfie-capture.js`](../src/selfie-capture.js) (camera and upload UI), [`src/selfie-refine.js`](../src/selfie-refine.js) (`assessPhoto` / `refineSelfie`), and [`src/selfie-pipeline.js`](../src/selfie-pipeline.js) (the bridge to the backend). A fourth module, [`src/face-quality.js`](../src/face-quality.js), runs a live 468-point face mesh for framing feedback. All three MediaPipe consumers (face mesh, segmenter, face detector) load `@mediapipe/tasks-vision` from our own bundle and resolve the WASM runtime and model files through [`src/shared/mediapipe-assets.js`](../src/shared/mediapipe-assets.js), which serves the vendored copy under `public/vendor/mediapipe/` first and only then falls back to a CDN, so a blocked `cdn.jsdelivr.net` no longer disables the scanner. Every quality threshold those modules apply lives in one shared, unit-tested module, [`src/selfie-gates.js`](../src/selfie-gates.js): each number is traced in its header comment to a real reconstruction-pipeline failure mode (the worker's no-face rejection, the 35-degree morph-yaw ceiling, provider blur failures, the dim/backlit band from the robustness benchmark), so the client rejects a shot for the same reasons the backend would.
Two of those numbers are measured rather than reasoned about. The blur floor (`BLUR_STDDEV_MIN`) is calibrated against six real portrait photographs framed as 720x1280 phone selfies and scored through the module's own math, sharp versus the reconstruction worker's exact `robustness.py` degradations: sharp faces read 22.8 to 39.4, a Gaussian blur of radius `longestEdge/220` reads 10.6 to 15.7, and a radius-10 smear reads 6.3 to 9.4. The floor sits at 12, in the empty band between the blurred and sharp populations. And because a blown-out face *raises* Laplacian response instead of lowering it, and averages back into the accepted band, neither the blur nor the mean-luma gate can see window glare on its own: `grayFaceStats` also reports `clippedFrac`, the share of the face crop pinned to near-white, gated separately by `CLIPPED_FRAC_MAX`.
-1. **Capture, in the browser.** `getUserMedia({ video: { facingMode: 'user', width: { ideal: 1280 }, height: { ideal: 1706 } } })` opens the front camera. A real-time wireframe overlay tracks head pose, yaw, centering, blur, luminance, and highlight clipping, and only unlocks the shutter when a face is found; the hint line names the single most actionable fix ("Face the camera straight on.", "Hold steady. The image is blurry.", "Too dark. Find better light.", "Too bright. Move out of direct light or turn away from the window.") until every gate passes. A 3-2-1 countdown fires, then `shoot()` draws the current video frame to a canvas and calls `canvas.toBlob(blob, 'image/jpeg', 0.92)`. This is a **single still**, not a video scan. Camera support is feature-detected; if none exists, the shutter is disabled and an "Upload instead" path takes any image file.
+1. **Capture, in the browser.** `getUserMedia({ video: { facingMode: 'user', width: { ideal: 1280 }, height: { ideal: 1706 } } })` opens the front camera. A real-time wireframe overlay tracks head pose, yaw, centering, blur, luminance, and highlight clipping, and only unlocks the shutter when a face is found; the hint line names the single most actionable fix ("Face the camera straight on.", "Hold steady. The image is blurry.", "Too dark. Find better light.", "Too bright. Move out of direct light or turn away from the window.") until every gate passes. A 3-2-1 countdown fires, then `shoot()` draws the current video frame to a canvas and calls `canvas.toBlob(blob, 'image/jpeg', 0.92)`. This is a **single still**, not a video scan. Camera support is feature-detected; if none exists, the shutter is disabled and an "Upload instead" path takes any image file. A photo shared into three.ws from the Android share sheet (the Seeker app or any installed PWA) is POSTed to `/create/share`, parked by `public/share-target-sw.js`, and lands here with `?shared=1`; the capture page reads those files once (`src/shared/share-target.js`), fills the frontal slot and then left and right, and strips the param so a reload does not look like a fresh share.
2. **Review the still.** The countdown leaves ~3 seconds for motion blur, a head turn, or a lighting change to land in the actual capture, so the frozen still is re-scored (`checkImageQuality`) against the same gates before you accept it. The review screen shows per-gate chips plus a verdict line; only a missing face disables "Use this" (mirroring the worker's one hard input rejection), everything else is a warning you can accept.
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-114).
+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`. Before any GPU work starts the handler pre-flights the caller's avatar library against its plan ceiling (`assertAvatarSlotAvailable`) and refuses a full library with `402 plan_limit`, so nobody waits ninety seconds for a mesh that could never be saved.
+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-116).
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-181): 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.
+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>`. A `done` job with no `resultAvatarId` means the server's materialize stage threw after the mesh was generated; that stage re-runs on every poll, so the client looks again up to three more times before treating it as a failure. If the materialization lost the quota race (another avatar landed while this one was generating), the server ends the job as `failed` with caller-facing copy rather than leaving it stranded at `done`. 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-187): 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
@@ -84801,20 +88854,20 @@ Request body: `name` (1-120, required), `photos` (1-6 image URLs or data URIs) *
- **Quality gating.** Only a frontal with no detectable face hard-blocks. Blur, illustrations, or multiple faces are surfaced as warnings you can proceed past.
- **Error handling.** Camera denial distinguishes `NotAllowedError` ("Camera access was denied... use Upload instead") from other failures. Job failures map to friendly messages (no face, content-safety flag, blur, service unavailable, timeout, out-of-memory). Poll tolerates up to 5 consecutive network errors with backoff before "Lost connection to the avatar engine." Rate limits (`429`) start a 60-second cooldown with a live countdown. Pending jobs resume across reloads.
- **Output.** glTF 2.0 GLB with a Mixamo-standard humanoid rig, 52 ARKit blendshapes, and 15 visemes. Private avatars return a short-lived signed `url`; `model_url` is the public CDN URL once you make it public.
-- **Error copy.** The worker classifies a failure as either the caller's input or a service fault. An input rejection ("no face detected in any of the provided photos") is relayed verbatim so the client can name the fix; a service fault is masked into neutral retry copy, because its raw text can carry a vendor name or an operator-only correlation id. Your visibility choice rides along to the Forge store, so a private capture never surfaces in a public gallery.
+- **Error copy.** The worker classifies a failure as either the caller's input or a service fault. An input rejection ("no face detected in any of the provided photos") or a plan refusal is relayed verbatim, and the status response carries `errorKind: 'input'` so the client shows that text as-is instead of rewriting an unrecognised message into generic "try a clearer photo" advice; a service fault is masked into neutral retry copy, because its raw text can carry a vendor name or an operator-only correlation id. Your visibility choice rides along to the Forge store, so a private capture never surfaces in a public gallery.
## Related
-- [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-181): 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-415) and [Lipsync](#sec-267): drive the finished avatar's mouth.
+- [Avatar reconstruction pipeline](#sec-116): the full engine: MediaPipe face-texture transfer, geometry morph, the fixed pre-rigged head template, and the Cloud Run worker.
+- [Avatar pipeline](#sec-115): the distinct Forge text-to-3D generation lane.
+- [Draft agent mint](#sec-187): the on-chain identity every finished reconstruction gets, the network flags, and the devnet proof script.
+- [Trait-based avatar builder](#sec-140): customize and dress the avatar after you scan it.
+- [Talking Avatar Video](#sec-433) and [Lipsync](#sec-279): 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-390"></a>
+<a id="sec-407"></a>
> **Source:** `docs/share-and-embed.md` · [↑ table of contents](#table-of-contents)
@@ -84880,13 +88933,13 @@ 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-187) 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-193) 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:
+If all you want on the page is the 3D avatar, without chat, voice, or any widget UI, [Avatar Artifact](#sec-109) 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>
@@ -84921,14 +88974,14 @@ To customize the preview image, change the agent's thumbnail in the editor.
## What's next
-- **Make your agent smarter** → [Skills system](#sec-399)
-- **Understand the technical embed options** → [Embedding guide](#sec-187)
-- **Payment and crypto questions** → [Do I need crypto?](#sec-179)
-- **Give it a permanent on-chain address** → [Register on-chain](#sec-477)
+- **Make your agent smarter** → [Skills system](#sec-417)
+- **Understand the technical embed options** → [Embedding guide](#sec-193)
+- **Payment and crypto questions** → [Do I need crypto?](#sec-185)
+- **Give it a permanent on-chain address** → [Register on-chain](#sec-497)
---
-<a id="sec-391"></a>
+<a id="sec-408"></a>
> **Source:** `docs/shared-utilities.md` · [↑ table of contents](#table-of-contents)
@@ -85027,6 +89080,41 @@ timeAgo('2026-07-29T10:00:00Z'); // "3m ago"
timeAgo(1783670400); // unix seconds, handled
```
+### Browser-side fallbacks: never depend on one host
+
+Four helpers exist so no page hinges on a single third-party host. Reach for
+them instead of writing a CDN URL, a gateway URL, or a price feed inline.
+
+```js
+import { fetchFirst, fetchFirstOrNull } from './shared/failover-fetch.js';
+import { getSolPriceUsd, getTokenPriceUsd, getBtcPriceUsd } from './shared/usd-price.js';
+import { ensureModelViewer, ensureModelViewerOrFallback } from './shared/model-viewer-loader.js';
+import { loadVision, visionWasmBase, modelUrl } from './shared/mediapipe-assets.js';
+import { uriCandidates } from './ipfs.js';
+import { readProvider } from './erc8004/chain-meta.js';
+```
+
+| Helper | Covers | Behaviour when a host is down |
+|---|---|---|
+| `fetchFirst(providers, opts)` | any ordered provider list | 4s per attempt, 60s cooldown on a failing provider, throws only when all miss |
+| `getSolPriceUsd` / `getTokenPriceUsd(mint)` / `getBtcPriceUsd` | USD quotes | 4 feeds each; returns the last real price, or null. Never a hardcoded rate |
+| `ensureModelViewerOrFallback(root)` | the `<model-viewer>` element | 3 CDNs, then every viewer in `root` becomes its poster image or a caption |
+| `loadVision()` / `visionWasmBase()` / `modelUrl(path)` | MediaPipe | module is bundled; runtime prefers `public/vendor/mediapipe`, then 2 CDNs |
+| `uriCandidates(uri)` | IPFS / Arweave content | one URL per gateway, including for a URL whose gateway was already chosen |
+| `readProvider(chainId)` | browser EVM reads | ethers `FallbackProvider` over every keyless node in `CHAIN_META`, quorum 1 |
+
+Two rules that are easy to get wrong:
+
+- **Resolve asset paths against `import.meta.url`, not the site root.** Inside a
+ third-party `<agent-3d>` embed a `/vendor/...` path resolves against the
+ *embedding* page and 404s. `new URL('../../vendor/mediapipe', import.meta.url)`
+ points at whichever origin served the module, which is what you want.
+- **A file under `public/` that is not a Vite input cannot import from `src/`.**
+ It ships as a raw copy, so the `/src/*` reference 404s in production
+ (`public/forever.js` keeps its feed list inline for exactly this reason).
+ Either register the page as a Rollup input in `vite.config.js` or stay
+ self-contained.
+
---
## Backend
@@ -85058,6 +89146,107 @@ a 400 or a `TypeError` is not retried. Pass `shouldRetry` to override.
hand-rolled `sleep(base * 2 ** attempt)` loops had no jitter at all, so a shared
upstream blip re-synchronized every caller into the same retry wave.
+### `api/_lib/upstream-fetch.js`: the one fetch for third-party calls
+
+```js
+import { fetchUpstream, fetchUpstreamJson, fetchAnyJson, lastGood } from './_lib/upstream-fetch.js';
+
+// Deadline (8s default), transient-only retries, Retry-After honoured, breaker.
+const body = await fetchUpstreamJson(url, {}, { timeoutMs: 6000, name: 'dexscreener' });
+
+// Equivalent mirrors, first one that answers wins; a dead mirror is benched.
+const { value } = await fetchAnyJson(['https://api.drand.sh/public/latest', 'https://api2.drand.sh/public/latest']);
+
+// Keep the page alive through a blip: serve the previous value, flagged stale.
+const { value: rows, stale } = await lastGood('llama:chains', () => fetchUpstreamJson(LLAMA));
+```
+
+A non-2xx response rejects with an `UpstreamError` carrying `status`, `url` and
+a body excerpt, so `isRetryableError` and handlers can branch on it. Solana and
+EVM RPC do not go through here: `api/_lib/solana/connection.js` and
+`api/_lib/evm/rpc.js` have method-aware rotation. Ordered lists of *different*
+providers (with per-provider parsers) use `fetchFirst` from
+`src/shared/failover-fetch.js` instead.
+
+Because every third-party call in `api/` passes through one of these three
+(`fetchUpstream`, `fetchFirst`, or the Solana connection), they are also where
+[Brownout](#sec-133) hooks in. Each attempt is recorded against the
+current request (`recordSource` from `api/_lib/brownout/`), and a `lastGood`
+hit records itself as `tier: 'stale'` with its age, which is what lets the
+response carry the `x-brownout` / `x-brownout-trace` headers saying which rung
+answered and how fresh it was. The same seam honours a declared fault
+(`faultFor(name)`): an `x-brownout-chaos` directive raises the fault in the
+shape of the real failure, from inside the same `try` the genuine outage would
+land in, so retries, `Retry-After` handling, cooldowns and the breaker all see
+it exactly as they would see the outage. `failover-fetch.js` and
+`connection.js` are isomorphic and load the brownout module lazily on the
+server only (the specifier is parked on `globalThis` so Rollup cannot fold it
+into the CDN bundle); in a browser both hooks are inert.
+
+### `api/_lib/cache.js`: `cacheWrapLastGood`
+
+```js
+import { cacheWrapLastGood } from './_lib/cache.js';
+
+// Fresh for 5 minutes; on a thrown refresh, the fleet-wide last-good copy (24h).
+const board = await cacheWrapLastGood('pump:board', 300, () => fetchBoard());
+const { value, stale } = await cacheWrapLastGood(key, 300, load, { withMeta: true });
+```
+
+Unlike `lastGood` above, the mirror lives in the shared store (Upstash), so a
+freshly started instance can ride out an outage on a value another instance
+fetched.
+
+### `api/_lib/solana/read-guards.js`: chain reads that survive a dead RPC
+
+```js
+import {
+ ataExists, blockhashKey, getRecentBlockhashInfo, mintDecimals, readBalanceOrNull,
+} from './solana/read-guards.js';
+
+const { blockhash } = await getRecentBlockhashInfo(conn, blockhashKey({ network: 'mainnet' }));
+const decimals = await mintDecimals(conn, usdcMint); // constant, no network read
+if (!(await ataExists(conn, ata))) ixs.push(createAssociatedTokenAccountIdempotentInstruction(...));
+const lamports = await readBalanceOrNull(conn, pubkey); // null means unknown, never zero
+```
+
+Every read here answers the question "what should this do when the chain cannot
+be read at all?", and each answer is different:
+
+- **Blockhash**: serve a cached one that is still inside its validity window.
+ Pass `{ forceFresh: true }` on an expired-blockhash retry so the retry means
+ something.
+- **Mint decimals**: USDC, USDT, wSOL and `$THREE` have fixed decimals, so the
+ common case never touches the network and cannot fail.
+- **ATA probe**: fail OPEN to "missing". This is safe **only** with
+ `createAssociatedTokenAccountIdempotentInstruction`; with the plain create, an
+ unnecessary create fails the whole transaction. Always pair the two.
+- **Balance**: `null` for unknown. Never let a caller read it as zero.
+
+Anything that cannot degrade raises `rpcUnavailableError`, which
+`respondRpcUnavailable` renders as a 503 with `Retry-After`, so a caller learns
+"ask again shortly" instead of a sanitized 500.
+
+### `api/_lib/lexical-rank.js`: the fallback for a search that cannot embed
+
+```js
+import { rankLexically } from './lexical-rank.js';
+
+const rows = rankLexically(query, docs, { limit: 20 }); // [{ id, score: null, lexicalScore, match: 'lexical' }]
+```
+
+Semantic search is the one place where a provider ladder is **wrong**: a stored
+vector space has one embedder, so another lane's vector is a different dimension
+in a different geometry. When the embedder is down, degrade the *method* instead
+of the provider. Every row is labelled `match: 'lexical'` with a null semantic
+score, so no caller can mistake the ordering for a vector one. Used by
+`/api/galaxy` and `/api/ibm/galaxy`.
+
+`api/_lib/embeddings.js` covers the other half: `embedPassagesAny(preferredTag,
+texts)` walks every configured embedder at **ingest** time (where no space is
+fixed yet) and returns the tag that actually answered, so the caller records the
+space it really got.
+
### `api/_lib/mem-cache.js` — bounded in-process cache
Backed by [`lru-cache`](https://www.npmjs.com/package/lru-cache).
@@ -85068,6 +89257,8 @@ import { createCache, cached } from './_lib/mem-cache.js';
const cache = createCache({ max: 512, ttlMs: 60_000 });
// Read-through with single-flight: concurrent misses share one load().
+// When load() throws, the last value it returned for this key (kept 30 min,
+// `staleMs`) is served instead; pass `staleMs: 0` where the error must surface.
const price = await cached(cache, mint, () => fetchPrice(mint));
// Per-entry TTL when lifetimes vary by key:
@@ -85125,6 +89316,50 @@ visitor-supplied chat transcripts.
## Operations
+### `scripts/check-fetch-timeouts.mjs`: no unbounded third-party call
+
+```bash
+npm run check:fetch-timeouts # wired into `npm run gate`
+node scripts/check-fetch-timeouts.mjs --json
+```
+
+Fails the gate on a `fetch()` that carries no deadline. A fetch with no signal
+has no deadline at all: undici's defaults run to minutes, so one upstream that
+accepts a connection and then stalls holds the request until the platform kills
+the invocation, and takes the request budget of every fallback behind it with
+it. In production that does not read as "an upstream was slow", it reads as a
+dead endpoint, a dead cron, or a page that spins forever.
+
+A call counts as bounded when it passes a `signal` or goes through a wrapper
+that supplies one (`fetchUpstream`, `fetchFirst`, `pumpFetchJson`, ...). An init
+object assembled earlier in the function counts too: the checker resolves
+`fetch(url, init)` back to where `init` was built. Only the deadline is
+enforced, deliberately: retries, provider ladders and last-good tiers are the
+right thing to add on top, but which one fits is a judgement call per call site,
+while a deadline never is.
+
+**Scope differs by directory.** In browser code (`src`, `public`, `workers`) the
+rule covers literal external hosts only, since a page's fetch of our own API is
+bounded by the page lifecycle and by `src/api.js`. Under `api/` it covers EVERY
+call, whatever the URL is, because the two shapes that hang in practice are
+invisible to a literal-host scan: a handler calling its own `/api/forge` (a real
+socket between two serverless instances, not a free local call) and a download
+of a provider result URL that only exists at runtime. Three exemptions there,
+each for a call that cannot hang or is already bounded elsewhere: a `data:` URL
+(no socket), a client snippet quoted as a string (it runs in a browser), and a
+wrapper that spreads its caller's `init` (the deadline is the caller's, and a
+second one would silently shorten it). Two shapes are never counted as calls at
+all: a `fetch(` that sits inside a string literal (a usage example shipped as
+data in an API response), and a member call such as `client.fetch(...)`, which
+is somebody else's method rather than the global `fetch`.
+
+The checker reads each call's real extent by balancing parentheses rather than
+scanning a fixed window, because `signal` is conventionally the last key of an
+options object and a windowed check reports a bounded call as unbounded exactly
+when its options are longest. `tests/check-fetch-timeouts.test.js` covers that
+case: a checker that silently stops catching things is worse than no checker,
+since the gate keeps passing while the protection erodes.
+
### `scripts/check-cron-drift.mjs` — cron config vs. reality
Validates every cron expression in `vercel.json` with
@@ -85148,7 +89383,217 @@ paused during an incident and never resumed, failed silently.
---
-<a id="sec-392"></a>
+<a id="sec-409"></a>
+
+> **Source:** `docs/shipfeed.md` · [↑ table of contents](#table-of-contents)
+
+# The ship log: release notes joined to the code that shipped them
+
+Every project keeps two records of the same work.
+
+The **commit log** is complete and unreadable. The **changelog** is readable and incomplete. On three.ws both are published, both are pushed to the holder Telegram channel, and until now neither knew the other existed. The same afternoon's work reached the same channel twice, in two voices, with nothing saying it was the same work.
+
+The ship log is the join. Live at **[three.ws/ship](https://three.ws/ship)**, served as data at **[/api/ship/feed](https://three.ws/api/ship/feed)**, and computed by an open-source package, **[@three-ws/shipfeed](../packages/shipfeed/README.md)**, that works on any repository.
+
+It answers two questions no changelog and no `git log` can answer alone:
+
+1. **Which commits produced this release note?**
+2. **What shipped that nobody ever wrote up?**
+
+---
+
+## How it works
+
+```
+GitHub /repos/nirholas/three.ws/commits public/changelog.json
+ (through fetchUpstream: deadline, (baked into the running
+ retry, breaker, last-good) image by every deploy)
+ │ │
+ └──────────────┬───────────────────────────┘
+ ▼
+ @three-ws/shipfeed
+ parse ──▶ classify ──▶ link ──▶ group ──▶ render
+ │
+ ┌──────────────┼───────────────────────┐
+ ▼ ▼ ▼
+ /api/ship/feed /ship page the holder Telegram lanes
+ (JSON, MD, RSS) (provenance footer + noise filter)
+```
+
+### 1. Parse
+
+Full Conventional Commits 1.0.0, plus revert subjects, GitHub's merge subjects, and git trailers. `feat(resilience): ...` becomes a headline a reader can parse ("Feature · resilience") instead of the raw type prefix the commit feed used to print. A subject that follows the older `Avatar Studio: 122 sliders` house style keeps that convention; a subject with no convention at all is reported honestly rather than mangled.
+
+### 2. Classify
+
+Each commit gets an **audience** and a **signal** score from 0 to 1, with a reason attached to every point:
+
+| audience | who it is for |
+| --- | --- |
+| `holder` | someone who uses or owns a piece of the product |
+| `developer` | someone who builds against it |
+| `internal` | someone who works on it |
+
+Merge commits, `chore(deps):` bumps, and lockfile-only changes come back `noise: true`.
+
+### 3. Link
+
+Provenance without metadata. A `Changelog: <slug>` trailer in the commit always wins, and almost no commit has one, so the fallback has to earn its answer from four signals:
+
+1. **A time window.** A release note is written the day its work lands, so only commits within `windowDays` (default 4, plus one day of lead) are candidates.
+2. **IDF-weighted term overlap.** Shared rare words ("meshopt", "settle", "fingerspelling") carry weight; shared common ones ("agent", "the", "fix") carry almost none. The similarity blends how much of the entry a commit covers with how much of the commit the entry contains, so a one-line commit can still explain a paragraph.
+3. **Tag agreement.** An entry tagged `fix` prefers a `fix:` commit.
+4. **Proximity.** Same-day work outranks work three days out.
+
+A commit belongs to at most one entry; an entry may claim many. On this repository the default threshold (0.26) links roughly two thirds of visible commits, and the reasons behind every link are published with it.
+
+### 4. Group
+
+Everything unclaimed is clustered into **ships**: bursts of commits separated by 90 minutes of quiet, each headlined by its own strongest commit. That section is the interesting one. It is the work that shipped and was never announced.
+
+---
+
+## The page
+
+**[three.ws/ship](https://three.ws/ship)** renders the whole feed:
+
+- four live counters (commits read, release notes, percentage linked to code, unannounced work) and a daily-commit sparkline
+- an audience filter: everything, developers, or product news only
+- every release note with its commits folded underneath, each showing its short sha, headline, audience, and a `why 41%` control that expands the exact reasons the link was made
+- an **Unannounced** section for the ships nothing claimed
+
+---
+
+## The API
+
+### `GET /api/ship/feed`
+
+Public, no auth, cached for 5 minutes.
+
+| param | values | default |
+| --- | --- | --- |
+| `limit` | 1 to 500 commits | 200 |
+| `audience` | `holder`, `developer`, `internal` | `internal` (everything) |
+| `format` | `json`, `markdown`, `rss` | `json` |
+| `explain` | a 7 to 40 character commit sha | none |
+
+```bash
+curl -s 'https://three.ws/api/ship/feed?limit=100&audience=holder' | jq '.stats'
+```
+
+```json
+{
+ "commits": 100,
+ "hidden": 22,
+ "releases": 24,
+ "linked": 53,
+ "orphans": 25,
+ "coverage": 0.679,
+ "byAudience": { "holder": 62, "developer": 27, "internal": 11 },
+ "velocity": [{ "date": "2026-08-27", "count": 61 }]
+}
+```
+
+Each release carries its commits, and each linked commit carries the receipt:
+
+```json
+{
+ "shortSha": "2771f41",
+ "headline": "Feature · forge",
+ "summary": "three more independent concept-image rungs",
+ "audience": "holder",
+ "signal": 0.86,
+ "confidence": 0.41,
+ "why": ["shared terms: painter, concept, providers", "type \"feat\" matches tag", "before the entry by 0.4d"]
+}
+```
+
+### `GET /api/ship/feed?explain=<sha>`
+
+One commit's full reasoning: every scoring rule that fired, and the release note it was attached to (or a plain statement that nothing claimed it).
+
+```bash
+curl -s 'https://three.ws/api/ship/feed?explain=65f3fe5' | jq '.classification.reasons'
+```
+
+A heuristic nobody can interrogate is a heuristic nobody should trust, which is why this endpoint exists alongside the feed.
+
+### Feed formats
+
+```bash
+curl -s 'https://three.ws/api/ship/feed?format=markdown' > RELEASES.md
+curl -s 'https://three.ws/api/ship/feed?format=rss' # a feed reader, with commits inline
+```
+
+---
+
+## What changed in the Telegram channel
+
+Two lanes post to the holders' channel, and they now share this one join.
+
+**Release announcements** (`/api/cron/changelog-push`, every 20 minutes) carry a provenance footer:
+
+```
+Update: Text-to-3D now has five independent image sources behind it
+
+Every text-to-3D generation starts by painting a concept image...
+
+shipped in 4 commits ← links to the GitHub compare view for the range
+
+three.ws/changelog/2026-08-27-text-to-3d-... · 2026-08-27 · #fix #infra
+```
+
+The footer is best-effort by design: if GitHub cannot be read at that moment, the announcement goes out without it rather than not going out.
+
+**The raw commit feed** (`/api/cron/commit-feed-push`, every 5 minutes) reads its headline from the same parser, so a scoped commit now says "Feature · resilience" rather than "feat(resilience)", and it skips commits the classifier calls noise: merges, `chore(deps):` bumps, and lockfile-only changes. A skipped commit still advances the lane's state, so nothing is ever re-read, and the tick reports `{ posted, skipped }` so the drop is visible in the logs rather than silent.
+
+---
+
+## Use it on your own repository
+
+The package is standalone and dependency-free.
+
+```bash
+npx @three-ws/shipfeed --repo your/repo --changelog https://your.site/changelog.json
+npx @three-ws/shipfeed explain <sha>
+npx @three-ws/shipfeed stats
+npx @three-ws/shipfeed --local --markdown > RELEASES.md
+```
+
+```js
+import { shipfeed } from '@three-ws/shipfeed';
+
+const feed = await shipfeed({
+ repo: 'your/repo',
+ changelogUrl: 'https://your.site/changelog.json',
+ productScopes: ['checkout', 'search'],
+});
+```
+
+The full reference, including the linking internals exported for tuning, is in the [package README](../packages/shipfeed/README.md).
+
+---
+
+## Where the code lives
+
+| Piece | File |
+| --- | --- |
+| The package | [packages/shipfeed/](../packages/shipfeed/README.md) |
+| Feed endpoint | [api/ship/feed.js](../api/ship/feed.js) |
+| Provenance for the changelog lane | [api/_lib/ship-provenance.js](../api/_lib/ship-provenance.js) |
+| The page | [public/ship/index.html](../public/ship/index.html) |
+| Release announcements | [api/_lib/changelog-push.js](../api/_lib/changelog-push.js) |
+| Raw commit feed | [api/_lib/commit-feed-push.js](../api/_lib/commit-feed-push.js) |
+
+## Known limits
+
+- **GitHub's unauthenticated rate limit is 60 requests an hour per IP.** Set `GITHUB_TOKEN` on the service to raise it. Without one, a busy hour can leave the feed serving its 5-minute cache and the Telegram footer absent.
+- **Linking is a heuristic, and it publishes as one.** Every link carries a confidence and its reasons; a release note that legitimately found no code says so on the page rather than silently showing nothing.
+- **A commit older than the window can never be linked**, however well it matches. That is deliberate: the alternative is a note claiming work from a month it had nothing to do with.
+
+---
+
+<a id="sec-410"></a>
> **Source:** `docs/showcase.md` · [↑ table of contents](#table-of-contents)
@@ -85158,7 +89603,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-189) for the identity standard itself, [on-chain deployments](#sec-176) for the live feed of every registration as it lands (with no avatar filter), and [on-chain agents](#sec-311) for registering one yourself.
+Live at [three.ws/showcase](https://three.ws/showcase). Related reading: [ERC-8004](#sec-195) for the identity standard itself, [on-chain deployments](#sec-182) for the live feed of every registration as it lands (with no avatar filter), and [on-chain agents](#sec-322) for registering one yourself.
Code: [api/showcase.js](../api/showcase.js). Data comes from `erc8004_agents_index`, populated by the `erc8004-crawl` cron.
@@ -85217,14 +89662,14 @@ Each agent carries its on-chain identity plus explorer links resolved from the c
## Related
-- [ERC-8004](#sec-189): the identity standard behind every row here.
-- [On-chain deployments](#sec-176): the same registration stream without the 3D filter, including Solana Metaplex Core mints.
-- [Deploy agents on-chain](#sec-311): how to register an agent so it can appear here.
-- [Agent manifest](#sec-055): the metadata format whose 3D model field decides `has_3d`.
+- [ERC-8004](#sec-195): the identity standard behind every row here.
+- [On-chain deployments](#sec-182): the same registration stream without the 3D filter, including Solana Metaplex Core mints.
+- [Deploy agents on-chain](#sec-322): how to register an agent so it can appear here.
+- [Agent manifest](#sec-056): the metadata format whose 3D model field decides `has_3d`.
---
-<a id="sec-393"></a>
+<a id="sec-411"></a>
> **Source:** `docs/sign-language.md` · [↑ table of contents](#table-of-contents)
@@ -85392,7 +89837,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-523) exposes signing as an attribute. Present at boot, or toggled at runtime, it does the same thing:
+The [web component](#sec-543) 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>
@@ -85576,7 +90021,7 @@ Errors are plain: fewer than `min_frames` captured throws "Not enough signing ca
| [Non-manual markers](#the-face-is-grammar) | ARKit face blendshapes (most generated avatars have them) | The avatar still signs; it just loses the facial grammar |
| Left-handed signing | Nothing extra | Works on any rig that can sign |
-There is no rig allowlist. Any humanoid whose bone names the canonicalizer recognizes can sign; see [docs/animations.md](#sec-093) for how that mapping works.
+There is no rig allowlist. Any humanoid whose bone names the canonicalizer recognizes can sign; see [docs/animations.md](#sec-095) for how that mapping works.
---
@@ -85735,15 +90180,15 @@ None of this replaces a human interpreter. It makes an avatar legible to signers
- [/sign-mirror](https://three.ws/sign-mirror), camera-graded handshape practice, entirely on-device
- [`@three-ws/sign-language`](../packages/sign-language/README.md), the engine as an npm package
- [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-523), every `<agent-3d>` attribute including `sign-language`
+- [Animation Studio](#sec-094), the Spell box, exports, and share links
+- [docs/animations.md](#sec-095), clip formats and the retarget engine
+- [docs/web-component.md](#sec-543), 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-394"></a>
+<a id="sec-412"></a>
> **Source:** `docs/signals.md` · [↑ table of contents](#table-of-contents)
@@ -85813,7 +90258,7 @@ curl -s https://three.ws/api/signals/subscribe \
}'
```
-The feed's numeric `feed_id` comes from the marketplace read; the subscription's network is inherited from the feed, so you do not pass one.
+The feed's numeric `feed_id` comes from the marketplace read; the subscription's network is inherited from the feed, so you do not pass one. `feed_id` and a subscription `id` must be numeric row ids: anything else is refused with `400 invalid_feed` / `400 invalid_id` before any query runs. The live SSE stream (`GET /api/signals/stream`) likewise takes its network from the feed it streams, not from a query parameter.
Go live within your caps, then instantly kill if needed:
@@ -85842,22 +90287,22 @@ curl -s https://three.ws/api/signals/subscribe -H 'authorization: Bearer YOUR_TO
## Related
-- [Custody you can verify](#sec-171) - the spend caps, freeze, and audit trail the subscriber wallet pays and trades under
-- [Financial controls](#sec-222) - the plain-English rules and firewall the mirror respects
-- [Oracle](#sec-326) - the conviction engine and its own follow/copy tier
-- [x402](#sec-563) - the USDC payment protocol every signal settles over
-- [Trader card](#sec-423) - the verified track record that regresses a feed's edge
+- [Custody you can verify](#sec-177) - the spend caps, freeze, and audit trail the subscriber wallet pays and trades under
+- [Financial controls](#sec-229) - the plain-English rules and firewall the mirror respects
+- [Oracle](#sec-338) - the conviction engine and its own follow/copy tier
+- [x402](#sec-589) - the USDC payment protocol every signal settles over
+- [Trader card](#sec-441) - 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-395"></a>
+<a id="sec-413"></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-337) 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-349) 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?
@@ -86126,7 +90571,7 @@ The repository already has the fix. `/cdn/<key>` ([api/cdn-object.js](../api/cdn
What makes it non-trivial is that `thumbnailUrl()` in [api/\_lib/r2.js](../api/_lib/r2.js) is deliberately the single resolver for a stored thumbnail key, and its output goes to more places than a page:
-- `GET /api/explore` is a **documented public endpoint** (see [the API reference](#sec-096)), so its `image` field has third-party consumers and cannot become a site-relative path.
+- `GET /api/explore` is a **documented public endpoint** (see [the API reference](#sec-098)), so its `image` field has third-party consumers and cannot become a site-relative path.
- The same helper feeds the image baked into on-chain token metadata via `api/_lib/draft-mint.js`, which is written once and cannot be corrected afterwards.
The shape of the fix is therefore a second helper, absolute rather than relative, applied only to first-party page feeds and never to the metadata writer, plus an addition to [tests/thumbnail-url-guard.test.js](../tests/thumbnail-url-guard.test.js) so the split stays honest. Sizing the thumbnails is worth doing in the same pass: they are stored at 768x768 and painted into a 293px box.
@@ -86140,7 +90585,7 @@ Two things in the numbers above are real and are not being fixed by tuning:
---
-<a id="sec-396"></a>
+<a id="sec-414"></a>
> **Source:** `docs/sketchfab.md` · [↑ table of contents](#table-of-contents)
@@ -86176,8 +90621,9 @@ guard), when it was already uploaded, or when it failed three times.
**Brand safety.** The official account never publishes firearms or explicit
content, regardless of what the forge itself allows. A conservative
word-boundary denylist filters the selection query and re-checks before
-upload, and the platform's NemoGuard content classifier runs as a second
-layer. Blocked creations are parked in the ledger (`blocked`) and never
+upload, and the NemoGuard content classifier in `api/_lib/publish-safety.js`
+runs as a second, fail-open layer. Both are limits on what this account
+publishes, not on what users may forge. Blocked creations are parked in the ledger (`blocked`) and never
re-picked. Refinement children are also excluded from the creator-validated
tier, since their prompts are instructions, not titles.
@@ -86185,7 +90631,14 @@ tier, since their prompts are instructions, not titles.
Every published model carries:
-- **The generation prompt** at the top of the description, in quotes.
+- **The generation prompt** at the top of the description, in quotes. The
+ model's name is the prompt with a leading article stripped and clamped to
+ Sketchfab's display limit; a creation whose stored prompt is a placeholder
+ rather than a description (the image-to-3D path stores its route name,
+ `image-to-3d`, as the prompt) is named from its forge category instead
+ ("Forged Sci-Fi"), falling back to "3D Model" for the catch-all buckets, so
+ a winning image-derived model never reaches the account titled after a
+ route.
- **AI disclosure**: the `ai-generated` tag plus a plain statement that the
model was AI-generated on the three.ws Forge. Sketchfab has no dedicated
AI-content field, so tag + statement is the correct marking.
@@ -86230,7 +90683,7 @@ and [`api/_lib/sketchfab.js`](https://github.com/nirholas/three.ws/blob/main/api
---
-<a id="sec-397"></a>
+<a id="sec-415"></a>
> **Source:** `docs/skill-bundles.md` · [↑ table of contents](#table-of-contents)
@@ -86421,13 +90874,13 @@ agent's marketplace listing is the next step.
## Related
-- [Marketplace](#sec-277): 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
+- [Marketplace](#sec-286): how skills and assets are listed, bought, and settled
+- [Agent skills](#sec-061): what a skill is in the first place
+- [Agent wallets](#sec-074): where a bundle's payment lands
---
-<a id="sec-398"></a>
+<a id="sec-416"></a>
> **Source:** `docs/skill-royalties.md` · [↑ table of contents](#table-of-contents)
@@ -86633,14 +91086,14 @@ whose pending balance clears $0.01, so nobody pays gas to move dust.
## Related
-- [Skills marketplace](#sec-399): publishing, pricing, and installing skills
-- [x402 endpoints](#sec-559): every paid endpoint and who each one pays
-- [Money map](#sec-294): how value moves across the whole platform
-- [Remix royalties](#sec-377): the parallel royalty rail for 3D creations
+- [Skills marketplace](#sec-417): publishing, pricing, and installing skills
+- [x402 endpoints](#sec-584): every paid endpoint and who each one pays
+- [Money map](#sec-304): how value moves across the whole platform
+- [Remix royalties](#sec-390): the parallel royalty rail for 3D creations
---
-<a id="sec-399"></a>
+<a id="sec-417"></a>
> **Source:** `docs/skills.md` · [↑ table of contents](#table-of-contents)
@@ -87362,7 +91815,7 @@ 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-398).
+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-416).
Publish your own from the marketplace ("Publish a Skill") or `POST /api/skills` with `{ name, slug, description, category, tags, content }` (or `schema_json`).
@@ -87400,15 +91853,15 @@ Those filters are also the page URL, so [/marketplace?tab=skills&tag=solana&sort
## See also
-- [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-523) — embedding agents and passing skill attributes
+- [Architecture Overview](#sec-102) — how skills fit into the agent runtime
+- [Agent System](#sec-065) — the protocol bus and built-in tool system
+- [Web Component](#sec-543) — 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-400"></a>
+<a id="sec-418"></a>
> **Source:** `docs/smart-contracts.md` · [↑ table of contents](#table-of-contents)
@@ -88066,7 +92519,7 @@ On Base at typical gas prices (~0.001 gwei base fee), an agent registration runs
---
-<a id="sec-401"></a>
+<a id="sec-419"></a>
> **Source:** `docs/smart-money.md` · [↑ table of contents](#table-of-contents)
@@ -88080,7 +92533,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-326) 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-338) draws on, exposed as its own browsable surface.
## How it works
@@ -88088,7 +92541,7 @@ The page is a self-contained module inside `pages/smart-money.html` that polls `
The numbers are produced by a cron rollup (`api/cron/smart-money-rollup.js`) in three phases that write to `wallet_reputation`, `coin_smart_money`, and a `smart_money_scored` dedupe ledger:
-**Phase A: judge and fold.** Six hours after launch, a coin's outcome is binary: present in `pumpfun_graduations` is a win, otherwise a dud. For the top 60 buyers of each judged coin, per-wallet deltas are folded into `wallet_reputation`. An entry counts as **early** when the wallet's first buy is within 180 seconds of the coin's first trade, and a **dump** when the wallet sold at least half of what it bought.
+**Phase A: judge and fold.** Six hours after launch, a coin's outcome is binary: present in `pumpfun_graduations` is a win, otherwise a dud. Each run judges up to 400 coins, oldest first; the budget has to outrun the firehose (about 32k mints a day), because a coin that ages past the 14-day retention window unjudged is pruned and its buyers never fold into anyone's record. For the top 60 buyers of each judged coin, per-wallet deltas are folded into `wallet_reputation`. An entry counts as **early** when the wallet's first buy is within 180 seconds of the coin's first trade, and a **dump** when the wallet sold at least half of what it bought.
**Phase B: recompute reputation.** For each touched wallet the score is:
@@ -88160,19 +92613,20 @@ for (const c of conviction.slice(0, 5)) {
- **Auth.** The read APIs are public and require no account. The rollup cron is Bearer-authenticated with `CRON_SECRET`.
- **Rate limit.** 600 requests per minute per IP; over that returns 429.
- **Warm-up window.** A coin is not judged until roughly 6 hours after launch, so a very fresh coin shows "not scored yet." The per-coin read deliberately returns `200 { found: false }` rather than a 404 for an unscored mint.
-- **Empty and error states.** The feed, leaderboard, and watchlist each have designed empty copy ("No proven money on a fresh coin yet," "No wallets ranked yet"). A wallet with no history returns 404 and renders "No track record yet." A failed full refresh shows a stale-data reconnecting bar with a Retry button and escalates its message after repeated failures.
+- **Input validation.** A `wallet` or `mint` that is not a base58 Solana address is refused at the boundary with `400 invalid_wallet` / `400 invalid_mint`, so "that is not an address" and "no track record yet" stay different answers. Every error on the route, the wallet 404 included, carries the shared `{ error, error_description }` shape.
+- **Empty and error states.** The feed, leaderboard, and watchlist each have designed empty copy ("No proven money on a fresh coin yet," "No wallets ranked yet"). A wallet with no history returns 404 and renders "No track record yet." A failed full refresh shows a stale-data reconnecting bar with a Retry button and escalates its message after repeated failures. The watchlist tells a network failure apart from an honest "not on the radar": when every lookup fails to reach the API (or answers 5xx), the grid shows one "Couldn't reach the radar" panel with a Retry and keeps the saved list, and a single unreachable coin gets a "Couldn't load this one" card rather than being labelled unscored.
- **Two engines, one name.** This page reads `/api/pump/smart-money` (the graduation-outcome rollup). A sibling endpoint, `/api/intel/smart-money`, is a distinct funder-cluster and sybil-detection graph used by other surfaces. They answer related questions from different tables; do not conflate them.
## Related
-- [Oracle: the conviction engine](#sec-326) uses this proven-wallet ledger as its WHO pillar
-- [The trading surfaces](#sec-429) map, including the Coin Intelligence cross-coin trader board
-- [Coin Radar](#sec-374) and [Mission Control](#sec-416) surface the same pedigree read inline
+- [Oracle: the conviction engine](#sec-338) uses this proven-wallet ledger as its WHO pillar
+- [The trading surfaces](#sec-447) map, including the Coin Intelligence cross-coin trader board
+- [Coin Radar](#sec-387) and [Mission Control](#sec-434) 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-402"></a>
+<a id="sec-420"></a>
> **Source:** `docs/sniper-autonomy.md` · [↑ table of contents](#table-of-contents)
@@ -88245,7 +92699,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-427): recover the stake as soon as
+ [take-initials ladder](#sec-445): 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*
@@ -88345,8 +92799,8 @@ 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-427): the exit thesis the
+- [Agent Sniper](#sec-062): the trading pipeline the arms run on
+- [The 10 SOL trading experiment](#sec-445): the exit thesis the
ladder implements
- [`api/_lib/sniper-optimizer.js`](../api/_lib/sniper-optimizer.js): the tuning
rules, tier-scaled
@@ -88355,7 +92809,7 @@ tighter rather than rewarded for the hit rate.
---
-<a id="sec-403"></a>
+<a id="sec-421"></a>
> **Source:** `docs/social-layer.md` · [↑ table of contents](#table-of-contents)
@@ -88430,7 +92884,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-292) for that one.
+> [Money Feed](#sec-302) for that one.
## Follow graph
@@ -88490,14 +92944,29 @@ PUT /api/notifications/preferences → update it
Preferences are a category × channel matrix
([api/_lib/notify-prefs.js](../api/_lib/notify-prefs.js)): categories are
-sales, purchases, social, IRL, market alerts, creations, and account &
-security; channels are `in_app`, `push`, `email`, and `telegram`. Every
-channel is a per-category toggle (`in_app` defaults on everywhere, and is
-locked on for account & security so the bell record of security events never
-goes silent), edited from the Notifications panel in `/dashboard/settings`
+sales, purchases, social, IRL, market alerts, creations, companion
+deliveries, knocks at your door, and account & security; channels are
+`in_app`, `push`, `email`, `telegram`, and `avatar`. Every channel is a
+per-category toggle (`in_app` defaults on everywhere, and is locked on for
+account & security so the bell record of security events never goes silent),
+edited from the Notifications panel in `/dashboard/settings`
([src/dashboard-next/pages/settings.js](../src/dashboard-next/pages/settings.js)).
Bell client: [src/notifications.js](../src/notifications.js).
+The `avatar` channel is the corner companion walking on screen and saying the
+notification out loud. It is delivered client-side: the bell hands its unread
+inbox to [src/notification-herald.js](../src/notification-herald.js), which
+owns every rule (the per-category preference, freshness, per-id dedupe, a
+batch cap), and `GET /preferences` ships the server's `type_categories` map so
+the browser gates on the same type-to-category table push and email use. It
+defaults on only for the categories worth interrupting for (sales, creations,
+companion, knock, account & security) and off for the rest. A click-through
+from a spoken notification is tracked as `channel: "avatar"` on
+`POST /api/notifications/track`. `PUT /preferences` is a merge, not a
+replacement: a body carries only the keys being changed, omitting a key keeps
+its stored value, and `telegram_chat_id` must be a numeric chat id (send
+`null` or `""` to disconnect).
+
## Leaderboard, streaks, and badges: `/rankings`
One leaderboard across every surface, plus daily streaks and badges.
@@ -88509,7 +92978,11 @@ GET /api/leaderboard/unified?metric=creations&limit=50&offset=0
`metric` is one of `creations`, `remixes_received`, `launches`, `followers`,
`walk_distance` (limit 1..100, default 50). Sending the request with a session
or Bearer token pins your own row into the response even when you are outside
-the page window.
+the page window. `remixes_received` counts only finished derivatives made by
+someone else: both the parent and the child must be `status = 'done'`, and a
+creator's own refines of their own model (which also write
+`parent_creation_id`) never count, so nobody climbs that board by re-refining
+their own work.
The streak engine ([api/_lib/streaks.js](../api/_lib/streaks.js),
`recordDailyActivity()`) is called from sign-in, forge saves, diorama saves,
@@ -88581,16 +93054,16 @@ be replayed any time from the getting-started page.
## Related pages
-- [Money Feed](#sec-292): the value-movement ticker (`GET /api/feed`),
+- [Money Feed](#sec-302): the value-movement ticker (`GET /api/feed`),
a different feed from the activity feed documented here.
-- [Remix economy](#sec-377): what happens after someone finds your model in
+- [Remix economy](#sec-390): 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-404"></a>
+<a id="sec-422"></a>
> **Source:** `docs/solana-pumpfun.md` · [↑ table of contents](#table-of-contents)
@@ -88667,11 +93140,13 @@ SOLANA_RPC_URL_DEVNET=
`PUMPFUN_BOT_URL` is an **optional enrichment layer**, not a hard dependency. When it's unset (the prod default), the `pumpfun-signals` cron still runs off the live WS-fed `pumpfun_graduations` table and the `pf:claims` / `pf:whales` / `pf:mints` Redis lanes — only the bot's richer claim intel (tier, GitHub account age) is skipped. The `op=claims` read proxy and watch skills soft-degrade to empty when the bot is absent. Solana agents that don't use it pay no cost.
+The read proxy validates its request before that degrade, so the contract does not depend on the deployment's env: an unknown `op`, or `op=token` without `mint` / `op=creator` without `wallet`, is `400 validation_error` whether or not the bot is configured.
+
---
## Skills
-All registered through `registerPumpFunWatchSkills` in [src/agent-skills.js](../src/agent-skills.js).
+All registered through `registerPumpFunWatchSkills` in [src/agent-skills.js](../src/agent-skills.js). The skills await their platform fetches inline in the agent's turn, so every one is bounded (8 s by default) and a stalled feed fails the skill instead of leaving the chat mid-reply forever.
| Skill | MCP-exposed | Effect |
|---|---|---|
@@ -88735,7 +93210,7 @@ These are **off-chain** signals — flagged as such, not on-chain attestations.
## Widget
-The `pumpfun-feed` widget renders a stack of cards (claim or graduation) as an absolutely-positioned overlay on top of the 3D viewer. With `autoNarrate: true`, the avatar narrates each event through the protocol bus.
+The `pumpfun-feed` widget renders a stack of cards (claim or graduation) as an absolutely-positioned overlay on top of the 3D viewer. With `autoNarrate: true`, the avatar narrates each event through the protocol bus. Each card's trading-terminal links come from the shared builder in [src/shared/trading-terminals.js](../src/shared/trading-terminals.js) (`terminalLinks(mint)` and `referralOffers()`), the same one the copy pages use, so adding or re-pointing a terminal is one change. The overlay carries no inline event handlers (a broken token image hides through the `data-fallback="hide"` hook), which is what keeps it inside the site's CSP.
Studio config schema (validated in `widget-types.js`):
@@ -88753,7 +93228,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-405)), 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-423)), 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.
@@ -88777,7 +93252,7 @@ The MCP client and cron crawler are unit-tested with mocked `fetch` and `sql`. E
---
-<a id="sec-405"></a>
+<a id="sec-423"></a>
> **Source:** `docs/solana-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -88787,7 +93262,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-189) / [Reputation System](#sec-379) (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-057) (the why) and [ERC-8004](#sec-195) / [Reputation System](#sec-392) (the EVM how-to). If you haven't read those, start with [Agent Reputation](#sec-057) 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.
---
@@ -88863,7 +93338,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-378), 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-391), 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:
@@ -88956,7 +93431,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-379)) *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-392)) *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.
---
@@ -88972,7 +93447,7 @@ In the agent card, both registrations sit side by side as CAIP-style references
| Sybil defense | one review per wallet, no self-review | per-attester averaging + credential/verified tiers | capability + `min_reputation` gates, slashing |
| Read | MCP tool, REST, SDK, contract | Passport, `/api/agents/solana-reputation`, x402 | `agenc_*` MCP tools, SDK |
-The shapes differ; the purpose is identical — let an agent decide, before it pays, whether a counterparty is worth trusting. ([Why that matters →](#sec-056))
+The shapes differ; the purpose is identical — let an agent decide, before it pays, whether a counterparty is worth trusting. ([Why that matters →](#sec-057))
---
@@ -88988,14 +93463,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-378)**: 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-406)** — registering an agent as a Metaplex Core asset.
-- **[ERC-8004](#sec-189)** · **[Reputation System](#sec-379)** — the EVM side of the same idea.
+- **[Reputation Staking Market](#sec-391)**: 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-057)** — the trust problem both chains solve.
+- **[Solana agents](#sec-424)** — registering an agent as a Metaplex Core asset.
+- **[ERC-8004](#sec-195)** · **[Reputation System](#sec-392)** — the EVM side of the same idea.
---
-<a id="sec-406"></a>
+<a id="sec-424"></a>
> **Source:** `docs/solana.md` · [↑ table of contents](#table-of-contents)
@@ -89003,11 +93478,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-189) 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-195) 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-311).
+> Deploying many agents at once (server-side, into the three.ws Agents collection, with a live dashboard)? See [Deploy agents on-chain (bulk)](#sec-322).
---
@@ -89020,16 +93495,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-405)) |
+| 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-423)) |
| 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-384)) |
+| Credentialed attestations (SAS) | Live | [api/agents/sas/\[action\].js](../api/agents/sas/[action].js) (see [SAS attestations](#sec-398)) |
| 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-311) 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-322) 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.
@@ -89253,13 +93728,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-405) and [solana-pumpfun.md](#sec-404).
-- **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-384)).
+- **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-423) and [solana-pumpfun.md](#sec-422).
+- **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-398)).
## 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-311)).
+- **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-322)).
- **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.
@@ -89275,7 +93750,7 @@ A full ERC-8004-equivalent on Solana (Identity / Reputation / Validation as Anch
---
-<a id="sec-407"></a>
+<a id="sec-425"></a>
> **Source:** `docs/spatial-mcp.md` · [↑ table of contents](#table-of-contents)
@@ -89372,7 +93847,7 @@ The reference renderer is framework-free and reusable independent of three.ws:
</script>
```
-It applies `camera`/`environment`/`affordances`, plays `animation` when present, offers AR when `ar` (or the GLB) supports it, and shows a designed fallback for an unusable payload — never a blank frame.
+It applies `camera`/`environment`/`affordances`, plays `animation` when present, offers AR when `ar` (or the GLB) supports it, and never shows a blank frame: an unusable payload gets a designed fallback (`.spatial-empty`), a downloading GLB gets a skeleton under the viewer (`.spatial-loading`), and a GLB that cannot be fetched or decoded gets an error message that names the host, says what to check (reachable, https, `Access-Control-Allow-Origin`, a valid `.glb`), and offers a `.spatial-retry` button that re-renders in place (`.spatial-error`). The mount carries `data-spatial-state` (`empty`, `loading`, `ready`, `error`) so a host can style each state; the renderer ships no CSS of its own, so style those classes the way [`/spatial-mcp`](https://three.ws/spatial-mcp) does or the way your host already styles its own empty and error cards.
## Data minimization (required for store-safe adoption)
@@ -89406,7 +93881,7 @@ Free 3D Studio (`structuredContent.spatial`): `forge_free`, `text_to_avatar`, `m
---
-<a id="sec-408"></a>
+<a id="sec-426"></a>
> **Source:** `docs/specs/agent-trading.md` · [↑ table of contents](#table-of-contents)
@@ -89493,7 +93968,7 @@ Real routes (no mocks), server-side guards with tests (including the $THREE-sell
---
-<a id="sec-409"></a>
+<a id="sec-427"></a>
> **Source:** `docs/splat.md` · [↑ table of contents](#table-of-contents)
@@ -89558,13 +94033,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-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.
+- [Avatar creation](#sec-111) and [avatar pipeline](#sec-115) cover the mesh (GLB) avatar path.
+- [Scene Capture](#sec-137) 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-410"></a>
+<a id="sec-428"></a>
> **Source:** `docs/stage.md` · [↑ table of contents](#table-of-contents)
@@ -89705,7 +94180,7 @@ The show's running total is rolled on each tip as a convenience; if that bump fa
Every state on this surface is designed, because a live show has more failure modes than a static page:
-- **Realtime feed offline.** If no multiplayer server is configured or the socket cannot be reached after one retry, the connection pill honestly reads "feed offline" instead of pretending to be live. Captions, tips, and the leaderboard still work through the API.
+- **Realtime feed offline.** If no multiplayer server is configured or the socket cannot be reached after one retry, the connection pill honestly reads "feed offline · tap to retry" instead of pretending to be live, and tapping it reconnects. Tips and the leaderboard still work through the API; the caption you see is the last one the feed delivered. Asking a question while the feed is down tells you to reconnect first rather than silently dropping it.
- **No WebGL.** The venue swaps to an "audio and captions mode" card: you still hear the host, read every line, and can still tip.
- **No wallet on the host.** Tipping is disabled with a plain explanation rather than a failing transaction.
- **Not live yet.** Tips are refused client-side and server-side with "tips open when the host goes live".
@@ -89723,21 +94198,21 @@ The venue is split across two deployments, so it needs both halves wired:
| `MULTIPLAYER_SHARED_SECRET` | both | The HMAC secret for both directions of the bridge. Must match on both sides |
| `THREEWS_API_BASE` or `MULTIPLAYER_API_BASE` | realtime server | Where the room reads stage config and fetches host beats from. Defaults to the production API |
-The browser resolves the realtime server from, in order: `window.STAGE_SERVER_URL`, a `stage-server` meta tag, `VITE_STAGE_SERVER_URL` at build time, a forwarded development port, or the same host on port 2567 in local development. In production with none of these set, the page runs in feed-offline mode rather than hanging on a socket.
+The browser resolves the realtime server from, in order: `window.STAGE_SERVER_URL`, a `stage-server` meta tag, `VITE_STAGE_SERVER_URL` at build time, and then the chain every other live world uses ([`src/shared/game-server-url.js`](../src/shared/game-server-url.js)): localhost always talks to the local server on port 2567, otherwise the `game-server` meta tag the page carries ([`pages/stage.html`](../pages/stage.html) bakes in the production multiplayer service, exactly like `/play`), then `VITE_GAME_SERVER_URL`, then a forwarded development port. In production with none of these set, the page runs in feed-offline mode rather than hanging on a socket. The client subscribes to the host's frame with `listen` on the root state rather than `onChange` on the child, because the join resolves before the first state patch lands and the child has no decoder reference yet; it also registers its message handlers before any state work, because the room opens the show the instant the first person arrives and that first line must not be dropped.
## Related
-- [Agent wallets](#sec-072): the host wallet a stage provisions at creation and receives tips into.
-- [Lip-sync](#sec-267) and [Voice Lab](#sec-521): 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-300): the go-live and tip notifications a stage emits.
-- [Agora](#sec-075) and [IRL presence](#sec-259): the other rooms on the same realtime backbone, with the same presence discipline.
+- [Agent wallets](#sec-074): the host wallet a stage provisions at creation and receives tips into.
+- [Lip-sync](#sec-279) and [Voice Lab](#sec-541): the speech and mouth-shape machinery the host performs with.
+- [Agent abilities](#sec-011): the always-on Stage Show variant that runs the same ShowDirector inside an agent's own screen.
+- [Notifications](#sec-311): the go-live and tip notifications a stage emits.
+- [Agora](#sec-077) and [IRL presence](#sec-270): 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-411"></a>
+<a id="sec-429"></a>
> **Source:** `docs/start-here.md` · [↑ table of contents](#table-of-contents)
@@ -89771,9 +94246,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-272)
+**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-284)
-**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-258) or [Quick start →](#sec-373)
+**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-268) or [Quick start →](#sec-386)
---
@@ -89788,7 +94263,7 @@ Every page on the platform is one of four things. Knowing these will orient you:
| **Marketplace** | Where avatars (and shared agents) live | `/marketplace` |
| **Studio** | Where you assemble everything | `/studio` |
-For a deeper explanation of how agents and avatars differ, see [Agents vs. Avatars →](#sec-073)
+For a deeper explanation of how agents and avatars differ, see [Agents vs. Avatars →](#sec-075)
---
@@ -89796,16 +94271,16 @@ 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-272)** — create a 3D AI character in the browser, no code
-3. **[Share & embed](#sec-390)** — get the embed snippet and put your agent anywhere
-4. **[Do I need crypto?](#sec-179)** — honest answers to the wallet and payment questions
+1. **[Agents vs. Avatars](#sec-075)** — understand the two core concepts (5 min read)
+2. **[Make your first agent](#sec-284)** — create a 3D AI character in the browser, no code
+3. **[Share & embed](#sec-407)** — get the embed snippet and put your agent anywhere
+4. **[Do I need crypto?](#sec-185)** — 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-396).
+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-414).
-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-224).
+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-231).
-Curious what happens between the prompt and the model? [How the Forge works](#sec-241) tells the story in plain language; [the Forge pipeline](#sec-226) is the full engineering deep dive.
+Curious what happens between the prompt and the model? [How the Forge works](#sec-250) tells the story in plain language; [the Forge pipeline](#sec-233) is the full engineering deep dive.
---
@@ -89813,87 +94288,96 @@ 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-346) — 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-393)
-- **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-112) shows their reputation, wallet, and profile
-- **Running a live event in the world?** → [Live events in `/play`](#sec-340): 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-217): 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-339): 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-337): 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-395): 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-403): 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-259): 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-281) 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-377). Vote on the best community models and win the weekly board: [Forge-Off](#sec-225)
-- **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-296) — 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-153) — 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-442) 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-429) maps the solo stack (Radar, Coin Intelligence, Live Trade Feed, Watchlist, Mission Control); [trading arenas](#sec-425) covers tournaments, the theater, vaults, and swarms; [Oracle](#sec-326) 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-439)
-- **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-402), 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-171) — spend limits, freeze, Merkle proof-of-custody, and social recovery; [claim your wallet](#sec-423) turns any pump.fun track record into a public, provable Trader Card. Every real-funds feature sits behind the [risk acknowledgment](#sec-382) — read the [Risk Disclosure](https://three.ws/legal/risk) before committing anything
-- **Need a track record another app can verify?** → [Trader Passport](#sec-424): 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-181): 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-432) — 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-299) — 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-273) — 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-383) — 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-558) — 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-557) — 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-517) — 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-336): upgrade with a single on-chain payment in USDC, SOL, or $THREE (the platform coin takes 20% off); [hold-to-access](#sec-240) covers the separate hold-$THREE tier ladder; [the $THREE thesis](#sec-419) is the long-form case for the token with every utility, sink, listing, and risk in one place; [The First 19 Weeks](#sec-417) is the week-by-week record of everything shipped since the first commit; [the open-source ecosystem](#sec-312) maps every package, server, contract, and registry where the code lives
-- **Building a community perk?** → [Token-gated 3D embeds](#sec-421) — 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-232): 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-228): 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-308) has hundreds of CC0 props with live preview, AR placement, and direct GLB download
-- **Rendering avatars outside the viewer?** → [Media and render API](#sec-285): 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-483) is the guided walkthrough
-- **Uploaded an avatar that loads but never moves?** → [Rig Doctor](#sec-381): 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-290): 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-332): 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-376): 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-527): 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-522): 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-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-467): 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-398): 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-519) 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-410) covers shareable stages; [the Avatar Engines Atlas](#sec-110) is the factual survey of the engines in this space and which ones we animate
+- **Want to know why the avatars feel alive?** → [Procedural animation](#sec-359) — 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-144): 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-411)
+- **Want that character to tell you what actually matters?** → [The Companion](#sec-156): connect your own Telegram bot, calendar, inbox, or phone at [/companion](https://three.ws/companion), set the bar for what is worth interrupting you for, and a 3D character delivers it in person, wearing the avatar of whoever sent it. Also a desktop app, an SDK, a CLI, and an MCP server so your agents can reach you the same way
+- **Wondering who the little character in the corner is?** → [The agent shell](#sec-060) — 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-059), 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-114) shows their reputation, wallet, and profile
+- **Running a live event in the world?** → [Live events in `/play`](#sec-352): 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-223): 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-150): 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-351): 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-349): 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-413): 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-421): 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-270): 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-290) 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-390). Vote on the best community models and win the weekly board: [Forge-Off](#sec-232)
+- **Using ChatGPT?** → [AR in ChatGPT](#sec-142) 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-306) — 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-158) — 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-462) shows how every part works
+- **Want a full-body avatar assistant on your site instead?** → [Assistant widget](#sec-103) — 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-447) maps the solo stack (Radar, Coin Intelligence, Live Trade Feed, Watchlist, Mission Control); [trading arenas](#sec-443) covers tournaments, the theater, vaults, and swarms; [Oracle](#sec-338) is the conviction engine underneath all of it
+- **Want your agent to trade for you?** → [Agent Sniper](#sec-062) — 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-459)
+- **Wondering what stands between the chat agent and your wallet?** → [The agent runtime and transaction guard](#sec-058): 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-420), 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-177) — spend limits, freeze, Merkle proof-of-custody, and social recovery; [claim your wallet](#sec-441) turns any pump.fun track record into a public, provable Trader Card. Every real-funds feature sits behind the [risk acknowledgment](#sec-396) — read the [Risk Disclosure](https://three.ws/legal/risk) before committing anything
+- **Need a track record another app can verify?** → [Trader Passport](#sec-442): 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-187): 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-055): 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-450) — 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-106): 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-310) — 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-285) — 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-397) — 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-583) — 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-582) — 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-129) — 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-131) — `/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-130) — `/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-537) — 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-348): upgrade with a single on-chain payment in USDC, SOL, or $THREE (the platform coin takes 20% off); [hold-to-access](#sec-249) covers the separate hold-$THREE tier ladder; [the $THREE thesis](#sec-437) is the long-form case for the token with every utility, sink, listing, and risk in one place; [The First 19 Weeks](#sec-435) is the week-by-week record of everything shipped since the first commit; [the open-source ecosystem](#sec-323) maps every package, server, contract, and registry where the code lives
+- **Building a community perk?** → [Token-gated 3D embeds](#sec-439) — 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-239): 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-235): 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-139) has 106 rigged characters (one click into the Studio, Animation Studio, or an embed) and the [Object Library](#sec-319) has hundreds of CC0 props with live preview, AR placement, and direct GLB download
+- **Rendering avatars outside the viewer?** → [Media and render API](#sec-294): 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)
+- **Want the avatar in your terminal, or as your coding agent's face?** → [Terminal avatar](#sec-451): `npx @three-ws/tty-avatar <avatar id>` draws any avatar or agent body live in a terminal (truecolor half-blocks, braille, or plain ASCII, no browser or GPU), and `install-hooks --write` ties its moods to Claude Code so it thinks while the agent reads, works while it edits, and celebrates when it finishes
+- **Putting avatars in your build pipeline?** → [Avatar CLI](#sec-110): 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-503) is the guided walkthrough
+- **Uploaded an avatar that loads but never moves?** → [Rig Doctor](#sec-395): 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-299): 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-344): 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-389): 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-548): 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-542): 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-073): 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-008): 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-136): 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-487): 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-416): 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-053) counts only settled agent-to-agent USDC for paid skills, and [Viability](#sec-539) 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-054) turns a brand brief into a rigged avatar plus posed studio renders; [Living Stages](#sec-428) covers shareable stages; [the Avatar Engines Atlas](#sec-112) 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-345) has the logos, the usage rules, and the boilerplate (editorial use needs no permission), and [the partner ecosystem](#sec-329) maps every partner program to what the integration actually is
-- **Backing an agent with capital?** → [USDC agent vaults](#sec-518): 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-503): 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-166): 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-235): 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-176): 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-177): 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-375): hash-chained, on-chain-anchored records of every consequential agent decision, verifiable by anyone at /ledger
-- **Following Solana traders?** → [KOL Tracker](#sec-262): 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-300): the bell, the /notifications center, category filters, and the full inbox API
-- **Showing off your work?** → [The creator portfolio](#sec-168): 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-420): three.ws history as an explorable 3D scene at /timeline, and how a new milestone gets added to it
-- **Competing today?** → [Daily Match](#sec-173): live daily standings over real agent output (actions, trades, skill sales, launches), resetting 00:00 UTC
-- **Developer docs** → Read the [Introduction](#sec-258) for the full technical picture
-- **Contributing code?** → [Shared utilities](#sec-391) — 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-309) — the Agent Identity Studio and the pay-per-call 3D services other agents buy from us; demo identities at [/agent-identities](/agent-identities)
+- **Writing about us?** → [The press kit](#sec-358) has the logos, the usage rules, and the boilerplate (editorial use needs no permission), and [the partner ecosystem](#sec-341) maps every partner program to what the integration actually is
+- **Backing an agent with capital?** → [USDC agent vaults](#sec-538): 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-523): 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-171): 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-242): 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-182): 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-183): 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-388): hash-chained, on-chain-anchored records of every consequential agent decision, verifiable by anyone at /ledger
+- **Following Solana traders?** → [KOL Tracker](#sec-274): 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-064): /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-311): the bell, the /notifications center, category filters, and the full inbox API
+- **Something too important for a badge?** → [Herald](#sec-248): the open SDK behind /herald, where a 3D character walks onto the page and says it out loud, with an interrupt budget (importance floor, quiet hours, dedupe, batching), an accessible card for machines with no GPU, a rail so CI or an AI agent can reach the tab you have open, and a CLI that announces when your build finishes
+- **Want strangers to be able to reach you, but not for free?** → [Knock](#sec-273): a priced door at /knock/<username> that anyone, human or agent, can pay to get one message through; the USDC settles straight to your wallet, your companion delivers it in person, and every refusal happens before the payment
+- **About to pay for something?** → [Checkout companion](#sec-143): the browser extension that reads a payment page before you pay, why the arithmetic is never a model's job, and why it never reads a form field
+- **Curious what a website looks like as a place?** → [Portal](#sec-355): paste any address and walk it in 3D; sections become buildings sized by what they say, links become doors you step through, and the world downloads as a GLB, embeds in your page, or reaches an agent over MCP
+- **Did that re-export break the rig?** → [Model Diff](#sec-301): what actually changed between two GLBs, why a rename is not a rewrite, and the severity that tells you a dropped joint from a recolour
+- **Something broken on a page?** → [Feedback](#sec-228): telling the corner companion what went wrong, what the browser attaches for you, and the boundary that keeps untrusted text from ever reaching anything with write access
+- **Showing off your work?** → [The creator portfolio](#sec-174): 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-438): three.ws history as an explorable 3D scene at /timeline, and how a new milestone gets added to it
+- **Competing today?** → [Daily Match](#sec-179): live daily standings over real agent output (actions, trades, skill sales, launches), resetting 00:00 UTC
+- **Developer docs** → Read the [Introduction](#sec-268) for the full technical picture
+- **Contributing code?** → [Shared utilities](#sec-408) — 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
+- **Wondering what happens when a third-party service goes down?** → [Upstream resilience map](#sec-393): every external service this platform calls, what protects each call, and the degradation contract each endpoint is held to
+- **Your agent needs a face?** → [OKX.AI marketplace services](#sec-320) — 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-188) — 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-502) 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-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
+- **Want your agent to have a body?** → [Embodiment](#sec-194) — 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-522) 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-061) — 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-118) — 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
---
@@ -89901,55 +94385,60 @@ 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-180): 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-295): 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-304): 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-256): 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-230): 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-422): 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-303): what the platform already runs on NVIDIA silicon and what the program adds on top
-- [NVIDIA visibility map](#sec-307): 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-306): 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
-- [three.ws on Hugging Face](#sec-243): our organization account there, the community article on giving agents bodies and wallets, the published avatar rigs and the Space that renders them, and the checklist for publishing the next one
-- [The onboarding tier](#sec-310): 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-155): five audience-specific walkthroughs tying shipped features to concrete outcomes
-- [UX Flow Atlas](#sec-504): screen-by-screen traces of the platform's core flows, starting with onboarding and creation
-- [Demo routes](#sec-174): the canonical map of every `/demo/*` and `/demos/*` route
-- [Agent trading spec](#sec-408): the proposed agent trading capability contract
-- [ERC-8004 validation attestation](#sec-190): the attestation written when an agent registers on-chain
-- [zauth](#sec-565): 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-353): the vendored on-chain program reference behind the launch surfaces
-- [pump-fun-mcp at the edge](#sec-349): the Cloudflare Workers mirror of the pump.fun MCP endpoint
-- [Package extraction](#sec-328): 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-431): fixes organized by symptom
-- [The 3D viewer](#sec-520): 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-221): give an agent your Farcaster voice, proved with a wallet the account already verified, and revoke it in one click
-- [X memory seeding](#sec-530): 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-236): 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 ship log](#sec-409): how every release note is joined to the commits that shipped it, the public feed at /api/ship/feed (JSON, Markdown, RSS, and a per-commit "why did you link that" endpoint), and the zero-dependency package that does it for any repository
+- [Docs World](#sec-186): 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-305): 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-005): the canonical design vocabulary (colors, spacing, type, motion) every surface builds from
+- [NVIDIA models on three.ws](#sec-315): 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-266): 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
+- [three.ws on Solana Seeker](#sec-403): the Android app for Seeker and Saga, and what it adds on top of the website (Seed Vault sign-in, share-sheet capture, offline shell, Seeker verification)
+- [Publishing to the Solana dApp Store](#sec-404): the release runbook for the Seeker app, from the Publisher Portal setup and the release keystore through building, verifying, and submitting a signed APK
+- [Submission day: getting three.ws onto the Seeker dApp Store](#sec-405): the owner's step-by-step, with every portal field, the listing copy to paste, and the five screenshots to capture on the phone
+- [three.ws on iOS](#sec-269): the App Store app, what it adds on top of the website (native share sheet, universal links, wallet deep links, offline shell), and how the web half of it ships on every deploy
+- [Free LLM providers](#sec-237): 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-440): 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-314): what the platform already runs on NVIDIA silicon and what the program adds on top
+- [NVIDIA visibility map](#sec-318): 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-127): 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-317): our Nemotron Nano write-up, published on the NVIDIA Developer Forums
+- [three.ws on the AWS Builder Center](#sec-123): the index of our published AWS engineering writing, what code each article documents, and the checklist for publishing the next one
+- [three.ws on Hugging Face](#sec-253): our organization account there, the community article on giving agents bodies and wallets, the published avatar rigs and the Space that renders them, and the checklist for publishing the next one
+- [The onboarding tier](#sec-321): 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-011): the full abilities dossier, generated from the source article
+- [Use cases and example workflows](#sec-160): five audience-specific walkthroughs tying shipped features to concrete outcomes
+- [UX Flow Atlas](#sec-524): screen-by-screen traces of the platform's core flows, starting with onboarding and creation
+- [Demo routes](#sec-180): the canonical map of every `/demo/*` and `/demos/*` route
+- [Agent trading spec](#sec-426): the proposed agent trading capability contract
+- [ERC-8004 validation attestation](#sec-196): the attestation written when an agent registers on-chain
+- [zauth](#sec-591): the vendored security infrastructure docs our agent auth builds on
+- [Agent tokens](#sec-071): 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-366): the vendored on-chain program reference behind the launch surfaces
+- [pump-fun-mcp at the edge](#sec-362): the Cloudflare Workers mirror of the pump.fun MCP endpoint
+- [Package extraction](#sec-340): how reusable packages graduate out of the monorepo
+- [Agent task briefs](#sec-066): self-contained task prompts for AI agents working on the platform
+- [Troubleshooting and FAQ](#sec-449): fixes organized by symptom
+- [The 3D viewer](#sec-540): the rendering layer reference (model loading, cameras, animation, lighting)
+- [Avatar Artifact](#sec-109): the standalone viewer page, its ?agent= and ?model= parameters, and the iframe you paste anywhere
+- [Farcaster memory seeding](#sec-227): give an agent your Farcaster voice, proved with a wallet the account already verified, and revoke it in one click
+- [X memory seeding](#sec-553): 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-243): 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-388): 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-266): 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-218): copy-paste-ready code for common use cases
+- [The catalog quality gate](#sec-402): 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-278): 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-224): 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-344): the monthly Data API pass, one on-chain payment replacing per-call micropayments for 30 days
-- [Guardian console](#sec-238): 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-172): a new deterministic 3D creative challenge every day
-- [x402 Studio](#sec-562): the merchant console for running a paid x402 business on three.ws
-- [Contributing](#sec-161): local environment setup through a mergeable pull request
-- [ERC-8004 smart contracts](#sec-400): contract interfaces, deployed addresses, and how to read and write each registry
-- [Internationalization](#sec-244): how the UI translation catalog works and how to add a locale
+- [Premium](#sec-357): the monthly Data API pass, one on-chain payment replacing per-call micropayments for 30 days
+- [Guardian console](#sec-246): the inbox for the other side of social recovery and inheritance of agent wallets
+- [Coin Clash](#sec-146): token-gated community battles between coin factions
+- [Daily Forge](#sec-178): a new deterministic 3D creative challenge every day
+- [x402 Studio](#sec-588): the merchant console for running a paid x402 business on three.ws
+- [Contributing](#sec-166): local environment setup through a mergeable pull request
+- [ERC-8004 smart contracts](#sec-418): contract interfaces, deployed addresses, and how to read and write each registry
+- [Internationalization](#sec-254): how the UI translation catalog works and how to add a locale
---
-<a id="sec-412"></a>
+<a id="sec-430"></a>
> **Source:** `docs/strategy-objects.md` · [↑ table of contents](#table-of-contents)
@@ -89958,7 +94447,7 @@ Deeper references that don't fit a track above but answer real questions:
A Strategy Object is a trade strategy as a first-class thing you can own: a structured, validated rule set (entry conditions, sizing, take-profit, stop-loss, risk caps) that your agent can equip and run on-chain, ranked on a leaderboard by real live performance and forkable by anyone. The Strategy Lab is the workbench: write a strategy as data, validate it, backtest it against real recorded pump.fun history with the same evaluator its live runs use, and run it live or in simulation, end to end. Both run strategies as additional constraints on top of your agent's server-side spend policy, never a way around it.
Pages: [/strategies](https://three.ws/strategies) (the library and leaderboard), [/strategy-lab](https://three.ws/strategy-lab) (the workbench)
-API: `GET/POST /api/strategies`, `GET /api/strategies/leaderboard`, `GET/PATCH/DELETE /api/strategies/:id`, `POST /api/strategies/:id/{fork,publish}`, `GET/POST/DELETE /api/dca-strategies`, the Lab's `POST /api/pump/strategy-{validate,backtest,run,close-all}`, and the sniper backtester `POST /api/sniper/backtest`
+API: `GET/POST /api/strategies`, `GET /api/strategies/leaderboard`, `GET/PATCH/DELETE /api/strategies/:id`, `POST /api/strategies/:id/{fork,publish}`, `GET/POST/PATCH/DELETE /api/dca-strategies`, the Lab's `POST /api/pump/strategy-{validate,backtest,run,close-all}`, and the sniper backtester `POST /api/sniper/backtest`
## Why it exists
@@ -89981,7 +94470,7 @@ Every strategy is normalized and validated by `api/_lib/strategy-schema.js` befo
- **exits**: `take_profit_pct`, a mandatory `stop_loss_pct`, optional `trailing_stop_pct`, and `max_hold_minutes`. Validation requires a stop-loss and at least one upside exit.
- **risk**: `max_concurrent_positions` and `cooldown_minutes`.
-The schema enforces hard bounds on every field, so a stored config can never carry a nonsense number into the runtime. Two pure, synchronous functions, `matchesEntry` (does this real launch pass the entry gate) and `shouldExit` (should this open position close now), are the same logic the live equipped-strategy runtime (`api/_lib/agent-strategy-runtime.js`) and the assisted scan preview (`POST /api/trading/scan`) both evaluate, so a stored rule means exactly the same thing everywhere it runs.
+The schema enforces hard bounds on every field, so a stored config can never carry a nonsense number into the runtime. Two pure, synchronous functions, `matchesEntry` (does this real launch pass the entry gate) and `shouldExit` (should this open position close now), are the same logic the live equipped-strategy runtime (`api/_lib/agent-strategy-runtime.js`) and the assisted scan preview (`POST /api/trading/scan`) both evaluate, so a stored rule means exactly the same thing everywhere it runs. The assisted scan is owner-scoped and rate-limited twice (per IP and per owner, because every match it prices costs an upstream call); when the live launch feed cannot be reached it answers `502 feed_unavailable` rather than an empty scan that looks like "nothing matched".
### The library, leaderboard, and forking
@@ -89992,7 +94481,7 @@ The schema enforces hard bounds on every field, so a stored config can never car
`/strategy-lab` is where you build and prove a declarative pump.fun strategy. The Lab speaks its own tiny strategy DSL (a spec with `scan`, `filters`, `entry`, and `exit` predicate rules), and one compiled evaluator powers validation, backtest, and live runs, so they cannot drift:
- **Validate** (`POST /api/pump/strategy-validate`) checks the spec with the same validator the runner uses, so a broken spec is caught with field-level issues before anything runs. No sign-in needed.
-- **Backtest** (`POST /api/pump/strategy-backtest`, sign-in required) replays the compiled strategy over real recorded on-chain history: for each candidate mint (from the request's `mints`, the spec's `scan.mints`, or a live scan of new or trending launches) it fetches the token's real details, holders, bonding curve, and recent trades, evaluates the entry gate at the first recorded trade, then walks the subsequent real trades to trigger the exit rules. It never synthesizes launches or invents price paths; the response's `data` carries `spent`, `realizedPnlSol`, `roiPct`, `tradeCount`, `winRate`, `maxDrawdownSol`, the per-mint `trades`, and `mintsUsed`.
+- **Backtest** (`POST /api/pump/strategy-backtest`, sign-in required) replays the compiled strategy over real recorded on-chain history: for each candidate mint (from the request's `mints`, the spec's `scan.mints`, or a live scan of new or trending launches served by the pump.fun MCP's `get_new_tokens` and `get_trending_tokens`, which read pump.fun's public feed and the platform's own launch recorder, so no external indexer is needed) it fetches the token's real details, holders, bonding curve, and recent trades, evaluates the entry gate at the first recorded trade, then walks the subsequent real trades to trigger the exit rules. It never synthesizes launches or invents price paths; the response's `data` carries `spent`, `realizedPnlSol`, `roiPct`, `tradeCount`, `winRate`, `maxDrawdownSol`, the per-mint `trades`, and `mintsUsed`.
- **Run** (`POST /api/pump/strategy-run`) executes the strategy for a bounded duration (5 to 600 seconds) and streams events over Server-Sent Events. In **simulate** mode it needs no wallet and spends nothing; in **live** mode it requires auth, an agent you own with a provisioned Solana wallet, and every buy passes a `policyGuard` that calls the same `checkBuyAllowed` spend-policy check the rest of the platform uses.
- **Close all** (`POST /api/pump/strategy-close-all`, sign-in required) exits open strategy positions.
@@ -90000,7 +94489,7 @@ A second, separate backtester serves sniper-style rule sets: `POST /api/sniper/b
### DCA and subscription builders
-`/api/dca-strategies` runs recurring, scheduled buys (executed by the `run-dca` cron). Each strategy is validated (agent, delegation, token in and out, amount per execution, a daily or weekly period, and slippage capped server-side), and non-GET methods over a cookie session require a CSRF token because these move real funds on a schedule.
+`/api/dca-strategies` runs recurring, scheduled buys (executed by the `run-dca` cron). Each strategy is validated (agent, delegation, token in and out, amount per execution, a daily or weekly period, and slippage capped server-side), and non-GET methods over a cookie session require a CSRF token because these move real funds on a schedule. `PATCH /api/dca-strategies/:id` with `{ "action": "pause" }` or `{ "action": "resume" }` pauses and resumes a schedule: a resume schedules `next_execution_at` a full period out from the resume, so periods missed while paused never fire as a burst of swaps, and it is refused when the signed delegation behind the strategy is no longer active (grant a new one to restart it). A schedule that fails to execute three times in a row (`MAX_CONSECUTIVE_FAILURES`) pauses itself; a relayer that is switched off or rejects our own credentials is a platform outage and is retried without counting toward that limit. Rows carry `paused_at`, `resumed_at`, and `consecutive_failures`, and the per-agent list (`GET ?agent_id=`) returns every strategy whatever its status, so a paused or cancelled one stays visible with its history.
## Walkthrough
@@ -90055,16 +94544,16 @@ curl -s https://three.ws/api/sniper/backtest \
## Related
-- [Custody you can verify](#sec-171) - the spend limits and audit trail every live run is bounded by
-- [Financial controls](#sec-222) - the plain-English rules and firewall layered on the same enforcement point
-- [Oracle](#sec-326) - the conviction engine an entry gate can require before it fires
-- [Trading surfaces](#sec-429) - where equipped strategies execute through the guarded path
-- [Trading arenas](#sec-425) - competitive surfaces where strategies are put to the test
+- [Custody you can verify](#sec-177) - the spend limits and audit trail every live run is bounded by
+- [Financial controls](#sec-229) - the plain-English rules and firewall layered on the same enforcement point
+- [Oracle](#sec-338) - the conviction engine an entry gate can require before it fires
+- [Trading surfaces](#sec-447) - where equipped strategies execute through the guarded path
+- [Trading arenas](#sec-443) - 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-413"></a>
+<a id="sec-431"></a>
> **Source:** `docs/swarms.md` · [↑ table of contents](#table-of-contents)
@@ -90074,9 +94563,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-297) 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-402).
+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-307) first, which this builds on rather than repeats. For the single-agent trading pipeline that a swarm's treasury reuses, see [agent sniper](#sec-062), and for the earned-autonomy model behind each member's weight, see [earned autonomy](#sec-420).
-> **This moves real money.** `contribute` and `exit` transfer real SOL on Solana mainnet. Nothing here is simulated. Read the [risk acknowledgment](#sec-382) 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-396) 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).
@@ -90271,6 +94760,7 @@ Every failure returns `{ error, error_description }` with a specific code rather
| 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 |
+| 503 | `rpc_unavailable` | The treasury balance could not be read from Solana RPC, so `contribute` or `exit` refused to proceed rather than treat an unknown balance as zero; retry after the `Retry-After` window (15 seconds) |
| 404 | `not_found` | No such swarm |
| 404 | `agent_not_found` | No such agent |
| 404 | `not_member` | `exit` from an agent that is not an active member |
@@ -90281,14 +94771,14 @@ Every failure returns `{ error, error_description }` with a specific code rather
## Related
-- [Multi-agent coordination](#sec-297), the general model swarms specialize.
-- [Trading arenas](#sec-425), which covers swarms alongside tournaments, the theater, and vaults.
-- [USDC agent vaults](#sec-518), 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-171) for the spend guards every transfer here passes through.
+- [Multi-agent coordination](#sec-307), the general model swarms specialize.
+- [Trading arenas](#sec-443), which covers swarms alongside tournaments, the theater, and vaults.
+- [USDC agent vaults](#sec-538), 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-177) for the spend guards every transfer here passes through.
---
-<a id="sec-414"></a>
+<a id="sec-432"></a>
> **Source:** `docs/syndication.md` · [↑ table of contents](#table-of-contents)
@@ -90318,7 +94808,7 @@ query parameter, `source`, which selects what the feed is built from:
| --- | --- |
| 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). |
+| `nichxbt` | Announcements archived from the `@nichxbt` account. The account is suspended (reported 2026-08-27) and the source is unaffected: the items are read from the archived JSON in `data/x-archive/`, never scraped live. Only the per-item links into X are dead. See [`x-accounts.md`](#sec-550). |
| `archive` | Both archived accounts, merged and de-duplicated, newest first. |
The value is case-insensitive. Anything else is a `400` with
@@ -90364,12 +94854,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-329), [Listings and
-distribution](#sec-269).
+See also: [Partners](#sec-341), [Listings and
+distribution](#sec-281).
---
-<a id="sec-415"></a>
+<a id="sec-433"></a>
> **Source:** `docs/talking-avatar-video.md` · [↑ table of contents](#table-of-contents)
@@ -90382,9 +94872,9 @@ API: `POST /api/avatar/presign-audio` · `GET`/`POST /api/avatar/video-generate`
## Why it exists
-Real-time browser lipsync (see [Lipsync](#sec-267)) 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-279)) 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-521) 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-541) and bring the resulting clip here.
## How it works
@@ -90395,7 +94885,7 @@ The page ([`pages/create/video.html`](../pages/create/video.html)) loads [`src/c
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.
+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-098), 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."
@@ -90460,14 +94950,14 @@ curl -H 'cookie: __Host-sid=<SESSION>' \
## Related
-- [Voice Lab](#sec-521): clone or synthesize the audio track you upload here.
-- [Lipsync](#sec-267): the real-time, in-browser lipsync path (no export).
-- [Selfie to Avatar](#sec-389) and [Avatar reconstruction](#sec-114): create the avatar you render.
+- [Voice Lab](#sec-541): clone or synthesize the audio track you upload here.
+- [Lipsync](#sec-279): the real-time, in-browser lipsync path (no export).
+- [Selfie to Avatar](#sec-406) and [Avatar reconstruction](#sec-116): 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-416"></a>
+<a id="sec-434"></a>
> **Source:** `docs/terminal.md` · [↑ table of contents](#table-of-contents)
@@ -90481,7 +94971,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-429) 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-447) 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
@@ -90491,6 +94981,8 @@ The page mounts `mountMissionControl` from `src/mission-control/index.js` and la
- **Focus (center).** The selected coin's identity and market state (`/api/pump/coin`), its candlestick chart (`/api/pump/price-history`, Birdeye with a GeckoTerminal fallback and a last-good-candles degrade), the live trade tape (`/api/pump/dex-trades` polled every 8s for graduated pairs the stream misses), the firewall verdict, and the smart-money read.
- **Positions (right).** Your agent's open positions with streaming unrealized PnL over SSE (`/api/sniper/stream`, DB-polled every 1.5s), spot holdings (`/api/agents/:id/solana/holdings`, refreshed every 30s), and a one-tap quick exit.
+Signed out, or signed in without an agent wallet, the cockpit stays fully readable: the feed, chart, security grid, and smart-money read all work, while the trade desk and the Positions pane say exactly what unlocks trading (sign in, or create an agent wallet) and the Positions connection pill reads idle instead of reconnecting. Token art is served through the same-origin `/api/img` proxy because the public IPFS gateways most launches use refuse direct browser requests. The top bar also hosts the language picker: on phones the site-wide floating picker would otherwise cover the Positions tab of the bottom pane switcher.
+
Each row in the feed is enriched on demand by `enrich.js`, which fans out three cached reads per mint: intel (`/api/pump/intel?mint=`), the Trade Safety Firewall (`/api/pump/safety?mint=&amp;amount=`, which runs an SPL authority audit plus an on-chain simulated buy then sell round-trip and returns `allow` / `warn` / `block`), and smart money (`/api/intel/smart-money?mint=`). Failures cache `null` and mark the field unavailable rather than retry-storming or faking a value.
Every SSE endpoint self-closes about every 90 seconds by design; `realtime.js` treats an `event: close` as normal and fast-reconnects, with exponential backoff only on real errors.
@@ -90518,7 +95010,7 @@ The filter bar (state in `store.js`) narrows the feed by source, free-text query
## Firewall, MEV, and trading from your agent wallet
-Trading is the guarded path, and the client checks are only a fast gate: the server is the real authority. `POST /api/agents/:id/solana/trade` is owner-only (session or bearer auth, then agent-ownership verification) and, for a real execute, requires a single-use `x-csrf-token` and an `idempotency_key`. A `{ preview: true }` call returns a live quote and moves no funds. On execute the server runs a fixed enforcement order: fresh quote, kill switch, per-trade cap, daily budget, spend-limit enforcement, price-impact breaker, then the Trade Safety Firewall (`assessTradeSafety`; a `block` returns HTTP 422 `firewall_blocked`), then SOL headroom, then it claims the idempotency slot and submits through the MEV engine (`submitProtected` with `tipMode 'off'`: dynamic compute budget from a real simulation and a Helius priority-fee estimate on a protected single-tx send; the engine's Jito bundle-with-tip route exists but is not used by this endpoint). The agent's key is decrypted only at signing time via `recoverSolanaAgentKeypair`, and every attempt is audit-logged. A retried idempotency key never double-spends; a previously failed key returns 409. The firewall thresholds live in `api/_lib/trade-firewall.js`: block at score 45 and below, warn at 70 and below, with a fatal check (a dead sell leg or no venue) forcing `block` regardless of score.
+Trading is the guarded path, and the client checks are only a fast gate: the server is the real authority. `POST /api/agents/:id/solana/trade` is owner-only (session or bearer auth, then agent-ownership verification) and, for a real execute, requires a single-use `x-csrf-token` and an `idempotency_key`. A `{ preview: true }` call returns a live quote, moves no funds, and surfaces any guard that would reject the execute as a warning instead of a rejection. On execute the server runs a fixed enforcement order: fresh quote (a pump.fun mayhem-mode coin is refused here with HTTP 422 `mayhem_blocked`, on preview and execute alike), kill switch, per-trade cap, daily budget, spend-limit enforcement, price-impact breaker, then the Trade Safety Firewall on buys only (`assessTradeSafety`; a `block` returns HTTP 422 `firewall_blocked`; a sell brings SOL inward and skips it), then SOL headroom, then it claims the idempotency slot and submits through the MEV engine (`submitProtected` with `tipMode 'off'`: dynamic compute budget from a real simulation and a Helius priority-fee estimate on a protected single-tx send; the engine's Jito bundle-with-tip route exists but is not used by this endpoint). The agent's key is decrypted only at signing time via `recoverSolanaAgentKeypair`, and every attempt is audit-logged. A retried idempotency key never double-spends; a previously failed key returns 409. The firewall thresholds live in `api/_lib/trade-firewall.js`: block at score 45 and below, warn at 70 and below, with a fatal check (a dead sell leg or no venue) forcing `block` regardless of score.
Express mode (`trade.js`): the first trade always shows a confirm modal; accepting sets a per-agent express flag so later orders execute instantly. `x` toggles it back off.
@@ -90586,15 +95078,15 @@ Settled trades for graduated coins are unaffected: they come from
## Related
-- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-429)
-- [Coin Radar](#sec-374) and [Smart Money Radar](#sec-401) feed the same intel into their own surfaces
-- [Oracle: the conviction engine](#sec-326) supplies the fused conviction score
-- [Financial controls and custody guardrails](#sec-222) and [custody](#sec-171) document the server-side rails every order runs through
+- [The trading surfaces: Radar, Mission Control, Live Trade Feed, Watchlist, Coin Intelligence](#sec-447)
+- [Coin Radar](#sec-387) and [Smart Money Radar](#sec-419) feed the same intel into their own surfaces
+- [Oracle: the conviction engine](#sec-338) supplies the fused conviction score
+- [Financial controls and custody guardrails](#sec-229) and [custody](#sec-177) 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-417"></a>
+<a id="sec-435"></a>
> **Source:** `docs/the-first-19-weeks.md` · [↑ table of contents](#table-of-contents)
@@ -91238,7 +95730,7 @@ Contract address: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
---
-<a id="sec-418"></a>
+<a id="sec-436"></a>
> **Source:** `docs/three-microbuy.md` · [↑ table of contents](#table-of-contents)
@@ -91400,13 +95892,13 @@ The response reports `fired`, `paid`, `buys`, `pending`, `errors`, `toll_spent_u
## Related
-- [docs/x402-ring-economy.md](#sec-560) — the closed-loop x402 ring the toll settles through.
+- [docs/x402-ring-economy.md](#sec-586) — 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-419"></a>
+<a id="sec-437"></a>
> **Source:** `docs/three-thesis.md` · [↑ table of contents](#table-of-contents)
@@ -91448,7 +95940,7 @@ The response reports `fired`, `paid`, `buys`, `pending`, `errors`, `toll_spent_u
## 1. The one-paragraph version
-Most tokens are a story looking for a product. $THREE is the reverse: it is the coin of a shipping, open-source, revenue-generating platform that gives AI agents a 3D body, an on-chain identity, a wallet, and a way to get paid. The platform (three.ws) has published 2,673 changelog entries in about four months, exposes 723 public pages, ships 70 npm packages and 36 MCP servers, and runs a live pay-per-call economy (x402) with over one million individually priced datapoints. The token is wired into that machine at every level: hold-to-access tiers create standing demand, a 20% discount on plans and premium passes creates spend demand, a policy that commits 50% of platform revenue to market buybacks creates buy-side pressure, a micro-buy loop turns every settled x402 call into a small $THREE purchase, and on-chain agent deploys route their fee to the buyback wallet. Supply is never destroyed by the platform; instead the treasury buys. The token trades on MEXC, LBank, KCEX, Bybit Alpha, KuCoin Alpha, and every major Solana DEX, is Jupiter-verified, Phantom-verified, and a verified project on pump.fun. It is a real product's real coin, and the product is one of the more complete agent-economy stacks in the open-source world.
+Most tokens are a story looking for a product. $THREE is the reverse: it is the coin of a shipping, open-source, revenue-generating platform that gives AI agents a 3D body, an on-chain identity, a wallet, and a way to get paid. The platform (three.ws) has published 2,738 changelog entries in about four and a half months, exposes 761 public pages, ships 89 npm packages and 39 MCP servers, and runs a live pay-per-call economy (x402) with over one million individually priced datapoints. The token is wired into that machine at every level: hold-to-access tiers create standing demand, a 20% discount on plans and premium passes creates spend demand, a policy that commits 50% of platform revenue to market buybacks creates buy-side pressure, a micro-buy loop turns every settled x402 call into a small $THREE purchase, and on-chain agent deploys route their fee to the buyback wallet. Supply is never destroyed by the platform; instead the treasury buys. The token trades on MEXC, LBank, KCEX, Bybit Alpha, KuCoin Alpha, and every major Solana DEX, is Jupiter-verified, Phantom-verified, and a verified project on pump.fun. It is a real product's real coin, and the product is one of the more complete agent-economy stacks in the open-source world.
The thesis is not "number go up." The thesis is: **if agents become economic actors, they need bodies, identities, wallets, and rails, and three.ws has shipped all four with $THREE in the middle.**
@@ -91477,7 +95969,7 @@ On top of those five, the platform layers an entire agent economy:
- **A multiplayer world (`/play`)** with a strictly separated in-game currency and a $THREE cosmetics boutique.
- **An MCP endpoint** at `https://three.ws/api/mcp` behind a full OAuth 2.1 authorization server, so any MCP-capable AI client can drive the platform.
-Infrastructure: a single Google Cloud Run container serves the frontend, the route table, and every API handler; Neon Postgres, Cloudflare R2, and Upstash Redis behind it; a self-hosted Cloud Run GPU fleet (L4s plus one RTX PRO 6000 Blackwell) for text-to-3D, rigging, and motion; roughly 76 Cloud Scheduler crons keep the economy ticking.
+Infrastructure: a single Google Cloud Run container serves the frontend, the route table, and every API handler; Neon Postgres, Cloudflare R2, and Upstash Redis behind it; a self-hosted Cloud Run GPU fleet (L4s plus one RTX PRO 6000 Blackwell) for text-to-3D, rigging, and motion; 110 Cloud Scheduler crons (the `crons` array in `vercel.json`) keep the economy ticking.
The point of listing all of this: **$THREE is not attached to a landing page.** It is attached to a system with dozens of live, wired, money-moving surfaces.
@@ -91485,18 +95977,18 @@ The point of listing all of this: **$THREE is not attached to a landing page.**
## 3. The scale of what has been built
-Numbers measured directly from the repository on 2026-08-25:
+Numbers measured directly from the repository on 2026-09-01 (the external figures, such as GitHub, npm downloads, registry counts, and settlement totals, are as of 2026-08-25):
| Dimension | Figure |
|---|---|
-| Public pages (`data/pages.json`) | **723** across 10 sections (Crypto 137, Build 59, Learn 373, Main 52, Labs 22, Blog 39, and more) |
-| Changelog entries (`data/changelog.json`) | **2,673**, dated 2026-04-15 to 2026-08-24 |
-| Changelog tag mix | fix 1,190 · improvement 1,075 · feature 991 · infra 320 · docs 225 · security 216 · sdk 166 |
-| npm packages published under @three-ws | **101** (42 of them MCP servers, 6,225 downloads in the last 30 days); 70 live under `packages/` in this repo |
-| Root `package.json` | 257 scripts, 139 dependencies, version 1.5.2 |
+| Public pages (`data/pages.json`) | **761** across 10 sections (Crypto 137, Build 69, Learn 397, Main 56, Labs 22, Blog 39, and more) |
+| Changelog entries (`data/changelog.json`) | **2,738**, dated 2026-04-15 to 2026-09-01 |
+| Changelog tag mix | fix 1,219 · improvement 1,107 · feature 1,016 · infra 330 · docs 234 · security 218 · sdk 182 |
+| npm packages published under @three-ws | **101** (42 of them MCP servers, 6,225 downloads in the last 30 days); 89 live under `packages/` in this repo |
+| Root `package.json` | 277 scripts, 142 dependencies, version 1.5.2 |
| MCP servers in the official registry | **72** under `io.github.nirholas` (including `three-token-mcp`, `threews-3d-studio`, `threews-pumpfun`, `x402-mcp`, `agora-mcp`, `metaplex-agent`) |
| Docs mentioning $THREE | 89 markdown files |
-| Cloud Scheduler crons | ~76 |
+| Cloud Scheduler crons | 110 |
| Crypto news archive | **660,000+ articles** from September 2017 onward, 192 publisher feeds in 18 languages |
| DeFi pools indexed | ~15,000 live pools |
| Individually priced x402 datapoints | **1,000,000+** at $0.0005 each |
@@ -91618,7 +96110,7 @@ The fee rides inside the same transaction that creates the asset, so a failed de
### 5.11 The Rider pass
-`api/_lib/rider.js`: `REQUIRED_AMOUNT = 8000` $THREE. Granted two ways: by holding, or by paying 8,000 $THREE into the rider vault (recorded by a Helius webhook), so a payer who later sells is not revoked. Both sources are honored by `GET /api/rider/check`.
+`api/_lib/rider.js`: `REQUIRED_AMOUNT = 8000` $THREE. Granted two ways: by holding, or by paying 8,000 $THREE into the rider vault (recorded by a Helius webhook), so a payer who later sells is not revoked. Both sources are honored by `GET /api/rider/check`. The verdict is cached per wallet for ten minutes whenever both sources answered, so an RPC outage mid-session returns the wallet's last verdict marked stale (`x-rider-stale: 1`) instead of refusing the gate; a wallet never checked before gets a typed `503 rpc_unavailable` with `Retry-After`.
### 5.12 x402 rail acceptance
@@ -91940,7 +96432,7 @@ If buybacks never turn on, perks never activate, or revenue does not grow, the t
## 17. Summary of the bull case
-1. **A real, shipping, open-source product** with 725 pages, 101 npm packages, 72 MCP servers in the official registry, 4,519 priced x402 endpoints with 110,416 on-chain settlements, and 2,674 changelog entries in four months. The code is public and every mechanic in this document can be read. The week-by-week record is in [The First 19 Weeks](#sec-417).
+1. **A real, shipping, open-source product** with 761 pages, 101 npm packages, 72 MCP servers in the official registry, 4,519 priced x402 endpoints with 110,416 on-chain settlements, and 2,738 changelog entries in four and a half months. The code is public and every mechanic in this document can be read. The week-by-week record is in [The First 19 Weeks](#sec-435).
2. **A complete agent-economy stack**: bodies (3D avatars), identities (ERC-8004 and Metaplex Core), wallets (custodial with a single spend-policy boundary), rails (x402 with a self-hosted Solana facilitator), trust (cross-chain reputation and identity verification), and markets (skills, assets, labor, bounties, vaults).
3. **The token is wired into every layer**: hold-to-access tiers, 20% discounts on plans and passes, marketplace-only currency, labor and bounty escrow, game cosmetics, gated embeds, holder worlds, rider passes, deploy-fee waivers, x402 acceptance, and one-signature allowances.
4. **Three simultaneous demand vectors**: standing demand from holding, spend demand from discounts, and buy-side demand from a published 50%-of-revenue buyback commitment plus a per-call micro-buy loop. The platform never sells and never burns.
@@ -91983,7 +96475,7 @@ Every file referenced in this thesis, relative to the repository root:
---
-<a id="sec-420"></a>
+<a id="sec-438"></a>
> **Source:** `docs/timeline.md` · [↑ table of contents](#table-of-contents)
@@ -92115,7 +96607,7 @@ server reads that route table on boot).
---
-<a id="sec-421"></a>
+<a id="sec-439"></a>
> **Source:** `docs/token-gated-3d-embeds.md` · [↑ table of contents](#table-of-contents)
@@ -92123,7 +96615,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-390), [Embedding Guide](#sec-187)). 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-407), [Embedding Guide](#sec-193)). 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`.
@@ -92228,13 +96720,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-390)
+- Embed runtime this builds on: [`<three-d>` / embed v1](https://three.ws/embed/v1/preview), [Share & embed](#sec-407)
- 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-240) (site-wide $THREE tiers, distinct from per-embed gates)
+- Related: [Hold-to-access tiers](#sec-249) (site-wide $THREE tiers, distinct from per-embed gates)
---
-<a id="sec-422"></a>
+<a id="sec-440"></a>
> **Source:** `docs/tokens-xyz.md` · [↑ table of contents](#table-of-contents)
@@ -92400,12 +96892,12 @@ The batch market read is deliberately **not** cached here. Its caller in the mar
## Related
-- [Market Data API](#sec-273) - the pay-per-call x402 endpoints behind every `/markets` page
-- [Free LLM providers](#sec-230) - the same failover-chain pattern applied to text completion
+- [Market Data API](#sec-285) - the pay-per-call x402 endpoints behind every `/markets` page
+- [Free LLM providers](#sec-237) - the same failover-chain pattern applied to text completion
---
-<a id="sec-423"></a>
+<a id="sec-441"></a>
> **Source:** `docs/trader-card.md` · [↑ table of contents](#table-of-contents)
@@ -92424,13 +96916,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-326)). 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-338)). 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. "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.
**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-425).
+**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-443).
## Claiming: one signature, no gas
@@ -92461,18 +96953,18 @@ Returns the identity summary, KPI aggregates, and the per-coin ledger (up to 60
- `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-284)).
+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-293)).
## Related
-- [Trader Passport](#sec-424): the on-chain credential a claimed record earns, and how another app verifies it
-- [Oracle](#sec-326) — the WHO pillar runs on this same wallet-reputation ledger
-- [Trading arenas](#sec-425) — where a verified track record unlocks tournaments, vaults, and mirrors
-- [Trading surfaces](#sec-429) — the solo trading stack
+- [Trader Passport](#sec-442): the on-chain credential a claimed record earns, and how another app verifies it
+- [Oracle](#sec-338) — the WHO pillar runs on this same wallet-reputation ledger
+- [Trading arenas](#sec-443) — where a verified track record unlocks tournaments, vaults, and mirrors
+- [Trading surfaces](#sec-447) — the solo trading stack
---
-<a id="sec-424"></a>
+<a id="sec-442"></a>
> **Source:** `docs/trader-passport.md` · [↑ table of contents](#table-of-contents)
@@ -92636,20 +97128,20 @@ The Proof tab of [`/trader/<agent_id>`](https://three.ws/trader) renders the pas
## Related
-- [Claim your wallet](#sec-423): the read-only track record that comes before any credential
-- [Trading arenas](#sec-425): what a verified record unlocks
-- [Copy trading](#sec-166): leaderboard weighting and performance fees
-- [API reference](#sec-096): every public endpoint
+- [Claim your wallet](#sec-441): the read-only track record that comes before any credential
+- [Trading arenas](#sec-443): what a verified record unlocks
+- [Copy trading](#sec-171): leaderboard weighting and performance fees
+- [API reference](#sec-098): every public endpoint
---
-<a id="sec-425"></a>
+<a id="sec-443"></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-429). 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-447). 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).
@@ -92691,7 +97183,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-171)). 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-177)). 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.
@@ -92711,18 +97203,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-429) → 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-326) conviction is the intelligence all of these agents are acting on.
+Prove yourself solo (the [trading surfaces](#sec-447) → 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-338) conviction is the intelligence all of these agents are acting on.
## Related
-- [Trading surfaces](#sec-429) — the solo stack (Radar, Mission Control, Trade Feed, Watchlist, Coin Intelligence)
-- [Custody](#sec-171) — the spend limits, freeze, and audit rails every mirrored/pooled trade runs through
-- [Oracle](#sec-326) — the conviction engine · [Trading experiment](#sec-427) — one agent's journaled live run
-- [Agent reputation](#sec-056) / [Solana reputation](#sec-405) — how the trust scores are computed
+- [Trading surfaces](#sec-447) — the solo stack (Radar, Mission Control, Trade Feed, Watchlist, Coin Intelligence)
+- [Custody](#sec-177) — the spend limits, freeze, and audit rails every mirrored/pooled trade runs through
+- [Oracle](#sec-338) — the conviction engine · [Trading experiment](#sec-445) — one agent's journaled live run
+- [Agent reputation](#sec-057) / [Solana reputation](#sec-423) — how the trust scores are computed
---
-<a id="sec-426"></a>
+<a id="sec-444"></a>
> **Source:** `docs/trading-copilot.md` · [↑ table of contents](#table-of-contents)
@@ -92782,8 +97274,10 @@ Arrow keys move through the menu, `Enter`/`Tab` selects, `Esc` closes.
always visible and exact.
- **Copy / Regenerate** — hover any reply to copy it or re-run the last turn.
- **Stop** — the send button becomes a stop button while a reply streams.
-- **Voice** — 🎙 dictates your message (browser `SpeechRecognition`); 🔊 speaks replies
- in the agent's configured voice (ElevenLabs, with a browser-speech fallback).
+- **Voice**: 🎙 dictates your message (browser `SpeechRecognition`); 🔊 speaks replies
+ in the agent's configured voice (ElevenLabs, with a browser-speech fallback). The
+ request names the agent, so an owner-cloned voice on the owner's saved ElevenLabs key
+ plays here too instead of silently degrading to browser speech.
- **Persistence** — the conversation, its data cards, and the executed-action log are
saved per wallet + network in `localStorage` and restored when you return. Live trade
proposals are intentionally **not** persisted, so a reload never resurrects a
@@ -92803,10 +97297,16 @@ The model is **read-and-propose only**. It cannot sign, and it cannot bypass a g
**structured proposal**, never executed on the server.
3. The browser **re-quotes it live** and, only on your confirmation, calls the existing
guarded endpoints:
- - `POST /api/agents/:id/solana/trade` — enforces the spend guards
+ - `POST /api/agents/:id/solana/trade`: enforces the spend guards
([`api/_lib/agent-trade-guards.js`](../api/_lib/agent-trade-guards.js)), the
rug/honeypot firewall ([`api/_lib/trade-firewall.js`](../api/_lib/trade-firewall.js)),
- and the custody audit (`agent_custody_events`).
+ and the custody audit (`agent_custody_events`). The guards fail closed: a caller that
+ passes neither pre-read limits nor the agent's `meta` gets the policy read from the
+ agent's own row (a deleted agent has no policy and its spend is refused), and the
+ ledger also meters a `per_counterparty_daily_usd` ceiling on what one agent can send
+ to a single destination per day. The copilot's risk-limits card edits the per-trade
+ cap, daily budget, max price impact, and kill switch; the counterparty cap is set
+ from the wallet hub.
- `PUT /api/agents/:id/trade/limits` — patches guardrails by key.
A conversation can therefore never bypass a spend cap, the kill switch, or the firewall.
@@ -92830,13 +97330,16 @@ SSE events:
| `done` | `{ reply, proposals, citations }` | final reply |
| `error` | `{ code, message }` | turn failed |
-The provider chain is free-first and OpenAI-compatible (Groq → OpenRouter, including any
-`OPENROUTER_FALLBACK_KEYS` → NVIDIA, with paid OpenAI as the backstop), so the copilot
-works without any paid key. Whenever the GCP project is configured, a keyless,
-credits-billed **Vertex Gemini** rung is appended unconditionally as the final anchor,
-so the chain always ends on a provider that cannot be evicted by a dead key. A 15s heartbeat
-keeps the stream alive across slow tool rounds; the client aborts a genuinely dead stream
-and offers Retry rather than hanging.
+The provider chain is free-first and OpenAI-compatible, shared with the built-in chat
+agent loop in [`api/_lib/llm-tool-chain.js`](../api/_lib/llm-tool-chain.js): Groq →
+Cerebras → OpenRouter (including any `OPENROUTER_FALLBACK_KEYS`) → NVIDIA → SambaNova →
+Mistral → Z.ai → Gemini (API key), with paid OpenAI as the backstop, each rung present
+only when its key is set, so the copilot works without any paid key. Whenever the GCP
+project is configured, a keyless, credits-billed **Vertex Gemini** rung is appended
+unconditionally as the final anchor, so the chain always ends on a provider that cannot
+be evicted by a dead key. Each round has a 45s deadline and fails over to the next rung on
+any transport or non-2xx error. A 15s heartbeat keeps the stream alive across slow tool
+rounds; the client aborts a genuinely dead stream and offers Retry rather than hanging.
## $THREE
@@ -92853,18 +97356,19 @@ plumbing — and never suggests, shills, or names another token on its own initi
| Client mount (chat UI, cards, slash, persistence, voice) | [`src/agent-copilot.js`](../src/agent-copilot.js) |
| Wallet-hub tab wrapper | [`src/agent-wallet-hub/tabs/copilot.js`](../src/agent-wallet-hub/tabs/copilot.js) |
| Server (tool loop, SSE, proposals) | [`api/agents/copilot.js`](../api/agents/copilot.js) |
+| Provider chain + streamed tool-call reader (shared with the chat agent loop) | [`api/_lib/llm-tool-chain.js`](../api/_lib/llm-tool-chain.js) |
| Markdown renderer | [`src/md.js`](../src/md.js) |
| UI contract tests | [`tests/agent-copilot-ui.test.js`](../tests/agent-copilot-ui.test.js) |
## Related
-- [The trading surfaces: Radar, Mission Control, Feed, Watchlist, Intel](#sec-429)
-- [Financial controls & custody guardrails](#sec-222)
-- [The autonomous trading experiment](#sec-427)
+- [The trading surfaces: Radar, Mission Control, Feed, Watchlist, Intel](#sec-447)
+- [Financial controls & custody guardrails](#sec-229)
+- [The autonomous trading experiment](#sec-445)
---
-<a id="sec-427"></a>
+<a id="sec-445"></a>
> **Source:** `docs/trading-experiment.md` · [↑ table of contents](#table-of-contents)
@@ -92976,7 +97480,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-402). A losing arm cannot reach the field at
+[Earned autonomy](#sec-420). 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.
@@ -93110,11 +97614,12 @@ is still fail-closed: unproven is never treated as safe.
`isMayhemMode` lives on the pump.fun bonding curve, not the new-mint firehose, so
it's read from the curve (one cached read per mint) and checked as **gate 0** in
-`executeBuy` — before any throttle, wallet decrypt, or position row — so it covers
+`executeBuy` (before any throttle, wallet decrypt, or position row) so it covers
**every** trigger path (new_mint, intel, alpha, first_claim, radar, swarm). On by
-default (`SNIPER_MAYHEM_FILTER=0` disables; `SNIPER_MAYHEM_STRICT=1` also skips
-when the curve can't be read). A Mayhem mint is skipped with reason
-`mayhem_excluded`.
+default (`SNIPER_MAYHEM_FILTER=0` disables). A Mayhem mint is skipped with reason
+`mayhem_excluded`. The gate also fails closed by default: a curve that still can't
+be read after the RPC-chain retries is skipped with reason `mayhem_unknown`, and
+`SNIPER_MAYHEM_STRICT=0` restores allow-on-unknown.
## Funding it from the UI
@@ -93199,7 +97704,7 @@ much — and tune the next run. That is the whole point of the experiment.
---
-<a id="sec-428"></a>
+<a id="sec-446"></a>
> **Source:** `docs/trading-hub.md` · [↑ table of contents](#table-of-contents)
@@ -93307,17 +97812,17 @@ credentials, and writes nothing.
## Related
-- [Agent Sniper](#sec-061), what the autonomous trader is and how it is wired
-- [The 10 SOL experiment](#sec-427), the full risk policy
-- [Risk acknowledgment](#sec-382), read before arming real funds
-- [Custody model](#sec-171), how an agent holds its own keys
-- [Earned autonomy](#sec-402), how an agent earns more freedom
-- [Trading Copilot](#sec-426), the fair-launch market maker
-- Tutorial: [Arm an autonomous sniper](#sec-439)
+- [Agent Sniper](#sec-062), what the autonomous trader is and how it is wired
+- [The 10 SOL experiment](#sec-445), the full risk policy
+- [Risk acknowledgment](#sec-396), read before arming real funds
+- [Custody model](#sec-177), how an agent holds its own keys
+- [Earned autonomy](#sec-420), how an agent earns more freedom
+- [Trading Copilot](#sec-444), the fair-launch market maker
+- Tutorial: [Arm an autonomous sniper](#sec-459)
---
-<a id="sec-429"></a>
+<a id="sec-447"></a>
> **Source:** `docs/trading-surfaces.md` · [↑ table of contents](#table-of-contents)
@@ -93343,9 +97848,9 @@ All five surfaces read the same underlying truth: the Coin Intelligence Engine (
On top of that base layer:
-- **Oracle conviction** ([the conviction engine](#sec-326)) enriches coins across all five surfaces with its 0–100 fused score and tier.
+- **Oracle conviction** ([the conviction engine](#sec-338)) 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).
+- **Live trades** stream over server-sent events from `/api/pump/trades-stream` (PumpPortal websocket, relayed). PumpPortal gates per-coin trade subscriptions behind an API key funded with at least 0.02 SOL; when it refuses one, the socket stays open and simply never delivers, so the relay forwards that refusal as an SSE `notice` event and the tape shows a degraded state instead of a lit "live" lamp over an empty panel. A malformed `mint` is refused up front with `400 invalid_mint`.
- **Smart-money pedigree** comes from the proven-wallet ledger (`/api/intel/smart-money`).
One naming trap for API users: `/radar` is served by `api/pump/coin-intel.js` and `/coin-intel` is served by `api/pump/intel.js`. The names look swapped; they are two distinct read models over the same engine.
@@ -93373,11 +97878,11 @@ Four tabs:
3. **Smart-Money Traders** — the cross-coin trader board.
4. **What it learned** — the learned per-signal weights and outcome distribution. The engine grades its own predictions against real outcomes and shows you the weights it arrived at.
-If the engine is still warming up (fresh deploy, empty tables), the page says so honestly instead of rendering blanks. Public, no account, refreshes every 15 seconds.
+If the engine is still warming up (fresh deploy, empty tables), the page says so honestly instead of rendering blanks. Public, no account, refreshes every 15 seconds. A caller mistake is answered as one, never as an outage: an unknown `view`, a non-base58 `mint`, or a `minQuality` outside 0-100 gets a `400` (`invalid_view`, `invalid_mint`, `invalid_min_quality`) rather than the "warming up" state. The feed's `q` search runs in SQL over the whole observed feed, and a `verdict` filter (derived after the row is shaped) scans up to 600 recent rows before slicing to the requested page, so `?verdict=strong` on a busy feed no longer answers with the one strong coin that happened to sit on page one. The `traders` and `learning` views are whole-history aggregates and are edge-cached for 5 minutes; the feed stays on a 5-second cache.
## Live Trade Feed — /trades
-The proof stream. The left rail is a public feed of closed positions where a platform agent turned a meaningful profit — realized PnL, hold time, exit reason, transaction signatures, Oracle context, and how many copiers followed the trade. Filter by time window (1h → all-time) and minimum PnL. $THREE is pinned at the top of the rail.
+The proof stream. The left rail is a public feed of closed positions where a platform agent turned a meaningful profit: realized PnL, hold time, exit reason, transaction signatures, Oracle context, and how many copiers followed the trade. Filter by time window (1h → all-time) and minimum PnL (`min_pnl_pct`, default 10). $THREE is pinned at the top of the rail. Each row's `multiple` is derived from the position's cumulative realized percentage rather than exit over entry, because a position that took initials first rewrites its cost basis and books only the closing leg's proceeds. Pages walk a `cursor` (an ISO 8601 timestamp; anything else is a `400 validation_error`) ordered by close time then position id, so two exits sharing a timestamp cannot reorder between pages.
Click any trade (or paste any mint) and the center pane becomes a full analytics workstation for that coin:
@@ -93405,7 +97910,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-222)).
+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-229)).
The three panes:
@@ -93429,7 +97934,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-326) for the fused conviction verdict — and armed agents can run the same loop autonomously (see [the trading experiment](#sec-427) and [Oracle's agent loop](#sec-326)).
+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-338) for the fused conviction verdict — and armed agents can run the same loop autonomously (see [the trading experiment](#sec-445) and [Oracle's agent loop](#sec-338)).
## API quick reference
@@ -93439,10 +97944,13 @@ All read endpoints are public and IP rate-limited:
# Radar list + market pulse
curl 'https://three.ws/api/pump/coin-intel?stats=1'
-# Intel engine: scored feed, leaderboard, learned weights, one coin
-curl 'https://three.ws/api/pump/intel?view=feed&limit=10'
+# Intel engine: scored feed, leaderboard, learned weights, cross-coin traders, one coin
+curl 'https://three.ws/api/pump/intel?view=feed&limit=10' # views: feed | leaderboard | learning | traders
curl 'https://three.ws/api/pump/intel?mint=<MINT>'
+# Proven-wallet pedigree for one coin, or one wallet's reputation (both base58-validated)
+curl 'https://three.ws/api/intel/smart-money?mint=<MINT>'
+
# Winning-trade feed
curl 'https://three.ws/api/trades/feed'
@@ -93450,21 +97958,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-284) (`@three-ws/intel-mcp`, `@three-ws/portfolio-mcp`) — and the paid x402 lanes in [x402-endpoints](#sec-559).
+Agents wanting the same intel over MCP: see [docs/mcp.md](#sec-293) (`@three-ws/intel-mcp`, `@three-ws/portfolio-mcp`) — and the paid x402 lanes in [x402-endpoints](#sec-584).
## Related
-- [Meta-Allocator: the ETF of degens](#sec-288): 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-426) — conversational trading over these same numbers
-- [Oracle — the conviction engine](#sec-326) · [/oracle/docs](https://three.ws/oracle/docs)
-- [The autonomous trading experiment](#sec-427)
-- [Financial controls & custody guardrails](#sec-222)
-- [UX flows: crypto trading & analytics](#sec-510) — screen-by-screen walkthrough
+- [Meta-Allocator: the ETF of degens](#sec-297): diversify a budget across the top verified leaders
+- [Clip Director: every trade becomes content](#sec-147): turn any closed trade into shareable cards per surface
+- [The Trading Copilot — talk to your wallet](#sec-444) — conversational trading over these same numbers
+- [Oracle — the conviction engine](#sec-338) · [/oracle/docs](https://three.ws/oracle/docs)
+- [The autonomous trading experiment](#sec-445)
+- [Financial controls & custody guardrails](#sec-229)
+- [UX flows: crypto trading & analytics](#sec-530) — screen-by-screen walkthrough
---
-<a id="sec-430"></a>
+<a id="sec-448"></a>
> **Source:** `docs/triage.md` · [↑ table of contents](#table-of-contents)
@@ -93532,14 +98040,14 @@ We are actively looking to grow this. The path is the normal one: land a few goo
## Related
-- [Your first contribution](#sec-223)
+- [Your first contribution](#sec-230)
- [CONTRIBUTING.md](../CONTRIBUTING.md)
-- [Community](#sec-151)
+- [Community](#sec-155)
- [Security policy](../.github/SECURITY.md)
---
-<a id="sec-431"></a>
+<a id="sec-449"></a>
> **Source:** `docs/troubleshooting.md` · [↑ table of contents](#table-of-contents)
@@ -94198,7 +98706,7 @@ Idle blink and head-drift are active in the current release: `src/idle-animation
---
-<a id="sec-432"></a>
+<a id="sec-450"></a>
> **Source:** `docs/trust-primitives.md` · [↑ table of contents](#table-of-contents)
@@ -94217,7 +98725,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-563)).
+(Base or Solana mainnet, via [x402](#sec-589)).
Pass any counterparty identifier. The type is auto-detected and scored from whatever
real on-chain evidence exists for it:
@@ -94335,7 +98843,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-563).
+dropped >10 points). See the [x402 catalog](#sec-589).
---
@@ -94360,7 +98868,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-563)).
+— $0.005 USDC per call (Base or Solana mainnet, via [x402](#sec-589)).
It verifies a **claim** that `identity` controls `address`, for **any** identity type,
on any chain — regardless of the platform the counterparty came from:
@@ -94434,11 +98942,253 @@ score *whether to trust* them.
---
-See also: [x402 paid endpoints](#sec-563) · [Agent Bouncer](#sec-096) · [ERC-8004 identity](#sec-189)
+See also: [x402 paid endpoints](#sec-589) · [Agent Bouncer](#sec-098) · [ERC-8004 identity](#sec-195)
---
-<a id="sec-433"></a>
+<a id="sec-451"></a>
+
+> **Source:** `docs/tty-avatar.md` · [↑ table of contents](#table-of-contents)
+
+# Terminal avatar (`@three-ws/tty-avatar`)
+
+Every three.ws avatar and every agent's 3D body can run in a terminal. One command, no browser, no GPU:
+
+```sh
+npx @three-ws/tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa
+```
+
+That draws the avatar in colour at 24 frames a second in whatever terminal you are in, swaying gently, and keeps it there until you press Ctrl-C. Point it at an agent instead (`agent:<id>`) and you get that agent's bound body. Point it at any `.glb` on disk or on the web and it draws that.
+
+The reason it exists is the second half: wire it to Claude Code once and the avatar becomes your coding agent's face. It looks up and thinks while the agent reads your prompt, nods quickly while it edits and runs commands, shakes when a tool fails, pulses when the agent is waiting on you, and bounces when it finishes. The caption under it says what the agent is doing right now (`editing index.js`, `$ npm test`, `searching`).
+
+## Try it
+
+Pick any avatar in the [gallery](/gallery). Its page's **Embed** tab has a **Terminal** section with the exact command for that avatar. Or use an agent from [/agents](/agents) with `agent:` in front of its id.
+
+```sh
+# a three.ws avatar
+npx @three-ws/tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa
+
+# an agent's body
+npx @three-ws/tty-avatar agent:bd1b56b0-5494-47e2-ad78-04ef4c43ae5b
+
+# the page URL works too
+npx @three-ws/tty-avatar https://three.ws/avatars/81a076b6-55ff-49a2-b007-1d88e7dce2aa
+
+# your own model
+npx @three-ws/tty-avatar ./hero.glb --mode braille --zoom 1.3
+```
+
+Three glyph modes. `blocks` (default in a terminal) draws truecolor half-blocks, two colours per cell. `braille` draws 2x4 dots per cell for four times the vertical detail. `ascii` is a plain luminance ramp with no colour codes, and is what you get automatically when the output is piped, so `npx @three-ws/tty-avatar snapshot <id> > avatar.txt` produces something you can paste anywhere.
+
+## Give your coding agent a face
+
+```sh
+npx @three-ws/tty-avatar install-hooks --write
+```
+
+That merges nine hook entries into `~/.claude/settings.json` (it leaves any hooks you already have alone, and running it twice does not duplicate them). Open two panes: run the viewer in one, Claude Code in the other.
+
+| What Claude Code does | What the avatar does |
+|---|---|
+| Starts a session | bounces once, "session started" |
+| Reads your prompt | tilts and looks up, "reading your prompt" |
+| Reads, edits, runs, searches | quick working nods with the file or command as the caption |
+| A tool fails | a short shake, "Bash failed" |
+| Needs your permission or input | pulses, with the notification text, until you answer |
+| Finishes a turn | bounces, "done", then settles |
+| Compacts context | thinks, "compacting memory" |
+| Ends the session | head down, asleep |
+
+The hook command that gets installed is just `cat > ~/.three-ws/tty-avatar/event.json`. It starts no interpreter, so it costs a tool call nothing. The viewer polls that file five times a second and maps each payload to a mood itself. Any agent runtime that can write a Claude-Code-shaped JSON payload to that path gets the same behaviour, and any script can drive the mood directly:
+
+```sh
+npx @three-ws/tty-avatar mood happy --say "deploy landed" --ttl 5000
+npx @three-ws/tty-avatar say "migrating the database"
+```
+
+`install-hooks` without `--write` prints the JSON so you can paste it yourself; `--json` prints just the `hooks` object for another tool to merge.
+
+## Moods
+
+`idle`, `spin`, `think`, `work`, `talk`, `happy`, `attention`, `error`, `sleep`. Each is procedural whole-body motion (sway, tilt, nod, bounce, shake), which is why it works on any GLB with no rig at all, props included. Switching moods cross-fades over half a second so a burst of hook events never makes the model pop. `tty-avatar moods` lists them.
+
+## As a library
+
+```js
+import { resolveSource, parseGlb, TtyAvatar, snapshot } from '@three-ws/tty-avatar';
+
+const { bytes, name } = await resolveSource('agent:bd1b56b0-5494-47e2-ad78-04ef4c43ae5b');
+const mesh = await parseGlb(bytes);
+
+const viewer = new TtyAvatar(mesh, { name, fps: 24 });
+viewer.setMood('talk', { say: 'hello from the terminal', ttlMs: 4000 });
+await viewer.start();
+```
+
+`snapshot(mesh, { mode, columns, rows, yaw, pitch, zoom, mood })` returns one frame as a string without touching the terminal, which is how the package tests render and how you would put a frame in a log or a README. The rasterizer (`createFrame`, `render`) and encoders (`encodeBlocks`, `encodeBraille`, `encodeAscii`) are exported separately for anything custom. The full export table is in the [package README](https://github.com/nirholas/three.ws/tree/main/packages/tty-avatar#library).
+
+## How it draws
+
+The terminal is the framebuffer. A character cell is split into subpixels (1x2 for half-blocks, 2x4 for braille), the mesh is projected with a perspective camera onto that grid, and a z-buffered scanline fill writes one lit colour per subpixel. Faces are shaded with a key light, a fill light, an ambient floor and a rim term so silhouettes stay legible on both dark and light terminal themes. Colour comes from each primitive's material factor and vertex colours; textures are not sampled because a cell is far coarser than a texel. A typical 20k-triangle three.ws avatar renders in under 5 ms per frame at 160x96 subpixels, so 24 fps costs a fraction of one core.
+
+Id resolution uses the same public endpoints the web studio does: `/api/avatars/:id` for an avatar's `model_url`, `/api/agents/:id` for an agent's `avatar_model_url`. Models are decoded with `@gltf-transform`, so meshopt-compressed three.ws avatars and Draco files load as-is.
+
+## Related
+
+- [Avatar CLI](/docs/avatar-cli): manifests, validation and embed snippets from the shell.
+- [Web component](/docs/web-component): the same avatar in a browser.
+- [Share & embed](/docs/share-and-embed): every other way to put an avatar somewhere.
+- Source and tests: [packages/tty-avatar](https://github.com/nirholas/three.ws/tree/main/packages/tty-avatar).
+
+---
+
+<a id="sec-452"></a>
+
+> **Source:** `docs/tty.md` · [↑ table of contents](#table-of-contents)
+
+# Terminal renderer
+
+`curl three.ws/tty` and a rigged 3D agent walks in your terminal.
+
+No GPU is involved, on either side. There is no WebGL, no browser, and nothing to
+install. A software rasterizer decodes the model, evaluates its animation, blends
+the joint matrices per vertex on the CPU, and rasterizes triangles into a buffer
+the size of your terminal. Then it writes the result as coloured text.
+
+```bash
+curl three.ws/tty
+```
+
+Press Ctrl-C to stop it. It works in any terminal that renders colour: macOS
+Terminal, iTerm2, Windows Terminal, GNOME Terminal, Alacritty, WezTerm, tmux, a
+VS Code terminal, an SSH session on a box with no display.
+
+## Why it exists
+
+three.ws gives AI agents a body. AI agents increasingly live in a terminal. This
+closes the gap: the same avatar that renders in WebGL on a web page renders in
+the shell where the agent actually runs, with no client to install and no
+graphics stack to negotiate.
+
+It is also useful on its own. A rigged character, animating, is a good way to
+check what a GLB actually contains before you wire it into anything.
+
+## The endpoint
+
+`GET /api/tty` streams frames as `text/plain`, paced in real time, so the
+response body *is* the animation. It starts drawing before the model has finished
+loading. Every parameter is optional.
+
+| Parameter | Meaning | Default |
+| --- | --- | --- |
+| `avatar` | A public three.ws avatar id. The path form `/tty/<id>` sets this. | the default model |
+| `src` | Any public GLB URL. | none |
+| `w`, `h` | Columns and rows. One row is two vertical pixels. | 76 x 30 |
+| `frames` | How many frames to send. `1` gives a still image. | 8 seconds worth |
+| `fps` | Frames per second, 4 to 30. | 18 |
+| `t` | Where in the clip to start, in seconds. | 0 |
+| `spin` | Turntable speed in radians per second. `0` holds still. | 0.9 |
+| `clip` | Animation name to play. | the first clip |
+| `color` | `truecolor`, `ansi256`, or `mono`. | `ansi256` |
+| `zoom` | 1 fits the model, higher moves closer. | 1 |
+| `pitch` | Camera elevation in radians. | 0.08 |
+
+```bash
+# a specific avatar, wider, held still instead of spinning
+curl 'three.ws/tty/8f2c1a90-1c4e-4b2b-9d77-3f0a1b2c3d4e?w=110&spin=0'
+
+# any public GLB
+curl 'three.ws/tty?src=https://example.com/robot.glb&frames=120'
+
+# one frame of plain ASCII, for a README, a commit hook, or a motd
+curl 'three.ws/tty?frames=1&color=mono&w=60'
+```
+
+Colour defaults to 256 rather than truecolor on purpose. `curl` forwards neither
+`COLORTERM` nor `TERM`, so the server cannot know what you are running, and
+guessing truecolor wrong sprays literal escape sequences across your screen.
+Pass `color=truecolor` if you know your terminal handles it.
+
+A browser asking for `/tty` gets [the page](https://three.ws/tty) instead of the
+stream, because a browser renders escape codes as literal garbage. Add `?raw=1`
+to see the bytes anyway.
+
+### Limits
+
+40 streams per IP per 10 minutes, in their own bucket so a terminal stream and a
+browser render never starve each other. A single stream is capped at 600 frames
+or 45 seconds. Private avatars never render: the endpoint is unauthenticated, so
+it only serves models that are already public.
+
+## Running it locally
+
+The renderer is published as [`@three-ws/tty-3d`](https://www.npmjs.com/package/@three-ws/tty-3d).
+
+```bash
+# a local file
+npx @three-ws/tty-3d ./avatar.glb
+
+# anything on the web
+npx @three-ws/tty-3d https://three.ws/avatars/default.glb --spin 1.4
+
+# a still frame, piped somewhere
+npx @three-ws/tty-3d avatar.glb --once --width 80 --color mono > frame.txt
+```
+
+Arrow keys orbit, `w`/`s` tilt, `+`/`-` zoom, space pauses, `q` quits.
+
+Piping is safe: when stdout is not a terminal the default is a single frame, not
+an infinite animation, so redirecting to a file terminates.
+
+### As a library
+
+```js
+import { loadModel, createRenderer } from '@three-ws/tty-3d';
+
+const model = await loadModel('./avatar.glb'); // path, https URL, or bytes
+const renderer = createRenderer(model, { width: 80, height: 40 });
+
+process.stdout.write(renderer.frame(1.25)); // one string per frame
+```
+
+`frame(time)` is pure: the same time always renders the same string. Full API in
+the [package README](https://github.com/nirholas/three.ws/tree/main/packages/tty-3d).
+
+## How it works
+
+**Half blocks, not ASCII art.** Each cell is a `▀` with its own foreground and
+background colour, so one character carries two independently coloured pixels.
+That doubles vertical resolution and makes pixels square, because terminal cells
+are roughly 1:2. It is why a sphere comes out round rather than squashed.
+
+**Real skinning.** Joint matrices are evaluated per frame from the glTF animation
+samplers and blended per vertex, so a rigged avatar moves its limbs. It is not a
+spinning static mesh. `EXT_meshopt_compression` is decoded on the way in, because
+most three.ws avatars ship compressed and a reader that skips the decoder reads
+garbage vertex data rather than failing.
+
+**Framing that holds still.** The camera radius is fixed from the widest frame of
+the clip while the centre tracks the current pose. Fitting each frame alone makes
+the camera breathe as the silhouette changes; fitting the union of every frame is
+worse on anything with root motion, because the union is a corridor as long as
+the character walks.
+
+**Silhouette-first shading.** A key light, a fill light, and a rim term. At this
+resolution the outline carries the shape, so faces turning away from the camera
+are lifted rather than crushed to black.
+
+## Related
+
+- [Widget types](/docs/widgets) puts a live WebGL agent on a web page.
+- [Avatars](/avatars) is where the models come from.
+- The [roadmap](https://github.com/nirholas/three.ws#roadmap) covers native
+ home-screen widgets, the other surface where an agent shows up outside a browser.
+
+---
+
+<a id="sec-453"></a>
> **Source:** `docs/tutorials/add-a-3d-assistant.md` · [↑ table of contents](#table-of-contents)
@@ -94556,7 +99306,7 @@ Then ask, in plain language: "build a 3D assistant widget named Aria with an oce
---
-<a id="sec-434"></a>
+<a id="sec-454"></a>
> **Source:** `docs/tutorials/agent-personality.md` · [↑ table of contents](#table-of-contents)
@@ -95009,7 +99759,7 @@ The system prompt is the cheapest, highest-leverage thing you can change about a
---
-<a id="sec-435"></a>
+<a id="sec-455"></a>
> **Source:** `docs/tutorials/agent-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -95286,7 +100036,7 @@ A read costs nothing and asks no one's permission. That's the property that lets
---
-<a id="sec-436"></a>
+<a id="sec-456"></a>
> **Source:** `docs/tutorials/agent-spending-envelope.md` · [↑ table of contents](#table-of-contents)
@@ -95849,7 +100599,7 @@ The two "budget stays reserved" cases are the only place the system deliberately
---
-<a id="sec-437"></a>
+<a id="sec-457"></a>
> **Source:** `docs/tutorials/animate-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -96025,7 +100775,7 @@ The difference that matters is the layer. `wave`, `point`, `nod` and `shrug` are
---
-<a id="sec-438"></a>
+<a id="sec-458"></a>
> **Source:** `docs/tutorials/animate-your-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -96207,7 +100957,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-453)), 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-473)), 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.
@@ -96245,16 +100995,16 @@ You learned the apply-and-remix workflow for motion on three.ws:
**See also:**
-- [docs/animations.md](#sec-093): the runtime animation registry, manifest, and agent slot reference.
+- [docs/animations.md](#sec-095): 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-491), loading and switching avatars in the Studio.
-- [docs/tutorials/upload-custom-glb.md](#sec-494), getting a Mixamo or custom rig into three.ws as a clean, animatable GLB.
+- [docs/tutorials/swap-avatar-in-studio.md](#sec-511), loading and switching avatars in the Studio.
+- [docs/tutorials/upload-custom-glb.md](#sec-514), 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-439"></a>
+<a id="sec-459"></a>
> **Source:** `docs/tutorials/arm-an-agent-sniper.md` · [↑ table of contents](#table-of-contents)
@@ -96368,7 +101118,7 @@ The hard-config sniper you just armed is the control group. The next phase runs
---
-<a id="sec-440"></a>
+<a id="sec-460"></a>
> **Source:** `docs/tutorials/build-a-3d-asset-pipeline.md` · [↑ table of contents](#table-of-contents)
@@ -96587,7 +101337,7 @@ step once the mechanical stages are running.
---
-<a id="sec-441"></a>
+<a id="sec-461"></a>
> **Source:** `docs/tutorials/build-a-scene.md` · [↑ table of contents](#table-of-contents)
@@ -96806,7 +101556,7 @@ The leverage of [Scene Studio](/scene) is that it's a *real* editor producing a
---
-<a id="sec-442"></a>
+<a id="sec-462"></a>
> **Source:** `docs/tutorials/build-a-site-concierge.md` · [↑ table of contents](#table-of-contents)
@@ -96924,7 +101674,7 @@ Then: `<three-concierge endpoint="/my/concierge">`. The production reference, wi
---
-<a id="sec-443"></a>
+<a id="sec-463"></a>
> **Source:** `docs/tutorials/character-library-to-embed.md` · [↑ table of contents](#table-of-contents)
@@ -97429,7 +102179,7 @@ Doing the copy server-side also sidesteps cross-origin reads and browser upload
---
-<a id="sec-444"></a>
+<a id="sec-464"></a>
> **Source:** `docs/tutorials/claim-threews-name.md` · [↑ table of contents](#table-of-contents)
@@ -97555,7 +102305,7 @@ The server then, in order:
1. Confirms minting is configured (the platform parent key is present) — otherwise `503 config_missing`.
2. Loads your user, confirms you have a username, and confirms it **matches the label** — otherwise `409`.
-3. Confirms nobody has claimed it through three.ws and nobody owns it on-chain — otherwise `409 conflict`.
+3. Confirms nobody has claimed it through three.ws and nobody owns it on-chain, otherwise `409 conflict`. Unlike the availability check, this on-chain lookup is a hard gate: if Solana RPC cannot answer, the mint stops with a retryable `503 upstream_unavailable` instead of attempting a transaction that would burn rent and fail.
4. Picks the **recipient wallet**: if you pass `owner_wallet` it must be a Solana wallet **linked to your account** (else `403 forbidden`); otherwise it falls back to your **default agent's Solana wallet** (the oldest agent you own). No agent and no linked wallet → `409 no_wallet`.
5. Runs the atomic mint + URL-record + transfer transaction and records the claim in `user_subdomains`.
@@ -97605,6 +102355,8 @@ const { data } = await r.json();
`/api/sns` is the public resolver. A miss returns `resolved: false` with `address: null` (a `200`, not a `404`) — so if you see `resolved: false` right after minting, give the RPC cache its short TTL and retry.
+Add `&domains=1` to either direction (`?name=` or `?address=`) to also get the owner's full `.sol` holdings: the envelope gains `all_domains`, `favorite_domain`, and `domains_truncated`. It is opt-in because it costs two extra calls to the Bonfida index, and it is best-effort, so an index outage returns the plain envelope rather than an error.
+
**In Brave:** type `nich.threews.sol` into the URL bar. Because the `URL` record was written at mint time, Brave's SNS resolver redirects you straight to `https://three.ws/u/nich` — your showcase, rendering your public agents, avatars, paid skills, and socials. No extension, no plugin.
---
@@ -97712,6 +102464,7 @@ Either way, the USDC lands in the wallet your `nich.threews.sol` points at — t
- **`409 no_wallet`** — you passed no `owner_wallet` and have no agent. Create an agent (it provisions a Solana wallet) or link a Solana wallet and pass it as `owner_wallet`.
- **`403 forbidden` on mint** — the `owner_wallet` you passed isn't linked to your account. Link it first; three.ws won't mint into an unlinked wallet.
- **`503 config_missing`** — subdomain minting isn't configured on this deployment (the platform parent key is absent). This is an environment issue, not a request error.
+- **`503 upstream_unavailable` on mint**: the pre-mint on-chain ownership check could not reach Solana RPC. Nothing was minted; retry in a moment.
- **`401 unauthorized`** — minting and `mode=send` need a signed-in session or bearer token. The availability check and `mode=prep` preview do not.
- **`/api/sns` says `resolved: false` right after minting** — resolution is cached briefly; the negative cache TTL is short. Wait a few seconds and re-resolve.
- **Pay-by-name `404 not_found`** — the name doesn't resolve. Confirm the exact spelling (`<label>.threews.sol`), or use the GET resolver to see what it points at.
@@ -97737,7 +102490,7 @@ See also:
---
-<a id="sec-445"></a>
+<a id="sec-465"></a>
> **Source:** `docs/tutorials/connect-ai-brain.md` · [↑ table of contents](#table-of-contents)
@@ -98159,7 +102912,7 @@ The brain is the part of the agent you'll iterate on most after the system promp
---
-<a id="sec-446"></a>
+<a id="sec-466"></a>
> **Source:** `docs/tutorials/create-and-edit-memory.md` · [↑ table of contents](#table-of-contents)
@@ -98480,7 +103233,7 @@ The leverage is in *enhancement*: the right type, one fact per memory, tags, del
---
-<a id="sec-447"></a>
+<a id="sec-467"></a>
> **Source:** `docs/tutorials/custom-skill.md` · [↑ table of contents](#table-of-contents)
@@ -99005,7 +103758,7 @@ The skill installs via a URI in the agent manifest, runs entirely client-side, a
---
-<a id="sec-448"></a>
+<a id="sec-468"></a>
> **Source:** `docs/tutorials/customize-appearance.md` · [↑ table of contents](#table-of-contents)
@@ -99443,7 +104196,7 @@ Most production embeds use four or five of these together. The combination is wh
---
-<a id="sec-449"></a>
+<a id="sec-469"></a>
> **Source:** `docs/tutorials/deploy-to-vercel-custom-domain.md` · [↑ table of contents](#table-of-contents)
@@ -99963,7 +104716,7 @@ In rough order of likelihood:
---
-<a id="sec-450"></a>
+<a id="sec-470"></a>
> **Source:** `docs/tutorials/earn-and-spend-in-play.md` · [↑ table of contents](#table-of-contents)
@@ -100158,16 +104911,16 @@ Every paid sale splits 50% to the holder-rewards sink and 50% to the treasury.
## Next
-- **[The in-game economy](#sec-255)** is the full reference: every
+- **[The in-game economy](#sec-265)** 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-145)** explains the worlds themselves, and how
+- **[Coin communities](#sec-149)** explains the worlds themselves, and how
any coin becomes a walkable 3D space.
---
-<a id="sec-451"></a>
+<a id="sec-471"></a>
> **Source:** `docs/tutorials/embed-in-30-seconds.md` · [↑ table of contents](#table-of-contents)
@@ -100443,7 +105196,7 @@ A working embedded agent is the foundation everything else builds on. From here,
---
-<a id="sec-452"></a>
+<a id="sec-472"></a>
> **Source:** `docs/tutorials/embed-on-website.md` · [↑ table of contents](#table-of-contents)
@@ -100954,7 +105707,7 @@ Squarespace's developer preview and published output can differ. Try adding the
---
-<a id="sec-453"></a>
+<a id="sec-473"></a>
> **Source:** `docs/tutorials/emotion-from-data.md` · [↑ table of contents](#table-of-contents)
@@ -101065,7 +105818,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-252)) 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-262)) 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`.
@@ -101181,7 +105934,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-252)).
+- **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-262)).
---
@@ -101196,7 +105949,7 @@ function reactIfConfident(clipOrEmoteName, { confident, useExactClip = false } =
---
-<a id="sec-454"></a>
+<a id="sec-474"></a>
> **Source:** `docs/tutorials/explore-docs-world.md` · [↑ table of contents](#table-of-contents)
@@ -101273,13 +106026,13 @@ Make one with the [Forge](/create) or the [Avatar Studio](/avatar-studio), copy
## Where to next
-- [Docs World reference](#sec-180): controls table, device behaviour, contributor notes.
-- [What is three.ws?](#sec-411): the guided tour of the whole platform, readable in either surface.
+- [Docs World reference](#sec-186): controls table, device behaviour, contributor notes.
+- [What is three.ws?](#sec-429): 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-455"></a>
+<a id="sec-475"></a>
> **Source:** `docs/tutorials/find-a-better-exit-policy.md` · [↑ table of contents](#table-of-contents)
@@ -101482,7 +106235,7 @@ returned over every replayable trade in the corpus, with the caveats attached an
the underlying transactions one click away.
If you run your own agent, the same parameters are what
-[`/api/sniper/strategy`](#sec-096) accepts, so a finding here maps
+[`/api/sniper/strategy`](#sec-098) accepts, so a finding here maps
directly onto a strategy you can arm. Read
[Arm an autonomous sniper](/tutorials/arm-an-agent-sniper) for that path, and
size it small first: an in-sample optimum is a description of the past, and the
@@ -101522,7 +106275,7 @@ disclaimers bolted onto the result. They are the result.
---
-<a id="sec-456"></a>
+<a id="sec-476"></a>
> **Source:** `docs/tutorials/first-agent.md` · [↑ table of contents](#table-of-contents)
@@ -102031,7 +106784,7 @@ Now that you have a working agent, here's what to explore next:
---
-<a id="sec-457"></a>
+<a id="sec-477"></a>
> **Source:** `docs/tutorials/first-prompt-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -102151,7 +106904,7 @@ A rigged avatar's AR link gains a **Bring it to life** option: instead of a froz
---
-<a id="sec-458"></a>
+<a id="sec-478"></a>
> **Source:** `docs/tutorials/generate-3d-api.md` · [↑ table of contents](#table-of-contents)
@@ -102376,7 +107129,7 @@ If you've never made an x402 call, start with [Build a paid x402 endpoint](/tuto
---
-<a id="sec-459"></a>
+<a id="sec-479"></a>
> **Source:** `docs/tutorials/getting-started.md` · [↑ table of contents](#table-of-contents)
@@ -102561,7 +107314,7 @@ Everything is editable forever — swap the body, rewrite the prompt, add capabi
---
-<a id="sec-460"></a>
+<a id="sec-480"></a>
> **Source:** `docs/tutorials/greeting-and-first-speech.md` · [↑ table of contents](#table-of-contents)
@@ -102909,7 +107662,7 @@ A working greeting moves the embed from "decoration" to "interaction", which is
---
-<a id="sec-461"></a>
+<a id="sec-481"></a>
> **Source:** `docs/tutorials/image-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -103012,7 +107765,7 @@ Everything you generate is kept in **Your creations** at the bottom of the page,
---
-<a id="sec-462"></a>
+<a id="sec-482"></a>
> **Source:** `docs/tutorials/import-avatar-url.md` · [↑ table of contents](#table-of-contents)
@@ -103182,7 +107935,7 @@ The URL path and the file-upload path converge on the same avatar record and the
---
-<a id="sec-463"></a>
+<a id="sec-483"></a>
> **Source:** `docs/tutorials/js-api-events.md` · [↑ table of contents](#table-of-contents)
@@ -103648,7 +108401,7 @@ The `whenReady`, awaited-`ask()`, and try/catch patterns are small but they remo
---
-<a id="sec-464"></a>
+<a id="sec-484"></a>
> **Source:** `docs/tutorials/mcp-server-for-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -104303,7 +109056,7 @@ Things that look right but bite you:
---
-<a id="sec-465"></a>
+<a id="sec-485"></a>
> **Source:** `docs/tutorials/mine-vanity-address.md` · [↑ table of contents](#table-of-contents)
@@ -104360,7 +109113,7 @@ A **case-insensitive** match (matching letters in any case) roughly halves the w
Two ways to do the grind exist on three.ws, and they solve different problems:
- **In-browser grind ([/vanity-wallet](/vanity-wallet))** — your machine generates the keypair. Nothing is sent anywhere, so there's nothing to trust. Free, up to 6 pattern characters.
-- **Provably-fair paid grind (`/api/x402/vanity-verifiable`)** — three.ws's servers do the work and hand back a **signed receipt**. Because someone else generated your key, the protocol exists to *prove* they did it honestly and never kept a copy. This is the `three-vanity/v1` protocol, specified in [docs/PROTOCOL-vanity.md](#sec-005).
+- **Provably-fair paid grind (`/api/x402/vanity-verifiable`)** — three.ws's servers do the work and hand back a **signed receipt**. Because someone else generated your key, the protocol exists to *prove* they did it honestly and never kept a copy. This is the `three-vanity/v1` protocol, specified in [docs/PROTOCOL-vanity.md](#sec-006).
Start with the browser grind. It's the right default for almost everyone.
@@ -104461,7 +109214,7 @@ If you buy a grind from the paid endpoint (`/api/x402/vanity-verifiable`, an x40
4. the receipt was **signed by the real three.ws service key**, not an impostor;
5. (optionally) the key you recovered from the sealed envelope is byte-for-byte the one the receipt describes — **you alone hold it**.
-A receipt is a JSON object carrying the `commitment`, the revealed `serverSeed` and `clientSeed`, the `requestNonce`, the `winningIndex`, the `pattern`, the `difficulty`, and an Ed25519 `signature` over a canonical projection of those fields. When you supply a `sealTo` X25519 public key, the secret is delivered as a `sealedSecret` envelope encrypted to you — the plaintext key never appears in the response. The full field list and signing rules are in [docs/PROTOCOL-vanity.md](#sec-005).
+A receipt is a JSON object carrying the `commitment`, the revealed `serverSeed` and `clientSeed`, the `requestNonce`, the `winningIndex`, the `pattern`, the `difficulty`, and an Ed25519 `signature` over a canonical projection of those fields. When you supply a `sealTo` X25519 public key, the secret is delivered as a `sealedSecret` envelope encrypted to you — the plaintext key never appears in the response. The full field list and signing rules are in [docs/PROTOCOL-vanity.md](#sec-006).
---
@@ -104575,17 +109328,17 @@ You learned to mine a Solana vanity address and to operate the proof-of-grind pr
- **Bounties** ([/vanity/bounties](/vanity/bounties)) — escrow a USDC reward for a hard pattern; a fleet grinds it and seals the result to you.
- **CREATE2 vanity** ([/eth-vanity](/eth-vanity)) — the same grind for Ethereum contract addresses, searching salts, no keys involved.
-The protocol itself is fully specified in [docs/PROTOCOL-vanity.md](#sec-005), and the verifier is open source — you never have to take three.ws's word for it.
+The protocol itself is fully specified in [docs/PROTOCOL-vanity.md](#sec-006), and the verifier is open source — you never have to take three.ws's word for it.
## See also
-- [three-vanity/v1 protocol specification](#sec-005) — the commit–reveal, seed-mixing, sealed-delivery, and signing scheme in full
+- [three-vanity/v1 protocol specification](#sec-006) — the commit–reveal, seed-mixing, sealed-delivery, and signing scheme in full
- [Create, enhance & edit agent memory](/docs/tutorials/create-and-edit-memory) — give the agent that owns your vanity wallet durable context
- [Build a Custom Skill](/docs/tutorials/custom-skill) — extend that agent with new capabilities at runtime
---
-<a id="sec-466"></a>
+<a id="sec-486"></a>
> **Source:** `docs/tutorials/mint-pumpfun-token.md` · [↑ table of contents](#table-of-contents)
@@ -104946,7 +109699,7 @@ If you have a lawyer, talk to them before launching. If you don't, default to th
---
-<a id="sec-467"></a>
+<a id="sec-487"></a>
> **Source:** `docs/tutorials/monetize-mcp-server.md` · [↑ table of contents](#table-of-contents)
@@ -105262,7 +110015,7 @@ That connector can search the bazaar, read your challenge without paying (`inspe
---
-<a id="sec-468"></a>
+<a id="sec-488"></a>
> **Source:** `docs/tutorials/multi-agent-coordination.md` · [↑ table of contents](#table-of-contents)
@@ -105667,7 +110420,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-297).
+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-307).
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.
@@ -105822,7 +110575,7 @@ async function safeHandoff(targetEl, brief, fallbackEl, originalQuestion) {
---
-<a id="sec-469"></a>
+<a id="sec-489"></a>
> **Source:** `docs/tutorials/nvidia-3d-free.md` · [↑ table of contents](#table-of-contents)
@@ -105944,7 +110697,7 @@ It talks **directly** to a TRELLIS NIM and returns the GLB **synchronously** in
---
-<a id="sec-470"></a>
+<a id="sec-490"></a>
> **Source:** `docs/tutorials/nvidia-nim-self-host.md` · [↑ table of contents](#table-of-contents)
@@ -106127,7 +110880,7 @@ The proxy normalizes every documented artifact shape (inline `base64`, a bare st
---
-<a id="sec-471"></a>
+<a id="sec-491"></a>
> **Source:** `docs/tutorials/paid-x402-endpoint.md` · [↑ table of contents](#table-of-contents)
@@ -106819,7 +111572,7 @@ Both work. Choose based on whether your endpoint is part of an agent platform yo
---
-<a id="sec-472"></a>
+<a id="sec-492"></a>
> **Source:** `docs/tutorials/pay-for-x402-service.md` · [↑ table of contents](#table-of-contents)
@@ -107047,7 +111800,8 @@ If the result looks wrong but you were charged, note: x402 has **single-shot, no
- **"Endpoint did not return 402 (got 200/404…)"** — you pointed `pay()` at a free or non-x402 URL. Confirm the endpoint actually challenges with `curl -i <url>` (Step 3).
- **402 but "no `accepts` array could be found"** — a proxy stripped the body *and* the `payment-required` header, or the seller's challenge is malformed. Try the endpoint's own canonical URL; if it's third-party, the seller's 402 is non-compliant.
- **Signature rejected at settle on Base** — almost always a wrong EIP-712 domain. Base USDC's domain name is `"USD Coin"` at version `"2"`; a seller advertising anything else produces a payload the facilitator rejects. Nothing you can fix as a buyer — report it to the provider.
-- **Solana checkout fails at "Authorize"** — usually a stale blockhash on a flaky RPC; the prepare endpoint fails open to a recent cached blockhash, so simply retry. A too-stale blockhash never confirms and never double-charges.
+- **Solana checkout fails at "Authorize"**: usually a stale blockhash on a flaky RPC; the prepare endpoint fails open to a recent cached blockhash, so simply retry. A too-stale blockhash never confirms and never double-charges. When the chain is unreadable and nothing is cached, `/api/x402-checkout?action=prepare` answers a typed `503 rpc_unavailable` with a `Retry-After: 15` header instead of an opaque 500; the agent-wallet path (`POST /api/x402-pay`) returns the same code with a note that no funds were transferred.
+- **"The Solana wallet component could not be loaded"**: the Solana path fetches `@solana/web3.js` on demand from esm.sh, then jsdelivr and unpkg for the same pinned version, each under a deadline. All three failing means the host page's Content-Security-Policy is blocking third-party modules; the message names the hosts it tried and steers you to a Base wallet, which needs no third-party code.
- **Clicking an MCP card doesn't open a payment modal** — by design; MCP tools open the details panel. Wire them through an MCP client ([mcp-server-for-your-agent](/tutorials/mcp-server-for-your-agent)).
- **Endpoint Shopper button stays disabled** — the budget is below $0.01 or the task is empty; the hint under the button names the exact unmet precondition.
@@ -107094,7 +111848,7 @@ package family is listed under [x402 → Open-source packages](/x402#open-source
---
-<a id="sec-473"></a>
+<a id="sec-493"></a>
> **Source:** `docs/tutorials/personal-ai-site.md` · [↑ table of contents](#table-of-contents)
@@ -107649,7 +112403,7 @@ The technical investment is one HTML file, a GLB avatar, and a system prompt. Th
---
-<a id="sec-474"></a>
+<a id="sec-494"></a>
> **Source:** `docs/tutorials/place-agent-irl.md` · [↑ table of contents](#table-of-contents)
@@ -107899,7 +112653,7 @@ This is fundamentally different from viewing a single model in AR. If you only n
---
-<a id="sec-475"></a>
+<a id="sec-495"></a>
> **Source:** `docs/tutorials/prompts-for-3d.md` · [↑ table of contents](#table-of-contents)
@@ -108035,7 +112789,7 @@ The tiers are explained in detail in [the text-to-3D tutorial](/tutorials/text-t
---
-<a id="sec-476"></a>
+<a id="sec-496"></a>
> **Source:** `docs/tutorials/read-the-trading-fleet.md` · [↑ table of contents](#table-of-contents)
@@ -108262,7 +113016,7 @@ funds.
---
-<a id="sec-477"></a>
+<a id="sec-497"></a>
> **Source:** `docs/tutorials/register-onchain.md` · [↑ table of contents](#table-of-contents)
@@ -108611,7 +113365,7 @@ Your agent's URL will keep working as long as Base exists and IPFS gateways serv
---
-<a id="sec-478"></a>
+<a id="sec-498"></a>
> **Source:** `docs/tutorials/render-avatar-images.md` · [↑ table of contents](#table-of-contents)
@@ -109156,7 +113910,7 @@ If you want a talking, animated agent rather than a viewer, that is the `<agent-
---
-<a id="sec-479"></a>
+<a id="sec-499"></a>
> **Source:** `docs/tutorials/self-host-agent-backend.md` · [↑ table of contents](#table-of-contents)
@@ -109388,6 +114142,8 @@ curl http://localhost:3000/api/healthz
You should get a JSON body starting `{"status":"ok","service":"3d-agent",...}`, with `uptime`, the resolved `version`, and a per-subsystem readiness block (`x402`, mail, and so on). Anything other than `"status":"ok"` names the subsystem that is unhappy.
+Look at the response headers too. Every handler that goes through `wrap()` in `api/_lib/http.js` stamps its response with `x-brownout` (and `x-brownout-trace` when an upstream was involved), saying which provider or cache tier answered and how fresh the data is; the same seam honours an `x-brownout-chaos` directive for reproducing an outage on demand. Both are documented in [Brownout](#sec-133), and neither needs any configuration on your fork.
+
Now open `http://localhost:3000` in a browser. You should land on the platform's home page. Click into the editor — drag any GLB onto it — confirm the avatar loads. Open DevTools → Console. **There should be no red errors.** If there are, the most common causes:
- Database tables missing → re-run the schema in Step 3
@@ -109513,7 +114269,7 @@ Up to this point, anyone embedding an agent from your platform is loading the bu
**1. The embed generator derives its URL from the page origin.** The "Copy embed" output is built by `src/editor/publish.js`, which emits `` `${origin}/dist-lib/agent-3d.js` `` from the origin the dashboard is running on. Once your fork is served from `agent.yourcompany.com`, every copied snippet already points at your domain — no build constant to set.
-**2. The bundle itself self-locates.** The element derives its API base from the script's own URL (`new URL(import.meta.url).origin`, see `src/element.js:123`), falling back to the page origin, and can be overridden per element with the `api-base` attribute. A third party who pastes your embed on `their-site.com` will have the script fetch agents from *your* domain, not theirs, and you can move infrastructure later without breaking existing embeds.
+**2. The bundle itself self-locates.** The element derives its API base from the script's own URL (`new URL(import.meta.url).origin`, the `apiBase` resolution in `src/element.js`), falling back to the page origin, and can be overridden per element with the `api-base` attribute. A third party who pastes your embed on `their-site.com` will have the script fetch agents from *your* domain, not theirs, and you can move infrastructure later without breaking existing embeds.
Verify with a smoke test: create a static HTML file and paste your embed:
@@ -109536,24 +114292,26 @@ Open it in a browser. The agent should load and chat correctly. Check the Networ
## Step 12 — Hardening: CORS
-`api/_lib/http.js` exposes a `cors()` helper used by every paid route. The default policy is permissive (`Access-Control-Allow-Origin: *`) because the platform is designed to be embedded from anywhere. That's the right call for the public CDN script and for x402 endpoints (anyone with a wallet should be able to pay you).
+`api/_lib/http.js` exposes a `cors()` helper that every route calls first. Its default policy is an allowlist, not a wildcard: with no `origins` option it reflects the request origin only when it is your `APP_ORIGIN`, one of the partner origins pinned in `isAllowedOrigin()` (x402scan, agentic.market, `*.ibm.com` and its Seismic CMS gateway), or `localhost` outside production. Any other origin gets no `access-control-allow-origin` header at all, so a session-cookie route is safe cross-origin by default.
-For **internal** routes that shouldn't be called cross-origin — admin actions, account routes, the dashboard API — tighten CORS to your domain:
+Two ways to widen it, both explicit at the call site:
```js
import { cors } from '../_lib/http.js';
-export default async function handler(req, res) {
- if (cors(req, res, {
- origin: 'https://agent.yourcompany.com',
- methods: 'GET,POST,OPTIONS',
- credentials: true,
- })) return;
- // ... handler
-}
+// Public, embeddable from anywhere: the CC0 object manifest, x402 endpoints
+// (anyone with a wallet should be able to pay you), the CDN script.
+if (cors(req, res, { origins: '*', methods: 'GET,OPTIONS' })) return;
+
+// A named list. Strings match exactly; a RegExp matches a family of hosts.
+if (cors(req, res, {
+ origins: ['https://agent.yourcompany.com', /^https:\/\/[a-z0-9-]+\.yourcompany\.com$/],
+ methods: 'GET,POST,OPTIONS',
+ credentials: true,
+})) return;
```
-Audit which routes are sensitive. A simple rule: anything that uses the session cookie (`api/auth/*`, `api/dashboard/*`, account-scoped writes) should restrict CORS to your domain.
+`credentials: true` only takes effect on a matched, non-wildcard origin (the browser forbids cookies with `*`). On your fork the one thing to change is the partner list in `isAllowedOrigin()`: replace those pinned origins with the sites you actually embed on, and set `APP_ORIGIN` to your domain so the default reflects it.
---
@@ -109719,7 +114477,7 @@ A self-hosted instance with light traffic runs at $20–50/month all-in. The dom
---
-<a id="sec-480"></a>
+<a id="sec-500"></a>
> **Source:** `docs/tutorials/selfie-to-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -109758,7 +114516,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-109).)
+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-111).)
---
@@ -109920,7 +114678,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-109) 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-111) 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.
---
@@ -109969,13 +114727,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-109) — the full reference: every creation path, rig requirements, and accessories.
+- [Avatar Creation](#sec-111) — 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-481"></a>
+<a id="sec-501"></a>
> **Source:** `docs/tutorials/sell-a-skill-with-a-trial.md` · [↑ table of contents](#table-of-contents)
@@ -110117,7 +114875,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-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.
+> **This is a real bug we shipped, not a hypothetical.** The [circulation engine](#sec-145) 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.
---
@@ -110188,7 +114946,7 @@ A healthy funnel shows a mix of `trial` rows with counts ticking down and `confi
---
-<a id="sec-482"></a>
+<a id="sec-502"></a>
> **Source:** `docs/tutorials/share-your-agent.md` · [↑ table of contents](#table-of-contents)
@@ -110216,7 +114974,7 @@ Go to [https://three.ws/my-agents](https://three.ws/my-agents). Sign in if you'r
You see a grid of every agent you own. Click the agent you want to share. The agent's profile page opens at a URL of this shape:
```
-https://three.ws/agent/d94d2a50-86fa-4d2e-b87b-580f7517aa4c
+https://three.ws/agents/d94d2a50-86fa-4d2e-b87b-580f7517aa4c
```
The `<id>` is your agent's permanent identifier: a UUID, assigned when the agent is first saved. Copy the full URL from the browser's address bar and it works forever.
@@ -110261,7 +115019,7 @@ Both produce QR codes that work with every modern phone camera. For most uses, a
If you don't want to leave the documentation flow, you can generate a code in two seconds using an inline service. Open this URL in a new tab, replacing the encoded URL with your agent link:
```
-https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=https%3A%2F%2Fthree.ws%2Fagent%2FYOUR_AGENT_ID
+https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=https%3A%2F%2Fthree.ws%2Fagents%2FYOUR_AGENT_ID
```
The page returns a 400x400 PNG of the QR code. Right-click → Save As to download it.
@@ -110269,7 +115027,7 @@ The page returns a 400x400 PNG of the QR code. Right-click → Save As to downlo
For an SVG (which scales infinitely without loss, important for print):
```
-https://api.qrserver.com/v1/create-qr-code/?size=400x400&format=svg&data=https%3A%2F%2Fthree.ws%2Fagent%2FYOUR_AGENT_ID
+https://api.qrserver.com/v1/create-qr-code/?size=400x400&format=svg&data=https%3A%2F%2Fthree.ws%2Fagents%2FYOUR_AGENT_ID
```
### Sizing the QR code for real-world use
@@ -110303,17 +115061,17 @@ three.ws builds those tags automatically. You do not configure anything for the
### Share the `/share` URL, not the bare profile URL
-The agent profile page at `/agent/<id>` is a JavaScript app. Its HTML carries the generic three.ws card, because at the moment a crawler fetches it, the page has not yet loaded which agent it is about. So the platform serves a second, server-rendered address purely for crawlers:
+The agent profile page at `/agents/<id>` is a JavaScript app. Its HTML carries the generic three.ws card, because at the moment a crawler fetches it, the page has not yet loaded which agent it is about. So the platform serves a second, server-rendered address purely for crawlers:
```
-https://three.ws/agent/<id>/share
+https://three.ws/agents/<id>/share
```
-That page is plain HTML with your agent's real meta baked into the `<head>`, and a redirect that sends a human straight on to `/agent/<id>`. A recipient who taps the link never sees it; the unfurler does. This is the URL the Share button copies, and the one to paste anywhere a preview matters.
+That page is plain HTML with your agent's real meta baked into the `<head>`, and a redirect that sends a human straight on to `/agents/<id>`. The older singular form, `/agent/<id>/share`, serves the same page, so links already in the wild keep unfurling. A recipient who taps the link never sees it; the unfurler does. This is the URL the Share button copies, and the one to paste anywhere a preview matters.
### What the previews contain
-When a platform fetches `https://three.ws/agent/<id>/share`, it sees:
+When a platform fetches `https://three.ws/agents/<id>/share`, it sees:
- **og:title**: `<agent name> · 3D AI Agent · three.ws`, or `<agent name> · 3D AI Agent on <chain> · three.ws` when the agent has been deployed on-chain.
- **og:description**: Your agent's description (first 120 characters), the chain it is deployed on if any, then `3D AI Agent on three.ws`.
@@ -110325,7 +115083,7 @@ When a platform fetches `https://three.ws/agent/<id>/share`, it sees:
Both image paths target the 1200x630 standard OG aspect.
-There is also a wallet variant, `/agent/<id>/share?wallet=1`, which swaps the copy and the deep link over to the agent's wallet view and always uses the generated card (the card is what carries the wallet identity). Use it when the thing you are sharing is the agent's wallet rather than the agent.
+There is also a wallet variant, `/agents/<id>/share?wallet=1`, which swaps the copy and the deep link over to the agent's wallet view and always uses the generated card (the card is what carries the wallet identity). Use it when the thing you are sharing is the agent's wallet rather than the agent.
### Preview freshness
@@ -110345,7 +115103,7 @@ Don't ship a link without testing the preview first. There are three levels of c
**Read the tags yourself.** One command, no third party, no cache in the way:
```bash
-curl -s https://three.ws/agent/YOUR_AGENT_ID/share \
+curl -s https://three.ws/agents/YOUR_AGENT_ID/share \
| grep -o '<meta[^>]*og:[^>]*>'
```
@@ -110359,7 +115117,7 @@ You should see your agent's name in `og:title` and a real image URL in `og:image
If a preview looks wrong, the causes in order of likelihood are:
-- **You shared `/agent/<id>` instead of `/agent/<id>/share`.** That gets the generic three.ws card. This is by far the most common one.
+- **You shared `/agents/<id>` instead of `/agents/<id>/share`.** That gets the generic three.ws card. This is by far the most common one.
- **The agent's name or description is unset** → set them in the editor and re-check.
- **The avatar is private**, so the card falls back to the generated SVG rather than your avatar's thumbnail → set the avatar's visibility to unlisted or public in the [avatar dashboard](/dashboard/avatars).
- **A platform cached an old version** → use its debugger's re-scrape button.
@@ -110386,7 +115144,7 @@ Each platform has its own conventions. Here is what works on each.
A line of plain text at the bottom of your email signature is the most under-used share context for personal agents.
```
-Talk to my AI: https://three.ws/agent/YOUR_AGENT_ID/share
+Talk to my AI: https://three.ws/agents/YOUR_AGENT_ID/share
```
The recipient sees the link and the email client unfurls a preview card if it supports OG (Gmail, Apple Mail, Outlook all do). For agents that represent you personally, this is a way to let every email recipient interact with your AI persona without an explicit invite.
@@ -110396,7 +115154,7 @@ The recipient sees the link and the email client unfurls a preview card if it su
A simple post with the URL works, but the engagement is higher if you give context:
```
-Built a 3D AI agent that knows my work. Ask it anything → https://three.ws/agent/YOUR_AGENT_ID/share
+Built a 3D AI agent that knows my work. Ask it anything → https://three.ws/agents/YOUR_AGENT_ID/share
```
X expands the URL into a large image card. The agent's preview image shows. Don't add a screenshot — let the auto-preview do the work; otherwise the platform sometimes hides the card.
@@ -110408,7 +115166,7 @@ LinkedIn's link unfurling is conservative. The post performs better if you write
```
I built a personal AI assistant that visitors can talk to instead of reading my "About me" page. It knows my work, my availability, and what I'm building right now.
-Try it: https://three.ws/agent/YOUR_AGENT_ID/share
+Try it: https://three.ws/agents/YOUR_AGENT_ID/share
```
LinkedIn shows the preview card below your post. Engagement is highest within the first few hours, so post during your network's morning timezone.
@@ -110443,7 +115201,7 @@ [email protected] │ ▓▓▓▓▓▓▓▓▓▓▓ │
│ │
└─────────────────┘
Talk to my AI:
- three.ws/agent/...
+ three.ws/agents/...
```
Include the short URL beneath the QR so people who can't scan in the moment can type it later.
@@ -110492,11 +115250,11 @@ Your share strategy:
1. **Embed on your portfolio site** — Following [Embed in 30 seconds](/tutorials/embed-in-30-seconds), you've added the one-line embed to the home page of your portfolio. Visitors can talk to Mara without leaving your site.
-2. **Public link in your email signature.** At the bottom of every email you send: "Available 24/7 to chat about projects → https://three.ws/agent/<MARA_ID>/share". Recipients can talk to Mara even when you're asleep, and the mail client unfurls her card inline.
+2. **Public link in your email signature.** At the bottom of every email you send: "Available 24/7 to chat about projects → https://three.ws/agents/<MARA_ID>/share". Recipients can talk to Mara even when you're asleep, and the mail client unfurls her card inline.
3. **QR on the back of your business card** — At networking events, instead of "I'll email you next week", you say "Scan my card, ask Mara about my work, and book a call directly through her if it's a fit". The conversation happens on your terms, on her schedule.
-4. **Social preview on launch posts** — Every quarter when you post a portfolio update on LinkedIn, you include the agent link. The auto-generated preview card shows Mara's 3D avatar with the title "Mara — Alex's UX consultant", which catches more attention than a plain text post.
+4. **Social preview on launch posts.** Every quarter when you post a portfolio update on LinkedIn, you include the agent link. The auto-generated preview card shows Mara's 3D avatar under the title "Mara · 3D AI Agent · three.ws", with the first 120 characters of her description as the card text, which catches more attention than a plain text post.
Each channel uses the right format for its medium. The underlying agent is one thing, maintained in one place, that you've defined once.
@@ -110527,9 +115285,9 @@ So plan on the URL being reachable by anyone who has it. For genuinely internal
## What you learned
-- Every agent has a permanent public URL at `https://three.ws/agent/<id>`, where the id is a UUID
+- Every agent has a permanent public URL at `https://three.ws/agents/<id>`, where the id is a UUID (the singular `/agent/<id>` form redirects there)
- The URL is stable across body swaps, system prompt updates, and skill changes
-- Rich previews come from `https://three.ws/agent/<id>/share`, a server-rendered page that carries the agent's real Open Graph, Twitter Card, and Farcaster Frame meta and forwards humans to the profile
+- Rich previews come from `https://three.ws/agents/<id>/share`, a server-rendered page that carries the agent's real Open Graph, Twitter Card, and Farcaster Frame meta and forwards humans to the profile
- The Share button on the profile page shows that card and copies the `/share` link for you
- Nothing is pre-rendered and nothing needs purging: edits appear in new previews within minutes, and the stale copy you see is usually the sharing platform's own cache
- A QR code generated from any standard service points to that URL for offline share
@@ -110552,7 +115310,7 @@ The agent's URL is the durable handle. Embed it, link it, print it. The agent sh
---
-<a id="sec-483"></a>
+<a id="sec-503"></a>
> **Source:** `docs/tutorials/ship-an-avatar-manifest.md` · [↑ table of contents](#table-of-contents)
@@ -110573,7 +115331,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-108) is the exhaustive flag-by-flag contract. This tutorial is the guided path through it.
+- Optional: the [Avatar CLI reference](#sec-110) is the exhaustive flag-by-flag contract. This tutorial is the guided path through it.
Every command below is real and runs as written.
@@ -110861,13 +115619,13 @@ A JSON file that names an avatar, pins its mesh by content rather than by locati
**Next:**
-- The [Avatar CLI reference](#sec-108) documents every flag, exit code, and `--json` shape.
-- The [web component reference](#sec-523) covers everything `<agent-3d>` can do beyond rendering a body: voice, an LLM brain, memory, and skills.
+- The [Avatar CLI reference](#sec-110) documents every flag, exit code, and `--json` shape.
+- The [web component reference](#sec-543) 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-484"></a>
+<a id="sec-504"></a>
> **Source:** `docs/tutorials/shopify-shopping-assistant.md` · [↑ table of contents](#table-of-contents)
@@ -110985,7 +115743,7 @@ The [wire format](/docs/concierge) for the answer endpoint is documented, so you
---
-<a id="sec-485"></a>
+<a id="sec-505"></a>
> **Source:** `docs/tutorials/shopify-store-guide-advanced.md` · [↑ table of contents](#table-of-contents)
@@ -111295,7 +116053,7 @@ The clip URLs inside the manifest resolve **relative to the manifest**, so a sel
---
-<a id="sec-486"></a>
+<a id="sec-506"></a>
> **Source:** `docs/tutorials/shopify-store-guide.md` · [↑ table of contents](#table-of-contents)
@@ -111384,7 +116142,7 @@ It's powered by the open-source [`@three-ws/tour`](https://www.npmjs.com/package
---
-<a id="sec-487"></a>
+<a id="sec-507"></a>
> **Source:** `docs/tutorials/sign-with-your-avatar.md` · [↑ table of contents](#table-of-contents)
@@ -111598,9 +116356,9 @@ None of it replaces a human interpreter. It makes an avatar legible to signers i
**See also:**
-- [docs/sign-language.md](#sec-393): the full reference: vocabulary, developer APIs, and how the signing engine works
-- [docs/tutorials/animate-your-avatar.md](#sec-438): the clip library, retargeting, and animated GLB export in depth
-- [docs/web-component.md](#sec-523): every `<agent-3d>` attribute, including `sign-language`
+- [docs/sign-language.md](#sec-411): the full reference: vocabulary, developer APIs, and how the signing engine works
+- [docs/tutorials/animate-your-avatar.md](#sec-458): the clip library, retargeting, and animated GLB export in depth
+- [docs/web-component.md](#sec-543): 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
@@ -111608,7 +116366,7 @@ Primary call to action: open **[/sign-language](/sign-language)** and sign your
---
-<a id="sec-488"></a>
+<a id="sec-508"></a>
> **Source:** `docs/tutorials/skill-with-database-auth.md` · [↑ table of contents](#table-of-contents)
@@ -112346,7 +117104,7 @@ Before this skill faces a real visitor:
---
-<a id="sec-489"></a>
+<a id="sec-509"></a>
> **Source:** `docs/tutorials/solana-agent-reputation.md` · [↑ table of contents](#table-of-contents)
@@ -112538,7 +117296,7 @@ A read costs nothing and asks no one's permission — which is exactly what lets
---
-<a id="sec-490"></a>
+<a id="sec-510"></a>
> **Source:** `docs/tutorials/sperax-tour.md` · [↑ table of contents](#table-of-contents)
@@ -112709,7 +117467,7 @@ This is covered by an automated test — [`tour-sdk/test/director.test.mjs`](htt
---
-<a id="sec-491"></a>
+<a id="sec-511"></a>
> **Source:** `docs/tutorials/swap-avatar-in-studio.md` · [↑ table of contents](#table-of-contents)
@@ -112903,7 +117661,7 @@ The key insight is the snippet's stability. Once embedded, your customers' pages
---
-<a id="sec-492"></a>
+<a id="sec-512"></a>
> **Source:** `docs/tutorials/text-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -113031,7 +117789,7 @@ This is normal — prompt, generate, adjust, repeat is the workflow, not a failu
---
-<a id="sec-493"></a>
+<a id="sec-513"></a>
> **Source:** `docs/tutorials/trigger-from-page-events.md` · [↑ table of contents](#table-of-contents)
@@ -113535,7 +118293,7 @@ The pattern under all of these is the same: every recipe starts with `whenReady(
---
-<a id="sec-494"></a>
+<a id="sec-514"></a>
> **Source:** `docs/tutorials/upload-custom-glb.md` · [↑ table of contents](#table-of-contents)
@@ -113963,7 +118721,7 @@ Once the body is on the platform, the embed snippet doesn't change. The same `<a
---
-<a id="sec-495"></a>
+<a id="sec-515"></a>
> **Source:** `docs/tutorials/view-in-ar.md` · [↑ table of contents](#table-of-contents)
@@ -114152,7 +118910,7 @@ AR surface detection needs a moment to work. Move the phone slowly over the targ
---
-<a id="sec-496"></a>
+<a id="sec-516"></a>
> **Source:** `docs/tutorials/voice-and-lipsync.md` · [↑ table of contents](#table-of-contents)
@@ -114293,7 +119051,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-521)).
+**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-541)).
> 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.
@@ -114403,7 +119161,7 @@ The leverage is that the avatar drives its mouth from the *audio it actually pla
---
-<a id="sec-497"></a>
+<a id="sec-517"></a>
> **Source:** `docs/tutorials/walk-companion.md` · [↑ table of contents](#table-of-contents)
@@ -114756,7 +119514,7 @@ The leverage is composability: the same engine renders the corner mascot, the fu
---
-<a id="sec-498"></a>
+<a id="sec-518"></a>
> **Source:** `docs/tutorials/wallet-sign-in.md` · [↑ table of contents](#table-of-contents)
@@ -115040,7 +119798,7 @@ A wallet sign-in that works from any origin that can reach the API, survives the
---
-<a id="sec-499"></a>
+<a id="sec-519"></a>
> **Source:** `docs/tutorials/web-component-end-to-end.md` · [↑ table of contents](#table-of-contents)
@@ -115133,7 +119891,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-452) 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-472) covers the iframe path and the no-code platforms in depth.)
---
@@ -115639,12 +120397,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-452), the no-framework paths (Webflow, WordPress, Squarespace) for completeness
+- [Embed a three.ws agent on your website](#sec-472), 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-500"></a>
+<a id="sec-520"></a>
> **Source:** `docs/tutorials/write-a-guard.md` · [↑ table of contents](#table-of-contents)
@@ -115664,6 +120422,8 @@ We will build `check-fetch-timeouts`: a guard that refuses to build when server
This is a real class of bug. A `fetch` with no timeout hangs until the platform's own limit kills it, so one slow upstream turns into stacked requests, then a cold pool, then a 502 on an endpoint that has nothing to do with the slow service. It is invisible in review because the line looks completely normal.
+This guard has since shipped for real: [`scripts/check-fetch-timeouts.mjs`](../scripts/check-fetch-timeouts.mjs) runs in the `gate` chain as `npm run check:fetch-timeouts`, is registered in `data/guards.json` with an `append` proof, and is covered by [`tests/check-fetch-timeouts.test.js`](../tests/check-fetch-timeouts.test.js). The shipped version is stricter than the one built below (it balances parentheses to read each call's real extent, treats the shared bounded wrappers such as `fetchUpstream` as satisfying the rule, judges every `fetch` under `api/` whatever its URL, and skips a `fetch` that only appears inside a string). Follow the steps here to learn the shape, using a throwaway id such as `check-fetch-timeouts-tutorial` for the files you create, then read the shipped guard for the finished form.
+
---
## Step 1: write the checker
@@ -115948,7 +120708,7 @@ Your guard is done when all of these are true:
---
-<a id="sec-501"></a>
+<a id="sec-521"></a>
> **Source:** `docs/tutorials/x402-server-sdk.md` · [↑ table of contents](#table-of-contents)
@@ -116161,7 +120921,7 @@ const res = await pay('https://your.api/v1/embed', { method: 'POST', body });
---
-<a id="sec-502"></a>
+<a id="sec-522"></a>
> **Source:** `docs/ui-juice.md` · [↑ table of contents](#table-of-contents)
@@ -116185,8 +120945,13 @@ Three guarantees hold for every export:
`public/tokens.css` (`--duration-*`, `--ease-*`). No raw millisecond literals.
- **Reduced-motion-safe.** That token file zeroes every `--duration-*` under
`@media (prefers-reduced-motion: reduce)`. `reducedMotion()` reads the computed
- token, so each primitive lands on its correct final state with no animation —
- automatically, with an explicit JS fallback path as belt-and-braces.
+ token, so each primitive lands on its correct final state with no animation,
+ automatically, with an explicit JS fallback path as belt-and-braces. The same
+ media block also floors every animation and transition on the page to 1ms,
+ whether or not it was authored through a token; only elements marked
+ `data-motion="essential"` (or `.motion-keep`), `aria-busy` regions, progress
+ bars, spinners and loaders keep their motion, because a frozen spinner reads as
+ a hung page.
- **Real values only.** These are transition helpers over real numbers/series.
They never fabricate or sample inputs.
@@ -116214,6 +120979,10 @@ and the ES module import. The classes the helpers attach all live under the
Animate a number between two real values via `requestAnimationFrame`, preserving
the caller's formatting. Cancels any in-flight count-up on the same element.
Reduced motion → final value instantly. Stashes the target on `el.dataset.juiceVal`.
+The clock starts from the first frame's own timestamp and progress is clamped to
+`[0, 1]`, so no frame ever paints a value outside `[from, to]` (a `rAF` timestamp
+behind `performance.now()` used to drive the easing negative and flash garbage
+like "-42797%").
```js
countUp(volEl, 1200, 1875, { format: (n) => '$' + Math.round(n).toLocaleString() });
@@ -116283,6 +121052,11 @@ flip.play();
### `liveDot(state?, opts?)` / `setLiveDot(el, state, label?)`
Markup + in-place updater for an SSE status indicator mirroring the swarms
`.sw-live` vocabulary. States: `live` | `connecting` | `idle` | `error`.
+`setLiveDot` also keeps the state pinned: when the badge sits inside a
+`data-i18n-html` line, the async translation pass rewrites that line from a
+frozen snapshot of the original markup (badge included), so the helper watches
+the container's child list and re-stamps the last requested state and label
+whenever the markup around the badge is replaced.
```js
header.insertAdjacentHTML('beforeend', liveDot('connecting'));
@@ -116323,13 +121097,13 @@ should reach for these primitives rather than re-rolling RAF loops.
---
-<a id="sec-503"></a>
+<a id="sec-523"></a>
> **Source:** `docs/user-wallet.md` · [↑ table of contents](#table-of-contents)
# Your master wallet: the per-user custodial hub
-Every three.ws **agent** owns a wallet ([agent-wallets.md](#sec-072)). Separately, every **user account** can own one custodial wallet of its own: the **master wallet**. It is the financial hub for the person rather than the bot. You fund it once, then push money out to wherever it needs to be: into an agent's wallet so the agent can trade or pay for API calls, or straight out to any Solana address.
+Every three.ws **agent** owns a wallet ([agent-wallets.md](#sec-074)). Separately, every **user account** can own one custodial wallet of its own: the **master wallet**. It is the financial hub for the person rather than the bot. You fund it once, then push money out to wherever it needs to be: into an agent's wallet so the agent can trade or pay for API calls, or straight out to any Solana address.
Solana is the operative chain here. The master wallet also holds an EVM keypair (used for reading a Base USDC balance and for the chains where agents register an on-chain identity), but the send paths documented below are Solana only.
@@ -116362,9 +121136,9 @@ 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-171) 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-177) 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.
+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-074)), which a freeze never blocks.
## Auth model: session plus CSRF
@@ -116372,7 +121146,7 @@ Funds flow one way through the platform's plumbing: master wallet to agent walle
- Every write (`POST`) additionally requires a one-time CSRF token in `X-CSRF-Token`, obtained from `GET /api/csrf-token`. The token is bound to your user id, single-use, and expires after an hour. Missing: `403 csrf_missing`. Stale or wrong: `403 csrf_invalid`. Fetch a fresh token per write.
- Reads are rate limited at 60 per minute per user. Writes that move funds are limited to **5 per day per user**, and that limiter is critical: if its backend is unreachable in production the write is refused rather than uncapped. A `simulate: true` preview does **not** draw on that daily budget; previews have their own ceiling of 30 per minute per user, so pricing a transfer a few times can never lock you out of sending. Both money-moving routes are additionally limited per IP, as is wallet creation.
-See [authentication.md](#sec-103) for how sessions and CSRF tokens work in general.
+See [authentication.md](#sec-105) for how sessions and CSRF tokens work in general.
The examples below assume a browser-style cookie jar in `cookies.txt` and a token in `$CSRF`:
@@ -116542,7 +121316,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-518)) 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-538)) 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
@@ -116602,15 +121376,15 @@ 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-171) for limits, freeze, proof of custody, and recovery on the agent side
-- [vaults.md](#sec-518) 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-294) for how funds move across the whole platform
+- [agent-wallets.md](#sec-074) for the per-agent wallet this one funds, and its spend policy
+- [custody.md](#sec-177) for limits, freeze, proof of custody, and recovery on the agent side
+- [vaults.md](#sec-538) for what a funded agent wallet can then back
+- [authentication.md](#sec-105) for sessions, CSRF tokens, and why API keys do not apply here
+- [money-map.md](#sec-304) for how funds move across the whole platform
---
-<a id="sec-504"></a>
+<a id="sec-524"></a>
> **Source:** `docs/ux-flows/01-onboarding-creation.md` · [↑ table of contents](#table-of-contents)
@@ -116633,12 +121407,12 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
6. **Step 2 — Name & Brain.** Type agent name (required) and bio/description; optionally click a personality preset (researcher/support/podcast/artist/assistant/crypto/community/defi) to fill the bio; pick a model (`data-model`). Click "Continue" → `validateStep` requires a non-empty name (else toast "Please give your agent a name.").
7. (optional) Toggle **Crypto mode** (`#crypto-toggle`) to reveal crypto personality + crypto skills sections.
8. **Step 3 — Skills.** Toggle skill cards (`data-skill`: memory/think/pumpfun/solana/x402/web). Click "Continue to deploy".
- 9. **Step 4 — Deploy.** `startDeploy()` runs automatically: (a) POST `/api/agents` (name, description, resolved skills via `SKILL_MAP` + `BASE_SKILLS`, optional `avatar_id`); (b) POST `/api/widgets` (type `talking-agent`, config.agent_id); (c) builds embed `<script>` snippet + live URL `/agent/<id>`. Shows live status labels per phase.
+ 9. **Step 4, Deploy.** `startDeploy()` runs automatically: (a) POST `/api/agents` (name, description, resolved skills via `SKILL_MAP` + `BASE_SKILLS`, optional `avatar_id`); (b) POST `/api/widgets` (type `talking-agent`, config.agent_id); (c) builds embed `<script>` snippet + live URL `/agents/<id>`. Shows live status labels per phase.
10. On deploy success: success panel shows "<name> is live", live URL link, and an embed code block. (optional) Click "Copy" (`#copy-embed`) to copy the embed snippet. Click "Continue".
11. **Step 5 — Earn (conditional).** If crypto skills were selected: enter a per-call price (USDC, shown as USD-equivalent hint) and a payout wallet (chain auto-detected SOL vs ETH/BASE). Click "Save & finish" → `saveEarnSettings()` POSTs `/api/agents/:id/skills/set-price` (USDC mint) and `/api/billing/payout-wallets`, then clears state and redirects to `/dashboard?welcome=1`. If no crypto skills: a "skip" panel shows and the button reads "Go to dashboard" → straight to `/dashboard?welcome=1`.
- **Decision points / branches:** template vs blank start; resume saved session vs fresh; avatar method (selfie / editor / upload / skip); crypto-mode on/off → governs whether Step 5 is the Earn panel (price+wallet) or the Skip panel; deploy success vs failure (retry button injected).
- **External calls / dependencies:** `GET /api/csrf-token`; `POST /api/avatars` (upload); `POST /api/agents`; `POST /api/widgets`; `POST /api/agents/:id/skills/set-price`; `POST /api/billing/payout-wallets`. No on-chain txn from this page (wallet address is just registered as a payout target).
-- **Success state:** A real deployed agent + public widget, an embeddable `<script>` snippet, a live `/agent/<id>` URL, optional monetization configured; user lands on `/dashboard?welcome=1`.
+- **Success state:** A real deployed agent + public widget, an embeddable `<script>` snippet, a live `/agents/<id>` URL, optional monetization configured; user lands on `/dashboard?welcome=1`.
- **Empty / error states:** Toast (`#wz-toast`) for validation ("Please give your agent a name.", file-too-large). Deploy failure recolors the status label red and injects a "Try again" button that re-runs `startDeploy()`. Upload errors restore the card label.
- **Step count:** 6 required (gallery → name → skills → deploy auto → deploy success → finish) + ~5 optional (template apply, avatar upload, skip avatar, crypto toggle, earn setup).
@@ -116650,17 +121424,18 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
- **Prerequisites / gates:** Anonymous-friendly for the base-avatar editor / template / studio / direct GLB upload (guest avatar staged in IndexedDB; auth deferred to `/create-review`). **Auth-gated paths:** the selfie card (`requireAuthForSelfie` → redirect `/login?next=/create/selfie`), the prompt card (redirect `/login?next=/create/prompt`), and the video card (redirect `/login?next=/create/video`). Signed-in users also hit an avatar-quota check (`/api/usage/summary`) before opening a creator. No wallet/$THREE gate.
- **Steps (N):**
1. Land on `/create`. The page now opens with a four-card **intent hub**: "Build an AI agent" → `/create-agent`, "Make a 3D avatar" → `#avatar-options` (tagged "You're here"), "Generate a 3D model" → `/forge`, "Launch a token world" → `/launchpad`. The avatar method cards live below at `#avatar-options`.
- 2. `boot()` probes `/api/config` for the `videoAvatar` feature flag (greys out the video card if off) and, for signed-in users with avatars, loads `/api/avatars` to render a "Start from one of yours" remix strip. The prompt card cycles 7 example prompts with a reduced-motion-aware typewriter (`#card-prompt-example`).
- 3. (optional) If `?fork=<id>` present: `handleFork` runs immediately, POSTing `/api/avatars/fork` (signed-in → owned copy → redirect `/avatars/<id>`); on 401/403 falls back to fetching the source, downloading its GLB, staging a guest copy, and redirecting to `/create-review`.
+ 2. `boot()` probes `/api/config` for the `videoAvatar` feature flag with three outcomes: off dims the video card with a "Coming soon" chip and CTA (keyboard activation gets the same explanation as a click), an unanswered probe keeps the card live and re-asks on activation, and on leaves it untouched. For signed-in users with avatars it loads `/api/avatars` (the `{ avatars }` envelope) to render a "Start from one of yours" remix strip; a thumbnail whose storage object expired falls back to the silhouette. The prompt card cycles 7 example prompts with a reduced-motion-aware typewriter (`#card-prompt-example`).
+ 3. (optional) If `?fork=<id>` present: `handleFork` runs last, after every card is wired, POSTing `/api/avatars/fork` (signed-in → owned copy → redirect `/avatars/<id>`); on 401/403 falls back to fetching the source, downloading its GLB, staging a guest copy, and redirecting to `/create-review`. A remix that cannot load renders a persistent inline alert in `#create-alert-slot` ("That remix could not be loaded") with "Try the remix again" and "Start something new instead" (which drops `?fork=` from the URL), not a toast, so the visitor is never left on a page of cards wired to nothing.
4. Choose a creation method card: **Customize a base avatar** (`card-default-editor` → `AvatarCreator.openDefaultEditor`), **Describe it to 3D** (`card-prompt` → `/create/prompt`, auth-gated), **Start with a template** (`card-customize` → `createFromTemplate`), **Scan yourself to 3D** (`card-selfie` → `/create/selfie`, auth-gated), **Talking avatar video** (`card-video-avatar` → `/create/video`, feature-flagged + auth-gated), **Living world (Cosmos)** (`card-cosmos` → `/cosmos`), **Upload your own GLB** (`card-upload-glb` → `#glb-input`), or **Avatar Studio (beta)** (`card-agent-studio` → `/create/studio`).
5. (optional) Upload path: pick a `.glb`; `handleGlbFile` validates the GLB magic bytes, then `stageAndReview` stashes the blob via `guest-avatar.js` (IndexedDB) and navigates to `/create-review`.
6. (optional) Editor/Template path: the in-page `AvatarCreator` produces a GLB blob → `stageAndReview` → `/create-review`.
7. (optional) Remix strip: click a saved avatar thumbnail → `handleFork(av.id)` (same fork path as step 3).
+ 8. (optional) Android share-sheet handoff: a file shared into the installed app is POSTed to `/create/share`, parked in the Cache API by `public/share-target-sw.js`, and the visitor lands here with `?shared=glb` (a `.glb`, pulled back out through `src/shared/share-target.js` and fed into the upload path), `?shared=1` (a photo, handed on untouched to `/create/selfie?shared=1`), `?shared=nosw` (the worker was not installed yet; share again) or `?shared=error`. The read is one-shot, so a reload never re-attaches the file.
- **Decision points / branches:** intent hub (agent wizard / avatar options / Forge / launchpad) vs direct card pick; fork vs fresh; eight creation method cards (base editor / prompt / template / selfie / video / Cosmos / upload / studio); anonymous (stage→review) vs signed-in (direct save/fork); video flag on/off; avatar-quota reached vs not.
- **External calls / dependencies:** `GET /api/config`; `GET /api/avatars`; `GET /api/usage/summary`; `POST /api/avatars/fork`; `GET /api/avatars/:id` + raw GLB fetch (guest fork). External avatar-platform iframes loaded by `AvatarCreator`.
- **Success state:** A staged or owned avatar; the user is forwarded to `/create-review` (anonymous) or `/avatars/<id>` (forked) — onward to agent creation.
-- **Empty / error states:** `status-toast` for invalid GLB, fork failure, quota-limit; video card shows "coming soon" when flag off; save overlay (`#save-loading`) covers staging. Remix strip stays hidden for anonymous users / users with no avatars.
-- **Step count:** 2 required (land → pick a method) + ~4 optional (fork, upload, editor produce, remix).
+- **Empty / error states:** `status-toast` for invalid GLB, quota-limit, a feature probe that could not reach three.ws, and a shared file that was not a `.glb`; fork failure uses the inline alert; video card carries a "Coming soon" chip when the flag is off; the boot blackout clears after 6 s even if `/api/auth/me` never answers (treated as signed out, the auth-gated cards re-check at `/login`); save overlay (`#save-loading`) covers staging. Remix strip stays hidden for anonymous users / users with no avatars.
+- **Step count:** 2 required (land → pick a method) + ~5 optional (fork, upload, editor produce, remix, shared file).
---
@@ -116712,15 +121487,15 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
- **Steps (N):**
1. Land; `boot()` resolves auth. Signed out, the ship CTA relabels to "Sign in to ship <name> →" and a "no account needed to build" note (`#build-free-note`) unhides. A fresh guest draft (see below) or a guest-companion claim (`peekGuestAgent()` carries the companion's name in) can prefill the form.
2. **Step 0 (Basics).** Enter name (required, ≤60), description (≤280), and tags (≤8, Enter/comma to add). (optional) Use the **"Build it for me"** AI box: type a one-line brief (or a chip / "✦ Surprise me") → POST `/api/agents/suggest-spec` → the returned spec fills the whole wizard and jumps to Review. Guests can generate too; the guest rate limit maps a 429 to a sign-in nudge. Click "Next" → validates name present.
- 3. **Step 1 — Model.** Choose a body via one of four tabs: **Starter** (4 shipped GLBs: Vern/CZ/Saga/Boss with `model-viewer` previews), **Library** (your owned avatars, paginated via `GET /api/avatars`, filtered to avatar/creature categories), **Upload** (drag-drop `.glb` ≤16 MB, validated by GLB magic), or **Add later** (must tick the `#f-skip-ack` confirm box → default starter assigned at create). Selected model renders in the live preview. Click "Next" → requires a starter/upload/library pick or acknowledged skip.
+ 3. **Step 1, Model.** Choose a body via one of four tabs (a real ARIA tablist: arrow keys and Home/End move between them): **Starter** (4 shipped GLBs: Vern/CZ/Saga/Boss with `model-viewer` previews), **Library** (your owned avatars, paginated via `GET /api/avatars`, filtered to avatar/creature categories; signed out it never fires the request and shows "Sign in to reuse an avatar you already made" with a Sign in button that saves the draft first), **Upload** (drag-drop `.glb` ≤16 MB, validated by GLB magic), or **Add later** (must tick the `#f-skip-ack` confirm box → default starter assigned at create). Selected model renders in the live preview. Click "Next" → requires a starter/upload/library pick or acknowledged skip.
4. **Step 2 — Skills.** Five core skills (greet/present-model/validate-model/remember/think) are locked on; toggle optional skills (wave/dance/pump-fun/explain-gltf/web-search). Click "Next".
5. **Step 3, Personality.** Pick category (14 marketplace categories), greeting (≤200), and profile/system prompt (≤2000). (optional) Run the **onboarding interview** (`#interview-*`): answer any of the shared `INTERVIEW_QUESTIONS` in your own words → POST `/api/persona/interview` runs them through the platform LLM chain and writes the extracted paragraph into the profile field (editable), with tone tags rendered as chips; the structured result (traits, tone tags, vocabulary, answer provenance) rides in state until the agent exists. Click "Next" (soft tip if publishing without category+prompt).
6. **Step 4, Voice.** Pick **Built-in voice** or **Clone your voice** (`data-voice` buttons). Choosing custom mounts `VoiceSetup` in `bind:'later'` mode: record or upload a short sample (validated in-browser, with inline BYOK ElevenLabs key entry via `PATCH /api/user/provider-keys`); the sample is held in memory and bound after create. Click "Next".
7. **Step 5 (Review).** Editable summary grid (each row jumps back to its step). Toggle "Publish to marketplace" (`#f-publish`, default on). Click "Create" (or "Sign in to ship…" when signed out, which round-trips through `/login` and resumes here).
8. `submit()`: (a) resolves the body to a real owned avatar, via `saveRemoteGlbToAccount` for starter URL or uploaded file (with upload % progress), library = connect directly, none = assign default starter; (b) POST `/api/agents` (name, description, skills, avatar_id, meta with greeting/voice/tags); (c) if a custom voice sample is held → `voiceSetup.bindTo(agent.id)` clones it onto the new agent (non-fatal: a failure becomes a soft warning); (d) if publish opted-in AND category+prompt present → POST `/api/marketplace/agents/:id/publish`; (e) if the interview produced a result → POST `/api/agents/:id/persona/save` persists the structured persona with interview provenance (also best-effort).
- 9. Success panel: "<name> is ready", 3D preview if public, and buttons: **Go live** (`/agent/<id>/wallet#activate`, primary; claims the on-chain welcome grant), Fund wallet (`/agent/<id>/wallet#deposit`), Open (`/agent/<id>`), Edit (`/agent/<id>/edit`), Widget Studio (`/studio?model=<avatar_model_url>`), and Give it a voice (`/voice`).
+ 9. Success panel: "<name> is ready", 3D preview if public, and buttons: **Go live** (`/agents/<id>/wallet#activate`, primary; claims the on-chain welcome grant), Fund wallet (`/agents/<id>/wallet#deposit`), Open (`/agents/<id>`), Edit (`/agents/<id>/edit`), Widget Studio (`/studio?model=<avatar_model_url>`), and Give it a voice (`/voice`).
- **Guest draft autosave:** every input change debounce-saves (600 ms) to `localStorage['threews:create-agent:draft']` once the form has real content, with a `beforeunload` flush; drafts expire after 7 days (`src/create-agent-draft.js`). A returning guest resumes on the exact saved step with "Resumed your saved draft. [Start fresh]". A picked upload `File` cannot survive navigation: the draft marks it lost, downgrades the model to "Add later", and asks the user to re-attach on the model step. Creation stops the autosave so a shipped agent never resurrects as a draft.
-- **Decision points / branches:** signed-in ship vs signed-out login round-trip (draft preserved); AI-generated spec vs manual form; model tab (starter/library/upload/skip); interviewed persona vs hand-typed prompt (a fresh AI-spec fill resets the interview so a new concept never inherits the previous voice); built-in voice vs cloned sample; publish on/off and whether publish prerequisites are met (publishes vs creates private with a soft warning); name conflict (409 → bounce to Step 0 to rename); resume draft vs "Start fresh"; per-step jump-back via stepper pips and review "Edit" buttons.
+- **Decision points / branches:** signed-in ship vs signed-out login round-trip (draft preserved); AI-generated spec vs manual form; model tab (starter/library/upload/skip); interviewed persona vs hand-typed prompt (a fresh AI-spec fill resets the interview so a new concept never inherits the previous voice); built-in voice vs cloned sample; publish on/off and whether publish prerequisites are met (publishes vs creates private with a soft warning); name conflict (409 → bounce to Step 0 to rename); resume draft vs "Start fresh"; per-step jump-back via stepper pips (real buttons, so a completed step is a tab stop and the current one carries `aria-current`) and review "Edit" buttons.
- **External calls / dependencies:** `getMe()` (account.js); `POST /api/agents/suggest-spec` (AI spec generator); `POST /api/persona/interview` (interview extraction); `GET /api/avatars` (library tab); `saveRemoteGlbToAccount` (account.js → presign + R2 upload + commit); `POST /api/agents`; `POST /api/agents/:id/voice/clone` (via `VoiceSetup.bindTo`) + `PATCH /api/user/provider-keys` (BYOK key); `POST /api/marketplace/agents/:id/publish`; `POST /api/agents/:id/persona/save`.
- **Success state:** A real agent with its own wallet/on-chain identity, a guaranteed 3D body, optionally listed on the marketplace; success card links to go-live/fund/view/edit/embed.
- **Empty / error states:** Library tab has loading / error (with "Try again") / empty (no character models) states; per-step inline validation via `#foot-msg`; 409 name conflict bounces back; guest generate 429 → "That's the guest generation limit. Sign in to keep going, or fill the form in by hand."; publish, voice-bind, and persona-save failures are non-fatal (soft warning, agent still created); submit failure re-enables the form with an error message; lost upload on draft resume → re-attach prompt.
@@ -116731,17 +121506,17 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
### Prompt → Avatar — `/create/prompt` (create-prompt)
- **Source:** `pages/create-prompt.html` + `src/create-prompt.js` (imports `src/shared/log.js`)
- **Entry point:** The "Prompt" card on `/create` (`/create` redirects signed-out users to `/login?next=/create/prompt`). Also reachable directly.
-- **Prerequisites / gates:** **Auth required** — the submit endpoint returns 401 → page redirects to `/login?next=/create/prompt` (also enforced upstream by `/create`). No wallet/$THREE gate.
+- **Prerequisites / gates:** **Auth required**: the submit endpoint returns 401 → page redirects to `/login` with `next=/create/prompt?prompt=<text>`, so the typed prompt survives the round trip through the `?prompt=` deep link (also enforced upstream by `/create`). No wallet/$THREE gate.
- **Steps (N):**
1. Land on the **compose** step; type a text prompt (3 to 600 chars; live counter), or dictate it: a mic button (`src/voice/prompt-dictation.js`, browser SpeechRecognition with an NVIDIA Riva fallback) mounts next to the textarea only when the browser can dictate. (optional) Click an example chip to fill the prompt; around July 4 (July 1-5, viewer local time) seasonal preset chips are injected via `src/shared/festive-presets.js`. A `?prompt=<text>` deep-link prefills the composer (no auto-submit).
- 2. Click "Generate" (or Cmd/Ctrl+Enter). `start()` → switches to the **building** step, starts the elapsed clock, sets progress to 8%. Escape (or the cancel button) aborts the build back to compose.
+ 2. Click "Generate" (or Cmd/Ctrl+Enter). `start()` → switches to the **building** step, starts the elapsed clock, sets progress to 8%. Escape (or the cancel button) aborts the build back to compose; Cancel is gated on the building step rather than on an in-flight request, so it still works after a failure. Every build claims a run token, and a cancelled or superseded run can no longer write to the screen (starting a second build no longer lets the abandoned poll drop the old avatar onto the done screen).
3. POST `/api/avatars/reconstruct` `{ name (derived from prompt), prompt, visibility: 'private' }`. Server renders a reference image (Flux) then runs reconstruct→auto-rig. Returns `{ jobId }`.
4. `pollUntilDone(jobId)` polls `GET /api/avatars/regenerate-status?jobId=...` every 3s (8-min timeout), advancing the progress bar by phase (queued→running→rigging).
5. On `{ status: 'done', resultAvatarId }`: `renderDone` fetches `GET /api/avatars/:id`, sets the `model-viewer` src (using the owner's presigned URL for private avatars), and tags it (Animation-ready / static, Private). Shows the **done** step with "Open in editor" (`/avatars/<id>/edit`) and "Make another"; dispatches `tws:feature-done` for the cross-feature discovery layer.
-- **Decision points / branches:** compose vs building vs done; typed vs dictated prompt; success vs failure (`mapSubmitError`/`friendlyJobError` map codes to human messages: rate-limited, unconfigured→suggest selfie, no-face, NSFW, timeout, OOM); cancel mid-build; 401 mid-flow → login redirect; "Make another" resets to compose.
+- **Decision points / branches:** compose vs building vs done; typed vs dictated prompt; success vs failure (`submitError`/`jobError` build an `ApiError` carrying human copy plus whether retrying can help: rate-limited quotes the server's `retry_after`, unconfigured and needs-BYOK suggest the selfie scanner without a retry, a full library (402 `plan_limit`, or a job that lost the race mid-build) links to `/dashboard` and `/pricing` without a retry, no-face, NSFW, timeout, OOM); cancel mid-build; 401 mid-flow → login redirect carrying the prompt; "Make another" resets to compose (bound once at module scope).
- **External calls / dependencies:** `POST /api/avatars/reconstruct`; `GET /api/avatars/regenerate-status`; `GET /api/avatars/:id`. Backend uses a text-to-image (Flux) + reconstruct/rig pipeline.
- **Success state:** A private, riggable 3D avatar previewed in-page with an "Open in editor" path.
-- **Empty / error states:** Compose: inline `#compose-error` if prompt < 3 chars. Building: `#build-error` with a "Back" button to return to compose; friendly mapping of provider errors; 8-min timeout message suggesting the dashboard. Generate button disabled until prompt ≥ 3 chars.
+- **Empty / error states:** Compose: inline `#compose-error` if prompt < 3 chars. Building: the screen stops claiming work is in flight (orb frozen, bar muted, phase line and Cancel hidden) and `#build-error` offers "Edit prompt" always, "Try again" only for a retryable failure (held as a "Try again in Ns" countdown while a Retry-After runs), and the dashboard / pricing links for a full library; a fetch-level failure says the engine could not be reached rather than "something went wrong"; 8-min timeout message suggesting the dashboard. Generate button disabled until prompt ≥ 3 chars.
- **Step count:** 3 required (compose → generate/build → done) + 1 optional (example chip).
---
@@ -116753,17 +121528,17 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
- **Steps (N):**
1. Land; inline boot fetches `/api/config` to pick platform vs BYOK mode and dynamically imports the capture UI + pipeline.
2. (optional, BYOK only) **api-key step:** pick provider (Meshy/Tripo), paste key (>8 chars), submit → `storeByokKey` → advance to capture.
- 3. **capture step:** capture or upload a **frontal** photo (required) via camera overlay (`selfie-capture.js`, with face-oval guidance) or file upload; optionally add **left/right** angle photos (fidelity boost). The live shutter gate and the still-photo check now judge frames through one shared threshold module (`src/selfie-gates.js`), and a blocked shutter surfaces the grader's retake reason in the capture UI (poor lighting, off-angle) instead of silently refusing to fire. Each added frontal photo is also quality-assessed on-device (`src/selfie-refine.js` `assessPhoto`), surfacing `#quality-notice` warnings (blurry / drawing / no face) before the user waits out a full build. The page also cross-links `/image-to-3d` for object (non-face) photos.
+ 3. **capture step:** capture or upload a **frontal** photo (required) via camera overlay (`selfie-capture.js`, with face-oval guidance) or file upload; optionally add **left/right** angle photos (fidelity boost). The live shutter gate and the still-photo check now judge frames through one shared threshold module (`src/selfie-gates.js`), and a blocked shutter surfaces the grader's retake reason in the capture UI (poor lighting, off-angle) instead of silently refusing to fire. Lighting is graded before blur (a dark frame trips both, and light is the root cause), a blown-out face is caught by the share of clipped pixels as well as mean luma (the badge reads "Blown out" and the hint says to move out of direct light), and the live blur floor is a measured 12 (Laplacian stddev on the 64px crop; the old 3.5 never fired on a real photograph). Photos shared from the Android share sheet arrive with `?shared=1` and fill frontal, then left and right, in order. Each added frontal photo is also quality-assessed on-device (`src/selfie-refine.js` `assessPhoto`), surfacing `#quality-notice` warnings (blurry / drawing / no face) before the user waits out a full build. The page also cross-links `/image-to-3d` for object (non-face) photos.
4. Click "Build my avatar" (`#submit-btn`) → dispatches `selfie:submit`. Pipeline downscales photos (≤1024px JPEG), runs a local MediaPipe face check, then dispatches `selfie:preview` (shows the user's own photo on a placeholder).
5. POST `/api/avatars/reconstruct` `{ name, photos[], visibility: 'private', params:{bodyType,style}, optional provider_key/provider_name }` → `{ jobId }`. Stashes `selfie:pendingJobId` in sessionStorage (for resume across login). Dispatches `selfie:building` → shows the **building** step (and requests Notification permission).
- 6. `pollUntilDone` polls `GET /api/avatars/regenerate-status?jobId=...` (1.5s first, then 3s w/ backoff, 8–10 min timeout), dispatching `selfie:progress` labels (mesh → geometry → rigging → finishing).
+ 6. `pollUntilDone` polls `GET /api/avatars/regenerate-status?jobId=...` (1.5s first, then 3s w/ backoff, 8 to 10 min timeout), dispatching `selfie:progress` labels (mesh → geometry → rigging → finishing). A `done` job with no `resultAvatarId` (the server's materialize stage lost a transient race) is polled up to three more times before it is treated as final, and a failure whose `errorKind` is `input` is relayed in the server's own words when no local mapping matches, so "your library is full" is never rewritten as "try a clearer photo".
7. On done: `selfie:done` fires; the page fetches `GET /api/avatars/:id`, renders the model in the **done** viewer, prefills the name. If the tab is hidden, flashes the title + fires an OS notification.
8. **done step** actions: "Open my avatar" (`#done-save-btn`, optional PATCH name → `/avatars/<id>`), "List on marketplace" (`#done-list-btn`, PATCH name + visibility public → `/marketplace/avatars/<id>`), "Customize in editor" (`#done-editor-btn` → `/avatars/<id>/edit`), or "Not quite right? Try again" (`#done-regen-btn`, reset to capture).
- **Abandoned jobs finish server-side (platform mode):** the browser poll is no longer the only engine. `api/cron/reconstruct-sweep.js` (every 5 min) picks up open reconstruct jobs quiet for over 3 minutes and runs the same finalize stages, so closing the tab mid-build still lands the avatar in the user's library (30-day rescue window). BYOK jobs stay browser-driven (the server has no user key).
- **Decision points / branches:** platform vs BYOK mode (key step or not); camera vs upload; frontal-only vs +side angles; photo quality warnings vs proceed; mid-flow 401 → login + job resume; done vs build-error (per-slot error highlighting, retry); resume-pending-job on reload.
-- **External calls / dependencies:** `GET /api/config`; `POST /api/avatars/reconstruct`; `GET /api/avatars/regenerate-status`; `GET /api/avatars/:id`; `PATCH /api/avatars/:id` (save/list). MediaPipe (client face detect); camera `getUserMedia`; optional Meshy/Tripo BYOK providers.
+- **External calls / dependencies:** `GET /api/config`; `POST /api/avatars/reconstruct`; `GET /api/avatars/regenerate-status`; `GET /api/avatars/:id`; `PATCH /api/avatars/:id` (save/list). MediaPipe tasks-vision for the client face check (bundled from the npm dependency; `src/shared/mediapipe-assets.js` serves the WASM runtime and the face landmarker model from the vendored copy under `public/vendor/mediapipe` first and a CDN second, and fetches the segmenter and face-detector models from Google's bucket under a deadline, so capture survives a blocked CDN); camera `getUserMedia`; optional Meshy/Tripo BYOK providers.
- **Success state:** A private, rigged 3D avatar (reconstructed from the selfie), previewed in-page with save/list/edit paths.
-- **Empty / error states:** `selfie:needs-byok` → key-entry form ("No API key found"); local face-check failure highlights the offending slot with guidance; `selfie:build-error` recolors the building step, shows tips, and a "Try again" → capture; rate-limit cooldown with a live countdown; viewer load failure marks the preview `.failed`; 8-min timeout message.
+- **Empty / error states:** `selfie:needs-byok` → key-entry form ("No API key found"); local face-check failure highlights the offending slot with guidance; `selfie:build-error` recolors the building step, shows tips, and a "Try again" → capture; rate-limit cooldown with a live countdown; the error banner scrolls into view on first appearance so a tap on the sticky submit bar from higher up the page never fails silently; viewer load failure marks the preview `.failed`; 8-min timeout message.
- **Step count:** 4 required (capture frontal → build → poll → done) + ~4 optional (BYOK key step, side angles, upload-vs-camera, save/list/edit/make-another).
---
@@ -116771,33 +121546,33 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
### Talking Avatar Video: `/create/video`
- **Source:** `pages/create/video.html` + `src/create-video.js` (imports `src/account.js` for `apiFetch`; the page also loads `src/wallet-auth.js` inline for the sign-in button)
- **Entry point:** The "Talking avatar video" card on `/create` (`card-video-avatar`), which is both feature-flagged and auth-gated there. Also reachable from the Video capability tile on `/create-review` and directly by URL.
-- **Prerequisites / gates:** **Auth required.** `boot()` fetches `/api/auth/me` first and `location.replace('/login?next=/create/video')` on a non-OK response or a missing user, before anything renders. **Feature-flagged upstream:** `/create` greys the card out when `/api/config` reports `videoAvatar` off. **Quota:** the generate endpoint returns `402 free_trial_used` after the one free video. No wallet/$THREE gate.
+- **Prerequisites / gates:** **Auth required.** `boot()` fetches `/api/auth/me` first and `location.replace('/login?next=/create/video')` on a non-OK response or a missing user, before anything renders. **Feature-flagged upstream:** `/create` greys the card out when `/api/config` reports `videoAvatar` off. **Quota:** the generate endpoint returns `402 free_trial_used` after the one free video. **Renderer probe:** `GET /api/avatar/video-generate` answers `{ available, reason, free_generations }`; when the GPU worker is unconfigured the page shows a "Video rendering is offline" banner (pointing at `/avatar-studio` and `/create/prompt`) and keeps Generate disabled with the hint "Generation is paused while the renderer is offline.", and a 503 from the real POST flips the same state. No wallet/$THREE gate.
- **Steps (N):**
- 1. Land; `loadAvatars()` fetches `GET /api/avatars` and fills the avatar strip, auto-selecting the first one. With no owned avatars it falls back to a single "Default" thumbnail backed by `/avatars/default.glb`, so the page is never empty.
+ 1. Land; `loadAvatars()` fetches `GET /api/avatars` and fills the avatar strip, auto-selecting the first one. With no owned avatars the strip shows "No avatars yet. Make one and it shows up here, ready to speak." with a "Create an avatar" link, and a failed list shows "We could not load your avatars" with Retry (a failure is never rendered as an empty library); in both cases the stage shows `/avatars/default.glb` as decoration only, never as a generation source. The viewer starts with no `src`, so the login redirect cannot abort a model download mid-flight.
2. Pick an avatar from the strip (click, or Enter/Space; each thumb is a real `role="button"` with an aria-label). Private avatars come back from the list endpoint with no CDN URL, so `selectAvatar` lazily resolves a short-lived signed URL from `GET /api/avatars/:id` and guards against the user switching avatars mid-await. The pick renders in the `model-viewer` stage.
- 3. Add audio: drag-drop onto `#audio-drop` or pick a file. A non-audio drop is rejected with a toast. The chosen filename shows with a clear button. "Generate" stays disabled until both an avatar and an audio file are present.
+ 3. Add audio: drag-drop onto `#audio-drop` or pick a file. A non-audio drop is rejected with a toast. The chosen filename shows with its duration and size, an inline `<audio>` preview and a clear button; drops are accepted by MIME type or by extension. "Generate" stays disabled until both an avatar and an audio file are present, and the `#generate-hint` line under it always says what is still missing ("Pick an avatar to generate.", "Add an audio clip to generate.") or, once ready, roughly how many 3.72 s clips the audio will render into.
4. (optional) Type a direction prompt in `#prompt-input` to steer the render.
5. Click "Generate". `uploadAudio` requests `POST /api/avatar/presign-audio` (declaring `bytes`, capped at 64 MB) and PUTs the file to R2. A failed presign is reported as an error: there is no data-URI fallback, since `video-generate` only accepts an https three.ws-hosted `audio_url`.
- 6. `POST /api/avatar/video-generate` `{ image_url, audio_url, avatar_id, prompt }` returns `{ job_id }`.
- 7. `pollJob` polls `GET /api/avatar/video-status?job_id=…` every 5 s with a 20-minute deadline. The status endpoint reports `progress` plus the worker's planned `segments` count and measured `audio_seconds`, so the label names the work ("Rendering N clips… X%", one 3.72 s clip per segment) instead of a bare percent. Transient non-2xx and network errors are swallowed and retried until the deadline.
+ 6. `POST /api/avatar/video-generate` `{ audio_url, avatar_id, prompt }` returns `{ job_id }`. The server resolves `avatar_id` to a real reference image (the stored thumbnail, else a cached portrait render through the `/api/avatar/render` pipeline), so the browser never sends an `image_url`; it used to send the GLB, which the worker wrote into its reference image and failed on minutes later.
+ 7. `pollJob` polls `GET /api/avatar/video-status?job_id=…` every 5 s with a 20-minute deadline. The status endpoint reports `progress` plus the worker's planned `segments` count and measured `audio_seconds`, so the label names the work ("Rendering N clips… X%", one 3.72 s clip per segment) instead of a bare percent. Transient non-2xx and network errors are retried, but six in a row (30 s) stop the poll with "Lost contact with the render job", and a `failed` job relays the worker's own error text.
8. On `status: 'done'`: the returned `video_url` loads into the result `<video>` with a Download link and a "Make another" button that resets to idle.
-- **Decision points / branches:** signed-in vs redirect to login; owned avatars vs the default-avatar fallback; public (CDN URL) vs private (signed-URL resolve) avatar; presign success vs presign failure (413 too-large / 429 rate-limit / generic, each with its own message; no data-URI fallback exists); prompt vs no prompt; done vs failed vs 20-minute timeout; `402 free_trial_used` retargets the retry button to "Upgrade plan" pointing at `/dashboard`.
-- **External calls / dependencies:** `GET /api/auth/me`; `GET /api/avatars`; `GET /api/avatars/:id` (signed GLB URL); `POST /api/avatar/presign-audio` + R2 PUT; `POST /api/avatar/video-generate`; `GET /api/avatar/video-status`. Rendering runs on the talking-head worker, not in the browser.
+- **Decision points / branches:** signed-in vs redirect to login; renderer available vs offline (banner, Generate disabled); owned avatars vs the empty-strip note vs a failed list with Retry; public (CDN URL) vs private (signed-URL resolve) avatar; presign success vs presign failure (413 too-large / 429 rate-limit / generic, each with its own message; no data-URI fallback exists); prompt vs no prompt; done vs failed vs 20-minute timeout; `402 free_trial_used` retargets the retry button to "Upgrade plan" pointing at `/dashboard`.
+- **External calls / dependencies:** `GET /api/auth/me`; `GET /api/avatar/video-generate` (availability probe); `GET /api/avatars`; `GET /api/avatars/:id` (signed GLB URL); `POST /api/avatar/presign-audio` + R2 PUT; `POST /api/avatar/video-generate`; `GET /api/avatar/video-status`. Rendering runs on the talking-head worker, not in the browser; both worker calls go through the shared upstream breaker (a submit is never retried, a status read is).
- **Success state:** A downloadable lip-synced talking-head clip of the user's own avatar, playable in-page, with a one-click path to generate another.
-- **Empty / error states:** No avatars falls back to the default thumbnail rather than an empty strip. An avatar whose model cannot be resolved toasts "Could not load this avatar's 3D model. Pick another one." and leaves Generate disabled. Audio upload failure, job-start failure, worker failure, and the 20-minute timeout each render in `#error-area` with a retry that returns to idle. Free-trial exhaustion swaps retry for an upgrade link.
+- **Empty / error states:** No avatars shows the create-one note; a failed avatar list shows a retryable error; the offline banner covers an unconfigured renderer. An avatar whose model cannot be resolved toasts "Could not load this avatar's 3D model. Pick another one." and leaves Generate disabled. Audio upload failure, job-start failure, worker failure, and the 20-minute timeout each render in `#error-area` with a retry that returns to idle. Free-trial exhaustion swaps retry for an upgrade link.
- **Step count:** 4 required (pick avatar → add audio → generate → poll to done) + ~2 optional (direction prompt, download / make another).
---
-### Agent Editor: `/agent/<id>/edit` (and the retired `/agent/new`)
-- **Source:** `pages/agent-edit.html` + `src/agent-edit.js` (vercel route `/agent/<id>/edit` → `/agent-edit.html`; imports `src/avatar-creator.js`, `src/account.js`, `src/api.js`, `src/avatar-gallery-picker.js`, `src/shared/agent-wallet-chip.js`, `src/shared/glb-magic.js`)
-- **Entry point:** "Edit" buttons on agent profiles and the create-agent success panel. **`/agent/new` no longer serves this editor:** the bare route 301s to `/create-agent`, and `/agent/new?avatar_id=` / `?avatar_glb=` rewrites to `create-agent.html`, where `applyAvatarHandoff()` pre-seeds the wizard's model step (marketplace "Start an agent with this avatar" now lands in the wizard).
+### Agent Editor: `/agents/<id>/edit` (and the retired `/agent/new`)
+- **Source:** `pages/agent-edit.html` + `src/agent-edit.js` (vercel routes the canonical `/agents/<id>/edit` and the legacy `/agent/<id>/edit` both → `/agent-edit.html`, and the module accepts either path segment; imports `src/avatar-creator.js`, `src/account.js`, `src/api.js`, `src/avatar-gallery-picker.js`, `src/shared/agent-wallet-chip.js`, `src/shared/glb-magic.js`)
+- **Entry point:** "Edit" buttons on agent profiles and the create-agent success panel. **`/agent/new` no longer serves this editor:** the bare route 301s to `/create-agent`, and `/agent/new?avatar_id=` / `?avatar_glb=` rewrites to `create-agent.html`, where `applyAvatarHandoff()` pre-seeds the wizard's model step (marketplace "Start an agent with this avatar" now lands in the wizard). Autopilot receipts link here as `/agents/<id>/edit?tab=knowledge#mem-<memoryId>`: the cited memory is highlighted and scrolled into view once the list renders, and the `?tab=` section scroll stands down for it.
- **Prerequisites / gates:** **Auth required.** Loading an agent you don't own (or with no session) hits a 401, which stashes `login_redirect` and redirects to `/login`. No $THREE gate.
- **Steps (N):**
- 1. Navigate to `/agent/<id>/edit`; `loadAgent()` fetches `GET /api/agents/:id` and the full editor renders (`render()`): identity (name/description), 3D body (starter/library picker/upload via `avatar-gallery-picker.js` + `AvatarCreator`), skills, animations, **gesture slots** (per-agent bindings for the fixed gesture vocabulary, saved via `#anim-slots-save`, previewable on `/gestures`), voice, wallet chip, and the embed/manifest panels.
+ 1. Navigate to `/agents/<id>/edit`; `loadAgent()` fetches `GET /api/agents/:id` and the full editor renders (`render()`): identity (name/description), 3D body (starter/library picker/upload via `avatar-gallery-picker.js` + `AvatarCreator`), skills, animations, **gesture slots** (per-agent bindings for the fixed gesture vocabulary, saved via `#anim-slots-save`, previewable on `/gestures`), voice, wallet chip, and the embed/manifest panels. The wallet panel reads balances from `GET /api/portfolio/summary` (`{ usd, native, tokens }` per wallet), sends through `POST /api/portfolio/send` with `asset: 'native'` or the USDC mint and the typed decimal amount (echoing the returned `tx_hash`), and the Fund modal's deposit QR tries qrserver then quickchart before hiding the image behind the copyable address. The Social tab hides Connect X with a stated reason when X OAuth is not configured on the deployment (`?x=unconfigured` after a bounced connect). Embed and manifest panels emit the canonical `/agents/<id>` URLs.
2. Edit any field → changes persist through the same verified endpoints (PUT `/api/agents/:id`, animations endpoint, etc.).
- **Decision points / branches:** existing agent (URL id) vs the retired new-draft path (bare `/agent/new` now redirects to the `/create-agent` wizard before this page ever loads); signed-out → login; gesture overrides set vs cleared.
-- **External calls / dependencies:** `GET /api/agents/:id`; `PUT /api/agents/:id`; `PUT /api/agents/:id/animations`; `GET /api/agents/:id/manifest`; avatar APIs via `saveRemoteGlbToAccount` / gallery picker.
+- **External calls / dependencies:** `GET /api/agents/:id`; `PUT /api/agents/:id`; `PUT /api/agents/:id/animations`; `GET /api/agents/:id/manifest`; `GET /api/portfolio/summary`; `POST /api/portfolio/send`; `GET /api/auth/x/connect?agent_id=` (redirect); avatar APIs via `saveRemoteGlbToAccount` / gallery picker.
- **Success state:** The agent loaded into the full editor for fine-grained configuration, with saves confirmed inline (e.g. "Saved N gesture overrides.").
- **Empty / error states:** `showError(...)` for load failures; 401 → login redirect with return.
- **Step count:** 1 required (navigate → editor); the editor itself is open-ended.
@@ -116854,7 +121629,7 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
### Voice Lab — `/voice`
- **Source:** `pages/voice.html` + `src/voice-lab.js`
- **Entry point:** Nav/feature links; used to mint a cloned voice that agents/avatars can speak with.
-- **Prerequisites / gates:** Microphone permission (`getUserMedia`). The clone endpoint is called with `credentials: 'include'` — auth/credit limits are enforced server-side (a failure surfaces as a "Clone failed" status). No wallet/$THREE gate. Cloned-voice library is stored in `localStorage` (`voicelab_voices_v1`).
+- **Prerequisites / gates:** Microphone permission (`getUserMedia`). The clone endpoint is called with `credentials: 'include'`; auth/credit limits are enforced server-side (a failure surfaces as a "Clone failed" status), and the route checks identity before configuration, so a signed-out caller gets a 401 rather than a reading of the server's ElevenLabs setup. No wallet/$THREE gate. Cloned-voice library is stored in `localStorage` (`voicelab_voices_v1`).
- **Steps (N):**
1. Land; a reading script is shown (cycle with "Next script"). Voice library + playground voice dropdown render from `localStorage`.
2. Click "Record" (`#btnRecord`) → `getUserMedia` (mono, 48kHz, with AGC/NS/EC), live waveform + level meter, max 60s (recommended 20–30s).
@@ -116862,11 +121637,11 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
4. (optional) "Re-record" (`#btnRerecord`) to discard and try again.
5. Enter a voice name (required) and click "Clone" (`#btnClone`) → POST `/api/tts/eleven-clone` (multipart audio + name).
6. On success: stores `{ voiceId, name, status }` in `localStorage`, shows the **done** state ("<name> cloned successfully"), re-renders the library + playground voice list.
- 7. (optional) "Try in playground" (`#btnTryPlayground`): pick a voice, type text, click "Speak" → POST `/api/tts/eleven` `{ voiceId, text }` to synthesize and play. "Play sample" on a library card does the same with a canned line. "Record another" loops back.
+ 7. (optional) "Try in playground" (`#btnTryPlayground`): pick a voice, type text, click "Speak" → POST `/api/tts/eleven` `{ voiceId, text }` to synthesize and play. "Play sample" on a library card does the same with a canned line. "Record another" loops back. A lane that goes down mid-session drops its voices from the picker (a lane-down error re-reads the catalog), an unavailable lane's pill stays legible with a greyed billing badge so it never reads as live, and Space toggles record/stop only when focus is not on a control.
- **Decision points / branches:** record vs re-record; clone success vs failure (mic denied, recording too short, network error, server HTTP error); playground speak vs library sample playback; delete voice from library.
- **External calls / dependencies:** `POST /api/tts/eleven-clone` (clone); `POST /api/tts/eleven` (TTS playback/sample). ElevenLabs via the server proxy. There is no free platform TTS lane: each clip is billed to the caller's own ElevenLabs key (BYOK, sent as `x-eleven-key` or saved via provider keys) or metered against the prepaid credit wallet, with an R2 cache absorbing repeats; the `x-tts-billing` response header reports which lane served the call, and the playground surfaces the per-clip cost. Browser `getUserMedia` / `MediaRecorder` / Web Audio.
- **Success state:** A cloned voice ID saved to the local library, immediately usable in the in-page TTS playground (and selectable elsewhere for agent speech).
-- **Empty / error states:** Library empty state ("No cloned voices yet"); status banner (`setStatus`) for mic-denied, recorder-init failure, too-short clip, network/HTTP clone errors, name-required; playground/sample buttons surface synth errors inline.
+- **Empty / error states:** Library empty state ("No cloned voices yet"); status banner (`setStatus`) for mic-denied, recorder-init failure, too-short clip, network/HTTP clone errors, name-required; playground/sample buttons surface synth errors inline, and an unknown `voiceId` comes back as a 400 `validation_error` naming the voice (ElevenLabs' 400/404 is the caller's fault, not a 502).
- **Step count:** 4 required (record → stop → name → clone) + ~3 optional (cycle script, re-record, playground speak/sample).
---
@@ -116875,13 +121650,13 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
- `/start`, `/create`, `/create-agent`, `/import/rpm`, `/features/scan`, `/voice` all resolve via explicit `vercel.json` `routes[]` rewrites to their `*.html` files.
- `/create/prompt` → `create-prompt.html`, `/create/selfie` → `create-selfie.html`.
- `/create-review` → `create-review.html`, `/create/next` → `create-next.html`, `/create/video` → `create/video.html`, `/create/studio` → `avatar-studio.html` (the studio surface itself is documented in cluster 04).
-- `/agent/new` → **301 to `/create-agent`** (or a rewrite to `create-agent.html` when the URL carries `?avatar_id=`/`?avatar_glb=`); the existing-agent editor lives at `/agent/<uuid>/edit` → `agent-edit.html`.
+- `/agent/new` → **301 to `/create-agent`** (or a rewrite to `create-agent.html` when the URL carries `?avatar_id=`/`?avatar_glb=`); the existing-agent editor lives at `/agents/<uuid>/edit` → `agent-edit.html` (canonical; the legacy `/agent/<uuid>/edit` still rewrites there, while the bare `/agent/<uuid>` 301s to `/agents/<uuid>`).
- `/scan` is a **route-level 301** to `/create/selfie` (`pages/scan.html` no longer exists; the 301 drops query params).
- `/features/scan` is a **static landing page** with no flow logic; its CTAs link straight to `/create/selfie`.
---
-<a id="sec-505"></a>
+<a id="sec-525"></a>
> **Source:** `docs/ux-flows/02-forge-text-to-3d.md` · [↑ table of contents](#table-of-contents)
@@ -116890,7 +121665,7 @@ Honest limits, stated plainly: this is a **custodial** wallet, so the platform c
This atlas entry traces the "Text/Image-to-3D (Forge)" cluster end-to-end from real source. Routes are resolved through `vercel.json` rewrites (not the default `pages/<route>.html` convention in every case).
Routing facts (from `vercel.json`):
-- `/forge` → `pages/forge.html` (loads `src/forge.js` + 19 sibling `forge-*` modules).
+- `/forge` → `pages/forge.html` (loads `src/forge.js` + 25 sibling `forge-*` modules).
- `/image-to-3d` → `pages/forge.html` (same app; lands with the photos tab preselected and its own document title; `?mode=image` on any forge URL does the same).
- `/forge-max` → `pages/forge.html` (same app; lands with the High tier pinned and "Forge Max" header copy; `?tier=draft|standard|high` presets the selector on any forge URL).
- `/forge/share/<id>` → `api/forge-share.js` (SSR page that bakes OG/Twitter/Farcaster preview meta for crawlers, then JS-redirects browsers to `/forge?share=<id>`, which opens the creation in the viewer).
@@ -116920,10 +121695,10 @@ Routing facts (from `vercel.json`):
- **Steps (core text→3D path):**
1. User lands on `/forge`; `forge.js` fetches the engine/tier catalog (`GET /api/forge?catalog=1`) and live backend health (`GET /api/forge?health=1`), then builds the tier buttons (Draft/Standard/High) and the per-mode engine selector. The empty stage (`#state-empty`) shows an idle community/sample model.
2. Mode tab defaults to **Describe it** (text). Tabs: *Describe it*, *From photos*, *From a sketch* (the sketch tab stays `hidden` until the catalog reports a live TripoSG sketch engine).
- 3. **(text)** User types a prompt in `#prompt` (max 1000 chars). Live: a character counter, a prompt **coach** grading the prompt (tip/warn/strong, from `forge-prompt-studio.js`), and example chips ("a low-poly red fox, sitting", etc.) with a "↻ More ideas" swap.
+ 3. **(text)** User types a prompt in `#prompt` (max 1000 chars). Live: a character counter, a prompt **coach** grading the prompt (tip/warn/strong, from `forge-prompt-studio.js`), and example chips with a "↻ More ideas" swap. The static chip labels in `forge.html` are written at the generator's 64-character cap ("a low-poly red fox sitting upright, matte fur, soft studio light", etc.) and carry no `data-i18n`; on every JS visit `forge-prompt-studio.js` swaps them for generated prompts (`generateForgeChipSet`) whose combined width never exceeds the labels they replace, so the flex-wrapped row cannot gain a line and shift the page.
4. (optional) User clicks **Surprise me** to fill a random vivid prompt, or **Enhance** (injected by `forge-enhance.js`) to rewrite their text via `POST /api/forge-enhance` into a sharper single-subject FLUX→TRELLIS prompt.
5. (optional) User picks a **Quality tier** (Draft / Standard / High). Selecting High while locked reveals the in-place lock panel + holder note linking to `/three`; a wallet-aware perk line / "Connect wallet" chip may appear under Generate.
- 6. (optional) User picks an **Engine**. Engines are filtered by mode (text/photo/sketch input). BYOK engines show a key glyph; choosing one reveals the `#byok-row` API-key input with a provider-specific hint. Health-degraded engines show an amber dot; down/unconfigured ones are disabled with the reason in the tooltip.
+ 6. (optional) User picks an **Engine**. Engines are filtered by mode (text/photo/sketch input). BYOK engines show a key glyph; choosing one reveals the `#byok-row` API-key input with a provider-specific hint. Health-degraded engines show an amber dot; down/unconfigured ones show a red dot, are disabled, and carry the reason in the tooltip; a legend under the picker decodes both dots and the FREE/key pills.
7. (optional) User sets the reference-image **aspect ratio** (1:1 / 4:3 / 3:4 / 16:9) — shown only when relevant to the mode/engine. A live **estimate** line (`#estimate`) shows the catalog's real cost/time for the current tier+engine.
8. User clicks **Generate** (or ⌘/Ctrl+Enter). `collectComposerCfg()` validates (text ≥ 3 chars). If High is locked and submitted via keyboard, the gate/upsell opens instead of firing.
9. `startJob()` `POST`s to `/api/forge` with `{ prompt, aspect_ratio, path, tier, backend }` plus headers (client id, BYOK key if any, $THREE tier pass if eligible/needed — minted/awaited before the request when `highTierNeedsPass()`). Stage switches to `#state-generating`.
@@ -116968,17 +121743,17 @@ Routing facts (from `vercel.json`):
- Generation engines: FLUX (image) → TRELLIS (mesh) free lane; BYOK Meshy / Tripo / Rodin / Stability / Replicate; Hunyuan3D / TripoSG (sketch). Hosted on NVIDIA NIM / providers; same pipeline exposed to agents over MCP at `/api/mcp-3d`.
- **Photoreal reference-image path (the realism lever):** the final mesh reads as real only if the reference image the reconstructor sees is a photoreal, single-subject, plain-seamless-background, evenly-lit photograph. Two pieces drive that:
- `POST /api/forge-enhance` (director): rewrites the raw prompt into one centered real-world subject with material + surface micro-detail + neutral studio-lighting cues. It classifies the subject (person / animal / vehicle / food / object) and returns a `subject`-aware `negative_prompt` targeting that class's failure modes (hands/faces for people, wheel-count/panel symmetry for vehicles, plastic-replica sheen for food). It prefers a Vertex Gemini rewrite (GCP credits) and falls through to the free-first LLM chain automatically, so it never hard-depends on Vertex. Response schema is unchanged apart from the additive `subject` field.
- - `api/_lib/forge-reference-image.js` → `generateReferenceImage(directedPrompt, { aspectRatio, negativePrompt?, seed, skipNim })`: generates the reconstruction reference image on the Vertex Gemini 2.5 Flash Image lane (`imageConfig.imageSize:"2K"`), tuned as a plain-background studio photo, with the director's negatives folded in as natural-language avoidance. Automatic fallthrough to the existing provider chain (`textToImage`: NIM FLUX free → Vertex Imagen → Replicate), returning `{ imageUrl, model, lane }` (generated base64 output is persisted through the shared `image-persist` lib). The same directed prompt + aspect + negatives within 24h reuses its cached reference set instead of re-spending a Vertex generation. When `negativePrompt` is omitted it derives subject-aware negatives from the prompt itself, so a caller gets them for free. `api/forge.js` imports it on the text→3D path (dynamic import with `textToImage` as the fallback).
+ - `api/_lib/forge-reference-image.js` → `generateReferenceImage(directedPrompt, { aspectRatio, negativePrompt?, seed, skipNim })`: generates the reconstruction reference image on the Vertex Gemini 2.5 Flash Image lane (`imageConfig.imageSize:"2K"`), tuned as a plain-background studio photo, with the director's negatives folded in as natural-language avoidance. Automatic fallthrough to the existing provider chain (`textToImage`: NIM FLUX free → Vertex Imagen → Replicate), returning `{ imageUrl, model, lane }` (generated base64 output is persisted through the shared `image-persist` lib). The same directed prompt + aspect + negatives within 24h reuses its cached reference set instead of re-spending a Vertex generation. When `negativePrompt` is omitted it derives subject-aware negatives from the prompt itself, so a caller gets them for free. `api/forge.js` imports it on the text→3D path (dynamic import with `textToImage` as the fallback). The whole reference step (the Vertex lane, its QA score and corrective retry, and the fallthrough ladder) runs under one shared budget, `TEXT_TO_IMAGE_BUDGET_MS` (default 60 s), so a stalled image provider can no longer hold a submit open for minutes before a job exists. Separately from the client-side Enhance button, `api/forge.js` runs its own art-director rewrite on every text prompt by default (send `director: false` to skip it; it fails soft to the raw prompt).
- 3rd-party viewer: model-viewer 4.0.0 (googleapis CDN).
- **Success state:** A textured **GLB** standing in the in-page `<model-viewer>` (orbit/AR), auto-saved to "Your creations", with a downloadable file and all post-processing/export/embed/share actions enabled. Optional converted formats (OBJ/STL/PLY/USDZ/FBX) and a community showcase entry.
- **Empty / error states:**
- **Empty/idle** (`#state-empty`): isometric wireframe art + "Enter a prompt to generate", with a live sample/community model in the viewer.
- - **Unconfigured** (`#state-unconfigured`): deployment missing `REPLICATE_API_TOKEN` — explains how to enable.
+ - **Unconfigured** (`#state-unconfigured`): only for the `unconfigured` error (no 3D engine reachable: none of `NVIDIA_API_KEY`, `HF_TOKEN`, or `REPLICATE_API_TOKEN` set); it names the env vars to set and offers no retry.
- **Generation failed** (`#state-error`): generic failure with "Try again", plus contextual recovery buttons: "Refine current model instead" (rate-limited fallback), "Generate anyway" (vision override).
- BYOK errors: `needs_key` / `invalid_key` reveal + focus the key field; `insufficient_credits` explains provider is out of credits.
- - `429`/limiter-unavailable: countdown + local-refine escape hatch.
+ - `429`/limiter-unavailable, and any other `503` (`generation_unavailable`: a worker still warming or a free lane that shed the request): the recoverable countdown state carrying the server's own message and `retry_after` (20 s when absent) + local-refine escape hatch.
- High gate `402 three_hold_required`: designed upsell (held vs required, Get $THREE, Pay-per-use).
- - Payment errors: `payment_invalid` / `payment_expired` re-offer Pay; `payment_already_used` clears the stale proof.
+ - Payment errors: `payment_invalid` / `payment_expired` re-offer Pay; `payment_already_used` clears the stale proof; a settle call that cannot be reached after the $THREE transfer already confirmed surfaces `settle_unreachable` with the transaction signature, so the payment is reconciled rather than sent twice.
- Upload errors: per-slot states (503 uploads unavailable, 429 rate-limited, too-large/empty/wrong-type, network).
- Viewer load failure: `#viewer-load-error` overlay → "use the download button to save the file directly".
- **Step count:** ~12 required (text path, entry → download) + ~16 optional (surprise/enhance, tier/engine/aspect choices, refine-tier, refine-local, iterate, stylize, restyle-materials, rig, optimize, game-ready, export, reel, embed, AR, share/cinema/compare/compose/segment/verdict/category).
@@ -117004,9 +121779,9 @@ Routing facts (from `vercel.json`):
### Describe it to 3D (prompt → rigged avatar) — `/create/prompt`
-- **Source:** `pages/create-prompt.html` + `src/create-prompt.js`. **Overlap note:** this is the **onboarding/avatar-creation** cluster, not Forge. It shares the same conceptual "type a prompt → 3D" pattern but uses an entirely **different backend** — the selfie/avatar reconstruction + auto-rig pipeline, not the Forge engine catalog. It explicitly cross-links to `/forge` for "making an object, prop, or scene piece instead of a character." Entry points include `/create`, `/create-agent`, dashboard avatars/agents pages, and the gallery.
+- **Source:** `pages/create-prompt.html` + `src/create-prompt.js`. The page has a real light theme (`:root[data-theme='light']`) with AA-contrast secondary copy in both themes. **Overlap note:** this is the **onboarding/avatar-creation** cluster, not Forge. It shares the same conceptual "type a prompt → 3D" pattern but uses an entirely **different backend**: the selfie/avatar reconstruction + auto-rig pipeline, not the Forge engine catalog. It explicitly cross-links to `/forge` for "making an object, prop, or scene piece instead of a character." Entry points include `/create`, `/create-agent`, dashboard avatars/agents pages, and the gallery.
- **Entry point:** From `/create` (and `create.js`), the create-agent flow, dashboard, and gallery "make one" CTAs.
-- **Prerequisites / gates:** **Sign-in required** ("Sign-in required" chip). A `401` on submit or poll redirects to `/login?next=/create/prompt`. No wallet / no $THREE gate. Avatars default to `private` visibility.
+- **Prerequisites / gates:** **Sign-in required** ("Sign-in required" chip). A `401` on submit or poll redirects to `/login?next=/create/prompt?prompt=<typed prompt>`, so the words already typed come back with the user. No wallet / no $THREE gate. Avatars default to `private` visibility.
- **Steps (3 stages):**
1. **Compose:** User types a single-subject character description in `#prompt` (max 600; counter; Generate disabled under 3 chars). Optional example chips fill the box. A `?prompt=` query param pre-fills the composer (remix/copy-prompt deep links; nothing auto-submits). Hint: "Single subject, full body works best." Cross-link offered to `/forge` for objects.
2. User clicks **Generate avatar** (or ⌘/Ctrl+Enter). `start()` POSTs `/api/avatars/reconstruct` `{ name (derived from prompt), prompt, visibility:'private' }`. UI switches to the **Building** stage (spinning orb).
@@ -117015,14 +121790,14 @@ Routing facts (from `vercel.json`):
- **Decision points / branches:** Signed-in vs not (login redirect); rigged vs static-mesh tag; open editor vs make another; (offered) divert to `/forge` for non-characters.
- **External calls / dependencies:** `POST /api/avatars/reconstruct`, `GET /api/avatars/regenerate-status?jobId=`, `GET /api/avatars/<id>`. Flux text→image + reconstruct + auto-rig backend (shared with the selfie pipeline). model-viewer CDN. Dispatches `tws:feature-done` for the site discovery layer.
- **Success state:** A **rigged GLB avatar** saved to the user's account, previewed, ready to open in the avatar editor.
-- **Empty / error states:** Compose inline error ("Add a few words…"). Build error box with friendly mappings: rate-limited (`txt2img_rate_limited`/429), unconfigured (`regen_unconfigured`/`txt2img_unconfigured` → suggests `/create/selfie`), provider billing, unreachable, render error, no-face-detected, NSFW-blocked, timeout, OOM; plus a "Back" recovery button. Poll timeout message points the user to their dashboard.
+- **Empty / error states:** Compose inline error ("Add a few words…"). Build error box with friendly mappings: rate-limited (`txt2img_rate_limited`/429), unconfigured (`regen_unconfigured`/`txt2img_unconfigured` → suggests `/create/selfie`), provider billing, unreachable, render error, no-face-detected, NSFW-blocked, timeout, OOM; plus a "Back" recovery button. Each failure carries a `retryable` flag that decides which recovery buttons render: a full avatar library (`402`/`plan_limit`, also detected when a job loses the race mid-build) drops "Try again" and links to `/dashboard` (delete one) and `/pricing` (upgrade); an unconfigured engine drops it too; a `429` quotes the server's `Retry-After` and holds the retry button for exactly that long. On failure the orb, progress bar and phase line freeze and Cancel goes away; the error box (`role="alert"`) is the only live control. Cancel stays live for the whole building step, and every run holds a monotonic token so a cancelled build can never paint its late result over a newer one. Poll timeout message points the user to their dashboard.
- **Step count:** 3 required (compose → generate → done) + 1 optional (pick an example chip) — excludes downstream editor actions.
---
### Tutorial · Text Prompt to 3D Model — `/tutorials/text-to-3d`
-- **Source:** `pages/tutorial.html` (shared template, renders any `/tutorials/<slug>`) + content `docs/tutorials/text-to-3d.md`. Slug resolved client-side, markdown fetched from `/docs/tutorials/text-to-3d.md`, rendered with marked.js + highlight.js. Metadata/preview model come from `/tutorials-manifest.js` (`window.TUTORIALS`). The template also loads `/live-steps.js` (runnable ```` ```live ```` blocks: real API calls rendered inline) and `/tutorial-figures.js` (resolves `figure:` directives in the markdown into captured media, live 3D viewers, and a keyboard-navigable lightbox).
+- **Source:** `pages/tutorial.html` (shared template, renders any `/tutorials/<slug>`) + content `docs/tutorials/text-to-3d.md`. Slug resolved client-side, markdown fetched from `/docs/tutorials/text-to-3d.md`, rendered with marked.js + highlight.js. Metadata/preview model come from `/tutorials-manifest.js` (`window.TUTORIALS`). The template also loads `/live-steps.js` (runnable ```` ```live ```` blocks: real API calls rendered inline) and `/tutorial-figures.js` (resolves `figure:` directives in the markdown into captured media, live 3D viewers, and a keyboard-navigable lightbox). Relative links in the markdown resolve against `docs/tutorials/<slug>.md`: sibling tutorials go to `/tutorials/<slug>`, other docs to `/docs/<name>` (with `#section` preserved), and repo-only docs (`docs/internal`, `docs/ops`, `docs/security`) or cited source files open on GitHub.
- **Entry point:** `/tutorials` index, `/docs`, in-Forge "/docs" hint, blog, search, and cross-links from the image-to-3d and prompts-for-3d tutorials.
- **Prerequisites / gates:** None — read-only content page. (The tutorial itself states: "no account, no wallet, no code.")
- **Steps (read-only content page):**
@@ -117063,7 +121838,7 @@ Routing facts (from `vercel.json`):
---
-<a id="sec-506"></a>
+<a id="sec-526"></a>
> **Source:** `docs/ux-flows/03-3d-editing-viewer.md` · [↑ table of contents](#table-of-contents)
@@ -117079,10 +121854,10 @@ Routing summary (from `vite.config.js`):
| `/compose` | `pages/compose.html` | `src/scene-compose.js` |
| `/pose` | `pages/pose.html` | `src/pose-studio.js` |
| `/validation` | `public/validation/index.html` | `src/validation-ui.js` + `src/validation-page.js` (+ `src/validator.js`) |
-| `/app` | `pages/app.html` | `src/app.js` → `src/viewer.js`, `src/editor/index.js`, `src/validator.js` |
+| `/app` | `pages/app-next.html` (the Next shell; `pages/app.html`, the classic shell, serves `/app-classic`, `/deploy`, `/showcase`) | `src/app.js` → `src/viewer.js`, `src/editor/index.js`, `src/validator.js`, plus `src/app-next-overlay.js` on the Next shell |
| `/hydrate` | `public/hydrate/index.html` | inline module (no `src/` file) |
| `/artifact` | `public/artifact/index.html` | inline module (no `src/` file) |
-| `/avatar-artifact` | `pages/avatar-artifact.html` | inline script (CDN three.js r128, fully procedural) |
+| `/avatar-artifact` | `pages/avatar-artifact.html` | `src/avatar-artifact.js` (bundled three.js; agent avatar, allowlisted GLB, or procedural portrait) |
---
@@ -117115,11 +121890,11 @@ Routing summary (from `vite.config.js`):
### Scene Composer — `/compose`
- **Source:** `pages/compose.html`, `src/scene-compose.js`, `src/shared/log.js`.
-- **Entry point:** `<script type="module" src="/src/scene-compose.js">` (compose.html:377). Module sets up a Three.js renderer/scene/PMREM environment, OrbitControls, a `TransformControls` gizmo, undo/redo stack, then on IIFE boot reads URL params (`?glb=` / `?avatar=`) and renders the initial hierarchy (scene-compose.js:107-120, 940-964, 1343).
+- **Entry point:** `<script type="module" src="/src/scene-compose.js">` (compose.html:445). Module sets up a Three.js renderer/scene/PMREM environment, OrbitControls, a `TransformControls` gizmo, undo/redo stack, then on IIFE boot reads URL params (`?glb=` / `?avatar=`) and renders the initial hierarchy (scene-compose.js:107-120, 940-964, 1343).
- **Prerequisites / gates:** None to compose/forge/export. Forge ownership is auth-free via a generated `forge_client_key` in localStorage sent as the `x-forge-client` header (scene-compose.js:88-94). **Saving an outfit** requires an avatar loaded from `/api/avatars/<id>` (a real avatar id), otherwise it falls back to "Use Export GLB" (scene-compose.js:1318-1320). No wallet / $THREE gate.
- **Steps (N):**
1. Arrive at `/compose`. If `?glb=<url>` present → load that GLB as an item (scene-compose.js:940-942). If `?avatar=<id-or-url>` present → resolve via `/api/avatars/<id>` (or direct URL) and load as the avatar (scene-compose.js:948-960). Else show the avatar prompt / canvas hint.
- 2. Choose a base avatar (optional): paste a URL and **Load** (`btn-load-url`, scene-compose.js:967-971); **Browse** opens a modal listing avatars from `/api/explore?type=avatar&limit=24` (scene-compose.js:980-999); or **Skip** to compose without an avatar (scene-compose.js:973).
+ 2. Choose a base avatar (optional): paste a URL and **Load** (`btn-load-url`, scene-compose.js:967-971); **Browse** opens a modal listing avatars from `/api/explore?source=avatar&only3d=1&limit=24`, with eight shimmering `.gsk` placeholder tiles while it loads (`openAvatarModal`, scene-compose.js:1171-1260); or **Skip** to compose without an avatar (scene-compose.js:973).
3. **Forge an item from text:** type a prompt, optionally pick an intent chip (accessory/item/scene/creature/vehicle — drives suggestion pills + `model_category`), press **Forge** (`startForge`, scene-compose.js:1071-1103). Live progress bar with staged labels; polls `/api/forge?job=<id>` every 3s until `done` (then adds the GLB to the scene) or `failed`/timeout (scene-compose.js:1105-1142).
4. (optional) Import a local GLB/glTF via drag-drop on the drop zone or the file input (`loadFile`, scene-compose.js:1240-1260).
5. Select an object by clicking it (or via the hierarchy list `#ol`). Inspector `#ins` shows transform + scale-lock chain.
@@ -117131,9 +121906,9 @@ Routing summary (from `vite.config.js`):
11. **Export GLB** → bundles all visible, non-bone-attached objects into one group and downloads `scene-compose.glb` (scene-compose.js:1284-1305).
12. **Save outfit** → requires a loaded avatar with bone-attached items; PATCHes `/api/avatars/<id>` with the `accessories` array (bone, glbUrl, name) (scene-compose.js:1310-1335).
- **Decision points / branches:** Boot branch on `?glb=` vs `?avatar=` vs neither (scene-compose.js:940-963). Forge synchronous `done` vs async `job_id` poll (scene-compose.js:1088-1097). Export (all objects, any state) vs Save outfit (avatar + bone-attached items only; requires a `/api/avatars/<id>`-sourced avatar id). Bone-attach UI only appears for non-avatar items when an avatar with bones exists.
-- **External calls / dependencies:** `POST /api/forge` + `GET /api/forge?job=<id>` (text-to-3D, with `x-forge-client` header); `GET /api/forge-gallery?limit=24` (your forged creations, scene-compose.js:1175); `GET /api/explore?type=avatar&limit=24` (avatar browse modal); `GET /api/avatars/<id>` (resolve avatar by id); `PATCH /api/avatars/<id>` (save outfit accessories). Imports: GLB/glTF (URL or local file). Exports: GLB (`GLTFExporter`, binary), PNG screenshot.
+- **External calls / dependencies:** `POST /api/forge` + `GET /api/forge?job=<id>` (text-to-3D, with `x-forge-client` header); `GET /api/forge-gallery?limit=24` plus `?scope=community&limit=24` (your forged creations and the community strip, rendered behind six `.gsk` skeleton tiles until they answer, scene-compose.js:1444-1472); `GET /api/explore?source=avatar&only3d=1&limit=24` (avatar browse modal); `GET /api/avatars/<id>` (resolve avatar by id); `PATCH /api/avatars/<id>` (save outfit accessories). Imports: GLB/glTF (URL or local file). Exports: GLB (`GLTFExporter`, binary), PNG screenshot.
- **Success state:** Forged/loaded items appear in scene + hierarchy with toasts ("Added: …", "Loaded: …", "Attached to <bone>"); export/save flash "Exported ✓" / "Outfit saved ✓" (`flashSave`, scene-compose.js:1337-1341).
-- **Empty / error states:** Empty hierarchy → "No objects — load an avatar or forge an item." (scene-compose.js:604). Forge errors → red banner via `showForgeError` (auto-hides 6s); timeout → "Generation timed out. Try again." Avatar browse empty → "No avatars found. Forge one first." Export with nothing → toast "Nothing to export". Save outfit with no avatar → "Load an avatar first"; no attached items → "Attach at least one item to a bone first"; non-API avatar → "Use Export GLB to save this scene".
+- **Empty / error states:** Empty hierarchy → "No objects" with the hint "load an avatar or forge an item." (scene-compose.js:734). Forge errors → red banner via `showForgeError` (auto-hides 6s); timeout → "Generation timed out. Try again." Avatar browse empty → "No public avatars are available yet." with a "Create one →" link to `/create`; browse fetch failure → "Could not load avatars: …" with a Retry button Export with nothing → toast "Nothing to export". Save outfit with no avatar → "Load an avatar first"; no attached items → "Attach at least one item to a bone first"; non-API avatar → "Use Export GLB to save this scene".
- **Step count:** ~5 required (arrive → forge or import → select → transform → export) + ~7 optional (load/browse/skip avatar, intent chips, bone attach, rename/visibility, camera presets, screenshot, save outfit).
---
@@ -117156,7 +121931,7 @@ Routing summary (from `vite.config.js`):
11. (optional) Import a pose JSON (`#pose-import-json`) → applies a single static pose (pose-studio.js:917-934).
12. Completion paths: **Export JSON** clip (`serializeClip`); **Export GLB** with embedded clip (`bakeAnimatedGlb`); **Record in Scene →** (bakes GLB, stashes in IndexedDB, navigates `/scene?handoff=1`); **Save** to account (Ctrl/Cmd+S → PoseLibrary dialog, POST/PATCH `/api/animations/clips`); **Export pose JSON** (single pose) / **PNG screenshot**; **Sell** a saved clip for USDC from the "My animations" drawer (pose-studio.js:1408-1491; pose-library.js). Export buttons disabled until ≥1 keyframe (`refreshExportEnabled`, 1206-1211).
- **Decision points / branches:** Mannequin vs loaded GLB (changes bone-pick strategy, model-tuning availability, IK availability, preset/AI-library availability, and whether the saved clip links an `avatar_id`). Save vs Update vs Save-as-copy (PATCH existing clip vs POST new, pose-library.js:218-262). Four independent completion paths: Save (auth-gated) / Export / Sell (USDC) / Scene handoff. Boot branch on `?avatar=` and chained `?anim=`.
-- **External calls / dependencies:** `GET /api/avatars/:id`; `GET /api/auth/me`; clip CRUD `POST/PATCH/DELETE/GET /api/animations/clips[/:id]` (mine + `include_public=true&visibility=public`); `POST /api/animations/thumbnail`; sell flow `POST /api/animations/presign` → R2 `PUT upload_url` → `POST /api/animations/sell` (USDC on Base or Solana); AI/preset clips `GET /animations/manifest.json`, `POST /api/forge-motion` + poll. Imports: pose JSON. Exports: pose JSON, clip JSON, animated GLB (`GLTFExporter` binary), PNG. Scene handoff: `putSceneHandoff({glb,name})` to IndexedDB, then navigate `/scene?handoff=1` (shared/scene-handoff.js). URL pose codec `#p=`/`?p=` (pose-share.js).
+- **External calls / dependencies:** `GET /api/avatars/:id`; `GET /api/auth/me`; clip CRUD `POST/PATCH/DELETE/GET /api/animations/clips[/:id]` (mine + `include_public=true&visibility=public`; a priced clip you do not own answers `paywalled` with no tracks rather than a 404, and a private one still 404s); `POST /api/animations/thumbnail` (admits a full-size poster PNG; an oversized one is a typed `413 too_large`); sell flow `POST /api/animations/presign` → R2 `PUT upload_url` → `POST /api/animations/sell` (USDC on Base or Solana); AI/preset clips `GET /animations/manifest.json`, `POST /api/forge-motion` + poll. Imports: pose JSON. Exports: pose JSON, clip JSON, animated GLB (`GLTFExporter` binary), PNG. Scene handoff: `putSceneHandoff({glb,name})` to IndexedDB, then navigate `/scene?handoff=1` (shared/scene-handoff.js). URL pose codec `#p=`/`?p=` (pose-share.js).
- **Success state:** HUD `#pose-status` confirmations ("Loaded …", "Keyframe added at Xs · N total", "Screenshot saved"); export buttons show busy → "Saved ✓"/"Opening ↗"; save → "Saved '…' to your account"; sell → "Listed '…' for N USDC".
- **Empty / error states:** Timeline `#tl-empty` "Pose the figure, then press K…" until a keyframe exists; mode-aware no-selection hint; bone search "No bones match"; library drawer "No animations yet" / "Sign in to see your animations"; AnimationLibrary "Load a rigged avatar"/"can't be retargeted"; boot idle "Ready. Click a body part to pose, or load an avatar." Errors (red HUD): avatar load failure, "no recognizable humanoid skeleton", import parse failure, "Add a keyframe first, then play", export "… failed"; library/API errors show inline `.pl-dialog-err` + Retry; `?avatar=` boot failure falls back to mannequin with explanation.
- **Step count:** ~6 required (arrive → select bone → FK pose → add keyframe → scrub/play → export) + ~7 optional (load/switch avatar, scene/model tuning, IK, preset pose, motion library/AI, import pose JSON, save/sell/scene-handoff/screenshot).
@@ -117165,34 +121940,34 @@ Routing summary (from `vite.config.js`):
### glTF Validator — `/validation`
- **Source:** `public/validation/index.html`, `src/validation-page.js`, `src/validation-ui.js`, `src/validator.js`, `src/gltf-inspect.js`, `src/components/validator-report.jsx`, `src/components/inspect-report.jsx`, `src/erc8004/validation-recorder.js`, `src/erc8004/agent-registry.js`.
-- **Entry point:** `public/validation/index.html` (module at lines 1040-1042) imports `ValidationDashboard` (validation-ui.js) and `ValidationPage` (validation-page.js); constructs the dashboard then the page (which references the dashboard for the on-chain hand-off). On construct, `ValidationPage` renders the Khronos sample chips, binds input events, and restores the active tab from the URL hash (validation-page.js:32-46).
+- **Entry point:** `public/validation/index.html` (module at line 1206) imports `ValidationDashboard` (validation-ui.js) and `ValidationPage` (validation-page.js); constructs the dashboard then the page (which references the dashboard for the on-chain hand-off). On construct, `ValidationPage` renders the Khronos sample chips, binds input events, and restores the active tab from the URL hash (validation-page.js:33-52). The three tabs are a roving-tabindex tablist: Arrow keys, Home and End move between them (`switchTab`, validation-page.js:53-70).
- **Prerequisites / gates:** None to validate/inspect — runs fully client-side in the browser. The **Records / "Pin & sign on-chain"** path requires an Ethereum wallet (`ensureWallet` via ethers / `window.ethereum`, validation-ui.js:12) to sign + submit an on-chain attestation; that is the only gated sub-flow. No $THREE gate.
- **Steps (N):**
- 1. Arrive at `/validation`. Three tabs: **Validate**, **Inspect**, **Records** (default `validate`, restored from `#validate|#inspect|#records`, validation-page.js:50-69).
- 2. Provide a model — three input sources sharing one pipeline: drag-drop a GLB on the drop zone, pick a file via the file input, paste a URL and click the URL button (Enter also works), or click a Khronos sample chip (Box/Duck/BoomBox/DamagedHelmet/Avocado from jsdelivr) (validation-page.js:78-118).
- 3. `_run(bytes, name)` fires both analyses in parallel (validation-page.js:145-189): the official Khronos validator (`Validator.validateBuffer` → `gltf-validator` `validateBytes`, validator.js:57-66) and the glTF-Transform inspector (`inspectModel` + `suggestOptimizations`).
- 4. **Validate tab** renders the report (`ValidatorReport`) — error/warning/info/hint counts bucketed by severity, aggregated repeated codes, generator/asset metadata (validator.js:106-189; validation-page.js:191-198).
- 5. **Inspect tab** renders glTF-Transform stats + optimization suggestions (`InspectReport`, validation-page.js:200-203).
+ 1. Arrive at `/validation`. Three tabs: **Validate**, **Inspect**, **Records** (default `validate`, restored from `#validate|#inspect|#records`).
+ 2. Provide a model: three input sources sharing one pipeline: drag-drop a GLB on the drop zone, pick a file via the file input, paste a URL and click the URL button (Enter also works), or click a Khronos sample chip (Box/Duck/BoomBox/DamagedHelmet/Avocado from jsdelivr) (`loadFile` / `loadUrl`, validation-page.js:145-176; each remembers `lastSource` so a failure card's Retry can rerun it).
+ 3. `_run(bytes, name)` fires both analyses in parallel (validation-page.js:177-243): the official Khronos validator (`Validator.validateBuffer` → `gltf-validator` `validateBytes`, validator.js:57-66) and the glTF-Transform inspector (`inspectModel` + `suggestOptimizations`).
+ 4. **Validate tab** renders the report (`ValidatorReport`): error/warning/info/hint counts bucketed by severity, aggregated repeated codes, generator/asset metadata (validator.js:106-189).
+ 5. **Inspect tab** renders glTF-Transform stats + optimization suggestions (`InspectReport`).
6. (optional) Download either report as JSON (`buildDownloadHref` data URI on each report panel).
7. (optional) View the validation report in a standalone lightbox tab (`Validator.showLightbox`, validator.js:198-212).
- 8. (optional, wallet) **Pin & sign on-chain**: `_handOffToDashboard` switches to the Records tab, opens the submit modal pre-filled with the in-memory report + its `hashReport` hash (no file re-pick), then `ValidationDashboard.submitReport` connects the wallet, pins to IPFS, and records the attestation (validation-page.js:221-242; validation-ui.js).
- 9. **Records tab** (independent): enter agent id + chain id (or arrive via `?agent=&chain=`), **Load** past validation records (`getLatestValidation`), or **Submit** a new report by dropping/picking a report JSON file (validation-ui.js:33-79).
+ 8. (optional, wallet) **Pin & sign on-chain**: `_handOffToDashboard` switches to the Records tab, opens the submit modal pre-filled with the in-memory report + its `hashReport` hash (no file re-pick), then `ValidationDashboard.submitReport` connects the wallet, pins to IPFS, and records the attestation (validation-page.js:283-300; validation-ui.js). The submit modal traps focus, closes on Escape or a scrim click, and returns focus to the control that opened it.
+ 9. **Records tab** (independent): enter agent id + chain id (or arrive via `?agent=&chain=`), **Load** past validation records (`getLatestValidation`; Enter in either input also loads, and IPFS report URIs resolve through the shared gateway list in `src/ipfs.js`), or **Submit** a new report by dropping/picking a report JSON file (validation-ui.js; the empty Records state carries its own "Submit a Validation" button).
- **Decision points / branches:** Input source (file / URL / sample) — all converge on `_run`. Validate vs Inspect (run together, two tabs). In-memory hand-off to Records vs manual report-file submission. Records load (`?agent=&chain=` auto-loads) vs manual entry. On-chain submit requires wallet; validation/inspection do not.
- **External calls / dependencies:** `fetch(url)` for URL/sample inputs (validation-page.js:136); `gltf-validator` `validateBytes` (in-browser); `src/gltf-inspect.js` (glTF-Transform, in-browser). On-chain: IPFS pin (`pinFile`), `recordValidation` (validationRequest + validationResponse) / `getLatestValidation` (validation-recorder.js), `ensureWallet`/ethers + `window.ethereum`. Inputs: GLB (and glTF + external resources resolved from the dropped asset map). The Validate tab can read the GLTFLoader-cached ArrayBuffer when invoked from the viewer (validator.js:26-34). Outputs: JSON report download, on-chain attestation.
-- **Success state:** Status line "Loaded <name> · <KB> · validated" (validation-page.js:184-187); rendered validate + inspect reports; **Pin & sign** button enabled once a report exists.
-- **Empty / error states:** Initial — three empty tab panels with sample chips inviting input. While running — "Validating…" / "Inspecting…" loading rows. File read error → "Could not read file: …"; fetch error → "Could not fetch <name>: HTTP <status>"; validator failure → "Validator failed: …" inline; inspector failure → "Inspector failed: …" inline (validation-page.js:122-217). On-chain hand-off with no report → toast "Run a validation first" (validation-page.js:222-224).
+- **Success state:** Status line "<name> · <size> · no issues found" (or "· N issues found", summed across errors, warnings, infos and hints; validation-page.js:226-241); rendered validate + inspect reports; **Pin & sign** button enabled once a report exists.
+- **Empty / error states:** Initial: three empty tab panels with sample chips inviting input. While running: "Validating…" / "Inspecting…" loading rows. Every failure renders a designed `.result-error` card (title, raw detail, what to try next, and a Retry that reruns the last input via `retryLast`; `errorCard`, validation-page.js:245-282): an unreadable file → "<name> could not be read" in both panels (`_failBoth`); a fetch error → "Could not fetch <name>" with CORS hints (the host must send `Access-Control-Allow-Origin`; download and drop the file instead); a validator failure → "<name> is not valid glTF"; an inspector failure → "Could not inspect <name>". The status line flips to its failed style and **Pin & sign** is disabled again. On-chain hand-off with no report → toast "Run a validation first" (validation-page.js:222-224).
- **Step count:** ~4 required (arrive → provide model → read Validate report → read Inspect report) + ~5 optional (download JSON, lightbox, pin & sign on-chain, browse records, submit report file).
---
### 3D Viewer / Editor (main app) — `/app`
-- **Source:** `pages/app.html`, `src/app.js`, `src/viewer.js`, `src/editor/index.js`, `src/validator.js`, `src/account.js`, `src/wallet.js`, `src/erc8004/*`, widget mounts under `src/widgets/*`, `src/components/screenshot-modal.js`, `src/next-layout.js`.
-- **Entry point:** `<script defer type="module" src="/src/app.js">` (app.html:57). `_bootApp()` constructs `new App(document.body, location)` and exposes `window.VIEWER.app` (app.js:2583-2596). The `App` constructor (app.js:162-401) parses hash + query into `this.options`, conditionally builds dropzone/avatar-creator/layout/nav, dispatches on route mode, then inits the agent system + widget bridge.
-- **Prerequisites / gates:** No hard gate blocks the viewer — the default CZ avatar (or `?model=`/`?agent=` target) loads for everyone, anonymous included. The "gate" is presentation-only: in `main` mode `_applyViewerMode` sets `data-authed` (`pending`/`false`) and CSS (`public/style.css`:6589-6606) overlays the `.auth-gate` card and hides the agent sidebar + dat.GUI editor for anonymous/pending users (app.js:614-629); `getMe()` (`GET /api/auth/me`) reconciles to the real state (app.js:681-695). A wallet button exists (`initWalletButton`, eager `eagerConnectWallet`) but connecting is never required. **No $THREE token gate.** "Save to account" and "Save edits" redirect to `/login` when signed out. The dat.GUI editor only exists once a model has loaded (built by the viewer on content load).
+- **Source:** `pages/app-next.html` (the Next shell served at `/app`), `pages/app.html` (the classic shell at `/app-classic`, `/deploy`, `/showcase`), `src/app.js`, `src/app-next-overlay.js`, `src/viewer.js`, `src/editor/index.js`, `src/validator.js`, `src/account.js`, `src/wallet.js`, `src/erc8004/*`, widget mounts under `src/widgets/*`, `src/components/screenshot-modal.js`, `src/next-layout.js`.
+- **Entry point:** `<script defer type="module" src="/src/app.js">` (app-next.html:59, followed by `/src/app-next-overlay.js`, which re-skins the same app with the Next chrome; app.html:57 loads the identical module for the classic shell). `_bootApp()` constructs `new App(document.body, location)` and exposes `window.VIEWER.app` (app.js:2583-2596). The `App` constructor (app.js:162-401) parses hash + query into `this.options`, conditionally builds dropzone/avatar-creator/layout/nav, dispatches on route mode, then inits the agent system + widget bridge.
+- **Prerequisites / gates:** No hard gate blocks the viewer: the default CZ avatar (or `?model=`/`?agent=` target) loads for everyone, anonymous included. The "gate" is presentation-only: in `main` mode `_applyViewerMode` sets `data-authed` (`pending`/`false`, app.js:647-662); on the classic shell that CSS (`public/style.css`) overlays the `.auth-gate` card ("Your agent lives here") and hides the agent sidebar + dat.GUI editor for anonymous/pending users, while the Next shell's overlay header shows a "Sign in to save" primary CTA that routes to `/login?next=/app` (`src/app-next-overlay.js`); `getMe()` (`GET /api/auth/me`) reconciles to the real state. A wallet button exists (`initWalletButton`, eager `eagerConnectWallet`) but connecting is never required. **No $THREE token gate.** "Save to account" and "Save edits" redirect to `/login` when signed out. The dat.GUI editor only exists once a model has loaded (built by the viewer on content load).
- **Steps (N):**
1. Arrive at `/app`. Constructor dispatches by mode; `_maybeResumeOrLoad(options)` runs for the default path (app.js:378, 408-458).
2. A model auto-loads: `?resume=<token>` restores a stashed editor session (optional), else `options.model || '/avatars/cz.glb'`; the default CZ avatar crossfades into a "taunt" landing clip (app.js:451-486).
- 3. Viewer renders via `view()` → WebGL check, `createViewer()`, `viewer.load(url, …)` with a progress callback, then attach avatar, notify editor, configure animations, set AR target, run validator (app.js:1783-1876).
+ 3. Viewer renders via `view()` → WebGL check, `createViewer()`, `viewer.load(url, …)` with a progress callback, then attach avatar, notify editor, configure animations, set AR target, run validator. Framing reads the rig's facing off its canonicalized shoulder, arm or leg bones (`src/viewer/facing.js`) so the camera seats in front of the face whether the rig was authored facing +Z or -Z; a model with no readable rig keeps the legacy +Z seat.
4. (optional) Load your own model — drag-drop a `.glb`/`.gltf` or folder anywhere on `.wrap` (`SimpleDropzone` → `load(files)`, app.js:1708-1776); or the `#file-input` picker; or `?model=<url>`/`#model=` (host-validated by `isSafeQueryModelUrl` for the deploy path, app.js:25-38); or `?agent=<uuid>`.
5. (optional) Open the editor controls (dat.GUI / Next-layout drawer): **Display** (background, autoRotate, wireframe, skeleton, grid, point size, transparent bg, screenshot, model info, mesh labels), **Lighting** (IBL/envMap, exposure, tone mapping, punctual lights), **Light Probes**, **Animation**, **Morph Targets**, **Cameras**, **Agent** follow mode, **Performance** stats (viewer.js `addGUI`).
6. (optional) Play animations: `_configureAnimations` fetches `/animations/manifest.json`, registers clips, honors `?anim=<name|uuid>`; Next-layout dock gives clip picker + play/pause + scrubber + loop. When an agent is loaded, its per-slot gesture overrides (`meta.edits.animations`, written by `PUT /api/agents/:id/animations` with `animationSlots`) are applied via `setAnimationMap`; the `/gestures` page documents the slot vocabulary.
@@ -117200,14 +121975,14 @@ Routing summary (from `vite.config.js`):
8. (optional) Edit materials / textures / scene via the `Editor` (`MaterialEditor`, `TextureInspector`, `SceneExplorer`, `MagicBrush`; rebuilt on each new model, editor/index.js:19-55).
9. (optional) Take a screenshot → `viewer.captureScreenshot()` → `ScreenshotModal.show(blob)` (app.js:825-837).
10. (optional) Export GLB → editor export folder → `exportEditedGLB(session)` → `downloadGLB(...)`; also a postMessage `exportGLB` bridge returns base64 GLB to a parent frame (editor/index.js:57-129; app.js:1498-1526).
- 11. (optional) Save edits / save model to account — editor `_saveEdits` (R2 presign+upload+PATCH) or header "Save to account" (`_triggerSaveToAccount` → if signed out, stash + `/login?next=/app?pending=1`; if signed in, `_performSave` saves the GLB, creates/links an agent, redirects to `/agent/<id>`, app.js:839-974).
+ 11. (optional) Save edits / save model to account: editor `_saveEdits` (R2 presign+upload+PATCH) or header "Save to account" (`_triggerSaveToAccount` → if signed out, stash + `/login?next=/app?pending=1`; if signed in, `_performSave` saves the GLB, creates/links an agent, redirects to `/agents/<id>`, app.js:839-1010).
12. (automatic) Validate — `validator.validate(...)` runs on every non-kiosk load; surfaces a `.validator-toggle` badge + lightbox (app.js:1872; validator.js).
13. (optional) Cross-links — "Make this a widget" → `/studio?model=<url>`; "Open in Composer" → `/compose?glb=<url>`; "Deploy on Solana" → guided on-chain deploy agent `/app?agent=67bf6e67-…` (app.js:759-810).
14. (optional) Chat with the agent — `_initNichAgent` mounts the NichAgent chat/voice UI + thought bubble (skipped in widget/kiosk/deploy/showcase, app.js:1633-1648).
- **Decision points / branches:** Route mode dispatch (app.js:288-394): kiosk/embedChat (chromeless), `/deploy` (RegisterUI wizard), `/showcase` (marketplace grid), on-chain `/a/<chain>/<id>` (anonymous-safe), legacy `#agent=` embed, chat embed `/a/<uuid>?embed=1`, `#widget=<id>` (slim shell vs full SPA, type-specific mounts), `?agent=<uuid>` authenticated agent-edit, else default `_maybeResumeOrLoad`; `?pending=1` replays a stashed post-login save. Anonymous vs signed-in (auth-gate overlay + save gating only). Classic vs Next layout (localStorage toggle). File-drop vs URL vs agent vs on-chain model source.
- **External calls / dependencies:** `GET /api/auth/me`, `POST /api/auth/logout`, `GET /api/avatars/<id>`, `GET /api/agents/<id>`, `GET /api/agents/me`, `POST /api/agents`, `PUT /api/agents/<id>`, `POST /api/avatars/thumbnail`, `POST /api/widgets/<id>/view`, `GET /animations/manifest.json` + `HEAD /animations/*.glb`; `saveRemoteGlbToAccount` (R2 presign/upload/commit); editor save (R2); on-chain dynamic imports (`erc8004/queries|abi|register-ui|showcase`) + Solana/ETH RPC; IPFS/Arweave URL resolution (`ipfs.js`). Imports: glTF/GLB (+ textures). Exports: binary GLB; PNG screenshot; AR uses USDZ (iOS) + GLB (Android). Validator: in-browser `gltf-validator`.
- **Success state:** `LOAD_END(success)` fades the poster, hides the status overlay, fires `three-ws:first-frame`, runs first-time onboarding (agent-edit), backfills a missing thumbnail (app.js:2033-2066). Model renders, orbitable; editor + agent sidebar available for signed-in users.
-- **Empty / error states:** No true empty void — the CZ default always loads. Anonymous main mode shows the `.auth-gate` card ("Your agent lives here — Sign in…") with sidebar/GUI hidden; the dropzone invites upload/generate. Loading: spinner/determinate progress bar (`_showViewerLoading`/`_updateLoadProgress`) + poster thumbnail for agent-edit. Errors: `_classifyLoadError` → human message + Retry (`_showViewerError`, app.js:2090-2181); "No .gltf or .glb asset found." on bad drop; `_showWebglUnavailable` reload card; `_showWidgetError`; on-chain `_showOnChainError`/`_updateOnChainCard`.
+- **Empty / error states:** No true empty void: the CZ default always loads. Anonymous main mode shows the `.auth-gate` card ("Your agent lives here", classic shell) or the "Sign in to save" CTA (Next shell) with sidebar/GUI hidden; the dropzone invites upload/generate. Loading: spinner/determinate progress bar (`_showViewerLoading`/`_updateLoadProgress`) + poster thumbnail for agent-edit. Errors: `_classifyLoadError` → human message + Retry (`_showViewerError`, app.js:2090-2181); a drop or pick with no model file shows the error card "No .gltf or .glb file in that drop. Pick a model file to view it." with a "Choose a file" action that reopens the picker (app.js:1840-1857); `_showWebglUnavailable` reload card; `_showWidgetError`; on-chain `_showOnChainError`/`_updateOnChainCard`.
- **Step count:** ~3 required (arrive → model auto-loads → view/orbit) + ~11 optional (load own model, GUI controls, animations, env/lights/camera, material/texture editing, screenshot, export GLB, save to account, validate review, cross-links, agent chat).
---
@@ -117233,43 +122008,45 @@ Routing summary (from `vite.config.js`):
### Artifact Viewer (Claude artifact bundle preview) — `/artifact`
- **Source:** `public/artifact/index.html` (self-contained inline module — no `src/` entry), backend `api/artifact`. NOTE: product purpose is "Embed your agent in Claude.ai" — it previews the standalone HTML artifact bundle that `/api/artifact` generates, not a glTF model.
-- **Entry point:** Inline `<script type="module">` at artifact/index.html:585. On load, `init()` reads `?agentId=` and, if present, auto-runs `generate()` (artifact/index.html:754-760).
+- **Entry point:** Inline `<script type="module">` at artifact/index.html:798. On load, `init()` reads `?agentId=`, `?theme=`, `?idle=` and `?bg=` back into the form, auto-runs `generate()` when an id is present, and `loadAgents()` fills a picker of real public agents from `GET /api/agents/public?sort=popular&limit=12&avatar=1` (`avatar=1` is load-bearing: an agent without a publicly readable GLB cannot become an artifact) (artifact/index.html:1139, 1228-1240).
- **Prerequisites / gates:** None on the page. Validity depends on a real agent id resolving server-side at `/api/artifact`. No auth/wallet/$THREE gate on the page itself (`fetch(..., { credentials: 'omit' })`).
- **Steps (N):**
1. Arrive at `/artifact` (optionally with `?agentId=`).
- 2. Enter an **Agent ID** (UUID or handle); optionally set theme (light), idle behavior, and a 6-hex background color (artifact/index.html:633-643).
- 3. Click **Generate** (or Enter) → `buildUrl()` assembles `/api/artifact?agent=…&theme=…&idle=…&bg=…`, updates the address bar, and fetches the artifact HTML (artifact/index.html:652-687).
- 4. On success: compute size, TTFP, and CSP-sandbox compliance (checks `frame-ancestors *` in the response CSP), show the stats panel (color-coded ok/warn/bad), and render the artifact via `iframe.srcdoc` (artifact/index.html:688-715).
+ 2. Enter an **Agent ID** (a UUID; `/api/artifact` rejects anything else with `400 invalid_request`, and the page adds the hint "Agent IDs are UUIDs. Copy one from an agent profile page, or pick an agent on the left.") or click one of the public agents in the picker; optionally set theme (light), idle behavior, and a 6-hex background color (artifact/index.html:649-700).
+ 3. Click **Generate** (or Enter) → `buildUrl()` assembles `/api/artifact?agent=…&theme=…&idle=…&bg=…`, mirrors the whole configuration into this page's own query string (`syncQueryString`, so a shared builder URL rebuilds the same artifact), marks the picked agent, and fetches the artifact HTML with `credentials: 'omit'` (artifact/index.html:908-1010).
+ 4. On success: compute size (graded against the ceiling a 6 MiB model produces once base64-inlined on top of the ~565 KB viewer, about 8.6 MB; amber past 70%, red past 100%), fetch time, render time (the iframe's first paint, timed out at 30s), and CSP-sandbox compliance (checks `frame-ancestors *` in the response CSP), show the stats panel (color-coded ok/warn/bad), and render the artifact via `iframe.srcdoc` (artifact/index.html:1030-1075).
5. (optional) **Reload** re-fetches; **Copy URL**; **Copy raw HTML** (with byte size); **Open** in a new tab.
- 6. (optional) The page fetches a reference CSP from `simonw/scrape-claude-artifacts` for the documented Claude.ai sandbox policy, with a documented fallback if unreachable (artifact/index.html:740-752).
- 7. Copy the generated **Claude snippet** ("Here's my agent for this conversation:\n<url>") to paste into Claude.ai (artifact/index.html:713-714).
-- **Decision points / branches:** `?agentId=` present → auto-generate vs manual entry. Fetch network error vs non-OK HTTP vs success. Size/TTFP/sandbox stats branch into ok/warn/bad styling. CSP reference fetch success vs fallback copy.
-- **External calls / dependencies:** `GET /api/artifact?agent=…` (the artifact bundle, `credentials: 'omit'`); `GET` raw CSP doc from raw.githubusercontent.com (reference only). Output: the artifact HTML rendered in an iframe; copy-to-clipboard URL/HTML/snippet. No 3D file import/export.
+ 6. (optional) The page shows the documented Claude.ai sandbox CSP from our own origin, `GET /claude-artifact-csp.txt` (the vendored bytes `tests/api/artifact.test.js` pins the endpoint against; `node scripts/refresh-claude-csp.mjs` refreshes it), with a fallback line pointing at `specs/CLAUDE_ARTIFACT.md` if that fetch fails (artifact/index.html:1213-1226).
+ 7. Copy the generated **Claude snippet** ("Here's my agent for this conversation:\n<url>") to paste into Claude.ai (artifact/index.html:1062).
+- **Decision points / branches:** `?agentId=` present → auto-generate vs manual entry vs picking from the public-agent list. Fetch network error vs non-OK HTTP vs success. Size/fetch/render/sandbox stats branch into ok/warn/bad styling. CSP reference fetch success vs fallback copy.
+- **External calls / dependencies:** `GET /api/artifact?agent=…` (the artifact bundle, `credentials: 'omit'`); `GET /api/agents/public?sort=popular&limit=12&avatar=1` (the picker); `GET /claude-artifact-csp.txt` (reference only, same origin). Output: the artifact HTML rendered in an iframe; copy-to-clipboard URL/HTML/snippet. No 3D file import/export.
- **Success state:** Stats panel populated (size/TTFP/sandbox), artifact rendered in `#previewFrame`, action buttons enabled, snippet shown.
-- **Empty / error states:** Initial — "Enter an agent ID and press Generate" overlay; snippet placeholder "Generate to see the snippet…". No id → "Enter an agent ID first." error overlay. Network error → "Network error: <msg>". Non-OK → server `error_description`/`error`/`HTTP <status>` shown in the overlay. CSP fetch failure → documented fallback text.
-- **Step count:** ~3 required (arrive → enter agent id → Generate) + ~4 optional (theme/idle/bg options, reload, copy URL/HTML/snippet, open in tab).
+- **Empty / error states:** Initial: "Enter an agent ID and press Generate" overlay; snippet placeholder "Generate to see the snippet…". No id → "Enter an agent ID first." error overlay. Network error → "Network error: <msg>". Non-OK → server `error_description`/`error`/`HTTP <status>` shown in the overlay, followed by an actionable hint keyed on the error code (`not_found`, `no_avatar` → generate one at `/create`, `too_large` → re-export under 6 MB, `invalid_request`, `rate_limited` → 600 requests a minute per IP, `upstream_error`). Picker fetch failure leaves the list with its own message. CSP fetch failure → documented fallback text.
+- **Step count:** ~3 required (arrive → enter or pick an agent id → Generate) + ~4 optional (theme/idle/bg options, reload, copy URL/HTML/snippet, open in tab).
---
-### Avatar Artifact (standalone procedural avatar) — `/avatar-artifact`
-- **Source:** `pages/avatar-artifact.html` (fully self-contained; CDN Three.js r128 via cdnjs with SRI; no `src/` module, no model load, no API). NOTE: this is a "standalone Three.js viewer for avatar artifacts — embeddable and shareable without any wrapper page" (page OG meta). The geometry is procedurally built in-page (cylinders/spheres/boxes forming a stylized portrait), not loaded from a GLB.
-- **Entry point:** Inline `<script>` at avatar-artifact.html:271. After the CDN three.js `<script>` loads, the script guards on `window.THREE` + WebGL, then builds scene/camera/renderer/lights/materials and the procedural avatar group, and starts the `animate()` RAF loop (avatar-artifact.html:271-303, 603).
-- **Prerequisites / gates:** None. No auth, wallet, $THREE gate, model load, or API. Renders immediately on a successful runtime + WebGL context.
+### Avatar Artifact (standalone avatar viewer): `/avatar-artifact`
+- **Source:** `pages/avatar-artifact.html` (markup, the designed loading/error overlays with their `data-msg-*` copy, the embed/share snippet, and the inline failure + watchdog script) → `src/avatar-artifact.js` (scene, artifact resolution, GLB loading, retargeted idle). three.js ships with the bundle; there is no third-party CDN script, because the page is meant to be pasted into other sites as a bare iframe. NOTE: this is the "standalone Three.js viewer for avatar artifacts, embeddable and shareable without any wrapper page" (page OG meta). Three modes share one composed stage (lighting, ground, fog, drifting motes): `?agent=<uuid>` renders that agent's avatar, `?model=<url>` renders any GLB on an allowlisted host, and no params renders the house portrait, a procedural figure (cylinders/spheres/boxes) that tracks the visitor.
+- **Entry point:** `<script type="module" src="/src/avatar-artifact.js">` (avatar-artifact.html:511), preceded by the inline script that defines `window.__avatarArtifactFailed` and arms a 12s watchdog (avatar-artifact.html:415-457). The module resolves the artifact from the query string (`resolveArtifact`), imports `three` (plus `GLTFLoader` and the meshopt decoder only on the model lane), and calls `boot(artifact)`.
+- **Prerequisites / gates:** None. No auth, wallet, or $THREE gate. The agent lane reads the public `GET /api/agents/:id`; a `?model=` URL must be `https://` on three.ws, `*.r2.dev`, `*.r2.cloudflarestorage.com`, `*.amazonaws.com`, `*.cloudfront.net`, `storage.googleapis.com`, `*.blob.core.windows.net`, or `*.vercel.app` (the same allowlist `/api/artifact` enforces, `ALLOWED_MODEL_HOSTS`, avatar-artifact.js:28-40). Renders on a successful runtime + WebGL context.
- **Steps (N):**
- 1. Arrive at `/avatar-artifact`. Loading overlay shows while the CDN three.js runtime loads.
- 2. Runtime + WebGL guard — if three.js never arrives (`onerror`) or `window.THREE` is missing, or WebGL context creation throws, the designed error state is shown (`window.__avatarArtifactFailed`, avatar-artifact.html:257-298).
- 3. On success the procedural avatar renders; the loading overlay fades out on first frame (avatar-artifact.html:663-669).
- 4. Interact — the avatar's gaze follows the mouse (`mousemove`), touch drag (`touchmove`), or keyboard (arrow keys / WASD nudge the gaze; canvas is `tabIndex=0`, `role="img"`, ARIA-labeled, KEY_STEP 0.25) (avatar-artifact.html:543-589).
- 5. The canvas continuously animates (idle motion, blink) and stays responsive to resize/orientation change (avatar-artifact.html:685-686).
-- **Decision points / branches:** Runtime available + WebGL OK (render) vs runtime/WebGL failure (error state). Coarse pointer (phones/tablets) → lighter render (lower DPR, no shadow pass, avatar-artifact.html:286-302). Pointer/touch input vs keyboard gaze control.
-- **External calls / dependencies:** CDN `three.min.js` r128 from cdnjs (with SRI integrity + `crossorigin`); `/api/page-og` for OG/Twitter share images (meta only). No model import/export, no platform API, no glTF validator.
-- **Success state:** Animated procedural avatar that tracks cursor/touch/keys; loading overlay faded out.
-- **Empty / error states:** Loading overlay (`#loading`) during runtime load; designed error overlay (`#error`) when the CDN runtime fails or WebGL is unavailable. No empty "no model" state — the avatar is always present once the runtime loads.
-- **Step count:** ~3 required (arrive → runtime/WebGL OK → avatar renders) + ~1 optional (interact via cursor/touch/keyboard).
+ 1. Arrive at `/avatar-artifact` (optionally with `?agent=` or `?model=`). Loading overlay shows while the bundled runtime loads; the artifact lane holds it until the GLB has actually arrived, with a lane-specific loading note.
+ 2. Resolve the artifact: both params → `msgBoth` failure; a non-UUID or unknown `?agent=` → `msgNotFound` with an action link to `/agents`; an agent whose lookup failed → `msgAgentFetch`; an agent with no avatar → `msgNoAvatar`, or `msgAvatarPrivate` when it has one it will not show, each linking the agent's profile; a `?model=` off the allowlist → `msgModelBlocked` (avatar-artifact.js:60-165).
+ 3. Runtime + WebGL guard: if the runtime import fails, WebGL context creation throws, or the module never runs at all (the watchdog fires after 12s of silence; a heartbeat re-arms it while a large model is still downloading), the designed error state is shown (`window.__avatarArtifactFailed`, with a Retry that reloads). A GLB that fails to parse → `msgModelFailed`.
+ 4. On success the avatar (or the house portrait) renders and the loading overlay fades on the first painted frame, which also clears the watchdog and any error that raced it (avatar-artifact.js:378-392). A loaded humanoid rig plays the shared retargeted `idle` clip from `/animations/manifest.json` through `AnimationManager` (`breatheLife`); a rig the canonicalizer cannot drive simply stands still.
+ 5. Interact: the figure's gaze follows the mouse (`mousemove`), touch drag (`touchmove`), or keyboard (arrow keys / WASD nudge the gaze by `KEY_STEP` 0.25; the canvas is focusable, `role="img"`, ARIA-labeled). A turntable orbits the look target unless `prefers-reduced-motion` is set.
+ 6. (optional) **Copy embed**: the page carries its own `<iframe>` snippet pointing at this URL; once a specific artifact resolves, the module hands its query back (`__avatarArtifactSetEmbed`) so the copied iframe shows the avatar on screen rather than the house portrait. Clipboard denied (cross-origin frame, insecure context) → the snippet field is revealed and selected for manual copying (avatar-artifact.html:459-507).
+ 7. The canvas keeps animating (idle motion, blink, drifting motes) and stays responsive to resize/orientation change.
+- **Decision points / branches:** Agent lane vs model lane vs house portrait. Runtime available + WebGL OK (render) vs runtime/WebGL/watchdog failure (error state). Coarse pointer (phones/tablets) → lighter render (no antialias, lower DPR, no shadow pass). Pointer/touch input vs keyboard gaze control. Clipboard write vs manual snippet.
+- **External calls / dependencies:** `GET /api/agents/:id` (agent lane), the avatar GLB itself (model lane; meshopt decoded), `GET /animations/manifest.json` + the retargeted idle clip; `/api/page-og` for OG/Twitter share images (meta only). No platform API on the house-portrait lane, no glTF validator, no export.
+- **Success state:** Animated avatar (or procedural portrait) that tracks cursor/touch/keys; loading overlay faded out; embed snippet copied.
+- **Empty / error states:** Loading overlay (`#loading`) during runtime and model load; designed error overlay (`#error`) with per-failure copy (`data-msg-both`, `-not-found`, `-agent-fetch`, `-no-avatar`, `-avatar-private`, `-model-blocked`, `-model-failed`, `-no-webgl`), one contextual action link, and a Retry. No empty "no model" state: without params the house portrait is always present once the runtime loads.
+- **Step count:** ~3 required (arrive → resolve + runtime/WebGL OK → avatar renders) + ~2 optional (interact via cursor/touch/keyboard, copy the embed snippet).
---
-<a id="sec-507"></a>
+<a id="sec-527"></a>
> **Source:** `docs/ux-flows/04-embed-widget-studio.md` · [↑ table of contents](#table-of-contents)
@@ -117288,7 +122065,7 @@ Routing recap (from `vercel.json`):
| `/avatar-studio`, `/create/studio` | `pages/avatar-studio.html` (+ `src/avatar-studio.js`) — **Avatar Studio** (appearance builder; feeds the embed flows) |
| `/w/<id>` | saved widget page (live widget) |
| `/widget`, `/widget.html` | slim viewer shell (`/src/app.js`) used as Studio/gallery preview iframe + script-tag embed target |
-| `/agent/<id>/embed`, `/embed/avatar/<handle>`, `/embed`, `/a-embed.html` | embed iframe targets |
+| `/agents/<id>/embed` (the legacy `/agent/<id>/embed` still serves the same page), `/embed/avatar/<handle>`, `/embed`, `/a-embed.html` | embed iframe targets |
| `/embed.js`, `/embed-sdk.js`, `/artifact.js`, `/dist-lib/agent-3d.js` | embed loader / SDK / web-component scripts |
> Naming note: the prompt's "avatar-studio embeddable AI widget builder" maps to the **Widget Studio** at `/studio` (the talking-agent widget type is the embeddable AI widget). `/avatar-studio` is the **appearance builder** — it produces the avatar that the Studio and embed panels then wrap. Both are documented below.
@@ -117316,7 +122093,7 @@ Routing recap (from `vercel.json`):
- `?edit=<id>` → `loadForEdit()` hydrates an existing widget (PATCH on save). `?template=<id>` → `cloneTemplate()` (config copied, avatar must be re-picked, POST creates new). `?model=<url>` / `?avatar=<id>` → preselect / auto-register R2 model (`autoRegisterAndSelect` HEADs the GLB then POSTs `/api/avatars`).
- Embed-modal include toggles add `noAnimations=1` / `noChat=1` / `noControls=1` to the URL.
- Right column tabs: **Brand** ↔ **⚡ Launch** (launch panel hides save/generate row).
-- **External calls / dependencies:** `/api/auth/me`, `/api/auth/logout`, `/api/avatars`, `/api/avatars/public`, `/api/avatars/:id` (POST to register), `/api/widgets` (GET/POST/PATCH/DELETE), preview iframe `/widget#…`, embed loader `/embed.js`, share/live `/w/<id>`, `/api/widgets/:id/og` (poster). Importmap loads `@solana/web3.js` + `@solana/spl-token` from esm.sh for the Launch tab.
+- **External calls / dependencies:** `/api/auth/me`, `/api/auth/logout`, `/api/avatars`, `/api/avatars/public`, `/api/avatars/:id` (POST to register), `/api/widgets` (GET/POST/PATCH/DELETE), preview iframe `/widget#…`, embed loader `/embed.js`, share/live `/w/<id>`, `/api/widgets/:id/og` (poster). The page importmap pins `@solana/web3.js` + `@solana/spl-token` to esm.sh; `launch-panel.js` loads its own web3.js and `qrcode` copies through `/load-module.js` (esm.sh, then jsdelivr, then unpkg, each under a deadline) and, if all three miss, reports "<what> could not be loaded (<hosts> unreachable or blocked). Check your connection or ad blocker and try again."
- **Success state:** Embed modal open with a copyable iframe + script snippet and a live shareable `/w/<id>` URL; "View live" opens it in a new tab. Toast "Saved" on draft save.
- **Empty / error states:** No avatars → empty card with "Make one from a selfie →" / "browse every way to build one →". Avatar load failure → inline error card with **Retry**. Public search failure → status line shows reason. Save failure → `#form-error` text. Preview without a model → a note that the avatar has no public URL (make it public/unlisted to preview). Pre-selected avatar missing → toast + falls back to demo. Pending-status types show a "ships in a later prompt" banner (currently none: all 10 are `ready`).
- **Step count:** 10 required (+5 optional)
@@ -117341,7 +122118,7 @@ Routing recap (from `vercel.json`):
- Preview iframe uses `reveal=interaction` + a `/api/widgets/<id>/og` poster to keep WebGL slots free on a dense page.
- **External calls / dependencies:** `/widgets-gallery/showcase.json`, preview iframes at `/widget#widget=<id>…`, `/api/widgets/<id>/og` (poster), model-viewer 4.0.0 (footer avatar, from googleapis CDN with SRI). Mints used in defaults are SOL wrapped-mint and the `$THREE` CA.
- **Success state:** Snippet copied to clipboard ("Copied!"); live preview rendered in card.
-- **Empty / error states:** Showcase fetch failure → error card "Could not load showcase config." with detail. Per-card iframe failure leaves the placeholder/play button. Hero count defaults to 15 in static HTML, overwritten by real count.
+- **Empty / error states:** Showcase fetch failure → `role=alert` card "The widget showcase could not load. Check your connection and try again." with the detail, a **Try again** button that re-runs the load (replacing the filter bar instead of stacking a second one) and a "Read the widget docs" link (`/docs/widgets`). A manifest with zero widgets → "No showcase widgets yet" empty state with **Open the Studio**. Per-card iframe failure leaves the placeholder/play button. Hero count defaults to 15 in static HTML, overwritten by the real count (and re-written whenever the i18n runtime repaints the badge).
- **Step count:** 6 required (+3 optional)
---
@@ -117364,48 +122141,46 @@ Routing recap (from `vercel.json`):
### Claude.ai Artifact builder — `/artifact`
- **Source:** `public/artifact/index.html` (self-contained, inline module script), `public/artifact/README.md`, `public/artifact/snippet.html`. Backend: `GET /api/artifact` (returns one self-contained HTML doc; see `specs/CLAUDE_ARTIFACT.md`). Also a `/artifact.js` loader script for in-artifact `<div data-agent-id>` mounting.
- **Entry point:** Direct nav to `/artifact`; deep link `?agentId=<id>` (auto-generates on load).
-- **Prerequisites / gates:** None to use the builder. To produce a working artifact you need a valid **agent ID/handle** (or whitelisted-CDN `model` URL). GLB must be **≤ 6 MB** (server returns 413 otherwise). No auth/$THREE gate on the page itself.
+- **Prerequisites / gates:** None to use the builder. To produce a working artifact you need a valid **agent UUID** (a hand-typed handle is refused with `400 invalid_request`: "agent must be the agent UUID, copied from the agent profile page") or a whitelisted-CDN `model` URL. GLB must be **≤ 6 MB** (server returns 413 otherwise). No auth/$THREE gate on the page itself.
- **Steps (6):**
- 1. Visitor lands; the page fetches and shows the live Claude sandbox CSP (`raw.githubusercontent.com/simonw/scrape-claude-artifacts/…`) in a `<details>`.
- 2. **Configure**: enter Agent ID; `(optional)` set Theme (dark/light), Idle clip name, Background hex.
- 3. Click **Generate** (or Enter) → `buildUrl()` assembles `/api/artifact?agent=…&theme=…&idle=…&bg=…`; overlay shows "Fetching artifact…"; `history.replaceState` adds `?agentId=`.
- 4. System fetches the artifact HTML, measures size + first-paint, checks the response CSP for `frame-ancestors *`, and renders it into a **sandboxed iframe** (`sandbox="allow-scripts"`, `srcdoc`). Stats panel fills in (Artifact size ok/warn/bad, First paint, Sandbox compliant/mismatch).
+ 1. Visitor lands; the page shows the vendored Claude sandbox CSP (`/claude-artifact-csp.txt`, the same bytes `tests/api/artifact.test.js` pins the endpoint against) in a `<details>`, and a **"Public agents you can embed"** picker loads `GET /api/agents/public?sort=popular&limit=12&avatar=1` (four skeleton tiles → a grid of avatar tiles; "Browse all" → `/agents`).
+ 2. **Configure**: click a picker tile (fills the ID and generates in one tap) or paste an agent UUID; `(optional)` set Theme (dark/light), Idle clip name, Background hex (six hex digits, validated live with an inline hint).
+ 3. Click **Generate** (or Enter) → `buildUrl()` assembles `/api/artifact?agent=…&theme=…&idle=…&bg=…`; overlay shows "Fetching artifact…"; the query string is synced to `?agentId=` plus any non-default theme/idle/bg so the address bar carries the whole configuration.
+ 4. System fetches the artifact HTML, measures size, fetch time and render time, checks the response CSP for `frame-ancestors *`, and renders it into a **sandboxed iframe** (`sandbox="allow-scripts"`, `srcdoc`). Stats panel fills in: Artifact (size, graded against the ~8.6 MB ceiling a 6 MB model produces once base64-inlined on top of the 565 KB viewer), Fetch, Render, Sandbox compliant/mismatch.
5. **Copy** the result: **Copy URL** (the `/api/artifact?…` link), **Copy raw HTML** (the full self-contained doc), or **Open in tab**; `(optional)` expand the "Paste-into-Claude snippet" (`Here's my agent for this conversation:\n<url>`).
6. Paste the URL into a Claude.ai conversation → Claude embeds the artifact and the 3D avatar renders inline (zero external fetches, CSP-compliant). Done.
- **Decision points / branches:**
- `agent` vs. `model` source (README); theme/idle/bg are optional refinements.
- - Size thresholds: >5 MB = warn, >8 MB = bad (server caps at 6 MB → 413).
+ - Size thresholds: the stat grades the inlined HTML against the ceiling a legal 6 MB model produces (`ceil(6 MiB / 3) * 4 + 565 KB`): over 70% of it = warn, over 100% = bad; the server caps the model itself at 6 MB → 413. Fetch: >2s warn, >5s bad. Render: >3s warn, >8s bad, 30s timeout.
- Two consumption paths: paste the **URL** directly, or paste the **raw HTML** / use the `/artifact.js` `<div data-agent-id>` snippet inside an existing artifact.
-- **External calls / dependencies:** `GET /api/artifact` (the bundle), Claude CSP mirror at `raw.githubusercontent.com/simonw/scrape-claude-artifacts/main/content-security-policy.txt`. Artifact bundle inlines three.js + GLTFLoader + GLB (~565 KB viewer overhead) — no runtime fetch.
+- **External calls / dependencies:** `GET /api/artifact` (the bundle; answers open CORS for GET/HEAD/OPTIONS so an embedder may fetch it as well as iframe it), `GET /api/agents/public` (the picker), `/claude-artifact-csp.txt` (same-origin vendored copy of Claude's sandbox CSP). Artifact bundle inlines three.js + GLTFLoader + GLB (~565 KB viewer overhead), no runtime fetch.
- **Success state:** Live preview renders in the CSP-mirrored sandbox; stats show "compliant"; URL/HTML copied.
-- **Empty / error states:** No agent ID → overlay "Enter an agent ID first." Network error / non-OK → overlay shows `error_description`/HTTP status. CSP mirror unreachable → falls back to a note pointing at `specs/CLAUDE_ARTIFACT.md`. Sandbox mismatch → stat shows "mismatch" (bad).
+- **Empty / error states:** No agent ID → overlay "Enter an agent ID first." with the hint to pick a public agent on the left or paste an ID from a profile, and focus returns to the field. Network error / non-OK → error overlay with the server's `error_description`, a per-code next step (`not_found` pick a public agent or paste an ID; `no_avatar` generate one at `/create`; `invalid_request` "Agent IDs are UUIDs…"; `upstream_error` retry or use a different avatar) and a **Retry** button. Picker feed failure → note in the picker with a retry. CSP file unreachable → "Could not load /claude-artifact-csp.txt. The locked-in copy is in specs/CLAUDE_ARTIFACT.md." Sandbox mismatch → stat shows "mismatch" (bad).
- **Step count:** 6 required (+2 optional)
---
-### Agent embed snippet (SharePanel / `<agent-3d>`) — share/embed panel flow
-- **Source:** `src/share-panel.js` (`SharePanel` class) + `src/share-panel-builders.js` (`buildEmbedUrl`, `buildIframeSnippet`, `buildWebComponentSnippet`) + `src/share-panel.css`. Mounted on the agent home page via `src/agent-home-orphans.js`. (`src/agent-detail.js` and `src/forge.js` use the lighter `showSharePanel` from `src/shared/share.js`, a different share sheet.) Embed targets: `/agent/<id>/embed` (CSP `frame-ancestors *`), web component `/dist-lib/agent-3d.js`. Preview iframe = same `/agent/<id>/embed?preview=1`.
-- **Entry point:** **Share** button on an agent profile/home page (`agent-home-orphans.js` injects it next to the title) → `new SharePanel({ agent }).open()`.
-- **Prerequisites / gates:** Must be on an **existing agent** (an `agent.id`/`slug`). No sign-in required to copy snippets — embedding is free ("no wallet or on-chain deployment required"). No $THREE gate.
-- **Steps (6):**
- 1. Click **Share** → modal opens with the agent's permalink `/a/<slug|id>`, a live preview iframe, and pre-rendered snippets.
- 2. `(optional)` **Copy link** or **Open ↗** the agent permalink.
- 3. **Customise embed** `(optional)`: Background (transparent/dark/light), Name plate (on/off), Size (small 320×420 / medium 420×520 / large 520×680). Each toggle re-renders the snippets and reloads the live preview (`?preview=1` bypasses the embed origin allow-list).
- 4. Choose a format and **Copy**: **iframe embed** (`<iframe src="/agent/<id>/embed?…">`) or **Web component** (`<script src="/dist-lib/agent-3d.js">` + `<agent-3d agent-id="…" background=… name-plate=off>`). Button flips to "Copied ✓".
- 5. `(optional)` **OG preview** + copy the `/api/a-og?id=<id>` card URL; **QR code** of the permalink is rendered (canvas, SVG fallback).
- 6. Paste the iframe or `<agent-3d>` snippet on any third-party site → the agent renders inline (the `/agent/<id>/embed` page runs `src/avatar-embed.js` / element runtime, exposing the `v1.avatar.*` postMessage bridge). Done.
+### Agent embed snippet (studio page / `<agent-3d>`): share/embed panel flow
+- **Source:** the canonical studio page `/agents/<id>` (`src/avatar-page.js`, `renderEmbedPanel`) and the long-form profile `/agents/<id>/profile` (`src/agent-detail.js` + `renderEmbed` in `src/agent-detail-market.js`, the `#ad-embed-card`). Both build their snippets inline; the **Share** button on those pages opens the lighter `showSharePanel` sheet from `src/shared/share.js` (Copy link, Share on X, Share on Farcaster, Remix, OG preview image). `src/share-panel.js` (`SharePanel` class) + `src/share-panel-builders.js` (`buildEmbedUrl`, `buildIframeSnippet`, `buildWebComponentSnippet`) remain in the tree as a tested library (`tests/share-panel.test.js`), but nothing mounts them since the `agent-home-orphans` helper was deleted on 2026-08-06. Embed targets: `/agents/<id>/embed` (CSP `frame-ancestors *`; the legacy `/agent/<id>/embed` serves the same page), web component `/dist-lib/agent-3d.js`.
+- **Entry point:** the **Embed** view in the studio page's action bar (`?view=embed`, alongside 3D · Chat · AR · Profile) reveals the embed panel; on the profile, `?view=embed` scrolls to and flashes the embed card (`focusEmbedSection`).
+- **Prerequisites / gates:** Must be on an **existing agent** with a public GLB. No sign-in required to copy snippets; embedding is free (no wallet or on-chain deployment required). No $THREE gate. An owner who switched embedding off in the embed policy (`/api/agents/<id>/embed-policy`) hides the profile card (`data-embed-disabled`).
+- **Steps (4):**
+ 1. Open the agent's studio page → switch to the **Embed** view (or open the profile and scroll to "Embed").
+ 2. Read the intro ("Drop this <agent|avatar> on any website. Use the wizard for a live preview and platform instructions.") and, `(optional)`, click **Configure in wizard ↗** → `/embed?…` (the walk-through embed wizard) in a new tab.
+ 3. Choose a snippet and **Copy** (button flips to "Copied ✓", reverting after ~1.8s): **Web component** (`<script type="module" src="https://three.ws/dist-lib/agent-3d.js">` + `<agent-3d src="<glb>" agent-id="…">`), **iframe** (studio page: `<iframe src="/agents/<id>?embed=1">`, the page hides its chrome in embed mode; profile card: `<iframe src="/agents/<id>/embed" width="480" height="640">`), the **page link**, or (studio page) the **Terminal** snippet that runs the avatar in any terminal with no browser or GPU (see `/docs/tty-avatar`).
+ 4. Paste the iframe or `<agent-3d>` snippet on any third-party site → the agent renders inline (`/agents/<id>/embed` runs `src/avatar-embed.js` / the element runtime, exposing the `v1.avatar.*` postMessage bridge). Done.
- **Decision points / branches:**
- - iframe vs. web-component snippet (web component observes `background` / `name-plate` attrs).
- - Default options (transparent bg, name on, medium) are omitted from the URL to keep it canonical/short.
- - Separate, simpler embed entry points exist: **Agent Hub** "Embed" button → `AgentEmbedModal` (`src/agent-embed-modal.js`, iframe / `<agent-3d>` / SDK tabs with width×height); **Dashboard** avatar/agent "Embed" → `openAvatarEmbedModal` (`src/dashboard/dashboard.js`, `/a-embed.html?avatar=<id>` with size/bg/name presets). See variants below.
-- **External calls / dependencies:** `/agent/<id>/embed` (preview + final), `/dist-lib/agent-3d.js` (web component), `/api/a-og?id=<id>` (OG image), `/a/<slug|id>` (permalink). QR rendered locally (`src/erc8004/qr.js`).
-- **Success state:** Snippet copied ("Copied ✓"); live preview shows the agent in the chosen size/bg.
-- **Empty / error states:** Preview iframe failure leaves the framed area blank with the chosen bg color visible; OG image alt text shown if it fails to load; QR falls back canvas → SVG → plain link text.
-- **Step count:** 6 required (+3 optional)
+ - iframe vs. web-component snippet (the web component observes `agent-id`, `background`, `name-plate` attrs).
+ - Studio page (`?embed=1`, full studio inside the frame) vs. profile card (`/agents/<id>/embed`, the chat-style embed).
+ - Separate, simpler embed entry points exist: the legacy **Agent Home** page (`public/agent/index.html`, only reachable at its literal `/agent/index.html` path now that `/agent/<id>` 301s to `/agents/<id>`) mounts `src/agent-hub-actions.js`, whose "Embed" button opens `AgentEmbedModal` (`src/agent-embed-modal.js`); **Dashboard** avatar/agent "Embed" → `openAvatarEmbedModal` (`src/dashboard/dashboard.js`, `/a-embed.html?avatar=<id>` with size/bg/name presets). See variants below.
+- **External calls / dependencies:** `/agents/<id>/embed` and `/agents/<id>?embed=1` (final), `/dist-lib/agent-3d.js` (web component), the agent's GLB URL, `/embed` (wizard), `/api/agents/<id>/embed-policy` (profile card gate).
+- **Success state:** Snippet copied ("Copied ✓"); the pasted snippet renders the agent inline on the host page.
+- **Empty / error states:** Agent without a 3D avatar → the profile card's web-component snippet reads `<!-- No 3D avatar attached yet -->`; embedding switched off by the owner → profile card hidden; a clipboard write that throws leaves the button reading "Copy" (the snippet stays selectable in its `<pre>`).
+- **Step count:** 4 required (+1 optional)
#### Variant — Agent Hub embed modal (`AgentEmbedModal`)
- **Source:** `src/agent-embed-modal.js`, triggered from `src/agent-hub-actions.js` (hub "Embed" button) and `src/dashboard/dashboard.js` (`openAgentEmbedModal`).
-- **Steps (4):** (1) Click "Embed" on the agent hub → modal opens (default 420×520). (2) `(optional)` adjust Width/Height. (3) Switch tab: **iframe** (`/agent/<id>/embed`), **`<agent-3d>`** (`/dist-lib/agent-3d.js` web component), or **SDK** (`/embed-sdk.js` + `Agent3D.connect()` bridge example). (4) **Copy** → paste on site. Snippets are pure-string built from `origin` + `id` + `w` + `h`; note: "Free to embed — no wallet or on-chain deployment required."
+- **Steps (4):** (1) Click "Embed" on the agent hub → modal opens (default 420×520). (2) `(optional)` adjust Width/Height. (3) Switch tab: **iframe** (`/agents/<id>/embed`), **`<agent-3d>`** (`/dist-lib/agent-3d.js` web component), **SDK** (`/embed-sdk.js` + `Agent3D.connect()` bridge example), or **walking avatar** (a live `/walk-embed` preview iframe that reloads as the options change). (4) **Copy** → paste on site. Snippets are pure-string built from `origin` + `id` + `w` + `h`; note: "Free to embed : no wallet or on-chain deployment required."
- **Step count:** 4 required (+1 optional)
#### Variant — Dashboard avatar embed (`openAvatarEmbedModal`)
@@ -117422,15 +122197,15 @@ Routing recap (from `vercel.json`):
- **Steps (7):**
1. Page boots → loads `BASE_GLB_URL` (`/avatars/default.glb`) into a `TalkScene` viewport with idle breathing/blinking; accessory presets load. In create mode a **Base switcher** offers Stylized (the default stylized humanoid body) or Parametric (`/avatars/parametric-base.glb`, a CC0 MakeHuman-derived base with ~120 identity morph sliders); Color/Layers panels adapt to the loaded base (dead slots hide).
2. `(optional)` In **edit mode** (`?edit=<id>`) the saved appearance (colors/morphs/accessories/hidden layers) is hydrated onto the model.
- 3. **Customize**: switch tabs — Color (skin/hair/outfit swatches + hex), Hats, Glasses, Earrings (accessory presets), Face (sculpt morphs). Each change applies live to the scene graph; `(optional)` undo/redo (history up to 50).
+ 3. **Customize**: switch tabs: Color (skin/hair/outfit swatches + hex), Hats, Glasses, Earrings (accessory presets from the catalog, each tab with its own loading / error / populated state), Sculpt (morphs), Animate. On narrow viewports the tab bar collapses to icons. Each change applies live to the scene graph; an accessory is recorded in the appearance only once it is actually on the rig, and the tap that adds one shows busy feedback while the GLB fetches. `(optional)` undo/redo (history up to 50; each step is stamped so a press superseded while its accessories were still loading is dropped rather than applied late).
4. `(optional)` Show/hide garment layers; `(optional)` search accessories.
5. **Save** → exports the live scene via GLTFExporter (colors/morphs/accessories already baked), optimizes/validates the GLB (`avatar-studio-optimize.js`), uploads via `account.js` (`/api/avatars`), and PATCHes the appearance JSON so it stays re-editable; uploads a snapshot thumbnail.
6. The saved avatar now appears in the avatar library used by **Widget Studio** (`/studio` step 3) and the **embed/share panels**.
7. Continue into an embed flow: open Widget Studio, the agent SharePanel, or a dashboard embed modal to generate the snippet. Done.
- **Decision points / branches:** Create (from default) vs. Edit (`?edit=<id>`). Single-select tabs (hat/glasses) vs. multi (earrings). Save requires auth → otherwise prompts sign-in.
-- **External calls / dependencies:** `/avatars/default.glb`, accessory preset assets, `/api/avatars` (save/PATCH), avatar-snapshot upload, GLTFExporter. Hands off to `/studio`, SharePanel (`/agent/<id>/embed`), or `/a-embed.html`.
+- **External calls / dependencies:** `/avatars/default.glb`, accessory preset assets, `/api/avatars` (save/PATCH), avatar-snapshot upload, GLTFExporter. Hands off to `/studio`, the agent studio page's Embed view (`/agents/<id>/embed`), or `/a-embed.html`.
- **Success state:** Avatar saved to account, re-editable, and selectable in the embed/Studio flows.
-- **Empty / error states:** Queued ops swallow + log failures (`queueOp`); GLB validation/optimize failures surface in the save path; signed-out save routes to login. Unsaved-changes tracking via `appearanceEqual`.
+- **Empty / error states:** Boot failure → "Avatar Studio couldn't load. Check your connection and try again." (a model that fails to load gets the same stage error with a retry). The accessory catalog is a separate fetch from the model: while it loads the three accessory tabs show "Loading hats…" etc.; if it fails they show a retryable error ("We couldn't load the hats catalog … Colors, sculpt and animation still work, and you can save your avatar without accessories") while Color, Sculpt, Animate and Save keep working. A single accessory that fails to load → status "Couldn't load <name>: … Tap it again to retry", and it is not written into the appearance. Queued ops hand their outcome back to the caller (`runQueued` → `{ ok, error }`) instead of swallowing it; GLB validation/optimize failures surface in the save path; signed-out save routes to login. Unsaved-changes tracking via `appearanceEqual`.
- **Step count:** 7 required (+4 optional)
---
@@ -117443,7 +122218,7 @@ Routing recap (from `vercel.json`):
---
-<a id="sec-508"></a>
+<a id="sec-528"></a>
> **Source:** `docs/ux-flows/05-discovery-social.md` · [↑ table of contents](#table-of-contents)
@@ -117472,7 +122247,7 @@ Routing recap (from `vercel.json`):
---
### Discover — `/discover`
-- **Source:** `public/discover/index.html`, `public/discover/discover.js`, `public/discover/detail.{html,js,css}` (detail), `/api/explore`, `/api/discover-detail` (rewrite target for `/discover/a/...`)
+- **Source:** `public/discover/index.html`, `public/discover/discover.js`, `public/discover/detail.{html,js,css}` (detail), `/api/explore`, `/api/discover-detail` (rewrite target for `/discover/a/...`; a `kind=solana` asset that is not one of ours falls back to the crawled `solana_agents_index`, so external Solana agents get a real link preview, and a malformed id returns the bare shell instead of a 500)
- **Entry point:** Page load auto-calls `loadPage()`. URL params hydrate filters (`?q=`, `?chain=`, `?source=`, `?only3d=`, `?sort=`). Default view (no params) is **3D-only**.
- **Prerequisites / gates:** None to browse. Auth (`/api/auth/me`) only reveals the "View my agents" chip + nav link; no gate.
- **Steps (8):**
@@ -117483,7 +122258,7 @@ Routing recap (from `vercel.json`):
5. (optional) User picks a chain in the dropdown → reloads filtered to that chain.
6. (optional) User scrolls; IntersectionObserver sentinel (`480px` rootMargin) auto-loads the next cursor page, or user clicks "Load more".
7. (optional) User clicks a card's "Embed" button → embed modal opens with tabs (Web component / iframe / Link / Markdown / Farcaster), copy buttons; or "URI" button copies `agent://<chain>/<id>`.
- 8. **Payoff:** User clicks a card → navigates to detail (`/discover/a/<chain>/<id>`, `/discover/a/sol/<asset>`, served by `/api/discover-detail`) or "View 3D" → opens the GLB viewer.
+ 8. **Payoff:** User clicks a card → its canonical detail page from the API's `detailUrl`: ERC-8004 agents `/a/<chain>/<id>`, three.ws agents `/agents/<id>`, external Solana agents `/discover/a/sol/<asset>` (served by `/api/discover-detail`), avatars `/avatars/<id>`; or "View 3D" → opens the GLB viewer.
- **Decision points / branches:** card kind (onchain / avatar / solana → different render + detail URL); 3D-only default vs `only3d=0` firehose; signed-in (chip shown) vs not; IntersectionObserver present vs manual button.
- **External calls / dependencies:** `GET /api/explore`, `GET /api/auth/me`, `/api/discover-detail` (detail nav), `model-viewer` CDN, clipboard API.
- **Success state:** Grid of agent cards with live/static thumbnails + totals line; deep-linkable filtered view via `replaceState`.
@@ -117504,7 +122279,7 @@ Routing recap (from `vercel.json`):
5. (optional) Scroll → IntersectionObserver auto-loads next cursor page, or "Load more" button.
6. (optional) Click "Embed" on a card → avatar embed modal (Web component / iframe / Link / Markdown tabs, copy buttons); or click the hero's "✨ Surprise me" button (`data-surprise-avatar`) → `POST /api/avatars/surprise` composes a unique rigged GLB, revealed live in a tinted-stage modal with Reroll, a shareable `/gallery?surprise=<seed>` link, and "Make it mine" (stages the GLB into the guest flow → `/create-review`). No sign-in needed to see it.
7. (optional) For accessory cards, click "Equip" → modal fetches `GET /api/avatars` (user's own); if 401, shows Sign-in CTA; else lists up to 12 avatars; choosing one navigates to `/avatars/:id/edit?equip-glb=…&equip-bone=Head`.
- 8. **Payoff:** Click a card thumbnail → `/app#model=<glb>` (3D viewer); or "Use" → `/studio?avatar=<id>`; or "Animate" → `/pose?avatar=<id>`; or "View avatar" → `/avatars/<id>`. Below the grid, the **From the Forge** section renders community 3D models (`GET /api/forge-gallery?scope=community&limit=16`, deduped by prompt) with View/Remix actions.
+ 8. **Payoff:** Click a card thumbnail → `/avatars/<id>` (the avatar's own page, not the bare GLB viewer); or "Use" → `/studio?avatar=<id>`; or "Animate" → `/pose?avatar=<id>`; or "View avatar" → `/avatars/<id>`. Below the grid, the **From the Forge** section renders community 3D models (`GET /api/forge-gallery?scope=community&limit=16`, deduped by prompt; a forge row has no title, so the card shows the first clause of its spec prompt and keeps the full text in the tooltip) with View/Remix actions.
- **Decision points / branches:** accessory category → Equip flow vs Use/Animate; model_url present → model-viewer vs img; signed-in chip; forge section enabled vs hidden (additive, never blocks).
- **External calls / dependencies:** `GET /api/avatars/public`, `GET /api/forge-gallery`, `GET /api/avatars` (equip), `GET /api/auth/me`, `model-viewer` CDN, `onchain-badge.js`, `template-picker.js`, clipboard API.
- **Success state:** Grid of 3D avatar cards + total count + Forge community section.
@@ -117515,18 +122290,18 @@ Routing recap (from `vercel.json`):
### Animation Gallery — `/animations`
- **Source:** `pages/animations.html`, `src/animations-gallery.js`, `src/animation-categories.js` (derived categories), `src/animations-live-preview.js` (shared WebGL preview engine), `/api/animations/clips`, `/animations/manifest.json`, `/api/animations/library`, `/pose` (studio)
-- **Entry point:** Module runs `loadAll()` on import. Query (`?q=`, `?cat=`, `?filter=loop|once`, `?sort=`) round-trips through the URL; `?clip=<id>` deep-links straight into the detail modal.
+- **Entry point:** Module runs `loadAll()` on import. Query (`?q=`, `?cat=`, `?filter=loop|once`, `?sort=`) round-trips through the URL, and an unknown `cat`, `filter` or `sort` value falls back to the default rather than blanking the control or filtering everything away; `?clip=<id>` deep-links straight into the detail modal.
- **Prerequisites / gates:** None. Community clips fetched with `credentials: 'include'` but public visibility is the query; no sign-in required to browse.
- **Steps (5):**
- 1. User lands on `/animations`. System shows loading state and merges three sources into one grid: community clips (`GET /api/animations/clips?include_public=true&visibility=public`, capped at 300, newest first), the built-in three.ws motion library (`/animations/manifest.json`, the same curated clips `/pose` ships with), and the full Mixamo-sourced catalog (`GET /api/animations/library`, fetched from the R2 CDN in bounded 1000-clip pages).
+ 1. User lands on `/animations`. System shows loading state and merges three sources into one grid: community clips (`GET /api/animations/clips?include_public=true&visibility=public`, capped at 300, newest first), the built-in three.ws motion library (`/animations/manifest.json`, the same curated clips `/pose` ships with), and the full Mixamo-sourced catalog (`GET /api/animations/library`, fetched from the R2 CDN in bounded 1000-clip pages; only clips whose manifest entry carries a `thumb` get a thumbnail request, the rest show the icon placeholder without a doomed fetch).
2. System normalizes every clip to one card shape (poster thumbnail, derived category, duration, loop/once badge) and paginates client-side (36 per page, infinite scroll, lazy thumbnails).
3. (optional) User searches (`/` hotkey focuses the box), picks a category chip, a loop/once filter, or a sort → grid re-filters client-side; the URL stays shareable.
4. (optional) User hovers a card's preview zone → the ONE shared WebGL engine moves its singleton canvas into that card and plays the retargeted clip on the preview avatar (no iframes, no per-card GL contexts; skipped for touch and reduced-motion users, who get the preview inside the detail modal instead).
- 5. **Payoff:** Click a card → detail modal (arrow keys step between clips, Space toggles play, Copy link copies `/animations?clip=<id>`, Copy embed copies an `/embed/avatar?anim=<id>` iframe snippet) → "Open in Studio" navigates to `/pose?anim=<id>` to apply/remix the clip on an avatar.
+ 5. **Payoff:** Click a card → detail modal (arrow keys step between clips, Space toggles play, Copy link copies `/animations?clip=<id>`, Copy embed copies an `/embed/avatar?anim=<id>` iframe snippet) → "Open in Studio" navigates to `/pose?anim=<id>` to apply/remix the clip on an avatar. The transport stays hidden until the clip is on the stage, Tab is trapped inside the dialog, the sliders keep their own arrow and Space keys, and closing returns focus to the card that opened it.
- **Decision points / branches:** community vs library vs full-catalog card (community listed first); thumbnail present vs placeholder; touch/reduced-motion (modal-only preview) vs hover preview; search/filter active → empty-search state.
- **External calls / dependencies:** `GET /api/animations/clips`, `GET /animations/manifest.json`, `GET /api/animations/library` (R2 CDN pages), shared live-preview engine, `/pose` nav.
- **Success state:** One searchable grid across all three clip sources, each card live-previewable in place; "Open in Studio" reaches the editor.
-- **Empty / error states:** No results + no filter → empty state; with filter/query → empty-search state with the query echoed + Clear-search; fetch failure → error state with Retry.
+- **Empty / error states:** No results + no filter → empty state; with filter/query → empty-search state with the query echoed + Clear-search; fetch failure → error state with Retry only when nothing loaded and at least one source failed, since a partial failure still renders whatever answered.
- **Step count:** 2 required (+3 optional)
---
@@ -117538,29 +122313,29 @@ Routing recap (from `vercel.json`):
- **Steps (4):**
1. User lands on `/characters`. System renders 6 skeleton cards and fetches `GET /api/characters?limit=24&sort=new`.
2. System renders character cards: avatar image (or color-hash placeholder), creator handle, description, chat-count / holders stats, optional `$`token block (symbol, market cap, 24h change), and a wallet chip if the character has a Solana address (`walletChipHTML`).
- 3. (optional) User types in search → 300ms debounce → reload with `q`; or clicks a sort button (`data-sort`) → reload; or clicks "Load more" → paginates by cursor.
+ 3. (optional) User types in search → 300ms debounce → reload with `q`; or clicks a sort button (`data-sort`) → reload; or clicks "Load more" → paginates by cursor (opaque: `sort=new` echoes `created_at`, `sort=chats` echoes `<chat_count>:<created_at>` so Top pages through every character instead of ending after one page; a hand-edited cursor is a 400).
4. **Payoff:** User clicks a card → navigates to `/character/:id` (character detail / chat).
-- **Decision points / branches:** has token block vs not; has Solana address → wallet chip; image URL valid http(s) vs placeholder; reset vs append render.
+- **Decision points / branches:** has token block vs not; has Solana address → wallet chip; image URL valid http(s) vs placeholder; reset vs append render (a reset supersedes an in-flight request through a generation token, so a slow first page cannot paint over a newer sort or search).
- **External calls / dependencies:** `GET /api/characters`, `walletChipHTML` from `src/shared/agent-wallet-chip.js`.
-- **Success state:** Grid of character cards each linking to its detail page.
-- **Empty / error states:** Empty → "No characters found." Fetch error → "Failed to load characters. Please try again."
+- **Success state:** Grid of character cards each linking to its detail page; the header carries a "Create a character" link to `/create-agent`.
+- **Empty / error states:** Search-empty → "No characters match “<q>”." with Clear search; feed-empty → "No characters published yet." with a Create a character link (`/create-agent`); fetch error → "Could not load characters." with Try again; a failed Load more keeps the cards already on screen and relabels the button "Retry loading more".
- **Step count:** 1 required (+3 optional)
---
### Community — `/community`
-- **Source:** `pages/community.html` (content + inline live-activity module + footer newsletter)
+- **Source:** `pages/community.html` (content, an Official channels ledger, inline live-activity module, an inline newsletter form plus the footer one; the palette is token-derived, so the page follows the site theme switcher)
- **Entry point:** Page load; the inline module fetches the live activity feed.
- **Prerequisites / gates:** None.
- **Steps (4):**
1. User lands on `/community` and reads the hero ("Build with us.").
- 2. System: the "Live activity" section fetches `GET /api/users/me/feed?scope=all&limit=10` (3 skeleton rows while loading) and renders the latest platform activity rows (avatar, actor + verb, title, relative time, thumbnail); "Open the full feed →" links to `/feed`.
- 3. (optional) User clicks a channel card: Follow on X (`@trythreews`), GitHub (`nirholas/three.ws`), Docs (`/docs`), Tutorials (`/tutorials`).
- 4. (optional) User reads "Ways to get involved" (ship an agent at `/create`, report bugs on GitHub issues, share feedback to `[email protected]`) or subscribes via the footer newsletter form.
+ 2. System: the "Live activity" section fetches `GET /api/users/me/feed?scope=all&limit=10` (3 skeleton rows while loading) and renders the latest platform activity rows (avatar, actor + verb, title · relative time, thumbnail; the item is a stretched overlay link and the actor's name is a separate `/u/<username>` link, so one row carries two destinations without nesting anchors); "Open the full feed →" links to `/feed`.
+ 3. (optional) User clicks a channel card: Follow on X (`@trythreews`), GitHub (`nirholas/three.ws`), Docs (`/docs`), Tutorials (`/tutorials`), IBM user group, Rankings (`/rankings`). Below the cards, **Official channels** lists every account and address the platform operates (X, Telegram `t.me/three_ws` plus the community chat, GitHub, the web domain, `[email protected]`, and the `$THREE` contract with a Copy button that falls back to selecting the text when the clipboard is unavailable) and a "Two things we never do" impostor notice.
+ 4. (optional) User reads "Ways to get involved" (ship an agent at `/create`, report bugs on GitHub issues, share feedback to `[email protected]`) or subscribes via the inline newsletter form (email + Subscribe, with a status line beneath it) or the footer one.
- **Decision points / branches:** activity populated vs empty vs error; which outbound channel the user follows; newsletter subscribe vs not.
-- **External calls / dependencies:** `GET /api/users/me/feed?scope=all` (live activity), external links (x.com, github.com), mailto, footer newsletter script.
-- **Success state:** Live activity rows render; user reaches a community channel / submits the newsletter form / opens `/feed`.
-- **Empty / error states:** Activity empty → "Nothing has happened yet" with a `/create` CTA; fetch failure → "Could not load live activity right now." Newsletter form handles its own submit feedback.
+- **External calls / dependencies:** `GET /api/users/me/feed?scope=all` (live activity), external links (x.com, github.com, t.me, IBM Community), mailto, clipboard API, footer newsletter script.
+- **Success state:** Live activity rows render; user reaches a community channel / submits the newsletter form / opens `/feed` / copies the `$THREE` contract.
+- **Empty / error states:** Activity empty → "No activity yet. Be the first to create something." with a `/create` link; fetch failure → "Could not load live activity right now." with a Try again button that reloads the feed. Newsletter form handles its own submit feedback.
- **Step count:** 2 required (+2 optional); content page with a live feed section
---
@@ -117574,7 +122349,7 @@ Routing recap (from `vercel.json`):
2. **Payoff (move):** On desktop, press **W/A/S/D / arrows** (Shift = run) to walk the avatar camera-relative; on mobile, drag the **left joystick** (nipplejs). Animation crossfades idle→walk→run to actual ground speed.
3. Orbit camera — drag mouse / pointer-lock (desktop) or the right look-stick (mobile); scroll/pinch to zoom; Q/E snap-turn 45°.
4. (optional) Set player name (`#walk-name-input`, persisted, broadcast); open Avatar picker → `GET /api/avatars?limit=20` (auth) → choose avatar (broadcast to room).
- 5. (optional) Jump (Space / button), cycle camera mode C (follow/cinematic/firstperson/topdown), cycle environment V (rebuilds physics colliders), emote G + 1–9 (broadcast), minimap M, chat T/Enter (broadcast bubble), friends F, players-panel.
+ 5. (optional) Jump (Space / button), cycle camera mode C (follow/cinematic/firstperson/topdown), cycle environment V (rebuilds physics colliders), emote G + 1 to 9 (broadcast), minimap M, chat T/Enter (broadcast bubble), friends F, players-panel; inspecting a remote player offers a DM that opens that thread in the in-world friends panel rather than sending the player to another surface.
6. (optional) **AR passthrough:** tap AR button/CTA → `getUserMedia({ video: { facingMode: { ideal: 'environment' } } })`; on grant the canvas goes transparent over the live rear-camera feed, terrain hides (shadow-catcher only), camera freezes in world space, blob shadow grounds the avatar; light estimation adapts intensities. (optional) Screenshot P, record 6s clip R (`MediaRecorder` → `navigator.share()` / download).
- **Decision points / branches:** mobile (touch joysticks) vs desktop (WASD + mouse); avatar source param; coin community mode (`?coin=` spawns CoinTotem + trade polling) vs solo/lobby; physics ready (Rapier) vs legacy movement; AR on/off; camera permission granted/denied/unavailable; multiplayer connected vs solo; zen mode (`?ui=hidden`).
- **External calls / dependencies:** `GET /api/avatars/{id}`, `GET /api/avatars?limit=20`, `GET /animations/manifest.json`, coin trades poll (`/api/pump/coin-trades?mint=` every 7s in coin mode), Colyseus WebSocket (multiplayer). Device APIs: `getUserMedia` (camera), `navigator.vibrate` (haptics), `navigator.share`, `requestPointerLock`, localStorage/sessionStorage.
@@ -117601,7 +122376,7 @@ Routing recap (from `vercel.json`):
- **Decision points / branches:** WebGL supported vs fatal overlay; placement path (gyro-GPS / WebXR floor / iOS Quick Look / QR marker / map); camera/motion/location granted vs denied (each → fallback); compass available (north-aligned) vs relative-only (`gyro-gps:rel`); GPS ready vs warm-up hold; agent crosses ENTER vs EXIT band; tap on mesh vs label vs background; precision Exact vs Nearby; room mode (shared frame) vs solo.
- **External calls / dependencies:** `POST/PATCH/DELETE /api/irl/pins`, `GET /api/irl/pins` (+ `/mine`), `GET /api/irl/agent-card`, `POST /api/irl/interactions`, `GET /api/irl/interactions-stream` (SSE), `POST /api/irl/report`, `POST /api/irl/fix-token`. Device: `getUserMedia` (camera), `DeviceOrientationEvent.requestPermission` / `deviceorientation(absolute)` (motion), `navigator.geolocation.watchPosition`, `navigator.permissions.query`, `navigator.vibrate`, `AudioContext`, WebXR `immersive-ar`. Realtime: Colyseus WebSocket (`IrlNet`, room `irl_world`). Libs: GLTFLoader (+Draco/meshopt), Leaflet/CARTO, in-browser USDZ exporter.
- **Success state:** Agent anchored to a real-world spot, visible in AR; nearby agents discovered by proximity (dots→impostors→meshes) with name labels, arrival cues, and an interaction sheet.
-- **Empty / error states:** WebGL unsupported → fatal designed overlay. Camera/motion/location denied → designed recovery cards with platform Settings steps + fallbacks. GPS warm-up → shimmer "Acquiring…". No nearby agents → calm "0 nearby" + "Place an agent here" CTA. Poll fail → amber "refresh failed" (15s retry). Rate-limited → calm blue chip, self-recovers. Avatar load fail → "Couldn't load this agent" + Retry. WebGL context lost → "AR paused" + Reload. Placement rejected (moderation/full/rate) → status message, lock released.
+- **Empty / error states:** WebGL unsupported → fatal designed overlay. Camera/motion/location denied → designed recovery cards with platform Settings steps + fallbacks. GPS warm-up → shimmer "Acquiring…". No nearby agents → calm "0 nearby" + "Place an agent here" CTA. Poll fail → amber "refresh failed" (15s retry). Rate-limited → calm blue chip, self-recovers. Avatar load fail → "Couldn't load this agent" + Retry. WebGL context lost → "AR paused" + Reload. Placement rejected (moderation/full/rate) → status message, lock released; a caption naming a cashtag or pump.fun-style mint other than `$THREE` is refused whatever the ticker's length. Pin ids are strict UUIDs on every pin route (`/api/irl/pins`, `/api/irl/interactions`, privacy, report), so a malformed id answers 400 rather than surfacing a Postgres cast error as a 500, and reports read the device credential from the `x-irl-device` header (body fallback) so an owner cannot self-report their own pin as an independent reporter.
- **Step count:** 7 required (+ several optional)
---
@@ -117623,7 +122398,7 @@ Routing recap (from `vercel.json`):
### Reputation Explorer — `/reputation`
- **Source:** `public/reputation/index.html`, `public/reputation/reputation.js`, `src/erc8004/{chain-meta,abi,reputation}.js`, EAS (Ethereum Attestation Service) EASScan GraphQL, EAS SDK + ethers
-- **Entry point:** On load the module parses URL params (`?address=`, `?chain=`, legacy `?agent=N:M`). With an address it renders a profile; without one it renders the search landing.
+- **Entry point:** On load the module parses URL params (`?address=`, `?chain=`, legacy `?agent=N:M`). With an address it renders a profile; without one it renders the search landing. A banner above the app cross-links the Reputation Staking Market (`/reputation/market`).
- **Prerequisites / gates:** **Reading** attestations needs no wallet (EASScan GraphQL + public RPC). **Writing** a review requires an injected wallet (MetaMask) on the write chain (Base Sepolia by default) + gas.
- **Steps (6):**
1. User lands on `/reputation`. With no `?address`, system renders the search form (address / ENS input, chain select, example chips).
@@ -117649,7 +122424,7 @@ Routing recap (from `vercel.json`):
2. User types a Solana asset mint / agent ID / avatar ID / slug into the input and presses Enter or clicks "go". System sets `?q=` via `replaceState`, disables the button, shows a skeleton.
3. System fetches `GET /api/registry/resolve?q=<input>` and renders the result.
4. **Payoff:** The resolved agent renders as an interactive `<model-viewer>` 3D avatar (or 🔒/🤖/image placeholder) alongside its identity card and on-chain panel (Active / x402 status, owner, collection, copy buttons, Metaplex / Solscan / Magic Eden links). "Share" copies the current URL.
-- **Decision points / branches:** has `modelUrl` → 3D viewer; `state === 'private'` → 🔒 placeholder; `imageUrl` → thumbnail; none → 🤖 placeholder; on-chain present vs "Not deployed on-chain yet".
+- **Decision points / branches:** has `modelUrl` → 3D viewer; `state === 'private'` → 🔒 placeholder; `imageUrl` → thumbnail (served only for a public avatar; a private one yields identity metadata and no imagery); none → 🤖 placeholder; on-chain present vs "Not deployed on-chain yet".
- **External calls / dependencies:** `GET /api/registry/resolve`, `model-viewer` CDN, clipboard API.
- **Success state:** A single agent resolved and rendered with its 3D avatar + on-chain identity.
- **Empty / error states:** No match → "No agent found" with a tip + link to the explore feed. Fetch error → "Something went wrong" with the error message.
@@ -117659,17 +122434,17 @@ Routing recap (from `vercel.json`):
### Agents Index — `/agents`
- **Source:** `public/agents/index.html` (inline module), `/api/explore` (`source=agents` meta-source), `public/agents/boot.js`
-- **Entry point:** Inline module runs `load(true)` on load.
+- **Entry point:** Inline module runs `load(true)` on load; `?source=`, `?q=` and `?sort=` are read first and kept in sync with `replaceState`, so a filtered directory is a shareable, reload-safe link.
- **Prerequisites / gates:** None to browse.
- **Steps (4):**
1. User lands on `/agents` ("Agent Index"). System renders 8 skeleton cards and fetches `GET /api/explore?source=agents&limit=24`, one unified feed across every registry the platform crawls: ERC-8004 (EVM, erc8004-crawl cron), the Metaplex Agent Registry + AgenC protocol (Solana, solana-agents-crawl cron), and three.ws's own agents. The meta-source returns on-chain agents only, never avatars.
2. System renders agent cards: thumbnail proxied through `/api/img` (lettered-initial fallback), a source badge (chain short-name for EVM / Metaplex / AgenC / three.ws), name + description, up to 3 service/skill chips, and an `x402` chip when the agent accepts x402 payments. Count label shows loaded total.
- 3. (optional) Source chips All sources / Solana / EVM → reload; search box → 320ms debounce → reload with `q`; sort select (Newest first / Name A-Z, client-side re-sort); "Load more" → cursor pagination (`cursor`).
- 4. **Payoff:** Click a card → its natural detail surface: EVM agents → `/a/<chain>/<id>`, three.ws Solana agents → `/agent/<id>`, external Solana agents → their 3D viewer or on-chain explorer (new tab). Hero CTAs link to `/create-agent` and `/marketplace`.
+ 3. (optional) Source chips All sources / Solana / EVM (a pressed-button group) → reload; search box → 320ms debounce → reload with `q` (an unchanged term does not refetch); sort select (Newest first / Name A-Z, client-side re-sort); "Load more" → cursor pagination (`cursor`), the button showing a spinner via `aria-busy` while it fetches and appending the new page instead of rebuilding the grid. A newer request always supersedes the one in flight.
+ 4. **Payoff:** Click a card → its canonical detail page: EVM agents → `/a/<chain>/<id>`, three.ws Solana agents → `/agents/<id>`, external Solana agents → the API's `detailUrl` (`/discover/a/sol/<asset>`), else their 3D viewer or on-chain explorer (new tab); a registry row with nowhere real to go renders without a link rather than with a dead one. Hero CTAs link to `/create-agent` and `/marketplace`.
- **Decision points / branches:** source chip (all / solana / onchain); card kind → internal vs external (target="_blank") destination; thumbnail vs initial fallback; nextCursor present (Load more shown) vs not.
- **External calls / dependencies:** `GET /api/explore?source=agents`, `/api/img` (thumbnail proxy).
- **Success state:** Grid of on-chain agents across all crawled registries, each linking to its detail surface.
-- **Empty / error states:** Query-empty → "No agents found" for the term; unfiltered-empty → "No agents in this source yet" + create-first CTA (registries are crawled continuously); fetch error → "Couldn't load agents" with "Try refreshing the page."
+- **Empty / error states:** Query-empty → "No agents match "<q>"" with Clear search and Create an agent; unfiltered-empty → "No agents in this source yet" with Check again and Create the first one (registries are crawled continuously); fetch error → "Couldn't load agents" naming the failure, with Try again and Browse the marketplace; a failed Load more → "Couldn't load more agents" keeping every page already on screen, with Resume loading (off the surviving cursor) or Start over. The panel is a live region, so the outcome is announced.
- **Step count:** 1 required (+3 optional)
---
@@ -117682,7 +122457,7 @@ Routing recap (from `vercel.json`):
1. User lands on `/my-agents`. System renders 4 skeletons and fetches `GET /api/agents` with `credentials: 'include'`.
2. If 401 → auth gate ("Sign in to manage your agents") with Sign-in (`/login?next=`) + Create-account links — flow stops here until signed in.
3. On success, reveals the "+ Create agent" CTA and renders each owned agent as a row: thumbnail/initial, name, on-chain vs "not registered" badge, description, top skills.
- 4. **Payoff:** Per-row actions — "View" (`home_url` or `/agent/:id`), "Edit" (`/agent/:id/edit`), and for unregistered agents a gold "Deploy" link to the edit page's deploy flow.
+ 4. **Payoff:** Per-row actions: "View" (`home_url` or `/agents/:id`), "Edit" (`/agents/:id/edit`), and for unregistered agents a gold "Deploy" link to the edit page's deploy flow.
- **Decision points / branches:** 401 (auth gate) vs authed; on-chain (badge + no Deploy) vs not registered (Deploy link); zero agents (empty state) vs populated.
- **External calls / dependencies:** `GET /api/agents` (session cookie).
- **Success state:** List of the signed-in user's agents with View / Edit / Deploy actions.
@@ -117711,11 +122486,11 @@ Routing recap (from `vercel.json`):
- All listed sources were located and traced from real files; no source was missing.
- `/characters` page HTML lives at `public/characters.html` (root-level dest in `vercel.json`), not under `pages/`.
- `/agents`, `/my-agents`, and `/lookup` keep their grid/lookup logic in **inline `<script type="module">` blocks** within the page HTML rather than a separate `src/` module.
-- Detail pages reached from these routes (`/discover/a/...`, `/character/:id`, `/avatars/:id`, `/agent/:id`, agent profile `home_url`) are outside this cluster's scope but are the payoff destinations.
+- Detail pages reached from these routes (`/discover/a/...`, `/a/:chain/:id`, `/character/:id`, `/avatars/:id`, `/agents/:id`, agent profile `home_url`) are outside this cluster's scope but are the payoff destinations. `/agents/:id` is the canonical agent route; the singular `/agent/:id` now 301s to it.
---
-<a id="sec-509"></a>
+<a id="sec-529"></a>
> **Source:** `docs/ux-flows/06-marketplace-skills.md` · [↑ table of contents](#table-of-contents)
@@ -117801,7 +122576,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g
12. On confirmed, modal renders a signed receipt (`buildReceiptHTML`) with a Solscan link, then resolves true.
13. Client refreshes ownership: `fetchUserPurchases()` and reloads the detail (`loadDetail`) so the skill now shows "Installed ✓"; the purchase appears under the "My Purchases" tab and in `/collection`.
- **Decision points / branches:** gasless (wallet connected, sponsored) vs buyer-pays vs mobile QR (Solana Pay); already-owned short-circuit; insufficient funds → Add funds; gift purchase (`recipient`) resolved server-side via `resolveRecipient`; verification mismatch (tipped) vs expired. A separate agent rail exists: `POST /api/marketplace/purchase-as-agent` `{ buyer_agent_id, seller_agent_id, skill }` buys the skill FOR an owned agent from its custodial wallet (owner-authenticated, CSRF-gated, 10 autonomous purchases/hour/agent, same daily spend cap as asset purchases).
-- **External calls / dependencies:** `POST /api/marketplace/purchase`, `POST /api/marketplace/purchase/:ref/confirm`, `GET /api/marketplace/purchase/:ref` (status), `GET /api/marketplace/check-skill-access`, Solana RPC via `/api/solana-rpc`, `@solana/web3.js` + `@solana/spl-token` (lazy-loaded), `@solana/pay` (server `findReference`/`validateTransfer`), gasless tx builder, `/api/users/me/purchased-skills` (post-purchase refresh), `/api/billing/receipts` (receipt download in My Purchases).
+- **External calls / dependencies:** `POST /api/marketplace/purchase`, `POST /api/marketplace/purchase/:ref/confirm`, `GET /api/marketplace/purchase/:ref` (status), `GET /api/marketplace/check-skill-access`, Solana RPC via `/api/solana-rpc` (rotates lanes; when every lane dies at the wire it re-sweeps once and answers an idempotent read from its last-good body, flagged with an `x-solana-rpc-stale` header, instead of a 502), `@solana/web3.js` + `@solana/spl-token` (lazy-loaded), `@solana/pay` (server `findReference`/`validateTransfer`), gasless tx builder, `/api/users/me/purchased-skills` (post-purchase refresh), `/api/billing/receipts` (receipt download in My Purchases).
- **Success state:** Receipt with tx link; skill flips to owned; appears in My Purchases tab and `/collection`; `check-skill-access` returns `has_access: true`.
- **Empty / error states:** cancelled connect/tx ("try again"), insufficient funds (Add funds button), `verification_failed` (paid but unverified — contact support), network error, expired pending row — all with the confirm button re-enabled for retry. Re-verify (no new tx) supported when a txid exists.
- **Step count:** 9 required (+4 optional)
@@ -117841,7 +122616,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.
+- **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 `/agents/: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)
@@ -117933,7 +122708,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g
---
-<a id="sec-510"></a>
+<a id="sec-530"></a>
> **Source:** `docs/ux-flows/07-crypto-trading-analytics.md` · [↑ table of contents](#table-of-contents)
@@ -117951,23 +122726,23 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
---
### Oracle — `/oracle`
-- **Source:** `pages/oracle.html`, `src/oracle.js` (~2400 lines), lazy `src/oracle-graph.js` (3D force graph), `src/oracle-tape.js` (live trade tape in the coin drawer)
-- **Entry point:** nav link "Oracle"; direct URL; SEO/share links from `coinShareUrl()`. `/oracle/coin/<mint>` is now a standalone full conviction coin page (server-rendered by `api/oracle-share.js` in the markets-hub style: score dial, pillar bars, chart, launch intelligence), reached from the drawer's "Full page ↗" action.
+- **Source:** `pages/oracle.html`, `src/oracle.js` (~2500 lines), lazy `src/oracle-graph.js` (3D force graph), `src/oracle-tape.js` (live trade tape in the coin drawer)
+- **Entry point:** nav link "Oracle"; direct URL; SEO/share links from `coinShareUrl()`. `/oracle/coin/<mint>` is now a standalone full conviction coin page (server-rendered by `api/oracle-share.js` in the markets-hub style: score dial, pillar bars, chart, launch intelligence), reached from the drawer's "Full page ↗" action. The server-rendered hero also carries the score's measured odds (what share of calls in that band won, against the random-launch base rate, read from `conviction-calibration.json` via `hitRateFor`) and a "Since the call" strip (peak multiple, graduated / rugged / still live, market cap now) joined from `pump_coin_outcomes`, so the first paint and the share preview never show an unqualified 100/prime on a coin the market has already resolved; the share description gets a "since:" clause for the same reason. Coin identity falls back to DexScreener when pump.fun does not answer, coin art is proxied through `/api/img`, and the route is GET-only.
- **Prerequisites / gates:** Public dashboard for all read views (feed, movers, wallets, edge, proof, agents, activity, graph). The **Agent** (arm) tab requires sign-in + an existing 3D agent with a custodial Solana wallet; Live mode spends real (capped) SOL.
- **Steps (N):**
1. Arrive on `/oracle` → `boot()` populates category filter, binds tab/seg listeners, reads URL filters (`tier`, `category`, `minScore`, `view`), loads the **feed** view.
- 2. System: `GET /api/oracle/feed?...` renders conviction cards (0–100 score, tier pill prime/strong/lean/watch/avoid). If backend not migrated → "Oracle is warming up" honest empty state.
+ 2. System: `GET /api/oracle/feed?...` renders conviction cards (0 to 100 score, tier pill prime/strong/lean/watch/avoid). Each card's "Oracle's take" quotes the coin's own evidence (up to two reason clauses served with the feed, each with its lift over the base rate; the pillar template survives only for rows cached before reasons shipped), an odds chip states what that score band has actually returned ("N% held 2x+", shown once the band has 100+ resolved coins), and an outcome chip (graduated ✓ / rugged ✕ / peak Nx) lands once the market resolves the coin. If backend not migrated → "Oracle is warming up" honest empty state.
3. System: opens SSE `EventSource('/api/oracle/action-stream')` — new scored coins stream in live; "Live · fused conviction" / "Reconnecting…" indicator.
4. (optional) Filter: click `#tierSeg` tier buttons / category select / min-score / sort seg / ★-watchlist-only toggle / breadth-bar tier segments → `syncFilterUrl()` + `loadFeed()` (URL is shareable). A hero "Join the live Telegram feed" button appears when `/api/oracle/stats` reports a configured public signals channel.
- 5. (optional) Switch view tab: `movers`, `wallets` (reputation leaderboard), `edge` (tier backtest win-rate), `proof` (resolved wins), `agents` (agent win-rate ledger), `activity` (live agent actions), `graph` (3D force graph, lazy-imports oracle-graph.js).
+ 5. (optional) Switch view tab: `movers`, `wallets` (reputation leaderboard), `edge` (tier backtest win-rate; the hero names the specific bands that invert the ladder instead of claiming calibration, states the fitted event's own hit rate (a 3x run or graduation) beside the stricter clean-win rate, and each calibration row shows "claims N%" next to the realized bar, with "n/a" for an unmeasured band), `proof` (resolved wins), `agents` (agent win-rate ledger), `activity` (live agent actions), `graph` (3D force graph, lazy-imports oracle-graph.js).
6. (optional) Click a coin card → `openDrawer(mint)` → `GET /api/oracle/coin?mint=...` renders the 4-pillar conviction breakdown (who/how/what/move); oracle-tape.js streams that coin's live trades.
7. (optional) In the drawer: Full page ↗ (`/oracle/coin/<mint>`), pump.fun ↗, GMGN ↗ (via `src/shared/trading-terminals.js`, referral-tagged), solscan ↗, Details ↗ (`/launches/<mint>`), View in 3D ↗ (`/coin3d?mint=`), ☆/★ Watch (writes `ld_watchlist`), Copy mint, Copy link, Share to X; the live Market panel adds GMGN/DexScreener/GeckoTerminal/Birdeye links when available.
8. (optional, agents view) Follow an agent's signals: expand follow-panel → enter Telegram chat ID → `POST /api/oracle/follow`.
- 9. **Arm payoff (gated):** open **Agent** tab → `loadAgentPanel()` → `GET /api/agents`. Pick agent, set Min conviction (Prime/Strong+/Lean+), Size/trade SOL, Max daily SOL, Max open, category filters, optional Telegram chat ID (Send test → server push), toggle Armed + Live/Simulate switches → **Save configuration** → `POST /api/oracle/watch` `{armed, mode, min_score, per_trade_sol, max_daily_sol, max_open, ...}`. Confirmation: "Armed in simulate/live mode. Your agent is watching the stream."
+ 9. **Arm payoff (gated):** open **Agent** tab → `loadAgentPanel()` → `GET /api/agents`. Pick agent, set Min conviction (Prime/Strong+/Lean+), Size/trade SOL, Max daily SOL, Max open, category filters, optional Telegram chat ID (Send test → server push), toggle Armed + Live/Simulate switches → **Save configuration** → `POST /api/oracle/watch` `{armed, mode, min_score, per_trade_sol, max_daily_sol, max_open, ...}`. Confirmation: "Armed in simulate/live mode. Your agent is watching the stream." Arming live is judged on the raw request, not the clamped values: a `per_trade_sol` below 0.001 SOL or a `max_daily_sol` below `per_trade_sol` answers 400 before any real-money loop starts (simulate keeps the forgiving clamps), and the GET side rejects a non-uuid `agent_id` with 400.
- **Decision points / branches:** view tabs (9); feed warming vs populated vs filtered-empty; drawer coin scored vs "not scored yet"; agent has wallet vs needs creation (`/create/studio`); simulate vs live mode; signed-out → "Sign in and arm an agent".
- **External calls / dependencies:** `/api/oracle/feed`, `/api/oracle/coin`, `/api/oracle/search`, `/api/oracle/movers`, `/api/oracle/categories`, `/api/oracle/backtest`, `/api/oracle/wins`, `/api/oracle/stats` (hero statline + Telegram channel link), `/api/oracle/activity`, `/api/oracle/watch` (GET+POST), `/api/oracle/follow` (GET+POST), `/api/agents`; SSE `/api/oracle/action-stream`; oracle-tape live trade stream in drawer.
- **Success state:** live conviction feed scoring every pump.fun launch in real time; coin drawer with pillar breakdown; armed agent acting on the stream (simulate logs / live spends capped SOL), actions graded into a win-rate ledger.
-- **Empty / error states:** "Oracle is warming up" (backend not live); "No launches clear your filters" + Reset; drawer "not scored"; "No ranked agents yet"; SSE auto-reconnects ("Reconnecting…"); `api()` returns `{ok:false}` on timeout (12s abort) and degrades gracefully.
+- **Empty / error states:** "Oracle is warming up" (backend not live); "No launches clear your filters" + Reset; drawer "not scored"; "No ranked agents yet"; SSE auto-reconnects ("Reconnecting…"); `api()` returns `{ok:false}` on timeout (12s abort) and degrades gracefully; during a database outage the oracle endpoints (stats, feed, coin, activity, backtest, categories, follow, batch) answer 503 with Retry-After instead of a confident empty record, so the page shows its warming/retry state rather than "0 scored, 0 armed".
- **Step count:** 3 required (arrive → feed → live stream, all automatic) + ~6 optional read interactions, + a 6-field gated arm flow (steps 8–9).
---
@@ -117978,7 +122753,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Prerequisites / gates:** None — public live monitor.
- **Steps (N):**
1. Arrive → inline module sets `API='/api/oracle/activity'`, `STREAM_API='/api/oracle/action-stream'`, loads first page.
- 2. System: `GET /api/oracle/activity?...` renders rows (agent, verb closed↑/↓/entered, $symbol, tier pill, sim/live tag, outcome win/loss/flat/open, PnL) + summary KPIs.
+ 2. System: `GET /api/oracle/activity?...` renders rows (agent, verb closed↑/↓/entered, $symbol, tier pill, sim/live tag, outcome win/loss/flat/open, PnL) + summary KPIs. The KPIs merge `/api/oracle/stats` with the 7-day rollup; a value the API does not carry prints "n/a" (never a dash or a fake zero), PnL (7d) stays "n/a" until a settled action carries a realized figure, and the win-rate tile is coloured against the market's own base rate rather than a fixed 50%.
3. System: opens SSE `/api/oracle/action-stream` — new agent actions prepend live.
4. (optional) Filter by tier chip, mode pill (sim/live), or outcome → re-fetch with `?tier=&mode=&outcome=`.
5. (optional) Load more (cursor pagination).
@@ -117986,7 +122761,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Decision points / branches:** filter combinations; win/open rows show Copy CTA, losses don't; stale badge + retry if a background refresh fails while rows are on screen.
- **External calls / dependencies:** `GET /api/oracle/activity`; SSE `/api/oracle/action-stream`.
- **Success state:** real-time trading floor of every agent's Oracle-driven move, outcomes graded, winners copyable.
-- **Empty / error states:** empty feed placeholder; stale/reconnect badge with manual retry button on background-refresh failure.
+- **Empty / error states:** empty feed placeholder; stale/reconnect badge with manual retry button on background-refresh failure; a stats outage renders the KPI tiles as "n/a" instead of leaving the skeleton shimmering.
- **Step count:** 2 required (arrive → feed+stream) + ~3 optional (filter, paginate, copy).
---
@@ -117996,15 +122771,15 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Entry point:** nav "Trending"; footer; share links.
- **Prerequisites / gates:** None — public dashboard.
- **Steps (N):**
- 1. Arrive → inline module binds tab buttons (Agents / Coins) + window buttons (24h / 7d / All time), loads default (Agents, 24h).
- 2. System: `GET /api/trending?window=24h&limit=10` renders ranked list (agents by real chat activity, with wallet chip; coins by Oracle conviction score).
- 3. (optional) Switch tab Agents↔Coins → renders the other ranked list.
- 4. (optional) Switch window 24h/7d/All time → re-fetch with new `window`.
- 5. (optional) Click a row → deep link to the agent profile or coin/oracle page.
-- **Decision points / branches:** Agents vs Coins tab; 3 time windows; per-tab retry button on fetch failure.
-- **External calls / dependencies:** `GET /api/trending?window=&limit=10`.
+ 1. Arrive → inline module binds tab buttons (Agents / Trusted / Coins; arrow keys move between them) + window buttons (24h / 7d / All time), honors a `?tab=` deep link and keeps it in the address bar with `pushState`, loads default (Agents, 24h).
+ 2. System: `GET /api/trending?window=24h&limit=10` renders ranked list (agents by real chat activity, with wallet chip; coins by Oracle conviction score among coins scored inside the selected window, or every retained coin for All time, with ties broken by momentum and smart-wallet count so the board does not reshuffle on reload).
+ 3. (optional) Switch tab Agents / Trusted / Coins → renders the other ranked list; Trusted reads `GET /api/reputation/leaderboard?limit=25`, an all-time wallet-trust score, so the window control hides on that tab.
+ 4. (optional) Switch window 24h/7d/All time → re-fetch with new `window`; the legends and the coin empty state name the window.
+ 5. (optional) Click a row → `/agents/<id>` for an agent, `/oracle/coin/<mint>` for a coin, `/agents/<id>/wallet#reputation` for a trusted row. The whole row is the link, so the wallet chip renders without its Tip button and popover (tipping lives on the agent page).
+- **Decision points / branches:** Agents / Trusted / Coins tab; 3 time windows; per-tab retry button on fetch failure.
+- **External calls / dependencies:** `GET /api/trending?window=&limit=10`; `GET /api/reputation/leaderboard?limit=25` (Trusted tab).
- **Success state:** what's hot right now — top agents and top conviction coins across windows.
-- **Empty / error states:** per-tab empty + Retry button (`#agentRetry` / `#coinRetry`).
+- **Empty / error states:** per-tab designed empty copy that names the window ("No agent chats in this window yet.", "No coins scored in the last 24 hours.") with a widen-the-window hint and a `/create` or `/oracle` link; per-tab error + Retry button (`#agentRetry` / `#coinRetry`). Server side, an unparseable `limit` falls back to 10 (max 20) instead of failing both rankings into a fake "nothing trending", and a ranking that does fail is logged before it degrades to empty.
- **Step count:** 2 required (arrive → list) + ~3 optional (tab, window, drill-in).
---
@@ -118016,15 +122791,15 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Steps (N):**
1. Arrive → `readUrl()` restores mint/tab/network (network persisted to localStorage `tf_network`); the deep-dive mounts immediately with the URL mint, or $THREE by default (never an empty void).
2. System: left rail loads the active tab: **Launches** (`GET /api/pump/launches?network=&limit=40`, $THREE pinned at the top) or **Exits** (`GET /api/trades/feed?network=&window=7d&min_pnl_pct=10&limit=40`); refreshes every 30s. Header pulse (`GET /api/pump/helius-stats`, 20s) shows network mint rate, graduations/hour, and SOL price ± 24h change.
- 3. System: centre deep-dive (`mountDetail`) paints header + skeleton instantly from the clicked row, then fills progressively from five live endpoints (`/api/pump/launch-detail`, `/api/pump/curve`, `/api/pump/intel`, `/api/pump/smart-money`, `/api/coin/:mint/cohorts`; cohorts only for platform-tracked coins) plus three self-fetching widgets: candlestick chart, bonding-curve ring, live trade tape.
+ 3. System: centre deep-dive (`mountDetail`) paints header + skeleton instantly from the clicked row, then fills progressively from five live endpoints (`/api/pump/launch-detail`, `/api/pump/curve`, `/api/pump/intel`, `/api/pump/smart-money`, `/api/coin/:mint/cohorts`; cohorts only for platform-tracked coins) plus three self-fetching widgets: candlestick chart, bonding-curve ring, live trade tape. A row clicked in the Exits tab carries its trade with it, so an "Agent exit" card (realized PnL, exit multiple, hold time, entry/exit SOL, exit reason, entry/exit tx links, the agent's `/agents/<id>` link and "Copy trader →" to `/trader/<id>`) paints with the shell, no second round-trip. The price strip reads a migrated coin as Graduated even when the curve account is closed, and swaps the SOL cell for a "Price source" cell (Jupiter / pump.fun curve) once there is no curve price to quote.
4. (optional) Switch tab Launches ↔ Exits (`#ttTabs`) → reload rail; URL synced.
5. (optional) Change network mainnet/devnet (`#ttNetwork`, persisted) → reload rail + remount deep-dive.
6. (optional) Paste a mint into `#ttSearch` (base58-validated) → drives the deep-dive for that coin.
7. (optional) Click any rail row → `select(mint)` remounts the deep-dive (re-selecting the mounted coin is a no-op); URL reflects `?mint=` for sharing.
-- **Decision points / branches:** Launches vs Exits tab; mainnet vs devnet; platform-tracked coin (cohorts fetched) vs external mint (designed no-data state); each detail section degrades independently to an honest "unavailable" note.
+- **Decision points / branches:** Launches vs Exits tab; mainnet vs devnet; platform-tracked coin (cohorts fetched) vs external mint (designed no-data state); each detail lane (curve / detail / intel / smart) degrades independently: a lane that threw says "Could not load this section. The request to three.ws failed." with its own ↻ Retry that reruns only that lane, while a coin the first-seconds indexer never observed gets designed not-indexed cards pointing at `/oracle/coin/<mint>`, Bubblemaps and Solscan instead of being blamed for an outage.
- **External calls / dependencies:** `GET /api/pump/launches`, `GET /api/trades/feed`, `GET /api/pump/helius-stats`, `GET /api/pump/launch-detail`, `GET /api/pump/curve`, `GET /api/pump/intel`, `GET /api/pump/smart-money`, `GET /api/coin/:mint/cohorts`.
- **Success state:** live two-pane terminal: rail of platform launches/exits, deep-dive with chart, bonding curve, holders/cohorts, funder bubblemap, smart money, wallet footprint, trade tape, outcome, agent economics; shareable `?mint=` URL.
-- **Empty / error states:** per-tab empty copy ("No launches on this network yet" / "No profitable agent exits in this window yet"); per-section "unavailable" degradation in the deep-dive; pulse failures silent (decorative).
+- **Empty / error states:** per-tab empty copy that stays visible under the pinned $THREE row ("No launches indexed on this network yet." / "No agent exit cleared the +10% bar in the last 7 days." with a "Browse launches" action; on devnet both offer "Switch to mainnet"); feed load failure ("Could not load the launch feed." / "Could not load the agent exit feed." + Retry) only on a cold load, since a failed 30s refresh leaves the rows already on screen alone; per-lane retryable failure and not-indexed states in the deep-dive; the trade tape says "Live trades are unavailable for this coin right now. Showing settled trades only." and drops its live lamp when PumpPortal refuses the subscription; pulse failures silent (decorative).
- **Step count:** 3 required (arrive → rail + deep-dive) + ~4 optional (tab, network, search, row select).
---
@@ -118075,15 +122850,15 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Steps (N):**
1. (prerequisite) On any coin surface (oracle/radar/trades/launches/etc.) click ☆ Watch → mint stored in `ld_watchlist`.
2. Arrive on `/watchlist` → `readList()` reads + validates mints (base58 32–44).
- 3. System: for each mint mounts a live coin-status card (`mountCoinStatus` → one `/api/pump/coin` fetch/coin), with deterministic mint identicon placeholder behind real pump.fun logo; refreshes every 90s.
- 4. System: detects tier upgrades vs `wl_last_tiers` and surfaces changes.
+ 3. System: for each mint mounts a live coin-status card (`mountCoinStatus` → one `/api/pump/coin` fetch/coin), with deterministic mint identicon placeholder behind real pump.fun logo; refreshes every 90s. A parallel `GET /api/oracle/batch?mints=` sweep (chunks of 20) paints a conviction badge per card; a mint the Oracle answered for but has not scored gets an "unrated" badge linking to `/oracle/coin/<mint>`, and a chunk that failed leaves its cards' badges untouched rather than calling them unscored.
+ 4. System: detects tier upgrades vs `wl_last_tiers` and surfaces changes. The summary tiles (market cap, 24h volume, graduated, average conviction) aggregate only the coins that actually report each figure, with a hover note giving the coverage ("Combined across 3 of 5 watched coins"), and the tier bar carries a muted "not scored yet" segment for the remainder so the distribution never implies an opinion the Oracle has not given.
5. (optional) Toggle alerts (`#wl-alerts`, `wl_alerts_on`).
6. (optional) Clear list (`#wl-clear`).
7. (optional) Click a card → the coin's Oracle page (`/oracle/coin/<mint>`).
- **Decision points / branches:** empty list vs populated; tier-upgrade highlighting; alerts on/off; cross-tab storage sync.
-- **External calls / dependencies:** `GET /api/pump/coin` (one per watched coin, via coin-status-card).
+- **External calls / dependencies:** `GET /api/pump/coin` (one per watched coin, via coin-status-card); `GET /api/oracle/batch?mints=&network=mainnet` (conviction badges, chunks of 20).
- **Success state:** private tracked-coin board with live status cards, tier-change detection, deep links back to profiles.
-- **Empty / error states:** empty state when no mints saved (tells user to Watch coins elsewhere); invalid mints filtered out; per-card load handled by coin-status widget.
+- **Empty / error states:** empty state when no mints saved (tells user to Watch coins elsewhere); invalid mints filtered out; per-card load handled by coin-status widget; a summary tile shows the no-value dash rather than a fabricated $0 when no coin reports the figure, and the tier bar reads "Awaiting Oracle scores" or "Oracle unreachable" when nothing is scored.
- **Step count:** 1 required to view (arrive) — payoff depends on the prerequisite Watch action elsewhere; + ~3 optional (alerts, clear, drill-in).
---
@@ -118104,9 +122879,9 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
9. (optional) **Alerts**: build a rule (type/scope/threshold/agent + in-app/webhook/Telegram delivery + cooldown) → `POST /api/alerts/rules`; list/toggle/edit/delete; live firing against feed; history from `GET /api/notifications`.
10. (optional) **Vanity Generator payoff:** enter prefix/suffix → `validatePattern()` (base58, ≤6 chars) → `grindVanity()` spawns up to 8 Web Workers (WASM) → progress (tries/rate/eta) → match → reveal/copy/download keypair JSON (secret never leaves browser).
11. (optional) **Default Agent**: embed `/agent-embed.html` iframe, speak/gesture via postMessage; manage custom agents (`GET /api/agents`, delete with CSRF).
- 12. (optional) **Revenue**, **Configuration** (save + reconnect + probes), **API Reference** (create/revoke keys).
-- **Decision points / branches:** 12 hash-routed tabs; wallet connected vs empty; WS backoff (<8 retry vs ≥8 terminal banner); auth 401 on agents/alerts/keys; PumpKit backend present for Watches/Claims; vanity validation failures; simulate vs server-side alert delivery.
-- **External calls / dependencies:** `/api/healthz`, `/api/pump/helius-stats`, `/api/pump/channel-feed`, `/api/pump/trending`, `/api/agents/featured`, `/api/agents` (+CSRF), `/api/wallet/balances`, `/api/pump/scan`, `/api/pump/quote/{buy,sell}`, `/api/alerts/rules` (CRUD), `/api/notifications`, `/api/api-keys` (CRUD), revenue endpoints; `wss://pumpportal.fun/api/data`; Solana RPC via `/api/solana-rpc`; Phantom/MWA wallet; Web Workers for vanity; model-viewer CDN.
+ 12. (optional) **Configuration** (save + reconnect + probes), **API Reference** (create/revoke keys). The Revenue tab and its reporting endpoints were retired from this page on 2026-08-25.
+- **Decision points / branches:** 11 hash-routed tabs (dashboard, feed, watches, claims, alerts, scanner, quoting, vanity, animations, config, api); wallet connected vs empty; WS backoff (<8 retry vs ≥8 terminal banner); auth 401 on agents/alerts/keys; PumpKit backend present for Watches/Claims; vanity validation failures; simulate vs server-side alert delivery.
+- **External calls / dependencies:** `/api/healthz`, `/api/pump/helius-stats`, `/api/pump/channel-feed`, `/api/pump/trending`, `/api/agents/featured`, `/api/agents` (+CSRF), `/api/wallet/balances`, `/api/pump/scan`, `/api/pump/quote/{buy,sell}`, `/api/alerts/rules` (CRUD), `/api/notifications`, `/api/api-keys` (CRUD); `wss://pumpportal.fun/api/data`; Solana RPC via `/api/solana-rpc`; Phantom/MWA wallet; Web Workers for vanity; model-viewer CDN.
- **Success state:** green API/WS/SOL chips, populated panels, live feed streaming, optional wallet snapshot, working alerts, vanity address found with copy/download.
- **Empty / error states:** featured-agent retry; WS "Realtime feed stopped" + Reconnect after 8 fails; channel-feed retry (downgrades to WS); RPC error chip auto-clears 8s; sign-in prompts on 401; vanity validation toasts; designed empty states for wallet/agents/alerts/feed (state-kit).
- **Step count:** 3 required (arrive → API/WS connect → panels populate) + ~9 optional tab/interaction flows (vanity grind and alert-rule build are the headline interactive payoffs).
@@ -118141,14 +122916,14 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Steps (N):**
1. Arrive → inline module reads `ld_watchlist`, renders 6 skeletons, calls `refresh()`; auto-refresh every 20s (pauses when tab hidden).
2. System: `GET /api/pump/smart-money?limit=60` (feed: coins ranked by smart_money_score, proven-wallet count, smart buy volume) + parallel `?leaderboard=1&limit=60` (top wallets by reputation).
- 3. (optional) Switch tab Feed ↔ Top wallets.
+ 3. (optional) Switch view: Feed ("Smart money is buying", with On radar / Graduated / All filters) / Top wallets / Watchlist; the Watchlist view looks up each `ld_watchlist` mint with `?mint=`.
4. (optional) Watch toggle per coin → `ld_watchlist`.
5. (optional) Click coin → drawer `GET /api/pump/smart-money?mint=<mint>` (notable wallets, labels) + async `GET /api/oracle/coin?mint=` to enrich with conviction pillars.
6. (optional) Click wallet → drawer `GET /api/pump/smart-money?wallet=<addr>` (win rate, record, recent coins).
- **Decision points / branches:** Feed vs wallets tab; coin scored vs "not scored"; wallet has record vs none; Oracle enrichment present vs absent.
- **External calls / dependencies:** `GET /api/pump/smart-money` (feed / `?leaderboard=1` / `?mint=` / `?wallet=`), async `GET /api/oracle/coin`. Data sourced from `coin_smart_money` + `wallet_reputation` tables fed by the off-browser sniper engine — no direct browser RPC/WS.
- **Success state:** 60 fresh coins ranked by buyer pedigree; wallet reputation board (smart_money/sniper/dumper/rugger labels); coin + wallet drawers.
-- **Empty / error states:** "No proven money on a fresh coin yet"; "No wallets ranked yet"; drawer "Not scored yet" / "No track record yet"; "Couldn't reach the radar" + Retry; stale badge with last-update + "Retry now".
+- **Empty / error states:** "No proven money on a fresh coin yet"; "No wallets ranked yet"; drawer "Not scored yet" / "No track record yet"; "Couldn't reach the radar" + Retry; stale badge with last-update + "Retry now". A cold failure (nothing cached yet) paints "Couldn't reach the radar" with Retry on both the feed and the Top wallets view and says whether the API answered a status or was unreachable from the browser; the drawers show the explanatory "Not scored yet" (with a pump.fun link) / "No track record yet" (with a Solscan link) only when the radar answered, and offer Retry when it did not; on the Watchlist view a coin the radar could not be reached for reads "Couldn't load this one" with Retry rather than "Not on the radar yet", and if every lookup was unreachable one message covers the whole list.
- **Step count:** 1 required (arrive → feed) + ~5 optional (tab, watch, inspect coin/wallet).
---
@@ -118167,7 +122942,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
- **Decision points / branches:** 4 tabs; filter combinations; coin observed vs "not observed"; labeled winners vs none; ≥50 labeled coins for trained weights vs baseline; Oracle enrichment present vs absent.
- **External calls / dependencies:** `GET /api/pump/intel` (`view=feed|leaderboard|traders|learning`, `?mint=`), async `GET /api/oracle/coin`. Data from `pump_coin_intel`, `pump_coin_outcomes`, `pump_coin_wallets`, `pump_intel_weights` (off-browser engine). No direct browser RPC/WS.
- **Success state:** live classified-coin radar with verdicts + risk flags; leaderboard of best coins + confirmed winners (ATH multiple); cross-coin trader board; "what it learned" signal-weight transparency; per-coin bubble-map drawer.
-- **Empty / error states:** "The engine is warming up"; "No coins match these filters" + Reset; drawer "Not observed yet"; "No labeled winners yet"; "No traders recorded yet"; "Not enough data to train yet"; degraded badge; retry on network failure.
+- **Empty / error states:** "The engine is warming up"; "No coins match these filters" + Reset; drawer "Not observed yet"; "No labeled winners yet"; "No traders recorded yet"; "Not enough data to train yet"; degraded badge; retry on network failure. The leaderboard's own empty state reads "Nothing scored in the last 24 hours" (the radar's "loosen your filters" copy no longer appears on a tab with no filters); every failed tab (radar, both leaderboard rails, traders, all three learning panels, the drawer) carries its own Retry, and the header stat tiles fall back to dashes beside the amber degraded pulse rather than disappearing.
- **Step count:** 2 required (arrive → radar feed) + ~6 optional (search/filters, watch, tabs, inspect coin).
---
@@ -118254,21 +123029,21 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
---
### Constellation — `/constellation`
-- **Source:** `pages/constellation.html`, `src/constellation/main.js` (~500 lines), `src/constellation/embedding.js` (PCA/MDS + neighbor lookup)
+- **Source:** `pages/constellation.html`, `src/constellation/main.js` (~790 lines), `src/constellation/embedding.js` (PCA/MDS + neighbor lookup)
- **Entry point:** nav / direct URL.
-- **Prerequisites / gates:** None — public. WebGL required (fatal overlay if absent, no fallback). IBM Granite (watsonx) optional — without it, tokens place by rank instead of semantic space.
+- **Prerequisites / gates:** The galaxy, its live stats and its semantic layout are public; the per-star Granite analysis needs a signed-in account (it runs on the platform's own model keys), so `GET /api/auth/me` is resolved once at boot and a signed-out visitor gets a sign-in / create-account notice in the panel instead of a doomed request. WebGL required (fatal overlay if absent, no fallback). IBM Granite (watsonx) optional: without it, tokens place by rank instead of semantic space.
- **Steps (N):**
1. Arrive → boot WebGLRenderer + Three.js scene (camera, starfield, auto-rotate OrbitControls); fatal overlay if WebGL missing.
2. System: `GET /api/pump/trending?limit=64` → ≥3 valid tokens placed on a Fibonacci sphere (rank layout), colored by hue; loading overlay dismisses.
- 3. System (optional/semantic): `POST /api/watsonx/embed` → 1024-d vectors → PCA to 3 axes → nodes lerp from rank positions into semantic clusters; status "Embedded by IBM Granite · model · 1024d".
+ 3. System (optional/semantic): `POST /api/watsonx/embed` → 1024-d vectors → PCA to 3 axes → nodes lerp from rank positions into semantic clusters; the status names the model that actually produced the vectors: "Embedded by IBM Granite · model · 1024d", or a "Semantic layout live · <fallback embedder>" line when the embed endpoint fell through its failover chain, never a Granite credit for another model's output.
4. (optional) Drag to orbit / scroll to zoom.
- 5. (optional) Hover star → glow + tooltip (symbol/name).
- 6. (optional) Click star → right detail panel (symbol, name, logo, price, rank, nearest semantic neighbors, Pump.fun/Solscan links).
- 7. (optional) **Analysis payoff:** click "Analysis by IBM Granite" → `POST /api/brain/chat {provider:'ibm-granite', system: analyst, messages, maxTokens:400}` (SSE) → streams a live token analysis into the panel; Esc/close to dismiss.
-- **Decision points / branches:** WebGL present vs fatal; Granite configured (semantic layout + analysis) vs unconfigured (rank layout, analysis notice); rate-limited; <3 tokens → fatal.
-- **External calls / dependencies:** `GET /api/pump/trending?limit=64`; `POST /api/watsonx/embed`; `POST /api/brain/chat` (SSE).
+ 5. (optional) Hover star → glow + tooltip (symbol/name). The canvas is focusable: arrow keys walk the stars in trending-rank order with the tooltip following, Home/End jump to the ends, and Enter/Space opens the focused star. Picking tolerates a near miss (22px, 34px on a coarse pointer; a tap gets 46/60px and is judged on movement, not hold time) so the visible glow is the target.
+ 6. (optional) Click star → right detail panel (symbol, name, logo, market cap, price when the feed carries one, rank, nearest semantic neighbors once vectors land, Pump.fun/Solscan links); the panel is `inert` while closed and hands focus back to the canvas after a keyboard open.
+ 7. (optional) **Analysis payoff:** selecting a star fires `POST /api/brain/chat {provider:'ibm-granite', system: analyst, messages, maxTokens:400}` (SSE) → streams a live token analysis into the panel; Esc/close to dismiss. The byline names what actually answered: the `meta` event's model label, or after a `fallback` event "Analysis by <route>" with a meta line saying Granite could not serve the request.
+- **Decision points / branches:** WebGL present vs fatal; signed in (analysis streams) vs signed out (sign-in notice); Granite configured (semantic layout + analysis) vs unconfigured (rank layout, analysis notice) vs served by a fallback (labelled as such); rate-limited; <3 tokens → fatal.
+- **External calls / dependencies:** `GET /api/pump/trending?limit=64`; `GET /api/auth/me`; `POST /api/watsonx/embed`; `POST /api/brain/chat` (SSE).
- **Success state:** 64-star galaxy clustered by semantic similarity, hover tooltips, detail panel, and streaming Granite analysis per token.
-- **Empty / error states:** WebGL fatal overlay; "No trending tokens right now"; "Semantic layout off — IBM Granite isn't configured… placing by rank"; analysis notices (unconfigured / rate-limited / stream error); trending-fetch failure message.
+- **Empty / error states:** WebGL fatal overlay; a feed failure ("Couldn't load live tokens.", naming the pump.fun trending feed) and "No trending tokens right now." both carry a "Try again" button that rebuilds the galaxy (disposing the previous nodes' materials); a semantic-layout-off status when IBM watsonx is not configured (stars placed by trending rank); analysis notices (sign in required / unconfigured / rate-limited / every route refused / stream error), each telling the visitor to pick the star again to retry.
- **Step count:** 2 required (arrive → galaxy renders) + ~5 optional (orbit/zoom, hover, select, Granite analysis). Live-data exploration + AI analysis.
---
@@ -118303,14 +123078,14 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
2. System: `loadAgent(id)` → `GET /api/agents/:id` names the co-pilot and labels it "Your alpha co-pilot" for the owner or "Alpha co-pilot · public read" for everyone else; the `<agent-3d>` avatar mounts from `agentAvatarGlb()`.
3. System: `loadCandidates()` → `GET /api/agents/:id/alpha/candidates?network=mainnet` renders the live pump.fun launch rail behind 4 skeleton cards, counts up the launch total, and marks one "top pick" ranked by real smart-money + quality signals with a penalty for a sybil-dominated funder graph.
4. **Read payoff:** click a launch (or arrive with `?mint=`) → `POST /api/agents/:id/alpha/read {mint, network}` → thinking state, then a verdict (Snipe / Watch / Pass), a conviction bar that fills from 0, the spoken line, "What could go wrong" risks, and the eight grounded signal rows (liquidity, market cap, age, buy impact at 0.1 SOL, curve filled, quality, smart money + wallet count, organic), with the rows the agent actually cited highlighted.
- 5. System: the avatar speaks the verdict: `POST /api/tts/eleven` when the agent has a voice, else `POST /api/tts/speak`, else the browser `speechSynthesis` fallback. If the server's hallucination guard replaced a figure, the panel says so and points at the signals as ground truth.
+ 5. System: the avatar speaks the verdict: `POST /api/tts/eleven` (with `agentId`, so an owner-cloned voice is served on the owner's saved ElevenLabs key) when the agent has a voice, else `POST /api/tts/speak`, else the browser `speechSynthesis` fallback. If the server's hallucination guard replaced a figure, the panel says so and points at the signals as ground truth.
6. (optional) Owner extras in the read: the wallet line shows balance, per-trade limit, daily budget, and a paused flag.
- 7. (optional) **Act payoff (owner, gated):** click "Act, buy N SOL" → drawer opens → `previewAgentTrade()` fetches a fresh live quote (you pay / expected tokens / price impact, plus any warning) → **Confirm buy** → `executeAgentTrade()` posts through the guarded agent wallet path (spend limits and firewall re-checked at submit, written to the custody audit) → done state with the Solscan tx, the new wallet balance, and a link to the custody trail.
+ 7. (optional) **Act payoff (owner, gated):** click "Act: buy ◎N" → drawer opens (focus moves inside and returns to the trigger on close) → `previewAgentTrade()` fetches a fresh live quote (you pay / expected tokens / price impact, plus any warning) → **Confirm buy** → `executeAgentTrade()` posts through the guarded agent wallet path (spend limits and firewall re-checked at submit, written to the custody audit) → done state with the Solscan tx, the new wallet balance, and a link to the custody trail.
8. (optional) Replay the last spoken line; refresh the launch rail; paste a different agent ID or profile URL; pick another agent from the public gallery.
- **Decision points / branches:** owner vs public read (act button vs gate message); `gate.can_act` true vs blocked with a reason; agent resolved from URL / storage / session / featured vs none at all (the gallery becomes the call to action, and only if the gallery is empty does the ID row open); ElevenLabs voice vs server TTS vs browser speech; hallucination guard triggered vs clean; reduced motion (bars and counters land at their final values).
- **External calls / dependencies:** `GET /api/agents/:id`, `GET /api/agents/me`, `GET /api/agents/featured`, `GET /api/agents/public?sort=popular&limit=12`, `GET /api/agents/:id/alpha/candidates`, `POST /api/agents/:id/alpha/read`, `POST /api/tts/eleven`, `POST /api/tts/speak`; `previewAgentTrade` / `executeAgentTrade` (`POST /api/agents/:id/solana/trade`) for the act path.
- **Success state:** a named 3D agent reads a real launch aloud in character, shows the live signals behind the call, and the owner can act on it through the same guarded, audited wallet path the conversational copilot uses. The narrator itself never moves funds.
-- **Empty / error states:** "No live launches on the feed this second" with "Check again"; "Live feed hiccup" with Retry; read failure with "Try again"; "Couldn't fetch a live quote"; trade errors rendered above the confirm button with the button re-enabled; no-agent fallback copy on the avatar placeholder.
+- **Empty / error states:** "No live launches on the feed this second" with "Check again"; "Live feed hiccup" with Retry; read failure with "Try again"; "Couldn't fetch a live quote"; trade errors rendered above the confirm button with the button re-enabled; no-agent fallback copy on the avatar placeholder. The launches column never renders as an empty box: before an agent is on stage it reads "Pick a co-pilot above and the live launches it can read land here." (or the ID-entry variant when the gallery is empty), and an agent that fails to load clears the previous one off the stage rather than leaving its launch cards wired to nothing.
- **Step count:** 3 required (arrive → agent + launch rail → read) + ~5 optional, including the owner-gated buy (steps 7 to 8).
---
@@ -118324,7 +123099,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up
---
-<a id="sec-511"></a>
+<a id="sec-531"></a>
> **Source:** `docs/ux-flows/08-coin-launch-wallets.md` · [↑ table of contents](#table-of-contents)
@@ -118378,7 +123153,7 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
- Wallet source: connected (client-grinds mark, client-signs) vs. agent (server-grinds, server-signs).
- Connected path may require a one-time SIWS link, and a link may hit a takeover branch.
- Confirmation timeout → escape-hatch screen ("Finalize once confirmed" re-checks signature status, "Start over").
-- **External calls / dependencies:** `/api/auth/me`, `/api/avatars`, `/api/pump/by-agent`, `/api/auth/wallets`, `/api/auth/wallets/nonce-solana`, `/api/auth/wallets/link-solana`, `/api/pump/agent-wallet`, `/api/pump/build-metadata`, `/api/pump/launch-prep`, `/api/pump/launch-confirm`, `/api/pump/launch-agent`, `/api/native-launch/config`, `/api/native-launch/launch-prep`, `/api/native-launch/launch-confirm`, `/api/solana-rpc` (Connection RPC). External: `esm.sh/@solana/[email protected]`, `esm.sh/[email protected]`, pump.fun (mint target), Solscan (links).
+- **External calls / dependencies:** `/api/auth/me`, `/api/avatars`, `/api/pump/by-agent`, `/api/auth/wallets`, `/api/auth/wallets/nonce-solana`, `/api/auth/wallets/link-solana`, `/api/pump/agent-wallet`, `/api/pump/build-metadata`, `/api/pump/launch-prep`, `/api/pump/launch-confirm`, `/api/pump/launch-agent`, `/api/native-launch/config`, `/api/native-launch/launch-prep`, `/api/native-launch/launch-confirm`, `/api/solana-rpc` (Connection RPC). External: `@solana/[email protected]` and `[email protected]`, both loaded through `/load-module.js` (the pinned version on esm.sh, then jsdelivr, then unpkg, each under a deadline; if all three miss the panel says "<what> could not be loaded (<hosts> unreachable or blocked). Check your connection or ad blocker and try again."; `fees-panel.js` loads web3.js the same way), pump.fun (mint target), Solscan (links).
- **Success state:** `lp-ok` card — stamped mint, verified badge, pump.fun/Solscan/agent-page links, share-announcement copy, relaunch button. The coin appears in `/launches` within 60s via live refresh.
- **Empty / error states:** signed-out / no-avatar guided onboarding (4-step explainer + coin-type legend + cost note); "Checking for existing token…"; per-phase `lp-phase` status line; `friendlyError()` maps rejections/insufficient SOL/no-wallet/rate-limit to plain copy; confirmation-timeout escape hatch; agent-wallet error/retry/provision states; insufficient-balance "Fund" CTA.
- **Step count:** 15 required (+5 optional)
@@ -118408,21 +123183,21 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
### Claim Wallet (Trader Card) — `/claim-wallet`
- **Source:** `pages/claim-wallet.html` → `src/claim-wallet.js`.
-- **Entry point:** `#cwInput` address field + `#cwBtn` Preview; results render in `#cwResult`.
+- **Entry point:** `#cwInput` address field + `#cwBtn` **Analyze**; results render in `#cwResult` (a polite live region).
- **Prerequisites / gates:** Preview is public. Claiming requires sign-in AND control of the keypair (SIWS signature). The claimed wallet must equal the connected wallet.
- **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 60 recent pump.fun coins.
+ 3. Click **Analyze** (button reads "Analyzing…" and is held by the page while busy so a late-landing locale catalog cannot overwrite it) → `GET /api/traders/preview?wallet=` (in parallel with a SOL price read) → skeleton, then the Trader Card: label, KPI row (win rate, early-entry win rate, smart-money score, net PnL, dump rate; the reputation rates arrive already in percentage points and are printed as-is), a 7D / 30D / ALL time-window toggle, and a **Trade ledger** of up to 60 recent pump.fun coins with sortable columns, filter chips (Hide dust, on by default / Open only / Created), a header that reads "N of M coins · window", and a per-row link to `/launches/<mint>`.
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."
+ 8. On success, re-read linked wallets (force) and re-render in the claimed state; message "Claimed" (or "Moved to your account" after a takeover) followed by "your Trader Card is live."
- **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.
+- **Empty / error states:** invalid-address inline error (`role=alert`); a dead or non-OK fetch → an error card in the results area with the server's message (or a connection explanation) and a **Try again** button, never a blank page; "Wallet not yet indexed" not-found state; an empty ledger explains itself ("No pump.fun trades from this wallet in the last 7/30 days" with **Widen to all-time →**; a wallet the brain has graded but whose per-coin rows are still being indexed says so; "No indexed pump.fun trades for this wallet yet"); filters that exclude every row → "None of this window's N coins match the active filters" + **Clear filters**; signature-cancelled message; per-step error toasts on the claim button.
- **Step count:** 8 required (claim path; preview alone is 3)
---
@@ -118439,11 +123214,11 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
5. On hit → result card: highlighted address, attempts/duration/rate stats, **Download keypair (Solana CLI JSON)**, **Copy public key**, and a "save before leaving" warning.
6. (optional) **Assign to an agent**: `GET /api/agents`. If 401 → sign-in prompt; if none → create-agent prompt; else select an agent + check the custody-ack box.
7. (optional, assign) If the agent already has a wallet, the flow switches to "Replace" — `DELETE /api/agents/:id/solana` first, then `POST /api/agents/:id/solana` with `secret_key` (array) + `vanity_prefix`/`vanity_suffix`. 409 handled. Success confirms "encrypted server-side" custody transfer.
- 8. (optional) **Send a sealed gift** (`sealed-drops.js`): compose a funded wallet drop (asset/amount, optional vanity pattern reusing the page's grind fields, seal mode "Bearer link" vs direct X25519 key, message/theme, expiry, optional reclaim address) → pays the x402 create fee → shareable `/drop/:id` link + QR + OG card. The recipient's claim page opens the ECIES sealed envelope entirely client-side (claim key rides the URL fragment in bearer mode), then offers import / download / sweep; three.ws never sees the plaintext key. "Gifts you've sent from this browser" lists sent drops with reclaim for expired ones.
+ 8. (optional) **Send a sealed gift** (`sealed-drops.js`): the form first reads the drop config from `/api/vanity/drops` and applies it (the asset list is narrowed to what the funding wallet supports, the expiry field takes the server's min / max / default hours, and the hint states the create fee, or explains that sealed drops are unavailable when no funding wallet is configured); then compose a funded wallet drop (asset/amount, optional vanity pattern with its own "Starts with" / "Ends with" fields, seal mode "Bearer link" vs direct X25519 key, message/theme, expiry, optional reclaim address) → pays the x402 create fee → shareable `/drop/:id` link + QR + OG card. The recipient's claim page opens the ECIES sealed envelope entirely client-side (claim key rides the URL fragment in bearer mode), then offers import / download / sweep; three.ws never sees the plaintext key. "Gifts you've sent from this browser" lists sent drops with reclaim for expired ones.
- **Decision points / branches:** prefix vs suffix vs both; case-sensitive vs insensitive; assign vs keep self-custody; replace-existing-wallet branch; gift seal mode bearer vs direct-key; gift claimed vs expired (reclaim).
- **External calls / dependencies:** None for grinding (client-side WASM ed25519 workers). Assign: `/api/agents`, `/api/agents/:id/solana` (POST + DELETE). Gifts: `/api/vanity/drops` (+ x402 create fee, on-chain funding/reclaim server-side).
- **Success state:** vanity address found + downloadable keypair; optionally "Assigned to <agent>" with an open-agent link.
-- **Empty / error states:** invalid-Base58 preview; combined-length-over-max warning; grind-failed error; assign 401/empty/409/network errors each handled inline.
+- **Empty / error states:** invalid-Base58 preview; combined-length-over-max warning; grind-failed error; assign 401 (sign-in link to `/login?next=/vanity-wallet`) / empty / 409 handled inline; an agent-list load failure says "Could not load your agents (…). Your wallet above is unaffected: download it now, then retry." with a **Retry** button, since only the assignment step is lost; sealed drops disabled when the funding wallet is not configured.
- **Step count:** 3 required (+4 optional)
---
@@ -118497,7 +123272,7 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
5. `POST` bridge `?pay=1` (SSE, `accept: text/event-stream`) streams stages: `challenge` (402) → `signing` (agent wallet signs the SPL USDC transfer) → `signed`/`submitting` (X-PAYMENT submitted, facilitator settles) → `done` (settled on Solana mainnet). Board, kiosk, and side-panel stepper animate in lockstep.
6. On `done` → receipt: amount, payer (agent wallet) → payTo (endpoint), Solscan tx link, and the purchased crypto-intel payload (signal/headline/rationale). Avatar plays a celebrate emote, then walks home. Status refreshes; session total accrues.
- **Decision points / branches:** local dev bridge vs hosted prod bridge (different URL shapes + auth model); `?bridge=`/`?endpoint=` overrides; 401 needs-auth vs 429 rate-limit vs generic failure; bridge online/offline/connecting.
-- **External calls / dependencies:** bridge `status`/`quote`/`pay` (`/api/agent-wallet-bridge` or local `:4402`); the paid endpoint `https://three.ws/api/x402/crypto-intel`; Solana mainnet settlement via the x402 facilitator; Solscan (tx link). External payment is **real** ($0.01 USDC leaves the wallet).
+- **External calls / dependencies:** bridge `status`/`quote`/`pay` (`/api/agent-wallet-bridge` or local `:4402`); the paid endpoint `https://three.ws/api/x402/crypto-intel` (the hosted bridge calls it through the shared upstream fetch: the 402 probe is bounded and retried on a dropped connection, while the re-send that carries the signed payment is a single attempt with a timeout only, because a retry could double-spend); Solana mainnet settlement via the x402 facilitator; Solscan (tx link). External payment is **real** ($0.01 USDC leaves the wallet).
- **Success state:** "✓ $0.01 USDC settled on Solana" board + receipt card with tx link and purchased intel; avatar celebrates.
- **Empty / error states:** "Bridge offline" banner (dev hint to run the bridge) with Retry; low-balance banner; "Sign in to pay" (needs-auth); rate-limit message; "Payment failed — no funds moved" with the stepper marking the failed stage red.
- **Step count:** 6 required (+1 optional)
@@ -118512,31 +123287,31 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
1. Boot configures the avatar iframe (`?id=`/`?handle=`/`?model=`, transparent bg, overlay mode) and posts a `v1.avatar.hello`; queued speech/gestures flush on `v1.avatar.ready` (or a 5s resilience timeout).
2. `refreshWallet()` → `GET /api/agent/wallet` → renders balance (SOL + USD), network badge, short address + explorer link. The API reports an unreadable balance as `balanceAvailable: false` instead of failing the response, so an RPC blip shows "balance unavailable" while the address + explorer link survive.
3. A "Fund your wallet" hint appears when the live balance can't cover a $1 send + fee buffer; user can copy the deposit address. An unknown balance never triggers the hint (unreachable RPC ≠ empty wallet).
- 4. User chats; `ask()` streams an assistant reply, the avatar speaks/gestures, and the model may emit actions.
+ 4. User chats; `ask()` streams an assistant reply, the avatar speaks/gestures, and the model may emit actions. A turn that fails is not a dead sentence: the bot bubble is marked errored with the reason (the server's `error_description`, or "I couldn't reach my brain. Check your connection and try again." when the fetch itself died) and carries a **Try again** button that re-sends the same message.
5. On a `sendSol` action → a payment card renders ("Signing & broadcasting…"); `POST /api/agent/send-sol` with `{ usd, to? }`.
6. On success → card flips to "Confirmed on-chain" with SOL amount, recipient, and a Solscan signature link; the avatar celebrates and the wallet refreshes.
7. If a send was held server-side, a governance chip explains the IBM Granite Guardian block (the action is already stripped from the stream — client never gates).
- **Decision points / branches:** avatar-source param (id/handle/model); send governance allowed vs blocked; send success vs fail; optional shared-secret token.
- **External calls / dependencies:** `/api/agent/wallet`, `/api/agent/send-sol`, the chat/stream endpoint, `/avatar-embed.html`; Solscan (links). Real on-chain SOL transfer on success.
- **Success state:** "Confirmed on-chain" payment card with signature link; avatar verbal + gesture confirmation.
-- **Empty / error states:** "balance unavailable" chip (with fund hint suppressed) when the RPC is unreachable; fund-hint / low-balance states; payment-failed card + toast + avatar "didn't go through"; governance-blocked chip.
+- **Empty / error states:** "balance unavailable" chip (with fund hint suppressed) when the RPC is unreachable; fund-hint / low-balance states ("Only X SOL, not enough to cover a $1 send plus fees. Top it up at the address below."); errored chat bubble with **Try again**; payment-failed card + toast + avatar "didn't go through"; governance-blocked chip ("Send held by IBM Granite Guardian: <reason>").
- **Step count:** 6 required (+1 optional)
---
### threews.sol Name Claim (SNS subdomain) — `/threews/claim`
- **Source:** route `/threews/claim` → `pages/threews-claim.html` (self-contained inline module). Pay-by-name plumbing: `src/sns/pay-by-name.js`. Surfaced from the profile page's "Claim <username>.threews.sol" wallet pill (`pages/profile.html`).
-- **Entry point:** `#tw-label` label input + `#tw-mint` Mint button; `#tw-status` availability line; `#tw-result`.
-- **Prerequisites / gates:** Sign-in required to mint (CSRF token from `/api/csrf-token`; "not signed in" if absent). Minting an on-chain SNS subdomain under `*.threews.sol`.
+- **Entry point:** an **account card** (`#tw-account`, polite live region, skeleton while loading) above the mint card; `#tw-label` label input + `#tw-mint` Mint button; `#tw-status` availability line; `#tw-result`.
+- **Prerequisites / gates:** Sign-in required to mint (CSRF token from `/api/csrf-token`); the label is the account's username, so a username must be set and must be a valid `.sol` label (a-z, 0-9, hyphens, not starting or ending with a hyphen). Minting an on-chain SNS subdomain under `*.threews.sol`.
- **Steps (N):**
- 1. User types a label; input is lowercased and stripped to `[a-z0-9-]`. Debounced 350ms availability check.
- 2. `GET /api/threews/subdomain?label=` → shows "<full> is available" (enables Mint) or "claimed by @user / owned by <addr>".
- 3. User clicks **Mint** → `getCsrf()` (`GET /api/csrf-token`) → `POST /api/threews/subdomain` with `{ label }` + `x-csrf-token`.
- 4. On success → "<full> minted" with the showcase URL and a Solscan tx link for the on-chain mint signature.
-- **Decision points / branches:** available vs taken; label must equal the account's username (the server 409s `username_mismatch` otherwise, and requires a username to be set); signed-in vs not; optional `owner_wallet` must be a Solana wallet already linked to the account.
-- **External calls / dependencies:** `/api/threews/subdomain` (GET check + POST mint), `/api/csrf-token`; Solscan (tx link). On-chain SNS mint.
-- **Success state:** Minted name card with showcase URL + tx signature link.
-- **Empty / error states:** "Type a label to check"; availability "bad" state for taken names; mint-failed (re-enables button); not-signed-in CSRF failure.
+ 1. Boot checks the session (`GET /api/auth/me`, skipped for anonymous visitors so the 401 never logs) then `GET /api/threews/me` and renders the account card: anonymous → "Sign in to mint a subdomain. You can still check availability below." + Sign in; already claimed → "You already own <full>." with the owned-name card (showcase URL, tx link); no username → "Set a username before claiming a subdomain." + link to account settings; unmintable username → "Your username @x cannot be a .sol label…" + Change your username; ready → "Signed in as @handle. Your subdomain label must match your username.", the label input is pre-filled with the username and made read-only, and the availability check fires at once.
+ 2. For an anonymous visitor the label input stays free-typed: lowercased, stripped to `[a-z0-9-]`, debounced 350ms availability check `GET /api/threews/subdomain?label=` → "<full> is available" (enables Mint) or "claimed by @user / owned by <addr>".
+ 3. User clicks **Mint** → `getCsrf()` (`GET /api/csrf-token`) → `POST /api/threews/subdomain` with `{ label }` + `x-csrf-token`. Before minting, the server re-checks the on-chain owner as a hard gate (minting over a taken name burns rent and fails anyway); if that read fails it answers `503 upstream_unavailable` ("could not verify the name on Solana right now; retry in a moment") rather than a server error.
+ 4. On success → "<full> minted." status, the account card flips to "You own <full>." with a **View your showcase** link, and the owned-name card shows the showcase URL and a Solscan tx link for the mint signature.
+- **Decision points / branches:** anonymous / claimed / needs-username / unmintable-username / ready account states; available vs taken; label must equal the account's username (the server 409s `username_mismatch` otherwise); optional `owner_wallet` must be a Solana wallet already linked to the account; `DELETE /api/threews/subdomain?label=` releases a stored subdomain.
+- **External calls / dependencies:** `/api/auth/me`, `/api/threews/me`, `/api/threews/subdomain` (GET check + POST mint + DELETE release), `/api/csrf-token`; Solscan (tx link). On-chain SNS mint.
+- **Success state:** Minted name card with showcase URL + tx signature link; account card in the claimed state.
+- **Empty / error states:** "Type a label to check availability."; availability check unreachable → "Could not reach three.ws to check availability…" with a retry; availability "bad" state for taken names; account lookup failure → account card error state with retry; mint `401` → "Your session has expired. Sign in again to mint." + Sign in; mint `no_wallet` → "Create an agent" link (`/create`); mint `429/502/503` → the server's message with a retry action; any other mint failure re-enables the button with the server's `error_description`.
- **Step count:** 4 required
---
@@ -118551,7 +123326,7 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
3. (optional) **Hold more $THREE** → opens the Jupiter swap modal (SOL → $THREE) in place.
4. (optional) Per-feature access matrix from `/api/three/access` shows what each tier unlocks (`enforced` / `eligible` / `required`).
- **Decision points / branches:** wallet connected or signed in (tier highlighted) vs neither (connect/sign-in prompt); ladder loaded vs outage (retry); holdings overflow handled gracefully at $10M+.
-- **External calls / dependencies:** `/api/three/tier`, `/api/three/access` (both `?wallet=`-aware), Jupiter swap modal, `/three-token` (price page link).
+- **External calls / dependencies:** `/api/three/tier`, `/api/three/access` (both `?wallet=`-aware), Jupiter swap modal (`src/swap-jupiter.js`: quote 12s, swap build 20s and verified-token list 8s deadlines, so a stalled Jupiter surfaces as an error instead of a hung modal), `/three-token` (price page link).
- **Success state:** populated tier ladder with the visitor's real tier, delta to the next tier, and a working in-page path to hold more.
- **Empty / error states:** all five states designed: skeleton ladder while loading, connect/sign-in prompt with the public ladder, actionable error with retry, populated ladder, $10M+ overflow formatting.
- **Step count:** 1 required (+3 optional)
@@ -118576,17 +123351,18 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
### Coin 3D Snapshot — `/coin3d`
- **Source:** `pages/coin3d.html` → `src/coin3d/main.js`. Deep-linked from `/launches` cards and the MCP tool `pumpfun_token_3d`.
-- **Entry point:** Full-screen Three.js scene seeded by `?mint=<base58>` (& optional `&network=`).
-- **Prerequisites / gates:** A valid `?mint=` param. Read-only.
+- **Entry point:** Full-screen Three.js scene seeded by `?mint=<base58>` (& optional `&network=`); without a mint the page is a landing card.
+- **Prerequisites / gates:** None. Read-only.
- **Steps (N):**
- 1. Boot reads `mint` + `network`; shows a loading overlay.
- 2. Parallel MCP calls via `POST /api/pump-fun-mcp`: `getTokenDetails`, `getBondingCurve`, `getTokenHolders` (top 12). Token logo fetched from its metadata URI (IPFS→HTTP, 6s timeout).
- 3. Renders a spinning coin medallion (logo-textured), a galaxy of top holders (spheres sized by balance, tinted by concentration), and a graduation ring filled to bonding-curve progress. OrbitControls for interaction.
- 4. (optional) Watchlist toggle persists to localStorage (`ld_watchlist`, shared with `/launches`).
-- **Decision points / branches:** mainnet vs devnet; mint present vs missing; logo available vs fallback.
-- **External calls / dependencies:** `/api/pump-fun-mcp` (pump.fun MCP), IPFS gateway for the logo. All on-chain/live.
-- **Success state:** interactive 3D token scene (medallion + holder galaxy + graduation ring).
-- **Empty / error states:** designed loading / error / empty overlays (`?mint=` missing, MCP failure, no holders) via the status-overlay helper.
+ 1. No `?mint=` → landing card: "See any token in 3D" with a paste-a-mint form (**View in 3D**, inline validation), a "View $THREE in 3D →" link, a "Recent launches on three.ws" grid of 8 cards from `/api/pump/launches?limit=8` (falling back to the encoded `/api/pump/%5Baction%5D?action=launches` form so a partial deploy never empties it; each card shows the launching agent's avatar or the symbol initials, no per-card fetch), and links to `/launches` and `/launch`.
+ 2. With a mint: loading overlay, then the snapshot: `getTokenDetails` + `getBondingCurve` via `POST /api/pump-fun-mcp` (15s deadline each; a timeout or unreachable endpoint is kept apart from a JSON-RPC "no such token" answer) in parallel with GeckoTerminal token info (mainnet only: the reliable name / symbol / logo / market-cap source for graduated coins whose metadata authority is renounced, `$THREE` included). The logo is fetched from the metadata URI through the shared IPFS gateway chain (`src/ipfs.js`, 6s per fetch, walking the whole gateway list on retry).
+ 3. The data HUD paints first and the overlay clears, then the scene: spinning coin medallion (logo-textured), graduation ring filled to bonding-curve progress, OrbitControls. If WebGL is unavailable the page degrades to the HUD + live tape instead of hanging on the spinner.
+ 4. Async enrichment, none of it blocking the render: `getTokenHolders` (top 12, 25s deadline, best-effort; its HUD cell shows a pulsing bar until it lands and the holder galaxy fills in, spheres sized by balance and tinted by concentration; an empty scan says so), Oracle conviction (`/api/oracle/coin`), coin intel (`/api/pump/coin-intel`), market figures + sparkline (`/api/pump/price-history?interval=15m`, refreshed every 60s), and a live trade tape (`/api/pump/dex-trades?limit=40`, polled every 9s).
+ 5. (optional) Watchlist toggle persists to localStorage (`ld_watchlist`, shared with `/launches`); HUD links out to the coin's 3D world (`/communities/<mint>`).
+- **Decision points / branches:** mint present vs missing (landing); mainnet vs devnet; every source unreachable vs a definite "not a token"; logo available vs fallback; WebGL available vs data-only fallback.
+- **External calls / dependencies:** `/api/pump-fun-mcp` (pump.fun MCP), GeckoTerminal token info, IPFS gateway chain for the logo, `/api/oracle/coin`, `/api/pump/coin-intel`, `/api/pump/price-history`, `/api/pump/dex-trades`, `/api/pump/launches` (landing grid). All on-chain/live.
+- **Success state:** interactive 3D token scene (medallion + holder galaxy + graduation ring) with a live HUD, sparkline and trade tape.
+- **Empty / error states:** landing card with a validated mint form; loading overlay; every live source failing to respond → "Every live source for this token failed to respond. Check your connection, then try again." + **Retry**; a definite miss → "Token not found" + **Browse coins** (`/launches`); empty holder scan, "No price history yet." / "Price history unavailable." sparkline slot, and "Live trades are unavailable right now. Retrying every few seconds." tape, each in place; recent-launches grid → "No launches yet. Be the first →" or a "Browse launches →" fallback.
- **Step count:** 3 required (+1 optional)
---
@@ -118600,7 +123376,7 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.
---
-<a id="sec-512"></a>
+<a id="sec-532"></a>
> **Source:** `docs/ux-flows/09-x402-agent-commerce.md` · [↑ table of contents](#table-of-contents)
@@ -118633,9 +123409,9 @@ choreographed two-agent narrative driven by Server-Sent Events.
4. System POSTs `/api/x402-pay` (SSE) — timeline advances `challenge → built → verified → dispatched → settled`, each stage showing real ms timings and the settle tx prefix.
5. On `result`: receipt rendered (amount, payment, durations), MCP output rendered in chat — `tools/list` lists tools, `inspect/validate/optimize` show JSON/cards, model-processing tools render an actual `<model-viewer>` GLB. Ticker bumps; balance + feed refresh.
- **Decision points / branches:** payer mode (server agent vs Phantom vs EVM — `run()` dispatches to `runPhantomPayment` / `runEvmPayment` / SSE path); agent has wallet vs not (gen overlay); prompt parse (`parsePrompt`) into a tool call; stream error vs `result` vs "stream ended without result".
-- **External calls / dependencies:** `/api/x402-pay` (SSE payer + `?agents=1`, `?balance=1`, `?feed=1`, `/og`), `/api/mcp` (402 probe + dispatch), `/api/x402-checkout?action=prepare|encode`, `/api/agents/{id}/solana`, Solana mainnet RPC (`api.mainnet-beta.solana.com`), x402 facilitator (verify/settle), Solscan for tx links; BSC path uses `ThreeWSPayments` contract `0x…1B72Cc`.
+- **External calls / dependencies:** `/api/x402-pay` (SSE payer + `?agents=1`, `?balance=1`, `?feed=1`, `/og`), `/api/mcp` (402 probe + dispatch), `/api/x402-checkout?action=prepare|encode`, `/api/agents/{id}/solana`, Solana mainnet RPC (`api.mainnet-beta.solana.com`), x402 facilitator (verify/settle), Solscan for tx links; BSC path uses `ThreeWSPayments` contract `0x…1B72Cc`. The Phantom path imports `@solana/web3.js` through `/load-module.js`, which tries the pinned version on esm.sh, then jsdelivr, then unpkg, each under a deadline, so one blocked CDN no longer stalls the run at the signing step.
- **Success state:** receipt card + rendered MCP result (incl. live 3D model), Solscan tx link, balance ticks down, feed prepends the call, page title shows elapsed ms.
-- **Empty / error states:** not-signed-in → demo-wallet note; no agents → "Create your first agent"; agent has no wallet → gen overlay; `402`/network failure → timeline stage flips to error + `x402 call failed` / `Network error` message; stream ends without result → explicit error; wallet underfunded surfaces from server error.
+- **Empty / error states:** not-signed-in → demo-wallet note; no agents → "Create your first agent"; agent has no wallet → gen overlay; `402`/network failure → timeline stage flips to error + `x402 call failed` / `Network error` message; stream ends without result → explicit error; wallet underfunded surfaces from server error; Solana RPC unreadable while the server builds the transfer (every read on that path is guarded and cache-backed first) → `503 rpc_unavailable` with a `Retry-After` header and the copy "No funds were transferred; retry shortly" (the same guard answers `/api/x402-checkout?action=prepare`); a wallet component that fails to load on all three CDN mirrors → the failed step names the hosts it tried.
- **Step count:** 4 required (+ ~4 optional).
### Paid-call permalink — `/pay/calls`
@@ -118671,16 +123447,16 @@ choreographed two-agent narrative driven by Server-Sent Events.
- **Entry point:** Directory of live x402-paid endpoints (merged across facilitators) as a card grid with filters.
- **Prerequisites / gates:** None to browse; a wallet only when paying ("Try it").
- **Steps (5 required + 2 optional):**
- 1. Page loads → `GET /api/bazaar/list` → renders endpoint cards. The handler merges every configured facilitator behind a 60s in-process catalog memo (`BAZAAR_CATALOG_TTL_MS`), returns at most `limit` rows (default 200) and reports the pre-cut match count as `total`.
+ 1. Page loads → `GET /api/bazaar/list` → renders endpoint cards. The handler merges every configured facilitator behind a 60s in-process catalog memo (`BAZAAR_CATALOG_TTL_MS`), returns at most `limit` rows (default 200) and reports the pre-cut match count as `total`; `offset` (default 0) skips that many matches so a caller can page past the cap. The page asks for one page at a time (`limit=200`, or 100 for a search) and walks the rest with `offset`: the count reads "200 of 1,234" and a **Load more** button appends the next page, disappearing once everything is shown or when a page comes back empty because the catalog moved. Every request carries a sequence number and aborts the one in flight, so the cards always match the controls the user last touched.
2. (optional) Filter by type (HTTP/MCP), network (EVM/Solana), max price, extension, sort.
- 3. (optional) Search (`/api/bazaar/search?query=`) or scroll.
+ 3. (optional) Search (`/api/bazaar/search?query=`, same `offset` paging) or scroll, then **Load more**.
4. Click a card action: HTTP → **Try it** (pay flow); MCP tool → **Inspect tool** (details only — JSON-RPC, not auto-callable); **Details** → modal + `/api/bazaar/context?resource=`.
5. On **Try it**: `window.X402.pay({ endpoint, method, merchant, action, … })` opens the modal; pay → settle.
6. Inline `.receipt` on the card shows status + on-chain tx + explorer link.
- **Decision points / branches:** HTTP vs MCP (MCP = inspect only); pay success/cancel/error → distinct receipt states; explorer chosen from endpoint network (Solscan/Basescan/Arbiscan/etc.).
- **External calls / dependencies:** `/api/bazaar/list|search|context`, `/x402.js`, merchant endpoint, multi-chain explorers.
- **Success state:** green receipt with tx hash + explorer link + result JSON; SR announcement "Payment succeeded for <service>".
-- **Empty / error states:** no results → "No matching services…"; catalog unreachable → "Couldn't reach the catalog… Retry" (every `/api/bazaar/*` handler answers `502 facilitator_error` when all facilitators fail, so a total outage never renders as an empty catalog); modal load fail → "Payment module failed to load"; cancel → receipt hidden; error → red receipt.
+- **Empty / error states:** no results → "No matching services…"; catalog unreachable → "Couldn't reach the catalog… Retry" (every `/api/bazaar/*` handler answers `502 facilitator_error` when all facilitators fail, so a total outage never renders as an empty catalog); modal load fail → "Payment module failed to load"; cancel → receipt hidden; error → red receipt; a **Load more** failure keeps the rows already on screen and puts the reason next to the button ("Couldn't reach the catalog. Try again." or "Could not load more: …"); a cross-origin endpoint whose response carries no CORS headers → the modal's discover step says "<host> does not allow browser requests … Call it from a server, an agent, or the x402 CLI instead" and offers no Try-again button, since the same click can never succeed.
- **Step count:** 5 required (+2 optional).
### x402 Arbitrage — `/arbitrage`
@@ -118689,16 +123465,16 @@ choreographed two-agent narrative driven by Server-Sent Events.
- **Prerequisites / gates:** None to browse; wallet only to pay.
- **Deep links in:** `/arbitrage?focus=<capability>` (what `/bazaar` sends from a listing's priced-peers hint), `?q=<text>`, `?type=http|mcp`. The page writes its own filter state back with `replaceState`, so any filtered view is shareable.
- **Steps (3 required + 3 optional):**
- 1. Page loads → `GET /api/bazaar/arbitrage?minSpreadPct=0&limit=200` → skeleton then arb cards (spread %, up to 5 providers cheapest-first, metrics).
+ 1. Page loads → `GET /api/bazaar/arbitrage?minSpreadPct=0&limit=200` → skeleton then arb cards (spread %, up to 5 providers cheapest-first, metrics). A source strip (`#sources`, polite live region) names every facilitator that answered with its listing count; one that dropped out reads "<host> unreachable" (reason on hover) under an amber "Partial scan: N of M facilitators unreachable" pill, because the handler ships its `errors` next to `sources` and a half-blind scan must not read as a quiet market.
2. (optional) Filter type All/HTTP/MCP; (optional) search by capability/host.
3. Click **Pay cheapest · $X** → lazy-loads `/x402.js`, then `window.X402.pay({ endpoint: cheapest.resource, method:'GET', merchant: host, action: capability })`.
- 4. Result shows on the button: "✓ Paid" (auto-revert 4s) / "Failed: …" / revert on cancel.
+ 4. Result shows on the button: "✓ Paid" (auto-revert 4s) / "Failed: …" or "Error: …" (auto-revert 4s) / closing the modal hands the button straight back with no hold.
5. (optional) Click **Avoid · $Y** → navigates to `/bazaar?q=<capability>` (plus `&type=mcp` for MCP capabilities, since the catalog defaults to the HTTP tab) to see the full spectrum.
- **Decision points / branches:** MCP capability → "Pay" redirects to the catalog (can't call MCP directly); on-demand x402 load; button state management.
- **What counts as an opportunity (backend):** listings are grouped by capability key (MCP tool name, else service name, else the last literal URL segment; route placeholders like `/:solana_address` and `/{mint}` are skipped because they name the argument, not the capability). A group ships only if it spans two or more provider hosts, or if one host has a single resource quoted at two different prices by two different facilitators (a genuine cross-venue gap). A vendor charging different prices for its own distinct endpoints is not arbitrage and is dropped.
- **External calls / dependencies:** `/api/bazaar/arbitrage`, `/x402.js`, the cheapest live endpoint, Solscan/Basescan.
- **Success state:** "✓ Paid" on the cheapest provider; payment settled on-chain.
-- **Empty / error states:** filters exclude everything → "No opportunities match these filters" with a Clear-filters button and a catalog link; feed genuinely has no gap → "No cross-provider price gaps right now" with links to `/bazaar` and `/providers`; timeout (20s) → "Request timed out… Retry"; feed error → "Couldn't reach the arbitrage feed…"; modal fail → "Payment modal failed to load".
+- **Empty / error states:** filters exclude everything → "No opportunities match these filters" with a Clear-filters button and a catalog link; feed genuinely has no gap → "No cross-provider price gaps right now" with links to `/bazaar` and `/providers`; timeout (20s) → "Request timed out… Retry"; feed error → "Couldn't reach the arbitrage feed…"; a partial scan renders normally with the degraded source strip rather than as an error; modal fail → "Payment modal failed to load".
- **Step count:** 3 required (+3 optional).
### x402 Providers — `/providers`
@@ -118765,7 +123541,7 @@ choreographed two-agent narrative driven by Server-Sent Events.
4. `POST /api/x402/fact-check` with `{ claim, strictness }`.
5. On `402` → payment panel (Base USDC $0.10 / Solana USDC $0.10) + "Connect wallet to pay →" (`/marketplace`). On `200` → verdict banner (SUPPORTED/CONTRADICTED/MIXED/INSUFFICIENT + confidence), sources grid (stance/authority), cost breakdown, expandable SHA-256 attestation.
- **Decision points / branches:** empty claim → no submit; `402` → payment panel; `429` → "Too many checks…"; `5xx` → internal-error message; retry button re-runs same claim. Cached result returns `200` instantly. When the LLM stages cannot reach a provider, the check degrades instead of failing: real sources still return with neutral stances, the response carries a `degraded` marker, and the result is never cached (so a provider outage is not pinned for 7 days).
-- **External calls / dependencies:** `/api/x402/fact-check` (3 search queries → multi-source retrieval → LLM stance → weighted verdict → attestation; optional vision for image evidence, fail-open; the whole pipeline runs under a wall-clock budget, `FACT_CHECK_BUDGET_MS`, default 45s, so it never outlives the edge's 60s cutoff), Base/Solana USDC, Redis cache (7-day TTL, full-chain results only).
+- **External calls / dependencies:** `/api/x402/fact-check` (3 search queries → multi-source retrieval → LLM stance → weighted verdict → attestation; optional vision for image evidence, fail-open; the whole pipeline runs under a wall-clock budget, `FACT_CHECK_BUDGET_MS`, default 45s, so it never outlives the edge's 60s cutoff), Base/Solana USDC, Redis cache (7-day TTL, full-chain results only; every cache read and write is bounded at 2s, reads retry once, so a slow Upstash degrades to a cache miss instead of holding a paid request open).
- **Success state:** verdict banner + sources + cost breakdown + attestation toggle.
- **Empty / error states:** initial example chips; skeleton loading; error card (title/msg/code + retry); payment panel with network badges.
- **Step count:** 4 required (+3 optional).
@@ -118807,14 +123583,14 @@ choreographed two-agent narrative driven by Server-Sent Events.
- **Steps (6 required + 6 optional):**
1. Type the message (live char + byte counters; orange warning > 1500 bytes).
2. (optional) Enter a Taproot receive address.
- 3. (optional) Select fee rate → live fee estimate (`#feeEstimate`) with sats / BTC / ≈USD (CoinGecko best-effort).
+ 3. (optional) Select fee rate → live fee estimate (`#feeEstimate`) with sats / BTC / ≈USD (the first of four keyless price feeds to answer: CoinGecko, Coinbase, Kraken, DefiLlama, 4s each, best-effort).
4. Click **Inscribe forever** → native `confirm()` showing estimated BTC cost + address ("payment is final once broadcast. Continue?").
5. `POST /api/forever/inscribe` `{ message, receiveAddress, feeRate }` → creates OrdinalsBot order → returns charge address, amount (sats), Lightning invoice, mempool URL; order persisted to `sessionStorage forever:order` → **pay view**.
- 6. Pay view: QR (BIP-21), amount, pay-to/Lightning/receive/order-id rows, "Open in wallet" / "View on mempool" / "Cancel". User sends BTC from their own wallet.
+ 6. Pay view: QR (BIP-21; api.qrserver.com, then quickchart.io, and if both fail the payment URI as selectable text so the payer is never left with a broken image), amount, pay-to/Lightning/receive/order-id rows, "Open in wallet" / "View on mempool" / "Cancel". User sends BTC from their own wallet.
7. Auto-poll `GET /api/forever/status?id=<orderId>` every 6s → `waiting-payment → payment-received → inscribing → inscribed`. Once a reveal txid exists the response also carries `inscription.onchain` (confirmed, confirmations, block height and time) read keyless from Blockstream Esplora, so finality depth comes from the chain rather than from OrdinalsBot's order state; an Esplora outage degrades that field to `null` instead of failing the poll.
8. On `inscribed` → **win view**: large message, Inscription link (ordinals.com), reveal-tx link (mempool.space), receive address, "Bitcoin mainnet"; share to X / copy permalink / inscribe another.
-- **Decision points / branches:** empty / > 1500 bytes / invalid Taproot / invalid fee rate → inline errors; signed-out → the server's 401 copy surfaces in the error banner; confirm-dialog cancel → stays in compose; order-create `502/503` → "Inscription failed. Try again."; status `failed` → OrdinalsBot contact note; status `404` (the order id no longer resolves upstream) → polling stops, the saved order is cleared, and the page returns to compose with a nothing-was-charged explanation; reload mid-payment → `resumeIfAny()` restores the pay view + resumes polling (unless the saved order 404s, which takes the same retire path).
-- **External calls / dependencies:** `/api/forever/inscribe` + `/api/forever/status` → **OrdinalsBot** (`api.ordinalsbot.com`, Bitcoin mainnet Taproot inscription), Blockstream Esplora (`api/_lib/esplora.js`, keyless reveal-tx confirmations, fail-soft), CoinGecko (USD, best-effort), QR server, mempool.space + ordinals.com for verification.
+- **Decision points / branches:** empty / > 1500 bytes / invalid Taproot / invalid fee rate → inline errors; signed-out → the server's 401 copy surfaces in the error banner; confirm-dialog cancel → stays in compose; order-create `502/503` → "Inscription failed. Try again." (the OrdinalsBot order call is bounded at 30s and never retried, since a retry after a request that actually landed would buy a second inscription); a non-OK, non-404 poll (including the `502` the API answers when OrdinalsBot misses its 15s deadline twice) is skipped and the next 6s tick retries; status `failed` → OrdinalsBot contact note; status `404` (the order id no longer resolves upstream) → polling stops, the saved order is cleared, and the page returns to compose with a nothing-was-charged explanation; reload mid-payment → `resumeIfAny()` restores the pay view + resumes polling (unless the saved order 404s, which takes the same retire path).
+- **External calls / dependencies:** `/api/forever/inscribe` + `/api/forever/status` → **OrdinalsBot** (`api.ordinalsbot.com`, Bitcoin mainnet Taproot inscription), Blockstream Esplora (`api/_lib/esplora.js`, keyless reveal-tx confirmations, fail-soft), four BTC/USD feeds (CoinGecko, Coinbase, Kraken, DefiLlama; best-effort), two QR services (qrserver, then quickchart), mempool.space + ordinals.com for verification.
- **Success state:** win view with permanent inscription + reveal-tx links + share buttons.
- **Empty / error states:** compose validation errors; inscribe failure banner; pay-view polling states; order `failed` message with support info.
- **Step count:** 6 required (+6 optional).
@@ -118840,16 +123616,16 @@ choreographed two-agent narrative driven by Server-Sent Events.
### Agent Commerce — `/agent-trade`
- **Source:** `pages/agent-trade.html` + `src/agent-trade.js`; backend `api/agent-trade/demo` (SSE), guarded by `api/_lib/agent-trade-guards.js`.
- **Entry point:** Three.js scene with two geometric agents (Nexus buyer, Oracle seller) on platforms; topic dropdown + **▶ Run Trade Demo**; central card + step log. Cinematic camera, particle beam, burst on confirm.
-- **Prerequisites / gates:** No user auth. Server agent keypairs `AGENT_BUYER_SECRET` + `AGENT_SELLER_SECRET` (+ `AGENT_TRADE_PRICE_SOL`, `AGENT_TRADE_NETWORK`) must be configured + funded. Pre-flight `checkConfig()` (`/api/agent-trade/demo?check=1`); if unconfigured → modal overlay walkthrough + env instructions, Run disabled.
+- **Prerequisites / gates:** No user auth. Server agent keypairs `AGENT_BUYER_SECRET` + `AGENT_SELLER_SECRET` (+ `AGENT_TRADE_PRICE_SOL`, `AGENT_TRADE_NETWORK`) must be configured + funded. Pre-flight `checkConfig()` (`/api/agent-trade/demo?check=1`) runs with Run disabled and a skeleton card ("Checking the demo wallets") in the centre; configured → ready card + Run enabled; unconfigured → modal overlay walkthrough + env instructions, Run stays disabled; pre-flight unreachable → a "Status check failed" card with **Retry the status check**, and Run is left enabled so the run itself reports what failed.
- **Steps (2 required; rest auto):**
1. **[user]** Select a topic from the dropdown.
2. **[user]** Click **▶ Run Trade Demo** → "⏳ Running…".
- 3. **[auto SSE `/api/agent-trade/demo?topic=`]** ordered events with choreography: `init` (addresses/balances, camera fly) → `request` (buyer asks) → `challenged` (402 card, SOL price) → `paying` (particle beam buyer→seller) → `confirmed` (burst, Solscan tx card, balance debited) → `delivering` ("Analyzing with <model>…") → `delivered` (final analysis card + model + tx link).
+ 3. **[auto SSE `/api/agent-trade/demo?topic=`]** ordered events with choreography: `init` (addresses/balances, camera fly) → `request` (buyer asks) → `challenged` (402 card, SOL price) → `paying` (particle beam buyer→seller; the buyer bubble "Sending X SOL on-chain…" carries an indeterminate progress bar, since a real transfer can take tens of seconds and static text is indistinguishable from a stalled page) → `confirmed` (burst, Solscan tx card, balance debited) → `delivering` ("Analyzing with <model>…", same pending bar) → `delivered` (final analysis card + model + tx link).
4. Button re-enabled ("Run again"); idle animation resumes.
-- **Decision points / branches:** topic feeds the request payload; config gate (dismiss only hides overlay); `error` event → red chip + toast + retry; 35s safety timeout closes the stream.
+- **Decision points / branches:** topic feeds the request payload; config gate (dismiss only hides overlay); `error` event → the active chip flips red, a toast fires, and a centre failure card names the cause in its badge (`insufficient_funds` "Buyer wallet is short", `daily_budget_exhausted` "Daily spend limit reached", `analysis_unavailable` "No analysis model available", `analysis_failed` "Analysis failed after payment", `send_failed` "Payment failed", anything else "Trade stopped") with a **Run it again** button; `not_configured` instead re-opens the walkthrough overlay and disables Run; a stream that drops mid-run gets the same card badged "Stream dropped". Below 560px the labels and bubbles leave the 3D projection and stack into a flat strip (the layout the no-WebGL fallback also uses) so the card never paints over a speech bubble.
- **External calls / dependencies:** `/api/agent-trade/demo` (`?check=1` + `?topic=` SSE), real SOL settlement on Solana mainnet/devnet, AI model inference for the delivered analysis, Solscan.
- **Success state:** all 7 SSE stages + final delivered-skill card with model-generated content + on-chain tx.
-- **Empty / error states:** not-configured modal overlay; stream error toast + retry; timeout auto-finish; idle empty scene.
+- **Empty / error states:** pre-flight skeleton card; not-configured modal overlay + unconfigured card; status-check-failed card with retry; failure card (badge + message + Run it again) on any `error` event or dropped stream; idle ready card.
- **Step count:** 2 required (auto SSE thereafter).
### Agent Economy (Live) — `/agent-economy`
@@ -118878,8 +123654,8 @@ choreographed two-agent narrative driven by Server-Sent Events.
2. **[user]** Click **Run demo** → "Running…", log cleared, scene reset.
3. **[auto SSE `/api/demo-economy`]** typed events: `step` (e.g. agents_ready → camera fly) → `bazaar` (TV draws x402 service list) → `wallet` (chips updated) → `payment` (pay card; SOL amount; signature link or "SIMULATED" badge; mobile sheet slides up) → `content` (TV draws ORACLE market briefing with pools) → `done`.
4. Button re-enabled ("Run again").
-- **Decision points / branches:** configured+funded vs underfunded (error w/ fund notice) vs not-configured (error, prompts anon to sign in); `simulated=true` → "Simulated payment — sign in for live" + sim row. 35s hard timeout.
-- **External calls / dependencies:** `/api/demo-economy` (SSE), Solana RPC settlement (if live), market-data source, Solscan.
+- **Decision points / branches:** configured+funded vs underfunded (error w/ fund notice) vs not-configured (error, prompts anon to sign in); `simulated=true` → the pay card reads "Simulated payment" and asks the visitor to sign in to run a live on-chain transfer, plus a "Mode: Simulated" row. 35s hard timeout.
+- **External calls / dependencies:** `/api/demo-economy` (SSE), Solana RPC settlement (if live), GeckoTerminal trending pools for the briefing (read through the shared upstream fetch: 8s deadline, one retry, breaker-guarded, and backed by a last-known-good copy up to 30 min old, so a throttled upstream leaves the demo with a briefing flagged `stale` + `as_of` rather than nothing to sell), Solscan.
- **Success state:** TV shows final briefing with markets + prices + 24h changes; full activity log; "Run again".
- **Empty / error states:** not-configured error; underfunded fund notice; simulated mode; initial idle scene with "not configured" wallet chips.
- **Step count:** 1 required (auto SSE thereafter).
@@ -118936,7 +123712,7 @@ choreographed two-agent narrative driven by Server-Sent Events.
## Notes
- **Routing:** all clean URLs resolve through the `vercel.json` route table — read directly by the Cloud Run server (`server/index.mjs`) in production and mirrored by the `vite.config.js` `historyApiFallback` map in dev. `/pay`, `/bazaar`, `/arbitrage`, `/providers`, `/forever`, `/tutor` live under `public/`; the rest under `pages/`.
-- **Shared payment modal:** `/x402.js` (`public/x402.js`, ~1.5k LOC) is the drop-in `window.X402.pay()` modal used by `/pay/c`, `/bazaar`, `/arbitrage`, `/ibm/x402-demo`, `/shopper` (paywall), `/fact-checker`, `/unstoppable`, `/tutor`. It handles wallet connect (Phantom/Solana, MetaMask/Base via EIP-3009), the 402→sign→retry loop, and SIWX re-entry.
+- **Shared payment modal:** `/x402.js` (`public/x402.js`, ~2.4k LOC) is the drop-in `window.X402.pay()` modal used by `/pay/c`, `/bazaar`, `/arbitrage`, `/ibm/x402-demo`, `/shopper` (paywall), `/fact-checker`, `/unstoppable`, `/tutor`. It handles wallet connect (Phantom/Solana, MetaMask/Base via EIP-3009), the 402→sign→retry loop, and SIWX re-entry. Its Solana web3.js and SIWX hashing imports go through `/load-module.js` (the pinned version on esm.sh, then jsdelivr, then unpkg, each under a deadline); only when all three fail does the modal steer the buyer to MetaMask on Base, which needs no third-party code. A cross-origin endpoint whose response carries no CORS headers is reported as "<host> does not allow browser requests" with a pointer to a server, an agent, or the x402 CLI, and no Try-again button.
- **Server-payer vs user-payer:** the "agent economy" narratives (`/agent-exchange`, `/agent-trade`, `/agent-economy`, `/demo`, `/live`) pay from **server-held agent wallets** and stream the choreography over SSE — the user only triggers/selects, then watches. The "showcase" apps (`/shopper`, `/fact-checker`, `/tutor`, `/bazaar`, `/arbitrage`, `/ibm`) make the **user** pay via the `/x402.js` modal.
- **Auto-play demos:** `/agent-exchange`, `/agent-trade`, `/agent-economy`, `/demo` need one user click to start, then auto-play. `/live` adds an auth gate for real settlement. `/play/arena` is fully autonomous (agents trade themselves; user only watches/moves/inspects) and uses **no x402** — real pre-funded Solana trades.
- **Forever** is the only **non-x402** payment in the cluster: native Bitcoin (or Lightning) to an OrdinalsBot charge address, inscribing a real Taproot text inscription on Bitcoin mainnet.
@@ -118946,7 +123722,7 @@ choreographed two-agent narrative driven by Server-Sent Events.
---
-<a id="sec-513"></a>
+<a id="sec-533"></a>
> **Source:** `docs/ux-flows/10-chat-brain-labs.md` · [↑ table of contents](#table-of-contents)
@@ -118961,7 +123737,7 @@ modules. Routes resolved via `vercel.json` rewrites.
### Conversational AI Chat (3D talking agent) — `/chat`
- **Source:** `/workspaces/three.ws/chat/` (a standalone Svelte app, separate Vite build). Entry `/workspaces/three.ws/chat/index.html` → `/workspaces/three.ws/chat/src/main.js` → `/workspaces/three.ws/chat/src/App.svelte`. Key modules: `chat/src/providers.js` (LLM providers), `chat/src/convo.js` (streaming completion pipeline), `chat/src/AgentPicker.svelte`, `chat/src/ModelSelector.svelte`, `chat/src/stores.js`, `chat/src/walletAuth.js` (SIWE/SIWS), `chat/src/tools.js`, `chat/src/sync.js`, `chat/src/SkillsMarketplaceModal.svelte`, `chat/src/TxApprovalModal.svelte`.
- **Entry point:** `/chat` → `chat/index.html` (`<div id="app">` mounted by `main.js`).
-- **Prerequisites / gates:** None to start chatting: free built-in models stream through the server proxy with no key. Optional gates: user-supplied API key (Anthropic/OpenAI/Groq/Mistral/Ollama/OpenRouter) stored locally for non-built-in models; wallet sign-in (SIWE/SIWS via `/api/auth/*`) only for cross-device sync + on-chain tool calls; `TxApprovalModal` requires a connected wallet for wallet/pump tool transactions. No $THREE gate. Voice output is opt-in (off by default).
+- **Prerequisites / gates:** None to start chatting: free built-in models stream through the server proxy with no key. Optional gates: user-supplied API key (Anthropic/OpenAI/Groq/Mistral/Ollama/OpenRouter) stored locally for non-built-in models; sign-in only for cross-device sync + on-chain tool calls, either by wallet (SIWE/SIWS via `/api/auth/*`, `chat/src/walletAuth.js`) or by email/password on the platform's own cookie session (`chat/src/passwordAuth.js` POSTs `/api/auth/login` / `/api/auth/register`, with the Terms clickwrap gating the submit); `TxApprovalModal` requires a connected wallet for wallet/pump tool transactions. No $THREE gate. Voice output is opt-in (off by default).
- **Steps (6):**
1. Open `/chat`; app boots, fetches the free model list from `/api/chat/models`, shows empty state with suggestion chips. `BUILTIN_MODELS` in `providers.js` is only a first-paint seed; `resolveDefaultModel()` prefers a model the server reports as live, so if the configured default has been retired upstream a new conversation opens on a live model instead of a dead one. The list also carries one virtual entry, "three.ws Agent · server tools": a server-side agent loop that answers through `/api/chat/proxy` in the same wire format but runs multiple tool-calling LLM rounds per message; it is appended last so it can never become the silent default.
2. (optional) Click the model selector and pick an LLM, or open `AgentPicker` to load a persona/agent (from `/api/agents`, `/api/marketplace/agents`, or the agent library JSON). Loading an agent mounts its live `<agent-3d>` avatar in the panel.
@@ -118970,9 +123746,9 @@ modules. Routes resolved via `vercel.json` rewrites.
5. `convo.complete()` POSTs to the provider's completion URL (built-in → `/api/chat/proxy`; Anthropic → `/v1/messages`; others → `/v1/chat/completions`) and streams tokens back into the assistant bubble (markdown + KaTeX rendered live).
6. On reply completion: if an agent is loaded, its `<agent-3d>` avatar plays the talk animation (`agentEl.speak(...)`) and expresses the classified emotion (`agentEl.expressEmotion(...)`); those two calls are animation only and carry no audio. With voice output enabled, browser `speechSynthesis` reads the reply aloud, agent or not. Payoff: a 3D agent that answers in voice with mood animation.
- **Decision points / branches:** model/provider choice (free built-in vs keyed provider vs OpenRouter "all models" vs local Ollama); text vs voice output (agent-3d speech vs browser speechSynthesis vs silent); persona/agent loaded vs raw model; tool-calling on/off (16 curated tool packs in `tools.js` `curatedToolPacks`, surfaced via `ToolPackModal`: wallet-transactions, x402-pay, tradingview, price-chart-3d, token-price, token-ticker-3d, web-search, date-time, pump-launch, tx-explain, mint-scene-nft, nft-3d-import, forge-text-to-3d, forge-avatar, wallet-balances, token-gate-scene; the built-in wallet/agent/pump/payments tool schemas back them); every generated 3D model card carries "View in AR ↗" (`/ar?src=<glb>`), "Download GLB", and "Viewer ↗" actions; regenerate / edit / branch a message; share conversation (compressed link via `share.js`).
-- **External calls / dependencies:** `/api/chat/models` (free model list, OpenRouter-proxied), `/api/chat/proxy` (built-in completions), `/api/chat/config`, `/api/mcp` + `/api/pump-fun-mcp` (skills marketplace / pump tools), `/api/agents` + `/api/marketplace/agents` (agent picker), `/api/auth/{me,logout,siwe/nonce,siwe/verify,siws/nonce,siws/verify}` (wallet auth), agent-library `index.en-US.json`. Direct provider APIs (api.anthropic.com, api.openai.com, api.groq.com, api.mistral.ai, openrouter.ai, local Ollama) when a user key is set.
+- **External calls / dependencies:** `/api/chat/models` (free model list, OpenRouter-proxied), `/api/chat/proxy` (built-in completions), `/api/chat/config`, `/api/mcp` + `/api/pump-fun-mcp` (skills marketplace / pump tools), `/api/agents` + `/api/marketplace/agents` (agent picker), `/api/auth/{me,logout,siwe/nonce,siwe/verify,siws/nonce,siws/verify}` (wallet auth), `/api/auth/{login,register}` (email/password auth), agent-library `index.en-US.json`. Direct provider APIs (api.anthropic.com, api.openai.com, api.groq.com, api.mistral.ai, openrouter.ai, local Ollama) when a user key is set.
- **Success state:** Streamed assistant message rendered; with voice enabled the reply is read aloud once per message (a repeated end-of-stream chunk cannot double-speak it), and a loaded agent mouths along with mood animation; conversation persisted to IndexedDB / optional E2E-encrypted sync.
-- **Empty / error states:** Empty state with brand tagline + suggestion chips when no messages. Provider/network errors surface as inline notices; abortable generation via `controller`. Missing API key → model marked unavailable in selector. Avatar GLB load failure falls back to default avatar; speech failure degrades silently to text.
+- **Empty / error states:** Empty state with brand tagline + suggestion chips when no messages. Provider/network errors surface as inline notices: a request that never left the device is tagged `code: 'network'` in `convo.js` and renders "Could not reach the model. The request never left this device, so nothing was sent…" with a hover-refresh hint, and a stream that dies mid-reply renders "The reply stopped early because the connection dropped…" instead of the transport's own wording; the built-in proxy waits at most 25s for OpenRouter to start answering, rotates keys and models on a timeout, and reports a clean 504 when every route hangs. Abortable generation via `controller`. Missing API key → model marked unavailable in selector. Avatar GLB load failure falls back to default avatar; speech failure degrades silently to text.
- **Step count:** 6 required (+4 optional)
- **Voice path (resolved 2026-08-06):** there is exactly one speaker, browser `speechSynthesis`, gated on the voice-output toggle. The legacy standalone Talking Head component (a CDN build of met4citizen/TalkingHead pointed at the long-retired `/api/tts/google`) was imported but never rendered, and its dead `talkingHeadEnabled` flag suppressed `speechSynthesis` for anyone whose browser still carried the flag from an older build. Component, flag, and both dead branches are removed. `talkingHeadAvatarUrl` survives on purpose: it is the live store behind the Settings avatar picker, the sidebar logo, and the in-reply `<agent-3d>` viewer.
@@ -118981,13 +123757,13 @@ modules. Routes resolved via `vercel.json` rewrites.
### Agent Profile / Directory — `/agent`
- **Source:** `/agent` is a **301 redirect to `/agents`** (`vercel.json`). The directory `/agents` → `/workspaces/three.ws/pages/agents/index.html`; a single agent `/agents/:id` → `/workspaces/three.ws/pages/agent-detail.html` → `/workspaces/three.ws/src/agent-detail.js`. Supporting: `src/shared/agent-3d.js` (`seeInWorldHref`, `agentAvatarGlb`), `src/shared/agent-wallet-chip.js`, `src/shared/agent-coin.js`, `src/agent-detail-market.js`. (`src/agent-home.js` is a related presence component used by `/app` + `/app-demo`, not by `/agents/:id`.)
- **Entry point:** `/agent` (redirect) → `/agents` directory grid → click an agent → `/agents/:id` profile.
-- **Prerequisites / gates:** None to view. Editing (`/agent/:id/edit` → `agent-edit.html`) and owner actions require wallet/owner auth. No $THREE gate to browse.
+- **Prerequisites / gates:** None to view. Editing (`/agents/:id/edit` → `agent-edit.html`; the older `/agent/:id/…` subroutes still resolve but every link now uses the canonical `/agents/:id/…` form) and owner actions require wallet/owner auth. No $THREE gate to browse.
- **Steps (4):**
1. Hit `/agent` → 301 to `/agents`; directory of agents renders.
2. Click an agent card → `/agents/:id` loads `agent-detail.js`.
3. Profile renders: a live Three.js hero avatar (`mountIdleAvatar` retargets the canonical idle clip onto the rig with a procedural idle-life loop; no static `<model-viewer>`), identity, voice metadata (cloned provider or browser TTS pill), live $THREE/pump token chip (streamed via `/api/pump/by-agent`), skills (with dynamic price/promo state from `/api/marketplace/skill-promo?agent_id=…&skill=…`), history.
4. Click "See in world" → routes to `/play?avatar=<glb>&coin=<THREE_MINT>` (the 3D world payoff); or "Edit" / wallet chip / coin-launch actions for owners.
-- **Decision points / branches:** view vs edit (owner); "See in world" (→ /play) vs embed (`/agent/:id/embed`) vs wallet (`/agent/:id/wallet`); token chip present (launched coin) vs not.
+- **Decision points / branches:** view vs edit (owner); "See in world" (→ /play) vs embed (`/agents/:id/embed`) vs wallet (`/agents/:id/wallet`); token chip present (launched coin) vs not; a `/agents/:id?skill=<name>#pricing` deep link (what the Buy CTA on `/conversions` sends) scrolls the pricing card to that skill row once it renders (`focusRequestedSkill` in `agent-detail-market.js`, honoured once per page load).
- **External calls / dependencies:** `/api/agents/:id`, `/api/marketplace/agents/:id`, `/api/pump/by-agent` (live market-cap stream), `/api/marketplace/skill-promo` (skill pricing/promo), `/api/agent-share` (share). Three.js idle-avatar mount for the 3D preview (falls back to a flat image when WebGL/GLB fails).
- **Success state:** Agent profile with interactive 3D avatar, live token data, and working navigation to world/embed/edit.
- **Empty / error states:** Avatar mount failure → flat-image fallback; enrich failure logged non-fatally; save errors surface inline in the edit flow.
@@ -118999,18 +123775,18 @@ modules. Routes resolved via `vercel.json` rewrites.
### Brain — Persona Builder + Multi-LLM Playground — `/brain`
- **Source:** `/workspaces/three.ws/pages/brain.html` → `/workspaces/three.ws/src/brain.js`.
- **Entry point:** `/brain` → `brain.html` (H1 "Pick a vibe", sub-copy "One tap gives your agent a personality. No extra steps."; "Build Persona" is a sidebar button), two tabs: Persona + Playground.
-- **Prerequisites / gates:** None to open the playground, but signed-out callers are limited to the free-model set (`ANON_BRAIN_PROVIDERS` in `api/brain/chat.js`: gpt-oss-120b plus the NVIDIA NIM family); every paid first-party model returns `401 "sign in to use this model"`, and anonymous traffic is rate limited. Saving a persona as a deployed agent requires sign-in (auth-hint check + `/api/agents` with credentials); an auth gate is shown if signed out. No $THREE gate.
+- **Prerequisites / gates:** None to open the playground, but signed-out callers are limited to the free-model set (`ANON_BRAIN_PROVIDERS` in `api/brain/chat.js`: gpt-oss-120b plus the NVIDIA NIM family); every paid first-party model returns `401 "sign in to use this model"`, and anonymous traffic is rate limited. `GET /api/brain/chat` reports `requiresAuth` per model alongside `available`, so the page suffixes those chips "(sign in)" for a signed-out visitor and answers a click with the notice "<model> needs an account." plus a Sign in link (`/login?redirect=/brain`) instead of failing after Send. Freeform persona extraction (`POST /api/persona/extract`) also requires sign-in (`401 "Sign in to build your persona."`; the Persona tab shows a "Sign in to build your persona" gate that clears once you sign in and return) and is metered at 5 extractions per user per day. Saving a persona as a deployed agent requires sign-in (auth-hint check + `/api/agents` with credentials). No $THREE gate.
- **Steps (6):**
1. Open `/brain`; Persona tab active, archetype presets rendered.
- 2. (optional) Apply an archetype preset or type freeform persona text → `/api/persona/extract` structures it into a persona object (tone, vocabulary, interests, dont_say, greeting).
- 3. Switch to the Playground tab; provider availability fetched from `GET /api/brain/chat`, model chips/focus selector populated.
+ 2. (optional) Apply an archetype preset or type freeform persona text → `/api/persona/extract` structures it into a persona object (tone, vocabulary, interests, communication_style, dont_say, sample_greeting); the body is validated before the daily limiter is charged, and an empty model reply comes back as a retryable `502` rather than a blank card.
+ 3. Switch to the Playground tab; provider availability fetched from `GET /api/brain/chat` (each model carries `available` and `requiresAuth`), model chips/focus selector populated.
4. Choose **Compare** mode (query several models at once) or **Focus** mode (one model); select active models.
5. Type a prompt and run; `streamProvider()` POSTs to `/api/brain/chat` per model and streams responses side-by-side, each prefixed with the effective persona system prompt.
6. (optional) Save the persona as an agent → POST `/api/agents` (or PATCH `/api/agents/:id`) with the built `system_prompt`.
- **Decision points / branches:** Compare (multi-model fan-out) vs Focus (single model); persona enabled/disabled (`personaEnabled` toggle injects/omits the system prompt); archetype preset vs freeform extraction; model availability (unavailable models disabled in selector); save-as-agent (gated by auth).
- **External calls / dependencies:** `GET /api/brain/chat` (provider availability), `POST /api/brain/chat` (per-model streaming completions), `/api/persona/extract` (structure persona), `/api/agents` + `/api/agents/:id` (load/save agent). Models span Anthropic (via Google Vertex), OpenAI (via OpenRouter), xAI Grok, DeepSeek, Qwen/DashScope, IBM watsonx, NVIDIA NIM, and Google Vertex Gemini tiers.
- **Success state:** Multiple model responses stream into the compare grid (or one in focus); persona optionally persisted locally and/or saved as a deployable agent.
-- **Empty / error states:** "Select at least one model" notice; provider-availability fetch failure is non-fatal (all models treated available); upstream stream error surfaces per-model; signed-out use of a paid model errors with a sign-in prompt; auth gate shown when saving while signed out; sessions/persona persisted to localStorage.
+- **Empty / error states:** "Select at least one model" notice; provider-availability fetch failure is non-fatal (all models treated available); upstream stream error surfaces per-model, and when every rung of a model's fallback chain fails the column shows a plain-language verdict (rate limited: try again or pick another model; no working route on this deployment; no longer served upstream; took too long) with the precise upstream reason alongside as `reason`; signed-out use of a paid model errors with a sign-in prompt; auth gate shown when saving while signed out; sessions/persona persisted to localStorage.
- **Step count:** 6 required (+2 optional)
---
@@ -119072,7 +123848,7 @@ modules. Routes resolved via `vercel.json` rewrites.
### Lip-Sync (TTS-driven) — `/lipsync`
- **Source:** `/workspaces/three.ws/public/demos/lipsync-tts.html` (vercel rewrite target `demos/lipsync-tts.html`; resolves under `public/demos/`). Inline `<script type="module">`; uses Three.js + GLTFLoader (importmap) and the `wawa-lipsync` library for viseme detection.
- **Entry point:** `/lipsync` → `lipsync-tts.html`; 3D avatar viewer (left) + text/voice controls (right).
-- **Prerequisites / gates:** None client-side (no auth, wallet, mic, or $THREE). Requires WebGL; TTS is served by the backend OpenAI integration.
+- **Prerequisites / gates:** None client-side (no auth, wallet, mic, or $THREE). Requires WebGL; TTS is served by `/api/tts/speak`, which tries the free NVIDIA NIM Magpie lane first and falls back to OpenAI.
- **Steps (6):**
1. Open `/lipsync`; avatar GLB (`/avatars/default.glb`) loads, viseme morphs wired, default text prefilled.
2. (optional) Edit the text, pick a voice and speed.
@@ -119081,7 +123857,7 @@ modules. Routes resolved via `vercel.json` rewrites.
5. Per animation frame, lipsync analyses the audio (FFT) → viseme code → mapped to avatar morph targets with EMA smoothing.
6. Avatar mouth animates in sync; viseme bar chart updates live; "Speak" re-enables when playback ends.
- **Decision points / branches:** voice + speed selection; retry on TTS failure; avatar-load failure degrades (UI still works, morphs unavailable).
-- **External calls / dependencies:** `POST /api/tts/speak` (OpenAI TTS), `GET /avatars/default.glb`, `wawa-lipsync` (client-side viseme analysis via Web Audio AnalyserNode), Three.js.
+- **External calls / dependencies:** `POST /api/tts/speak` (lane 1 NVIDIA NIM Magpie, free, 30s budget; lane 2 OpenAI `/v1/audio/speech`, the paid backstop with its own 20s budget; `503 not_configured` when neither key is set), `GET /avatars/default.glb`, `wawa-lipsync` (client-side viseme analysis via Web Audio AnalyserNode), Three.js.
- **Success state:** Avatar speaks the text with synced lips; status log confirms playback + morphs wired.
- **Empty / error states:** Actionable errors for TTS unreachable / rejected text (400) / rate limit (429) / server error (5xx); autoplay-blocked → "needs a click to play"; avatar-load failure logged but non-blocking.
- **Step count:** 6 required (+1 optional)
@@ -119116,11 +123892,11 @@ modules. Routes resolved via `vercel.json` rewrites.
2. (optional) Select an avatar.
3. Spawn in the entrance scene; move with WASD / touch joystick, look via drag.
4. Walk to the neon door → "Enter the club" prompt; activate it.
- 5. Door reveals the x402 cover screen; connect wallet and pay the cover → `POST /api/x402/club-cover` settles on-chain and checks the gate.
+ 5. Door reveals the x402 cover screen; connect wallet and pay the cover → a paid `GET /api/x402/club-cover` (x402, `club-gate.js`) settles on-chain and checks the gate.
6. On approval the rope drops; walk through to the pole stage — entrance fades, main `club.js` stage becomes active (dancers at poles, leaderboard, live tip feed).
7. Select a pole + dance style and tip → `POST /api/x402/dance-tip`; on settlement the dancer performs the routine, leaderboard + live feed update, reactions float up.
- **Decision points / branches:** avatar choice; cover approved vs "not tonight"; wallet not connected / insufficient balance; tip per pole + dance style; back-out to alley while paying; entrance-GLB failure → drop straight to stage.
-- **External calls / dependencies:** `POST /api/x402/club-cover`, `POST /api/x402/dance-tip`, `GET /api/club/tips`, SSE `/api/club/tips/stream`, `GET /api/club/leaderboard`, `/api/avatars/`, `/api/explore`; club venue/prop GLBs under `/club/...`, `/avatars/default.glb`, animation manifest/clips; `x402.js` wallet modal (Solana web3 / EVM). Three.js + post-processing.
+- **External calls / dependencies:** `GET /api/x402/club-cover` (the door; a `POST` to the same path is a separate paid read for agents, `mode: "snapshot"` for membership growth/churn or `mode: "revenue"` for the door + floor take over a `period` of 24h/7d/14d/30d/all, not part of the visitor flow), `POST /api/x402/dance-tip`, `GET /api/club/tips`, SSE `/api/club/tips/stream`, `GET /api/club/leaderboard`, `/api/avatars/`, `/api/explore`; club venue/prop GLBs under `/club/...`, `/avatars/default.glb`, animation manifest/clips; `x402.js` wallet modal (Solana web3 / EVM). Three.js + post-processing.
- **Success state:** User is inside the 3D club after paying cover; tipping plays dance routines and updates the live leaderboard/feed in real time.
- **Empty / error states:** Cover denied → "not tonight" card (with reason); wallet-not-connected / insufficient-balance errors in the x402 modal; tip/clip load failure falls back to a default clip or bind pose; tip-stream disconnect → paused-feed badge with retry; entrance-GLB failure skips the walk-in.
- **Step count:** 7 required (+1 optional)
@@ -119189,7 +123965,7 @@ modules. Routes resolved via `vercel.json` rewrites.
---
-<a id="sec-514"></a>
+<a id="sec-534"></a>
> **Source:** `docs/ux-flows/11-account-dashboard.md` · [↑ table of contents](#table-of-contents)
@@ -119223,7 +123999,7 @@ Shared auth concepts:
---
### Sign in — `/login`
-- **Source:** `public/login.html` (inline `<script>` for email/password + already-auth guard), `public/wallet-login.js` (EVM SIWE + Solana SIWS connect buttons in the on-chain drawer), `src/privy-login.js` (Privy email-OTP + Privy SIWE/SIWS), `src/auth/email-auth.js` (shared helpers).
+- **Source:** `public/login.html` (inline `<script>` for email/password + already-auth guard), `public/wallet-login.js` (EVM SIWE + Solana SIWS connect buttons in the on-chain drawer), `src/privy-login.js` (Privy email-OTP + Privy SIWE/SIWS; it also imports `solana-mobile/src/index.js`, which boots the Seed Vault / Mobile Wallet Adapter wallet inside the Seeker Android app and is a no-op everywhere else), `src/auth/email-auth.js` (shared helpers).
- **Entry point:** Direct nav to `/login`; from "Sign in" links in nav/footer; via `requireAuth()` / `requireUser()` redirects (`/login?return=…` or `?next=…`) from any gated page.
- **Prerequisites / gates:** None to view. An existing account is required for the email/password path; wallet paths can sign in an existing wallet-linked user. If `GET /api/auth/me` resolves with a user on load, the page `location.replace(next)` immediately (skipped on back/forward navigation).
- **Steps (N):**
@@ -119236,7 +124012,7 @@ Shared auth concepts:
7. `POST /api/auth/login` with `{ email, password, remember, tosAccepted: true }` (notice-style clickwrap; the legal line sits under the form), credentials included. Button shows "Signing in…".
8. On `!res.ok`: 429 → "Too many attempts…", else "Email or password is incorrect." — inline error on password field, avatar facepalm, button re-enabled.
9. On success: persist `3dagent:last-email` + auth-hint; button "Signed in — redirecting…"; avatar plays a dance; after one dance cycle (700–1800ms) `location.replace(next)`.
- 10. **(optional) Privy email-OTP path:** type email in `#privy-email-input` → click **Send code**. If the Privy app has CAPTCHA, a Cloudflare Turnstile challenge resolves first. `privy.auth.email.sendCode()` sends the code; UI advances to the code step.
+ 10. **(optional) Privy email-OTP path:** type email in `#privy-email-input` → click **Send code**. The Privy app's CAPTCHA config is read first (`src/auth/privy-captcha.js`, 6 s timeout): when one is required a Cloudflare Turnstile challenge resolves before the request, and when the config cannot be read the step stops with "We could not reach the sign-in service to check whether this step needs a CAPTCHA…" rather than sending a token-less request that Privy would reject as `invalid_credentials`. `privy.auth.email.sendCode()` sends the code; UI advances to the code step. The same check runs before the Privy EVM wallet path.
11. Enter the 6-digit code → **Verify** → `privy.auth.email.loginWithCode()` returns an `identity_token` → `POST /api/auth/privy/verify` mints the session → `location.href = next`. (optional **← Back** returns to email step.)
12. **(optional) Privy EVM wallet:** click the **EVM** chain button → `eth_requestAccounts` → `privy.auth.siwe.init()` builds the message → `personal_sign` in wallet → `privy.auth.siwe.loginWithSiwe(signature)` → `POST /api/auth/privy/verify` → redirect. Status text walks through "Requesting accounts… / Generating message… / Sign… / Signing in…".
13. **(optional) Privy Solana wallet:** click the **Solana** chain button → `provider.connect()` (Phantom/Backpack/Solflare) → `GET /api/auth/siws/nonce` → build SIWS message → `provider.signMessage` → `POST /api/auth/siws/verify` (with `x-csrf-token`) → redirect.
@@ -119245,7 +124021,7 @@ Shared auth concepts:
- **Decision points / branches:** email+password (legacy `/api/auth/login`) **vs** Privy email-OTP (`/api/auth/privy/verify`) **vs** Privy EVM SIWE **vs** Privy Solana SIWS **vs** native on-chain drawer SIWE/SIWS (`wallet-login.js`) **vs** SAML SSO. Solana chain tab auto-disables and falls back to EVM when no Solana provider is detected.
- **External calls / dependencies:** `GET /api/auth/me`, `POST /api/auth/login`, `POST /api/auth/privy/verify`, `GET /api/auth/siws/nonce`, `POST /api/auth/siws/verify`, `GET /api/config`, `/api/auth/saml/login`; Privy JS SDK (`@privy-io/js-sdk-core`, app id from `/api/config`), Cloudflare Turnstile, browser wallet providers (`window.ethereum`, `window.solana`/Phantom/Backpack/Solflare), `@three-ws/agent-ui` (avatar), model-viewer CDN.
- **Success state:** Session cookie set; auth-hint persisted; `location.replace`/`href` to `next` (default `/dashboard`).
-- **Empty / error states:** Per-field inline errors with shake + avatar facepalm; transport-failure banner on the session probe; SSO error codes from the URL (`sso_unavailable`, `saml_invalid`, `account_deleted`, `rate_limited`, etc.) and `?signed_out` notice; Privy/wallet errors map "reject/denied/cancel" to "Signature cancelled."; wallet-module load failure shows a connection error; wallet skeleton shimmer while connect buttons mount.
+- **Empty / error states:** Per-field inline errors with shake + avatar facepalm; transport-failure banner on the session probe; if `GET /api/config` fails or times out (6 s), the Privy email and wallet sections hide behind an inline "Email and wallet sign-in could not load…" notice while the password form stays usable; every Privy and SIWS network call is bounded (10 to 20 s) and a transport failure reads as "Could not reach the sign-in service"; SSO error codes from the URL (`sso_unavailable`, `saml_invalid`, `account_deleted`, `rate_limited`, etc.) and `?signed_out` notice; Privy/wallet errors map "reject/denied/cancel" to "Signature cancelled."; wallet-module load failure shows a connection error; wallet skeleton shimmer while connect buttons mount.
- **Step count:** 9 required (+6 optional)
---
@@ -119352,7 +124128,7 @@ Shared auth concepts:
4. **(optional) Theme:** click Dark/Light/Auto → `localStorage['twx_theme']` (+ `window.threeTheme.set`) → toast "Theme applied" (no API).
5. **(optional) Sessions:** "Revoke" → `DELETE /api/auth/sessions/{id}` → toast + row removed; "Revoke all other" → `DELETE /api/auth/sessions` (revokes every other session **and rotates the current session cookie**) → toast.
6. **(optional) Notifications:** "Mark all read" → `POST /api/notifications/read-all` → toast. The inbox covers the full bell vocabulary (sales, purchases, follows, remixes, DMs, coin-launch graduations, IRL, market, account).
- 6b. **(optional) Notification preferences:** a category × channel matrix driven by the server response (`categories` + `channels`, default channels in-app / push / email / Telegram). Toggles flip locally; a single **Save notification preferences** button sends the whole matrix via `PUT /api/notifications/preferences` `{ categories }` → toast "Notification preferences saved". Per-category `lockedChannels` render disabled (in-app is typically locked on); the Telegram column stays disabled ("Link a Telegram chat id to enable") until `telegram_chat_id` is set; a footer reports subscribed push devices.
+ 6b. **(optional) Notification preferences:** a category × channel matrix driven by the server response (`categories` + `channels`, default channels in-app / push / email / Telegram / avatar). The **Avatar** column routes a category to the corner companion, which walks on screen and says the message out loud while the user is on the site; a hint line under the table explains it, and it can be muted per browser from the bubble's "Turn off" control. The response also carries `type_categories` (notification type → category), so the client-side herald (`src/notification-herald.js`) gates the avatar channel with the same mapping the server uses for push and email. Toggles flip locally; a single **Save notification preferences** button sends the whole matrix via `PUT /api/notifications/preferences` `{ categories }` → toast "Notification preferences saved". Per-category `lockedChannels` render disabled (in-app is typically locked on); the Telegram column stays disabled ("Link a Telegram chat id to enable") until `telegram_chat_id` is set; a footer reports subscribed push devices.
7. **(optional) Default network:** Base/Solana/Polygon → `localStorage['twx_default_network']` + best-effort `PATCH /api/dashboard/prefs` `{ prefs: { default_network } }` → toast.
8. **(optional) Preferences:** toggle email notifications / show tips / compact sidebar → **Save preferences** → `PATCH /api/dashboard/prefs` `{ prefs }` → toast "Preferences saved".
9. **(optional) Data export:** Agents / Avatars / All → fetch `GET /api/agents`, `GET /api/avatars?limit=100`, `GET /api/widgets` → build JSON blob → browser download → toast "Data exported".
@@ -119381,7 +124157,7 @@ Shared auth concepts:
- **External calls / dependencies:** `GET /api/auth/me`, `PATCH /api/auth/profile`, `GET /api/auth/wallets`, `POST /api/auth/logout-everywhere`, `GET /api/auth/sessions`, `DELETE /api/auth/sessions/{id}`, `DELETE /api/auth/sessions`, `GET /api/auth/github/status`, `/api/auth/github/connect`, `POST /api/agents/{id}/memory-seed`, `GET`/`POST /api/agents/{id}/memory/seed/x`, `/api/auth/x/connect`, `DELETE /api/auth/me`.
- **Success state:** "Saved!" / "Saved preference." / "All other sessions revoked." inline messages (auto-hide 4s); GitHub/X "Connected" tags; account deletion redirect to `/?deleted=1`.
- **Empty / error states:** "No sessions found."; "Not connected" + connect buttons for GitHub/X; inline `.ok`/`.err` messages; delete-flow confirmation gate + error alert with button revert; "Checking…"/"Loading…" placeholders during async loads.
-- **Fixed 2026-08-06 (was: two broken writes):** the page ran on a local `fetch` helper that attached no `x-csrf-token`, so profile **Save changes** and both session revokes were rejected in production with `403 csrf_missing` while the UI still reported success; and the Danger Zone called a `DELETE /api/auth/me` the server did not implement (`me` was GET-only), so deletion always ended in the "contact support" alert. Every call on the page now goes through the shared CSRF-carrying client (`src/api.js`), a non-ok response surfaces as an error instead of a false success, and `DELETE /api/auth/me` is implemented (see [authentication.md](authentication.md#deleting-the-account)).
+- **Fixed 2026-08-06 (was: two broken writes):** the page ran on a local `fetch` helper that attached no `x-csrf-token`, so profile **Save changes** and both session revokes were rejected in production with `403 csrf_missing` while the UI still reported success; and the Danger Zone called a `DELETE /api/auth/me` the server did not implement (`me` was GET-only), so deletion always ended in the "contact support" alert. Every call on the page now goes through the shared CSRF-carrying client (`src/api.js`, which also bounds every call: 20 s for reads, 90 s for mutations, `timeoutMs` to override), a non-ok response surfaces as an error instead of a false success, and `DELETE /api/auth/me` is implemented (see [authentication.md](authentication.md#deleting-the-account)).
- **Step count:** 3 required (boot + profile load + save profile) (+5 optional tab flows)
---
@@ -119394,7 +124170,7 @@ Shared auth concepts:
---
-<a id="sec-515"></a>
+<a id="sec-535"></a>
> **Source:** `docs/ux-flows/12-home-and-content.md` · [↑ table of contents](#table-of-contents)
@@ -119417,8 +124193,8 @@ viewers), all confirmed against source.
- Other lazy mounts referenced by inline scripts: `src/avatar-drop.js`, `src/walk-embed-preview.js`, `src/pump/homepage-launcher.js`, `src/api-playground.js`, `src/forge-embed-snippets.js`, `src/erc8004/qr.js`
- Web component runtime: `<script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js">` (near the top of `<head>`) + `/model-viewer-meshopt.js` (no `/embed.js` on this page)
- Chrome: `/nav.js` + `/seasonal.js`; the footer is hardcoded inline in `home.html` (no `/footer.js` here)
-- **Entry point:** Root route. No auth. The hero `<agent-3d>` and the capability/press strips render immediately; every widget below the fold is lazy-loaded on `IntersectionObserver` to keep the initial payload light.
-- **Prerequisites / gates:** None. Fully public, no wallet/login. The mini-Forge uses an anonymous device `forge:cid` handle (localStorage); no sign-up required to generate a model. **Progressive disclosure:** first-time visitors get the "lite" page (`tws-lite` class unless `localStorage['tws:tier'] === 'full'`); nine advanced sections are tagged `data-tier="advanced"` and hidden behind an "advanced platform" gate section (`#advanced-gate`) that links each of them (sniper, capabilities, token economy, live economy, oracle, x402, dev platform, stack).
+- **Entry point:** Root route. No auth. The hero `<agent-3d>` and the capability/press strips render immediately (the capability strip is decorative: `aria-hidden` and unreachable by keyboard); every widget below the fold is lazy-loaded on `IntersectionObserver` to keep the initial payload light.
+- **Prerequisites / gates:** None. Fully public, no wallet/login. The mini-Forge uses an anonymous device `forge:cid` handle (localStorage); no sign-up required to generate a model. **Progressive disclosure:** first-time visitors get the "lite" page (`tws-lite` class unless `localStorage['tws:tier'] === 'full'`); eight advanced sections (plus the hero "Earn" bullet) are tagged `data-tier="advanced"` and hidden behind an "advanced platform" gate section (`#advanced-gate`) that links each of them (sniper, capabilities, token economy, live economy, oracle, x402, dev platform, stack).
- **Steps (the landing flow is browse-and-branch, not linear; the "required" path is reach a CTA → click → leave to a product route):**
1. Land on hero: headline "The 3D agent layer of the internet.", three hero bullets (the third, "Earn USDC per chat", is advanced-tier), a live `<agent-3d>` on stage, and the eyebrow link "New · Text → 3D is live…" → `/forge`.
2. (Optional) Forge from the hero: `#hero-forge-form` is a live text-to-3D input ("describe anything…" + **"Forge it"** button + three Try chips: low-poly fox / sci-fi helmet / ceramic teapot) that types straight into the mini-Forge, which now sits directly under the hero. An "Open the full Forge →" note links `/forge`. A `<lang-switcher>` sits under the CTA row.
@@ -119433,7 +124209,7 @@ viewers), all confirmed against source.
- Three Doors: "Start building" → `/create`; "Read the docs" → `/docs`; "Set up monetization" → `/dashboard/monetize`.
- What You Get cards: "Open viewer" → `/playground`; "Widget Studio" → `/widgets`; "Claim your subdomain" → `/dashboard/account`.
- Community Forge: "Generate yours →" → `/forge`.
- - Autonomous trading (`#home-sniper`, via `src/home-sniper.js`): "Watch the arena →" → `/arena`; "Arm a strategy" → `/oracle/arm`.
+ - Autonomous trading (`#home-sniper`, via `src/home-sniper.js`): "Watch the arena →" → `/arena`; "Arm a strategy" → `/oracle/arm`. The engine pill is honest about solvency: a `starved` engine (no wallet can fund a trade) reads "Engine out of SOL" in the down style, and a degraded fleet shows "N/M wallets funded".
- Pose Studio: "Pose Studio" → `/pose`; "Open this pose in the full studio →" → `/pose?…` (carries pose params).
- Mini Forge: "open the full Forge →" → `/forge`.
- AR: "Forge gallery"/"Generate your own model →" → `/forge`; "Open this model in AR →" → `/forge`; "Browse the avatar gallery →" → `/gallery`; "AR feature overview →" → `/features/ar`; "How AR works →" → `/blog/see-your-3d-in-ar`.
@@ -119443,7 +124219,7 @@ viewers), all confirmed against source.
- Oracle: "Open Oracle →" / "View all conviction scores →" → `/oracle`; coin cards deep-link `/oracle/coin/<mint>`.
- Pay-per-call: "Configure monetization →" → `/dashboard/monetize`.
- Walk: "See walk mode →" → `/temporary` (the `/walk` route still exists but home points at `/temporary`).
- - Developer platform: "Get a key ↗"/"Get API key →" → `/dashboard/api`; "Docs" → `/docs`; "GitHub" → github.com/nirholas/three.ws; "OpenAPI" → `/api/openapi-json.js` (currently a dead link; only `/openapi.json` is routed); "MCP server" → `/docs/mcp`.
+ - Developer platform: "Get a key ↗"/"Get API key →" → `/dashboard/api`; "Docs" → `/docs`; "GitHub" → github.com/nirholas/three.ws; "OpenAPI" → `/openapi.json` (the routed spec; the handler is `api/openapi-json.js`); "MCP server" → `/docs/mcp`.
- The Stack: Studio → `/studio`; Registry → `/discover`; Embed → `/docs`; Pay-per-call → `/dashboard/monetize`; Walk → `/temporary`; SDK → `/docs/sdk`.
- Showcase 3D: "Browse all" → `/discover`; "Make your own" → `/create`.
- Avatar Drop & Vclose: "Build your agent →" → `/create`; "Text → 3D" → `/forge`; "Read the docs" → `/docs`.
@@ -119455,9 +124231,9 @@ viewers), all confirmed against source.
- **Pose Studio (`#home-pose`, `src/home-pose.js`)** — drag-to-orbit rig, joint sliders, preset chips, reset/snapshot/copy-link/open-studio buttons.
- **AR (`#home-ar`)**: `<model-viewer>` with `ar` modes (webxr/scene-viewer/quick-look), desktop QR (lazy `src/erc8004/qr.js`), model cycling (fed by a top-sorted `/api/forge-gallery` fetch).
- **Live token card (`#hlt-card`, `src/home-live-token.js`)** — real Pump.fun data; plus homepage launcher.
- - **Oracle feed**: `GET /api/oracle/feed?network=mainnet&limit=6&min_score=56`, renders top conviction coins ("Oracle is warming up…" empty state; error state renders an "Open Oracle →" button).
- - **Community Forge gallery**: a live, sortable browse loop over `GET /api/forge-gallery?scope=community&…limit=24`: Fresh/Trending tabs (`sort=fresh` vs `sort=top&window=week`), a 25s background refresh that prepends genuinely-new models on Fresh (with a live chip), prompt-based dedupe, and a "Show more" button (12 shown initially, up to 24).
- - **Showcase 3D grid**: `GET /api/explore?source=avatar&only3d=1&category=avatar,creature&limit=24&quality=high` (via `src/home-live-agents.js`), agent cards + CTA cards.
+ - **Oracle feed**: `GET /api/oracle/feed?network=mainnet&limit=6&min_score=56`, renders top conviction coins ("Oracle is warming up…" empty state; error state renders an "Open Oracle →" button). During a database outage the endpoint answers `503` with `Retry-After` instead of a confident empty feed, so the section shows the error state rather than a dead market presented as fact.
+ - **Community Forge gallery**: a live, sortable browse loop over `GET /api/forge-gallery?scope=community&…limit=24`: Fresh/Trending tabs (`sort=fresh` vs `sort=top&window=week`), a 25s background refresh that prepends genuinely-new models on Fresh (with a live chip), prompt-based dedupe, and a "Show more" button (12 shown initially, up to 24). Cards paint as poster images and upgrade to the live rotating mesh only as they near the viewport; community cards stay as posters.
+ - **Showcase 3D grid**: `GET /api/explore?source=avatar&only3d=1&category=avatar,creature&limit=24&quality=high` (via `src/home-live-agents.js`), agent cards + CTA cards; each card links the item's `detailUrl` (the canonical `/avatars/<id>` detail page with chat, skills, embed and launch actions), not the bare GLB viewer.
- **Other live agents** — What-You-Get viewer (50+ animation chips), Bento mini-agents, Vclose agent, Avatar Drop canvas, Walk preview canvas.
- **External calls / dependencies:** `POST/GET /api/forge` (+ `?catalog`/`?health` for the options panel), `GET /api/forge-gallery`, `GET /api/explore`, `GET /api/oracle/feed`; Pump.fun feed (live token card); `agent-3d` runtime + Google `model-viewer` CDN (lazy). Solana RPC indirectly via the launcher.
- **Success state:** User reaches and clicks a CTA into a product route, or completes an in-page demo (e.g. a forged model rendered with a working toolbar; an embed snippet copied).
@@ -119488,7 +124264,7 @@ viewers), all confirmed against source.
- **Source:** `pages/status.html` (dynamic).
- **Entry point:** `vercel.json` `/status → /status.html`.
- **Prerequisites / gates:** None.
-- **Steps (4):** 1) On load, fetch `GET /api/status` and render service cards (status dot, uptime %, avg latency, 90-day history bar). 2) Auto-poll every 5 min (`setInterval`, 300000 ms) updating the `aria-live` banner ("All systems operational" ↔ "X of Y services disrupted"). 3) Hover/focus a 90-day history cell for per-day tooltip. 4) Read the live build stamp: a `GET /api/version` fetch fills `#st-build` with the live commit (linked to GitHub), version, Cloud Run revision, and build time; it stays hidden if the endpoint is unreachable. Footer links to the SVG status badge (`/api/status?format=svg`) and `/changelog`.
+- **Steps (4):** 1) On load, fetch `GET /api/status` and render service cards (status dot, uptime %, avg latency, 90-day history bar); a subsystem that publishes structured `metrics` (today the agent index) also renders metric pills beside its sentence: Solana lag, Solana agents, EVM lag, Events indexed (`subMetrics`). 2) Auto-poll every 5 min (`setInterval`, 300000 ms) updating the `aria-live` banner ("All systems operational" ↔ "X of Y services disrupted"). 3) Hover/focus a 90-day history cell for per-day tooltip. 4) Read the live build stamp: a `GET /api/version` fetch fills `#st-build` with the live commit (linked to GitHub), version, Cloud Run revision, and build time; it stays hidden if the endpoint is unreachable. A "Last check …" stamp (`#st-checked`) sits beside the cadence sentence. Footer links to the SVG status badge (`/api/status?format=svg`) and `/changelog`.
- **External calls:** `GET /api/status`, `GET /api/version`.
- **Success state:** Live service grid rendered with current operational status + "last check" timestamp.
- **Empty / error states:** Skeleton loaders on first paint; on fetch failure renders an error message with retry guidance.
@@ -119503,13 +124279,13 @@ viewers), all confirmed against source.
### Support — `/support`
- **Source:** `pages/support.html` (static).
- **Entry point:** `vercel.json` `/support → /support.html`.
-- **Steps (5):** 1) Read intro/channels. 2) Copy a contact email via `.copy-btn` (support, security, partnerships, privacy, legal, dmca, abuse @three.ws) → clipboard, "Copied ✓" 1600ms; clipboard-blocked fallback opens `mailto:`. 3) Open a channel card (GitHub Issues / Discussions — new tab). 4) Use a `mailto:` link. 5) Hover channel cards (border/translate/arrow microinteractions).
+- **Steps (5):** 1) Read intro/channels. 2) Copy a contact email via `.copy-btn` (support, security, partnerships, privacy, legal, dmca, abuse @three.ws) → clipboard, "Copied ✓" 1600ms; clipboard-blocked fallback opens `mailto:`. 3) Open a channel card in a new tab: GitHub Issues for bugs and feature requests, or "Questions & help", which opens a question issue template (`issues/new?template=question.yml`) in the same tracker; Discussions is no longer a channel. 4) Use a `mailto:` link. 5) Hover channel cards (border/translate/arrow microinteractions).
- **Notes:** No contact form / no backend submission — email links + copy buttons only. No API.
### Events — Build 3D Agents Live — `/events/build-3d-agents-live`
- **Source:** `pages/events/build-3d-agents-live.html` (static + realtime; `/embed.js`, `/footer-newsletter.js`).
- **Entry point:** `vercel.json` `/events/([a-z0-9-]+) → /events/$1.html`.
-- **Steps (5):** 1) The countdown block reflects event phase (event was 2026-06-23 18:00 MT, 60 min, online; rAF tick → days/hrs/min/sec pre-event; "LIVE NOW" during; since EVENT_END passed it now renders the post-event headline "Thanks for joining" with the sub-label "replay coming soon"; no replay link exists yet). 2) Add to calendar (`#add-cal`/`#add-cal-2` build a Google Calendar render URL from EVENT_START/END, now a past date). 3) RSVP email signup (`#rsvp-form`, `data-newsletter-form` → `POST /api/newsletter/subscribe`, aria-live result). 4) Interact with the lazy-loaded hero `<agent-3d>` (deferred via `requestIdleCallback` → `/embed.js`). 5) Scroll-reveal sections.
+- **Steps (5):** 1) The countdown block reflects event phase (event was 2026-06-23 18:00 MT, 60 min, online; rAF tick → days/hrs/min/sec pre-event; "LIVE NOW" during; since EVENT_END passed it now renders the post-event headline "Thanks for joining" with the sub-label "this session has aired"; no replay link exists). Past-event mode also swaps the eyebrow to "Past event · hosted by three.ws" and strips the upcoming-event i18n hooks so the translation pass cannot paint the old copy back. 2) Add to calendar (`#add-cal`/`#add-cal-2` build a Google Calendar render URL from EVENT_START/END, re-applied on every `i18n:change`); both calendar controls are hidden once the event has passed, since adding a past event is a dead path. 3) RSVP email signup (`#rsvp-form`, `data-newsletter-form` → `POST /api/newsletter/subscribe`, aria-live result); after the event the section reads "Next session" / "Hear about the next live build" and asks for an email for the next scheduled session. 4) Interact with the lazy-loaded hero `<agent-3d>` (deferred via `requestIdleCallback` → `/embed.js`). 5) Scroll-reveal sections.
- **Notes:** Schema.org Event. Countdown is local (no API); only newsletter POSTs.
### Legal hub and policy documents - `/legal`, `/legal/privacy`, `/legal/tos`, `/legal/eula`, `/legal/content-policy`, `/legal/risk`
@@ -119541,21 +124317,21 @@ viewers), all confirmed against source.
- **Steps (5):** 1) Read hero (title/meta from manifest). 2) Hero CTA (manifest-driven, e.g. "Open the Forge"). 3) Read article: markdown fetched `GET /docs/tutorials/<slug>.md`, parsed with marked + highlight.js; per-`<pre>` **copy code** buttons ("Copy" → "Copied" 1700ms); `figure:` directives in the markdown resolve to real captured images via `/tutorial-figures.js` + `/tutorial-figures.css` (pipeline shared with the cookbook recipe viewer). 4) Use the sticky TOC (scroll-spy) and heading anchors. 5) Prev/Next pager (adjacent manifest entries); back-to-top button + top progress bar.
- **External calls:** `GET /docs/tutorials/<slug>.md`.
- **Success state:** Rendered article with working TOC, copy buttons, and pager.
-- **Empty / error states:** "Page not found." on failed markdown fetch.
+- **Empty / error states:** "Tutorial not found" on an unknown slug or failed markdown fetch.
- **Step count:** 1 required (read) (+4 optional: CTA, copy, TOC nav, pager).
- **Notes:** text-to-3d & image-to-3d tutorials use this same template (covered elsewhere).
### Docs (index + all subpages) — `/docs`, `/docs/start-here`, `/docs/make-your-agent`, `/docs/share-and-embed`, `/docs/do-i-need-crypto`, `/docs/quick-start`, `/docs/agent-system`, `/docs/erc8004`, `/docs/embedding`, `/docs/web-component`, `/docs/mcp`, `/docs/skills`, `/docs/api-reference`, `/docs/sdk`, `/docs/listings` (and ~50 more)
- **Source:** Single SPA shell `docs/index.html` (served for `/docs`, `/docs/`, and `/docs/<slug>` per `vercel.json`); markdown content in `docs/*.md` and `docs/tutorials/*.md`. Marked + highlight.js via CDN.
- **Entry point:** `vercel.json` `/docs → /docs/index.html`, `/docs/([^./]+) → /docs/index.html` (the slug becomes a hash route). `currentPath()` reads `location.hash` (or `/docs/<slug>`), defaulting to `start-here`.
-- **Steps (4):** 1) Land: the sidebar NAV is loaded from `GET /docs/nav.json` (currently 14 sections / ~273 links, with a designed failure state if the manifest 404s) + `start-here.md` fetched & rendered. 2) Sidebar **search** live-filters the nav by label AND surfaces a full-text results panel fed by the docs search index (with a Clear search control). 3) Click a sidebar link → hash route → `GET /docs/<slug>.md` rendered (headings get anchor IDs; internal `.md` links rewritten to hash routes; code highlighted). 4) Per-page tools: "Copy page" (markdown to clipboard), "View as Markdown" (`/docs/<slug>.md` new tab), "Open in Claude" (`claude.ai/new?q=…`); Prev/Next pager; mobile sidebar FAB/overlay; a lazy doc-freshness banner (`/doc-freshness.js`, backed by `public/docs-freshness*.json`).
+- **Steps (4):** 1) Land: the sidebar NAV is loaded from `GET /docs/nav.json` (currently 14 sections / ~286 links, with a designed failure state if the manifest 404s) + `start-here.md` fetched & rendered. 2) Sidebar **search** live-filters the nav by label AND surfaces a full-text results panel fed by the docs search index (with a Clear search control). 3) Click a sidebar link → hash route → `GET /docs/<slug>.md` rendered (headings get anchor IDs; internal `.md` links rewritten to hash routes; code highlighted). 4) Per-page tools: "Copy page" (markdown to clipboard), "View as Markdown" (`/docs/<slug>.md` new tab), "Open in Claude" (`claude.ai/new?q=…`); Prev/Next pager; mobile sidebar FAB/overlay; a lazy doc-freshness banner (`/doc-freshness.js`, backed by `public/docs-freshness*.json`).
- **External calls:** `GET /docs/nav.json`; `GET /docs/<slug>.md` per page (e.g. `do-i-need-crypto.md`, `quick-start.md`, `agent-system.md`, `erc8004.md`, `embedding.md`, `web-component.md`, `mcp.md`, `skills.md`, `api-reference.md`, `sdk.md`, `listings.md`, `make-your-agent.md`, `start-here.md`); marked + highlight.js CDNs.
- **Empty / error states:** Loading dots during fetch; "Page not found." on a missing slug; a designed nav-manifest failure state.
- **Notes:** Nearly all `/docs/*` slugs share this one SPA; the route is one repeated pattern: navigate (hash/sidebar/search) → fetch markdown → render, with copy-page + pager + TOC behaviors. Real steps per page = 1 required (read) +3 optional (search, copy-page, pager). **Exceptions mapped before the generic rule:** `/docs/widgets` (standalone page, below), `/docs/3d-api` → `/3d.html`, `/docs/agent-3d` → 308 → `/docs/web-component`, and the `/docs/walk*` family.
### Docs — Widgets (standalone) — `/docs/widgets`
- **Source:** `public/docs-widgets.html` (static; `vercel.json` `/docs/widgets → /docs-widgets.html`, mapped *before* the generic `/docs/*` rule).
-- **Steps (4):** 1) TOC anchor nav (`#quick-start`, `#widget-types`, `#urls`, `#embedding`, `#postmessage-api`, `#og-oembed`, `#csp-cors`, `#privacy`, `#faq`). 2) Read code blocks (iframe/script/oEmbed/postMessage). 3) Review reference tables (widget types, URL schemes, hash params, postMessage events, OG/oEmbed). 4) Follow links (`/studio`, `/widgets`, `/docs/deployment`, oembed.com); footer `<model-viewer>` demo (`/animations/robotexpressive.glb`).
+- **Steps (4):** 1) TOC anchor nav (`#quick-start`, `#widget-types`, `#urls`, `#embedding`, `#postmessage-api`, `#og-oembed`, `#csp-cors`, `#privacy`, `#faq`). 2) Read code blocks (iframe/script/oEmbed/postMessage). 3) Review reference tables (widget types, URL schemes, hash params, postMessage events, OG/oEmbed). 4) Follow links (`/studio`, `/widgets`, `/docs/deployment`, oembed.com). The former footer `<model-viewer>` demo is gone; the page loads the model-viewer runtime but renders no demo of its own.
- **Notes:** Pure static docs, no API. Distinct from the docs SPA.
### Blog index — `/blog`
@@ -119563,15 +124339,15 @@ viewers), all confirmed against source.
- **Entry point:** `/blog`.
- **Prerequisites / gates:** None.
- **Steps (2):** 1) Scan the hardcoded list of 35 post cards (each shows title, date, informational tag). 2) Click a post → `/blog/<slug>`. (Also: RSS link `/rss/announcements.xml`; X/GitHub external links.)
-- **Decision points / branches:** 35 indexed posts → individual article routes (37 post files exist; two are routable but unlinked from the index); RSS / social out.
+- **Decision points / branches:** 35 indexed posts → individual article routes (38 post files exist; three are routable but unlinked from the index); RSS / social out.
- **External calls:** None — fully static list (no fetch, no pagination, no filter/search). Tags are display-only, not filterable.
- **Success state:** User opens an article.
- **Empty / error states:** N/A (static).
- **Step count:** 1 required (click a post) (+ optional RSS/social).
-### Blog posts (37): `/blog/<slug>`
-- **Source:** `blog/<slug>.html`: 37 routable static HTML files, all on **one shared template** (`.post-wrap`, `.post-meta`, `.post-tag`, shared nav/footer containers). Routed via `vercel.json` `/blog/([a-z0-9-]+) → /blog/$1.html`. One legacy slug redirects: `/blog/all-90-trades` 308s to `/blog/autonomous-trading-experiment`.
-- **Slugs:** the routable set is exactly the `blog/*.html` filenames (37 today; enumerate with `ls blog/*.html`), which rots less than restating the list here. (`three-ws-alibaba-cloud-partnership` and `three-ws-play-coin-communities` are routable but not linked from the index.)
+### Blog posts (38): `/blog/<slug>`
+- **Source:** `blog/<slug>.html`: 38 routable static HTML files, all on **one shared template** (`.post-wrap`, `.post-meta`, `.post-tag`, shared nav/footer containers). Routed via `vercel.json` `/blog/([a-z0-9-]+) → /blog/$1.html`. One legacy slug redirects: `/blog/all-90-trades` 308s to `/blog/autonomous-trading-experiment`.
+- **Slugs:** the routable set is exactly the `blog/*.html` filenames (38 today; enumerate with `ls blog/*.html`), which rots less than restating the list here. (`three-ws-alibaba-cloud-partnership`, `three-ws-play-coin-communities` and `ibm-user-group-first-in-world-meetup-recap` are routable but not linked from the index.)
- **Steps (1):** Read the article; follow the "← Blog" back link, inline links, and the occasional primary CTA (e.g. text-to-3d post → "Try Forge — type a prompt →" → `/forge`).
- **Notes:** Repeated "read article" pattern. No embedded 3D demos / share / TOC / newsletter inside the post body in the sampled pages; copy-button CSS exists in the template but the sampled posts have no code blocks. No API.
- **Source not exposed:** Several `.md` files under `blog/` (drafts and source material such as `decision-optimization-3d-ai-crypto.md`, `internets-second-species.md`, `we-are-the-provider.md`, the autonomous-trading X drafts, plus `README.md`) are NOT routed (no rule maps `.md` blog slugs) and are not in the index; source material only, not live pages.
@@ -119588,9 +124364,9 @@ viewers), all confirmed against source.
- **Notes:** The header carries the subscribe row (`/changelog.xml` RSS, `/changelog.json`, `/llms.txt`, `/sitemap`). Delivery to the holders' Telegram channel is handled by the `changelog-push` cron off the same feed, not by this page.
### News index and articles - `/news`, `/news/<slug>`
-- **Source:** `public/news/index.html` plus 110 static article files `public/news/<slug>.html`.
+- **Source:** `public/news/index.html` plus 112 static article files `public/news/<slug>.html`.
- **Entry point:** `vercel.json` `/news → /news/index.html`, `/news/([a-z0-9_-]+)/? → /news/$1.html`. The home page's press strip links straight into individual `/news/*` slugs, so most arrivals skip the index.
-- **Steps (2):** 1) Scan the index: 110 hardcoded `post-link` cards, newest first, each with a `<time>` date, headline, summary paragraph, and a display-only tag list. 2) Click through to an article and read it; a "News" breadcrumb returns to the index, and inline links point at product routes.
+- **Steps (2):** 1) Scan the index: 112 hardcoded `post-link` cards, newest first, each with a `<time>` date, headline, summary paragraph, and a display-only tag list. 2) Click through to an article and read it; a "News" breadcrumb returns to the index, and inline links point at product routes.
- **External calls:** None. Fully static: no fetch, no pagination, no search, and the tags are not filterable.
- **Success state:** User reads the announcement and follows its product link.
- **Empty / error states:** N/A (static).
@@ -119623,7 +124399,9 @@ Agent/crawler endpoints — not user UX (0 user steps). All resolve via `vercel.
| Agent attestation schemas | `/.well-known/agent-attestation-schemas` | `/api/wk?name=agent-attestation-schemas` | ERC-8004 attestation schema descriptors |
| OAuth AS metadata | `/.well-known/oauth-authorization-server` | `/api/wk?name=oauth-authorization-server` | OAuth 2.0 Authorization Server metadata |
| OAuth protected resource | `/.well-known/oauth-protected-resource` (also under `/api/mcp/`) | `/api/wk?name=oauth-protected-resource` | OAuth 2.0 Protected Resource metadata |
-| Chat plugin manifest | `/.well-known/chat-plugin.json` | `/api/wk?name=chat-plugin` | AI chat-plugin manifest |
+| Chat plugin manifest | `/.well-known/chat-plugin.json` | `/api/wk?name=chat-plugin` | AI chat-plugin manifest (the real LobeChat manifest) |
+| Sperax plugin manifest | `/.well-known/sperax-plugin.json` | `/api/wk?name=sperax-plugin` | Sperax plugin manifest |
+| Apple app-site association | `/.well-known/apple-app-site-association` | `/api/wk?name=apple-app-site-association` | iOS universal-link association for the App Store shell |
| Vanity metadata | `/.well-known/three-vanity.json` | `/api/wk?name=three-vanity` | Vanity-wallet discovery metadata |
| JWKS | `/.well-known/jwks.json` | `/api/auth/persona/[action]?action=jwks` | Signing keys |
| DID document | `/.well-known/did.json` | `/api/x402/did` | x402 DID document |
@@ -119634,7 +124412,7 @@ All `/.well-known/*` and `/openapi.json` / `/sitemap.xml` responses are JSON/XML
---
-<a id="sec-516"></a>
+<a id="sec-536"></a>
> **Source:** `docs/validation.md` · [↑ table of contents](#table-of-contents)
@@ -119837,7 +124615,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-190) 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-196) for the platform's own automatic attestation flow.
The minimum check suite for a `pass` verdict includes:
@@ -120013,7 +124791,7 @@ The toggle's CSS class reflects the highest severity: `level-0` (errors), `level
---
-<a id="sec-517"></a>
+<a id="sec-537"></a>
> **Source:** `docs/vanity.md` · [↑ table of contents](#table-of-contents)
@@ -120021,7 +124799,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-563) rail and the
+no account, and no SOL. Pay per call in USDC over the [x402](#sec-589) rail and the
server grinds (or delivers from stock) a brand-new keypair that matches.
| Endpoint | What it is | Chars | Price | Pick it when |
@@ -120039,7 +124817,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-351) draws from the
+address from the catalog." [Pump Launcher](#sec-364) draws from the
same warehouse for instant vanity mint addresses.
## Which agent uses this, and why us
@@ -120193,7 +124971,7 @@ chars** and priced $0.02–$0.40. `sealTo` is strongly recommended here. Verify
`@three-ws/solana-agent`'s `verifyVanityReceipt()`, the CLI
(`scripts/verify-vanity-receipt.mjs`), or [`/vanity/verify`](https://three.ws/vanity/verify).
-The full wire format is specified in [PROTOCOL-vanity.md](#sec-005).
+The full wire format is specified in [PROTOCOL-vanity.md](#sec-006).
---
@@ -120241,7 +125019,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-351).
+atomicity, no separate purchase step. See [pump-launcher.md](#sec-364).
---
@@ -120256,20 +125034,20 @@ challenges and the discovery doc stay in parity.
## Related
-- [x402 endpoints overview](#sec-559)
-- [three-vanity/v1 protocol spec](#sec-005)
-- [Pump Launcher](#sec-351) — accepts an optional vanity mint prefix/suffix
+- [x402 endpoints overview](#sec-584)
+- [three-vanity/v1 protocol spec](#sec-006)
+- [Pump Launcher](#sec-364) — 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-518"></a>
+<a id="sec-538"></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-425), 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-443), 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`.
@@ -120297,7 +125075,7 @@ Two GETs are worth calling out because the pattern is easy to get wrong: `/api/v
Every write accepts either form of credential:
- **Session cookie**, as the browser does it. A one-time CSRF token is then required in `X-CSRF-Token`; get one from `GET /api/csrf-token`. A missing or stale token is `403 csrf_missing` / `403 csrf_invalid`.
-- **API key** (`Authorization: Bearer sk_live_...`), for scripts and servers. Bearer callers are CSRF-exempt because the token is itself the proof of intent. See [authentication.md](#sec-103) for minting one.
+- **API key** (`Authorization: Bearer sk_live_...`), for scripts and servers. Bearer callers are CSRF-exempt because the token is itself the proof of intent. See [authentication.md](#sec-105) for minting one.
Every write is also rate limited per user at 30 per minute, and the limiter fails closed: if the shared limiter backend is unreachable in production the write is refused rather than silently uncapped.
@@ -120305,9 +125083,9 @@ The examples below use an API key in `$API_KEY`.
## Opening a vault
-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.
+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-057) 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-171)). 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-074) and [custody.md](#sec-177)). 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`.
@@ -120340,9 +125118,9 @@ 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-503)). 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-523)). 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.
+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. A signed-in user with no agents gets a disabled form pointing at [/create](https://three.ws/create) instead of a submit that can only fail.
## How the money is priced
@@ -120542,7 +125320,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-171).
+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-177).
## Reading a vault
@@ -120573,16 +125351,16 @@ Two honest limits a backer should know: the platform can sign for the vault (tha
## Related
-- [trading-arenas.md](#sec-425) 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-171) for spend limits, the freeze switch, and proof of custody
-- [user-wallet.md](#sec-503) 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
+- [trading-arenas.md](#sec-443) for the product overview of vaults and the surfaces around them
+- [agent-wallets.md](#sec-074) for the custodial wallet a backer funds from
+- [custody.md](#sec-177) for spend limits, the freeze switch, and proof of custody
+- [user-wallet.md](#sec-523) for the per-user master wallet, the easiest way to send a vault its fee SOL
+- [agent-reputation.md](#sec-057) for the badge that gates opening a vault
+- [authentication.md](#sec-105) for sessions, CSRF tokens, and API keys
---
-<a id="sec-519"></a>
+<a id="sec-539"></a>
> **Source:** `docs/viability.md` · [↑ table of contents](#table-of-contents)
@@ -120750,7 +125528,7 @@ appears only when there is something to show, pointing at the filtered
- **Marketplace windows are 24 hours and 7 days; trading windows are 24 hours and
7 days, with realized P&L over 7 days.** There is no lifetime total on this
page. For the all-time agent-to-agent figure, see
- [Agent Economy Volume](#sec-052).
+ [Agent Economy Volume](#sec-053).
- **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.
@@ -120762,17 +125540,17 @@ appears only when there is something to show, pointing at the filtered
## Related
-- [The autonomous economy](#sec-104): the wallets, spend policies,
+- [The autonomous economy](#sec-106): the wallets, spend policies,
paid skills, and trading loops whose real activity this page measures.
-- [x402 paid endpoints](#sec-559): the platform's own endpoint
+- [x402 paid endpoints](#sec-584): 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
+- [Agent Economy Volume](#sec-053): the agent-to-agent USDC
roll-up, the third public money surface alongside this one.
---
-<a id="sec-520"></a>
+<a id="sec-540"></a>
> **Source:** `docs/viewer.md` · [↑ table of contents](#table-of-contents)
@@ -121166,7 +125944,7 @@ A subset of state (background, transparency, background color, auto-rotate, expo
---
-<a id="sec-521"></a>
+<a id="sec-541"></a>
> **Source:** `docs/voice-lab.md` · [↑ table of contents](#table-of-contents)
@@ -121196,7 +125974,7 @@ An agent that speaks in a generic stock voice is a demo. An agent that speaks in
| OpenAI | 11 | Credits | `gpt-4o-mini-tts` also takes a direction. |
| ElevenLabs | your account + the public library | Credits or BYOK | The only lane that can clone your voice. |
-The `providers` array from `GET /api/tts/catalog` is the source of truth: it reports, per lane, whether this deployment can actually serve it and why not when it cannot, which models it offers, and whether it accepts a direction. The picker renders unavailable lanes with their reason rather than hiding them.
+The `providers` array from `GET /api/tts/catalog` is the source of truth: it reports, per lane, whether this deployment can actually serve it and why not when it cannot, which models it offers, and whether it accepts a direction. The picker renders unavailable lanes with their reason rather than hiding them: the lane pill stays fully legible (a greyed billing badge and a not-allowed cursor carry the state, never a faded label) and its `aria-label` reads the lane name plus the reason, so a screen reader hears what to do about it.
### The ElevenLabs Voice Library
@@ -121268,7 +126046,7 @@ curl -X POST 'https://three.ws/api/tts/eleven' \
--output hello.mp3
```
-Note that agent-assigned voices always run on the platform account (the agent speaks server-side, where your browser key is not present), so a voice you want an agent to use must be cloned on the platform rungs, not under BYOK.
+Agent-assigned voices have their own rung. When an agent's voice was bound with the owner's saved ElevenLabs key (`agent_identities.voice_key_source = 'owner'`, set by `PUT /api/agents/:id/voice`), `/api/tts/eleven` with that `agentId` serves the clip on the owner's account (`x-tts-billing: agent_byok`), including to signed-out visitors on the chat and embed surfaces, rate-limited per IP; the requested `voiceId` must be the agent's own bound voice, so the credential can never be borrowed to synthesize anything else. An agent bound on the platform key speaks on the `credits` rung instead, and the agent lane falls back to that cleanly when the owner's key is absent. Your browser-side `x-eleven-key` is never involved in agent speech, so a voice an agent should use must be cloned either on the platform rungs or with the key you have saved to your account, not with a key that only lives in `localStorage`.
## Walkthrough
@@ -121324,18 +126102,18 @@ The agent-voice handler ([`api/agents/_id/voice.js`](../api/agents/_id/voice.js)
- **"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. 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.
+- **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. The ElevenLabs voice-list and voice-delete calls go through the shared `fetchUpstream` with a 10 s deadline and two attempts, so a slow upstream degrades the lane to empty-with-a-reason instead of holding the catalog request open.
## Related
-- [Voice and lipsync tutorial](#sec-496): the authoritative step-by-step, including wiring a cloned voice into an agent.
-- [Lipsync](#sec-267): how synthesized speech drives an avatar's mouth in real time.
-- [Talking Avatar Video](#sec-415): render a talking-head clip from an avatar and an audio track.
+- [Voice and lipsync tutorial](#sec-516): the authoritative step-by-step, including wiring a cloned voice into an agent.
+- [Lipsync](#sec-279): how synthesized speech drives an avatar's mouth in real time.
+- [Talking Avatar Video](#sec-433): 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-522"></a>
+<a id="sec-542"></a>
> **Source:** `docs/walk-leaderboard.md` · [↑ table of contents](#table-of-contents)
@@ -121459,7 +126237,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-527) 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-548) issue agent-signed proofs of physical presence with server-derived co-location.
---
@@ -121625,14 +126403,14 @@ The anonymous id is generated and persisted by the walk runtime in `localStorage
## Related
-- [Add the Walk Companion to your site](#sec-497), 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-517), 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-527), for movement claims that carry a verifiable agent signature rather than a leaderboard rank.
+- [World Lines](#sec-548), for movement claims that carry a verifiable agent signature rather than a leaderboard rank.
---
-<a id="sec-523"></a>
+<a id="sec-543"></a>
> **Source:** `docs/web-component.md` · [↑ table of contents](#table-of-contents)
@@ -121740,7 +126518,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-393), and the
+vocabulary are documented in [Sign language](#sec-411), and the
alphabet is browsable at [/asl-alphabet](https://three.ws/asl-alphabet).
### Skills and memory
@@ -122591,7 +127369,7 @@ defineElement('my-agent');
---
-<a id="sec-524"></a>
+<a id="sec-544"></a>
> **Source:** `docs/widget-api.md` · [↑ table of contents](#table-of-contents)
@@ -122798,7 +127576,7 @@ If you have multiple widgets and want to coordinate them (sync camera, broadcast
---
-<a id="sec-525"></a>
+<a id="sec-545"></a>
> **Source:** `docs/widget-studio.md` · [↑ table of contents](#table-of-contents)
@@ -123042,14 +127820,14 @@ You can override these freely in the iframe `width` and `height` attributes. Add
## Next steps
-- [Widget API (JSON-RPC)](#sec-524) — programmatic control over an embedded widget: camera, animation, screenshots, model loading
-- [Widgets reference](#sec-526) — technical details, postMessage API, CSP config, and oEmbed spec
-- [Web component](#sec-523) — the `<agent-3d>` custom element for developer integrations
-- [Embedding guide](#sec-187) — advanced embedding patterns and iframe options
+- [Widget API (JSON-RPC)](#sec-544) — programmatic control over an embedded widget: camera, animation, screenshots, model loading
+- [Widgets reference](#sec-546) — technical details, postMessage API, CSP config, and oEmbed spec
+- [Web component](#sec-543) — the `<agent-3d>` custom element for developer integrations
+- [Embedding guide](#sec-193) — advanced embedding patterns and iframe options
---
-<a id="sec-526"></a>
+<a id="sec-546"></a>
> **Source:** `docs/widgets.md` · [↑ table of contents](#table-of-contents)
@@ -123462,7 +128240,7 @@ The `config` object is validated against the type's schema (see [widget-types.js
**Widget share URL:** Every widget has a canonical share URL at `https://three.ws/w/<id>`. This URL is server-rendered with Open Graph metadata and a 1200×630 preview image, making it safe to post in Slack, Discord, X, or any link-preview-aware surface.
-For the full API reference including request/response shapes, error codes, and pagination, see [api-reference.md](#sec-096).
+For the full API reference including request/response shapes, error codes, and pagination, see [api-reference.md](#sec-098).
---
@@ -123554,7 +128332,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-524) 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-544) reference. The `ThreeWidget` SDK lives at `/widget-client.js` and works with any iframe pointing at `/widget`.
---
@@ -123567,7 +128345,200 @@ Need to drive a widget from the parent page — change the camera, play an anima
---
-<a id="sec-527"></a>
+<a id="sec-547"></a>
+
+> **Source:** `docs/witness.md` · [↑ table of contents](#table-of-contents)
+
+# Witness: bug reports that arrive as failing tests
+
+A bug report is a description of an experiment somebody else has to reconstruct.
+The reconstruction is the expensive part, it is where most reports die, and it is
+the part a machine can do.
+
+`@three-ws/witness` records what a person actually did, and compiles it into a
+Playwright spec that is **red while the bug exists and green once it is fixed**.
+
+- Package: [`packages/witness/`](../packages/witness) (`@three-ws/witness`, Apache-2.0, no dependencies)
+- On three.ws: the corner companion attaches a trace to every report, and
+ [`/feedback`](#sec-228) hands you the compiled test with one click.
+- Standalone: it works on any site, with or without the rest of three.ws.
+
+## The idea in one screen
+
+```
+The visitor's session The compiled spec
+───────────────────── ─────────────────
+goto /avatar-studio await page.goto('/avatar-studio');
+click the button "Export" await page.getByTestId('export').click();
+fill "Model name" (11 chars) await page.getByLabel('Model name').fill('xxxxxxxxxxx');
+click the button "Download" await page.getByRole('button', { name: 'Download' }).click();
+xhr POST /api/export -> 500 expect(failedRequests).toEqual([]); <- RED
+error TypeError: exportGLB is not a fn expect(pageErrors).toEqual([]); <- RED
+```
+
+The last two lines are the whole design. The spec asserts the failure is **gone**,
+not that it happened. A recorder that emitted `expect(status).toBe(500)` would
+write a test that passes while the site is broken and fails once it is fixed,
+which is worse than no test at all.
+
+## Why not session replay
+
+Session replay records the DOM mutation stream. It is megabytes per session, it
+costs real money to keep, and what it gives you is a video. You still have to
+reproduce the bug yourself afterwards.
+
+Witness records intent, at about two kilobytes per session. Small enough to leave
+on permanently, and that is the point: **the trace already exists at the moment
+somebody decides to complain.** Nobody can reproduce a bug on request; everybody
+has just done it.
+
+| | Session replay | Witness |
+| --- | --- | --- |
+| Records | DOM mutations, pixels | Intents, failures, stable selectors |
+| Size | megabytes | ~2 KB |
+| Output | a video to watch | a test to run |
+| Answers "is it fixed?" | you rewatch and judge | the test goes green |
+| Typed values | usually captured, then masked | never held |
+
+## Using it on three.ws
+
+Nothing to do. Every page runs the corner companion, which starts the recorder
+before the page finishes booting. When something breaks the companion asks what
+you were doing, and the session rides along with the answer.
+
+At [`/feedback`](https://three.ws/feedback) a cluster with a recorded session
+shows a **Recorded session** card: the replay confidence, the narrated steps, and
+**Show test** / **Copy test** / **Download**.
+
+From the shell:
+
+```bash
+npm run feedback:repro -- --list # reports with a replayable session
+npm run feedback:repro -- <report-id> # writes tests/repros/<id>.spec.js
+npm run feedback:repro -- <report-id> --run # writes it, then runs it
+npm run feedback:repro -- <id> --base http://localhost:3000 # replay locally
+```
+
+Repros live in `tests/repros/` with [their own Playwright
+config](../tests/repros/playwright.config.mjs), deliberately outside the
+`tests/e2e` suite: a reproduction is red by definition until its bug is fixed, so
+folding them into the default run would mean `npm test` fails for every open
+report.
+
+```bash
+npx playwright test -c tests/repros/playwright.config.mjs
+```
+
+Over HTTP (admin session required):
+
+```bash
+curl -s 'https://three.ws/api/feedback/repro?id=<id>' -H "cookie: $SESSION" \
+ > tests/repros/export-does-nothing.spec.js
+```
+
+Add `&format=json` for the source plus the narrated steps and confidence, which
+is what the queue page renders.
+
+And from an agent over MCP (`/api/mcp`, scope `feedback:read`, admin account):
+
+| Tool | What it does |
+| --- | --- |
+| `list_feedback` | The queue, one row per problem, flagging which ones are replayable |
+| `get_feedback_repro` | Compiles one report into a spec, with steps and confidence |
+
+Both are read-only. An agent can reproduce a reported bug and verify its own fix
+against the real session, and it still cannot change a status or touch the
+product: see the boundary in [feedback.md](feedback.md#the-boundary-that-makes-this-safe).
+
+## Replay confidence
+
+Every trace carries a score equal to its **weakest** selector, because one
+fragile locator breaks the whole spec:
+
+| Score | Meaning |
+| --- | --- |
+| 80-100 | Every step is anchored to a test id, an id, an aria-label, or a role and name. |
+| 60-79 | A step relies on visible text, which moves when copy changes. |
+| 40-59 | A step is anchored to a class name, which a restyle can break. |
+| 0-39 | A step falls back to a structural path and will not survive a refactor. |
+
+That number is honest feedback about your own markup, and it is actionable: add
+`data-testid` to the primary action on a page and every future report from that
+page compiles into a sturdier test. The full ladder is in the
+[package README](../packages/witness/README.md#the-selector-ladder).
+
+## Privacy
+
+Enforced at capture time, not by scrubbing afterwards. A recorder that captures
+everything and cleans up later has already put the secret in memory.
+
+- **Typed values are never held.** A filled field records `text:11`: eleven
+ characters of ordinary text. The characters do not exist in the trace.
+- **Password, hidden, email, tel and date inputs record nothing**, and neither
+ does any field whose name, id, `autocomplete`, label, or placeholder suggests
+ it holds something personal.
+- **URLs are stripped at capture**: userinfo and the hash go entirely, credential
+ parameter values are redacted, parameter names are kept.
+- **Free text is scanned** for emails, JWTs, API keys, card numbers, wallet
+ addresses, and long base58 runs.
+- **`data-witness="off"`** excludes a subtree completely. three.ws marks its own
+ feedback panel with it, because the act of reporting a bug is not part of the
+ bug.
+
+The visitor can see all of this before they send: the panel shows the exact step
+count and expands to the full list, above the line "Nothing you typed into a
+field is recorded, only how much."
+
+## When it cannot help, it says so
+
+If a session recorded no exception and no failed request, the visitor judged the
+*result* wrong, and no recorder can see that. The compiler does not invent an
+assertion to look useful:
+
+```js
+// The browser recorded no exception or failed request for this report:
+// the visitor judged the RESULT wrong, which no recorder can see.
+// Replace this with the assertion that states what should have happened.
+expect(pageErrors, 'no page errors during the reported flow').toEqual([]);
+test.fail(true, 'Add the assertion this report is really about.');
+```
+
+You get the reproduction steps for free and write the one line only a human can.
+
+## Using it on your own site
+
+```bash
+npm install @three-ws/witness
+```
+
+```js
+import { witness } from '@three-ws/witness';
+witness.start();
+witness.onFailure(() => openYourFeedbackForm());
+
+// when they submit:
+sendToYourBackend({ note, trace: witness.trace() });
+```
+
+```js
+import { compileToPlaywright } from '@three-ws/witness/compile';
+const { source, filename, confidence } = compileToPlaywright(trace, { title: note });
+```
+
+The recorder is browser-only; `compile` is pure and runs in Node, which is what
+lets one trace produce the maintainer's English steps in a dashboard and the
+engineer's spec file on disk. Full API in the
+[package README](../packages/witness/README.md#api).
+
+## Related
+
+- [Feedback](#sec-228): the loop this is the second half of, and the
+ untrusted-input boundary that governs all of it.
+- [Notifications](#sec-311): the same companion, delivering the other way.
+
+---
+
+<a id="sec-548"></a>
> **Source:** `docs/world-lines.md` · [↑ table of contents](#table-of-contents)
@@ -123575,9 +128546,9 @@ Need to drive a widget from the parent page — change the camera, play an anima
A **World Line** is a quest an agent leaves at a real place. Someone walks to that spot, completes the agent's challenge in a live ceremony panel (a tap, a passphrase, or a quiz), and the agent's own wallet signs an ed25519 **proof of presence**: a tamper-evident receipt that says *this visitor was in this area and did this thing*. The proof is independently verifiable by anyone, ownable by the visitor, and it never carries a coordinate finer than a roughly 1 km cell.
-Live at `three.ws/world-lines`. Four tabs: **Near me** (fix-gated quests within walking range), **Explore** (coordinate-free region roll-up), **My proofs** (your earned collectibles, each re-verifiable in place), and **Create** (place a quest on a pin you own, plus the completion dashboard).
+Live at `three.ws/world-lines`. Four tabs: **Near me** (fix-gated quests within walking range), **Explore** (coordinate-free region roll-up), **My proofs** (your earned collectibles, each re-verifiable in place), and **Create** (place a quest on a pin you own, plus the completion dashboard). The active tab is mirrored into the URL hash (`#near`, `#explore`, `#collectibles`, `#create`), so a tab is linkable and the back button walks tabs; Left/Right/Home/End move between them from the keyboard.
-This document is the deep reference. For where World Lines sits inside the wider IRL product (placing agents, discovering by walking up, Money Drops, the presence privacy contract), read the short version first: [IRL: agents in the real world](irl.md#world-lines). The REST summary lives in the [API reference](#sec-096); everything below is the full contract, the anti-cheat reasoning, and the exact privacy posture as coded.
+This document is the deep reference. For where World Lines sits inside the wider IRL product (placing agents, discovering by walking up, Money Drops, the presence privacy contract), read the short version first: [IRL: agents in the real world](irl.md#world-lines). The REST summary lives in the [API reference](#sec-098); everything below is the full contract, the anti-cheat reasoning, and the exact privacy posture as coded.
Code: [api/irl/world-lines.js](../api/irl/world-lines.js) (all nine endpoints), [api/\_lib/world-lines.js](../api/_lib/world-lines.js) (the pure crypto and ceremony core), [src/world-lines.js](../src/world-lines.js) (the page), [src/irl/world-line-ar.js](../src/irl/world-line-ar.js) (the completion ceremony), [src/irl/world-lines-client.js](../src/irl/world-lines-client.js) (browser client), [packages/irl](../packages/irl/README.md) (the npm SDK).
@@ -123668,7 +128639,7 @@ The collectible's display name is `reward_ref` when you set one, otherwise it is
What the visitor sees, and what the server checks under each step. The ceremony state machine is [src/irl/world-line-ar.js](../src/irl/world-line-ar.js); every state below is a rendered state, including the failure ones (speaking, awaiting the interaction, submitting, granted, already completed, capacity reached, no longer active, and error).
-The ceremony runs as a designed in-page panel on every device, with the agent's avatar rendered live and breathing in the card. The module also carries a self-contained immersive WebXR layer (`enterAR()`, floor hit-test, avatar anchored to the detected surface), which no current UI path activates: the ceremony renders no AR button, so the panel is what visitors get today on every browser. Nothing about the proof depends on which of the two is used, because the client owns no secrets and the server enforces co-location, the nonce, the signature, the caps, and idempotency regardless.
+The ceremony runs as a designed in-page panel on every device, with the agent's avatar rendered live and breathing in the card. The module also carries a self-contained immersive WebXR layer (`enterAR()`, floor hit-test, avatar anchored to the detected surface). On a browser that reports `immersive-ar` support the intro panel grows a "Meet the agent in AR" button that starts it; everywhere else no button renders and the panel is what visitors get, and an AR session that fails to start falls back to the panel's begin step. Nothing about the proof depends on which of the two is used, because the client owns no secrets and the server enforces co-location, the nonce, the signature, the caps, and idempotency regardless.
**1. Discover.** The page watches geolocation, mints a fix token, and calls `GET /nearby`. Each quest card shows a distance chip coarsened to 10 m, the difficulty, the reward, and whether you already hold its proof. Under 80 m the button becomes "You're here, begin"; further away it reads "Travel here to begin".
@@ -123809,7 +128780,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-260); 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-271); the user-facing summary is the `three.ws/irl-privacy` page. World Lines specifically:
**Stored.**
@@ -124149,14 +129120,606 @@ 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-260), the adversarial analysis behind every radius and cap above.
-- [Place a 3D agent in your real environment](#sec-474), 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.
+- [IRL threat model](#sec-271), the adversarial analysis behind every radius and cap above.
+- [Place a 3D agent in your real environment](#sec-494), how to create the anchor pin a World Line needs.
+- [API reference](#sec-098), the one-screen summary of these endpoints alongside the rest of `/api/irl/*`.
+- [AR](#sec-101), the camera and WebXR layer the ceremony builds on.
---
-<a id="sec-528"></a>
+<a id="sec-549"></a>
+
+> **Source:** `docs/x-account-appeal.md` · [↑ table of contents](#table-of-contents)
+
+# Getting @nichxbt back: the appeal packet
+
+`@nichxbt` (X user ID `2817123964`) was suspended on 2026-08-27. X's email, sent
+06:29 that morning, says the account "was reported and has been suspended"
+for "violating our rules against authenticity", and warns that creating a new
+account is evasion and that an X Premium subscription keeps billing. The
+suspension is confirmed independently: X's public user endpoint answers
+`"User is suspended"` for the handle.
+
+This file is the whole case in one place: what X's own process is, what the
+documented successful appeals had in common, what got other people denied,
+the exact text to submit, and the order to do things in. It was assembled on
+2026-08-27 from primary sources where they were reachable and from first-hand
+accounts where they were not. Every claim carries its source. Where a source
+is a marketing blog rather than a first-hand account, it is marked as such.
+
+The status table that the rest of the repo reads is in
+[`x-accounts.md`](#sec-550). Update that file when this one changes the
+facts.
+
+## 1. What this suspension is, and is not
+
+**The category is wrong for the account, and that is the case.** X's
+authenticity rules cover impersonation, fake or duplicate accounts, bulk or
+automated activity, engagement pods, coordinated campaigns, and purchased
+engagement. The email cites that family, and "was reported" says the trigger
+was user reports rather than a detection sweep. None of the listed behaviours
+describes the account:
+
+| Fact | Evidence on file |
+| --- | --- |
+| Real person, real company, twelve-year-old account | User ID `2817123964` is in the ID range X issued in late 2014. The oldest post in the archive is 2021-07-03, the newest 2026-05-09 ([`data/archives/nichxbt_tweets_2026-05-10.json`](../data/archives/nichxbt_tweets_2026-05-10.json)). |
+| Identity is corroborated by third parties, not just by us | Same person and company named by IBM, AWS, OpenAI, Google Cloud, and Alibaba Cloud partner listings (every one linked from `/community` and the blog), by the public GitHub organisation, and by the live product at three.ws. |
+| Manual posting cadence, no volume pattern | 207 own posts across the archive. The busiest month in the last year was February 2026 at 23 posts; most months are under 20. The busiest single day on record is 13 posts, on launch day. |
+| No X app, no API posting, from either account | The repository contains X integration code, and none of it was ever put into service. The "connect your X account" OAuth lane answers `501 not_configured` on production (checked 2026-08-28 at `/api/auth/x/connect`), so no user has ever posted through a three.ws app. The changelog-to-X lane was retired on 2026-07-18 and its state file ([`data/changelog-x-state.json`](../data/changelog-x-state.json)) was committed once, in a single sweep, with no tweet IDs and no thread: nothing was ever posted through it. The `nichxbt` archive was a one-time read of the public profile in May, not an API integration. Where that code names an account at all it names `@trythreews`. |
+| Not an engagement scheme | The product's "share on X" buttons open the standard `x.com/intent` composer with the user's own text and do not tag `@nichxbt` ([`pages/create-next.html`](../pages/create-next.html), [`api/trade-share.js`](../api/trade-share.js)). Users who connect their own X account post under their own OAuth grant, in their own name. |
+| Reach was organic and pre-dates the company | The two most-viewed posts are from 2024 and 2025 (3.0M and 7.9M views) and have nothing to do with three.ws. |
+
+So the appeal is not "please forgive me", it is "the cited rule does not apply,
+here is how you can check". That framing matters because the one piece of
+quantitative data anyone has published on X appeals found policy-specific
+appeals reinstated at roughly 2.5 times the rate of generic ones
+([YRS, 198 cases, Jan 2024 to Jun 2026](https://youreputationsolution.com/blog/recover-suspended-twitter-account/);
+a reputation-services vendor, so treat the number as indicative).
+
+**What it is not: the March 2026 spam-filter bug.** That wave was a
+detection sweep, reverted in bulk within a day (Nikita Bier, 2026-03-13:
+"99% of those suspensions were reverted today. For about 12 hours, a new spam
+filter had falsely tagged subset of accounts",
+[x.com/nikitabier/status/2032279113743155634](https://x.com/nikitabier/status/2032279113743155634)).
+This suspension is report-driven and individual. It will not lift on its own,
+and nobody should wait for that.
+
+## 2. X's own process, from X's own pages
+
+`help.x.com` refuses automated readers, so every quote below is from Wayback
+Machine captures of the live pages taken between June and August 2026, which
+agree with each other across captures. Local copies of each captured page are
+in the research notes listed at the end.
+
+**The policy page is one page now.** The old platform-manipulation,
+ban-evasion, and deceptive-identities pages all redirect into
+[help.x.com/en/rules-and-policies/authenticity](https://help.x.com/en/rules-and-policies/authenticity)
+(dated "April 2025"). Its headline rule is the sentence the email paraphrases:
+"You may not engage in inauthentic activity that undermines the integrity of
+X." Everything it lists as a violation is one of: unauthorized automation
+("as a user you are ultimately responsible for third-party applications you
+may authorize"), fake personas, impersonation, multiple coordinated accounts,
+ban evasion, account compromise, content spam (bulk replies, copypasta,
+hashtag abuse, link-only posting), engagement spam (buying or trading
+engagement, follow churn, engagement pods, indiscriminate following,
+mass false reporting), scams, manipulated media, and malicious URLs.
+
+**How X says it enforces this policy, verbatim:** "For severe violations,
+accounts will be permanently suspended at first detection. If the offense is
+an isolated incident or first offense, we may take a number of actions ranging
+from requiring deletion of one or more posts to temporarily locking
+account(s). In the case of a violation centering around the use of multiple
+accounts, you may be asked to choose one account to keep." And: "If you
+believe we made a mistake, you can submit an appeal."
+
+**What X says about mistaken suspensions**, on the suspended-accounts page:
+"Most of the accounts we suspend are suspended because they are spammy, or
+just plain fake ... Sometimes a real person's account gets suspended by
+mistake, and in those cases we'll work with the person to make sure the
+account is unsuspended." The appeal text in section 5 deliberately uses that
+framing.
+
+**The form**, [help.x.com/en/forms/account-access/appeals](https://help.x.com/en/forms/account-access/appeals),
+read from its form definition (captured 2026-07-29):
+
+- Login is required, and the form is explicitly built to accept a logged-in
+ *suspended* session (`logInRequired: true`, user role `suspended`). X's
+ instruction: "First, log in to the account that is suspended. Then, open a
+ new browser tab and file an appeal."
+- Three visible fields plus a CAPTCHA. **Username** (must include the `@`
+ and must match the logged-in account). **Email** ("This is where we'll
+ contact you"; must match the account). **Description of the problem**, with
+ the help text "Tell us if you're having a problem accessing your account,
+ or why you don't believe you violated the X Rules." There is no phone
+ field. The description has a minimum length and no published maximum.
+- After submission: "We've received your request. We'll review, and take
+ further action if appropriate. In some cases, we may send an email with
+ more information." Check spam folders.
+
+**Appeal limits and response time: X publishes neither.** No X page says one
+appeal, says you may appeal again, or gives a cooldown or an SLA. The "one
+shot" and "every two days" rules circulating online are third-party guidance.
+The only X timing statement is on the reporting page: reports "are typically
+resolved within a few days ... and may take thirty days." Working assumption:
+the first submission is the one a human is most likely to read, so it must be
+right, and later submissions are allowed but must not look like spam.
+
+**"Was reported" is not a defined tier.** X uses that framing on the
+suspended-accounts page ("We may suspend an account if it has been reported
+to us as violating our X Rules ... temporarily or, in some cases,
+permanently"). The email does not say "permanently suspended", which is the
+wording X's notices page reserves for its "most severe enforcement action".
+A "permanent" suspension is still appealable: "Violators can appeal permanent
+suspensions if they believe we made an error."
+
+**Evasion is a listed violation of this exact policy**, with wide reach:
+"creating new accounts; imitating a suspended account to replace it;
+repurposing an already-existing account; and having someone else operate an
+account on your behalf" are all prohibited, and "X reserves the right to also
+suspend any other account we believe the same account holder or entity may be
+operating ... regardless of when the other account was created." That last
+clause is why `@trythreews` must stay clean and separate: it is an existing
+account the same person operates.
+
+**Premium buys nothing here, and X says so.** From the Premium FAQ: "Premium
+subscribers receive dedicated support for subscription-specific issues,
+only." "Will subscribers receive preference when receiving account support?
+... The X Rules won't apply differently to subscribers." "Policy enforcement
+issues and reports by subscribers will continue to be handled by existing
+enforcement teams, under the current review process." The `@Premium` DM
+channel needs a working account anyway. Subscriptions are "non-refundable
+... That includes subscriptions linked to X accounts that have been
+suspended," so whether to keep paying is a money decision, not an appeal
+decision. Premium Business "Priority Support" exists but its documented scope
+is onboarding, affiliates, billing, and impersonation, and X's own forum
+reply on 2026-08-14 to a suspended Premium+ user simply pointed back at the
+Help Center.
+
+**What the automated answers look like.** The in-app banner is the same in
+2023 and 2026: "Your account is suspended. After careful review we
+determined your account broke the X Rules. Your account is permanently in
+read-only mode ... If you think we got this wrong, you can submit an appeal."
+A rejection that arrives within minutes, at any hour, is automated; every
+documented human decision took days. One 2026 rejection variant says "you can
+resolve the violations by logging into your account and completing the
+on-screen instructions" when no such instructions exist; Petryshyn's winning
+appeal was the one that answered that email's logic directly.
+
+**A "restored" email is not restoration.** Through mid-2026 X's automated
+system has sent "Our automated systems have determined there was no violation
+and have restored your account" to accounts that stayed suspended, some at
+thirty appeals ([developer forum, 2026-06-16](https://devcommunity.x.com/t/restoration-emails-for-suspended-accounts-inauthentic-behaviors-are-false-accounts-do-not-get-restored-suspension-is-not-lifted-as-email-indicates/268394)).
+If that email arrives, log out everywhere, request a password reset, log back
+in, and only then decide whether it worked.
+
+**How often appeals succeed, from X's own DSA reports.** For EU users in
+April to June 2025, complaints against account suspensions were overturned
+at roughly 10 to 16 percent by country (Germany 1,636 of 15,404; France 1,348
+of 10,029; Spain 761 of 4,492), with median handling of 2.5 to 7.5 days
+([transparency.x.com](https://transparency.x.com/dsa-transparency-report-2025-october.html)).
+That is the base rate a generic appeal faces. The whole point of this packet
+is to not be a generic appeal.
+
+## 3. What the successful appeals had in common
+
+The closest precedents are report-driven suspensions of real accounts, which
+is this case. Then the first-hand appeal write-ups, with the text they used
+where they gave it.
+
+**Report-driven suspensions that were reversed:**
+
+| Case | What X said | What got it reversed | Time |
+| --- | --- | --- | --- |
+| [@itscruxia, 2026-08-06](https://devcommunity.x.com/t/app-still-suspended-after-the-owning-account-was-reinstated-on-appeal-app-id-33278893/274182) | "inauthentic behaviours" "following a user report" | One appeal through the form. | Same day. The nearest match to this case on the record: a user-report authenticity suspension of a real account, reversed on the first filing. |
+| [Monad, 2026-04-28](https://www.crowdfundinsider.com/2026/04/276090-social-media-platform-x-suspends-official-account-of-l1-blockchain-project-monad/) (1.2M followers) | generic; co-founder said "system error, no abnormal activity or API misuse" | "Multiple channels have now been used to contact the X platform support team" plus a public "free Monad" push. | About 24 hours. |
+| [GMGN and BullX, June 2025](https://www.cryptopolitan.com/x-restores-elizaos-founder-account/) | none; BullX said on Discord it had been "mass reported" | GMGN: "actively appealing the decision, in close communication with X." | Weeks. Same sweep that took Pump.fun and Alon down for a day. |
+| [Never Back Down PAC, 2023-08-23](https://www.foxnews.com/politics/x-suspends-desantis-pacs-account-hours-debate.amp) | X afterwards: "our automated systems incorrectly picked it up as spam"; allies alleged coordinated mass reporting | Tagged Musk publicly. | Hours. The one case where X put in writing that a reported account was a false positive. |
+| [January 2024 journalist sweep](https://www.nbcnews.com/tech/social-media/x-temporary-ban-journalist-accounts-raises-alarm-rcna133084) | Musk: "We do sweeps for spam/scam accounts and sometimes real accounts get caught up in them" | Appeals returned only a "buggy response"; press and public outcry did it. | Hours. |
+| Counter-case: [a writing business, mass-reported, Jan 2025](https://devcommunity.x.com/t/1-5-years-since-business-accounts-permanent-suspension-after-being-mass-reported/268672) | permanent suspension | Appeals auto-denied in minutes for 18 months; DMs to X accounts returned canned links. | Never. Small account, no audience, no press. This is what the form path looks like with nothing behind it. |
+
+The split is stark: reported accounts with an audience or a company behind
+them come back in hours to weeks; a reported account with neither can sit
+for years. `@nichxbt` is in the first group, and the appeal should make that
+obvious in its first two sentences.
+
+**First-hand appeal write-ups:**
+
+| Case | Policy cited | What they did | Result |
+| --- | --- | --- | --- |
+| [Tony Gasparro, April 2026](https://tonygasparro.com/blog/x-account-suspended-inauthentic-behavior/) | "inauthentic behaviors", read-only | Day 0 appeal auto-denied. Days 1 to 2: completed government-ID plus selfie verification through Persona when X offered it at login. Then re-appealed every 3 to 5 days, each one "calm, clear, slightly reworded", stating: manual activity, no automation, Premium+ subscriber, ID verified, willing to remove anything flagged. | Restored day 13, silently, no email. |
+| [Vadym Petryshyn (Postory)](https://postory.io/blog/twitter-suspended-appeal) | unstated; author believes reply volume read as spam | Five appeals over a month, each rewritten so it was not a repeat. The one that worked argued the practical point: "how can I fix anything while suspended? I can't see my posts, I can't delete anything, I can't access the account at all. Restore my access and I will fix it." | Restored within an hour of that appeal. Reach stayed limited for eight more days. |
+| [Pump.fun and Alon, June 2025](https://coingape.com/pump-fun-and-founder-return-to-x-following-account-suspension/) | none shown; part of a ~20-account crypto sweep | No public appeal; no statement. | Restored in about 24 hours. Shows crypto-adjacent sweeps get reversed quietly when the accounts are plainly real. |
+| [Bankr, October 2025](https://www.theblock.co/post/374119/bankr-back-live-x) | none given | Community tagged X product leads under `#FreeBankr`. | Restored within hours. X never explained either direction. |
+| [Dean Phillips campaign, 2023](https://www.cbsnews.com/colorado/news/twitter-suspends-rep-dean-phillips-campaign-account-2024-presidential-bid/) | generic | Press coverage. | Restored; mechanism never disclosed. |
+| [Karen Selick, 2022](https://karenselick.substack.com/p/twitter-has-restored-my-account-after) | told in March the decision was permanent and could not be appealed | Re-appealed months later saying she did not understand the suspension. | Restored by July. A "cannot appeal" reply is not final. |
+| [Ken Klippenstein, Sept to Oct 2024](https://www.kenklippenstein.com/p/elon-musk-accepts-defeat) | "permanently suspended" | His own appeals did nothing. Reinstated 2024-10-13 after a New York Times story and Musk posting "I've asked X Safety to unsuspend him." | Restored after 17 days, by executive intervention, not by the form. |
+| [@Rainmaker1973, May 2026](https://x.com/nikitabier/status/2059285953815199899) | inauthentic behaviour | Public thread. Nikita Bier replied in public with the actual trigger (re-uploading others' videos with cropped watermarks to game creator payouts). | Not restored. Shows the risk of the public route: if there is a real trigger, the Head of Product will say what it was, in public. |
+
+Patterns that hold across every case that gave detail:
+
+1. **Short and specific beats long and general.** Name the handle, the date,
+ and the exact rule from the email. Say in one or two sentences why it does
+ not apply. Ask for a human review. Stop.
+2. **Identity verification is the single strongest move for an authenticity
+ suspension**, because it answers the charge directly. If X offers ID
+ verification at login (it did for Gasparro), complete it before appealing.
+ If it does not, say in the appeal that you will.
+3. **Say what you are willing to do.** "Willing to remove anything flagged"
+ and "restore access and I will fix it" both appear in winning appeals. It
+ costs nothing and it reads as cooperative to a reviewer who has just seen a
+ hundred angry ones.
+4. **Persistence worked, hostility did not.** Every success that took more
+ than one attempt spaced them days apart and reworded each one. Nobody who
+ reported success sent identical text repeatedly or filed within 24 hours of
+ a denial.
+5. **Reinstatement is often silent.** Check by logging in, not by waiting for
+ an email.
+6. **X's own staff say repeat filings do not change the automated answer;
+ they reach the eventual human.** A developer-relations staffer on X's
+ forum, June 2026: "Automated restoration emails without actual
+ reinstatement usually indicate the appeal was rejected by the system.
+ Multiple appeals won't change the outcome, wait for a manual review"
+ ([devcommunity](https://devcommunity.x.com/t/suspended-for-inauthentic-behavior-even-though-i-am-a-real-user-getting-automated-restoration-emails-looped/269327)).
+ Read together with the successes: spaced, reworded filings are how people
+ stayed in the queue until a person looked, not a lever in themselves. The
+ tell that a person looked is the email opening "Our support team" rather
+ than "Our automated systems".
+
+## 4. What got people denied
+
+Collected from the same sources plus the failure threads. Each is something a
+real appeal did.
+
+- **Creating a second account.** Ends the appeal and gets both suspended.
+- **Filing again inside 24 hours of an automatic denial**, or resubmitting the
+ identical text. Reads as spam to the system that judges spam.
+- **Arguing about the reporters, the motive, or the post that preceded it.**
+ Converts a category error into a content dispute, which a support queue
+ cannot decide in your favour.
+- **Threatening legal action, or an angry tone.** Listed as a rejection
+ trigger by every guide and never present in a successful case.
+- **A generic "I didn't do anything, please help."** The one quantified
+ dataset puts these at less than half the reinstatement rate.
+- **Novel-length appeals.** Reviewers skim. Anything past four short
+ paragraphs is unread.
+- **Letting other people mass-email support on your behalf.** The Bankr
+ campaign was public tagging by a community, not a support flood; guides list
+ third-party appeals as a rejection trigger.
+- **Changing the account's email, phone, or handle during the process.** The
+ form matches what you enter against the record. Worse, one June 2026 case
+ reports that changing the username and un-liking old posts to "clean up" is
+ what tripped the inauthentic flag in the first place
+ ([devcommunity](https://devcommunity.x.com/t/restoration-emails-for-suspended-accounts-inauthentic-behaviors-are-false-accounts-do-not-get-restored-suspension-is-not-lifted-as-email-indicates/268394)).
+- **Mass-deleting old posts.** Petryshyn, first-hand: "Removing hundreds of
+ old posts can worsen the case." Bulk deletion is itself a pattern the
+ classifier reads as inauthentic. Do not touch the timeline.
+- **Referencing the suspended account from another account's bio, or calling
+ X out from an alt.** Both listed as appeal-killers by Postory, and both
+ look like evasion under the policy's "imitating a suspended account" and
+ "having someone else operate an account on your behalf" clauses.
+- **Resuming full activity the moment it comes back.** A restored 2015
+ account reported being re-suspended "if I so much as breathe on the
+ account". Both first-hand successes had reach suppressed for about eight
+ days after restoration. Ramp up over a week.
+
+## 5. The appeal text, as filed
+
+**Filed 2026-08-28 at 06:26** through the form, logged in as `@nichxbt`,
+handle and email pre-filled by X. The form answered: "Thank you! We've
+received your request. We'll review, and take further action if appropriate.
+In some cases, we may send an email with more information to the address you
+provided." This is the text that was submitted, verbatim:
+
+> My account @nichxbt was suspended on August 27, 2026 for "violating our
+> rules against authenticity" after being reported. I believe a real person's
+> account was suspended by mistake. I have held this account since 2014 and
+> post from it by hand; it has never used automation or engagement services,
+> and it has never been used to spam or deceive anyone. It is where I share
+> the open-source 3D and AI software I build and stay in touch with people I
+> have known for over a decade. I am the founder of three.ws
+> (github.com/nirholas/three.ws), and my identity is public and verifiable
+> through our published partner listings with IBM, AWS, OpenAI and Google
+> Cloud. I am glad to complete government-ID verification or any other check
+> you need. Please have a person re-review the account and restore access.
+
+Seven sentences. Rule, why it does not apply, what the account is for,
+verifiable identity, an offer of the one check that answers an authenticity
+charge directly, one ask.
+
+**Two things an earlier draft said that this one deliberately does not.**
+The draft claimed the account had "never used multiple accounts"; the same
+person operates `@trythreews`, which X permits (up to ten accounts for
+distinct purposes) but which makes a flat "never" falsifiable in one click,
+and a false statement in an appeal is the one thing that can turn a mistaken
+suspension into an upheld one. The draft also offered to "remove any post
+you identify", which reads as though a post is expected to exist; it became
+an offer of any further check instead. Every remaining claim is one the
+owner can stand behind if asked: the year, manual posting, no automation or
+engagement services, the company, the partner listings, the offer to verify.
+
+**Why the appeal says nothing about the company account.** X's ban-evasion
+clause lets it link any account "the same account holder or entity may be
+operating", and its Head of Product has said that automation on one account
+suspends "all associated accounts" ([2026-02-14](https://x.com/nikitabier/status/2022496540275937525)).
+That would matter if `@trythreews` posted through an API app, because a
+reviewer who linked the two would find it. It does not: no X developer app
+was ever configured or used from three.ws, on either account (see the table
+in section 1; verified against production on 2026-08-28). So there is nothing
+to pre-empt, and volunteering the company account would only invite a
+reviewer to link two accounts that X has no reason to look at together.
+
+## Filing log
+
+Every contact with X about this suspension, in order. Append to it; never
+rewrite an earlier line.
+
+| When | What | Result |
+| --- | --- | --- |
+| 2026-08-27 06:29 | X emails: account "was reported and has been suspended" for "violating our rules against authenticity". | Suspension confirmed; public user endpoint answers "User is suspended". |
+| 2026-08-28 06:26 | Appeal #1 filed through the form with the text in section 5. | Form acknowledged receipt. Awaiting review. Next check: log in daily; earliest refiling if silent or auto-denied: 2026-08-31. |
+
+## 6. The order of operations
+
+1. **Create nothing.** Do not open a new account under any name, do not let
+ anyone operate one "for" the founder, and do not post about the suspension
+ from `@trythreews`. Premium can stay or go; X says it makes no difference
+ to enforcement and refunds nothing, so that is purely a billing call.
+2. **Log in as `@nichxbt` on desktop.** If X shows an identity-verification
+ prompt, complete it (government ID plus selfie, via Persona). This is the
+ highest-value single step for an authenticity case.
+3. **File the appeal through the form.** Done, 2026-08-28 06:26; see the
+ filing log. Keep the confirmation screenshot.
+4. **Wait a full 72 hours.** An automatic denial inside the first day is the
+ documented norm and is not the end.
+5. **If denied or silent after 72 hours: refile, reworded, with one new
+ fact.** The new fact is ID verification if it completed after the first
+ filing, otherwise a specific pointer such as the account's 2014 creation
+ or a partner listing URL. Do not resend the same text. Every 3 to 5 days,
+ never sooner.
+6. **Check by logging in, not by waiting for email.** Restoration was silent
+ in the best-documented case. A "restored" email that does not restore
+ access is a known 2026 bug: log out, reset password, log in again.
+7. **After restoration:** change the password, enable 2FA, and post lightly
+ for a week. Gasparro's reach stayed suppressed for about eight days after
+ reinstatement; Petryshyn's for eight. Do not resume the previous cadence on
+ day one, and do not use any third-party posting tool on this account.
+ (There is no developer app tied to this account, so the separate
+ app-reinstatement step that 2026 cases needed does not apply.)
+
+## 7. Escalation, if the form path stalls
+
+In order of documented effectiveness for a US-based founder:
+
+1. **The form, again, with new evidence** (section 6, step 5). Every
+ documented reinstatement of an inauthentic-behaviour suspension in 2026
+ went through the form, most after several spaced filings. Reddit's
+ r/twitterhelp survey of successful cases, as summarised by PiunikaWeb
+ (2026-04-26), converges on about five appeals spaced roughly 48 hours
+ apart, calm, each explicitly asking for manual review, continuing even
+ after a "cannot be restored" reply
+ ([PiunikaWeb](https://piunikaweb.com/2026/04/26/x-twitter-suspended-account-recovery-tips/)).
+2. **A public thread that reaches X's Head of Product.** This is the only
+ route with documented reversals of individual suspensions that the form
+ did not fix (Klippenstein 2024; the March 2026 wave; Bankr). Nikita Bier
+ reads replies to his posts and pulls the internal record, and he answers
+ in public. That is also the risk: in the Rainmaker1973 case he named the
+ real trigger for everyone to see. Run it from a personal or community
+ account, never from `@trythreews` (see [x-accounts.md](#sec-550)). Tag
+ `@nikitabier` with the handle, the date, the email's wording, and proof of
+ ID verification. `@Support` and `@Safety` do not answer individual cases
+ in any documented 2025 to 2026 instance, and the Better Business Bureau
+ lists 5,945 of 6,042 complaints against X Corp as unanswered.
+3. **Executive email, once, after two weeks.** Elliott Advocacy's verified
+ contact list (updated 2026-05-14): Head of Product `[email protected]`,
+ VP Product `[email protected]`, Head of the Americas `[email protected]`
+ ([elliott.org](https://www.elliott.org/company-contacts/twitter/)). One
+ email, the appeal text plus the ID-verification screenshot, sent only
+ after the form path has had two weeks and at least three filings.
+4. **A data-access request, for the record rather than the result.** In the
+ EU, an Article 15 GDPR request forced X to disclose an automated
+ classifier as the real trigger, but only under litigation (Mekić v. X,
+ Amsterdam, 2024). From the US, a CCPA "right to know" through
+ `help.x.com/en/forms/privacy/request-account-info/me` has no documented
+ case of returning enforcement history. File it anyway; it costs nothing
+ and dates the request.
+5. **EU Digital Services Act, only if physically in the EU when using X.**
+ The rights attach to location, not citizenship or account settings. Article
+ 20 gives an internal complaint with human review; Article 21 gives a
+ certified out-of-court body. Three facts most guides get wrong: X states
+ on its own DSA page that it "is not bound by any decision made by a
+ certified out-of-court dispute settlement body"; the Appeals Centre Europe
+ does **not** cover X (User Rights in Berlin and ADROIT in Malta do); and
+ no body has published a single X reinstatement through this route. Of
+ 14,000 suspension disputes the Appeals Centre received in its first year,
+ fewer than 150 got a full review because platforms did not hand over the
+ material ([RTE, 2026-05-28](https://www.rte.ie/news/2026/0528/1575608-social-media-complaints/)).
+ Leverage at best; not available from the US.
+6. **Legal.** The premise most articles rely on is dead: X's US consumer
+ Terms dropped arbitration on 2024-11-15 and now send disputes to state or
+ federal courts in Wichita or Tarrant County, Texas
+ ([x.com/en/tos](https://x.com/en/tos)), so there is no "make them pay AAA
+ fees" lever. On the merits, Ryan v. X Corp (N.D. Cal., 2024-12-09)
+ dismissed every theory under Section 230 plus the "for any or no reason"
+ clause, and the platform win streak on account-termination suits is
+ described as "effectively unbroken"
+ ([Goldman](https://blog.ericgoldman.org/archives/2024/12/suspended-twitter-user-loses-lawsuit-due-to-section-230-ryan-v-x.htm)).
+ The one public demand letter to X Corp at the Bastrop address went
+ unanswered. The single crypto counter-example, ElizaOS, was restored in
+ December 2025, six months after filing a federal antitrust suit over its
+ June 2025 suspension, with no settlement announced and no causal link
+ established ([Cryptopolitan](https://www.cryptopolitan.com/x-restores-elizaos-founder-account/)). Small claims is a Premium-refund play, not a reinstatement
+ play. This route ends every goodwill path above it; do not open it.
+7. **There is no AI "second review".** Grok is upstream of suspensions (X
+ uses it as a classifier), not an appeal lane. Asking `@grok` returns the
+ Help Center steps.
+
+## 8. What stays true regardless of outcome
+
+The platform's announcements do not depend on this account. The changelog
+publishes to Telegram straight from each deploy, `@trythreews` is verified as
+an organisation with 9.1K followers, and every partner listing already points
+at the company rather than the person. The account is worth recovering for
+its history and its reach, and the recovery should be run carefully because
+there is one clean shot at it, but nothing operational is waiting on it.
+
+## Research notes
+
+Primary X pages were read from Wayback Machine captures (June to August 2026)
+because `help.x.com` blocks non-browser requests; the captures were consistent
+across dates. First-hand appeal accounts, X's DSA transparency reports, the
+X developer forum threads, and the executive-contact list are linked inline.
+Where a source is a vendor blog rather than a first-hand account or an X
+page, the text says so. Nothing in this file is quoted from a source that
+could not be opened.
+
+---
+
+<a id="sec-550"></a>
+
+> **Source:** `docs/x-accounts.md` · [↑ table of contents](#table-of-contents)
+
+# X accounts: which handle is live, and what to do when one is not
+
+three.ws has used two X accounts. This file records their status and what
+each surface in the repo should do about it. Read it before posting
+anything from an [`x-posts/`](#sec-556) draft, before adding an X
+link to a page, and before deciding which handle a meta tag should name.
+
+## Status
+
+| Handle | Role | Status |
+| --- | --- | --- |
+| [`@trythreews`](https://x.com/trythreews) | Institutional. The platform account. | Live. This is the only handle to link to or post from today. |
+| `@nichxbt` | Personal. The founder account. | **Suspended 2026-08-27; appeal filed 2026-08-28 06:26, awaiting review.** Confirmed by X's own notification email. Do not link to it and do not plan a post from it. Status and filing log: [`x-account-appeal.md`](#sec-549). |
+
+The suspension is confirmed, not inferred. X emailed the account owner at
+06:29 on 2026-08-27: the account "was reported and has been suspended",
+citing the **authenticity** policy, which covers inauthentic activity that
+undermines the integrity of the platform. An HTTP probe could never have
+established this on its own, because x.com serves the same JavaScript shell
+with a `200` for a live profile and a suspended one. If the account is
+restored, update this table first and the surfaces below second.
+
+Two operational facts from that email, both load-bearing:
+
+- **Creating a replacement account is suspension evasion**, and X says
+ plainly it will suspend the new account too. So "spin up a second personal
+ handle" is not an available workaround for anything in this file, and the
+ quote-tweet rule below is written around that.
+- **An X Premium subscription is not cancelled by the suspension** and keeps
+ billing until someone cancels it deliberately.
+
+An appeal through X support is the only path back to the handle. The full
+case, X's own process, the precedents, the exact text to file, and the order
+to do it in are in [`x-account-appeal.md`](#sec-549). Nothing in
+this repo should wait on it.
+
+The reader-facing version of the status table lives on
+[three.ws/community](https://three.ws/community), which lists every channel and the
+`$THREE` contract address in one place so a visitor can check a suspicious account
+against it. Keep the two in step: this file is for the repo, that section is for the
+community, and neither should say something the other contradicts.
+[`community.md`](#sec-155) carries the same list for readers who arrive through
+the docs.
+
+## What a suspended handle actually breaks
+
+A suspended account's profile URL and every one of its post URLs serve a
+"this account has been suspended" interstitial. That has three distinct
+consequences in this repo, and they want three different responses:
+
+1. **Links a visitor clicks now.** These are the only ones that matter to a
+ reader today, and they are repointed at a live URL. Card metadata
+ (`twitter:creator`, `twitter:site`) and page attribution name
+ `@trythreews`; author identity in structured data points at
+ [github.com/nirholas](https://github.com/nirholas), which does not
+ depend on X at all.
+2. **Historical citations.** [`public/launch-week.html`](../public/launch-week.html),
+ the archives under [`data/archives/`](../data/archives) and
+ [`data/x-archive/`](../data/x-archive), the news feed's archived items,
+ and the changelog all cite posts by their URL because that URL is the
+ record of what was said and when. Those are left exactly as they are. A
+ citation that now resolves to an interstitial is still an accurate
+ citation; rewriting it would silently edit the platform's own history to
+ match an account status, which is worse than a dead link.
+3. **Unposted drafts that assume the account exists.** This is the real
+ cost, and it is covered below.
+
+## The two-account playbook, while `@nichxbt` is unavailable
+
+Nine drafts in [`x-posts/`](#sec-556), plus
+[`x402-solana-july-roundup-response.md`](#sec-587)
+and [`../marketing/openai-select-partner/social-copy.md`](../marketing/openai-select-partner/social-copy.md),
+are written around one pattern: `@trythreews` posts the institutional version, then `@nichxbt`
+quote-tweets it twenty to forty minutes later in first person, because an
+institutional account cannot credibly say "I built this and here is the
+part that broke." That second half is undeliverable right now.
+
+The drafts keep their two-account structure. They are not rewritten,
+because the structure is correct and the account may come back, and
+because flattening them into single-account copy would destroy the
+personal-voice half that is the harder half to write.
+
+Posting one of them today means doing this instead:
+
+- **Post the `@trythreews` half as written.** It stands alone; every draft
+ was built so the institutional post is complete on its own.
+- **Hold the `@nichxbt` half.** Do not port its copy onto `@trythreews`.
+ The personal-voice post reads as a person, and pasting it under the
+ platform account produces the exact self-amplifying tone the drafts warn
+ against.
+- **Do not stand up a new personal account to fill the slot.** A second
+ handle for the same person is suspension evasion by X's own definition and
+ gets suspended in turn, which costs the appeal as well as the account. If a
+ genuinely different person on the team takes the personal-voice slot, use
+ their handle verbatim and add it to the status table above; nothing else in
+ the drafts changes.
+
+Two drafts have a further wrinkle worth knowing before you open them:
+[`osf-issue-reply.md`](#sec-573) picks between a long and
+a short form based on whether the posting account has Premium, which is a
+question about a specific account rather than about the copy, and
+[`open-source-friday-plan.md`](#sec-325) submits the
+handle as a form field to a third party.
+
+## Do not litigate the suspension from `@trythreews`
+
+The suspension was report-driven. Whatever prompted the reports, the account
+that answers them publicly becomes the next target, and `@trythreews` is the
+platform's only remaining X presence and the one every partner listing links
+to. So the platform account does not post about the suspension, does not
+name or accuse anyone over it, and does not amplify the post that preceded
+it. Announcements continue on their normal cadence as though nothing
+happened, which is also true: see the next section.
+
+That restraint is a posture, not a concession. The appeal is the venue for
+the argument, and it is a private one.
+
+## The RSS mirror still works
+
+[`/rss/announcements.xml?source=nichxbt`](https://three.ws/rss/announcements.xml?source=nichxbt)
+is unaffected as a feed. It is built from the archived JSON in
+[`data/x-archive/`](../data/x-archive), not from a live scrape, so it keeps
+serving the same items with the same content whatever X does to the
+account. Only the per-item links point into the suspended account, which is
+case 2 above. The source stays valid; see
+[`syndication.md`](#sec-432).
+
+## Referral codes are not the handle
+
+`gmgn.ai/r/nichxbt`, `trade.padre.gg/rk/nichxbt`, and `fomo.family/r/nichxbt`
+in [`src/shared/trading-terminals.js`](../src/shared/trading-terminals.js)
+reuse the same string as a referral code on three unrelated services. They
+have nothing to do with X and are not affected. Do not "fix" them.
+
+Source-file copyright headers (`Copyright (c) 2026 nirholas | x.com/nichxbt
+| github.com/nirholas`) across the SDKs are attribution of authorship at a
+point in time, not a link a reader is expected to follow. They are left
+alone too.
+
+---
+
+<a id="sec-551"></a>
> **Source:** `docs/x-archive.md` · [↑ table of contents](#table-of-contents)
@@ -124217,7 +129780,7 @@ clean checkout.
## The report
-[docs/x-archive/trythreews-engagement.md](#sec-529)
+[docs/x-archive/trythreews-engagement.md](#sec-552)
is generated, never hand-edited. It carries:
- headline totals and the engagement **distribution** (median, p75/p90/p99, and
@@ -124268,7 +129831,7 @@ Code: [scripts/x-archive-lib.mjs](../scripts/x-archive-lib.mjs)
---
-<a id="sec-529"></a>
+<a id="sec-552"></a>
> **Source:** `docs/x-archive/trythreews-engagement.md` · [↑ table of contents](#table-of-contents)
@@ -124519,7 +130082,7 @@ The floor is as instructive as the ceiling: these are the shapes to stop repeati
---
-<a id="sec-530"></a>
+<a id="sec-553"></a>
> **Source:** `docs/x-memory-seeding.md` · [↑ table of contents](#table-of-contents)
@@ -124538,7 +130101,7 @@ 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-287), [Farcaster memory seeding](#sec-221), [GitHub seeding in the same table](memory.md#seeding-memory-from-an-existing-account)
+- **Related**: [Memory system](#sec-296), [Farcaster memory seeding](#sec-227), [GitHub seeding in the same table](memory.md#seeding-memory-from-an-existing-account)
---
@@ -124637,7 +130200,7 @@ Each fact becomes one row in `agent_memories`:
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-287)).
+ the chat runtime pages into every reply (see [memory system](#sec-296)).
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.
@@ -124852,7 +130415,7 @@ Seeded rows in `agent_memories` are found by tag (`tags && '{x_seed}'`) and by
---
-<a id="sec-531"></a>
+<a id="sec-554"></a>
> **Source:** `docs/x-posts/3d-ar-studio-launch.md` · [↑ table of contents](#table-of-contents)
@@ -125152,7 +130715,7 @@ Point it at your own catalogue with one option if you would rather use yours.
---
-<a id="sec-532"></a>
+<a id="sec-555"></a>
> **Source:** `docs/x-posts/3d-ar-studio-video-script.md` · [↑ table of contents](#table-of-contents)
@@ -125277,7 +130840,7 @@ match them to the narration beats:
---
-<a id="sec-533"></a>
+<a id="sec-556"></a>
> **Source:** `docs/x-posts/README.md` · [↑ table of contents](#table-of-contents)
@@ -125288,10 +130851,18 @@ staging only: nothing here is posted automatically, and posting is owner-gated p
[`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.
+> **`@nichxbt` is suspended (reported 2026-08-27).** Nine of the drafts below pair a
+> `@trythreews` post with a personal-voice quote tweet from `@nichxbt`, and that second half
+> cannot be posted right now. Post the `@trythreews` half as written and hold the other one;
+> do not move its copy onto the platform account. [`x-accounts.md`](#sec-550) has the
+> account status and the full rule.
+
## How these are written
- **Paste-ready, not outlines.** No placeholders, no "insert link here". Every link in a draft
- resolves today.
+ resolved when it was written. The one class that has since rotted is links into `@nichxbt`
+ posts, which now serve X's suspension interstitial; check any `x.com/nichxbt/status/...` link
+ before you paste a draft.
- **Character counts are measured, not guessed**, against X's rule that any URL counts as 23
characters regardless of length. Where a draft states a count, it was computed.
- **Each file opens with a verified-claims block** and, where it matters, a "do not claim" list.
@@ -125302,37 +130873,38 @@ explicit approval). Each file states what it's for and what has already been ver
| File | What it announces |
| --- | --- |
-| [`onchain-agent-wallets-x-post.md`](#sec-546) | Agent wallets with an on-chain spending allowance instead of a private key: SPL Token delegation, guardrails, x402, revocable custody |
-| [`mcp-registry-fleet-x-post.md`](#sec-539) | The fleet as a whole: 72 MCP servers under one namespace in the official registry, all current |
-| [`metaplex-agent-mcp-launch.md`](#sec-542) | The open-source agent infrastructure announcement covering `@three-ws/metaplex-agent-mcp` and `@three-ws/onchain-agent-wallets`, and why the integrations are bullish for $THREE |
-| [`metaplex-agent-mcp-x-post.md`](#sec-544) | The MCP server that mints an agent into the Metaplex Agent Registry with its own wallet and EIP-8004 identity |
-| [`metaplex-agent-deployer-x-post.md`](#sec-541) | The browser deployer at nirholas.github.io/metaplex-agent-mcp |
-| [`3d-ar-studio-launch.md`](#sec-531) | 3D AR Studio, the AR studio extracted from three.ws and published as an open-source package |
-| [`ar-quick-look-fix-x-post.md`](#sec-534) | AR Forge and AR Studio now open real Apple Quick Look / Google Scene Viewer on a phone, matching what `/avatars/:id/ar` already did. Shipped to `main` locally, **not yet deployed**: do not post until verified live on a real iPhone |
-| [`threews-avatar-launch.md`](#sec-553) | The three.ws avatar pipeline launch copy |
-| [`oracle-trading-mcp-x-post.md`](#sec-548) | The oracle trading MCP server launch |
-| [`sperax-staking-in-chat-x-post.md`](#sec-551) | SperaxOS chat-native staking, balance, and buy-SPA tool calls. The embedded `/staking` page is not working yet: do not announce until the blockers in the file clear |
-| [`news-archive-x-post.md`](#sec-545) | The news archive |
-| [`pumpfun-article-x-post.md`](#sec-550) | The pump.fun article |
+| [`onchain-agent-wallets-x-post.md`](#sec-570) | Agent wallets with an on-chain spending allowance instead of a private key: SPL Token delegation, guardrails, x402, revocable custody |
+| [`mcp-registry-fleet-x-post.md`](#sec-563) | The fleet as a whole: 72 MCP servers under one namespace in the official registry, all current |
+| [`metaplex-agent-mcp-launch.md`](#sec-566) | The open-source agent infrastructure announcement covering `@three-ws/metaplex-agent-mcp` and `@three-ws/onchain-agent-wallets`, and why the integrations are bullish for $THREE |
+| [`metaplex-agent-mcp-x-post.md`](#sec-568) | The MCP server that mints an agent into the Metaplex Agent Registry with its own wallet and EIP-8004 identity |
+| [`metaplex-agent-deployer-x-post.md`](#sec-565) | The browser deployer at nirholas.github.io/metaplex-agent-mcp |
+| [`3d-ar-studio-launch.md`](#sec-554) | 3D AR Studio, the AR studio extracted from three.ws and published as an open-source package |
+| [`ar-quick-look-fix-x-post.md`](#sec-558) | AR Forge and AR Studio now open real Apple Quick Look / Google Scene Viewer on a phone, matching what `/avatars/:id/ar` already did. Shipped to `main` locally, **not yet deployed**: do not post until verified live on a real iPhone |
+| [`threews-avatar-launch.md`](#sec-578) | The three.ws avatar pipeline launch copy |
+| [`oracle-trading-mcp-x-post.md`](#sec-572) | The oracle trading MCP server launch |
+| [`sperax-staking-in-chat-x-post.md`](#sec-576) | SperaxOS chat-native staking, balance, and buy-SPA tool calls. The embedded `/staking` page is not working yet: do not announce until the blockers in the file clear |
+| [`news-archive-x-post.md`](#sec-569) | The news archive |
+| [`proof-of-life-x-post.md`](#sec-574) | A shipping-evidence post for the platform account: what landed this week, with public verification links. Names nothing about the personal account |
+| [`pumpfun-article-x-post.md`](#sec-575) | The pump.fun article |
## Video and narration scripts
| File | What it covers |
| --- | --- |
-| [`metaplex-agent-mcp-veo-script.md`](#sec-543) | Shot-by-shot Veo (image-to-video) prompts for the agent infrastructure clip, built from a three.ws 3D avatar as the reference frame |
-| [`metaplex-agent-deployer-video-script.md`](#sec-540) | Spoken narration for the deployer clip |
-| [`threews-avatar-video-script.md`](#sec-554) | Shot list for the avatar clip |
-| [`3d-ar-studio-video-script.md`](#sec-532) | Narration and shot prompts for the AR Studio launch video |
+| [`metaplex-agent-mcp-veo-script.md`](#sec-567) | Shot-by-shot Veo (image-to-video) prompts for the agent infrastructure clip, built from a three.ws 3D avatar as the reference frame |
+| [`metaplex-agent-deployer-video-script.md`](#sec-564) | Spoken narration for the deployer clip |
+| [`threews-avatar-video-script.md`](#sec-579) | Shot list for the avatar clip |
+| [`3d-ar-studio-video-script.md`](#sec-555) | Narration and shot prompts for the AR Studio launch video |
## Events and community
| File | What it covers |
| --- | --- |
-| [`osf-issue-reply.md`](#sec-549) | The reply to Andrea Griffiths closing the loop on the Open Source Friday request (open-source-friday#254), in a Premium-length and a 280-character form |
-| [`event-x-posts.md`](#sec-535) | Event campaign copy, split by account (`@trythreews` institutional, `@nichxbt` personal) |
-| [`x-meetup-posts.md`](#sec-555) | The in-platform community meetup announcement |
-| [`ibm-skillsbuild-x-post.md`](#sec-538) | The IBM SkillsBuild badge |
-| [`fomo-verified-x-post.md`](#sec-536) | FOMO verification |
+| [`osf-issue-reply.md`](#sec-573) | The reply to Andrea Griffiths closing the loop on the Open Source Friday request (open-source-friday#254), in a Premium-length and a 280-character form |
+| [`event-x-posts.md`](#sec-559) | Event campaign copy, split by account (`@trythreews` institutional, `@nichxbt` personal) |
+| [`x-meetup-posts.md`](#sec-580) | The in-platform community meetup announcement |
+| [`ibm-skillsbuild-x-post.md`](#sec-562) | The IBM SkillsBuild badge |
+| [`fomo-verified-x-post.md`](#sec-560) | FOMO verification |
## Conventions
@@ -125348,7 +130920,99 @@ entry is dead once the file is no longer routed.
---
-<a id="sec-534"></a>
+<a id="sec-557"></a>
+
+> **Source:** `docs/x-posts/android-app-launch.md` · [↑ table of contents](#table-of-contents)
+
+# Announcement: the three.ws Android app
+
+**What this announces.** three.ws now installs as a real Android app. The signed APK is
+public at [`v1.0.0`](https://github.com/nirholas/three.ws/releases/tag/v1.0.0) and the
+Solana dApp Store listing was submitted on 2026-08-28 and is in review.
+
+**Two beats, deliberately.** This is beat one: the app exists and anyone can install it
+today. Beat two is "live on the Solana dApp Store", and it waits for approval. Spending
+both on one post wastes the bigger headline, and claiming a store listing that is still in
+review is the kind of line that ages badly in public.
+
+**Verified true when written (2026-08-28):**
+
+- The APK is signed, public, and 3.95 MB: `ws.three.app`, versionCode 1, SHA-256
+ `b83d9ab5…3c6945`. Installed and exercised on a physical Android phone by the owner.
+- Its signing fingerprint is served at `https://three.ws/.well-known/assetlinks.json`,
+ which is what makes the app open full-screen with no browser address bar.
+- minSdk 23, so it installs on any phone from Android 6 up.
+- dApp Store release `#331044442814` is In Review, submitted 2026-08-28.
+- `/seeker`, `/changelog`, and `/marketplace` all answer 200.
+- three.ws is open source under Apache 2.0.
+
+**Do not claim:**
+
+- "Available on the Solana dApp Store." It is in review. Say submitted, or say nothing.
+- Seed Vault as the sign-in on a general Android phone. Seed Vault is Seeker and Saga
+ hardware. On every other Android the same tap reaches whatever Solana wallet is
+ installed, through Mobile Wallet Adapter. Both are true; write the one that matches the
+ audience, and never imply a normal phone has a secure element it does not have.
+- A date for dApp Store approval. Nobody controls that.
+
+## Telegram (@three_ws)
+
+```
+three.ws is an Android app now.
+
+Install it from GitHub and it opens full-screen, no browser, no address bar:
+github.com/nirholas/three.ws/releases/tag/v1.0.0
+
+What the app adds over the website:
+
+- Sign in with one tap through your Solana wallet. On a Seeker that tap is Seed
+ Vault, and the key never leaves the secure element.
+- Point the phone camera at yourself and get back a rigged, animated 3D avatar.
+- Share a photo into three.ws from any app and it lands in the avatar flow already
+ attached.
+- Mint an agent on Solana mainnet from the phone.
+
+3.95 MB, Android 6 and up, open source. The Solana dApp Store listing is in review.
+```
+
+## The four images
+
+The artwork and the X copy live in [`../../marketing/android-launch/`](../marketing/android-launch). X changed its four-image layout on 2026-08-28 from a 2x2 collage to a swipe carousel that shows one image at a time in a cell of about 1.18:1, center-cropped, so there are two renders of the same scene:
+
+- **The strip (current).** `npm run build:x-strip` draws one 4800x1020 scene and cuts it into four 1200x1020 tiles in `kit/strip/`, the cell's own shape, so nothing is cropped and swiping reads as one continuous picture.
+- **The grid (kept in case X brings the collage back).** `npm run build:x-grid` draws one 4096x2304 composition and quarters it into `kit/images/`: every quadrant of a 16:9 rectangle is itself 16:9, so a 2x2 collage reassembles into the picture that was drawn. The headline is set as two halves that meet at the vertical seam with a word space at the cut, every phone sits wholly inside one tile, and the render refuses to write tiles whose outer border or seams are brighter than X's black timeline allows. The uncut master also becomes `kit/cmc-cover-640x360.png`, the CoinMarketCap article cover.
+
+**Attach the tiles in the order in [`kit/IMAGE-ORDER.md`](../marketing/android-launch/kit/IMAGE-ORDER.md).** X lays the images out in attachment order, and any other order scrambles the scene. The full thread, per-image alt text, and the follow-up replies are in [`kit/post.md`](../marketing/android-launch/kit/post.md).
+
+## X (@trythreews), held until the account is restored
+
+Do not post this while `@trythreews` is suspended; see
+[`../x-account-appeal.md`](#sec-549). It is written and ready for the day the
+appeal lands.
+
+```
+three.ws is an Android app.
+
+Install it, and it opens full-screen with no browser around it. Sign in with one tap
+through your wallet. Take one selfie, get a rigged 3D avatar back. Mint it on Solana
+from the phone.
+
+3.95 MB. Open source. Solana dApp Store listing in review.
+
+github.com/nirholas/three.ws/releases/tag/v1.0.0
+```
+
+Count: 331 characters (the URL counts as 23); needs Premium, which `@trythreews` has.
+
+## When the dApp Store approves
+
+Beat two gets its own post and its own changelog entry: the listing link, the five-panel
+carousel from `solana-mobile/publish/media/`, and the line this post is not allowed to use.
+The checklist item is in [`../../solana-mobile/docs/CHECKLIST.md`](../solana-mobile/docs/CHECKLIST.md).
+
+---
+
+<a id="sec-558"></a>
> **Source:** `docs/x-posts/ar-quick-look-fix-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -125356,7 +131020,7 @@ entry is dead once the file is no longer routed.
Announcement copy for a bug fix, not a new feature: `three.ws/ar` (AR Forge) and `three.ws/ar/studio`
(AR Studio) now place a model in your real room on iPhone the way `three.ws/avatars/:id/ar` already
-did. Related file: [threews-avatar-launch.md](#sec-553) sells the avatar-has-a-body
+did. Related file: [threews-avatar-launch.md](#sec-578) sells the avatar-has-a-body
story; this one sells "AR here means AR, on every phone, not just some of them."
**Thesis of this announcement:** every AR surface on the site now runs real ARKit Quick Look on
@@ -125439,7 +131103,7 @@ the resolution of a problem, and "watch it look real" is a dare to try it, not a
### From @nichxbt (the human one, quote-tweeting the @trythreews post above)
-Same two-account split as [event-x-posts.md](#sec-535): `@trythreews` posts the
+Same two-account split as [event-x-posts.md](#sec-559): `@trythreews` posts the
institutional version above, `@nichxbt` quote-tweets it with the human one a few minutes later, not
simultaneously. Her post is pure enthusiasm, first person, no bug talk.
@@ -125565,15 +131229,15 @@ what three.ws does well rather than dwelling on the fix.
post; add a $THREE line only if a specific alternate calls for it, don't bolt one onto every
draft.
- **Screenshots, if used, should show the model sitting convincingly in a real room**, the way
- [3d-ar-studio-launch.md](#sec-531) already frames its media: a real floor in
+ [3d-ar-studio-launch.md](#sec-554) already frames its media: a real floor in
frame is the whole point.
- **Do not combine this with the AR Studio open-source package announcement**
- ([3d-ar-studio-launch.md](#sec-531)). That post is about giving the surface away as
+ ([3d-ar-studio-launch.md](#sec-554)). That post is about giving the surface away as
a library; this one is about how good AR feels on three.ws today. Mixing them muddies both.
---
-<a id="sec-535"></a>
+<a id="sec-559"></a>
> **Source:** `docs/x-posts/event-x-posts.md` · [↑ table of contents](#table-of-contents)
@@ -125887,7 +131551,7 @@ Practical notes for reused footage:
---
-<a id="sec-536"></a>
+<a id="sec-560"></a>
> **Source:** `docs/x-posts/fomo-verified-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -125981,7 +131645,7 @@ Shorter alternate:
---
-<a id="sec-537"></a>
+<a id="sec-561"></a>
> **Source:** `docs/x-posts/github-100-stars.md` · [↑ table of contents](#table-of-contents)
@@ -125989,7 +131653,7 @@ Shorter alternate:
Post copy for the 100-star milestone on X. Posting is owner-gated; these are ready-to-paste drafts. Attach [media/github-100-stars-people.png](media/github-100-stars-people.png) (2400x1350, real contributor avatars pulled from GitHub at render time, plus three install commands) to the Version A main post, [media/github-100-stars-x.png](media/github-100-stars-x.png) (twelve stat tiles) to the Version B main post, and [media/github-100-stars-ecosystem.png](media/github-100-stars-ecosystem.png) (same size, the footprint beyond the repo) to reply 3. [media/github-100-stars-square.png](media/github-100-stars-square.png) (1620x1620) is the square cut for Telegram, Instagram, and LinkedIn.
-Regenerate both images with `node scripts/render-github-stars-banner.mjs` after updating the `STATS` and `SURFACES` arrays in the script. The canonical link and number table both announcements (the post and the X article) must cite is [open-source-footprint.md](#sec-313); keep the copy below in sync with it.
+Regenerate both images with `node scripts/render-github-stars-banner.mjs` after updating the `STATS` and `SURFACES` arrays in the script. The canonical link and number table both announcements (the post and the X article) must cite is [open-source-footprint.md](#sec-324); keep the copy below in sync with it.
## Where every number comes from (as of August 25, 2026)
@@ -126204,7 +131868,7 @@ Star the repo: github.com/nirholas/three.ws
---
-<a id="sec-538"></a>
+<a id="sec-562"></a>
> **Source:** `docs/x-posts/ibm-skillsbuild-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -126412,7 +132076,7 @@ https://www.credly.com/badges/b7ea921a-ce3d-4f4d-bfac-38f95276d361/twitter via @
---
-<a id="sec-539"></a>
+<a id="sec-563"></a>
> **Source:** `docs/x-posts/mcp-registry-fleet-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -126529,14 +132193,14 @@ Post 1 is the main post. Then:
---
-<a id="sec-540"></a>
+<a id="sec-564"></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-544); this file is what gets said, cut
+[metaplex-agent-mcp-x-post.md](#sec-568); 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
@@ -126636,7 +132300,7 @@ For a single generation with no editing. One breath, one idea.
---
-<a id="sec-541"></a>
+<a id="sec-565"></a>
> **Source:** `docs/x-posts/metaplex-agent-deployer-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -126874,7 +132538,7 @@ our own product, no pretending to be a bystander.
---
-<a id="sec-542"></a>
+<a id="sec-566"></a>
> **Source:** `docs/x-posts/metaplex-agent-mcp-launch.md` · [↑ table of contents](#table-of-contents)
@@ -127077,14 +132741,14 @@ fund them, which is already the safe, verified claim.
---
-<a id="sec-543"></a>
+<a id="sec-567"></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-542). Text-to-video only, no dialogue, no
+[`metaplex-agent-mcp-launch.md`](#sec-566). 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.
@@ -127188,7 +132852,7 @@ to show something spreading to others, not just one agent getting a wallet.
---
-<a id="sec-544"></a>
+<a id="sec-568"></a>
> **Source:** `docs/x-posts/metaplex-agent-mcp-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -127465,7 +133129,7 @@ keys, your limits.**
---
-<a id="sec-545"></a>
+<a id="sec-569"></a>
> **Source:** `docs/x-posts/news-archive-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -127555,11 +133219,11 @@ If someone asks how it stays current: the archiver runs hourly against all 197 f
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-299).
+mirror, archive search, and the agent knowledge corpus. See [docs/news-rights.md](#sec-310).
---
-<a id="sec-546"></a>
+<a id="sec-570"></a>
> **Source:** `docs/x-posts/onchain-agent-wallets-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -127745,7 +133409,7 @@ Post 1 is the main post above. Then:
---
-<a id="sec-547"></a>
+<a id="sec-571"></a>
> **Source:** `docs/x-posts/open-source-ecosystem.md` · [↑ table of contents](#table-of-contents)
@@ -127792,7 +133456,7 @@ Attach: marketing/open-source-ecosystem/images/header-x-article.png, then the ar
---
-<a id="sec-548"></a>
+<a id="sec-572"></a>
> **Source:** `docs/x-posts/oracle-trading-mcp-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -127803,7 +133467,7 @@ 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-325).
+Build plan this announces: [`docs/oracle-trading-mcp-plan.md`](#sec-337).
**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
@@ -127933,7 +133597,7 @@ place to be wrong.
---
-<a id="sec-549"></a>
+<a id="sec-573"></a>
> **Source:** `docs/x-posts/osf-issue-reply.md` · [↑ table of contents](#table-of-contents)
@@ -127981,11 +133645,137 @@ Measured: 231 characters with the URL counted at 23.
## After it is posted
-Nothing. The next move is theirs: on approval they apply the `approved` label and a bot comments on #254 with the booking link. Book a Friday at least two weeks out (2026-09-11 is the first realistic one), then follow the stream runsheet in [../open-source-friday-plan.md](#sec-314).
+Nothing. The next move is theirs: on approval they apply the `approved` label and a bot comments on #254 with the booking link. Book a Friday at least two weeks out (2026-09-11 is the first realistic one), then follow the stream runsheet in [../open-source-friday-plan.md](#sec-325).
---
-<a id="sec-550"></a>
+<a id="sec-574"></a>
+
+> **Source:** `docs/x-posts/proof-of-life-x-post.md` · [↑ table of contents](#table-of-contents)
+
+# X post: proof of life (no mention of the suspension)
+
+**Why this exists.** On 2026-08-28 holders started selling $THREE on the theory that the
+founder's suspended personal account means the team is gone. The answer is not a statement
+about the suspension: [`x-account-appeal.md`](#sec-549) rules out posting about
+it from `@trythreews` while the appeal is open, because a brand-account post linking the two
+handles is exactly what X's ban-evasion clause reaches for. The answer is evidence that the
+team is shipping, from the platform account, in the platform's voice, with links anyone can
+verify in a minute. Nothing below names `@nichxbt`, the suspension, or the sell-off.
+
+**Verified true when written (2026-08-28, from the repo and production):**
+
+- 431 commits to `main` since 2026-08-21 (`git log --since=2026-08-21`).
+- 65 entries in the public changelog dated 2026-08-21 or later (`data/changelog.json`).
+- Four features shipped on 2026-08-28: the iOS app's web half, the avatar in a terminal
+ (a coding agent's face), agents that explain why they are idle, and Knock.
+- Production was redeployed on 2026-08-28 at 06:56 UTC from commit `ad7b54c16`
+ (`https://three.ws/api/version`, public).
+- three.ws is open source under Apache 2.0 since 2026-08-21 (`github.com/nirholas/three.ws`).
+- `/changelog`, `/community`, and the GitHub repo all answer 200.
+
+**Do not claim:** a date for anything not yet shipped, a token price or buyback, anything
+about the personal account, and nothing apologetic or defensive. Confident and specific only.
+Do not reply to "exit scam" accusations with a denial; reply with the changelog link.
+
+## Main post (@trythreews)
+
+```
+Shipped to three.ws this week:
+
+- Your avatar runs in a terminal and can be your coding agent's face
+- Agents that tell you why they are idle
+- Knock: put a price on reaching you
+- The iOS app's web half
+- 60+ changelog entries, 400+ commits, fully open source
+
+Every line is public. three.ws/changelog
+```
+
+Count: 307 characters (the URL counts as 23); needs Premium, which @trythreews has.
+
+## Reply 1 (verification)
+
+```
+Want to check for yourself? Three links, no login:
+
+Live build and commit: three.ws/api/version
+Every commit: github.com/nirholas/three.ws/commits/main
+Every channel and the $THREE contract address in one place: three.ws/community
+```
+
+## Reply 2 (what is next, only what is already in main)
+
+```
+Next up, already in main and heading to production: the rest of the iOS app.
+
+We ship on weekends too. Watch the commit log.
+```
+
+## Telegram (@three_ws), same day
+
+Post the main post's text as one message, with the changelog link. Pin it. If someone asks
+about the personal account in the channel, the answer is one line and links, not a thread:
+"The team is here and shipping daily. Everything we do is public: three.ws/changelog,
+github.com/nirholas/three.ws. The only official X account is @trythreews; verify every
+channel at three.ws/community."
+
+## Cadence
+
+One shipping post per day from `@trythreews` until the appeal resolves, each one naming a
+real feature from that day's changelog. Daily evidence of work is the only thing that
+answers "they left", and it costs nothing under X's policy.
+
+## Official-channels post (@trythreews), for the impersonation risk
+
+The community asked for a warning so scammers cannot trade on the personal account being
+down. This post gives them the warning without the platform account naming the suspended
+handle or the word "suspended" (see the appeal file for why that matters). What scammers
+actually do is DM holders about a "new token", a "migration", or an "airdrop" from a
+lookalike handle, so the post pre-empts exactly those three.
+
+```
+A reminder on what is official, because lookalike accounts are circulating:
+
+The only three.ws account on X is @trythreews. We are posting from no other account right now.
+
+$THREE has one contract address, and it is not changing:
+FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
+
+There is no new token, no migration, no airdrop, and no presale. Anyone offering one is a scammer.
+
+Nobody from the team will ever DM you first or ask you to send tokens.
+
+Verify every channel and the address at three.ws/community
+```
+
+Count: 466 characters (URL as 23). Pin it.
+
+**What the post says about $THREE, and why only that:** the contract address, that it is
+unchanged, and the four things scammers offer (new token, migration, airdrop, presale).
+Those are provable from the chain. Do not add "the team is not selling" or anything about
+holdings or price: it cannot be verified from a post, and a claim that later looks wrong is
+what turns a panic into a rug narrative. Let the shipping post above carry the confidence.
+
+## Telegram and three.ws/community: the explicit version
+
+Telegram and the site are ours, not X's, so they can name the account:
+
+```
+Heads up: the founder's personal X account @nichxbt is currently suspended (an appeal is in with X). Until it is back, treat anything posted or DMed in that name as fake.
+
+Official X: @trythreews only.
+$THREE contract: FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump. Same address as always. No new token, no migration, no airdrop.
+Nobody from the team DMs first.
+
+Full list of channels: three.ws/community. The work has not stopped: three.ws/changelog.
+```
+
+Pin this in @three_ws alongside the shipping post.
+
+---
+
+<a id="sec-575"></a>
> **Source:** `docs/x-posts/pumpfun-article-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -128102,7 +133892,7 @@ Pick one option. Do not post all four.
---
-<a id="sec-551"></a>
+<a id="sec-576"></a>
> **Source:** `docs/x-posts/sperax-staking-in-chat-x-post.md` · [↑ table of contents](#table-of-contents)
@@ -128208,7 +133998,7 @@ on the `/staking` page footer, so anyone who tries it gets exactly what the post
---
-<a id="sec-552"></a>
+<a id="sec-577"></a>
> **Source:** `docs/x-posts/the-first-19-weeks.md` · [↑ table of contents](#table-of-contents)
@@ -128269,14 +134059,14 @@ The First 19 Weeks is out: the whole story of three.ws since the first commit, 9
---
-<a id="sec-553"></a>
+<a id="sec-578"></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-554).
+[threews-avatar-video-script.md](#sec-579).
**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.
@@ -128426,7 +134216,7 @@ Carries the part that does not fit the main post without spending its outbound l
---
-<a id="sec-554"></a>
+<a id="sec-579"></a>
> **Source:** `docs/x-posts/threews-avatar-video-script.md` · [↑ table of contents](#table-of-contents)
@@ -128434,9 +134224,9 @@ Carries the part that does not fit the main post without spending its outbound l
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-553), the spoken lines live in
-[metaplex-agent-deployer-video-script.md](#sec-540), and the
-deployer-specific shot list lives in [metaplex-agent-mcp-x-post.md](#sec-544).
+[threews-avatar-launch.md](#sec-578), the spoken lines live in
+[metaplex-agent-deployer-video-script.md](#sec-564), and the
+deployer-specific shot list lives in [metaplex-agent-mcp-x-post.md](#sec-568).
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
@@ -128579,7 +134369,7 @@ Keep the pause after "It has no body." That silence is the whole premise.
---
-<a id="sec-555"></a>
+<a id="sec-580"></a>
> **Source:** `docs/x-posts/x-meetup-posts.md` · [↑ table of contents](#table-of-contents)
@@ -128636,13 +134426,13 @@ https://community.ibm.com/community/user/discussion/community-meetup-inside-thre
---
-<a id="sec-556"></a>
+<a id="sec-581"></a>
> **Source:** `docs/x402-buyer.md` · [↑ table of contents](#table-of-contents)
# x402 Buyer Client
-To consume a paid [x402 endpoint](#sec-559) — ours or anyone's — a
+To consume a paid [x402 endpoint](#sec-584) — 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
@@ -128709,7 +134499,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-154)).
+`X402_MAX_PER_DAY_ATOMIC`; see [Configuration](#sec-159)).
## Axios variant
@@ -128732,13 +134522,13 @@ set) back into the payment so attribution survives the round trip.
## Related
-- [x402 protocol](#sec-563) — the underlying challenge/settle mechanics.
-- [x402 paid endpoints](#sec-559) — what you can buy from us.
-- [Autonomous x402 loop](#sec-105) — uses this client on a schedule.
+- [x402 protocol](#sec-589) — the underlying challenge/settle mechanics.
+- [x402 paid endpoints](#sec-584) — what you can buy from us.
+- [Autonomous x402 loop](#sec-107) — uses this client on a schedule.
---
-<a id="sec-557"></a>
+<a id="sec-582"></a>
> **Source:** `docs/x402-dev-tools.md` · [↑ table of contents](#table-of-contents)
@@ -128950,13 +134740,13 @@ implementation against a live server.
---
-<a id="sec-558"></a>
+<a id="sec-583"></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-563). Building them is
+three.ws sells 90+ pay-per-call services over [x402](#sec-589). 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,
@@ -128991,7 +134781,7 @@ distribution channel. See the Solana-first rule in `CLAUDE.md`.
Every major surface ranks the same way: **settled transaction count and
distinct buyers in the trailing 30 days**. Metadata quality gets us *found*
(semantic search embeds our `description` fields); paid traffic gets us
-*ranked*. The [autonomous x402 loop](#sec-105) already drives real
+*ranked*. The [autonomous x402 loop](#sec-107) already drives real
settled canary purchases against every `autobuy: true` entry in
[`api/_lib/x402/ring-catalog.js`](../api/_lib/x402/ring-catalog.js) — that loop
is also our 30-day-activity keeper: the CDP Bazaar **drops resources from
@@ -129171,25 +134961,25 @@ script. Everything else above updates itself.
## Related
-- [x402 overview](#sec-563) · [Paid endpoints reference](#sec-559) ·
- [Autonomous loop](#sec-105) · [Buyer client](#sec-556)
+- [x402 overview](#sec-589) · [Paid endpoints reference](#sec-584) ·
+ [Autonomous loop](#sec-107) · [Buyer client](#sec-581)
---
-<a id="sec-559"></a>
+<a id="sec-584"></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-563): the caller hits the endpoint, receives a `402 Payment Required`
+[x402](#sec-589): 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-556). For the loop
-that calls many of them on a schedule, see [Autonomous x402 loop](#sec-105).
+To call these as a buyer, see [x402 buyer client](#sec-581). For the loop
+that calls many of them on a schedule, see [Autonomous x402 loop](#sec-107).
> Source: handlers under [`api/x402/`](../api/x402), pricing
> [`api/_lib/x402-prices.js`](../api/_lib/x402-prices.js), shared handler
@@ -129220,7 +135010,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-154)):
+[Configuration](#sec-159)):
| Key | Meaning |
| ---------------------------------------------------- | ------------------------------------ |
@@ -129282,11 +135072,11 @@ buyer's USDC settles **directly** to that wallet and the platform never holds it
| Endpoint | Receiver | Source |
| -------- | -------- | ------ |
-| `/api/x402/skill-call` | skill **author** | `author_payto_*` ([skill-call.js:196](../api/x402/skill-call.js#L196)) |
+| `/api/x402/skill-call` | skill **author** | `author_payto_*` ([skill-call.js:205](../api/x402/skill-call.js#L205)) |
| `/api/x402/service` | service **provider** | `row.payout_address` ([service.js:91](../api/x402/service.js#L91)) |
| `/api/x402/asset-download` | 3D-asset **creator** | `creator_payto_*` ([asset-download.js:124](../api/x402/asset-download.js#L124)) |
| `/api/x402/animation-download` | clip **creator** | `creator_payto_*` ([animation-download.js:115](../api/x402/animation-download.js#L115)) |
-| `/api/x402/pay-by-name` | **buyer-named** wallet | resolved name/`.sol`/address, direct SPL transfer ([pay-by-name.js:279](../api/x402/pay-by-name.js#L279)) |
+| `/api/x402/pay-by-name` | **buyer-named** wallet | resolved name/`.sol`/address, direct SPL transfer ([pay-by-name.js:280](../api/x402/pay-by-name.js#L280)) |
**2. Post-settlement split** — the USDC lands in the **platform receiver**, then a
*separate* treasury forwards a share out-of-band (these are NOT `payTo` overrides):
@@ -129294,7 +135084,7 @@ buyer's USDC settles **directly** to that wallet and the platform never holds it
| Endpoint | Lands in | Then forwarded to | By |
| -------- | -------- | ----------------- | -- |
| `/api/x402/cosmetic-purchase` | platform receiver | **creator** 50% (≤90% cap) | `COSMETIC_SPLIT_TREASURY_SECRET_KEY_B64` ([cosmetics-economy.js:203](../api/_lib/cosmetics-economy.js#L203); the 50% default and 90% ceiling are [L31-L32](../api/_lib/cosmetics-economy.js#L31)) |
-| `/api/x402/dance-tip` | platform receiver | **dancer** (full tip) | `club-payouts` cron ([club/sweep.js](../api/_lib/club/sweep.js)) paying from `CLUB_SOLANA_TREASURY_SECRET_KEY_B64` ([club/payouts.js:54](../api/_lib/club/payouts.js#L54)) |
+| `/api/x402/dance-tip` | platform receiver | **dancer** (full tip) | `club-payouts` cron ([club/sweep.js](../api/_lib/club/sweep.js)) paying from `CLUB_SOLANA_TREASURY_SECRET_KEY_B64` ([club/payouts.js:55](../api/_lib/club/payouts.js#L55)) |
| `/api/x402/club-cover` | platform receiver (kept) | — (funds the club float; issues a door pass) | — |
`/api/x402/ring-settle` is an **internal** primitive (`discoverable:false`) — it is
@@ -129302,7 +135092,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-294).
+[money map](#sec-304).
## Intel & oracle endpoints
@@ -129323,8 +135113,17 @@ for to feed the oracle and sniper.
Agent-ready answers composed over live market data — composites, verdicts, and
risk flags rather than raw category feeds (the raw feeds stay free at
`/api/defi/*`, `/api/coin/*`, and `/api/news/*`; these paid surfaces are the
-loss-leader funnel's paid tier). Every one refuses before settlement when its
-upstream is down — a buyer is never charged for missing data.
+loss-leader funnel's paid tier). Every one refuses before settlement when it has
+no data to sell, so a buyer is never charged for missing data. The
+DeFiLlama-backed boards (`defi-radar`, `yield-scan`, `stablecoin-health`,
+`hack-check`) and `market-mood` keep a shared last-good copy
+(`cacheWrapLastGood` in `api/_lib/cache.js`) for 15 minutes past their normal
+TTL: a short upstream blip serves that recent copy rather than a refusal, and the
+pre-settle `503` fires only when there has never been data to serve. Their
+upstream reads go through `api/_lib/upstream-fetch.js` (bounded timeout, one
+retry), and `three-intel` reads $THREE's market through the shared failover
+reader (`api/_lib/market/token-market.js`: Birdeye, tokens.xyz, DexScreener,
+GeckoTerminal, DefiLlama, Raydium) instead of a single DexScreener call.
| Endpoint | Default | Returns |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
@@ -129372,7 +135171,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-432)). |
+| `/api/x402/agent-reputation` | $0.01 | Cross-chain 0–100 trust score for any wallet/mint/agent id ([trust primitives](#sec-450)). |
| `/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. |
@@ -129383,8 +135182,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-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-188). |
+| `/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-115). |
+| `/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-194). |
| `/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). |
@@ -129400,11 +135199,11 @@ datapoints at **$0.0005** USDC each by default, overridable per family with
| Endpoint | Default | Returns |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| [`/api/x402/pump-launch`](#sec-351) | $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-351). |
-| [`/api/x402/vanity`](#sec-517) | $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-517). |
-| [`/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/pump-launch`](#sec-364) | $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-364). |
+| [`/api/x402/vanity`](#sec-537) | $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-537). |
+| [`/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-006). |
| [`/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. |
+| `/api/x402/pay-by-name` | $0.001 | Resolve and pay a `@username` / `.sol` name / raw address (see [Agent wallets](#sec-074)); 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. |
| `/api/x402/did` | $0.001 | **POST** is the DID verification canary: it resolves three.ws's published W3C DID document over its real public route, structurally validates it, and returns `{ verified, latency_ms, configured, checks }`. `configured: false` means the resolver answered 404 or could not be reached at all. `mode: "sweep"` audits recent agent identities for resolvable key material instead. **GET** is the free publisher for `/.well-known/did.json`; every other verb returns `405`. |
| `/api/x402/three-buy` | $0.001 | Micro-buy service: one settled toll payment triggers one small, real on-chain USDC to $THREE buy funded by the micro-buy wallet (driven by the `three-buy-loop` cron). |
| `/api/x402/billboard` | $0.05 | Post to the on-platform billboard. |
@@ -129450,10 +135249,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-557). |
-| `/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-557). |
-| `/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-557). |
-| `/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-256). |
+| `/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-582). |
+| `/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-582). |
+| `/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-582). |
+| `/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-266). |
## $THREE only
@@ -129464,16 +135263,221 @@ input and do not promote any specific token.
## Related
-- [Pump Launcher](#sec-351) — the full launch flow, inputs/outputs, and the free `symbol` → launch → `launches` funnel.
-- [x402 protocol](#sec-563) — the challenge/settle mechanics.
-- [x402 buyer client](#sec-556) — how to pay these endpoints in code.
-- [Financial controls](#sec-222): where settled payments are recorded.
-- [Autonomous x402 loop](#sec-105) — the scheduled buyer that drives volume through these endpoints.
-- [MCP tools](#sec-282) — the same capabilities exposed as paid MCP tools.
+- [Pump Launcher](#sec-364) — the full launch flow, inputs/outputs, and the free `symbol` → launch → `launches` funnel.
+- [x402 protocol](#sec-589) — the challenge/settle mechanics.
+- [x402 buyer client](#sec-581) — how to pay these endpoints in code.
+- [Financial controls](#sec-229): where settled payments are recorded.
+- [Autonomous x402 loop](#sec-107) — the scheduled buyer that drives volume through these endpoints.
+- [MCP tools](#sec-291) — the same capabilities exposed as paid MCP tools.
---
-<a id="sec-560"></a>
+<a id="sec-585"></a>
+
+> **Source:** `docs/x402-preflight.md` · [↑ table of contents](#table-of-contents)
+
+# x402 Preflight
+
+**Ask an x402 seller whether it can actually settle, before you sign anything.**
+
+- Try it: [three.ws/preflight](https://three.ws/preflight)
+- Live attestation: [three.ws/.well-known/x402-preflight](https://three.ws/.well-known/x402-preflight)
+- Client: [`@three-ws/x402-preflight`](../packages/x402-preflight)
+- Wire contract: [specs/x402-preflight.md](../specs/x402-preflight.md)
+
+---
+
+## The gap this closes
+
+x402 answers *what does this resource cost*. It has no way to answer *can this
+seller complete the transaction it is charging for*. The two questions share a
+happy path and diverge only after the buyer has committed:
+
+1. Your agent `GET`s a paid route and gets `402` with a price.
+2. Your agent signs a USDC transfer and retries with `X-PAYMENT`.
+3. The seller cannot settle. Your agent gets `502`, having burned a signature, a
+ blockhash and two round trips.
+
+In the sponsored-fee model **your funds were never the problem**. The broken
+thing belongs to the seller: an empty fee wallet, an unreachable facilitator, an
+over-quota RPC. You had no way to see any of it before paying.
+
+We know because we were the broken seller. On 2026-08-28 the three.ws fee sponsor
+held 0.000899107 SOL against a 0.02 SOL floor, which is 0.0000082 SOL of
+spendable headroom, less than two transaction fees. Every transaction it fee-paid
+died at simulation with `InsufficientFundsForRent`. **95 payment attempts, 0
+settled, three hours.** Every one of those was predictable from state our server
+already had and was not publishing.
+
+So we published it, signed it, and wrote the client that reads it.
+
+## Using it
+
+### From an agent
+
+```bash
+npm i @three-ws/x402-preflight
+```
+
+```js
+import { guardedFetch } from '@three-ws/x402-preflight';
+
+// A drop-in fetch that will not spend your money on a seller who cannot deliver.
+const fetch402 = guardedFetch({ prefer: ['solana:mainnet'] });
+
+await fetch402('https://three.ws/api/x402/echo');
+```
+
+Before the request that could trigger payment, the seller's attestation is
+fetched once (cached for its own lifetime), verified offline, and either the
+request goes through on a rail that works, or it throws before your agent signs
+anything.
+
+Want the verdict rather than the guard:
+
+```js
+import { assertPayable, PreflightError } from '@three-ws/x402-preflight';
+
+try {
+ await assertPayable('https://three.ws', 'solana:mainnet');
+} catch (err) {
+ if (err instanceof PreflightError) {
+ err.reason; // 'sponsor_below_floor'
+ err.alternates; // ['eip155:8453'] <- pay here instead
+ err.retryAfter; // 300 <- or come back in 5 minutes
+ }
+}
+```
+
+### From a terminal
+
+```bash
+npx @three-ws/x402-preflight https://three.ws
+```
+
+```
+https://three.ws signed by 87ZCUMTEaXopUJtQoaFcrk7TrxJBtfd4F9RvkqgrQ4Bc
+ attestation verified, valid for another 60s
+
+ NOT PAYABLE solana:mainnet
+ reason sponsor_below_floor
+ settle 0.0% of 76 attempts over 3h (confidence 0.88)
+ retry after 300s
+```
+
+The exit code is the answer, so it composes: `0` payable, `1` verified and not
+payable, `2` unverifiable.
+
+```bash
+npx @three-ws/x402-preflight https://three.ws --network solana:mainnet && ./pay.sh
+```
+
+### From a conversation
+
+The MCP tool `x402_preflight` is free, read-only, and needs no wallet or account.
+Any agent connected to the three.ws MCP server can ask about **any** origin:
+
+> Before you pay that endpoint, check whether it can settle.
+
+It returns the verdict per network with the reason in plain language, the
+suggested retry delay, and any other rail on the same seller that does work.
+
+### From a browser
+
+[three.ws/preflight](https://three.ws/preflight) checks any origin you paste and
+verifies the signature **in your browser**, not on our server. A status page you
+have to trust is worth nothing; this one you can check with devtools open.
+
+## What you get back
+
+```json
+{
+ "solana:mainnet": {
+ "payable": false,
+ "reason": "sponsor_below_floor",
+ "retry_after": 300,
+ "settle": { "rate": 0.0, "attempts": 76, "window_hours": 3, "confidence": 0.88 },
+ "alternates": ["eip155:8453"]
+ }
+}
+```
+
+**`payable` is three-valued**: `true`, `false`, or `"unknown"`. A seller that
+cannot determine its own state must answer `"unknown"` and must never answer
+`true`. That asymmetry is the safety property of the format: acting on `true`
+means an irreversible transfer, so a false `true` is expensive and a false
+`"unknown"` costs a retry. Clients treat `"unknown"` as not payable by default.
+
+**Every rate carries its window and sample.** A seller that settled 3 of 3
+payments overnight reports 100%, which is indistinguishable from a proven rail
+unless `attempts` travels with it. `confidence` is derived from the sample alone
+and is capped below `1`.
+
+**`alternates`** names the other networks on the same seller that are payable, so
+your agent re-routes in the same round trip instead of discovering the outage one
+failed payment at a time.
+
+## Why it is signed
+
+An unsigned health endpoint is a courtesy. A signed, time-bounded one is
+evidence, and three properties follow that a status page cannot give you:
+
+- **Attributable.** A client that paid after reading `payable: true` holds a
+ statement signed by the seller's own key saying the seller believed it could
+ settle, at a stated instant. Between autonomous agents transacting with
+ strangers, that is the difference between "it broke" and "you said it would
+ work".
+- **Unreplayable.** Every attestation carries `expires_at`, and verification
+ *rejects* an expired one. A seller cannot serve a cached healthy attestation
+ through an outage.
+- **Relayable.** Because it verifies offline against a public key, a registry or
+ an index can cache and forward attestations without becoming trusted.
+ Discovery can rank sellers by measured settleability rather than by
+ self-description.
+
+Verification checks the signature, re-derives the digest from the report bytes,
+enforces expiry and rejects a future timestamp, and pins the subject to the
+origin you asked about. All of it happens before any field is readable, because
+a check a caller can forget is one that will be forgotten.
+
+## Serving one from your own endpoint
+
+The format is open and unencumbered. Nothing routes through three.ws, and a
+client needs no coordination with you.
+
+1. Generate an ed25519 keypair; publish the public key wherever you already
+ publish identity.
+2. Answer `GET /.well-known/x402-preflight` with a signed envelope built from
+ whatever settlement health you already measure.
+3. Keep the TTL short. A long TTL is a weaker assurance, not a stronger one.
+
+If you measure nothing yet, report `"unknown"`. That is honest and still useful:
+a client learns you are not claiming health you cannot back up.
+
+The full normative contract, including the canonicalization rules and the
+verification steps a conforming client must perform, is in
+[specs/x402-preflight.md](../specs/x402-preflight.md). The reference server is
+[api/x402/preflight.js](../api/x402/preflight.js) and the pure format core is
+[api/_lib/x402/preflight.js](../api/_lib/x402/preflight.js), both under 300
+lines.
+
+## What it does not promise
+
+- **Not a guarantee.** It is the seller's signed, timestamped best assessment. A
+ rail can fail in the seconds after it signs.
+- **Not a reputation system.** It reports current settleability, not honesty or
+ history. It is an input a reputation system could use.
+- **It does not stop a seller lying.** It makes lying attributable.
+
+## Related
+
+- [docs/x402.md](#sec-589) walks the payment flow itself.
+- [docs/mcp.md](#sec-293) covers connecting an agent to the three.ws MCP server.
+- [specs/x402-preflight.md](../specs/x402-preflight.md) is the wire contract.
+
+---
+
+<a id="sec-586"></a>
> **Source:** `docs/x402-ring-economy.md` · [↑ table of contents](#table-of-contents)
@@ -129788,6 +135792,16 @@ then kept in a verified, watched, auto-fundable state:
the sponsor" attack **and** enforces "only our wallets settle here".
- **SOL floor.** Below `X402_SPONSOR_SOL_FLOOR_LAMPORTS` (default 0.02 SOL) the
facilitator refuses to settle, pausing the loop before it can drain your SOL.
+ The floor guard is written by two witnesses, not one: the balance read, and
+ the chain's own verdict. `noteSponsorRentFailure()` trips it whenever a
+ settle simulation (or the rebalancer's sweep broadcast) fails with
+ `InsufficientFundsForRent` on account index 0 and that fee payer is our
+ sponsor, so a dry wallet is caught even while every RPC lane is over quota
+ and `getBalance` cannot answer (on 2026-08-28 that gap cost three hours and
+ 95 unsettleable payments). A buyer paying its own fee never trips it. The
+ autonomous loop reads the same guard (`sponsorKnownBelowFloor()`) when its
+ once-per-tick balance read fails, so an unreadable balance never reads as
+ solvent.
- **Runway alert.** The floor says the rail is already dead. The runway says
how long until it is, and it pages first: the ring monitor measures the
sponsor's burn from `fee_lamports` over `X402_SPONSOR_BURN_WINDOW_DAYS`
@@ -129807,7 +135821,10 @@ then kept in a verified, watched, auto-fundable state:
returns a real economic-tick receipt.
- **Rebalancer** — [api/_lib/x402/pipelines/ring-rebalance.js](../api/_lib/x402/pipelines/ring-rebalance.js),
registered in the autonomous loop. Sweeps treasury→payer so the float never
- drains. Recirculation, not spend — never consumes the daily spend cap.
+ drains. Recirculation, not spend: never consumes the daily spend cap. A
+ sweep broadcast rejected for the sponsor's rent exemption feeds the floor
+ guard above (most of the 2026-08-28 faults arrived through this branch, not
+ through settle simulation).
- **Net-position report** — [api/x402-ring.js](../api/x402-ring.js). `GET
/api/x402-ring?period=24h|7d|30d|all`. Gross volume, tx count, SOL burned (in
SOL + USD), sweep totals, live balances, the two fee-efficiency numbers
@@ -129818,6 +135835,11 @@ then kept in a verified, watched, auto-fundable state:
registered as `fee-audit` (nightly). Measures the real per-settlement and
per-$100 fee burn into `x402_fee_audit`, alerts on drift, and closes empty
non-role ATAs to reclaim their rent. Audit + reclaim only — never a spend.
+ This pipeline, the rebalancer and the pool funder all take their blockhash
+ from the shared read guard (`api/_lib/solana/read-guards.js`), which answers
+ from a hash still inside its validity window when the chain is briefly
+ unreadable, so a short RPC blip no longer throws a cron tick straight into an
+ ops alert; USDC's decimals resolve locally and cost no RPC call at all.
- **Endpoint catalog** —
[api/_lib/x402/ring-catalog.js](../api/_lib/x402/ring-catalog.js) is the single
source of truth for **every** paid x402 endpoint on the platform (84 entries as
@@ -130572,7 +136594,7 @@ activation runbook above is the fix.
---
-<a id="sec-561"></a>
+<a id="sec-587"></a>
> **Source:** `docs/x402-solana-july-roundup-response.md` · [↑ table of contents](#table-of-contents)
@@ -130590,7 +136612,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-535): `@trythreews` posts the institutional version, `@nichxbt`
+[event-x-posts.md](#sec-559): `@trythreews` posts the institutional version, `@nichxbt`
posts the human one. Do not post both within a few minutes of each other.
---
@@ -130631,7 +136653,7 @@ the specific claim the roundup credited us for. Second choice: the AR drop-in on
---
-<a id="sec-562"></a>
+<a id="sec-588"></a>
> **Source:** `docs/x402-studio.md` · [↑ table of contents](#table-of-contents)
@@ -130641,11 +136663,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-563) 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-589) 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-556) and the [paid endpoint catalog](#sec-559).
+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-581) and the [paid endpoint catalog](#sec-584).
## How it works
@@ -130659,7 +136681,7 @@ The page (`public/x402/studio.js`) is a dependency-free vanilla-JS single-page a
**SNS name resolution** (`/api/sns`) resolves a `.sol` name (including subdomains like `nich.threews.sol`) to an address, and reverse-resolves an address to its primary `.sol`, via Bonfida's `@bonfida/spl-name-service` `resolve()` on Solana mainnet. It always answers 200 (`resolved: false` on a miss, not a 404) and caches results in-process (5 minutes positive, 60 seconds negative).
-**Real USDC send** (`/api/x402/pay-by-name`) routes a payment by name across three namespaces in order: a raw base58 address, a `<name>.sol` resolved on-chain, or an `@username` mapped to that user's default agent's Solana address. Studio uses `mode: 'prep'`, which builds an unsigned SPL USDC transfer (mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) with your Phantom wallet as fee payer and source, returns the base64 transaction for signing, and caps the amount at 10,000 USDC per call. This send path is Solana-only (Phantom plus SPL USDC); Base is supported as a payout, agent, or charity destination, not in the send tool.
+**Real USDC send** (`/api/x402/pay-by-name`) routes a payment by name across three namespaces in order: a raw base58 address, a `<name>.sol` resolved on-chain, or an `@username` mapped to that user's default agent's Solana address. Studio uses `mode: 'prep'`, which builds an unsigned SPL USDC transfer (mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) with your Phantom wallet as fee payer and source, returns the base64 transaction for signing, and caps the amount at 10,000 USDC per call. The blockhash in that transaction comes from the shared Solana read guard, which serves a cached hash still inside its validity window when the RPC is briefly unreadable. This send path is Solana-only (Phantom plus SPL USDC); Base is supported as a payout, agent, or charity destination, not in the send tool. The `@solana/web3.js` signing component is fetched on demand through `/load-module.js`, which tries esm.sh, then jsdelivr and unpkg for the same pinned version, each under a deadline; if all three are unreachable or blocked, the status line names the hosts, states that nothing was sent, and re-enables the button.
**Storefront builder.** A palette of eight blocks (hero, product grid, single product, text, image, button, divider, footer) drops onto a canvas with HTML5 drag-and-drop and reorder. Save keeps it a draft; Publish sets `store_published` and serves it at `/store/<handle>`. Layout is capped at 60 blocks.
@@ -130731,16 +136753,16 @@ const { tx_base64, blockhash } = await res.json();
## Related
-- [x402: paid agent skills](#sec-563): the payment protocol Studio sits on top of
-- [Financial controls](#sec-222): where settled payments are recorded
-- [x402 paid endpoints](#sec-559): the platform's own catalog of paid endpoints
-- [x402 buyer client](#sec-556): the caller side of a 402 challenge
-- [x402 developer tools](#sec-557) and [x402 distribution](#sec-558)
+- [x402: paid agent skills](#sec-589): the payment protocol Studio sits on top of
+- [Financial controls](#sec-229): where settled payments are recorded
+- [x402 paid endpoints](#sec-584): the platform's own catalog of paid endpoints
+- [x402 buyer client](#sec-581): the caller side of a 402 challenge
+- [x402 developer tools](#sec-582) and [x402 distribution](#sec-583)
- Pages: [/x402/studio](https://three.ws/x402/studio) · [/x402](https://three.ws/x402)
---
-<a id="sec-563"></a>
+<a id="sec-589"></a>
> **Source:** `docs/x402.md` · [↑ table of contents](#table-of-contents)
@@ -130754,7 +136776,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-559).
+[x402 paid endpoints](#sec-584).
**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.
@@ -130910,20 +136932,20 @@ Each package has its own repository with a full README, API reference, and examp
## Tutorials
-- [Pay for an x402 service](#sec-472) — settle a paid request end to end with `@three-ws/x402-fetch`.
-- [Build a paid x402 endpoint](#sec-471) — stand up a seller endpoint with `@three-ws/x402-server`.
+- [Pay for an x402 service](#sec-492) — settle a paid request end to end with `@three-ws/x402-fetch`.
+- [Build a paid x402 endpoint](#sec-491) — stand up a seller endpoint with `@three-ws/x402-server`.
## Related
-- [x402 paid endpoints](#sec-559) — the catalog of the platform's own paid endpoints.
-- [Financial controls](#sec-222): where settled payments are recorded.
-- [x402 buyer client](#sec-556) — how to settle a 402 challenge in code.
-- [x402 bazaar over MCP](#sec-283) — discover and pay endpoints through the MCP bazaar.
-- [Autonomous x402](#sec-105) — agents paying for services on their own.
+- [x402 paid endpoints](#sec-584) — the catalog of the platform's own paid endpoints.
+- [Financial controls](#sec-229): where settled payments are recorded.
+- [x402 buyer client](#sec-581) — how to settle a 402 challenge in code.
+- [x402 bazaar over MCP](#sec-292) — discover and pay endpoints through the MCP bazaar.
+- [Autonomous x402](#sec-107) — agents paying for services on their own.
---
-<a id="sec-564"></a>
+<a id="sec-590"></a>
> **Source:** `docs/zauth/database.md` · [↑ table of contents](#table-of-contents)
@@ -131069,7 +137091,7 @@ Use this endpoint to browse all known x402 endpoints before your agents commit t
---
-<a id="sec-565"></a>
+<a id="sec-591"></a>
> **Source:** `docs/zauth/index.md` · [↑ table of contents](#table-of-contents)
@@ -131089,11 +137111,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-568)### [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-567)### [DatabaseLive registry of x402 endpoints. AI agents continuously test and verify endpoints, tracking success rates, pricing, and response data.Database](#sec-564)### [Provider HubManage your x402 endpoints. Monitor health, track agent interactions, configure refunds, and verify your services through our SDK.Provider Hub](#sec-566)
+### [VectorAI-powered vulnerability scanner. Automated recon, multi-category exploit testing, and detailed security reports for your web applications.Vector](#sec-594)### [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-593)### [DatabaseLive registry of x402 endpoints. AI agents continuously test and verify endpoints, tracking success rates, pricing, and response data.Database](#sec-590)### [Provider HubManage your x402 endpoints. Monitor health, track agent interactions, configure refunds, and verify your services through our SDK.Provider Hub](#sec-592)
---
-<a id="sec-566"></a>
+<a id="sec-592"></a>
> **Source:** `docs/zauth/provider-hub.md` · [↑ table of contents](#table-of-contents)
@@ -131195,7 +137217,7 @@ Supply your EVM or Solana private keys to enable automatic refunds when your end
---
-<a id="sec-567"></a>
+<a id="sec-593"></a>
> **Source:** `docs/zauth/reposcan.md` · [↑ table of contents](#table-of-contents)
@@ -131521,7 +137543,7 @@ TypeScript -@x402/fetch
---
-<a id="sec-568"></a>
+<a id="sec-594"></a>
> **Source:** `docs/zauth/vector.md` · [↑ table of contents](#table-of-contents)
diff --git a/marketing/mainstgrowth/og.png b/marketing/mainstgrowth/og.png
deleted file mode 100644
index 0298a28bd..000000000
Binary files a/marketing/mainstgrowth/og.png and /dev/null differ
diff --git a/marketing/mainstgrowth/render-card.mjs b/marketing/mainstgrowth/render-card.mjs
deleted file mode 100644
index fefd844df..000000000
--- a/marketing/mainstgrowth/render-card.mjs
+++ /dev/null
@@ -1,14 +0,0 @@
-import sharp from "sharp";
-const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
-<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#FF37C7"/><stop offset="1" stop-color="#FC72FF"/></linearGradient></defs>
-<rect width="1200" height="630" fill="#131313"/>
-<rect x="0" y="0" width="1200" height="630" fill="url(#g)" opacity="0.12"/>
-<circle cx="170" cy="315" r="96" fill="url(#g)"/>
-<text x="170" y="350" text-anchor="middle" font-family="Inter, Helvetica, Arial, sans-serif" font-size="88" font-weight="700" fill="#fff">P</text>
-<text x="320" y="285" font-family="Inter, Helvetica, Arial, sans-serif" font-size="96" font-weight="700" fill="#fff">PAIR</text>
-<text x="320" y="360" font-family="Inter, Helvetica, Arial, sans-serif" font-size="44" fill="#9B9B9B">PAIR on Robinhood Chain</text>
-<text x="320" y="480" font-family="Inter, Helvetica, Arial, sans-serif" font-size="40" font-weight="600" fill="#FF37C7">Swap on Uniswap</text>
-<text x="1160" y="590" text-anchor="end" font-family="Inter, Helvetica, Arial, sans-serif" font-size="30" fill="#9B9B9B">mainstgrowth.com</text>
-</svg>`;
-await sharp(Buffer.from(svg)).png({ compressionLevel: 9 }).toFile("og.png");
-console.log("ok");
diff --git a/marketing/mainstgrowth/worker.js b/marketing/mainstgrowth/worker.js
deleted file mode 100644
index 1896981d6..000000000
--- a/marketing/mainstgrowth/worker.js
+++ /dev/null
@@ -1,73 +0,0 @@
-// Cloudflare Worker for mainstgrowth.com: serves an X/OG link card that mirrors the
-// Uniswap token page it forwards to. Humans are redirected client-side; crawlers get a 200 with tags.
-const CHAIN = "ROBINHOOD";
-const CHAIN_LABEL = "Robinhood Chain";
-const TOKEN = "0x6b1d42927b1a84ec28fa88d4fc6fa7af404966be";
-const DEST = "https://app.uniswap.org/explore/tokens/robinhood/" + TOKEN;
-const SITE = "https://mainstgrowth.com";
-const OG_PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAABLAAAAJ2CAYAAABPQHtcAAAACXBIWXMAAAsTAAALEwEAmpwYAAAgAElEQVR42uzdh5tcZcHw//e/+L0vEIogRdpuyqZuOumkEkIqkAIECITeQu+I9CaIoGJFVB7rg6KIiqgoCAKCNKUJIYFQQoDs3r9zz7Jh9uzM7rTdndn5zHV9LjHZPXOmbXK+ucv/2f//2zP0mP8b7QVQ3/5fPfoCQO3ZrlrtDdB7tqc67EPK/+m5cCVeAYhXAMKVcAUIVwhX1RiwhCsA4QpAuBKuAOEK4aoqA5ZwBSBcAQhXwhUgXCFcVWXAEq4AhCsA4Uq4AsQrhKuqDFjCFYBwBSBeCVeAcIVwVZUBS7gCEK4AhCvhChCuEK+qMmAJVwDCFYBwJV4BwhXCVVUGLOEKQLgCEK6EK0C4QriqyoAlXAEIVwDClXAFCFcIV1UZsP6veAVQn/HKBTAgXAlXgHCFcFULAUu4AjDqCkC4Eq4A4QrhqioDlnAFIFwBCFfCFSBcIVxVbcBy0QoIV8IVgHAlXAHiFcKVgAUgXAlXAP0pXrmIBoQr4QoBC0C4Eq4AhCsA0Ui4QsAChCvhCkC4Eq8A4QrxSsACEK6EKwDhCkC4Eq4QsACEK+EKEK6EK0C4QrgSsADEK+EKQLgCEK6EKwQsAOFKvAKEK+EKEK4QrhCwAOFKuAIQroQrQLgSrhCwAIQr4QpAuAIQr4QrBCxAuBKuAIQr4QoQrhCuBCwA4Uq4AuhP8cpFNCBcCVcIWADClXAFYNQVgGgkXiFgAcKVcAUgXAlXgHCFcCVgAQhXwhWAcAUgXAlXCFgA4pVwBQhXwhUgXCFcIWABwpV4BSBcAQhXwhUCFoBwJVwBwpVwBQhXCFcIWIBwJVwBCFfCFSBcCVcIWADClXAFIFwBiFfCFQIWIFwJVwDilXAFCFcIVwhYgHAlXAEYdQUgXIlXCFgAwpVwBQhXwhUgXCFcIWABwpVwBSBcAQhXwhUIWIBwJVwBwpVwBQhXCFcIWIB4JV4BCFfCFSBcIVwhYAHClXAFIFwBCFfCFQIWgHDlIhgQroQrQLhCuELAAoQr4QpAuAIQr4QrELAA4Uq4AsQr4QoQrhCuELAA4Uq4AhCuxCtAuBKvQMAChCvhCkC4AhCMhCsELEC4Eq4AhCvhChCuEK4QsADhSrgCEK4AhCvhCgQsQLwSrwDhSrgChCuEKwQsQLgSrgCEKwDhSrgCAQsQroQrQLgSrgDhCuEKAQsQroQrAOFKuALEK0QTBCxAuBKuAGoiXrmIBoQr4QoELEC4Eq4AjLoCEI3EKxCwQLgSrgCEK+EKEK4QrhCwAOFKuAIQrgCEK+EKBCxAuBKuAOFKuAKEK4QrBCxAvBKvAIQrAOFKuAIBCxCuhCtAuBKuAOEK4QoELBCuhCsA4Uq4AoQr4QoELEC4Eq4AhCsA8Uq4AgELhCvhCkC8Eq4A4QrhCgELEK6EKwDhCkC4Eq9AwAKEK+EKEK7EK0C4QrgCAQuEK+EKQLgCEK6EKxCwAOFKuAKEK+EKEK4QrkDAAvFKuAIQroQrQLhCuAIBC4Qr8QpAuAIQroQrELAA4cpFMCBcCVeAcIVwBQIWCFfCFYBwBSBeCVcgYAHClXAFiFfCFSBcIVyBgAXClXAFIFy5iAaEK+EKELBAuBKuAEwXBBCNxCsQsEC4Eq4AhCvhChCuEK5AwALhSrgCEK4AhCvhCgQsQLwSrgDhSrgChCuEKxCwQLgSrwCEKwDhSrgCBCwQroQrQLgSrgDhCuEKBCwQroQrAOFKuALEK4QGELBAuBKuAIQrAOFKuAIBC4Qr4QpAvBKuAOEK4QoELBCuhCsAo64AhCvxChCwQLgSrgDhSrgChCuEKxCwQLgSrgCEKwDhSrgCBCwQr4QrQLgSrgDhCuEKBCwQrsQrAOFKuAKEK4QrELBAuBKuAIQrAOFKuAIELBCuXAQDwpVwBQhXCFcgYIFwJVwBCFcA4pVwBQhYIFwJV4B4JVwBwhXCFSBgIVwJVwDClXgFCFfiFSBggXAlXAEIVwDClXAFCFgIV8IVgHAlXAHCFcIVCFggXAlXAMIVgHAlXAECFohX4hUgXAlXgHCFcAUIWAhXwhWAcAUgXAlXgIAFwpVwBQhXwhUgXCFcAQIWwpVwBSBcCVeAeIULexCwQLgSrgBqI165iAaEK+EKELBAuBKuAIy6AhCNxCtAwEK4Eq4AhCvhChCuEK4AAQvhSrgCEK4AhCvhChCwQLgSrgDhSrgChCuEK0DAQrwSrwCEKwDhSrgCBCwQroQrQLgSrgDhCuEKELAQroQrAOFKuAKEK+EKQMBCuBKuAIQrAPFKuAJq0A5tBCyEK+EKEK+EK0C4QrgCqjJcCVgIV8IVIFyJV4BwhXgFVHW4ErAQroQrQLgSrgDhCuEKqOpwJWAhXAlXgHAlXAHCFcIVUPXxSsBCuBKuAOFKuAKEK4QroGrDlYCFeCVeAcKVcAUIVwhXQFWHKwEL4Uq4AoQr4QoQrhCugKoOVwIWwpVwBQhXwhUgXCFcAVUdrgQshCvhChCuhCtAvEK4Aqo6XAlYCFcA4pVwBQhXCFdAVYcrAQvhCkC4Eq4A4QrxCqjqcCVgCVfCFYBwJV4BwhXCFVDV4UrAEq6EKwDhSrgChCuEK6Dq45WAJVwJVwDClXAFCFcIV0DVhisBS7wSrgCEK+EKEK4QroCqDlcClnAlXgEIV8IVIFwhXAFVHa4ELOFKuAIQroQrQLgSrgCqOlwJWMKVcAUgXAlXgHglXAFUdbgSsIQr4Qqg7uOVi2hAuBKuAKo7XAlYwpVwBSBcAQhXwhVAVYcrAUu4Eq4ATBcEEK7EK0C4qgkClnAlXAEIVwDClXAFCFcCFsKVcAUIV8IVIFwhXAHilYAlXglXAMKVcAUIV8IVQL8KVwKWcCVeAQhXAMKVcAUIVwIWwpVwBQhXwhUgXCFcAcKVgCVcCVcAwhWAeCVcAfTLcCVgCVfCFYBwBSBcCVeAcCVgIVwJV4B4JVwBwhXCFSBcCVjClXAFYNQVgHAlXgHClYCFcCVcAcKVcAUIVwhXgHAlYAlXwhWAcCVcAcKVcAUgXglY4pVwBSBcAQhXwhUgXAlYwpV4BSBcCVeAcIVwBQhXApZwJVwBCFcAwpVwBQhXAhbClXAFCFfCFSBcIVwBwpWAJVwJVwDCFYB4JVwBiFQClnAlXAHilXAFCFcIV4BwJWAJV8IVgHAlXgHCFeIVIFz1hH0FLOFKuAKEK+EKEK4QrgDhqjrDVTsBS7gSrgDhSrgChCuEK0C8qspwJWAJV8IVIFwJV4BwhXAFCFdVHa4ELPFKvAKEK+EKEK4QrgDhqqrDlYAlXAEIV8IVIFwhXAHCVdXHKwFLuAIQroQrQLhCuAKEq6oNV/UdsIQrAOFKuALEK4QrQLiq+nBVnwFLuAIQr4QrQLhCuAKEq5oJV/UVsIQrAOFKvAKEK8QrQLiquXBVHwFLuAIQroQrQLhCuAKEq5oNV/07YAlXAMKVcAUIVwhXgHhV8+GqfwYs4QpAuBKuAOEK4QoQrvpNuOp/AUu8AhCuhCtAuEK4AoSrfhWu+k/AEq4AhCvhChCuEK4A4arfxqvaDljCFYBwJVwBwhXCFSBc9etwVbsBS7gCEK6EK0C8QrgChKu6CFe1F7CEKwDxSrgChCuEK0C4qqtwVTsBS7gCEK7EK0C4QrwChKu6DFfVH7CEKwDhSrgChCuEK0C4qutwVb0BS7gCEK6EK0C4QrgCxCvhqioDlnAFIFwJV4BwhXAFCFfCVdUGLPEKQLgSrgDhCuEKEK6Eq6oMWMIVgHAlXAHCFcIVIFyJV1UZsIQrAOFKuAKEK4QrQLgSrqoyYAlXAMKVcAWIVwhXgHAlXFVlwBKuAMQr4QoQrhCuAOFKuKrKgCVcAQhXwhUgXCFeAcKVcFWVAUu4AhCuxCtAuEK4AoQr4aoqA5ZwBSBcCVeAcIVwBYhXwlVVBizhCkC4Eq4A4QrhChCuhKuqDVjCFYBwJVwBwhXCFSBcCVdVGbCMugIQroQrQLhCuAKEK+GqKgOWcAUgXAlXgHCFcAUIV+JVVQYs4QpAuBKuAPEK4QoQroSrqgxYwhWAeCVcAcIVwhUgXAlXVRmwhCsA4Uq4AoQrhCtAuBKuqjJgCVcAwpV4BQhXiFeAcCVcVWXAEq4AhCvhChCuEK4A4Uq4qsqAJVwBCFfCFSBcIVwB4pVwJWAJVwDCFYBwJVwBwhXClYAlXgHClXAFCFcIV4BwJVwJWMIVgHAFIFwJVwDClXglYAlXgHAlXAHiFcIVIFwJV/TngOUiGBCuhCtAuEK4AoQr4UrAEq4A+nG8chENCFfCFYBwJVwJWMIVgFFXAKKReAUIV8IV9RCwXAADwpVwBQhXCFeAcCVcCVjCFYBwBSBcCVeAeIVwJWAJV4BwJVwBwhXCFSBcCVfUfMByEQwIV8IVIFwhXAHClXAlYAlXAMIVgHAlXAHCFeKVgCVcAcKVcAUIVwhXgHAlXFHTActFMCBcCVeAeIVwBQhXwhVVGbBcBAPilXAFCFcIV4BwJVxRlQHLBTAgXIlXgHCFeAUIV8IVVRmwXAADwpVwBQhXCFeAcCVcUZUBywUwIFwJV4BwhXAFiFfCFVUZsFwAA8KVcAUIVwhXgHAlXFG1ActFMCBcCVeAcIVwBQhXwhVVGbBcBAPClXAFCFcIV4BwJV5RlQHLRTAgXAlXgHCFcAUIV8IVVRmwXAQDwpVwBYhXCFeAcCVcUZUBy0UwIF4JV4BwhXAFCFfCFVUZsFwAA8KVeAUIV4hXgHAlXFGVAcsFMCBcCVeAcIVwBQhXwhVVGbBcAAPClXAFCFcIV4B4JVxRlQHLBTAgXAlXgHCFcAUIV8IVVRuwXAQDwpVwBQhXCFeAcCVcUZUBy0UwIFwJV4BwhXAFCFfiFVUZsFwEA8KVcAUIVwhXgHAlXFGVActFMCBcCVeAeIVwBQhXwhVVG7BcCAPilXAFCFcIV4BwJVwhYAEYdQUgXIlXgHCFcIWABQhXlTB014Ghea9hBRheUUN3HVSzF9Tx3Mt57MM/P6TPH8PgnRpKOvemXQYWfV/Ddhtc8fdPsUbsMVQIEq4QrgDhSrhCwIJchm3fGObuPDms2X1JuGzvk8LtDReHHwy+Ptw/9KvhkRF3h+dG/yK8PObX4Z3xf874YOLfQuukJzPif78zIfn1CX8JL4/7TXhuzH3hkVH3hPuH3xnuGXJ9uH3gJeGyfU4Oa/ZYGubuMjlzX55z4aoU3/7qN0Nf3lpaWsJbb74Vnn362fD7X/8ufPMrd4ULTz0/LJ52SGgcsG9VXlg//cRTZT3mN15/IzTu0LeP7bTVJ5d07jdcfl3R93XfT/43VNPt/ffeDy89/2L425/+Gn7y/R+H6y+7NqxdflwYt1+zaCRcIVwB4pVwhYBF/9W0XUNY+LkZ4by9jg3faLw8/Gn4d8KGsX8IrROf+NQ/2hyQy5NtJuXyVGidnM/ToXVKR29NfDg8PPJ74RuDrwzn7X1cWLjrgaFJ2BKuqjxgdRka3n0v/OZ/fx3OXHNaVYxaiuaNn12Rx3bEgpUCVhXeXvjXC+HOm+8IS2csCg3xL+eCknAlXAEIV8IVAha1asKAEeG4zy9JRlRdFP42/O6wZXwycmrCE20mpvVOvNpm6j87+GTKU+G5cb8MdzddH9btfUyYutNYr6FwVTMBK/u2+YPNmXOdNmxSn15k33Hj7RV5PP/zvR8JWFV+e/6Z5zKjAUuZNolwJVwBwpVwBQIWfTLC6ojdFoTb978o/GPkj5JQ9XiWJ6o2Xn3mmdA67TP/mfBgJmgdt8ehmcfmNa7vxdlrJWC13z755JPw9S/f2SdrGsUpjXH6X6WmscW1oQSs6r+9/spr4fRjTjUiS7gSrgDhCvEKAYvqM2r7weHsvVaH3zbdGTaPfSS0jn88Fa5qM151MP3ZsHnqE+GBUd8K6/Y5JozcYYjXvg53Fay1gJW9jtThc5b16gV3nPZXydsZx54mYNXQ7be/fMA6WcKVcAUIVwhXCFj0veHbDwxn7HlE+E3THWHLuE+jVbt+GK/Stkx7Mvx61F3h9L2Psih8HYSr9ovJWg1Y8bb1k63hkjMv6rUL7/+5+96Knn9ctF7Aqr1welCyDpoQJV4JV4BwhciCgEWvm7vzpGR64IXh7THJwuvj//6p+opX28z4V8Z7U/8e7h52Q7IQ/EzvkX4XrzpeUNZywGq/XXvJ1T1+4R2n+33w/geV3YFxa0uY0DBGwKqx23vJ5gKLpi0Qo4Qr4QoQroQrELDonXWtLthrTXhyeLKm1bi/Z4Ur8SrtHxN+Hs7fd631svpZuOpPASvezl57Vo9egMedEHviduV5VwhYNXjbsH5DmD58sjAlXIlXgHAlXIGARc8Yu8OwcM3ep4U3mh9oC1fiVZfxqvXA6LmMDVP/Gm4fcnmYuOMo76UanS7YnwPWRx99FA6ZPL/HLsQfeuAPPXLeTz/xlIBVo7cnHn08DNxxP5FKuBKuAOFKuAIBi8qZsuPo8L3GL4UPx/75s3AlXhUcr7J9OP3J8J1h14XJO4323qrhcNXfAla8/fMfT/dIUJjYOC4z3a+nbvP6YE0lAasyt2suvkqsEq6EK0C8Eq5AwKJ84wYMC19N1rdqC1ePiVdlxquMmdHz4aMDnwl3D78pGZHVLFzVYLgqN2D95aE/h/t+/Iui3f+zX4WHH3woPPn3J8Mr/34ltLa2VjQoXHz6BRW/KL/qwiuLOoe///Wxor7+jhtvF7DyLHJfynssLY6ee+wvj4ZnnnomfLj5w4q+397d9G5o3mu4cCUaCVeAcCVcgYBFaUbv0BS+sf+lYcu2cCVeVTJeZftwxlPhzqYrQ3PynAtXtROuyg1YK+YdVpEL35F7DA0rDzo83HXr18PGtzaWHRRee/nVMGjH/St6cf7s088WdQ5LZywKH3/8ccFf/9/X/hsa4x9UAlaH2+zRMyr+uBsH7Btmjpoezj1xXXj4d3+syMi66y69RrhCuAKEK+EKBCyKM3C7fZLF2Y8NG0c/GMK2cCVe9VS8ypjV5u3pfw9XNJyReQ2Eq+oPV9USsLIN3qkhM9ppy4dbygoKJ6w4rmLndPAB84q67ziqLH7fH3/7UFHfd8TBKwSsXghYaXPGzsyMJizn9uJzLwpXCFeAcCVcgYBF4Y7abUF4fvhPM+FKvOrdeNU664Vtnj3gN+GIPRYJV1UerqoxYGVHhbfefKvkoBCnjVXqXL7+5TuLuu/4fMbvu/Ssi4v6vv/53o8ErD4IWFFD8hf8r91yR82tYyZcCVcAwpV4hYBFDa5z9eOB14cw9jHxqo/j1TazXwj/2/z1MHbH4cJVlYarag5Y7SOfPnj/g5LO7f333s9MFavEdLP1b7xZ1H0fs+SozPdOGjS+qPW94jkP3XWQgNUHAatdjIglr712xoXiFcIVIFwJVyBgkd/Jux8e3m7+nXhVZfGqzYvhnQOfCBfsf2Jo+H97i1dVFq6qPWBFN195Y8lBYcGkg8q+/6MXH1nUfb737nthyM6N277/H48+UdT3n37MqQJWHwasMfuMCpve2VTSud773R8KVwhXgHAlXIGARWcHDBgV/jDk623hSryqyniV7Xfjvl87uxXWSbiqhYA1YvemTBQq5XbeSWeXff8/+8FPipsGePe9Hb4/Lu5dzO139z8oYPVhwIriZgKl3P72p78KVwhXgHAlXIGARUcnfP7Q8E7z78WrGolXrXPabJr5ZDhtn9XCVRXFq2oPWNGvfvrLks7vtmtvLTuefbj5wyKnD67ucIzZYw4s6vu3frI1TGgYI2D1YcA68pCVJZ3r66+8JlwhXgHClXAFAhZtmrZrCN/c/7LPwpV4VTPxqnXOS9v8z6jbw/AdBglXfRyuaiVgXXLmRSWd30++/+Oy7vfstWcVdX/vvP1OGLTj/p2O88K/XijqOF8893IBqw8D1rj9mks61zj1ULhCuAKEK+EKBCzC7J0mhhdG/Ey8qvF41e65KQ+GWZ+bJFz1YbiqlYC1ZtnRJZ3fb35xf1n3+6ffP1zU/f3gW/fkPM5Xrru1qOM8/cRTAlYfBqy4cH/L1paiz3XLli3CFcIVIF4JVyBg1bvjP78kvNf8B/Gqn8Sr1rlt3pv1z3DyPkcIV30UrmolYC2dsaik83v4wYdKvs/JgyeElpbiIkacepbrWHEx+WJvc8fNErD6KGBFWz7cUvS5vr1ho3CFcAUIV8IVCFj1qnG7fcJX97sgtI79m3jVz+JV69x/Z7Qk/33b0CuS13pf4UrAymnh1INLOr/f3f/bku/z2kuuLuq+Nr61MQzccb+8x3vxuReLOt5Xb/iKgNVHAWv454eUdK7xNRauEK4A4Uq4AgGrDg3bvjE8MOT2JFg9Kl7103i1zbx/h99NuCeM6Kl1sYSrmg5YRy8+sqTz+9kPf1ryfT7/zHNF3df3vv7dLo9385duLG5B8FdfD43xDy4Bq9c/D3PGzizpXB/7y6PCFcIVIFyJVyBg1ZsJA0aEJ4f9QLyqk3jV7p9THwiTdhotXAlYHaw7/sySzq+7qJR3xNeU+RV/LordjTDeVs1fLmD1QcC6bN0lJZ3rD7/9A/EK4QoQroQrELDqybydJ4fXR/5KvKqzeNU67z8Zr854JMzZdYpwJWBtc89dd5d0ftdcfFVJ93fXbd8o6n7Wv/FmQaOlnnnyn0Ud997v/lDA6oOA9deHHynpXM85YZ1whXAFCFfCFQhY9WLhLtPDO82/E6/qNF612zTn6bB093n9KF5V97Siag9YL7/0cknnF6ceFntfcR2rDes3FHU/37r9roKOfd2l1xR13Pffez8M3XWQgNWLn4VjlhwVSr3NGDFVuEK4AoQr4QoErHqwfNe54f3mh8SrOo9XrQe1eX/OM2HVXouMuqrzgLVm2dElB4UJDWOKvr9jl64u+n4OnbWkoGNPHz45tLa2FnXs048+RcDqpc/BxMZx4dX/vFLSef7r6WeFK8QrQLgSrkDAqgdH73ZI2DLmT+KVeJXl5bB57nNh9V5Lhas6DVhxNNQ///F0Sef2bIlB4Rf3/rzoxdYb4l9ECzz+E48+XuROig8KWL3wGZg8eEJ45qlnSo6lF5x6nnCFcAUIV8IVCFj1EK8+GvNn8Uq86hCv2m056IVw5F5LhKs6DFjf/8b3Sg4KN33xhqLvb+QeQ8OWD7cUdT9f//KdRd3HF8+9vKjjb/1kaxi//2gBq4cM3qkhnHfS2eHdTe+W/F7b9M6mHp3qKVwJV4B4JVyBgEUVOPRzs8Pm0Q+LV+JVznjVOv/l0JLYPO+5sHzPQ4SrOglYMSoUu5B69i1O0yslfMSQUext8bRDirqPSYPGh5aWlqLu44pzLxOwKmjcfs3JWlerwx033h7eevOtUO4t7looXAlXAMKVcAUCVj+25HMzw/ujrXklXnUdr9q9m6yJtWiP2cJVPw9YRxy8Ijz1+JNlBYUH7vtNSff9yEN/Kep+Xvn3K0VNH9x2P38s7n7i81GvAeu5f/4rPPn3J8sW16iK0z3ff/e9UMnbY395tKAdKIUr4QoQrhCuQMCqUfN2nhw2jf69eCVeFRSvWua/krEx2Z1wzm5That+FLDG7jsqHHnIysyUv7huVSVuxY6KiqY0HVD0AutfveErJT3mi8+4sOjHNHfcrLoMWNV8i7tE9uouiaKRcAUIV+IVCFj0rgkDRoTXRv5SvBKviopXGQe/El6e+UiYsPNI4aoKAtb6N94ML7/0ckneefudooNRIbf7fvyLkp6D6y+7tuj7WjDpoJKnsMW1rYq53X79bQJWFd22bNkSVs1fLlwJVwDClXAFAlZ/NXT7hvDE0O+LV+JVSfGq3RPTfh2GDRgoXPVxwKq2W1zPaMw+o0p6Dl587sWi7uul518s6zn/428fKnq3w0pPVROwSrvF+Lh2+XHilXAFIFwJVyBg9VeN2+0Tfjv4q+KVeFVWvGrzavj1hLtDY2b9IeFKwAqZhdGPXbq6pMcfpxwWe7v1mlvKes7PPXFd0fdZ6RE/AlbxtzdefyMcPmeZcCVcAYhRwhUIWP3ZHftdIF6JVxWJV+1uHfFF8UrAytwuPv2CXn3888bPLus5b95rePj444+Lus8ffecHAlYf3n53/28za7YJV+IVIFwhXIGA1Y8d//mloXXs38Qr8api8aplwath64JXwon7HSlc1XHAiutoXXvJ1SU/9kE77h/e3rCx6J3xKvG8x90Si1o0PNlBb+iugwSsXr49+ue/9fx6V6KRcAUIV8IVIGD1vVk7TQzvNz8kXolXFY1X7d496F9h9m5ThKs6DFibP9gcTj3qpLIe+/GHHVv0/cYdEyvxvJ9x7GlF33eMTgJW70wV/M4d3wrL5x4qXAlXAIKUcAUCVj0Yvv3A8MKIn4lX4lWPxKs2r4VnZzwUhu7QKFzVUcB65sl/hvkT55b92EsJK3G64hELVpbthBXHZdbuKnYam4DVs7df/fSXoSGzvp5wJVwBwhXCFQhYdeMHjVeLV+JVj8arjENeC98Zc4twVQcB691N74Yrzrk0DNxxv7If98g9hoYtH26puR3wJjSMEbB6eEOAQ2ctEa6EK0C4QrgCAatenPD5Q8Ur8apX4lW74/ZdIVz104D17xdeCl889/Iwas9hFXvcF5x6Xk1OnYwBr14CVlz3a9M7m0r20UcflXS/cZ2zwTs1CFfCFSBcIV6BgNXfTRwwMrzT/HvxSrzqtXgVbZj3dJiwc7Nw1Q8CVlyc/Z//eDp89YavhBXzDguN8Yd4hR/33/7015oMWE/+/cm6CVizR88o6zEetXBVyc/zzVfeKFwJV4BwhXAFAlZ/94chXxevxKtejVdtXg8PTvqRcNVLASuGlIcffKgsv7v/wXDfj38R7rnr7nDHjbeHc09cF5bNXBxGf2FEjz7m6cMnZyJZrd7mjJ0pYBXoF/f+vKT7jqO3ynqehSPhChCuhCtAwKpu64D8TmQAACAASURBVPY8UrwSr/okXmUsfD2c1rBGuOqFgBVHRtXqY46ja2r59pXrbhWwChTXDHsvmYpYyu3xv/09NA7YV7gSrgDhSrgCBKz+ZswOQ8PG5gfFK/Gqz+JVtOGgf4axO40QpwSsvF56/sWaDlivv/Ja2dMq6yVgRVece1nJz/Vl6y4RrsQrQLgSrgABq7/5+aCbxCvxqk/jVbt7x39dnBKwcopTFPvDrdznv54CVhxF9fQTT5V0Dps/2BymDZskXAlXgHAlXAECVn9x1G4LxCvxqiriVcvC/2as/MISgUrA6uR7X/9uvwhYP/z2DwSsIiyatiC0tLSUdB5xrTbhSrgCxCvhChCw+oGB2+0T/jX8x+KVeFU18apl0X/Dv2b9KQzcfj+RSsDaZvBODeHtjW/3i4D1frKu09BdBwlYRYibBZR6O+PY04Qr4QoQroQrQMCqdZd/4UTxSryqqnjV7sLBp4tUAtY2J648PvSn26lHnSRgFSHubrnxrY0lnUsMn+P2bxaOhCtAuBKuAAGrVjVvPyS8M/r34pV4VXXxKtp48L/C6B2HCVUCVsb9P/tV0Y/z3y+8FKYPn9zjHn7woaLP7cFf/VbAKtI5J6wrORj+7Ic/EZCEK0C4Eq8AAatWfWP/S8Ur8aoq41WbN8IdzdcJVQJWZvTNRx99VPTjvPlLN/bK+Z113OlFn9vWT7aG8fuPFrCK0JBc5Dzy0F9KjljHH36smCRcAcKVcAUIWLVmwoARYcvYP4tX4lXVxqto88KXw8Sdx4hVdR6wLj7jwpIe55yxM3vl/Ebs3hS2fLil6PO7/OxLBKwizRs/O3zyySclndPrr7wWRuzRJCwJV4BwJVwBAlYt+W7DF8Ur8aqq41XL4jbfGH2zWFXnAevvf32s6Mf49BNP9eo5lhJ6nnzsHwJWCb52yx0lj8KKnxmBSbgChCvhChCwasTkHZuT0Vd/Ea/Eq6qPV9GHi14Jk3cZK1jVacCaMWJqaG1tLfoxXn3Rl3r1PE9atbak12LuuFkCVpHiDo6vvfxqSefV0tISDpuzVGwSrwDhSrgCBKxa8L3GL4lX4lVNxKt23x57q2BVpwHry1ffXPTji8Fr6tBJvXqeTbsMDO+9+17R53rbtbcKWCU4+YgTSh6F9eJzL4amzw0UnYQrQLgSrgABq5qNGzAsfJhZ+0q8Eq9qI161LH4zfJCshTVmpxGiVZ0FrLho98svvVz043v0z3/rk/P9n7vvLWldpsb4B52AVZiseBJ3ciz1dstVN4lPwhUgXglXgIBVzW7e9xzxSryqqXjVsqTNDSMuF63qLGAdPmdZSY/vkjMv6pPzPXrxkSWd7/J5hwpYRYSrdjNGTAlbtmwp6fziLpAHT5onRAlXgHAlXAECVjVq2q4hrG9+ULwSr2ouXkXrD342NO3QKFzVUcC65667i1/jaGtLGL//6D4534E77hc2rN9Q9Dn/4Fv3CFhFhKtsN115Q8mjsJ549PHQuOO+opRwBQhXwhVQGQPaCFgVcMFea8Qr8aom41W78wafKlzVScCKa0q9u+ndoh/bQw/8oU/P+7tf+07R5/x+snZWZk0mAavgcNVu8M4NmTWtSr1dcc6l4pRwBQhX4hVQkXAlYFXQk8N/JF6JVzUbr6InZv5euKqTgHXyESeW9NjOXntWTU57POXIEwWs7UqLLEcuXFlywPpw84dh+vDJQpVwBQhXwhVQdrgSsCpk4S4zxCvxqqbjVcuS9aFl6fqwYI/Z4lUdBKwH7vtN0Y/ro48+CqP2HNbnC8+/9vKrRZ/7b3/5gIBVRnD5xb0/Lzli/en3D4eGeIEhXLkgB4Qr4QooI1wJWBVyd+NV4pV4VfPxKvr2uFvFq34esMbuOyp88sknRT+u+3/2q6o4/ztvvqOkRcULXbur3wWsCoSXCQ1jwnvJVMxSb+uOP0O4AhCuhCugrHAlYFXAsO0bw3tjHhavxKuaj1fRpkUvhaEDBgpY/ThgXbbukh6fhteTFk6ZX9L5x8ddVwGrwhHminMvKzlgvb3x7TC+YbR4BSBcCVdAyeFKwKqAM/c8QrwSr/pFvGp3SuOxAlY/Dlj/ePSJoh/T5g82h2G7Da6ax/DS88UvLB4fd10ErB4KMXFHwaefeKrkiPXzH/1MuAIQroQroKx4JWCV6YEhd4pX4lW/iVfRr6b8UMDqpwFr5qjpJT2mn97z46p6HLdcdVNJj2PuuFn9N2D1QpRZNG1BaGlpKTliHb98jXAFIEoJV0BJ4UrAKtOo7QeHLeMeEa/Eq34Tr1qWvRU2L3ktjNyxScDqhwHrtmtvLekxHbt0dVU9jhhwSrnddu2X+1/A6uVAc8837y45YL353zfCqL2GCVeAcIVwBcKVgNXbztnzaPFKvOpX8ardGYPWGoUF1cyufsIVIFwJV0AdhSsBq0y/bbpTvBKv+l28in499UcCAQhXCFeAcCVcAVURrgSsMjRt1xA2j31EvBKv+l28it5f/EoYskODWADCFcIVIFyJV0CfhysBqwyrdztEvBKv+mW8ardyn6WiAYhXCFeAcCVcAX0ergSsMnyj4XLxKh2vTn81hO+/3b172r1TuB+029RB67ffDq1f2xhar1sfWs9/I7Qe9WpbrBKvyopXLYduCHeMuUE4AOFKuAIQroQroM/DlYBVhheafyFepUde3fFWqIrbltYQnt4Swt3vhNaz/tsWqcSrouJV9My8vwgIIFwJVwDClXAF9Hm4ErBKNHHASPEq17TBaglY6dv6rckormS01opXxasC41W7Cbs0iwkgXIlXAMKVcAX0ebwSsEpwyp4rxKtc611Va8Bqv32cjMz68buhddkr4lUB8Spa23CUqADClXAFIEgJV0CfhisBq9T1rxovF69qMWC1397eGlovXC9edROvojvH3SgugHAlXAHiFcIVCFdVQcAq0j9G/Ei8yrXb4B0bQs3cksFYrd96R7zqIl61HLYhPDrndyIDCFfCFSBcIVyBcCVg1Zqm7RrCx+MfE6/S8Wrm87UVsNo71r3vild54lXLYRvDlkPfCE07NAoOIFwJV4BwhXAFwpWAVUsWf26meJUrXtVowMpErK++I17liFftFu45V3gA4Uq4AoQrxCsQrgSsWnL+XmvEq1zxqoYDVkg2KWw5803xKke8itYNPkWAAPFKuAKEK1zYg3AlYNWSuxqvEK9yxataDljx9u+Pk7j0qniVilfR18bdLEKAcCVcAcKVcAUIVwJWLfnz8O+KV7niVXRn8QGr9bYNofXc/+Z2Xrs3OrrszdB67Vuh9dbk/pI1rMLjH4bwYWv5Uwlv2ihe5fDHmfeJESBcCVeAcCVcAcKVgFVL3hr7B/EqV7yaVWLAOu210Drnpc7mtvt3R/Oy/eczi14OrddvyIykKvn2yidtkUq8+szhb4c3Fj0nSoBwJV4BwpVwBYhXAlatGLZ9o3iVL16VHLBeLz9eRQd96pCXQ7hnU8kNq+XM9eJVVryKth6+MQwdMFCgAOFKuAKEK+EKEK4ErFowb5fJ4lW+eDXrhcoErHLiVcbLbb5VWsRqvfc98SorXrWbvfs0oQKEK+EKEK+EK0C4ErBqwXG7LxWv8sWrSgSsSsWraH7iiS3FF6xnPhKvUvEqOnr/FYIFCFfCFSBcCVeAcCVg1YLL9j5JvMoXr8oNWBWOVy3RujeKD1iftCaBSbxKu2jYOuEC4QrhChCuhCtAuBKwasHtDReLV/niVTkBqyfi1afCW1uLXwfr2P+KV9mWvx1uG3OdgIFwhXAFCFfiFSBcCVi14AeDrxev8sWrsgNW5eNVy/xXQuuDHxQfsM57S7zKilcty98J3z/g60IGwhXCFSBcCVeAcCVg1YJfD7tDvMoXr2aXE7B6Jl5lAtYP3y3+nC7bIF5lxavol9PuFTQQrxCuAOFKuAKEKwGrFvx15PfFq3zxKhOwNpYfsCoYrzIB6xvvFH9OV28Ur7LiVfTn2Q+IGghXCFeAcCVcAcKVgFULnh99n3iVL17NfrH8gFXheNVycBKwvrOp+HO6dIN4lRWvomfnPypuIFwhXgHClXAFiFcCVi14feyD4lW+eFVuwOqBeJUJWD99r/g1sM5+S7xKeXXhMyIHwhXCFSBcCVeAcCVg1YIN4x4Sr/LFq3ICVg/Fq0zA+uuHxQesE94Ur1LeWPK82IFwhXAFiFfCFSBcCVi14N3xfxav8sWr6GslBKzTX++xeNWy8JUQNrcWd0IftSYBSrzqYMU74e1lr4geCFcIV4BwJVwBwpWAVQs+POBv4lW+eDWn3IBV4XgVR19dWfyuiOG5j8WrVLxqWbEpfHDYm+IHwhXCFSBcCVeAcCVg1YKtBzwuXuWLV2UFrMrHq5YFr4bw74+LP5+fvi9epeJV9EnydUIIwhXCFSBciVeAcCVg1VzAEq86xKs5L5UYsP5b+Xh18Kuh9cfFL96+bQF38apDvBKwEK4QrgDhSrgChCsBqyanEIpXneJVJQJWJeLVIUm8uvvdkuJVWL81iVHiVTpemUKIeIVwBQhXwhUgXAlYtbSI+4Q/i1f54lW5AasS8eqc9SE8/VEo9db6tU3iVY54Fb19qEXcEa4QrgDhSrgChCsBqyZsGP9H8SpfvCo1YJ3/ZmhN4shnXv3MYa8mISbba585OglMp7wRWq94K7Tem0wXfPHjUNbt7ZYkCP1XvMoRr1pWbgpvLH1BIEG4QrwChCvhChCuBKxa8Pr434tX+eJViQGrWm6tN70jXuWJV9Gri/8llCBcIVwBwpVwBYhXAlYteH7sL8WrfPFqbu0GrNZHtohXXcSrlpXvhmcWPCqYIFwhXAHilXAFCFcCVi14ZNQ94lW+eJUJWG/XXr167ZPQcsQb4lUX8Sr689wHhBOEK1yQA8KVcAUIVwJWLbh/+J3iVb54NffftRewNiS7Dh73pnjVTbyK7pt+r4CCcCVcAQhXwhUgXAlYteCeIdeLV/niVa0FrJeTkVdrxatC4lV096SvCykIV8IVgHAlXgHClYBVC24feIl4lS9e1VDAan34wyTw/Fe8KjBeRbeNu15QQbgSrgCEK+EKEK4ErFpw2T4ni1f54lX09SoPWG9ttdtgCfGqZdW74aLh5wgriFfCFYAYJVwBwpWAVQvW7LFUvMoXr+ZVccD6zyeh9bYkziz7r3hVQryKjm5YJa4gXAlXgHCFcAXCFQJWLZi3yxTxKl+8qqaA1Zp46ePQeu/7oeXcDVnRSrwqJV61rHovzN59msiCcCVeAcIVwhUIVwhYtWDY9o3iVb54VWLAan18S2h9aPNn/liMD0PrA8n/3vdBaP3Be6H1liTSnJNEoZVJiDrk9TbiVdnxamvyv0MHDBJbEK6Eq153+cWXhSuvuDLjwnMuqPjxDz/40G3Hj2aPn9knj3PMfqM6nMfa1ceLJhU0et+Oz+8J/eT5nTZySofHtWrxypoLV4tmHtLhMSyYPl+4AsQrBKxKeWviw+JVrng17z8lBayWM5MANP+VNgenvfqZBWmvtTkkF/GqUvEqemPZi3UTVkbs0RSmj5panOQC4oDB48KoLwwPDfEvsRU6l9H7jOx0X02fG1jeMfce0eF4Y/dv7vLrJw4aV/zz8akDhowPY5KLxoED9hOuetDY/UeF6c1TSzKpaWLmPTAkvq+q9AL9lptvCbfddlvGNVddU/HjH7nsiG3Hj+ZPmdcnj3N845gO53HWKWcKTxU0LvX8nnnyGb123w3JhU98fZfOXRyOPuyoJJ6tzdz/GSedHk469sSwOvm1Q2YcnPmaYo89c+yMDo/r+CPW1NyoqxiRsx9DfJ6EK0C4QsCqkIdHfk+8yhWvyg1Y4lVVxqvooTn3103AWnTggg5/kS7WjTfcGM4985ywOPkX5SG7NJZ1Lhefd1Gn469atKKsY65avKLD8dYeeVyXX3/uGWeX9XxEX/7yl8MlF1wcjly6KolyI0SnCjt25TFlv0a33npruOKSy8Nxq44NEwePF7AELAGrEvfZMCasPer4cM3V1xT8Wbzqi1/K/KwctvuQvgtYvRyAajdgubAH4QoBqwZ8Y/CV4lWueFVOwBKvqjZeRXdOvEXAKsEN198QFkybX9J5xBFdOS9urryqrFFefRGw0qFkzapjwuBdGsSnKgpYaaefeFoYvsfQughYS+YsDheff/E2M8fMELAErLIM2XVQJlzFn3elfgZvuvGmsGzukszorV4LWH0Ugg6edlC4OPlHjnbzJs8RrgDhCgGrUs7b+zjxKle8qljAEq+qKV61HPFeOKvpVAGrDGuSwFDsecSLn+zok3282eMOrNmA1S6OyGradaAAVaUBqy0WXZ1ZN6i/B6xqIWD1j4CVWcvs8i/m/VzF3zvvrHPDqcefEk5be2ryM/acLkdonXnSGWHgjvv3bMCy8Lp4BYhCAlb/tWjXmeJVrnh1UCUClnhVbfEqWrDX3LoNWOtOPavb74nrB43aa1iYlVxIHJ8EoTiNMH0Rcvj8ZQWfQ5x6GP/1vf1743op2cfMXNj2UcDqdkTZp1Fl4E77JVNgBicLDE/OTIeJMST9nMSplpnRZCJURQPW6kOPLOiiNV4UD/38kDB56MRwWDKF54pLr+j0Gn3pii+FQTs3CFgCloBV4ELxuWLUtcmvxdFUo/Yekfd7JwwcG45dcXSH93v2ueYbiVVWwBKkhCtADBKw+r+mZCfCj6c8KV6l41XZAUu8qsZ4tWXVxtC0w0ABqwgjk5iVXr8qBqnhuzcV9P1LkylN2d87dfikzL/WbxuR9eVbM/dRdQGri8gSpwyevOakThdm8ybNEaH6KGB1Wmg6+ctA3MGs07pryXtGwBKwBKyuDU7+4SFXBF6TrCsXf6/Q4zQn6wRedN6FnY4TI3PFApYgJVwBIpCAVV8eH/Nj8SodrzIB650SA5Z4VY3xKvrb/D/WTbyqVMCKhu42OFx/7XUdjrXikMMK+t7LL76s45pXyQVHnDbYKSpUS8AqMLTE0VZx6kyH5/e0s0SoKglY7eIowuzjXZ1Zd21fAUvAErC6+twk4SgdnZYvOKykY8VRj+etO6/DsW6++eYwYs+h5QUsQUq4AsQfAasObffpQu7iVcd4ddDLJQas9eJVlcarliPeD3dMuEXAKnW63qKOseiCs8/v9nviaKvs74lbrsdfb0z+wM0OYvFCvpTF3CsasEqILdObp3Y43i233BIa4x9EPRR3GgbsEyYPm5jZ5SqGnjgKLG5bf8zy1cmvLQuTmiZkvqbg8x81JfMYogmDxnb4vfg4Dhw9LRMq47pnp609JYlBazL3Hc+hVgJWvEhOr7s2dv/mgr8/Tk2cNmJy8jwcnjm3U447OZx0zAnJc350OPSgpZldDosJYl0FrDgFMr4n48ixONU2vr7xtV104CEF7+IWp321v6bRiDyL1x8wZMK2r5k6YlLH0WvJ44lTMdvfZ3HE5NrVx2fOKy4K3zhgv6IDVjqwZD/WE48+IfNY4+iehcnPrJFfGF7y6x2PG0dCxqm+MV7GdZniGnxxd8Z4f7miSbEj++Jzl3lukily8fMXxecpBp7Jww7IfE2px48jluL0vPbnfc3KY8PKRcszYSd77aieDFjx8xFHxmYfPz7Gsj6Hyfvwumuu63Y0ZDpgxZ1Es38/jtZdlOyKe+SyVZ8998nrsGD6/DBsjyElxZ34ek0efkBmt8Djjjg2c8zP3jerwpyJs5L31eCCjzcqeQ2nj566zai9h+f8ugnJ5ibbvi75HKZ/f+KQceHQ+UszPwNOOf7kcMLRazPnM2v8gcm09v2FKxCuELDqL1y1O3mvFeJVOl6VG7DEq6qLV9FxA48WsEo81pTkwiz7WPFipLvvOSU1zW7ioHHbfi9emHRYzH38zL4JWGXElkHJRUQ6jozYs6niUSdOWYwB5frrru92sfL4usSwEtft6u64cWfJ7DW82n99bnLBFkcqdbdwfTp6laftArXSASu68oorOxxzRhLmut15LVkLLsaVG7Oeo/wLxF8TFs9e1OXi1LkCVhyRmBmhslNDJu7mWi8oe6ptDDJNyY5wXR0/hprs75s/ZV7Or4uvd/vXxPdVdtiKr21Xj/eqL34pzIqbLxQRsE474dRtQTCeY3ePNUatYqaqxfs748TTC9op7/xkNFA62hUSMmNYuvbqawvasXXFwuWZ91AxoTWef1fHjWtPtf3M6tmAlR61GO+3mMeST/y5dMUll2fi4oT4Z0EBUwhjKG7/PMbzSoe19Kiu1YcfFRp33K+guBMjUAyR13ax6Hz2sWNAGrp795EsHjP7e2MYy/V1cXfU7M1NMuEz+fXxA8eEC8+5oNv3wkGT5wpXIF4hYNVXuGo3YacR4lU6XkXfKDFgiVdVGa+2Jv89bpdRAlaJxxqVjIrocJEZ/8K9ff5RU8OSf7GOI5Lav/6yZCph9u8fMGR82edWdsCaPr/s8HLzTTd3OOa4xtEVjVfxX+9zrUXTnUsvvCQM36PrmJZ9MX7x+Rdlfm1ZcrFVSARoXwsthoNKhKueDFjxsXVYq+yAOd2OQImRptjnPF50xhFAhQasGNZiGDnnjHMKvo/4OeoqYhUasM4+fV2HYBR/7cAx0zMX6oWcR3yPzJ04u+CAFUeuxVB3bhGPNT6fhYz2iiPUugob+cRAWejoofh5Kvb4X7zsi5kRVd2OmttnZEFhrF0MQHF3wJ4IWDGipDfuiDGuIscuYKRiOmDF93Ocwl7M8x/DUHeRKY7WuvDcC0vazXRsQ3NFAlYcVZX9dUOSz3UcCZZr45R8n8E4YlG4AuEKAatuwlW258f/WrzKjlfzSwxYZ60Xr6owXkVPL3ysruJVpQNWvMhKT5fr6uvTf4mPYST9NdkXJfEv4zGS1VLAiiOj0hcVbVOUKhOvhicXWekdD2MwOyGZzjXvgNmZqXxTkgueeZNmJyNW1nYIhu1b3MdzzHf87FFWl19yWWbaWHsIiNEsPr8Lph2UiSBx9ERc4ysdty4894KKhKueDFjpGJWZrpPna2MwvC613lschRXX4pkzYVZmitiUZGpsfE5ilEmHk/ie7mokVnbAiqNR4uPb9r0XXfrpcz4/c/w4JS3XaKiu1pMqNGDF4JH9dXHaXvu03ji6o31aVhzlsSTZiCE+1vT7Kz5P+UZJpQNWnI4VR9O0f9bje2nZvKWZ48f7ieedHikXxfddt/Eq9Z6Mz2scsRinO7ZPlYyjp3ItJt5dxIojf+LnKP2zL04jjece3wvxPRFjXhwhlA7a8fPbVdSM75V0oI7Hj8eKo1InNU0MM+L5J89VdoiNz0tPBKz0PyzE93e+aag9IR2wYjyLo/fazyXGqRiE5k2ek4k3cXpdrl1h5yY/H7uaMpiOxvHYcdrgsoPa3pMx5sb3ZXzfZu+i2x6eB8Wfq2UGrPge6jC1OQljV336Mzl+FuOU7UNmHJx5rHGEZ/z69LnE/982KsyFPQhXCFh1Eq7abVsHS7zKxKuWigQs8apa4lX01Qk3C1hlBKzpozqu95SZ/pTnaxtS07biBVn8V/TudiiMIwt6LGBtX/mANTO5yElPHcqs5VWhgHXmSad3Gn3TvM/wvF8fL4DSU//i+lX5vj77wjxGi/j/Yww4fMGhedfSikErfbFY3FTCri9gKx2wRu09Ik9kzD1CJHtqXRSjR1frJsU1sNJr+2TexwUErBiA4mcjXjwvnrUw5wiV+GvxIj79GPJFuEIDVnsUaNe+yHZceytflIqBMx1oFkw/uKCAFZ/H+N6KI41i8MkXc7KnVbWH1K5GLqUv6FcnUzHzjdqKz2U6/MTnPr6G+e4jTmVMx4uu1lCLI67SQSrGv66m1aV/huSbXhfP//AkamaiamqUTqUCVvp8YkDtzcXp0wGrPTrGn01x2mSuEDRk14Hh/GRNxuzviyMM8wWmuKZVh0B9ww1hUvLezvf18TVNR/DD5i8rO2DFOJbrMxhDWtNug3J+T5xemJ5KfmjmXFzgg3CFgFUn4ardUXssEq+y4lX5AUu8qqZ41XLk+2HFvssErDIC1tHJ2iIdpmmccFrer42Lf2d/bVyMOOfuhsmUiewpSzGiFLOYe0EBKyueVDJgxfM8P7WzVlzovFLxKo6s6niRdWOygHH3o7smJgsDZ49IaRtBkXsqYfYOkZ+NeDi82/s45/SzO4+uKzNc9VTASq/nE0ea5fvaWandMWOY6m5KYDQ1WeQ9PUpuSJ5pfrnWfooXvN3dR7yozf6euF5SOQErRpX0ecSo1d00rxiIsr8nBp5CAlYmZCePvW3Kaf7jx8Xq089R21TYzl8bF9vu9HOmhB32MlPOck0lbRjdaWRUIRsAxIX0s0erxc9jnPKXK0jF9dOy7yOzrlE3xz8uxw6BlQpY6ffFcV3tAtgTAWvcjJzr+o1IFm/vatpeek2w+Bls2HHfnF+bHn24asnKbqccxtFw2d9zcQx7ZQasNal1IKNzkj+j8p13u/gzutNr70IfhCsErHoJV+2GbL9/+GDqE+JVRQKWeFVt8er9levDkB0aBawSA9bIZARK+l/8O+zgl3JGahRFHL1V6ELvcybMrEzAyhFRKhWw4uikNanQEsXoVKmAFacEdh7VU9j3pkfXHJbsUJjr6y67+NLUmj1XFLSLYQxWHZ73ZEpjueGqJwJWHOGXnl62MJlylu/rz0iNeMuMsijwvtJrO+W7n3Sc+dIVXyponac4Kid9gZ5rpFShAevk1OcuhuRCdjpMx7q2tdMKC1hHLFlV0HN5XioMz8gx2ixO7cseDRZDbWa3twLXtPryl7/ccYRojlB59OGru9wRryvp0TVH5XgfxxFt6fdCITsYZiJfajpnpQJW9tpobXF6Se/Eq0/jTK6AFXcdLGRR9qtSo09Hx2iY4+viz5gYiuKI1muvuTYckOze2u1OhUlUyh7tF3+uDNx5/7ICVvpnXXwPj953ZLfnMn7gcENh6QAAIABJREFU2E6jAl3wg3CFgFU34SrbA83fEq+2eaW8gCVeVU28iu6f9ZO6i1eVClhxms5lF13a6S/MA+NFd57Ylb0uUOairIvF3qePnNJx6sdp68oPWNv3TMBqSqaqHJSsR3Lx+Z3XJYpTryoVr+LorvQ0kczCwQV+fzzH7O/N3mGwq4AV1w0q5PgxKHQewVJeuKpUwBq0c0Nm7aP0hXh0QTLNKF8giNPX0qNmRuw5rOD7jVMAO4yQOun0ggLWUUU8vvT00GlJTKpUwCp09FIMPZ0ungsMWJk17koYNTdvUudF9+OvddxZ8Pyi3ifnnXVutyOf0mtyxfWuCj3+ganpxXFttPTXpKeGxsddamiqVMBKrxOWb4popcNVvoAVo1G+UJS27rSOz0lX0wJLcckFHReSHxmDaQUDVoxqXZ9D2wVuQ7LLYnaYj9NOXfiDcIWAVXfxKlq3zzHi1afxqqyAJV5VVbyKThtyooD16V+Qm5KRC12Ja1WNTf7lem6yTkhmYfDUBXccudDViKp0VFoZd7Dq4hwz62VdfmWHcNC89/DSAtZRx3UZXtIBK65rEmNUd2LoiVN98u3OF6PboHiRVaGANXqfjus2XZNMrSzm+0fs2VTQ2lzpgFXoCLIDhozrHB3LDFf5AlZ87IW8RjEQxMCTbze6OHWwq8Wo49TLQtdeymVcw5jUe+uqggJWVwvKdzeNMEazSgWszEV2gbvUZX8O4vSuQgJWvtCVy9GpaYqZndbSUxmzFr8vZkfBdnE0WHrtrOzfjzs9Zj/O+LoVMjoqO6Rmf3/8uZle3D89XS8u2F3o8WNs7omAlV6wPm5c0BvhKl/AiqGx0MB0ajKFu8Nna/TUigasdPTMtyZXqQEr/nnWVbjKlj0iOrOLqAAAwhUCVj2Fq3YjBgwOH077h3jVHrDuKiFgrVsvXlVZvNq8amMYsVOTgFUB8SIsLuKdN0Ylf9nOXtMl/sU6jsjq7jzTF2OFLuZebsCqxPMRz3XgjvtVLF5Fc1OLDMe1toodwZVe3DpGre4CViFrbGUWi99/VMcRXnHkQIUubI/NMTWzHDEixN27mvKsSdVuYeqzcuZJxQWBQTt1DBbxv3NN8UsHrK4WiO9u/al0dCknYMX1vwo9j+x16+JuaYUErLb3cGHHjzGqwxSyHNMx0yOQ8j3OfOIU6K52dpyWGhkap5sV+16++ksdd8dLr/+VHtET77PQY8ddD3siYMUdHMt5XksNV/kCVlznrNDAdGJqV784Cq6UUBXXrxuR/CyM0/naTUx2Z8zeBbInAlZmRHA34apdXC8y+2eNEADCFQJWXYWrbL8edZd4FR1cqYAlXvVlvGo58oNw34E/rst4VemAFUekTEq2pO/q/uL6VR2nLJ5Z0HnGRcazR87ECNYY/4CvwoAVz/PCcy7I3HeuKFQJ6ZhyynEnFX2M9EiK8Y2juw1YcTev0gLWOVUVsOIF3aXJtNdjlh+dWYi7kPs9LHXRWcx6R+1izOluylx2wIoBtLtF07Mtm7c0NW31+IoFrFzTESsZsNKBqNyAlZ7GO3XEpKJeq/Q02PiZ7ioQrcuMMixvOt7U1HMcp1d3CiIFHjtOZ+yJgJWONEvmLO6VcJUvYB135JqCv/eE1LqBhQSs+PMh/iyPr29mlG2eEZy5VDpgxd0RuwtX7Tr8Q5GABeIVAlY9hqt2p+9zlHh1cKUClnjV1/EqOmnQ8QJWia656urMznpxB6au1rFqd3ZqDZI4yqG7KYvtzknFpTgKKe99fRpSyg1Y8bHFi42uxPtIL/g8YeCYHglX7eLi4cU8rlzilLrupgemA9bgXRqqLmDFkTvdvUZROh7FAFHM/caRdOUuHh+npHY14iYdsDJr1xRx/PQ6W7nWrSo1YBWzvlM1BKx0oI1TQIt5LtMLqKd3p4zT+dI7NBb7fohrz2UfI/4czf79OP0y+/ebk6nDhR47vah/pQJWfJ06bx7R8+EqX8A6vocCVhxVlWudvGJUOmBl3h8FXgALWCBc0V/sl/F/hKvSNSU7tW2a+ljdx6vyA5Z4VQ3xatOKN8PQAYMErKxRBgckF3rdiQu3x6hU1GLve4/Iu0ZUKc45/ey84apSAavQRdzT6+3E0R+F7NZXqvQ26WtWHVP0MdIjKdrWWqpUwGrutYBVaEiKi02n187KtbNcodPzCt0xr6uockAcsdhFwGpb26zw46ejStvi+fUZsNI7zo0vYvRSrjXP0mt0LZ69KDUK8uSyd/RLL0af3tl15F6FbxowIbUTXaUCVhy12HHdxHN6LV71VsCamKzhF+NxrtG1MfzH0Vjx9Y47SUbHLF+d+fmQDtQCFiBcUW646n8Ba7u+8d1h19d9vGoLWJtKDFjiVTXEq+hbk++o23hVqV0IC5VeeLkS08BiFOtqV8HeClhxgfb0dJ9Cd+wrxbLkgqfD48pMFSvuGHFESYcdueJW8WUHrLYL02oMWHEqXnrES4w0hUeTFd2uL1Xsmkdjks0QugpYcafJYo6/JBVVMusD1WnAuvziy7qNhcVMwbvkgou7XCMrVyzsTtwZMfsYcXfMrkZgxX84KHgE2bADeiRgpR93ZhfA1OLzPRGueitgDUp+xqXjZ/zcxj8LBn+uscvjx5gnYAHCFZUMV/0nYG3Xt+bvOq3u41XLwa9+ZkHaa23sNljV8arlqA/CwXvNEbB6IWANTH7wpqdwVcLqw47sMqj0VsCKZiYXQ9nfG6cSjm1o7pGA1Wn60tpTij7G1amLtDjtr/SA1fECtRoDVhSDUXZcKWZx8kMPWpp6Lx1f9LnfmBrVMXyPpi4DVnwPFXP89IXx8UesqduAdeG5HdeXyuyMWsRzGWNSp93usn5/dmo9v1Le4+lpvDE6dRixd8WVHX4/jqoq+PzHzuiRgDU82akzPZK24IXcC4hMTbsNatvNsY8C1rLU5zzGrJFx19sCjn/+2edXKGC1XdwKWCBcIVzVfsDarno8OeEX4pV4VdPx6vEFf6nreNWbASte4KSnKo5O1nMp1vTUzl/XXn1tlzv89WbAiuKaQx0e57kX9MhUwvQC03E6YDHfH5+z7MWI4wVOrgXauw9YuS9UqzVg5RpJFS/0utuBMNei3cU+pjhdMfv7Y+TJXKh3swthrsiV97lZ0XF618pFy+s2YJ229tQOX7Mwx9d0uZ5YN1MEu5tiWFDQTE8RTC3qn57mGyN5ocdeOmdxjwSsXIvPx/9fiRFX8fMQw2PcfTGzrmKOkNXTASuGyg7vm5mHFHz89Mit0gLWvgIWCFeIV/0gYG1Xfc7fb614JV7VbLyKzh12hoDVSwHrgtS/TMdpKKUeK8avjuvGzK6agBV3S0yvnRIXXK90wGpKYlP2KIg4jacxE0MK+/64yHx6B8lcX5c/YHV9gVvNAStOd7rikstTu/Wt7fb7RiWjMNLxtJgdAuMufoVc9KcD1rQk2pa6wPa8A+bUbcBKR4I1Re4aGXeZzP7+OAIv/T6KI+Sy10caUkAIbRfXs8o+fpwu2N1rsLSIHf/ie7qnAlZ6Pbm2QLig7KmC6WiYeU/0csC69uprUlFxWEHHjqO00iPTigtYnS92BSwQrhCuai9gbVet9g5Dtm8Ib075i3glXtVkvFp/+CvJhgQDBaxeCFjpC9U46mDQTvsXf6xPo8rCAw9OLSJ8dtUErCi9E1wMEnFHq0pHrHSEmT5qSuG7GB68LMdaSYUErMaCLnCrOWC1x6Tsi8343wcWMLolfXE7cfD4kncxjI+jkIBV6C5vMabFNbM6TgttrtuAlQ6GX7zsi2UtuJ+e3helw3wxO1suTP3szfX44zp63e0qme+9kB0wKh2wYrxLPz/x5/q291sJa1tNSnZ9TE/vzUSxXg5Y2ecQfy407LhvQcdOf66KC1hLBCwQrhCu+kHAqtJwle3mQReJV+JVzcWr6LoxX6r7eNVbASs9kuG4uC5PCeGqXRwFlD31JrOYe55A1BcBq2GHzhe25687L/PrFd2J8JDDclzcFnB+AzovcH3gmGl1FbByjVCJO4gNiTtrdrUTYWq3yULXwYoX/Ok1xyY1TSwoYMXNARrjX166uY+4xlOHKW2X5w429RKwYsRJb6xQ6DpY01JTleP0wFyj7dKxOrMzaoGPIT2S9KDJczt9TVx4Ph2JChnlNWfirE4xpZIBK4prx6XvI+6aOSGZWllKvEqPXL3gnPNzxqOeDljptRoLWf9qfDKi9eabbu70fEwcMl7AAuEKygpXtRGwtquNeBWNHjAsfDD9SfFKvKqpePXBqo1h9M4jBKxeCFiDd27otM7LxEHjSgpX2WKIyj7m0Zkd4aojYEXjGkZ3mF702fSfygWsEXsO7RA74kXK9Oap3X5fejHyGDryxbX+HLCG7ja40y5vxx95XJffM3rfUR3WDouvcb4Q1VVwufj8i/N+bfp989mOll2MuEn+UhQjaYeRW0moqueAlWsaYVw0vbv38KDkZ1Zcg6nDNODkOLm+NgbPdHjJNW2zuyl4Mfzk2skvRrMYVrO/9qhu3u9xrbX04u/FPr+FOmb56k73E3/ex4XQG+PahN2En4HJSNw4xTr9no+fyxF7De2TRdzT//gwf+q8Lo/ZnKzNGEf3tf8s7e748eL28IMPE7BAvEK46gcBq4bCVbbvDL9evBKvaiZetRy1OXxz8h3iVS8FrPQ0mcxW9GWEq3aTmiZ0uuDJtZh7XwWsKB0K4jpVzfsMr2jEOjw1FTBeTM9NRl/kG3m1fMFhnabO5Z96uE8SsC7rtwErSm8u0PZ8TC1qKmB878Ud6/KNvIpf3+E5TwJYHFmTb+pX9tfGY8dpgfHXYozJteh7jAAnHn1Cp4gwbPchdR+w4vN/+SUd38PnnnlOZv2pXF8fY0Q6BMbPQK64lG8qYByJk1njL8/rG9c7SgebrqYeLkmtCxXfCysWLs85Km9yMpKp/fGmd2Gs5Gdw2+NJRkidcvzJOXeIjREtvtcmDz8gsxFB+4Lsg5IRtPHXVi1Z2SnOtb/nuxrF1dMBKz63Hde6u6ZtN9kc8W1Bshts+7TdU5OdYA9LBdPMNOEci7MLWCBcIVzVdsCq0XDVbvLOY8OWA/8pXolXNRGvNh/xdpj0uXHiVS8FrBisso+/OO7oVEa4ynbpRZempuDMqaqANXCn/Tr9i3y8eK7kVMIYpc486fROF4HxojuOjoijG+JOdHG63DWp9Zs+26Vu77w7C/b3gBXFaV/pC++uHmeMGeckjyf9XMZRO3EkYHzO4/vupGNO6DTCK15ILosXq10cOz1iKDuyxYvSE1Yfn7nIjhfLccRYrte1q8W+6ylgRRMGju00LSye35knnZE5Tny9YmSM74NcI4HieXa33lR8rdOvQdwYIb5X4/Hj6xWnm6Z3qctEjmTnyO5G16V3I8ycW/KYTj/xtMx7IO6QGO8vO2DGx91hSl4ysqiiAStr58A4Kix7ZGIu8ffT02PT4vs9VyzqzYA1bI8hnUbVxffFmaecEVYnn++jDz8qE6uyP9vxuY+7uM4cO6PT5z2+PjFQzZ4wU8AC4QrhqsYDVo2Hq2zfGnateCVeVX28ir426SvCVS8FrEmp9VviCKQhMQyUGa7apbeJj3GomgJWNGP01E4XaXHdnEqOwooRKz6u9A5YXYkXkotiTMwTruopYMVpgekL63wLrGeHphgNCn2+26NCvliUPSWt49ppbdEhXjgXch/xPZBv6mC9BqzM+zGZ0puOyd2J7/3R+4wseNH0+BoV9RlMoki+qYlpcTRdetOGfOIIsANHT28bzZcVlWIEq2S4SoujquLOmsU8x599Nm7IjMiKo5q6i1A9HbCiWeMPzDmVN190G7FX206FcdpkvvdZZqdTAQuEK4SrmgxY/ShctZuwU3PYPOMp8Uq8qup49d6qDWH8Ls3CVS8FrBNTFwtxlEIlwlW7puRfvNM7Ro3Zb1RVBazolOM6hoAbk3/dHxW3Zq/wroRxWmVcqDmGwnwXW3E6zJpVx2TWz+oqXNVTwMq121t8LxUSbOJOd+tOW9dp97QOi8Mno25i3Mg3pS+9flH2956RjK7btjD3hFmZi+V89xMDRSE7KdZjwIrilLsYvdMjN9Ove3we4+c+13TN7sTHdNraUzut+5ce1bU2GUU3Ki4OXszOf0ncOWLJqk6j+rLDVYyq2TtPXnv1tZ+FluRx90S4Sovr8MXHl+88s5/rGLwOnb80ed8PLvj4vRGw2heWPy81nTT9uT58waGdotvYhjHh4tTI47aRdscIWCBcIVzVWMDqh+Eq251DrxSvxKuqjVdbE1+ZcLNoVQ22pyfFtcCmJKMh4lpYi2cdEg5J1mmZnYwoiAvLdzfiitLEi9ipIyaFeZPmZEbYxQASd2nLjgmVMmrvEZkL77gQ+MIk3MSL2mJjSL0bseewzLplca2q+HrFiBfDS1zYvxLHj7Fs8rADMtExHj+ukxWnkE1INrDItZthUetOJd8fNw5of6/Fc4/vve520OzpcJVLfF/G92pcCH3x7IVhUfLzaF4y1TuO1hr8ucayjt1b4uiq+NrFc4+PIe4WOS4Jle1reqUXaG8Xvy+udTeucWxoiu8rF/4gXCFe1UzA6ufhql3zgKFh4/THxCvxqirj1ZuHvxpG7tgkHglXCBhAD4ar+uPiHoQrhKv+ELDqJFxlu7jhFPFKvKq6eBWdN+IsAUm8Eq4AhCvhChCuqIlw1XsBq87CVbvG7fcNz0z6jXglXlVVvHpq0WOZ96aQJFwJVwDClXAFCFfUQrjq+YC1Xf3Gq3ZH7LlYvBKvqiZefbL6g7B832VCknAlXgEIV8IVIF5RM+Gq5wKWcNXBT5vvEK/Eqz6PV1tXbw4/nP5dMUm4Eq4AhCvhChCuqKlwVfmAJVzlNHrH4eGtuKC7eCVe9WG8emvFa2HsLiNFJeFKuAIQr4QrQLiipsJV5QKWcNWts/Y7VrwSr/osXkWnDjlBWBKuhCsA4Uq4AoQrai5clR+whKui/G7c98Ur8apP4tVv5t4nLglXwhWAKCVcAQINNRmuSg9YwlVJxu80Mqyf8Zh4JV71arxav/y1MOFzo0Um4Uq4AoQrxCsQrqBm41VxAUu4Ktvxe68Qr8SrXotXcdfBNQNXC03ClXAFCFcIVyBcQc2Gq8IDlnBVUXePvFm8Eq96PF5F35xyp9gkXglXgHCFcAXCFdR0uCosYAlXFTdsh0HhuSkPilfiVY/Gq6cXPx6aBgwUnIQr4QoQrhCuQLiCmg5XXQcso6561IGfmxTenfW0eCVe9Ui8envl+jDj81NEJ+FKvAKEK4QrEK4QrvqN/yNc9d16WC3to7DEK/GqQvHqk8TaQccIT8KVcAUIVwhXIF4hXPXDgCVc9Ynbhl4hXolXFYtXW1d/GG4af534JFwJV4B4hXAFwhXCVT8MWMJVn2ncft/w6/HfFa/Eq4rEq/tm/SzznhKihCvhChCuhCtAuEK4ErCEq4pq2qExPDb5f8Ur8aqsePXEwr+FYTsOFqKEK+EKEK6EK0C4QrgSsISrnjF2pxHh3zP+JF6JVyXFq38vez6M36VZjBKuhCtAuBKvAOEK8UrAEq561pzdpoa3Zz8pXolXRcWrt1a8HmbvPt1nSLgSrgDhSrgChCuEKwFLuOodB39+Ztg052nxSrwqKF5tWrk+HPKFg3x2xCvhChCuhCtAuEK4ErCEq961bI/54f05z4pX4lWX8er9I94Oh++31GdGuBKuAOFKuAKEK4QrAUu86htHfWFp2HLQC+KVeJUzXn1w5Dth1f7LfVaEK/EKEK6EK0C4QrgSsISrvrV8z4XhvbnPilfiVaeRV0c2rPAZEa6EK0C4Eq4A8QrhSsASrqrDYXseHN6d84x4JV5l4tU7q9aHZfss8tkQroQrQLwSrgDhCuFKwBKuqsvC3WeHDcnuhOJVfcerjSvfDIv3XuAzIVwJV4BwJVwBwhXClYAlXFWnObtNCy/PfES8qtN49dKy58Ls3af7LAhXwhUgXAlXgHCFcCVgCVfVbcxOI8Jfp/yveFVn8ervCx8J43dp9hkQroQrQLgSrwDhCvFKwBKuakPTDo3hF+O/LV7VSbz65eyfh6EDBnnvC1fCFSBcCVeAcIVwJWAJV7Wlcft9w60jrgxbF7wiXvXTePVJ4uYJ12dea+958Uq4AoQr4QoQrhCuKCpguYiuJsfsc3h456Bnxat+Fq82rVwf1g46xntcuBKuAOFKuAKEK4QrigtYLqKr1cxdJ4dnZzwkXvWTePX04sfDjM9P8d4WrsQrQLgSrgDhCuGK4gKWC+laWBfrruabwtZDXhWvajhe3TvjnjBsx8He06KRcAUIV8IVIF4hXFF4wBKGas1R+xwa3pj7D/GqxuLV+uWvhTUDV3sPi0bCFSBeCVeAcIVwReEBSwiqZRN2bg4PTvqReFUj8eo3c+8L43dpFq4QrgDhSrgChCuEKwoLWOJPf3LS/keH9fOeFq+qNF69ufzVcNbQU4UrhCtAuBKuAOEK4YrCA5bg0x817zg03D3mK2FrjFjiVdXEq1/M+p8wZueRwhXCFSBcCVeAcIV4hYBFu5VfWBKenvWQeNXH8eqpRY+F5fsuE64QrgDhSrwChCuEKwQscmncft9wVuMJYf1B/xSvejlebVj+eri8+cLMayBeIVwBwpVwBQhXCFcIWHRjVDKt8I7m68IHh/xHvOrhePXeqg3hKxNuDiN3bBKuEK4A4Uq4AoQrhCsELIo1dqcR4fbma8LmhS+LVxWOV1uO3BS+N+WbYcIuY4QrhCtAuBKuAOEK4QoBi3JN2mVs+PbYW8MHMWSJV2XFq/eTEVffnHxHOOBzY4UrxCtAuBKuAPEK4QoBi0obOaApXD70nPD6/KfEqyLj1frDXwk3jbsmjN55hHCFcAUIV8IVIFwhXCFg0dOadmgM5w0+NTwx8/fiVTfx6vEFfwnnDjsjDEmeM+EK4QoQr4QrQLhCuELAog/M+fz0cPvoa8PGQ54Trz4NV5tWvBnunnJXWLDX3Pp+f4hGwhUgXAlXgHCFcIWARTUZOmBgOLVxTfjVlB+GzUteq7t4tXnlxvDLmT8JJw8+PjQlz4VwhXAFCFfCFSBcIVwhYFHFRuzYFM4YtDbcP/WH4b3FL/fbePXeivXhV0m0Om3IicljHuK1F42EK0C4Eq8A4QrxCgGLWjRw+/3CYV9YGG4fc114Ys4fw9ZD36rpePXvxc+EuyZ9Naza7/D6Xtfq/2/vvv+sOu8Dj+//YYqoAokywxSKAAkhQAgkmhCqCBVASEIVSUhCvTerWUaSY8ctke1YdmI7dty7nV7sOHGysTf2ehMn62yaN8lmkz17vmc4l3vPfc6dOzOUAb1/eL+CmXNuHfTK+bye53vEK+EKEK6EK0C4QrhCwOJkteKUM7K983dl71z2bPbt8z+X/cv2n47bePXv1/5D9t1tv5t9cNV7stv7bspWTFnqOxSuhCtAuBKuAOEK4QoBi7fiHQ0vmbU5u2/gzux9Kw5m377gc9nfXPoXxzxe/XT7D7Nvb/pi9r5zXssODN6ZXTx7S/7aFviOhCvhChCuhCtAuEK4QsCC+rC1aea67Pp512aPLbovez3fgvjR1R/IvrDuE9lvb/xK9udb/yD70cV/kv3dFX+Z/f32n2T/fOVPG+Eq/vz3V/4k+7vtP8p+dOn3sz/b9gfZb2/+avaF9Z8sHuP1FS9njy6+P7s+Xwm2MX8OoUq4Eq8A4Uq4AsQrhCsELEC4QrgChCvhChCuEK4QsADhSrgCxCuEKxCuQLgSsFzMg3CFcAUIV8IVIFwhXCFgAcIVLsoB4Uq4AoQrhCsELEC4Eq4A4Uq8AoQrxCsELEC4QrgChCvhChCuEK4QsADxSrgChCuEKxCuEK5AwALhCuEKEK6EK0C4QrhCwAKEK/EKQIwSrgDxCuEKAQuEK4QrQLgSrgDhCuEKAQsQrhCuAPFKuAKEK4QrBCxAuBKuAOFKuAKEK4QrELBAuEK4AoQr4QoQrhCuELAA4Uq4AoQrxCsQrkC8QsAC4QrhChCuhCtAuEK4QsACxCvhCkC4Eq4A4QrhCgELEK6EK0C4Eq4A4QrhCgQsEK4QrwDhSrgChCuEKwQsQLgSrgDhSrgCxCuEKxCwQLhCuALEK+EKEK4QrhCwAOFKuAKEK4QrEK5AuELAAuEK4QoQroQrQLhCuAIBC4QrXJQDwpV4BQhXiFcIWIBwJVwBwpVwBQhXCFcgYIF4hXAFCFfCFSBcIVwhYAHClXAFCFcIVyBcIVyBgAXCFeIVIFwJV4BwhXAFAhYIV8IVgBglXAHiFcIVAhYIVwhXgHglXAHCFcIVCFggXCFcAcKVcAUIVwhXIGCBcCVcAcKVcAUIVwhXIGCBcIVwBQhX4hUgXCFegYAFwpVwBQhXCFcgXIFwhYAF4hXCFSBcCVeAcIVwBQIWCFfCFYBwJVwBwhXCFQhYIFyJV4BwJVwBwhXCFQhYIFwhXAHClXAFiFcIVyBggXAlXAHilXAFCFcIVyBggXCFcAUIV8IVIFwhXIGABcKVcAUIVwhXIFyBcAUCFsIVwhVwwoSrW6dfkWULv91m8ylrhCtAuEK8AgELhCuEq9LyiYuyAzN2ZR8+/fHsd3rem/1l369mP+3/dPaPA18s/u+P8v/9mz2/mH1kzpPZ3TOuyc6atEiQ4JhbMGFe9p7THmjz0Mw9I36sh2Zen3ys3rjAOsYrrgQs8QqEK4QrQMBCvEK46uC8yWdln5n7YvYfg99MXkDX+b8Lv5F9bM4z2cqJZwgrHDMDE3qSv48RV0f6WL+dn5N6rL63zT/mWwUFLBf3IFwhXAECFsIVwlWNm6dfnv3b4NdGFK6q/rb/M9lFp6wVVxCwxjDj6q0bsFzcg3CFcAUIWAhXCFcd7Ji6KfvPwW+NKV6V/rr/14stiAILb+mANYaQ0zdhfrZs0mDAs4U8AAAgAElEQVSb3vh/9IUrQLhCuAIBC4Qr3orxqudtc7MfLvhY8uL9r/o+lR2cfXexOmv71A3Z1nx11Q3TLs4eP3Vv9gc9H6iNWL+Yzw4SWHhLBix3DBSuAPEK4QoELIQrhKsj74opF9RGgIUTFnQ897lZtyXP/fnAl7L+t/WILLx1ApYgJVwBwhXCFQhYCFcIV0fPM6fekrxwv3jKeV2d//X5ryfP3zl1a/HzJRMHsnWTVrRYOXFpx8eMn1fPCZ2i2OCE3rbj10xa3vF5zp18Znbb9O3Z22fdnr06+95itdnT+edx3bRtxevu5v0vmtCXfK2xsq35uEtPWZ89lq9cez1/nlih9uSpN2WbJ685Zt/zqklLsztnXJU9derNxXt9x+z9+eu5MV9Rd0l2xoSBrh8n9X7jc6wed/7klcUdKl+efVfxfPFcm05ZfVIErHi/LZ/B5BXZool9LZEm/vcN0y/Jnpx1U/bu0+4vfsdumH5xNjixd9jAE+fGY1b15++3m0C0Nn99t8+4snjO10+7t7ib4suz78wOzNyZbZ2yNuuZUL8Vcc3k5W3Pu3Digtrj4zWlXus5k5d2DFcrJi/Jjzu7xZKJg7UXxP35v+/Lp16QPXzqDdkLs+8o3tOL+Xu6f+Z12ZZ8Nlhvvu2ymwvreF3V5z1z0uKWYxZP6s/2zdiRf377sved/lD2zvy/C3fOuDpbMmlAmADhCuEKBCwQroSr4yUuBFMX7mdOXNzV+VdP2ZR9Yu5z2St5EIlgESu6zp60pPHzPVO3tT32j/s+0fEx/yYfBp96Tfum76g9Z//0q9uO/8q8V5NbJu+ZcW32p70f7jjL6/8Mfj37tTnPZasnLev4WvdOu7Tj53dLvv3yL/o+Wvs8v9vzvmx9fhF9NL7biC8PzNzd8flDzD+L1xHbQ7sZ9p9acdd8J8tv9vxC7XP9Ts97sw153DqRA9ZP+j7Zdtz9+ecckaZ3wrzs+Tx8/HzwS8nH+/uBzxcx70gPcY/nje/6zxZ8pKs5dS/M3pcMU1+f/66245+adXPt80boST1H/BvutOLqu71vtJ2za/pFbcetzMPrh+c8kf3jwBc7vqcf9/1a9kget3ryz6HTBfZvzn9P27mfnvdi8bMIaG/MeTz/ff5y8jniJhcRZBdMnC9UgHCFcAUCFsIVwtWxFiuCUhdru6ZeeEQeP1bs/PvCr7c9/lmT0oPeY5VO3UXqR+Y8Wfs8Hzr9sbbjYzVV8zFLJvYnL9A7ieBw5dSNtc+7a9rW5HlbJq8unr+b5/inPHZceMqRXY0VK4P+a9+bIx7CH9Gv0+qzq6duTp4Xq+NiRVl8Xt18pkdi9dnxClipSBSrnSIiRQzp5nOOVVlHKmAtzb+vCIMj/a5/kP9+rD9lRctjxftIB570a/2VOU/VPv7GKauSF7uDeTir/jch4tBgEdQOHxf/toYLV+2/v69lA8Uqt/SF9lfnv5b8fYl49f0u4l/43Lx3dL3iC4QrhCtAwEK4Qrg6Qh7Mt+CkLtJisPtwW/C69Xs97297/BvzlUupY2OLW92F41/2/Wrtc/xJYkVVRKTmlVdfS1y8duMfBr5Q+1nEHRxT5zw0c08y3HVaFROx70h83kMh6XOjvpNkBJq611I3M23lxDNGFMwiFvS+bd6JFbAORZvv9P5S23GxVS9WVnX7/v/fwm9lO/NAM9aAFdsBv93z7lF/17FyKQJY+Xjbpp6XPKYuYMVqyrrHjps9pC56U/9mfiu+s6ZjYqtjRK3RvKePzX2m9oI74lP1+D/Kv8+I4yN5jthWKGAgXIF4BQIW4hXC1TEU83L+c+E3kxdp/zL4leyXTn80uyq/4FwwYfSx4eDse9oeO+YipY6NFUDV7W3N/zsVkiK2/Mdg63v4Wf9nW+ZQ7Zt+ZfI9frf3l4ttkLEibOMpq/IL0/1FXKge9/E5zyZf7yX5bKv0IPsvN8JUrMS6ZuqWYvtdPE7q8UN8TmP9PmOV2Q8XfDz5+LGVMGaexdyreC3vmn2gdsXUp+Y+P6L3+8HTH2n8+XsL3ijeZ8SCf67ZShe62bI4LgJWJdqk7sD5iblvL0JnGTw/k69a+vjcZ/MY+Cu17z+2Wo41YMVcrepx8W8hZjddM21LvgrqnOz8U1ZmV07bmL2aR7bU1sbYRty8FbH6OxG/r0NzolqfO7aLdvq3+oV5ryQvfmOLZfU1xIyu5mNSn3G8jngP6/P3c9bkxfn7uzC5FTGO2xoz/BLP/cn8e6oe/78HvtL4N/nF+e8s5oddnX92MW/rBzVR9l8Hv5qtzueFiRkIVyBcgYCFcIVwdQz9xtyXhl1xEBd5MT8mBp3HgPbh7lBYnZOVvHhPzGyKeUrNF6JxEdx83oEZu9rOizjUtu1p7ostx8SMp9RMm3MmtQ+U/9y8l5PvPzVEPlZ51X1msYpt+cSFbefEe0gdH9Gtd8LcMX2Xr9VsCY0gldoOFwPzY2Vb6pwYPF89/qJT1qbnaOURNOaG3TrtipbjV+Th43u9H0qe8+acp8d/wJrQHrBSv0tlBP58Hu0WT2od6F53t84IPkvygeFjCVipLXwHi9VB6RVTu/LoUz3+7/o/V4Sr8pjPJ1YpxUD66mM9dOr1Lcd8af7BlogVIS+11S6Oqz5+DGgvf37RlPPqo2rlsdZEgB9sD8LvzQNe6gL8zTnP1P57rUa0crvjH/Z8MHl83AhB1EC4QrgCBCyEK4SrYyhWH/2oJmLU+b8Lv1FsvYmVVM1b9VIi/MRqrubzY7ZN9U59MWuqGoCqWxxjpUv18V+edWfb64vzyp9HFPrd3vcXq2H+e/8niu11sYLi9/OtjanXe3vNaq1LEkGn08yu7VM31H4mqWHSIWLcaL/Hxfnd68pVQM3+R9+nirs01p1Xty0wwmb12K01ASsUw8kTjx+/H6lVZzFI/0QMWHXzpuL3a2Bi+k6Bdd93rG4cS8BKzXTbn98xr9OQ+A+c/nAeeB7Mnp51S7HaaPu0Dflg8sMBK+6W2RbFTrun7XE+O7c19D6af/9/vqD1hgGXTFnfdjH8s4HPthwTq/SaB6Pfmt8Z9HsLPpT9t/y/SbGCMf5bEZEqBsanLq7j33b19cYKrtSxdTO7YiVX3QD4uMth6vc3ttqKGwhXCFeAgIVwhXh1jMWdA0c7I6qcaVRdfdMsdWe66t3oYuVIdYVODDdvu7tZ5bFTg5lja+RoP4tLa7bJpeZ21QWsPxkmzsQdG1PnvZBvrxrt607dIbDbx0zdlTHCQnVFWF3AijvzdZpplXr8/znwGydVwIo7TtZFo/tmplfd3TFzx5gCVmq1YGyLPWvyoo4Rq5PYdlh9zG/koaz1rofz27YaRuiJ+VPV4fbNF8Tr8jtuVh/7y/mKrLFcZMfKrOSdTkcQsA7M3NnxOf54wRvJVXeLJvaLHIhXCFeAgIVwhXB1PMRqnC/POziiAeTNYlVGanthau7NgRk7W475/cqw97joj4AS2/fqwles4qoOLC8uXsfwGZyfP37qvd0546quA1Zxl7kOz3FuHthS5/363BdG/brff9rDycfcFvOARnlubBnsJmDFqp6RblONVXDjImBNGHvAiu2o/RN6aqNQrHJKDvvPt+GNJWDF8Pi6+XUxh+uhU/dkG/KZUSONWBGKqzcy6Gm6uL146rq2FZURtWJuVOtW4Xe3XBTfk4ei6mt9ctbNY7rQ/tCcx9NxdAQBa+WkZR2f4wNNM95attlOOV/oQLhCuAIELIQrhKvjKQajx5DtCBMjubtcOQeom+HfHzr9sZbh47EtsfnnMSQ6td0utjiV512QiE0fzS9SO723i/OgE4PVP5bPw4mhzfH4IVauxLymuvc7koBVjXNVsVopZka1343tPaP+zlLbyWLrU6ftg6WHZ16ffB+xnbKbgHX/zN0dH/+DiQAQ7/+4B6wJRyZgfb/YTlYfhNbWBMtH8+AzloAV/0ZSM6BSc65inlxsG7ygi6CVGnZ+wSnn1A5i/8q814q/31xZMRkhrT9+/w6d9+E5T9S8r/TF9MJ8W2xsKfyFPAh/et5Lxe94/FuN7yC2GYZ4b2MJWBHfhruoT22rDDcXq+5ED4QrhCtAwEK4QrgaN5ZPXFRsoXs9n3kVs6/q7lzYcmHXHGzy/wc5LhSbj4m71ZU/35s/dvPPYlZV+bOXZt1RG8hSA9HviFk5NcPkY27NaLdJjiRgdXOHvf/V334HwD9u+kxG6jv595IaPt/Nufum70ivEMrDVjcB65bK991+J8q7x1fAqgSbsQas+LtOQWjpxIGjErDC4zVxpZPY4hozpYZWVXW35fHe/O/Ki91v5yurmn8WYSz+PuZIRTxqnfO1uXHen/Z+pBKaPpOcPRXD018/7UDjbp4jNZKAFTcxGO7ifn/Nlt97htl6CMIVwhUwZpOGCFgIV8IVoxR374tVEalVROFb89vvMvileQfbBsGXq4OqK3TebFpFdVm+Taf5ZzF7p5y39NHKBWmEtRhKX33uuCAfLrodyYB17dQLh/0Mq9u0ykHgo/1O/qLvo22PF59VN+feNP2y5Pt4Jl+p1k3AivOPdcCKmwOkXksM9e42XJX+KBH/4veld+LcrgJWrAo6XgEr7MuHsVfDUTdiVdbCPBZVH29NYsXYG/lWvTIuxZbJ6vyr8oL40/nWxfYB8HPzuzP2Z/8x+M32LbOVC+qYK/V7icHsRytgFf/mhrnIj9iXep4HZ+4RQBCuEK6AoxquBCyEK+GKI+TqfHVF9aK0nAlUHer9RGKlSMzcSsWX5lgUq7dioHjzzy8+NNepetezYitX5TVuPGVV2/bEEK87LrZj+1ysANs1bWu2I78r3C01w9CP9Aqs1B0D/7Dng6P+LuLc1PfQzbnx3lLvI8LfeA1YoRpSaiPgMFvmftz3a+n4lzh2PAasECEqhsJHlPp55d9LJ5+Y+1zlsYYucKufSbE6MP/7+HdSjUXNq6geqNw5NGJU/P3OynlDW0+va7uwfiMx06q4m2b/p4pVWbEaave0bdmu6RcVM6iqd0McacD6Uf4+h7vYv7d2CP9VQgjCFeIVcNTjlYCFcCVcUbMta6TnpAZ0hzMnLh429sQsqhWTFrfcpj7+XF1F9eXK6q1YGbQkjwLVVVXvO+2httf38TnPdrXNsbRl8uojMANr17Cfc2pFWMz4Ge1395V5ryZfyxkTBoY9N76HbsLUeAtYf93/6+mB6m/r6SpchWWTBpPfxQ8XfOyEClgtdwnML0a2Tjm3mN0Ud+n7af+nO0as+D2uXuhWVzfGjR1i9dW7Truv4yqqtflcrtR5L8++q+15Y6VX87nLJi1MxuaYSxcruFIX5G/OeWZMASvi+HAX/c/ld1NMfW7XT79YEEG4QrgCjmq4ErAQr4QrYrD6lHXFjKPYvhdb/uIi92f9ny1WPI3kcd41+0Dy4q4aoeKOgdVtTp+Z+2Lb/KvUKqqnTr255ZiIZrunXdTVyqdU5PjBgjdr30/19YwmYL33tAc7fmZ1keyN0x8f9ff52uz0HemunLpx2HPfnPN08tw1k5aP64D1mzWzq26cfmnXseexU29MPkYMMj9RA1ZKnB8xK/XYMZS9esF754yr21dMTt3QNv8qtYoq7gRaPe+r818bduVTDGxPvb6Hi88pfWFefT2juQvh6snLO1781/37WF8MxBdHEK4QroCjF64ELIQr4YrcJxJ3Ghsa3L1nRI9TnW1VrrqIYFU9tjof5yd9n8xerYSX1CqqzZPXtJ1XXdERKzcW53ctq97tL7XFsdNKpzdrLnJHErBia2Onz6wa5OqGpo/ErsQWrRArZjreETG/yPnbxDyu5kH64zVgVQf8l2Kg/YL4fwaGiTpn5qv/UrPIhgZ0X3tSBazSl+a3/3v95bgjaOXCd8XkJS0rI8th7dWbMVRXUaWCT5xXvVvgR+Y82Xbek7PS/y725FsGUxfnsWIrNYfvZwOfHVHAeujUzrOsqkGuvEFCbzHkXyRBuEK4Ao5euBKwEK7EKzoM7v6Xwa8Us626eYzr8xVP/zn4ra4HaT9YmY8Tvtv7y8Ouokqt3qoO3v79nvbnjICV2h4Wd2FLvb6Yl1U3mD5ee7cBK0RQqgtGsQKsenzEgvWTV4z6++x72/zkarOY5bS0wzbCB2buTr7+g7PvGfcBa8Pklcnfv3IFVX9sia0JOedMXlrMdUqdGwFk8aS+cR2wLpyyJnt21q1FCPqtnvcUKyjjfw8XsF6efWfbY7/ntAeSF8ExT6z13+obXd3B767K6q3UkPwYjF4976lZ6a2sB2ru9vfB0x+t/W/YSAJWBOfeifOS50Q8S53zlXmviSSIVwhXwFEPVwIWwpVwxaEo9L3eDyUvzmLVUgSAPVO3ZavyOw5GHIlzFuTDmuMOhLvyu+x9LJ89k1rdVGz5qVlJdF5lPk5q5daiCX3Jcz8998WO56aCS0itLoqodekp69viVaw6qnv8uOviSAJWxKR4v9XP/AOnP5w8Pi7yx/qd1s2y+ka+4qy6Oi3E3RJjJUn1+J8PfDlbPnHhuA9YEWQ+WbOSsBz8/dLsO7Kr8uH8G/LtXhF99ubbC2PFUUSOuvMez2dH1QWg8RKwbpuxPbF17jNDv3PJ1zE3G5jYm4x2dxerzboPRKUPJ1ZR1a3eqv77W56vfuv2bn8RxJsDUwyNf3s+l6rTc6zM/zvVbcAqV6FVV1TF6rK/6vtU8vj9eaQTSxCuEK6Aox2uBCyEK+GKQ+Jufv86+NWu7lZW3TpUJ1ZUdZqjFdv/6s79vZ73156XWr3VLCLFSMJXhJu4aH1l9v7sc/NebgyPjhU9MZi6enxsgYqgF9sZy7hTF7D+fmBou9Q/5QOifymPALE1MC64v5NYiVKK2Vtj/T4jMMZKtLqg9u48wsUW0RiCH0PfU6vTiqCR3+kt9fjjKmAdCjMRKlIrz0br8/Pekf/+zhv3AStWl8UKqNSKuw/nd/I7kN85L2JdrCCKO/fFVtIf1dxtcdHE9ID0m2Zc1vGzun3GlbUX09U7hLatgEycE99l3Yq67+Xh7eBp92S/ePqD2Q/63mwJv6n3FfO+tuSf2dYpazsGrPjvWvmcEffi3+lDp15fxLu6/+b9cMHHs75idZ9ognCFcAUc3XAlYCFcCVdUhpanVuGMRmyNqw7+7nZgeHhnHpPqzuu0eitef+POcxWXT7mg40qNqhiGXjdkvTEk/FBsqgtY9+fb8roNg+EL8145Yt9nrJBLhY1uvZ6//7rHHhcBKxGIYmVVdYvpaMSg8cF8lVKnGDWeZmBFtK3b8tqNCDfF3ThrLozPmDhYu8pyaBXVotpzO63eeu/pD9Wel4rHdX6eB+J1k89O3omw9OOmYfGpgBUxLV5Pt88Zn0exPVg4QbhCuAKOQbgSsBCuhCsSs59im85YLoQ/ml8cpradVe1P3N2s2zvm1W3x6zSUvdOw76rY3leuHosoMdqAFRe4t067ouM2tVLMLxqc0HtEv89leXj4WuWub8PGgIEvZQdm7Oz4uMc1YA0z22nF5MXFqrLR/P7+cx5CYttgT3FhOOeECVghVliVK/5GIlYU3hjf2zAXyd+pzKhrXhHV6bxOq7fqhrKHiGI/XPCxYV9/BMvt0zYW52zNV5LWhbbhAlas5hqcuCBfeffKsM8ZqzTvzVe2iScIVwhXwLEKVwIWgpFwRY2rp2wqhkLXzX2prkT4swUfKeLE+fkw7W6fY+XEM5IromLuUjlra6Srt56bdduwz7tv+o7alUl/2PPBIjg1H7960rJkrIhYcEW+qqtTwCq3A16YR4cvzn9n8uI6tr3FVr5O2y3H6pqpW4qo02mFXcSCmB8W0Wu4xzsuAWuEd9m7eOp52cfnPjvstsJYIRfRNiJS3cD2E+UuhMvzu/G9I1+9GEPXh1tt+P383+wL+VywJfF9d3GxHLPfUo9TN/i9tKRm9VYx565my2Lzyq+Yr/Vvg19LrraMELV68vKWc2LLZGyHrK4S+8b8X+gYsIq7bR6aqxURM7UdMQL9t3veXYQyAQXhCvEKONbxSsASrhCu6GIVT4Sa2GIUdxWLGVT7pl+ZXZevnth6yrm1W/ZOhNVmEatitVEMo1+bD2rudPySPD7E+71kyrpie143Q9xvm7695bgV+cDqiIP35s8Zn+dFeQiKge7H6j1HGIzXHyvHDszYld2ef49xp8mVE5eO3+9qwtjFnQavnrY5uyX/zO/LA8cdM3dku6ddVGw5XDBx3hF5jvHh8EXusjxmXT71gmI+1T353fsi7NyW//mKqRuKMHQiXbBH6Lpm2oXFDK8Y8H7Z1PPz2FgfvyJCxeD1S6acXwS/6rGpgBWhs/oYce7ePMrGaqvd+X/vYii9gIJwhXAFHI9wJWCJVwhXcER0G7A4tuHqrcPF/Uh0E7BAuEK4AsZTuBKwhCuEKxCwhCvhSsASsBCuEK6AcR2uBCzhCvEKBCzhSrgSsAQshCuEK2BchysBS7hCuAIBS7gSrgQsAQvxCuEKGNfhSsASrhCuQMASr4QrAUvAQrhCuALGdbgSsIQrhCsQsIQr4UrAErAQrhCugHEdrgQs4QrhCgQs4Uq4ErAELIQrhCtgXIcrAUu4QriCI2LRhL5s17StbVZMWuzzEa7Eq3FmYx6cd02/qMWOqZt8NghXiFfAuI5XApZwhXAFCFfCFSBcIVyBcDXuCVjiFcIVIFwJV4BwhXAFwpWAhXAlXAHCFcIVCFcIV4BwJWAJV4hXgHAlXAHCFcIVcFKFKwFLuEK4AoQr4QoQrxCuQLgSsBCuhCtAvBKuAOEK4QoQrgQs4QrhChCuhCtAuEK4Ak7KcCVgCVcIV4BwJVwBwhXCFQhXAhbClXAFCFfiFSBcIV4B4pWAJVwhXAHClXAFCFcIVyBcCViIV8IVIFwhXIFwhXAFCFcClnCFcAUIV8IVIFwhXAHClYAlXIlXAMKVcAUIVwhXIFwJWMIVwhUgXAlXgHiFcAUIVwKWcIVwBYhXwhUgXCFcgXAlYCFcCVeAcCVcAcIVwhUgXAlYwhXCFSBcCVeAcIVwBYhUApZwJVwBwhXCFQhXIF6BeCVgCVcIV4BwJV4BwhXCFSBcCVjilXAFIFwJV4BwhXAFwpWAhXAlXAHClXAFCFcIV4BwJWAJVwhXgHAlXAHCFcIVCFcIWMKVeAUIV7i4B/EK4QoQrgQs4QrhChCuhCtAuEK4AoQrAUu4Eq4ABCnhChBoEK5AuBKwhCuEK0C4Eq4A4QrhChCuBCzhCuEKEK6EK0C4QrgC8QoBS7gSrgDhSrwChCvEK0C4ErDEK4QrQLgSrgDhCuEKhCsELOFKuAKEK4QrEK4QrgDhipM2YAlHwhUgXAlXgHCFcAUIVwKWcIV4BQhXwhUgXiFcgXCFgCVcCVeAcCVcAcIVwhUgXHFCByzRSLgCxCvhChCuEK4A4UrAEq4QrgDhSrgChCuEKxCuELCEK+EKEK6EK0C4QrgChCtO6IAlGglXgHAlXgHCFeIVIF4JWMIVwhUgXAlXgHCFcAXCFQKWeCVcAcKVcAUIVwhXgHDFiMwv/BfhCuEKEK6EK0C4QrgC4YrxGK7GV8ASjsQrQLgSrgDxCuEKEK6ohKvxEbBEI+EKEK6EK0C4QrgChCs6xKvjF7BEI+EKEK+EK0C4QrgChCuGCVfHJ2CJRsIVIFwJV4BwhXAFCFd0Ga6ObcASjYQrQLgSrgDhCuEKEK4YYbg6NgFLNBKuAOFKvAKEK8QrQLxilOHq6AYs0Ui4AoQr4QoQrhCuAOGKMYaroxewhCPhChCuhCtAuEK4AoQrjkC4OvIBSzgSrgDhSrgChCuEK0C44giGqyMXsIQj8QoQroQrQLhCuAKEK45CuBp7wBKNhCtAuBKuAPEK4QoQrjjK8Wp0AUs0Eq4A8Uq4AoQrhCtAuOIYhKuRByzRSLgChCvhChCuEK4A4YpjGK66D1iikXAFCFfCFSBcIVwBwhXHIVwNH7BEI+EKEK7EK0C4QrwCxCuOY7iqD1iikXAFCFfCFSBcIVwBwhXjIFylA5ZwJFwBwpVwBQhXCFeAcMU4CVetAUs4Eq4A4Uq4AoQrhCtAuGKchavDAUs8Eq8A4Uq4AoQrhCtAuBKuxjEBS7gChCvhChCvEK4A4Uq8ErAQrgDxSrgChCuEKxCuEK4ELOEKEK6EK0C4QrgChCtOqnAlYAlXgHAlXAHCFcIVIFwJVwIWLsoB4Uq8AoQrxCsQrxCuBCzhChCuhCtAuEK4AoQrTspwJWAJV4BwJVwBwhXCFSBcCVcClnAFIFwJV4BwhXAFwhXClYAlXgHClXAFCFcIV4BwJVwJWAhXgHAlXAHiFcIVCFeIVwKWcAWIV8IVIFwhXAHCFcKVgCVcAcKVcAUIVwhXIFwhXAlYwhUgXCFcgXAFwhUIVwhXApZwBQhXwhUgXCFeAeKVcCVgCVcAwpV4BQhXCFcgXCFcCVjCFSBcCVeAcIVwBQhXCFcClnAFCFfCFSBcIVyBcIVwJWAJV4BwJVwBwhXCFSBcIVwJWOIVIFwJV4B4hXAFCFfClYAlXAHCFcIVCFcgXIFwhXglYAlXgHglXAHCFcIVHHPXX7Une+Ce+7O7br1LuDoJ7bjoyuL7DT2nzBeuBCzhChCuhCtAuEK4ghPP/XnYeNe73pW9+PyLwtVJ6NYbbi2+37BgSq9wJWAJV4BwJVwBwhXCFZx4br7u5uyxhx/L7tt/37h7bUtOW5xduuHSbPWiVeJVBxet25ptPW/rCRSwhCcBS7gChCvxChCuEK/gJHH55suL8HLdjuuEqxqDMwey119/PXv+uedPgIAlOAlYwhUgXAlXgHCFcAUnmX179x0OWGJV0vkr1hef0fgOWEKTgCVcAcKVcAUIVwhXnFB68ovO2Bq3cOZgx+MWnbqwOK5n8vwRP/7i2YuKcxec0ntU3kM87hlzzihe40hf2+CMgWxgen9Xx+IT3xMAABMpSURBVD/71LMjClgLpvZm/dP7jsiqpkWzF3Y8pm/qgmzJ6YsL8efjFbB2Xn7tqANW/J4snXvGUQlb8Rkun788/z76RxxlBqYP5K9raf4dLMoHz/eMOu7E48TvaafHWJB/d/Fco3mdApZwBQhXwhUgXCFcccLbuvbC7Nmnny1E6Iloc8ueW7KD7zzYCAovvfBSds2l1xRhJ87pn9aX3XjtDdk7Xn5H45hX3vFKMacqflb3XEvzi/Sbdu3N3v7s27PXX3u9cW78+ZEHHsm2rbuo8RypVU7xGuO45r+P11u+/ovP31b83caVG7JH7n+48fjF8PcXXsx2X7m7NpbF32/fckXx+AcPHn7vrx58NXv6iaeyPXmcWjJ7ccs5TzzyRPG8sTUujo3Po3wtl226tC2U7Ll6T/bC219oPPbLL76c7c0/j0WzhiJU3IEvzo3PsfncTas3NR73jDlLspUDK7MnHn288TjL5i1tDWR56Nm+dXsxM6x8bcXnnP/58Ucez67atiPrm9Yas+K1xeM/+diTtXcB3LRqY+N13Lz7ptooFL8bccxjDz2a7bxiZ/HnV155pfFdl49x4K4DbQErXmPE0Ahu8XfNv4evvvpqdu+d92Yr+s4aU7RafNqi7Kbde4sbAjT/jjz1+FPZlfndEHvjd6QmxCw5fUnxnUWIaz43Xuf9d9+fbTxnY+25zzz5TPG+d1y0o/jfMQ/s6Sefbvl3cM8d92TLe5Y3ztm0alPxnTV/h488+Eh27hnnCljiFSBcCVeAeIVwxVvHJRdc3Lg4PrtvRR5GnhiKKy+9XASD5ov0CECxiifCSBmt3vnKO1uOOZAHhtTzrFm8uiV4xcV6xJx4jObzb8ujRSpi1d2FMIJZee41l1ydbb9we3GRHyK8VV/f/tv2tz12RLBHH3y05bh4XS+9+FLL38XjrVhwVmPGVfP7qbr6kqsawSQCVcSL5vceASTiWPzvCHrL5y8rPvP433fecmdLcLlw7ZbGuecMriwiSPNzNQeseK6W4BHBKF8hFqGk+fuM7zlCTnnetvUXNX62KobRD7NKKoJgseoucVy8n/J97N11Y+1nFLGs+tgRD5f3LGuEvghfEfqq30012nUr9XtY/R15OI+fA/kKvGqEWbtsbcvva/w5olc1ZsV7Sa2mKmPcjdfeWATG8v1Wf4/i84vnvyIPqvF7/Nprr7X9LsZ5K/J/rwKWcAUIV8IVIFwhXPGWEHeGa8SnfEVMhI7ybnoRKM5burYRVuJCP1ZnRVxYf+b6RmiK8NUcaFYOnN3yHL2TexpRIy7GL9lwSctKqJX9Z7cEpC2rN3cdsOKxm+NZPP4N19zQsm1wzZI12fOHnr8INAvPaXmM2PrXiHTbd2ULm86NuHXZxksbkSNWFTWvqorVQOW5sfIo/i40b9eLkFMec/ve2xsrruLzjVU4EUIeOvBgY+XX7Tfe1hJdNucrsJqfI6LLDddcn23MV0TF91dsdTz0eOXnFPZcdV3xWsrHGZjRX0TI8ucP3PtAI0LFNr1ytdaOfBVSpzBVxqXUSqiIT+XjRxSLlV7xGh4+tCIuzi0/o3g91YAVMSd+FyKSRmwqfx5bTe+4eV/jsaur1LqxcNZgIwTF71GsbCtXW8UWvttvvL3le6quvCpDU3xf8b01r9SKbYjNn325yqpZeX587hGz4pgFxe9JbKddnO2/fX/L+4vguOeqPY2YFv/3+vx7L4+55fpbBCzhChCvhCtAuEK44q3hwnO3tGyDWpbP2ake0xw9InKUgatZbP8rj4mteM0/u2DF+Y2f7d25t3Z7YbmtMLZRdRuwQvM2ubjgT26VPG9ry0qt5p/FKpr4+0ceeLjjSrV4fRFxYhtfGUXiz+XjpmZgxeym8vXF46dWLZ2Xr+xpfg+3FmHi8M83nrOhZdVPhKFUoNmw8oKWVUB1IScCWXnc+jPXNf6+XLkV2/TawtT8ZY3VQRFX4s9x98XqcZfmsa/8PYkoVv79g3mg63YGVqwwa45bzbPDygD17FPPjHhAe4TN8rWtWbymLbL05DE04lJ5TESp8mflew4RvlKRpi9fDVhGvohVfVP7Wn4eK/jKx9iVh9Lq+THjqnlrbTWiFbOwpixorEiLlXUClnAFCFfCFSBcIVzxlrBlzebDF8yx8idxTHOAipU0qWMifJXHRCho/lkMRI9gEPN8iihQ81rKi/8IGKMJWLElr27weqzgaaxcyVeRNf+s3AJWzGSqnnsogER4Ss2GGi5gXbb5ssbPI6LVBZbm1Te37Lm5NkxFbKvbute80mtojlL6uWKFXCp0laEyIln1vZZhKp6j3HYar7nuNTSvVBtpwIrHr3vt8R2VW/9GcmfBiFNlQIoZUnWhJeJURKy7br2rWLlXnJtvByy3DsYKxU6hJmbF1YWuMr7FKsHBuDlC4vzm7aEx6yx1TPkZxAotAUu4AoQr4QoQrhCueMsFrCvzuTypY1YtXNW6dStxTPMsqrpjhlNuM4sVJqMJWA/d91DHOxKWr6+YMdX82Hff14gisb2x2BrZ5cqe4QJW88qdTlGpec5Vp4B1484bax/j+ecOb/Hr9JojgJVD1WMYfPn3MeOpZZtl0zl33ToUpmI4fblNML6n5pgWfy4jzdAKo9EFrFi1Vvfam7cRxoqs4cJV6azesyqfYffx5ez+s1vjZ4djmz/DCIKpgFUE2przI66VK8BitVXqmOatjp0GzgtYwhUgXIlXgHCFeMVJGbBSs6dCDC5vbL/LV5ikjono0xJgap4vHitW2MTFfcSdODZWu0QgKVfIjDZgxeN0eq/lcdWAtTa/o1vzgPN4HbF9K6JSaivbSAJWuVomdHqscovecAFrx7YdyfPjzoPlMdXVTymxBa+ca1b+XW/TSqPmOVgRpspta2f2DkW4cg7W0CqhoePO7l/ReA1Dq5dGF7A6hanm46p3UkyFq1LcHbDld3gE8WXz6sP/RnZevrPjsc2hbGgYf3vAis+i7vxyC+MLz79Qe8zNuw9H0brIJWAJV4BwJVwBwhXCFSdtwLrg7AuGDVh1q7SGC1gxN6u8e+FwRhuw7rhp36gCVli3/LyWQfSlCFsH7rq3iG6pYDJcwIpVYYe3e9UHpdj62E3A2nb+tuT5i2YvbByTmmFVFfO4ypU+zdsF7z60lbH5MeLOh9WVXeVWwbibXvl32y+8YigA5qGmugVxRAFrymgCVueAsm39tsNbFPNVdiOJLxc33anzsk2XdTw2tgY2biqw/0AyYBVbVYcJWJ1WaQlYwhUgXAlXgHCFcIWAdRQCVsSrmE9VBpP9t+0v7uy3IX++mI21avCcQhm4jnnAalppdP6K9dlNu29qbMdrFjO6ijssjiBglaEoBuR3CkoRY7oJWFvPuzB5fgxML48phuAPE7DK7ZqhOTbFFsFyCHn591flq76Kzzffvlc9rvm54s9Dx93R9nxHL2B1F1CaA1bM8xpJfLnkgku6jl9xp8Dmu3oKWMctYLkoB4Qr4QoQrhCuELBGFrAeOhQvIiBtXLnhqM3AGnHAGibyxMyqK7Zcns+JeuLwHfLyrXfNK3+GC1jlfK3htsbF3KexBKy+qYcD2KMPdrOF8Nm2LYTV11HOwSq3QTYPVz/r0O9EGbpC/LlYJZa4S+LRCVh9XQeUGKhennftZdeOKL5sWbOl6+2H3WwhFLDEK0C4Eq4A8QrhCsZZwIrh7jEcvZj9c++Dta8jzo84dcwCVpdD2suVWTft3nt4G19ToBkuYMUsrW6Gk29atXFMAat5LlWsFBvuPZVD3J987Mm2n8Wd9so5WBGTInIVQ+jzOV3Nn8mLL7zYCF2rFp3TiJSLZi0cdwErZnU1bjKw++YRxZdzBs/p+tzmIe5Dvw8C1jEMWC7MAeFKuAKEK4QrBKzRBaylc87o6u6E65add2xnYCVmSHUKPktOX3x4kPcVO7sOWFdfclXj5xvP2VD7+Ptu2jfmgLX/0PyqeJ+dYtmKvsPfZwSh6s/jLn3xs3i88w4FmdhSWT2uvDPhlRdtz666+KqOA+SPTMCaP+qA1ZMPqC9DXKyoqzsuhs/HLLRYxRYrr+Lv4k5/3Zwbys8hbFq1ScA6NgHLhTkgXglXgHCFcIWANbaANdg0E6gYDJ44NwaYl6t+GtvajmTAOhRAUgFr63lbi7Dw2muvdYw+MfuqfH1XbLkiGbb27trbdt6qfP5X+fMYkJ567NWLVzVWqY0lYG1u2iZ3/dV7ao9rXk0Ww+urP79gxfmNoe0R6+LPt994W9txl2++fGgO1r67G/Ovdm3flXzOMszENsORB6zDIaRTwIr5U6sWriqcMeeMtojSfO665euSoeXW62+t3Elx6O9vu+G2xt/HKqvUuRG6yq2Z8TvVN7VPwDq6ActFOSBcCVeAcIVwhYB15GZgPfX4U0Mrg/JIs/7M9S0/i0gQP3/6iafy825pPMaZ+fypMQesSiRJBazYFhd3CCy308Ud96rnLZu3tDGMPUJX/O/yZ735yp4yPsX5/dP7hrbYHRqAHlvtYlVS+b52X7n78DH5z2LrYISNcvXUWAJWPGesHCo/6+aZVeXzxV0Dy88hPtP4u9RA+YMHDxbHlHdmTN398Oz+FY1YE6vmDkef9tcWA+DL93DuGWsar6d8/nTAmt8xQlUD1vmHwluIQfzVc2OmWQzTL+Lc8y+0RKwIQTHfqvxsYh5by7nzD58bq8hiW2H17oPN3+GV+fbL6vMLWMIVIFwJV4BwhXAF4zhgNT9HBILHH3m8GG4eF+llAIkVTheee3hYdkSCu269Kzsnn1004oBVE3jqthDGoPbyZ+V2uQgYse0tVoaVP4v/G8fWbY8rV4/FyqWhSHF49dYr73ilcUwEs3jv5d/FtrTmuwiONmCVQe65Z55rHB9/jtVRB+66txFQytgWq8fqHue+/fe13IExtTot4lMZrsrvsfmOhs3i7n2N34E8rsVnFJ/DwlmDiYBVH2XGErDChWsvLCJkeVy8jvj8yy2C5QyxpXOXtp27efXmRuyM34W4a2ZEq/j+y7tsDq1Wuz3/bHoErCMfsFyUA8KVeAUIV4hXCFhHL2CFWA300gsvtUSRCBkRV5bPWzb0GHkQiaHnjWCU/3zt0rUjC1iTRh6wwvkr1hchonkrX3N0i7Cw/sx1yceNlUjlSqXS/sp2wTN7lxd/V67iKSPd7nzLXazIivDTMitslAErRBSK7YzlXQGbxcqj2OYX2zY7PUasIGrcebGIKZ3nbhWf/8131B4XK9WaV2GVIW9w5sAxDVhh9eLVxfdZ/a5j1dkt19+Sz0Nb1HGgewSo5ghWihAWW1JT8UrAEq4A4Uq4AoQrhCs4QUSgihVVsXUr7ly3MN92lTquL78oX3La4qHtZd0+/qQjI2LSWb1n5uHs3GxdHqxihtVwsafcvhdb1OJ9dVrZFO8p3lu5jbAUK5zKKLHnquuOyHuJ1xRxLeZcxdymeF+pLYPHUsS1+IzitUTUqtsqeCzEtr81i9c0vufqzKpO+vPfiTgnzo1tk4tPW3xChKQTLGC5KAeEK+EKEK4QruAkMenEUbe9LkQIKQPWZZsuPaHe1+gJOwKWcAUIV8IVIFwhXIFwddzFQPKYpxXbJ4cGg6ePi22N5XbF5T3LhCveqgHLhTkgXAlXgHCFcAXC1fHQPCdq764bG3Ofyi2LcWfC8uf37LtbuOKtGLBcmAPClXAFiFcIVyBcHU8x8+rZp55pGV7+9BNPFXcCjMHh5d/H3y2atVC84q0UsFyYA+KVcAUIVwhXIFyNF7Hq6vqr9xR3Uazeve75596e7bxiZ1fD4oUrTpKA5aIcEK6EK0C4QrgC4Wo8G5jRn63oOytbmd+RcfFpi6y44q0UsFyUA8KVcAUIVwhXIFwhXDEuA5aLckC4Eq8A4QrxCsQrhCsELEC4Eq4A4QrhChCuEK4QsADhSrgChCuEKxCuEK4QsADhCuEKhCuEK0C4QrhCwAKEK+EKEK4QrgDhSrgCAQsQo4QrQLxCuALhCvEKAQsQr4QrQLhCuAKEK+EKBCxAuBKuAOEK4QqEK4QrBCxAuBKuAOEK4QoQrhCuELAA4Uq8AoQrxCsQrxCuQMAC4QrhCoQrEK5AuEK4QsAChCvhChCuEK4A4Uq4AgELEK6EK0C4QrgC4QrhCgELEK6EK0C4QrgChCuEKwQsQLgSrgDxCuEKhCvEKxCwQLwSrgDhCuEKEK4QrhCwAOFKuAKEK4QrQLgSrkDAAuEK4QqEKxCuQLhCuELAAoQr4QoQrhCvAPFKuAIBCxCuxCtAuEK4AuEK4QoELBCuhCtAuEK4AoQrhCsELEC4Eq4A4QrhCoQrhCsQsEC4QrgC4QrhChCuEK4QsEQEEK6EK0C8QrgChCvhCgQsQIwSrgDhCuEKhCvEKxCwQLwSrgDhCuEKEK6EKxCwAOFKuAKEK4QrEK4QrkDAAuFKuAKEK4QrQLxCuAIBC4Qr8QoQrhCvQLhCuAIBC4QrhCsQrkC4AuEK4QoELBCuhCtAuEK4AoQr4QoELEC4Eq4A4QrhCoQrhCs4Tv4/Flg9SJN3XiYAAAAASUVORK5CYII=";
-
-async function tokenInfo() {
- try {
- const res = await fetch("https://interface.gateway.uniswap.org/v1/graphql", {
- method: "POST",
- headers: { "content-type": "application/json", origin: "https://app.uniswap.org" },
- body: JSON.stringify({ query: `{ token(chain: ${CHAIN}, address: "${TOKEN}") { name symbol market { price { value } } } }` }),
- cf: { cacheTtl: 300, cacheEverything: true },
- });
- const t = (await res.json())?.data?.token;
- if (t?.symbol) return { name: t.name || t.symbol, symbol: t.symbol, price: t.market?.price?.value ?? null };
- } catch {}
- return { name: "PAIR", symbol: "PAIR", price: null };
-}
-
-function fmtPrice(p) {
- if (p == null) return "";
- const digits = p >= 1 ? 2 : Math.min(8, Math.max(2, 2 - Math.floor(Math.log10(p))));
- return " Price $" + p.toFixed(digits) + ".";
-}
-
-function esc(s) { return String(s).replace(/[&<>"]/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c])); }
-
-function page({ name, symbol, price }) {
- const title = `Get ${symbol} on Uniswap`;
- const desc = `Buy, sell, and swap ${name} (${symbol}) on Uniswap. ${CHAIN_LABEL}.${fmtPrice(price)}`;
- const image = SITE + "/og.png";
- return `<!doctype html><html lang="en"><head>
-<meta charset="utf-8">
-<title>${esc(title)}</title>
-<meta name="description" content="${esc(desc)}">
-<link rel="canonical" href="${SITE}/">
-<meta property="og:type" content="website">
-<meta property="og:url" content="${SITE}/">
-<meta property="og:site_name" content="Uniswap">
-<meta property="og:title" content="${esc(title)}">
-<meta property="og:description" content="${esc(desc)}">
-<meta property="og:image" content="${image}">
-<meta property="og:image:width" content="1200">
-<meta property="og:image:height" content="630">
-<meta name="twitter:card" content="summary_large_image">
-<meta name="twitter:site" content="@Uniswap">
-<meta name="twitter:title" content="${esc(title)}">
-<meta name="twitter:description" content="${esc(desc)}">
-<meta name="twitter:image" content="${image}">
-<meta http-equiv="refresh" content="0;url=${DEST}">
-</head><body style="font-family:sans-serif;background:#131313;color:#fff;display:grid;place-items:center;height:100vh;margin:0">
-<p>Opening <a style="color:#FF37C7" href="${DEST}">${esc(title)}</a>&hellip;</p>
-<script>location.replace(${JSON.stringify(DEST)})</script>
-</body></html>`;
-}
-
-export default {
- async fetch(request) {
- const { pathname } = new URL(request.url);
- if (pathname === "/og.png") {
- const bytes = Uint8Array.from(atob(OG_PNG_B64), c => c.charCodeAt(0));
- return new Response(bytes, { headers: { "content-type": "image/png", "cache-control": "public, max-age=86400" } });
- }
- if (pathname === "/robots.txt") return new Response("User-agent: *\nAllow: /\n", { headers: { "content-type": "text/plain" } });
- return new Response(page(await tokenInfo()), {
- headers: { "content-type": "text/html; charset=utf-8", "cache-control": "public, max-age=300" },
- });
- },
-};