Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs: refresh every doc whose code had moved, and record the 110 reviews behind it
nirholasbba254d3484f
diff --git a/data/docs-freshness-budget.json b/data/docs-freshness-budget.jsonindex e6b28a6a2..965f1a338 100644--- a/data/docs-freshness-budget.json+++ b/data/docs-freshness-budget.json@@ -1,7 +1,7 @@{"$doc": "/docs/freshness","$comment": "Ratchet for `npm run check:docs-freshness`. maxStale is the number of docs allowed to be describing code that moved after they were written. It goes DOWN as docs are refreshed and never up without a reason recorded below, which is what stops drift from being permanently normal.",- "maxStale": 15,+ "maxStale": 5,"history": [{"date": "2026-07-31",@@ -12,6 +12,11 @@"date": "2026-08-05","maxStale": 15,"reason": "Full sweep: all 55 stale docs re-verified against source; 47 corrected and recommitted, 8 remain measured-stale only because they were verified accurate without needing an edit (the tool's clock is the doc's last commit). 15 leaves headroom for normal weekly code churn between refresh passes."+ },+ {+ "date": "2026-09-17",+ "maxStale": 5,+ "reason": "Full sweep of the whole stale queue, 110 docs (109 ranked at the start, plus one that crossed the line during the pass): 82 corrected against the commits that drifted, 22 read and found already accurate, 6 classified as dated records. Review baselines landed in the same pass (data/docs-freshness-reviews.json), so a doc verified without an edit can now be recorded instead of staying measured-stale, which is what let this reach 0. The check is wired into `npm run gate` from here, so 5 is deliberate headroom for normal churn between passes rather than a backlog allowance: 367 docs sit in watch and a few cross the line most weeks."}]}diff --git a/data/docs-freshness-reviews.json b/data/docs-freshness-reviews.jsonindex 8c86745da..82e4b9beb 100644--- a/data/docs-freshness-reviews.json+++ b/data/docs-freshness-reviews.json@@ -1,5 +1,666 @@{"$doc": "/docs/freshness","$comment": "Review baselines for `npm run docs:freshness`. Without this file the only clock a doc has is its own last commit, so a page someone read end to end and found correct still measures as drifting, and the only way to clear it is a cosmetic edit that lies about what happened. A stamp here says a human or an agent checked this doc against the repo at that commit. Freshness is then measured from whichever is newer, the doc's last edit or its last review. Write stamps with `npm run docs:review -- <doc> [more docs] --note \"...\"`, never by hand: the tool resolves the commit, refuses a doc that does not exist, and keeps the ordering stable. kind `verified` means the prose was checked against the code and matched. kind `snapshot` means the doc is a dated record (an audit, an incident writeup, a finished work order) that documents a moment and must not be rewritten to match today's code, so it is never counted as drift.",- "reviews": {}+ "reviews": {+ "docs/3d-asset-pipeline.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/a2a-payments.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-abilities/ABILITIES.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-abilities/FULL-ARTICLE.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-abilities/chapters/01-the-body.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-abilities/chapters/11-markets-intelligence.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-abilities/wallet/07-signals.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-economy-volume.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-index.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-shell.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-symphony.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agent-tasks/fix-x402-caller-mismatches.md": {+ "commit": "53f2a200f",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/agent-wallet-api.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agora/tasks/00-INDEX.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/agora/tasks/05-commons-scaffold.md": {+ "commit": "53f2a200f",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/assistant-widget.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/avatar-engines.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/avatar-reconstruction.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/avatar-wardrobe.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/blender-mcp.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/btn-pill-migration.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/chatgpt-ar.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/choreography.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/clash.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/coin-pages.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/configuration.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/copy-trading.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/crews.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/daily-forge.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/demo-routes.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/diorama.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/economy-master.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/economy-solver.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/event-readiness/01-play-first-impression.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/event-readiness/07-platform-smoke-sweep.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/event-readiness/14-welcome-concierge.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/event-readiness/17-plaza-live-show.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/event-readiness/18-coin-wars-portal.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/financial-controls.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/forge-background-generation.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/forge-pipeline.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/free-crypto-apis.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/guards.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/home-households.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/home-privacy.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/home-security.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/internal/MAINNET-TEST-2026-07-03.md": {+ "commit": "53f2a200f",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/internal/fable-playbook.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/irl/THREAT-MODEL.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/labor-market.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/launch-usecases.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "recipe handoff re-checked against the rebuilt /launch page"+ },+ "docs/lipsync.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/mcp-safety.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/money-map.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/news-rights.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/notifications.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/nvidia-models.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/object-library.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/onboarding-tier.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/onchain-agents.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/cron-auth.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/forge-error-triage.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/home-operations.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/play-store-developer-page.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/search-indexing.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/solana-rpc-lanes.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/trading-bot-report.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ops/wallet-key-migration.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/oracle-trading-mcp-plan.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/overlay-audit.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/page-performance.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/play-hardening.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/pump-platform-fee.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/risk-acknowledgment.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/security/SECURITY_AUDIT.md": {+ "commit": "53f2a200f",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/security/review-2026-06-24.md": {+ "commit": "53f2a200f",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/seed-quality.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/seeker-app.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/seeker-publishing.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/site-performance.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/smart-home.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/social-layer.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/solana-reputation.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/sonar.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/spotlight.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/talking-avatar-video.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/terminal.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/timeline.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/tutorials/mine-vanity-address.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/tutorials/pay-for-x402-service.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/tutorials/self-host-agent-backend.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/tutorials/write-a-guard.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/upstream/home-assistant-js-websocket-resubscribe-rejection.md": {+ "commit": "53f2a200f",+ "kind": "snapshot",+ "by": "agent",+ "note": "dated record, kept as written"+ },+ "docs/user-wallet.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/01-onboarding-creation.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/02-forge-text-to-3d.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/03-3d-editing-viewer.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/04-embed-widget-studio.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/05-discovery-social.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/06-marketplace-skills.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/07-crypto-trading-analytics.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/08-coin-launch-wallets.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/11-account-dashboard.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/ux-flows/12-home-and-content.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/vaults.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/walk-leaderboard.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/x-accounts.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/x402-distribution.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ },+ "docs/x402-ring-economy.md": {+ "commit": "53f2a200f",+ "kind": "verified",+ "by": "agent",+ "note": "full sweep: read against the drifted commits and corrected where wrong"+ }+ }}diff --git a/docs/3d-asset-pipeline.md b/docs/3d-asset-pipeline.mdindex 247d8c233..ecd4649e5 100644--- a/docs/3d-asset-pipeline.md+++ b/docs/3d-asset-pipeline.md@@ -96,8 +96,10 @@ This is how a motion enters the **shared animation library** that every agent an# 2. Add an entry to scripts/animations.config.json# 3. Build:npm run build:animations-# → retargets to cz.glb, writes public/animations/clips/<name>.json,-# rewrites public/animations/manifest.json, then re-syncs+# → builds the project-authored clips first (build-original-animations.mjs,+# keyframe choreography with no third-party source file), then retargets to+# cz.glb, writes public/animations/clips/<name>.json, rewrites+# public/animations/manifest.json, then re-syncs# public/animations/registry.json (sync-animation-registry.mjs) and# rebuilds public/animations/signatures.json (build-motion-signatures.mjs)```@@ -148,10 +150,17 @@ Source: [scripts/optimize-glb.mjs](../scripts/optimize-glb.mjs). Lossless geometTrack names are **canonical bone names** (`Hips`, `Spine`, `LeftArm`, …) so the same clip retargets onto any rig at runtime.-**manifest.json** maps each clip to the UI:+Every number in a written clip is serialized to **7 significant digits**+(`compactClipJson` in [scripts/compact-clips.mjs](../scripts/compact-clips.mjs)),+which is lossless for float32 keyframes and about half the bytes of+double-precision output. Regenerating a clip any other way doubles its size for+no visible difference.++**manifest.json** maps each clip to the UI. `duration` is written from the built+clip, and `category` appears when the config entry sets one:```json-{ "name": "idle", "url": "/animations/clips/idle.json", "label": "Idle", "icon": "🧍", "loop": true }+{ "name": "idle", "url": "/animations/clips/idle.json", "label": "Idle", "icon": "🧍", "loop": true, "duration": 15.8 }```**The canonical skeleton** is the 52-bone humanoid set exported as `CANONICAL_BONES` from [src/glb-canonicalize.js](../src/glb-canonicalize.js): the torso chain (`Hips → Spine → Spine1 → Spine2 → Neck → Head`), both arms (`Shoulder → Arm → ForeArm → Hand`) with full finger chains, and both legs (`UpLeg → Leg → Foot → ToeBase`). `public/avatars/cz.glb` is the reference rig every clip is retargeted against.@@ -191,7 +200,10 @@ There is **no rig allowlist**. [src/glb-canonicalize.js](../src/glb-canonicalize| 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` |+| Reallusion CC3 / CC4 | `CC_Base_Hip`, `CC_Base_Spine01`, `CC_Base_L_Upperarm`, `CC_Base_NeckTwist01` |+| Apple Reality Composer / ARKit-to-USD | `hips_joint`, `left_arm_joint`, `left_upLeg_joint` (trailing `_joint` stripped; `root_joint` stays unmapped, it is a transform above the skeleton) |+| Kinect v2 / Azure Kinect body tracking | `SpineBase`, `SpineMid`, `SpineShoulder`, `ShoulderLeft`, `KneeRight`, `FootLeft` (side word last) |+| MediaPipe Pose | `left_hip`, `left_knee`, `left_heel`, `left_foot_index` (landmark joints) || 3ds Max Biped | `Bip01 Pelvis`, `Bip001 L UpperArm`, `Bip01 L Calf` || CharacterStudio | `CH_Hips`, `CH_LeftUpLeg` || Autodesk HumanIK / Maya / MotionBuilder | `Character1:Hips`, `subject:LeftArm`, `char:ns:Hips` |@@ -288,7 +300,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`, 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.+- **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 comes back *not ok*; a probe that is merely slow loses the 1.5 s race and the load starts on the same-origin copy anyway, and a probe that errors is retried on the next load rather than demoting the whole session), 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.@@ -301,6 +313,8 @@ text/image ──► mesh_forge ──► static GLB ──► rig_mesh ──|---|---|| [scripts/fbx-to-glb.mjs](../scripts/fbx-to-glb.mjs) | FBX → GLB (FBX2glTF) — `npm run convert:fbx` || [scripts/build-animations.mjs](../scripts/build-animations.mjs) | FBX/GLB → retargeted clip JSON + manifest — `npm run build:animations` |+| [scripts/build-original-animations.mjs](../scripts/build-original-animations.mjs) | Project-authored clips built from keyframe choreography, no source file. Runs first in `build:animations` |+| [scripts/compact-clips.mjs](../scripts/compact-clips.mjs) | 7-significant-digit clip serialization (`compactClipJson`), shared by both clip builders || [scripts/extract-glb-animations.mjs](../scripts/extract-glb-animations.mjs) | Extract baked animation out of a GLB — `npm run extract:animations` || [scripts/sync-animation-registry.mjs](../scripts/sync-animation-registry.mjs) | Regenerate registry.json's `clips` from the built truth: `npm run sync:animation-registry` (chained into `build:animations`) || [scripts/build-motion-signatures.mjs](../scripts/build-motion-signatures.mjs) | Measure every baked clip into signatures.json: `npm run build:motion-signatures` (check with `npm run audit:motion`) |diff --git a/docs/agent-abilities/ABILITIES.md b/docs/agent-abilities/ABILITIES.mdindex f7897b597..9c09c8456 100644--- a/docs/agent-abilities/ABILITIES.md+++ b/docs/agent-abilities/ABILITIES.md@@ -12,13 +12,13 @@ That wallet is one page of the site. This article covers all of it: the agent fiEvery agent is embodied. Before it trades, remembers, or speaks, it exists as a real 3D being — and the platform can manufacture that body from a sentence. If you are new here, start by typing a prompt at three.ws/forge (free, no account) or making an avatar at three.ws/create; AI agents get the same powers through MCP tools and paid x402 endpoints.-three.ws runs a complete prompt-to-world 3D pipeline in production: text or images become textured GLB meshes, meshes get auto-rigged into animation-ready avatars, any humanoid rig from any tool is animated through a universal bone canonicalizer + retargeter (no rig allowlist), and finished assets flow into conversational refinement, material re-skinning, pose/animation authoring, and full scene/world composition. Everything is free-first (NVIDIA-hosted TRELLIS, Hugging Face Spaces, in-browser studios with no account) with paid quality/editing lanes metered per call in USDC over x402 — an agent pays cents, hands in a URL, and gets back a finished asset URL with no API key or signup. Every output is a portable glTF 2.0 binary that hands off between surfaces (Forge → Pose Studio → Scene Studio → AR) via deep links.+three.ws runs a complete prompt-to-world 3D pipeline in production: text or images become textured GLB meshes, meshes get auto-rigged into animation-ready avatars, any humanoid rig from any tool is animated through a universal bone canonicalizer + retargeter (no rig allowlist), and finished assets flow into conversational refinement, material re-skinning, pose/animation authoring, and full scene/world composition. Everything is free-first (our own GCP GPU workers first, then Hugging Face Spaces and NVIDIA-hosted TRELLIS, plus in-browser studios with no account) with paid quality/editing lanes metered per call in USDC over x402: an agent pays cents, hands in a URL, and gets back a finished asset URL with no API key or signup. Every output is a portable glTF 2.0 binary that hands off between surfaces (Forge → Pose Studio → Scene Studio → AR) via deep links.## Text→3D ForgeType a prompt at /forge (or call the forge_free MCP tool) and get a downloadable textured 3D model (GLB) plus a browser viewer link. The default lane is completely free — no account, no key, no wallet — with paid quality tiers (draft $0.05 / standard $0.15 / high $0.50 USDC) when more geometric budget is needed.-Free lane is Microsoft TRELLIS hosted on NVIDIA NIM/NVCF (async submit + poll; the hosted preview is pinned to a proven 15-step sampling budget for draft and standard, since higher budgets overrun its gateway window, while high-tier jobs route to the higher-fidelity lanes; prompts clamped to 77 chars with an auto 'studio lighting' suffix; output bytes persisted to R2 for a durable first-party URL). The backend registry (api/_lib/forge-tiers.js) also routes to Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), Replicate, self-hosted GCP GPU workers, and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).+One ordered free-lane walk lives in the backend registry (api/_lib/forge-tiers.js), and both the env-only default and the health-aware resolver read it, so they can never disagree. It starts at the tier's named free engine (FREE_DEFAULT_FOR_TIERS: our self-hosted TRELLIS worker at draft and standard, our self-hosted Hunyuan3D worker at high), falls through the remaining self-hosted GCP GPU workers, then the free Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), and ends at the free NVIDIA NIM/NVCF TRELLIS lane, which is the fallback that still answers a text prompt when every worker and Space is cold. Only configured, capable lanes survive the walk. The NIM lane is async submit + poll and pinned to a 15-step sampling budget below the high tier, since higher budgets overrun its gateway window; prompts are clamped to 77 chars with an auto 'studio lighting' suffix; output bytes are persisted to R2 for a durable first-party URL. The registry also routes to Replicate and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).Zero-cost text→3D that any human or AI agent can use instantly, with a transparent pay-per-call ladder — identical pricing across REST and MCP — when quality matters.@@ -48,7 +48,7 @@ Every generated or uploaded mesh becomes animatable in one paid call of a few ce## Universal retargeting-Any humanoid avatar from any tool plays the entire animation library, legs included, with zero manual bone mapping. Mixamo, VRM/VRoid, VRM 1.0, Unreal mannequin, Daz/Genesis, MakeHuman, Blender .L/.R, Rigify, HumanIK/Maya namespaces, CH_-prefixed rigs, Reallusion CC3/CC4, SMPL/SMPL-X, Roblox R15/R6, Second Life/OpenSim, anatomical scan rigs, snake_case/kebab-case, and simple shoulderL-style rigs are all handled out of the box.+Any humanoid avatar from any tool plays the entire animation library, legs included, with zero manual bone mapping. Mixamo, VRM/VRoid, VRM 1.0, Unreal mannequin, Daz/Genesis, MakeHuman, Blender .L/.R, Rigify, HumanIK/Maya namespaces, CH_-prefixed rigs, Reallusion CC3/CC4 (numbered spines included), MikuMikuDance PMX/PMD rigs named in Japanese, Apple/ARKit `_joint` skeletons, Kinect body-tracking joints, MediaPipe Pose landmark joints, SMPL/SMPL-X, Roblox R15/R6, Second Life/OpenSim, anatomical scan rigs, snake_case/kebab-case, and simple shoulderL-style rigs are all handled out of the box.glb-canonicalize.js rewrites the GLB's joint names onto a canonical 52-bone humanoid set (O(1) lookup plus alias maps), folds Mixamo's +90°X armature rotation into children with a world-matrix safety check, and repacks a valid GLB in place. animation-retarget.js then renames each clip track to the rig's actual bones, applies per-bone bind-pose correction (C = targetRest · sourceRest⁻¹, handling A-pose vs T-pose rests), and rescales hip translation by height ratio. Gates: ≥8 canonical bones to be playable, ≥50% track coverage per clip, and a 45° hips-tilt sanity check; a genuinely non-riggable prop falls back to the default rig via AnimationManager.supportsCanonicalClips() — never a bind-pose T-pose.@@ -1942,7 +1942,7 @@ Real-time and nine-years-deep crypto news in one place, readable without visitin## 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; 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).+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, Birdeye, GMGN, and GeckoTerminal views where the coin qualifies, the embed URLs living once in src/shared/chart-embeds.js so /coin/:id and /launches/<mint> build identical charts and a provider that does not index the coin's chain is never offered; 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.@@ -1982,11 +1982,11 @@ Rug/bundle detection and launch quality signals for any pump.fun coin, free and## /launches feed + pump.fun launch integration-A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with Oracle tier badges, an agent filter, generative per-mint identicons, and a 60s live refresh. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed — user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.+A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with an agent filter, generative per-mint identicons, and a 60s live refresh. The feed is deliberately neutral: no score, tier, or grade is painted on a user's coin. Judgment is replaced by facts on each mint's own addressable profile at /launches/<mint>, a trader sheet over /api/pump/token-stats (5m/1h/6h/24h volume, buys, sells, net buy, unique traders, price change; holder count, top-10 share, dev share, early-buyer share; mint and freeze authority; bonding-curve progress and graduation state; liquidity) beside a live price chart and trade tape, where a field that could not be read renders as a dash and never as 0. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed, so user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.src/launches.js reads the platform's own pump_agent_mints launch records via GET /api/pump/launches and enriches per-coin from pump.fun via /api/pump/coin; the launch path is documented in docs/coin-launches.md and docs/pump-launcher.md over api/pump/[action].js.-Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed with Oracle conviction attached.+Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed plus its own /launches/<mint> profile that shows the numbers and leaves the verdict to the reader.## PumpPortal live feed + reactive avatarsdiff --git a/docs/agent-abilities/FULL-ARTICLE.md b/docs/agent-abilities/FULL-ARTICLE.mdindex f98054dc1..9629a3b5c 100644--- a/docs/agent-abilities/FULL-ARTICLE.md+++ b/docs/agent-abilities/FULL-ARTICLE.md@@ -10,13 +10,13 @@ That wallet is one page of the site. This article covers all of it: the agent fiEvery agent is embodied. Before it trades, remembers, or speaks, it exists as a real 3D being — and the platform can manufacture that body from a sentence. If you are new here, start by typing a prompt at three.ws/forge (free, no account) or making an avatar at three.ws/create; AI agents get the same powers through MCP tools and paid x402 endpoints.-three.ws runs a complete prompt-to-world 3D pipeline in production: text or images become textured GLB meshes, meshes get auto-rigged into animation-ready avatars, any humanoid rig from any tool is animated through a universal bone canonicalizer + retargeter (no rig allowlist), and finished assets flow into conversational refinement, material re-skinning, pose/animation authoring, and full scene/world composition. Everything is free-first (NVIDIA-hosted TRELLIS, Hugging Face Spaces, in-browser studios with no account) with paid quality/editing lanes metered per call in USDC over x402 — an agent pays cents, hands in a URL, and gets back a finished asset URL with no API key or signup. Every output is a portable glTF 2.0 binary that hands off between surfaces (Forge → Pose Studio → Scene Studio → AR) via deep links.+three.ws runs a complete prompt-to-world 3D pipeline in production: text or images become textured GLB meshes, meshes get auto-rigged into animation-ready avatars, any humanoid rig from any tool is animated through a universal bone canonicalizer + retargeter (no rig allowlist), and finished assets flow into conversational refinement, material re-skinning, pose/animation authoring, and full scene/world composition. Everything is free-first (our own GCP GPU workers first, then Hugging Face Spaces and NVIDIA-hosted TRELLIS, plus in-browser studios with no account) with paid quality/editing lanes metered per call in USDC over x402: an agent pays cents, hands in a URL, and gets back a finished asset URL with no API key or signup. Every output is a portable glTF 2.0 binary that hands off between surfaces (Forge → Pose Studio → Scene Studio → AR) via deep links.## Text→3D Forge — free TRELLIS lane + paid tiered lanesType a prompt at /forge (or call the forge_free MCP tool) and get a downloadable textured 3D model (GLB) plus a browser viewer link. The default lane is completely free — no account, no key, no wallet — with paid quality tiers (draft $0.05 / standard $0.15 / high $0.50 USDC) when more geometric budget is needed.-**How it works:** Free lane is Microsoft TRELLIS hosted on NVIDIA NIM/NVCF (async submit + poll; the hosted preview is pinned to a proven 15-step sampling budget for draft and standard, since higher budgets overrun its gateway window, while high-tier jobs route to the higher-fidelity lanes; prompts clamped to 77 chars with an auto 'studio lighting' suffix; output bytes persisted to R2 for a durable first-party URL). The backend registry (api/_lib/forge-tiers.js) also routes to Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), Replicate, self-hosted GCP GPU workers, and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).+**How it works:** One ordered free-lane walk lives in the backend registry (api/_lib/forge-tiers.js), and both the env-only default and the health-aware resolver read it, so they can never disagree. It starts at the tier's named free engine (FREE_DEFAULT_FOR_TIERS: our self-hosted TRELLIS worker at draft and standard, our self-hosted Hunyuan3D worker at high), falls through the remaining self-hosted GCP GPU workers, then the free Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), and ends at the free NVIDIA NIM/NVCF TRELLIS lane, which is the fallback that still answers a text prompt when every worker and Space is cold. Only configured, capable lanes survive the walk. The NIM lane is async submit + poll and pinned to a 15-step sampling budget below the high tier, since higher budgets overrun its gateway window; prompts are clamped to 77 chars with an auto 'studio lighting' suffix; output bytes are persisted to R2 for a durable first-party URL. The registry also routes to Replicate and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).**Why it matters:** Zero-cost text→3D that any human or AI agent can use instantly, with a transparent pay-per-call ladder — identical pricing across REST and MCP — when quality matters.@@ -46,7 +46,7 @@ Adds a humanoid skeleton with per-vertex skin weights to any static GLB, turning## Universal retargeting — any humanoid rig animates (src/glb-canonicalize.js + src/animation-retarget.js)-Any humanoid avatar from any tool plays the entire animation library, legs included, with zero manual bone mapping. Mixamo, VRM/VRoid, VRM 1.0, Unreal mannequin, Daz/Genesis, MakeHuman, Blender .L/.R, Rigify, HumanIK/Maya namespaces, CH_-prefixed rigs, Reallusion CC3/CC4, SMPL/SMPL-X, Roblox R15/R6, Second Life/OpenSim, anatomical scan rigs, snake_case/kebab-case, and simple shoulderL-style rigs are all handled out of the box.+Any humanoid avatar from any tool plays the entire animation library, legs included, with zero manual bone mapping. Mixamo, VRM/VRoid, VRM 1.0, Unreal mannequin, Daz/Genesis, MakeHuman, Blender .L/.R, Rigify, HumanIK/Maya namespaces, CH_-prefixed rigs, Reallusion CC3/CC4 (numbered spines included), MikuMikuDance PMX/PMD rigs named in Japanese, Apple/ARKit `_joint` skeletons, Kinect body-tracking joints, MediaPipe Pose landmark joints, SMPL/SMPL-X, Roblox R15/R6, Second Life/OpenSim, anatomical scan rigs, snake_case/kebab-case, and simple shoulderL-style rigs are all handled out of the box.**How it works:** glb-canonicalize.js rewrites the GLB's joint names onto a canonical 52-bone humanoid set (O(1) lookup plus alias maps), folds Mixamo's +90°X armature rotation into children with a world-matrix safety check, and repacks a valid GLB in place. animation-retarget.js then renames each clip track to the rig's actual bones, applies per-bone bind-pose correction (C = targetRest · sourceRest⁻¹, handling A-pose vs T-pose rests), and rescales hip translation by height ratio. Gates: ≥8 canonical bones to be playable, ≥50% track coverage per clip, and a 45° hips-tilt sanity check; a genuinely non-riggable prop falls back to the default rig via AnimationManager.supportsCanonicalClips() — never a bind-pose T-pose.@@ -2079,7 +2079,7 @@ Live news aggregated natively from 197 real publisher RSS/Atom feeds across 27 c## 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; 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).+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, Birdeye, GMGN, and GeckoTerminal views where the coin qualifies, the embed URLs living once in src/shared/chart-embeds.js so /coin/:id and /launches/<mint> build identical charts and a provider that does not index the coin's chain is never offered; 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.@@ -2119,11 +2119,11 @@ A radar over every new pump.fun coin's first seconds of trading: bundle-launch l## /launches feed + pump.fun launch integration-A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with Oracle tier badges, an agent filter, generative per-mint identicons, and a 60s live refresh. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed — user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.+A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with an agent filter, generative per-mint identicons, and a 60s live refresh. The feed is deliberately neutral: no score, tier, or grade is painted on a user's coin. Judgment is replaced by facts on each mint's own addressable profile at /launches/<mint>, a trader sheet over /api/pump/token-stats (5m/1h/6h/24h volume, buys, sells, net buy, unique traders, price change; holder count, top-10 share, dev share, early-buyer share; mint and freeze authority; bonding-curve progress and graduation state; liquidity) beside a live price chart and trade tape, where a field that could not be read renders as a dash and never as 0. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed, so user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.**How it works:** src/launches.js reads the platform's own pump_agent_mints launch records via GET /api/pump/launches and enriches per-coin from pump.fun via /api/pump/coin; the launch path is documented in docs/coin-launches.md and docs/pump-launcher.md over api/pump/[action].js.-**Why it matters:** Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed with Oracle conviction attached.+**Why it matters:** Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed plus its own /launches/<mint> profile that shows the numbers and leaves the verdict to the reader.## PumpPortal live feed + reactive avatarsdiff --git a/docs/agent-abilities/chapters/01-the-body.md b/docs/agent-abilities/chapters/01-the-body.mdindex 58b4b06cc..64cf3a25f 100644--- a/docs/agent-abilities/chapters/01-the-body.md+++ b/docs/agent-abilities/chapters/01-the-body.md@@ -2,13 +2,13 @@Every agent is embodied. Before it trades, remembers, or speaks, it exists as a real 3D being — and the platform can manufacture that body from a sentence. If you are new here, start by typing a prompt at three.ws/forge (free, no account) or making an avatar at three.ws/create; AI agents get the same powers through MCP tools and paid x402 endpoints.-three.ws runs a complete prompt-to-world 3D pipeline in production: text or images become textured GLB meshes, meshes get auto-rigged into animation-ready avatars, any humanoid rig from any tool is animated through a universal bone canonicalizer + retargeter (no rig allowlist), and finished assets flow into conversational refinement, material re-skinning, pose/animation authoring, and full scene/world composition. Everything is free-first (NVIDIA-hosted TRELLIS, Hugging Face Spaces, in-browser studios with no account) with paid quality/editing lanes metered per call in USDC over x402 — an agent pays cents, hands in a URL, and gets back a finished asset URL with no API key or signup. Every output is a portable glTF 2.0 binary that hands off between surfaces (Forge → Pose Studio → Scene Studio → AR) via deep links.+three.ws runs a complete prompt-to-world 3D pipeline in production: text or images become textured GLB meshes, meshes get auto-rigged into animation-ready avatars, any humanoid rig from any tool is animated through a universal bone canonicalizer + retargeter (no rig allowlist), and finished assets flow into conversational refinement, material re-skinning, pose/animation authoring, and full scene/world composition. Everything is free-first (our own GCP GPU workers first, then Hugging Face Spaces and NVIDIA-hosted TRELLIS, plus in-browser studios with no account) with paid quality/editing lanes metered per call in USDC over x402: an agent pays cents, hands in a URL, and gets back a finished asset URL with no API key or signup. Every output is a portable glTF 2.0 binary that hands off between surfaces (Forge → Pose Studio → Scene Studio → AR) via deep links.## Text→3D Forge — free TRELLIS lane + paid tiered lanesType a prompt at /forge (or call the forge_free MCP tool) and get a downloadable textured 3D model (GLB) plus a browser viewer link. The default lane is completely free — no account, no key, no wallet — with paid quality tiers (draft $0.05 / standard $0.15 / high $0.50 USDC) when more geometric budget is needed.-**How it works:** Free lane is Microsoft TRELLIS hosted on NVIDIA NIM/NVCF (async submit + poll; the hosted preview is pinned to a proven 15-step sampling budget for draft and standard, since higher budgets overrun its gateway window, while high-tier jobs route to the higher-fidelity lanes; prompts clamped to 77 chars with an auto 'studio lighting' suffix; output bytes persisted to R2 for a durable first-party URL). The backend registry (api/_lib/forge-tiers.js) also routes to Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), Replicate, self-hosted GCP GPU workers, and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).+**How it works:** One ordered free-lane walk lives in the backend registry (api/_lib/forge-tiers.js), and both the env-only default and the health-aware resolver read it, so they can never disagree. It starts at the tier's named free engine (FREE_DEFAULT_FOR_TIERS: our self-hosted TRELLIS worker at draft and standard, our self-hosted Hunyuan3D worker at high), falls through the remaining self-hosted GCP GPU workers, then the free Hugging Face Spaces (Hunyuan3D/TRELLIS/TripoSR with automatic failover), and ends at the free NVIDIA NIM/NVCF TRELLIS lane, which is the fallback that still answers a text prompt when every worker and Space is cold. Only configured, capable lanes survive the walk. The NIM lane is async submit + poll and pinned to a 15-step sampling budget below the high tier, since higher budgets overrun its gateway window; prompts are clamped to 77 chars with an auto 'studio lighting' suffix; output bytes are persisted to R2 for a durable first-party URL. The registry also routes to Replicate and BYOK Meshy/Tripo native-geometry engines; paid calls settle over x402 (/api/x402/forge, text_to_3d MCP).**Why it matters:** Zero-cost text→3D that any human or AI agent can use instantly, with a transparent pay-per-call ladder — identical pricing across REST and MCP — when quality matters.@@ -38,7 +38,7 @@ Adds a humanoid skeleton with per-vertex skin weights to any static GLB, turning## Universal retargeting — any humanoid rig animates (src/glb-canonicalize.js + src/animation-retarget.js)-Any humanoid avatar from any tool plays the entire animation library, legs included, with zero manual bone mapping. Mixamo, VRM/VRoid, VRM 1.0, Unreal mannequin, Daz/Genesis, MakeHuman, Blender .L/.R, Rigify, HumanIK/Maya namespaces, CH_-prefixed rigs, Reallusion CC3/CC4, SMPL/SMPL-X, Roblox R15/R6, Second Life/OpenSim, anatomical scan rigs, snake_case/kebab-case, and simple shoulderL-style rigs are all handled out of the box.+Any humanoid avatar from any tool plays the entire animation library, legs included, with zero manual bone mapping. Mixamo, VRM/VRoid, VRM 1.0, Unreal mannequin, Daz/Genesis, MakeHuman, Blender .L/.R, Rigify, HumanIK/Maya namespaces, CH_-prefixed rigs, Reallusion CC3/CC4 (numbered spines included), MikuMikuDance PMX/PMD rigs named in Japanese, Apple/ARKit `_joint` skeletons, Kinect body-tracking joints, MediaPipe Pose landmark joints, SMPL/SMPL-X, Roblox R15/R6, Second Life/OpenSim, anatomical scan rigs, snake_case/kebab-case, and simple shoulderL-style rigs are all handled out of the box.**How it works:** glb-canonicalize.js rewrites the GLB's joint names onto a canonical 52-bone humanoid set (O(1) lookup plus alias maps), folds Mixamo's +90°X armature rotation into children with a world-matrix safety check, and repacks a valid GLB in place. animation-retarget.js then renames each clip track to the rig's actual bones, applies per-bone bind-pose correction (C = targetRest · sourceRest⁻¹, handling A-pose vs T-pose rests), and rescales hip translation by height ratio. Gates: ≥8 canonical bones to be playable, ≥50% track coverage per clip, and a 45° hips-tilt sanity check; a genuinely non-riggable prop falls back to the default rig via AnimationManager.supportsCanonicalClips() — never a bind-pose T-pose.diff --git a/docs/agent-abilities/chapters/11-markets-intelligence.md b/docs/agent-abilities/chapters/11-markets-intelligence.mdindex ffa4b5ca3..9c08bb5fd 100644--- a/docs/agent-abilities/chapters/11-markets-intelligence.md+++ b/docs/agent-abilities/chapters/11-markets-intelligence.md@@ -22,7 +22,7 @@ Live news aggregated natively from 197 real publisher RSS/Atom feeds across 27 c## 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; 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).+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, Birdeye, GMGN, and GeckoTerminal views where the coin qualifies, the embed URLs living once in src/shared/chart-embeds.js so /coin/:id and /launches/<mint> build identical charts and a provider that does not index the coin's chain is never offered; 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.@@ -62,11 +62,11 @@ A radar over every new pump.fun coin's first seconds of trading: bundle-launch l## /launches feed + pump.fun launch integration-A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with Oracle tier badges, an agent filter, generative per-mint identicons, and a 60s live refresh. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed — user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.+A public directory of every coin launched through three.ws by its agents: registry rows render instantly, then live pump.fun market data (price, art, graduation status) streams in per card, with an agent filter, generative per-mint identicons, and a 60s live refresh. The feed is deliberately neutral: no score, tier, or grade is painted on a user's coin. Judgment is replaced by facts on each mint's own addressable profile at /launches/<mint>, a trader sheet over /api/pump/token-stats (5m/1h/6h/24h volume, buys, sells, net buy, unique traders, price change; holder count, top-10 share, dev share, early-buyer share; mint and freeze authority; bonding-curve progress and graduation state; liquidity) beside a live price chart and trade tape, where a field that could not be read renders as a dash and never as 0. Launching itself is built in: a 'Launch Pump.fun' modal on every agent profile (client-signed, so user keys never leave the browser via launch-prep/launch-confirm), autonomous server-signed agent launches under spend caps, the Memetic Launcher (per-user autonomous launcher with trend sources and daily SOL caps), and Launch Studio's 50 declarative launch recipes.**How it works:** src/launches.js reads the platform's own pump_agent_mints launch records via GET /api/pump/launches and enriches per-coin from pump.fun via /api/pump/coin; the launch path is documented in docs/coin-launches.md and docs/pump-launcher.md over api/pump/[action].js.-**Why it matters:** Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed with Oracle conviction attached.+**Why it matters:** Launch a real on-chain pump.fun coin from an agent's profile in one flow, and every launch gets a live, shareable home in the platform's public feed plus its own /launches/<mint> profile that shows the numbers and leaves the verdict to the reader.## PumpPortal live feed + reactive avatarsdiff --git a/docs/agent-abilities/wallet/07-signals.md b/docs/agent-abilities/wallet/07-signals.mdindex 8f90ec465..784a45cb8 100644--- a/docs/agent-abilities/wallet/07-signals.md+++ b/docs/agent-abilities/wallet/07-signals.md@@ -40,6 +40,7 @@ Publishing is gated by the same verification math that powers the trader leaderb- Stop — end a subscription while keeping its delivery history- Simulate mode: mirrors the publisher's sizing on paper without paying or trading, for trust-building before going live- Live mode: pays real USDC per signal or per epoch from the agent's own wallet and auto-mirrors entries and exits+- Going live needs a signed real-funds agreement: creating a live subscription, resuming or un-killing one, or forcing a Sync on it answers `403 risk_ack_required` until the owner has signed the Terms of Service, the Risk Disclosure, and the Agent Wallet Agreement at [/legal/agreements](https://three.ws/legal/agreements). Simulate mode, pause, stop, and the kill button never ask for it, and devnet is exempt- Per-signal billing charges entries only — exit signals ride free once the entry was paid- Follower sizing formula: your base SOL × the publisher's size multiple × your scaling factor, hard-capped by your max-per-trade — dust-sized orders are skipped- Copy-exits option: mirrored exits sell the follower's full holding of that coin@@ -54,7 +55,7 @@ Publishing is gated by the same verification math that powers the trader leaderb## Guardrails & safety-The whole tab is owner-only, and every write is authenticated, CSRF-protected, rate-limited, and scoped to an agent the caller owns. Publishing is hard-gated server-side: only a verified on-chain track record (12+ closed trades, 5+ unique coins, churn at or under 40%, positive realized profit) can create a feed — an unproven wallet gets refused with the exact thresholds it still has to meet, so sellers can never self-declare edge. Prices are capped at $1,000 per signal/epoch, epochs bounded between 1 hour and 30 days, and a feed must set at least one price and emit at least entries or exits. Subscriber inputs are clamped: base size 0.001–10 SOL, scaling 0.01–20x, max per trade 0.001–50 SOL, slippage 0–50%; an agent cannot subscribe to its own feed. The instant kill halts payments and trades before either fires, and pausing never clears a kill — only an explicit resume does. New subscriptions are never billed for pre-existing signals. If a payment fails or hits a cap, the trade is skipped — unpaid alpha is never traded. Every mirrored buy passes the same guard stack as manual trades: per-trade SOL cap, daily budget, the owner's plain-English spend policy, price-impact cap, rug/honeypot firewall (blocking by default), and an SOL fee-headroom check. Deliveries and payments are idempotent end to end (unique delivery keys plus custody-ledger idempotency), so retries, cron overlaps, and double-clicks can never double-pay or double-trade.+The whole tab is owner-only, and every write is authenticated, CSRF-protected, rate-limited, and scoped to an agent the caller owns. Publishing is hard-gated server-side: only a verified on-chain track record (12+ closed trades, 5+ unique coins, churn at or under 40%, positive realized profit) can create a feed. An unproven wallet gets refused with the exact thresholds it still has to meet, so sellers can never self-declare edge. Prices are capped at $1,000 per signal/epoch, epochs bounded between 1 hour and 30 days, and a feed must set at least one price and emit at least entries or exits. Subscriber inputs are clamped: base size 0.001-10 SOL, scaling 0.01-20x, max per trade 0.001-50 SOL, slippage 0-50%; an agent cannot subscribe to its own feed. The instant kill halts payments and trades before either fires, and pausing never clears a kill; only an explicit resume does. New subscriptions are never billed for pre-existing signals. Nothing that can spend real money starts unsigned: every path that turns a live subscription on is behind `requireRealFundsAgreement()`, so an account with no signed agreements is refused before a payment or a mirror can fire. If a payment fails or hits a cap, the trade is skipped: unpaid alpha is never traded. Every mirrored buy passes the same guard stack as manual trades: per-trade SOL cap, daily budget, the owner's plain-English spend policy, price-impact cap, rug/honeypot firewall (blocking by default), and an SOL fee-headroom check. Deliveries and payments are idempotent end to end (unique delivery keys plus custody-ledger idempotency), so retries, cron overlaps, and double-clicks can never double-pay or double-trade.## Screenshot-worthy (shot list)diff --git a/docs/agent-economy-volume.md b/docs/agent-economy-volume.mdindex 8cab28607..d2768887d 100644--- a/docs/agent-economy-volume.md+++ b/docs/agent-economy-volume.md@@ -37,6 +37,11 @@ after USDC has settled to the provider is the row flipped to `completed`, withsummary attached. So "completed" is exactly "real USDC moved on-chain, with thesignature on file".+A hire is also refused outright, before a row is inserted or any spend is+reserved, when the hiring account has not signed the real-funds agreements: the+endpoint answers `403 risk_ack_required` and nothing reaches the ledger (see+[the real-funds agreements](risk-acknowledgment.md)).+The one place pending work appears is `totals.pending_hires`, a plain count shownas the sub-label under "Settled hires". It never enters a money figure.diff --git a/docs/agent-index.md b/docs/agent-index.mdindex 61006e402..8bdb739ca 100644--- a/docs/agent-index.md+++ b/docs/agent-index.md@@ -156,12 +156,41 @@ as fresh. That shape (every cursor current, zero events) is what a crashingcrawler looks like from the outside, and it is invisible to any check that onlyasks whether the job ran.+Cursor age is blind to a second shape, because the Solana sweep stamps its+`last_indexed_at` on the failure path too (deliberately, so one unreadable+account cannot hold the oldest-first queue head forever). A wedged agent then+looks exactly as fresh as a healthy one. So the monitor also scores the **share+of Solana cursors carrying an error**: 5% reads as `degraded`, 25% as `down`+(`SOLANA_ERROR_RATE_DEGRADED` and `SOLANA_ERROR_RATE_DOWN`).++The failure those thresholds were built for is the retention wall. Each leg+resumes from the last signature or block it recorded; when the RPC answering the+call no longer serves it, the read throws, the cursor is never written, and+every later tick re-asks for the same dead history. Both legs recover from it+now. [`api/_lib/solana/cursor-recovery.js`](../api/_lib/solana/cursor-recovery.js)+recognizes an unresolvable cursor signature and restarts that agent's sweep from+the head, and the EVM crawl skips forward once per tick past a pruned-history+rejection instead of letting the range backoff retry something it cannot fix.+The blocks skipped that way are published on the health board+(`historyGapChains`, `historyGapBlocks`) and never scored, because that history+is already gone and no tick can bring it back.++Solana leads the verdict, and here that is correctness rather than preference:+an EVM-only fault caps the subsystem at `degraded` instead of `down`, since a+secondary chain months behind head changes nothing on the agent profile a reader+actually opens. The detail line says so whenever the cap applies.++Operator-side detail (error classes, the queries to group them by, and the+recovery script for cursors already stuck) lives in+[docs/ops/agent-index.md](./ops/agent-index.md).+## Where the code lives| Piece | File || --- | --- || Event shape, validation, read and write | [`api/_lib/onchain-events.js`](../api/_lib/onchain-events.js) || Solana classification and per-agent crawl | [`api/_lib/solana-agent-events.js`](../api/_lib/solana-agent-events.js) |+| Retention-wall cursor recovery | [`api/_lib/solana/cursor-recovery.js`](../api/_lib/solana/cursor-recovery.js) || ERC-8004 identity log decoder | [`api/_lib/erc8004-registry-events.js`](../api/_lib/erc8004-registry-events.js) || ERC-8004 reputation log decoder | [`api/_lib/erc8004-reputation-events.js`](../api/_lib/erc8004-reputation-events.js) || Freshness monitor | [`api/_lib/ops/index-lag.js`](../api/_lib/ops/index-lag.js) |diff --git a/docs/agent-shell.md b/docs/agent-shell.mdindex 18b9d3a51..a1cee113b 100644--- a/docs/agent-shell.md+++ b/docs/agent-shell.md@@ -97,10 +97,21 @@ Requirements for a shell page:tolerate their target elements disappearing mid-flight (a navigation can landwhile a fetch is pending).-Live proof pages: `/markets`, `/coins`, and `/markets/robinhood`-([pages/markets.html](../pages/markets.html),-[pages/coins.html](../pages/coins.html),-[pages/markets-robinhood.html](../pages/markets-robinhood.html)). The swapper lives in+Live proof pages (every page carrying `data-shell` today):++| Route | Page |+| --- | --- |+| `/markets` | [pages/markets.html](../pages/markets.html) |+| `/coins` | [pages/coins.html](../pages/coins.html) |+| `/pocket` | [pages/pocket.html](../pages/pocket.html) |+| `/markets/robinhood` | [pages/markets-robinhood.html](../pages/markets-robinhood.html) |+| `/markets/robinhood/desk` | [pages/hood-desk.html](../pages/hood-desk.html) |+| `/markets/robinhood/portfolios` | [pages/hood-portfolios.html](../pages/hood-portfolios.html) |+| `/markets/robinhood/portfolios/universe` | [pages/hood-portfolios-universe.html](../pages/hood-portfolios-universe.html) |++Navigating between any two of them is a content swap, which is what makes the+Robinhood Crypto cluster feel like one terminal rather than four pages. The+swapper lives in[src/view-transitions.js](../src/view-transitions.js), which is inlined onevery page by the `view-transitions` plugin in[vite.config.js](../vite.config.js).diff --git a/docs/agent-symphony.md b/docs/agent-symphony.mdindex d31015786..b15c76a06 100644--- a/docs/agent-symphony.md+++ b/docs/agent-symphony.md@@ -135,6 +135,14 @@ cross-links are asserted statically byexplorer). New arrivals prepend a single row; screen readers get one shortthrottled announcement per arrival from a dedicated live region rather thana re-announcement of the whole list.+- **Ledger states.** Three of them, and they never borrow each other's copy.+ While the first read is in flight the strip shows six inert skeleton bars+ (`aria-busy`). A reachable but idle feed says the economy is quiet. An+ unreachable feed says so instead, with a "Try again now" button and links to+ `/pulse` and `/economy`: claiming the platform is quiet while we cannot see+ it would be a lie. The status pill is derived from two facts (did the last+ feed read succeed, is the SSE tail open), so a page that never reached the+ API can never read `live`.- **Background tabs.** The visualization loop stops and audio suspends whenthe tab is hidden, and both resume on return.diff --git a/docs/agent-wallet-api.md b/docs/agent-wallet-api.mdindex f6f151d97..cafdc7402 100644--- a/docs/agent-wallet-api.md+++ b/docs/agent-wallet-api.md@@ -58,6 +58,16 @@ Every state-changing request passes through [`api/_lib/csrf.js`](../api/_lib/csrFailures are `403 csrf_missing` (header absent) and `403 csrf_invalid` (wrong user, expired, or already consumed).+### Signed real-funds agreements++Arming or running anything that can move real funds additionally requires that the caller's account has signed the three real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement). The check is server-side in [`api/_lib/real-funds-agreement.js`](../api/_lib/real-funds-agreement.js) and applies to bearer callers exactly as it does to cookie callers.++- Refusal is `403 risk_ack_required`. The body carries `context`, the current `version`, a `sign_url`, and the `documents` to sign. Nothing is armed and nothing is sent.+- Devnet is exempt, so `?network=devnet` writes pass without a signature.+- Only the arming direction is gated. Reads, previews, simulations, pausing, disarming, the kill switch, and deleting never ask for it: stopping an agent must always be possible.+- Sign once at [/legal/agreements](https://three.ws/legal/agreements). See [risk-acknowledgment.md](risk-acknowledgment.md).+- Where the agreement and CSRF both apply, the agreement is checked first, so a refusal does not consume the caller's single-use CSRF token.+### Network selectionSolana is the home chain and mainnet is the default. Append `?network=devnet` to switch a read or a write to devnet; any other value falls back to mainnet. Capabilities are network-independent and ignore the parameter.@@ -350,6 +360,8 @@ A condition is one level deep, with no expressions and no code: `{ "all": [leaf,### POST /orders+A live order trades from the agent wallet on its own when it fires, so this route requires a signed real-funds agreement: an unsigned account gets `403 risk_ack_required` and no order is created.+Returns `201` with `{ "data": { "order": … } }`. Validation failures are `422` and carry the specific code from the normalizer: `invalid_order`, `invalid_type`, `invalid_side`, `invalid_mint`, `invalid_size`, `invalid_price`, `invalid_trail`, `invalid_schedule`, `invalid_expiry`, or `invalid_condition`, each with a human-readable `error_description`. A malformed body is `400 bad_request`, a wrong content type is `415`, and a database failure is `500 create_failed`.DCA and TWAP orders are created with `next_fire_at` set to now, so the first slice fires on the next worker sweep.@@ -459,7 +471,7 @@ Each fill carries a `custody_event_id`, which is the join back into the custodyOnly a bounded set of fields can change, and `type`, `side`, and `mint` are immutable (cancel and recreate instead). Accepted keys: `limit_price` (on a `limit` order), `stop_price` (on a `stop`), `trail_pct` (on a `trailing`), `slippage_bps`, `expires_at`, and `paused`.-`paused: true` parks the order in a non-evaluated state without losing fill progress. `paused: false` returns it to `partial` if it has fills, otherwise `active`. An empty patch is a no-op that returns the unchanged order.+`paused: true` parks the order in a non-evaluated state without losing fill progress. `paused: false` returns it to `partial` if it has fills, otherwise `active`, and because that re-arms the order it is the one patch that requires a signed real-funds agreement (`403 risk_ack_required` without one). An empty patch is a no-op that returns the unchanged order.Errors: `404 not_found` for an unknown order, `422 immutable` for a filled, cancelled, or expired order, `422 invalid_price`, `422 invalid_trail`, `422 invalid_expiry`, and `500 update_failed`.@@ -598,13 +610,13 @@ curl -s -X POST "https://three.ws/api/agents/$AGENT_ID/intents/compile" \Body: `{ "intent": { … }, "source_text": "…", "public_trait": false }`. `intent` is required and is re-validated server-side, so a client cannot arm something the compiler would have rejected. A resolved `destination`, `destination_label`, `to_tipper`, and `mint` from the compile step are preserved through re-validation. `source_text` is stored (truncated to 1000 characters) so the owner can see the sentence the rule came from. `public_trait: true` publishes the rule as a visible agent trait.-Success is `201` with `{ "data": { "intent": … } }`. A missing intent object is `400 validation_error`, an invalid one is `422`, and a write failure is `500 create_failed`.+Success is `201` with `{ "data": { "intent": … } }`. A missing intent object is `400 validation_error`, an invalid one is `422`, and a write failure is `500 create_failed`. A rule whose action is anything other than `freeze` or `notify` can move funds, so arming it needs a signed real-funds agreement (`403 risk_ack_required` without one).### POST /intents/runBody: `{ "intent_id": "<uuid>", "dry_run": true }`. **`dry_run` defaults to `true`**: it is only a real run when you explicitly send `"dry_run": false`. A missing or non-UUID `intent_id` is `400 validation_error`.-A real run honors the freeze, the wallet spend policy, and the intent's own caps exactly like the scheduler, and claims an idempotent custody row so one event can never fire the same intent twice.+A real run honors the freeze, the wallet spend policy, and the intent's own caps exactly like the scheduler, and claims an idempotent custody row so one event can never fire the same intent twice. A real run also requires a signed real-funds agreement; a dry run does not.```json{@@ -654,7 +666,7 @@ The real numbers are gathered first (live balance, plus 30 days of tips in, spen### PUT and DELETE /intents/:intentId-`PUT` accepts any of `enabled`, `public_trait`, `title`, and `intent` (a full replacement rule, re-validated). `404 not_found` for an unknown id, `422` with the normalizer's code for an invalid replacement. `DELETE` returns `{ "data": { "deleted": true } }`.+`PUT` accepts any of `enabled`, `public_trait`, `title`, and `intent` (a full replacement rule, re-validated). Enabling a rule or rewriting what it does re-arms autonomous spending and needs a signed real-funds agreement; disabling, renaming, and publishing do not. `404 not_found` for an unknown id, `422` with the normalizer's code for an invalid replacement. `DELETE` returns `{ "data": { "deleted": true } }`.```bashcurl -s -X PUT "https://three.ws/api/agents/$AGENT_ID/intents/$INTENT_ID" \@@ -773,7 +785,7 @@ Body: `{ "text": "…", "sweep_destination": "<base58>" }`. An invalid `sweep_deA patch, not a replacement. Accepted keys: `rules` (array; a non-array is `400 bad_request`), `buffer_sol`, `sweep_destination` (validated, `400 invalid_address` on a bad one, `null` to clear), `source_text`, `armed`, and `kill_switch`.-Arming is treated as explicit consent: sending `"armed": true` stamps `approved_at` and `compiled_at` server-side at the current time. Returns `{ "data": { "policy": … } }` with the newly normalized policy. Ownership is re-verified inside the write, so a `403 forbidden` or `404 not_found` can still surface here.+Arming is treated as explicit consent: sending `"armed": true` stamps `approved_at` and `compiled_at` server-side at the current time, and is the one key in this patch that requires a signed real-funds agreement. Disarming and the kill switch never do. Returns `{ "data": { "policy": … } }` with the newly normalized policy. Ownership is re-verified inside the write, so a `403 forbidden` or `404 not_found` can still surface here.```bashcurl -s -X PUT "https://three.ws/api/agents/$AGENT_ID/autopilot" \@@ -784,7 +796,7 @@ curl -s -X PUT "https://three.ws/api/agents/$AGENT_ID/autopilot" \### POST /autopilot/run-Body: `{ "dry_run": true }`. **The default is a real cycle.** Unlike `/intents/run`, this endpoint only simulates when you explicitly send `"dry_run": true`; an empty body executes for real. Send the dry run first if you are exploring.+Body: `{ "dry_run": true }`. **The default is a real cycle.** Unlike `/intents/run`, this endpoint only simulates when you explicitly send `"dry_run": true`; an empty body executes for real. Send the dry run first if you are exploring. A real cycle requires a signed real-funds agreement; a dry run does not.A run honors the kill switch, the disarmed state, the freeze, and the spend policy exactly like the scheduler, and refuses rather than guessing when it cannot trust its inputs:diff --git a/docs/agora/tasks/00-INDEX.md b/docs/agora/tasks/00-INDEX.mdindex af2642b43..efc2cfac7 100644--- a/docs/agora/tasks/00-INDEX.md+++ b/docs/agora/tasks/00-INDEX.md@@ -132,7 +132,10 @@ from repo root `/workspaces/three.ws`.- **3D generation** — `@three-ws/forge` (`packages/forge/`), backing`api/forge*.js` + `api/mcp-3d.js`. Text/image → rig-ready GLB.- **x402 payments** — `api/_lib/x402/bazaar-client.js` (`Bazaar`), `api/x402/*`,- `api/_lib/x402-spec.js`. USDC micro-payments + the bazaar service directory.+ `api/_lib/x402-spec.js`. Micro-payments in USDC, and in $THREE on the Solana+ rail when `X402_ACCEPT_THREE_SOLANA` is on (a resource quoting both renders a+ token chooser in checkout; agent wallets stay USDC-only), plus the bazaar+ service directory.- **Pages/routing** — register new pages in `data/pages.json`; HTML in `pages/`,JS in `src/`, CSS co-located or in `public/`. Vite multi-entry(`vite.config.js`), dev server `npm run dev` (port 3000).diff --git a/docs/assistant-widget.md b/docs/assistant-widget.mdindex b41b01166..5aa14c1bf 100644--- a/docs/assistant-widget.md+++ b/docs/assistant-widget.md@@ -2,7 +2,7 @@The assistant widget puts a full-body, animated three.ws avatar on any website behind a floating launcher button. Click it and the avatar pops up, standing directly on the page (transparent background) or against a color or gradient, with a message box underneath. It has two modes:-- **Chat**: a real chatbot. Messages go to an LLM and the reply streams into a speech bubble above the avatar's head, optionally spoken aloud. By default answers come from the platform's free model chain (Groq, then OpenRouter, then NVIDIA, no key and no account needed). Visitors can instead bring their own Groq or OpenRouter API key in the widget's settings; the key is stored only in their browser and calls go straight from the browser to the provider.+- **Chat**: a real chatbot. Messages go to an LLM and the reply streams into a speech bubble above the avatar's head, optionally spoken aloud. By default answers come from the platform's free model chain (Groq, then OpenRouter, NVIDIA, SambaNova, Mistral, and Z.ai, with the credits-funded Vertex Gemini rung as the last-resort anchor; no key and no account needed). Visitors can instead bring their own Groq or OpenRouter API key in the widget's settings; the key is stored only in their browser and calls go straight from the browser to the provider.- **Speak**: the avatar repeats exactly what you type, out loud, with a speech bubble and a talking animation. No model involved; speech uses the browser's built-in text-to-speech voices at zero cost.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.@@ -124,7 +124,7 @@ Ask your agent something like "build a 3D assistant widget named Aria with an oc- The launcher and panel are plain DOM injected by [`public/assistant/v1.js`](https://github.com/nirholas/three.ws/blob/main/public/assistant/v1.js), the minified build of the [`@three-ws/assistant`](https://github.com/nirholas/three.ws/tree/main/assistant-sdk) loader (no dependencies, idempotent). The avatar, chat, and speech run inside an iframe on `https://three.ws/assistant-frame`, so your page never sees model keys and the frame never sees your DOM.- The frame ([`src/assistant-frame.js`](https://github.com/nirholas/three.ws/blob/main/src/assistant-frame.js)) renders the avatar with Three.js, retargets the platform's canonical animation clips onto it (idle, wave greeting, a talking loop while speaking), and anchors the speech bubble to the avatar's head projection every frame.-- Free-lane chat posts to `POST /api/chat` (SSE stream, anonymous access, server-side rate limits; three.ws applies no content filter of its own, so any refusal is the serving model's). BYOK chat streams directly from the visitor's browser to Groq or OpenRouter with their key; the key lives in `localStorage` on the three.ws origin and is never sent to three.ws servers or the host page. When every free provider is throttled at once, the route answers `503 rate_limited` with a `retry_after`, and the widget shows that wait in the bubble alongside the settings panel as the way out (a visitor's own key is never subject to the platform's capacity).+- Free-lane chat posts to `POST /api/chat` (SSE stream, anonymous access, server-side rate limits; three.ws applies no content filter of its own, so any refusal is the serving model's). BYOK chat streams directly from the visitor's browser to Groq or OpenRouter with their key; the key lives in `localStorage` on the three.ws origin and is never sent to three.ws servers or the host page. Either lane runs under a 60-second deadline, so a wedged upstream ends as a readable error in the bubble instead of a thinking animation that never stops. The Vertex anchor is the only rung with no third-party quota to exhaust, so a throttled free tier fails over rather than failing; when every rung really is exhausted the route answers `503 rate_limited` with a `retry_after`, and the widget shows that wait in the bubble alongside the settings panel as the way out (a visitor's own key is never subject to the platform's capacity).- Speak mode and spoken chat replies use the Web Speech API (`speechSynthesis`). Voice pick persists per browser. When the browser has no TTS or voice is muted, the bubble and talking animation still run for the estimated duration, so the widget never silently stalls.- Every config param is re-validated inside the frame by [`src/assistant-widget-core.js`](https://github.com/nirholas/three.ws/blob/main/src/assistant-widget-core.js) (strict background/color grammars, length clamps, avatar host allow-list), so a hostile embedding page cannot inject CSS or URLs into the frame.diff --git a/docs/avatar-reconstruction.md b/docs/avatar-reconstruction.mdindex e30d8bc08..a103c5973 100644--- a/docs/avatar-reconstruction.md+++ b/docs/avatar-reconstruction.md@@ -41,6 +41,29 @@ poll would have, so an abandoned job still lands in the library. Design notes:- A provider 404 (`gcp_task_missing`) is terminal here, so a job whose workerrecord is genuinely gone resolves instead of being retried forever.+## Object storage cannot take the avatar away++The last step of finalize copies the finished GLB from the worker's bucket into+ours. That single `putObject` used to sit between the user and the avatar they+had already waited ninety seconds for: when the R2 credential stopped verifying+at 03:15 UTC on 2026-09-11, materialize aborted, no avatar row was written, and+the page could only say "Avatar finished but could not be saved. Try again."+Retrying never worked, because the photo was never the problem.++The mesh was never lost. The reconstruction worker parks it in+`gs://three-ws-avatar-reconstructions`, which is public and lifecycle-free, and+that URL is already in the job row. So `storeGlbOrKeepProviderUrl` in+[`reconstruct-finalize.js`](../api/_lib/reconstruct-finalize.js) now lets a+*named* storage-infrastructure fault (`isStorageInfrastructureError`: credential+rejected or revoked, bucket missing, endpoint unreachable) cost the durable copy+in our bucket rather than the user's avatar. The provider's absolute https URL+becomes the storage key: `publicUrl()` passes an absolute key straight through,+`copyObject()` declines to copy one, `defaultStorageMode()` records+`r2.present = false` instead of claiming bytes that are not there, and+`source_meta` carries `servedFrom` plus the `pendingBucketKey` a later re-copy+needs. Any other error still throws, so only a fault we can name is allowed to+degrade.+## Plan quotas are checked twice, on purposeA reconstruction only meets the caller's plan quota at the very end, insidediff --git a/docs/avatar-wardrobe.md b/docs/avatar-wardrobe.mdindex a789c2037..2731445fa 100644--- a/docs/avatar-wardrobe.md+++ b/docs/avatar-wardrobe.md@@ -158,6 +158,15 @@ live catalog is deliberately NOT checked at save time — a garment retired fromthe catalog later degrades to "not worn" on the next load/bake instead ofbricking the avatar.+The record is the only place an outfit lives, which is why a surface that+exports the live scene as a new avatar's **base** model has to strip the+garments off first. Avatar Studio's create-mode save does exactly that through+`GarmentCloset#withGarmentsOff()`: it detaches every worn piece scene-side, lifts+the skin occlusion they impose, exports, then re-attaches from the closet's own+byte cache (a parse, not a download). `working.garments` is never touched,+because that array is precisely what the server bake replays onto the base. Skip+the strip and every garment is applied twice.+## Failure posture- Garment can't reach the skeleton → refused with the measured coverage in thediff --git a/docs/blender-mcp.md b/docs/blender-mcp.mdindex 78978cbf4..f6ae611c3 100644--- a/docs/blender-mcp.md+++ b/docs/blender-mcp.md@@ -39,7 +39,7 @@ Some Linux distribution packages ship Blender without the Python modules its glTclaude mcp add blender -- npx -y @three-ws/blender-mcp```-In this repository the server is already declared in [`.mcp.json`](../.mcp.json) and runs straight from the working tree:+To run it straight from a checkout of this repository instead of the published package, add it to [`.mcp.json`](../.mcp.json) yourself. The entry is not committed: an MCP client rewrote that file in place on 2026-09-12 and dropped it, and the package it points at ships either way.```json{@@ -259,7 +259,7 @@ Failures come back as structured tool errors, each naming a fix:## Security-`blender_run_python` executes caller-supplied Python inside Blender with this server's permissions, including filesystem access. That is what the tool is for, and it is annotated `destructiveHint: true` so a client prompts before running it. For unattended or shared deployments set `BLENDER_MCP_ALLOW_PYTHON=0`: the tool is then never advertised, and the other five keep working.+`blender_run_python` executes caller-supplied Python inside Blender with this server's permissions, including filesystem access. That is what the tool is for, and it is annotated `destructiveHint: true` so a client prompts before running it. For unattended or shared deployments set `BLENDER_MCP_ALLOW_PYTHON=0`: the tool is then never advertised, and the other six keep working.Only `blender_forge_import` reaches the network, and only the deployment named by `THREE_WS_BASE`. Everything else stays on the machine. The broader model is in [MCP safety](./mcp-safety.md).diff --git a/docs/btn-pill-migration.md b/docs/btn-pill-migration.mdindex a2e5f12db..1b8e4258c 100644--- a/docs/btn-pill-migration.md+++ b/docs/btn-pill-migration.md@@ -56,7 +56,7 @@ Linked pills: use `<a class="pill pill--onchain">` — gets hover/focus states a## Remaining long tail — classes → canonical equivalent-These classes are defined across the codebase. Follow-up agents should replace them with canonical classes (keep old class as needed for scoped CSS overrides). Re-verified 2026-08-05: every class in both tables below is still in use in `pages/`, `src/`, or `public/`, so every row remains open work.+These classes are defined across the codebase. Follow-up agents should replace them with canonical classes (keep old class as needed for scoped CSS overrides). Re-verified 2026-09-17: every class in both tables below is still in use in `pages/`, `src/`, or `public/`, so every row remains open work.### Button class names → canonical@@ -78,13 +78,12 @@ These classes are defined across the codebase. Follow-up agents should replace t| `bento-action-btn`, `bento-pill-btn` | `.btn.btn--ghost` / `.pill` || `market-empty-cta-btn`, `market-empty-cta-btn.primary` | `.btn` / `.btn.btn--primary` || `btn-primary`, `btn-secondary` | `.btn.btn--primary` / `.btn.btn--secondary` |-| `capture-btn` | `.btn.btn--ghost` || `anim-btn`, `anim-btn--active`, `anim-btn--loading` | `.btn` + `[aria-busy]` for loading || `ltm-toggle-btn` | `.btn.btn--ghost` || `back-btn` | `.btn.btn--secondary` || `abort-btn`, `add-btn`, `assign-btn` | `.btn.btn--secondary` / `.btn.btn--danger` || `pay-btn` | `.btn.btn--primary` |-| `model-btn`, `anim-upload-btn`, `anim-repin-btn`, `anim-stop-btn` | `.btn.btn--ghost` |+| `d-model-btn` (marketplace detail), `anim-upload-btn`, `anim-repin-btn`, `anim-stop-btn` | `.btn.btn--ghost` |### Pill/badge class names → canonical@@ -111,8 +110,8 @@ These classes are defined across the codebase. Follow-up agents should replace t## Marketplace page note-`pages/marketplace.html` defines inline `.btn-primary` / `.btn-secondary` styles. Migration:+The page's bare inline `.btn-primary` / `.btn-secondary` definitions are gone; what remains are two scoped overrides in its `<style>` block (`.avatar-modal-actions .btn-primary/.btn-secondary` and `.payment-modal-success .ps-actions .btn-primary/.btn-secondary`) plus the detail-panel rules in `public/marketplace.css` (`.market-avatar-detail .btn-secondary`, `.market-tool-detail .btn-secondary`). The markup still uses the old names throughout. Migration:-1. Remove inline button CSS.-2. Replace `btn-primary` → `btn btn--primary`, `btn-secondary` → `btn btn--secondary`.+1. Replace `btn-primary` → `btn btn--primary`, `btn-secondary` → `btn btn--secondary` in the markup.+2. Retain the scoped sizing/colour overrides, rewritten against the canonical classes (`.avatar-modal-actions .btn { ... }`).3. Replace `market-empty-cta-btn.primary` → `btn btn--primary`.diff --git a/docs/chatgpt-ar.md b/docs/chatgpt-ar.mdindex eed776b5c..d0fb8dd02 100644--- a/docs/chatgpt-ar.md+++ b/docs/chatgpt-ar.md@@ -31,7 +31,7 @@ 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 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](./mcp-studio.md).+Two front doors serve the same free tools over one handler, both with no authentication. `https://three.ws/api/mcp-chatgpt` is the one ChatGPT lists: the eight 3D tools and the model viewer, with no persona tools and no `frameDomains`, because OpenAI's app guidelines reserve frame domains for embedding an essential third-party experience. `https://three.ws/api/mcp-studio` is the full surface for Claude and every other MCP host and adds the three persona tools. `SURFACES` in [api/_mcp-studio/dispatch.js](../api/_mcp-studio/dispatch.js) is the single definition of what each door advertises. Across the two, 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, on `/api/mcp-studio` only, 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](./mcp-studio.md).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.@@ -117,7 +117,7 @@ A place-in-your-room link is built to be forwarded. When it is pasted into a chaEverything 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](./3d-api.md).-- **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](./spatial-mcp.md) 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](./mcp-3d-studio.md), 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 full 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](./spatial-mcp.md) 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](./mcp-3d-studio.md), 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, so the end user pays nothing and needs no account. No backend is pinned: the health-aware router in [api/gpt-forge.js](../api/gpt-forge.js) walks the free lanes first (the self-hosted TRELLIS worker, the free NVIDIA NIM text→3D lane, the Hugging Face Spaces image→3D lane) and keeps the platform-keyed Replicate lane as a failover rung, so a cold or throttled free worker degrades to the next healthy engine instead of failing the request. Either way the cost lands on the platform. Real per-IP rate limits apply and are documented per endpoint (see [Funding & limits](./mcp-studio.md#funding--limits)).diff --git a/docs/clash.md b/docs/clash.mdindex 03f526303..2b739ec3e 100644--- a/docs/clash.md+++ b/docs/clash.md@@ -60,7 +60,7 @@ curl -X POST 'https://three.ws/api/clash/enlist' \-d '{"token":"<FACTION_MINT>","wallet":"<YOUR_WALLET>"}'```-The Coin Clash state and leaderboard are also exposed read-only over MCP through `@three-ws/clash-mcp` (`get_clash_state`, `get_clash_leaderboard`).+Coin Clash is also driveable over MCP through `@three-ws/clash-mcp`: `get_clash_state` and `get_clash_leaderboard` read the bracket and the records, and `enlist_faction` and `rally_faction` run the same wallet-signed enlist and rally an agent would run against the API (`enlist_faction` signs the challenge locally with the wallet's Solana key and returns the war pass; `rally_faction` spends taps with that pass, or auto-enlists first from a mint). No funds move in either.## States and limits@@ -75,5 +75,5 @@ The Coin Clash state and leaderboard are also exposed read-only over MCP through- [Token-gated 3D embeds](./token-gated-3d-embeds.md): the same real on-chain balance gate, applied to embeds- [Hold to access](./hold-to-access.md): the platform's broader hold-do-not-spend membership thesis- [The social layer](./social-layer.md): platform-wide feed, follows, and leaderboards-- [MCP tools](./mcp.md): the read-only Clash MCP server+- [MCP tools](./mcp.md): the Clash MCP server, read tools plus the wallet-signed enlist and rally- Pages: [/clash](https://three.ws/clash) · [/communities](https://three.ws/communities)diff --git a/docs/coin-pages.md b/docs/coin-pages.mdindex a71bae425..041a74b1b 100644--- a/docs/coin-pages.md+++ b/docs/coin-pages.md@@ -48,13 +48,21 @@ Grotesk display face).- **CoinGecko** — the native line chart (always available).- **TradingView** — the advanced candlestick widget (indicators, drawingtools), for any coin with a ticker symbol.- - **DexScreener** — the on-chain terminal keyed by the token's contract- address, for coins with a Solana mint or a supported EVM contract.- - **GeckoTerminal** — the on-chain terminal keyed by the token's most-liquid+ - **DexScreener**, **Birdeye**, **GMGN**: on-chain charts keyed by the token's+ contract address, for coins with a Solana mint or a supported EVM contract+ (GMGN indexes Solana, Ethereum, Base and BSC only, so it is offered only+ there).+ - **GeckoTerminal**: the on-chain chart keyed by the token's most-liquidpool, resolved server-side via `GET /api/coin/pool` (below).The picked source is remembered across coins and visits (localStorage`tws_coin_chart_source`), and the embeds follow the site's light/dark theme.+ Every embed URL shape lives once in+ [`src/shared/chart-embeds.js`](../src/shared/chart-embeds.js), so this page and+ the launch coin page `/launches/<mint>` build identical embeds and a provider+ changing its format is a one-file fix. Providers that refuse cross-origin+ framing or need a key are left out rather than offered as a tab that can only+ fail.A third-party terminal that never renders is caught, not left as an emptybox: [`src/shared/embed-guard.js`](../src/shared/embed-guard.js) gives each@@ -259,10 +267,11 @@ third-party gas API, no key.### `/screener`: the Token ScreenerA live filtering workbench over the **top 250 coins by market cap**. The page-loads the whole set once (`/api/coin/markets?page=1&per_page=250`, the same-cached endpoint behind the markets table, so no new endpoint), then every-keystroke, filter change, and sort runs instantly in the browser with no-further network traffic.+loads the whole set once (`/api/coin/markets?page=1&per_page=250&sparkline=0`,+the same cached endpoint behind the markets table, so no new endpoint; the+screener draws no sparkline column, and dropping the 7-day series cuts that+250-row response from roughly 215 KB to 70 KB), then every keystroke, filter+change, and sort runs instantly in the browser with no further network traffic.The filter controls, all composable (a coin must pass every active one):@@ -275,9 +284,12 @@ The filter controls, all composable (a coin must pass every active one):- **Reset** restores every control and the default sort in one click (thezero-results empty state offers the same reset inline).-The results table reuses the shared `cv-table` pattern from the markets index:-rank, coin (icon, name, symbol), price, 24h %, 7d %, market cap, and 24h-volume. **Every column sorts**: click a header, or focus it and press+The results table renders through the shared market-table primitives+([`src/shared/market-table.js`](../src/shared/market-table.js)), the same rows,+columns, sorting and row navigation the markets index, the token page and the+coin lobby use, so those surfaces cannot disagree about what a row or a stale+value looks like: rank, coin (icon, name, symbol), price, 24h %, 7d %, market+cap, and 24h volume. **Every column sorts**: click a header, or focus it and pressEnter/Space (headers are keyboard-reachable and announce `aria-sort`). Thefirst activation sorts name and rank ascending and every numeric columndescending; activating the already-active column flips the direction. Rows@@ -296,8 +308,9 @@ Files: [`pages/screener.html`](../pages/screener.html) (shell, controls, SEO),[`src/screener.js`](../src/screener.js) (state, filtering, sorting,rendering), [`src/filter-controls.css`](../src/filter-controls.css) (thelabelled filter row, shared with `/yields`), with shared formatters-from [`src/shared/coin-format.js`](../src/shared/coin-format.js) and the table-pattern from [`src/coins-index.js`](../src/coins-index.js).+from [`src/shared/coin-format.js`](../src/shared/coin-format.js) and the rows,+columns and sorting from+[`src/shared/market-table.js`](../src/shared/market-table.js).### `/compare` — side-by-side comparison@@ -323,8 +336,8 @@ Three details the table and chart depend on:## More market tools-Eight further tools round out the suite, same design system, same "real key-free-data" rule:+Thirteen further tools round out the suite, same design system, same "real+key-free data" rule:- **`/screener`**: filter the top 250 coins by search, gainers/losers, minimummarket cap, and minimum 24h volume; every column sorts. Reuses@@ -611,6 +624,7 @@ text before they reach the client.| News archive | [`pages/news-archive.html`](../pages/news-archive.html) + [`src/news-archive.js`](../src/news-archive.js) || News engine + sources | [`api/_lib/news.js`](../api/_lib/news.js) + [`api/_lib/news-sources.js`](../api/_lib/news-sources.js), endpoints in [`api/news/`](../api/news) || Shared news renderers | [`src/shared/news-render.js`](../src/shared/news-render.js); table primitives in [`src/shared/market-table.js`](../src/shared/market-table.js) |+| Shared chart embeds | [`src/shared/chart-embeds.js`](../src/shared/chart-embeds.js): the third-party embed URLs `/coin/:id` and `/launches/<mint>` both build from || Shared design system | [`src/coin-pages.css`](../src/coin-pages.css) (Inter, Space Grotesk, JetBrains Mono self-hosted in `public/fonts/`) || Shared formatters | [`src/shared/coin-format.js`](../src/shared/coin-format.js) — unit-tested in [`tests/coin-format.test.js`](../tests/coin-format.test.js) || API proxies | [`api/coin/`](../api/coin): one file per `/api/coin/*` endpoint in the table above (`detail.js`, `ohlc.js`, `pool.js`, `markets.js`, `tickers.js`, `categories.js`, `category.js`, `exchanges.js`, `exchange.js`, `derivatives.js`, `rates.js`, `trending.js`, `global.js`, `fear-greed.js`, `gas.js`, `news.js`, `liquidations.js`) |diff --git a/docs/configuration.md b/docs/configuration.mdindex 80fafce9a..ee98b2f5c 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -249,19 +249,8 @@ Sign up through the [Avaturn developer docs](https://docs.avaturn.me/).AVATURN_API_URL=https://api.avaturn.me```-#### `VITE_AVATURN_EDITOR_URL`-**Optional.** URL for the hosted avatar editor (no photos required, opened by the "Use default avatar" card at `/create`).--```-VITE_AVATURN_EDITOR_URL=https://editor.avaturn.me/-```--#### `VITE_AVATURN_DEVELOPER_ID`-**Optional.** Developer ID appended as a query parameter to the avatar editor URL.--```-VITE_AVATURN_DEVELOPER_ID=xxxxx-```+#### `VITE_AVATURN_EDITOR_URL`, `VITE_AVATURN_DEVELOPER_ID`+**Retired; no code reads them.** Both still appear in `.env.example`, but the photo pipeline no longer builds an editor URL in the browser: `src/avatar-creator.js` opens the `@avaturn/sdk` editor against the session URL that `/api/onboarding/avaturn-session` mints server-side from `AVATURN_API_KEY`. Setting either variable changes nothing.#### `AVATAR_REGEN_PROVIDER`**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`.@@ -444,7 +433,8 @@ The build is controlled by the `TARGET` environment variable:| Command | `TARGET` | Output | Description ||---|---|---|---|| `npm run build` | `app` (default) | `dist/` | Full multi-page SPA |-| `npm run build:lib` | `lib` | `dist-lib/` | Self-contained web component for CDN |+| `npm run build:lib` | `lib` | `dist-lib/` | Self-contained web component for CDN (ES module only) |+| `npm run build:lib:full` | `lib` | `dist-lib/` | The same bundle in both ES and UMD form (`LIB_FORMATS=es,umd`); this is what `build:gcp` runs || `npm run build:all` | both | both | Builds the chat bundle first, then app and lib in parallel |**App build** (`TARGET=app`) emits many HTML entry points for the multi-page app, sourced from `pages/`:@@ -455,11 +445,11 @@ The build is controlled by the `TARGET` environment variable:- `pages/dashboard-next/`: user dashboard (sub-pages auto-discovered)- `public/studio/index.html`: widget studio-**Library build** (`TARGET=lib`) emits a self-contained ES module and UMD bundle:+**Library build** (`TARGET=lib`) emits a self-contained ES module. The UMD bundle is opt-in through `LIB_FORMATS`, which is why the deploy chain runs `npm run build:lib:full` (`TARGET=lib LIB_FORMATS=es,umd`) rather than `build:lib`:```-dist-lib/agent-3d.js # ES module-dist-lib/agent-3d.umd.cjs # UMD (CommonJS-compatible)+dist-lib/agent-3d.js # ES module (npm run build:lib)+dist-lib/agent-3d.umd.cjs # UMD, CommonJS-compatible (npm run build:lib:full)```Three.js and ethers are bundled (not externalized) so the web component works as a zero-install drop-in embed via `<script type="module">`.diff --git a/docs/copy-trading.md b/docs/copy-trading.mdindex 77d3c4f51..f1dad0796 100644--- a/docs/copy-trading.md+++ b/docs/copy-trading.md@@ -198,6 +198,8 @@ Then `planMirror` (pure, unit-tested in `tests/mirror-engine.test.js`) decides:The sized order then goes through `runFollowerTrade`, which is the same guard sequence the discretionary trade endpoint and the sniper use, in this order: agent kill switch, per-trade cap, rolling daily budget, the natural-language spend policy (`meta.policy_rules`), price-impact breaker, rug and honeypot firewall (a `block` verdict refuses the mirror), on-chain SOL headroom, then an idempotency claim in the custody ledger before anything is signed. Slippage is capped at 300 bps. Every mirrored trade lands in `agent_custody_events` with `reason: 'mirror'` and a `meta.mirror` reference naming the leader and the leader's event.+A mirrored trade is a trade three.ws signs, so it carries the platform trade fee like every other one: 1 percent of the SOL spent on a buy, or of the minimum SOL out on a sell, transferred to the platform treasury inside the same transaction. It is built by the shared `buildTradeInstructions`, which is why the mirror cannot route around it, and it is skipped for platform-owned agents and wherever no fee wallet is configured. The rate, the basis, and what is not billed are in [platform trade fee](./pump-platform-fee.md). The copier path has no such fee: you sign that trade yourself, from your own wallet.+Nothing double-spends: the custody idempotency key `mirror:<follow_id>:<leader_event_id>:<side>` and the unique index on `agent_mirror_fills (follow_id, leader_event_id, side)` both dedupe, so a retried cron or an overlapping manual sync replays instead of re-buying.Each attempt writes exactly one `agent_mirror_fills` row with status `executed`, `skipped`, `failed`, or `unconfirmed`, plus a machine reason. The UI renders those reasons through `SKIP_LABELS`, for example `Over per-trade cap`, `Blocked by safety firewall`, `Wallet underfunded`, `Daily budget used up`.@@ -401,7 +403,6 @@ Response:"categories": ["smart_money"],"name": "<DISPLAY_NAME>","twitter_username": "<HANDLE>",- "avatar": "<IMAGE_URL>","realized_profit_30d_usd": 0,"pnl_30d": 0,"pnl_7d": 0,@@ -427,7 +428,7 @@ Response:`total` is the count *after* filtering, `facets` carries the directory-wide counts by chain and category for building filter chips, and `source` plus `generated_at` are the provenance of the snapshot. Note that `win_rate_30d` is a fraction (0 to 1) here, unlike the leaderboard's `win_rate`, which is a percentage.-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.+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`. The snapshot records an avatar URL for some wallets, but the endpoint strips it: that image host answers 403 to any off-site request, so the URL cost every client a blocked load and no client could ever render it. The dashboard shows the trader initial instead. 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](./smart-money.md).diff --git a/docs/economy-master.md b/docs/economy-master.mdindex 27afbcbdf..53e363dcd 100644--- a/docs/economy-master.md+++ b/docs/economy-master.md@@ -99,6 +99,10 @@ Topup is the outbound leg; **sweepback**:41) is the return leg. It walks the same registry and brings surplus back, soevery lamport cycles master → engines → work → master:+- **Never swept at all.** A signer marked `holdsUserFunds` in the registry holds+ money owed to third parties, not platform float, so both sweepback and+ `reclaimIdleSol` skip it in every mode, drain included, and report it as+ `holds_user_funds`.- **Excess mode (the schedule).** Skims only SOL *above* each signer's operatingfloat — the same `refillTo` the topup refills to, so the two crons neveroscillate — and consolidates stray token balances from signers that don't@@ -145,7 +149,7 @@ the return.## Agent-wallet reclaim: the other half of the fleet's SOLSweepback and `reclaimIdleSol` both walk the **`SOLANA_SIGNERS` registry** — the-fourteen engine wallets. That is not where most of the platform's SOL lives.+fifteen engine wallets. That is not where most of the platform's SOL lives.`fundAgentForLaunch` ([`api/_lib/launcher-funding.js`](../api/_lib/launcher-funding.js))moves SOL master → **agent custody wallet** one way, and nothing ever moved itback: snipes recycle ~97 % of their capital, but the proceeds settle into the@@ -642,7 +646,7 @@ a third-party-verifiable timestamp of the books.The 2026-07-02 wiring gaps this section used to track are closed. Current stateof the tree the master feeds:-- **The registry defines the master plus fourteen engine signers** (relayers,+- **The registry defines the master plus fifteen engine signers** (relayers,launcher master, treasuries, marketplace payer, a2a payer, ring sponsor/payer,circulation treasury, NFT collection authority). An engine whose secret env isunset simply never resolves and is skipped by the sweep; set each engine'sdiff --git a/docs/event-readiness/01-play-first-impression.md b/docs/event-readiness/01-play-first-impression.mdindex 789c26d1f..f82c89cf9 100644--- a/docs/event-readiness/01-play-first-impression.md+++ b/docs/event-readiness/01-play-first-impression.md@@ -22,7 +22,7 @@ https://three.ws/play?coin=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump&name=thr1. **The blank-screen window.** Time from navigation to first meaningful paint of the world. Anything over a couple of seconds of dead screen needs a designed loading state: skeleton or branded loader with real progress (assets actually loading), never a fake timer. Note `pages/play.html` already ships an inline boot watchdog: while the loading card is up, a failed same-origin script/stylesheet, an uncaught boot error, or 45s of silence swaps the spinner for a real error card with a retry, and it deliberately ignores blocked optional extras and flaky WebSocket reconnects (scope in `docs/play-boot-performance.md`). Build on that path; do not duplicate it.2. **Query-string identity.** The coin name, symbol, and image from the URL must be visibly used: page title, HUD, world signage. Verify the `image` param (an /api/img proxy URL) renders everywhere it should and has a fallback if the IPFS fetch fails.3. **Intro/onboarding flow.** Run it fresh (clear localStorage). Is it skippable? Does it explain movement, chat, and the economy in under 30 seconds? Does it re-appear when it should not?-4. **HUD polish.** Every button: hover, active, focus states. Panel open/close transitions (opacity + transform, no pops). Consistent spacing and typography with the existing design tokens (`docs/DESIGN-TOKENS.md`).+4. **HUD polish.** Every button: hover, active, focus states. Panel open/close transitions (opacity + transform, no pops). Consistent spacing and typography with the existing design tokens (`docs/DESIGN-TOKENS.md`). Two ratchets already cover the mechanical half of this and the HUD is expected to stay clean under both: `npm run audit:states` fails a selector that declares `cursor: pointer` with no `:hover` rule behind it (the focus and disabled floors live in `public/tokens.css`), and `npm run audit:motion-tokens` fails a transition whose duration or easing is off the one ladder. Run them over your changes rather than eyeballing the CSS.5. **Dead paths.** Click every visible control. Anything that does nothing, links nowhere, or throws is a bug to fix now.6. **The screenshot test.** Would a stranger screenshot this and share it? If not, identify the top 3 visual gaps (lighting, framing, initial camera position, signage) and fix them.diff --git a/docs/event-readiness/17-plaza-live-show.md b/docs/event-readiness/17-plaza-live-show.mdindex f444d1d36..5120e427d 100644--- a/docs/event-readiness/17-plaza-live-show.md+++ b/docs/event-readiness/17-plaza-live-show.md@@ -5,15 +5,15 @@ The platform already has Living Stages: an embodied AI host runs a real-time sho## 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 client (page-level, reuse it): `src/stage.js`, `src/stage-net.js`, `src/stage-element.js`, served at `pages/stage.html`. The host's performance is already extracted out of that page into `src/shared/stage-voice.js` (`StageVoice`: fetches `/api/tts/speak`, routes it through the host's `PositionalAudio`, taps an `AnalyserNode` for lip-sync, and stops cleanly when the next beat pre-empts it), written to be imported by the plaza show client too- 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.** 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.+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`; the attendance ring around it is `STAGE_ATTEND_REACH` (8 m past the edge, so 13 m from the stage centre), sized to contain the golden-angle seat ring StageRoom deals out (`RING_RADIUS` 6 m plus 1.6 m per concentric ring, so 6.0/7.6/9.2 m from the stage origin). A nearer ring, `STAGE_MARQUEE_REACH`, is where the marquee is still legible and where the 45 s show-state poll (`REFRESH_MS` in `plaza-stage.js`) runs.+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 `src/shared/stage-voice.js` rather than rewriting either: 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.diff --git a/docs/event-readiness/18-coin-wars-portal.md b/docs/event-readiness/18-coin-wars-portal.mdindex 490353bf4..6a2241f0c 100644--- a/docs/event-readiness/18-coin-wars-portal.md+++ b/docs/event-readiness/18-coin-wars-portal.md@@ -6,7 +6,7 @@ Coin Wars is finished and, since the portal landed, visible. `ClashRoom` runs fu- 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+- 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), plus `src/play/war-board.js`, the war-room panel every terminal state on that page renders (hand-typed URL, expired ticket, holding that came up short): live battles, the queue, and the top of the Elo ladder off the same `/api/wars` fold the portal board reads, each row linking back into that coin's world. `/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: 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()`)diff --git a/docs/financial-controls.md b/docs/financial-controls.mdindex c3a6a22e5..cf7fd1be3 100644--- a/docs/financial-controls.md+++ b/docs/financial-controls.md@@ -44,6 +44,7 @@ and whether it is reconciled against the chain.| a2a mandate settlements | **no durable ledger** — mandate is an unstored JWS; cap in Redis (`INCRBY`) with per-replica memory fallback | ❌ | ❌ | Redis atomic (bypassable w/o Upstash) | ❌ || Credit deposits | `credit_ledger` (`amount_usd, balance_after, tx_signature, idempotency_key UNIQUE`) — balance+ledger in one CTE | ✅ | ✅ | `idempotency_key UNIQUE` + finalized-only | on finalized tx || Subscriptions | `subscription_checkouts` (`reference UNIQUE, amount, platform_fee_amount, tx_signature`) | ✅ | mutable status | `reference UNIQUE` + payment-idempotency | ❌ |+| Platform trade & launch fee (1%, live since 2026-09-16) | **no fee ledger of its own.** A server-signed agent trade records the fee block in `agent_custody_events.meta.platform_fee` next to the trade's signature; a wallet-signed trade or launch carries it only in the prep/confirm response, and `launch-confirm` refuses to list a launch whose confirmed transaction did not pay it (`txPaidPlatformFee`) | ✅ via the trade's own signature | custody events by convention | the trade's own claim row | ❌ **no** || Vanity bounty payouts | **Redis / in-memory** (`vanity-bounty-store.js`) — not Postgres | ⚠️ in Redis only | ❌ (memory fallback loses on restart) | Redis CAS | ❌ |\* **"By convention"** means the code never issues UPDATE/DELETE on the table, but@@ -86,7 +87,8 @@ Books automatically verified against the chain:**NOT reconciled against the chain:** `x402_audit_log` (the main revenue ledger),`club_payouts`, `cosmetic_sales`, `agent_jobs`, `agent_withdrawals`,-`three_buyback_runs`, and vanity payouts.+`three_buyback_runs`, vanity payouts, and the 1% trade/launch fee (which has no+ledger to reconcile).Two blind spots default a record to `reconciled=true` without verifying it:**EVM/Base** settlements (`skipped_non_solana`) and **RPC failures** (`unknown`).@@ -239,7 +241,14 @@ Ranked by accounting/regulatory risk. Each is a tracked remediation item.covered, see §3); **no external alert channel beyond Telegram, and the pushlane self-throttles**; **global kill switches need a redeploy** (add aruntime halt flag).-14. **Financial data shares the storage-capped Neon branch** — isolate money/audit+14. **The 1% trade and launch fee has no revenue ledger.** Every customer trade+ three.ws builds or signs pays it on-chain (see+ [pump platform fee](pump-platform-fee.md)), but the only durable record is the+ custody event of a server-signed trade; fees paid inside a user-signed+ transaction are countable only by scanning the fee wallet. *Fix: an append-only+ `platform_fee_events` row per charged transaction, keyed `UNIQUE` on the+ signature, and a reconciler against the fee wallet's on-chain receipts.*+15. **Financial data shares the storage-capped Neon branch.** Isolate money/audittables onto their own branch/DB so an intel-firehose cap can't drop financialwrites.diff --git a/docs/forge-background-generation.md b/docs/forge-background-generation.mdindex 7c249f3fe..e531d4d8c 100644--- a/docs/forge-background-generation.md+++ b/docs/forge-background-generation.md@@ -31,7 +31,14 @@ Three cooperating pieces:submitted, its signed job token persists in `localStorage`(`forge:inflight`). On page load the forge resumes polling that token; allreal state lives server-side, so a reload costs nothing. The record clears- on completion, terminal failure, or cancel.+ on completion, terminal failure, or cancel. The poll loop itself is built on+ [src/shared/resilient-poll.js](../src/shared/resilient-poll.js) (retry,+ visibility-wake, attempt-based budget), because a generation runs for minutes+ and on a phone the tab is backgrounded, the radio drops, and the edge answers+ the odd 502, none of which mean the job died. A connection we finally gave up+ waiting on throws with `kind = 'transport_lost'`, and that one case+ deliberately **keeps** the inflight record rather than clearing it, which is+ what makes the error's own "reopen /forge to pick it back up" true.2. **Server-side finalizer** ([api/cron/forge-finalize.js](../api/cron/forge-finalize.js),every minute via Cloud Scheduler): sweeps `forge_creations` rows still at@@ -65,6 +72,15 @@ Three cooperating pieces:Email delivery uses the platform Resend pipeline and skips undeliverableplaceholder addresses.+ **Developer webhooks are the one channel that ignores the attended /+ unattended split.** `forge.completed` fires from `materializeCreation`, the+ universal completion writer, so an API integrator learns every outcome+ whether or not a browser was watching. `forge.failed` fires from+ `notifyForgeFailed` instead, because this is the only place that can tell a+ terminal failure from a failover that is still running: `markFailed` also runs+ on the redispatch path, and telling a subscriber the job died while it is+ still running would be a lie. See [api-reference.md](api-reference.md).+## Self-host poll recovery (the "task not found" grace)A self-host worker poll (`/tasks/:id` or `/jobs/:id`) can 404 when the durable@@ -107,6 +123,15 @@ worst backend/path and top error class so a page is actionable. It rolls into`degraded` 60 to 85%, `down` < 60%, `unknown` below 15 finished generationsin-window. This is the forge twin of the x402 settlement-success sensor.+The rate can only judge generations that got far enough to write a+`forge_creations` row, so `classifyForgeStall` answers the other question: has+the forge stopped **starting** generations? A failure upstream of that row (on+2026-09-07, object storage rejecting the reference-image upload every lane+needs) writes no rows at all, and no rows otherwise reads as a quiet hour. A+lane averaging at least 3 starts an hour that has started nothing for 45 minutes+reports `down` with the hint to check `object_storage` in the same payload+first, because that shape is a shared dependency rather than a lane fault.+## Operational notes- The finalizer needs `CRON_SECRET` (the shared fail-closed cron gate,@@ -118,6 +143,15 @@ in-window. This is the forge twin of the x402 settlement-success sensor.- The response body reports `{ swept, done, failed, failed_over, resubmitted,timed_out, still_running, unpollable }` per tick, so a quick manual hitshows queue health at a glance.+- A finished mesh also gets a phone-sized delivery variant (`buildWebVariant`,+ meshopt geometry plus WebP textures capped at 2048 px) written straight after+ materialization, to a second key, so the stored original is never touched and+ `download` and every API consumer keep the full-resolution mesh. Meshes forged+ before 2026-09-04 are backfilled newest-first by+ [api/cron/forge-web-variants.js](../api/cron/forge-web-variants.js) (every 10+ minutes, `FORGE_WEB_VARIANT_BATCH` meshes per tick, default 6). A row whose+ variant would not be smaller keeps `web_glb_url` null, and every reader already+ treats null as "serve `glb_url`".Related: [3d-pipeline.md](3d-pipeline.md) for the generation lanes themselves,and the notification preference model indiff --git a/docs/forge-pipeline.md b/docs/forge-pipeline.mdindex 3ba80fda8..d7e846c43 100644--- a/docs/forge-pipeline.md+++ b/docs/forge-pipeline.md@@ -133,6 +133,8 @@ 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.+**Backdrop pre-matting.** A synthesized reference view is on a *plain* background, which is not the same as a transparent one, and the reconstructor fuses that backdrop in as geometry: six text personas through the live router returned four figures standing on a full-footprint slab and two that were a bare plane with no figure at all. Non-draft text jobs therefore get the same rembg cutout that image jobs already got (`matte: tier.id !== 'draft'`), while draft stays single-view and fast. It is best-effort worker-side: a rembg miss falls back to the original image rather than failing the generation.+**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@@ -141,7 +143,9 @@ Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forg### Poll-`GET /api/forge?job=<id>` returns `status`: `queued`, `running`, `done` (with `glb_url`, `viewer_url`, and the `path`/`tier`/`backend` that actually produced it), or `failed`. Polling is free and unauthenticated. The in-flight job id is also written to `localStorage`, so an interrupted browser session resumes polling for up to 30 minutes; background completion persists the result to the user's gallery either way (see [Background generation](./forge-background-generation.md)).+`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.++Every non-terminal poll also carries honest timing: `elapsed_seconds` (the age of the *job*, from `created_at`, not of the tab watching it), `eta_seconds` (the lane's typical total) and `eta_remaining_seconds`. The remaining figure is floored at 5, because the estimate is a typical duration rather than a deadline and a countdown that goes negative reads as "stuck" on a job that is merely slower than average. A `queued` poll on a scale-to-zero self-host lane additionally carries `cold_start` and `cold_start_seconds` (that lane's spin-up budget). `laneColdStart()` is module-scope for exactly this reason: it used to be a closure inside the submit handler, so only the submit response could say a worker was booting, and a client that never saw it (a coalesced job, a page resumed after a reload, a failover successor) was told "queued" with no explanation for a wait that is a container boot rather than a stall. `forgeStageNarration()` and `coldStartState()` in [src/shared/forge-frames.js](../src/shared/forge-frames.js) turn those fields into the same copy on every surface, off the payload and never off a local clock, and the flag clears on the first real `running` poll rather than on a timer. 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](./forge-background-generation.md)).**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.@@ -170,6 +174,17 @@ Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forg**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.+### When object storage is the thing that is down++A rejected S3 secret takes 3D generation and every avatar, thumbnail and GLB read down at once, and on 2026-09-07 it did so with no health signature at all, because the forge sensor only sees generations that got far enough to write a row. Four rules now bound that blast radius:++1. **It has its own sensor.** [api/_lib/ops/object-storage-health.js](../api/_lib/ops/object-storage-health.js) probes the bucket with a signed one-key list and reports `ok` / `degraded` / `down` with the R2-specific hint (the secret is the token *digest*, not the token).+2. **The reference-view write is no longer a single point of failure.** `persistImageBytes` runs before the reconstructor is ever called, so a refusing bucket returned 502 on 100% of text-to-3D while image-to-3D, which supplies its own view URLs, kept working. A storage-*infrastructure* fault now falls back to an inline `data:` URI under 4 MB ([api/_lib/image-persist.js](../api/_lib/image-persist.js)). `backendAcceptsInlineViews()` names the lanes that can read one, and it is true for our own GPU workers and only them, because every `workers/model-*` declares `images: [data-uri|url]` while a third-party reconstructor takes a URL it fetches itself. A programming error or an oversized payload still throws.+3. **A refusal is reported as a refusal.** `/api/forge-upload` used to check only that the S3 env vars were *present*, so a rotated token still minted a well-formed presigned URL, the bucket answered the browser's PUT with a `403 SignatureDoesNotMatch` carrying no `Access-Control-Allow-Origin`, and the page fell into its catch-all "network error" branch for a fault that had nothing to do with the user's connection. `objectStorageUsable()` in `r2.js` runs the same probe, cached and single-flighted so a six-slot burst costs one, and both forge entry points answer `503 storage_unavailable` rather than forwarding a raw signing complaint.+4. **Reads fail over to the public domain.** When the signed read fails on infrastructure rather than on the object, [api/cdn-object.js](../api/cdn-object.js) **streams** the same key from the public bucket domain. It must stream and never redirect: `r2.dev` sends no `access-control-allow-origin`, a browser re-runs the CORS check on a redirect's target, and the wildcard grant this handler sets is discarded the moment the hop is followed (measured on 2026-09-09, every cross-origin `/cdn` read threw "Failed to fetch" while the same URL curled 200). Streaming keeps the response on three.ws so the CORS, CORP and content-type headers survive the degraded path, and a short 60 s edge cache absorbs a thumbnail burst instead of pointing every browser at the rate-limited public domain the route exists to dodge.++Note the asymmetry with rule 3: `objectStorageUsable()` fails closed only on a *rejected credential*, which never recovers on retry, and stays open through a timeout, so a flaky probe cannot take uploads down on its own.+### The delivery variant: what a phone downloads is not what a download gives youA raw generation is 1.25 to 3.5 MB of unquantized vertex data and embedded PNG skins. On a mid-tier phone over slow 4G (1.6 Mbps) that is ten to twenty seconds before the first frame, which is most of what made the model pages and the marketplace grid unusable on a handset.@@ -209,7 +224,7 @@ Workers are Python FastAPI services on Cloud Run (scale-to-zero L4 GPUs unless n| `workers/model-triposr/` | TripoSR fast path and fallback (5 to 15s). || `workers/rig/` | Make-It-Animatable rigging: 52-bone Mixamo skeleton, skin weights, ARKit-52 blendshapes, sub-second GPU predict, grafted into the original GLB bytes. Replaced the retired `workers/unirig/` (2026-07-17); cutover was the `GCP_UNIRIG_URL` env change. || `workers/avatar-pipeline-controller/` | CPU orchestrator for the avatar flow: `POST /reconstruct` picks a mesh backend by weighted random, then auto-rigs. |-| `workers/remesh/`, `workers/texture/`, `workers/segment/`, `workers/stylize/`, `workers/rembg/` | Post-processing: retopology and Game-Ready, SDXL retexture, part splitting, geometric stylize, background removal. |+| `workers/remesh/`, `workers/texture/`, `workers/segment/`, `workers/stylize/`, `workers/rembg/` | Post-processing: retopology and Game-Ready, SDXL retexture, part splitting, geometric stylize, background removal. `rembg` also offers `birefnet` (birefnet-general-lite) for cutouts where hair and thin edges decide the mesh: roughly 6 s against the default's 1 s, so it is worth it on a hero image and not on a batch, and the default is deliberately unchanged. |Model weights are staged from `gs://three-ws-model-weights` via `workers/deploy/stage-weights.sh`. Each worker has its own `cloudbuild.yaml`; every config pins the `three-ws-build@` service account.diff --git a/docs/free-crypto-apis.md b/docs/free-crypto-apis.mdindex 6881a1835..a30ec1fbb 100644--- a/docs/free-crypto-apis.md+++ b/docs/free-crypto-apis.md@@ -14,8 +14,8 @@ These need no new vendor relationship. Either the credential slot already exists| Provider | Status in repo | What finishing it buys || --- | --- | --- |-| DeBank Open API | `DEBANK_ACCESS_KEY` / `DEBANK_API_KEY` declared in `.env.example`, zero code readers | Multi-chain wallet portfolio + DeFi positions for any EVM address. Either wire it or delete the dead vars. |-| Etherscan gas oracle | We already hold `ETHERSCAN_API_KEY`; only the contract-creation endpoint is called | Free EVM gas recommendations (safe/proposed/fast) via the V2 multichain API we already use. |+| DeBank Open API | `DEBANK_ACCESS_KEY` declared in `.env.example`, zero code readers | Multi-chain wallet portfolio + DeFi positions for any EVM address. Either wire it or delete the dead var. |+| Etherscan gas oracle | Done: it is the last rung of the gas chain behind `/api/v1/gas` (`api/_lib/gas-oracles.js`) | Free EVM gas recommendations (safe/proposed/fast) via the V2 multichain API we already use. || Alchemy NFT + Token APIs | `ALCHEMY_API_KEY` already funds our RPC lanes | NFT metadata/ownership and token balances on the same free compute units. No new signup. || CryptoPanic | Named in the `api/news/archive.js` docstring, never called | Aggregated crypto news with votes/sentiment. Free developer tier, API key. Would slot into the news pipeline as a structured source next to RSS. || Helius DAS extras | Helius key already live | Webhooks are used; the free tier also covers priority-fee estimates and enhanced transaction parsing we do not call yet. |@@ -114,7 +114,7 @@ Jupiter owns the Solana lane. For the EVM x402/trade surfaces there is no aggreg| --- | --- | --- | --- || RugCheck | Free (Solana) | No | See Solana section; highest-fit item in this file. || Honeypot.is | Free | No | EVM honeypot simulation (can you sell after you buy). Complements GoPlus flags on BSC/Base tokens. |-| GoPlus authenticated tier | Free app key | Yes | We call GoPlus keyless today; `GOPLUS_APP_KEY`/`GOPLUS_APP_SECRET` sit unused in `.env.example`. Signing up raises rate limits at zero cost, or the vars should be deleted. |+| GoPlus authenticated tier | Free app key | Yes | We call GoPlus keyless today, and the unused `GOPLUS_APP_KEY`/`GOPLUS_APP_SECRET` slots have since been dropped from `.env.example`. Signing up raises rate limits at zero cost, and would mean declaring the pair again. |## News, sentiment, and events@@ -140,7 +140,7 @@ Jupiter owns the Solana lane. For the EVM x402/trade surfaces there is no aggreg## Suggested adoption order-1. Zero-cost cleanups: wire or delete the dead DeBank and GoPlus env vars; call the Etherscan gas oracle and Alchemy NFT endpoints our existing keys already pay for.+1. Zero-cost cleanups: wire or delete the dead `DEBANK_ACCESS_KEY` var (the GoPlus pair is already gone); call the Alchemy NFT endpoints our existing key already pays for.2. Solana product fit: RugCheck in the oracle/sniper risk path; Solscan Pro or Shyft as a Helius-relief lane; Tensor or Magic Eden if any NFT surface ships.3. Resilience rungs: Binance + OKX public tickers in `market-fallbacks.js`; CoinMarketCap and CoinCap as listing fallbacks; Coin Metrics for fundamentals.4. New capability: CoinGlass (derivatives breadth), Dune (any-metric API), CoinMarketCal (forward-looking events), CryptoPanic (structured news), a keyless EVM swap-quote rung (ParaSwap or KyberSwap).diff --git a/docs/guards.md b/docs/guards.mdindex 339ffa1a8..93bc33341 100644--- a/docs/guards.md+++ b/docs/guards.md@@ -135,7 +135,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. |+| Documentation integrity | `npm run audit:docs` | No dead relative link, no site link that matches no route, no command naming a missing script, no `packages/*` or `workers/*` directory without a README, and no public doc that is live but unregistered in `data/pages.json` (or declared there with no article behind it). || 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`. || Home lane translation keys | `npm run i18n:home` | Every string the connected home speaks from JS has a key in `public/locales/en.json` whose English matches the code exactly, and no source value bakes a user's own room or device name into a translatable sentence. |diff --git a/docs/home-households.md b/docs/home-households.mdindex 555d05f0a..1f4f5c5d0 100644--- a/docs/home-households.md+++ b/docs/home-households.md@@ -133,9 +133,9 @@ membership-aware at once rather than each one growing its own check.|---|---|---|| Store reads | `api/_lib/home/store.js` | `getConnection`, `listConnections` and `getDecryptedToken` join `home_members`. Each row comes back carrying `role` and `entity_scope`. There is deliberately no `or user_id = ...` beside the join. || Bridge runtime | `api/_lib/home/runtime.js` | `acquire` reads the home and its token through those two store functions, so it inherits membership without a check of its own |-| REST routes | `api/_lib/home/access.js` | `resolveHomeAccess(req, res, homeId, capability)` is the single door. It returns `role` and `scope`, refuses a non-member 404 and a member without the capability 403 |+| REST routes | `api/_lib/home/access.js` | `resolveHomeAccess(req, res, homeId, capability)` is the single door. It returns `role` and `scope`, refuses a non-member 404 and a member without the capability 403. A bearer principal is held to the OAuth scope its capability maps to (`read` needs `home:read`, everything that changes the house, the roster, the layout or the allowances needs `home:act`), checked BEFORE the home is read so the refusal names the principal and not a house id || Room graph | `api/home/[id].js`, `api/home/[id]/stream.js` | `filterGraphForScope` runs before serialization, on the single read and on every streamed frame |-| The gate | `api/home/[id]/call.js` | `confirmed: true` from a role without `confirm` is refused before the socket is acquired, and an out-of-scope target is refused against the live graph |+| The gate | `api/home/[id]/call.js` | `confirmed: true` is refused before the socket is acquired, twice over: `canAssertConfirmation` refuses any principal that is not a signed-in browser session (a bearer token holding `home:act` can ask to act and can never say yes), then the role must hold `confirm`. An out-of-scope target is refused against the live graph || Scenes | `api/home/[id]/activate.js` | needs `act`; a scoped role is refused outright, because a scene reaches the whole house and a half-run scene is worse than none || Confirmation redemption | `api/home/[id]/confirm.js` | needs `confirm`; bearer principals are refused before authentication || Chat and MCP tools | `api/_lib/home/tools.js` | a bearer principal inherits the role of the account whose token it is, through `requireMembership` |@@ -219,8 +219,10 @@ silently a change to what they can do.Sending an invitation mails it. The email names the role and, for a guest, states in the body thatthey will never be able to approve unlocking a door, so somebody forwarding an invitation can see-they are handing over a guest seat and not the house. The link is shown in the UI either way, and-the response says whether the mail actually went out (`emailed`) rather than assuming: a platform+they are handing over a guest seat and not the house. The link is shown in the UI either way, in a+region the panel owns rather than in the part that re-renders, so refreshing the roster does not+wipe the only copy that will ever exist. The response says whether the mail actually went out+(`emailed`) rather than assuming: a platformthat mails the only copy of a one-use credential and then fails to deliver it has destroyedsomething the inviter cannot recreate. There is no way to see the link again afterwards, becausethe server keeps only a hash.@@ -281,7 +283,7 @@ curl -X POST https://three.ws/api/home/$HOME_ID/members \"invite": { "id": "...", "email": "[email protected]", "role": "guest","scope": { "mode": "allow", "areas": ["kitchen"], "entities": ["light.hall_lamp"] },"expires_at": "2026-09-10T03:31:52.462Z" },- "invite_url": "https://three.ws/home/join?invite=BBQFpFGdBbULN9KQUhbIfw0SiFA0DDbPx1iFFpx2Lng"+ "invite_url": "https://three.ws/smart-home/join?invite=BBQFpFGdBbULN9KQUhbIfw0SiFA0DDbPx1iFFpx2Lng"}```diff --git a/docs/home-security.md b/docs/home-security.mdindex 4094116ca..71666a191 100644--- a/docs/home-security.md+++ b/docs/home-security.md@@ -317,7 +317,10 @@ npx vitest run tests/home-security.test.js# command, and it is the only instance any live home test should use.eval "$(node scripts/home-test-instance.mjs --up --onboard --seed --name sec11 --env)"npx vitest run tests/home-security.test.js-node scripts/home-test-instance.mjs --down --name sec11+# --force because the teardown follows the run: since 2026-09-09 --down refuses a+# house any run took in the last 30 minutes, so a peer's live house cannot be+# removed out from under it by someone passing its lane name.+node scripts/home-test-instance.mjs --down --name sec11 --force```**The model half is a real requirement, not a nicety.** Check 4's real arm asks thediff --git a/docs/internal/fable-playbook.md b/docs/internal/fable-playbook.mdindex 7e42904dd..dce20ff39 100644--- a/docs/internal/fable-playbook.md+++ b/docs/internal/fable-playbook.md@@ -235,9 +235,13 @@ of the map is already a dependency.1. **Distribution beats features from here.** The platform out-builds itsawareness. `llms.txt`, the sitemap and the changelog rails exist; the missingpiece is the loop that turns every artifact into a share. Wire sharing into- artifacts (§3.3, §3.4) rather than adding surfaces. Note that the X lane is- retired and the toolkit that drove it is no longer vendored here: it lives at- `nirholas/XActions` and on npm (see `STRUCTURE.md`).+ artifacts (§3.3, §3.4) rather than adding surfaces. Note that the changelog's automatic X delivery+ stays retired and the toolkit that drove it is no longer vendored here: it+ lives at `nirholas/XActions` and on npm (see `STRUCTURE.md`). The X surface+ that does exist is the reviewed @trythreews content queue+ (`/api/cron/x-content` every 15 minutes, [docs/x-content-pipeline.md](../x-content-pipeline.md)),+ and it only previews: nothing is sent until an item is `approved` and+ `X_CONTENT_AUTO_PUBLISH=true` is set on the service, which it is not today.2. **Trust is a sellable feature.** We run a hash-chained economy ledger, breachmonitoring, risk-acknowledgment gating, spend guards, and fail-closed tradingrules. "Agents that touch real money, auditable by design" is positioningdiff --git a/docs/labor-market.md b/docs/labor-market.mdindex f1378bbb7..33a142f4f 100644--- a/docs/labor-market.md+++ b/docs/labor-market.md@@ -22,6 +22,15 @@ get paid in **$THREE** — settled on-chain through real escrow. Live atRead paths: `GET /api/labor/feed` (open bounties, in-flight jobs, settlementticker, market totals, `escrow_configured`) and `GET /api/labor/agent?agentId=…`.+Every leg that commits real funds is gated on the caller's signed real-funds+agreements: `POST /api/labor/post` (escrowing the reward), `POST /api/labor/award`+(committing that escrow to a worker), and a **poster-side**+`POST /api/labor/settle` (releasing its own escrow). An account with no current+signature gets `403 risk_ack_required` and nothing is escrowed, awarded or+released. Sign once at [/legal/agreements](https://three.ws/legal/agreements);+see [risk acknowledgment](./risk-acknowledgment.md). A worker settling a+delivered job to collect its own payout is not gated.+The escrow secret lives only on the server (`LABOR_ESCROW_SECRET_BASE58`). Theescrow wallet pays its own SOL fees on release and self-tops-up from the platformtreasury / `LABOR_ESCROW_GAS_SECRET` when low (see `api/_lib/labor-escrow.js`).diff --git a/docs/launch-usecases.md b/docs/launch-usecases.mdindex 8d61e167f..91121b57e 100644--- a/docs/launch-usecases.md+++ b/docs/launch-usecases.md@@ -80,9 +80,13 @@ blocking a launch:| `x:<handle>` | An X account, same resolver. || `wallet:<address or name.sol>` | A fixed Solana recipient. |-[`public/launch/launch.js`](../public/launch/launch.js) parses it, the launch-panel shows the routing on the form before the mint ("Creator fees route to-@deepseek-ai on GitHub"), and the moment the coin lands the post-launch+`/launch` itself was rebuilt on [`src/launch/launch-page.js`](../src/launch/launch-page.js),+which serves a Create tab and a My-coins tab. A `?reward=` visit is the one case+that bypasses both: the fee-split handoff belongs to the studio panel, so those+visits mount [`public/launch/launch.js`](../public/launch/launch.js) instead,+which is what parses the value. The launch panel shows the routing on the form+before the mint ("Creator fees route to @deepseek-ai on GitHub"), and the moment+the coin lands the post-launch[fees panel](../public/studio/fees-panel.js) mounts on the success screen withthat recipient already filled in at 100%. It is a draft, not an automatic write:the creator still reviews and signs the split, and a coin that already hasdiff --git a/docs/money-map.md b/docs/money-map.mdindex d18b46a05..be44627ea 100644--- a/docs/money-map.md+++ b/docs/money-map.md@@ -16,7 +16,7 @@ signer/funder wallets and how to fund them).Money-routing is deliberately **config-driven** — no receiver is hardcoded, so anunset receiver fails closed rather than silently routing real USDC to a baked-in-address ([env.js:808](../api/_lib/env.js#L808)).+address (the `X402_PAY_TO_*` getters in [env.js](../api/_lib/env.js)).### Receivers (inbound USDC)| Env var | Role | Value |@@ -39,7 +39,7 @@ address ([env.js:808](../api/_lib/env.js#L808)).| Env var | Fills from | Default rate || ------- | ---------- | ------------ || `MARKETPLACE_PLATFORM_FEE_WALLET` (→ platform treasury pubkey) | marketplace skill sales | `MARKETPLACE_PLATFORM_FEE_BPS` = **0** (off), ≤10% |-| `PUMP_PLATFORM_FEE_WALLET` (→ platform treasury pubkey) | pump trades | `PUMP_PLATFORM_FEE_BPS` = **0** (off), ≤5% |+| `PUMP_PLATFORM_FEE_WALLET` (→ platform treasury pubkey) | pump trades + coin launches | `PUMP_PLATFORM_FEE_BPS` = **100 (1%)**, ≤5%; `PUMP_LAUNCH_FEE_BPS` = **100 (1%)** on the dev buy, ≤5% |### Signer / funder walletsEvery engine signs from its **own** keypair; a single **funding root** tops those@@ -71,7 +71,8 @@ encodings, minimum balances, guards, funding tool — in the| `cosmetic-purchase` | platform receiver → split | 50% | creator 50% (≤90%) from `COSMETIC_SPLIT_TREASURY_*` || marketplace skill sale | agent owner `payout_address` | 0–10% fee | atomic split; fee → fee wallet || labor skill (escrow) | worker + author | author 10% royalty | paid from escrow ([labor-settle.js:97](../api/_lib/labor-settle.js#L97)) |-| pump trade | counterparty | 0–5% fee | fee appended to trader's tx |+| pump trade | counterparty | **1%** | fee transfer appended to the trader's own tx (SOL, or USDC on a USDC-paired coin) |+| coin launch dev buy (`/launch`) | the bonding curve | **1%** of the dev buy | fee transfer inside the launch tx; no dev buy, no fee || `pump-launch` | `X402_PAY_TO_SOLANA/BASE` | 100% of $5 | pump.fun creator rewards accrue on-chain to nominated wallet || `ring-settle` (internal) | `X402_PAY_TO_SOLANA` | 100% | recirculates (dogfood volume) || vanity bounty | worker | escrow-based | from `VANITY_BOUNTY_PAYOUT_KEY` (→ club treasury fallback) |@@ -91,19 +92,23 @@ in the platform receiver first, then a separate treasury forwards a share| Cosmetic creator split | creator share | `cosmetics-economy.js` `DEFAULT_CREATOR_BPS` | **50%** (cap 90%) || Labor skill royalty | author royalty | `LABOR_SKILL_ROYALTY_BPS` | **10%** (cap 50%) || Marketplace platform fee | platform cut | `MARKETPLACE_PLATFORM_FEE_BPS` | **0%** (cap 10%) |-| Pump trade fee | platform cut | `PUMP_PLATFORM_FEE_BPS` | **0%** (cap 5%) |+| Pump trade fee | platform cut | `PUMP_PLATFORM_FEE_BPS` | **1%** (cap 5%) |+| Coin launch fee | platform cut on the dev buy | `PUMP_LAUNCH_FEE_BPS` | **1%** (cap 5%) || Club tip | dancer share | — | **100%** to dancer (platform nets 0) || Club cover | platform share | — | **100%** (club float) |-All defaults are a low/off demo curve; production deployments tune them to real-unit economics.+The trade and launch fees are live at 1% (owner decision, 2026-09-16): every+customer trade three.ws builds or signs pays it in the same transaction, and+platform-owned agents are exempt. The rest are a low/off demo curve; production+deployments tune them to real unit economics. Detail, surfaces and disclosure:+[pump platform fee](pump-platform-fee.md).---## 4. Services catalog (what three.ws sells)-- **x402 HTTP endpoints**: 80+ paid endpoints (81 distinct paid routes in the- [ring catalog](../api/_lib/x402/ring-catalog.js), the single source of truth)+- **x402 HTTP endpoints**: 86 distinct paid routes in the+ [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](x402-endpoints.md).diff --git a/docs/notifications.md b/docs/notifications.mdindex cef47ccae..2a76805c4 100644--- a/docs/notifications.md+++ b/docs/notifications.md@@ -56,30 +56,41 @@ than naming a coin.## Categories: how the filter tabs group types-The `/notifications` page has eight tabs: **All**, **Sales & earnings**,+The `/notifications` page has nine tabs: **All**, **Sales & earnings**,**Purchases**, **Social**, **In person**, **Market alerts**, **Creations**,-and **Account**. Each notification type maps to exactly one category; the-mapping (`TYPE_CATEGORY`) lives in+**Companion**, and **Account**. Each notification type maps to exactly one+category; the mapping (`TYPE_CATEGORY`) lives in[api/_lib/notify-prefs.js](../api/_lib/notify-prefs.js) and is mirrored in[src/notifications-page.js](../src/notifications-page.js) for tab filtering.| Category (tab) | Key | Notification types ||---|---|---|| Sales & earnings | `sales` | `skill_purchased`, `asset_purchased`, `sale`, `payment-earned`, `payment_received`, `referral_earned`, `referral_signup`, `referral_reward`, `pump_launch_filled`, `royalty_paid` |-| Purchases | `purchases` | `skill_purchase_confirmed`, `asset_purchase_confirmed`, `skill_gift_received`, `skill_gift_sent` |+| Purchases | `purchases` | `skill_purchase_confirmed`, `asset_purchase_confirmed`, `skill_gift_received`, `skill_gift_sent`, `print_update` || Social | `social` | `remix`, `reply`, `comment`, `embed`, `mention`, `fork`, `follow`, `dm_received`, `agent_review`, `quest_complete` || In person | `irl` | `irl_interaction`, `irl_reply` || Market alerts | `alerts` | `pump_alert` || Creations | `creations` | `forge_complete`, `forge_failed` |+| Companion | `companion` | `companion_delivery` |+| (no tab yet) | `knock` | `knock_received` || Account | `account` | `withdrawal_completed`, `withdrawal_failed`, `payment_mismatch`, `asset_payment_mismatch`, `skill_payment_mismatch`, `security_alert`, `wallet_anomaly_frozen`, plus any type not in the map |-Two details worth knowing:+`print_update` is the single type Materialize uses for a physical order's whole+lifecycle, quoted through delivered, and it sits with purchases because the+order is the buyer's own.++Three details worth knowing:- **Unmapped types fall back to `account`**, so a newly added notificationtype is never silently undeliverable or unfilterable.- **Tab filtering is client-side** over the pages already fetched. The API'sown `?type=` parameter filters server-side by a single exact type (e.g.`?type=pump_alert`), not by category.+- **`knock` is a preference category without a tab.** The preference center+ lists it ("Knocks at your door") and the server gates delivery on it, but+ the page's own copy of the map has no entry for `knock_received`, so on+ `/notifications` a knock is filtered under **Account** rather than a tab of+ its own.## The avatar channel: delivered in person@@ -92,12 +103,15 @@ loud, with a link straight to the thing that happened.`telegram`. It is gated by the same per-category matrix, edited in the sameplace (`/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+**What gets announced.** By default: **Sales & earnings**, **Creations**,+**Companion deliveries**, **Knocks at your door**, and **Account**. Money+landing, a generation finishing while you waited, a message your companion+triaged as worth hearing, someone who paid your price to reach you, andanything 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.+at all) is two clicks away. The defaults live in `DEFAULTS` in+[api/_lib/notify-prefs.js](../api/_lib/notify-prefs.js).**When it stays quiet.** The rules live in[src/notification-herald.js](../src/notification-herald.js):diff --git a/docs/nvidia-models.md b/docs/nvidia-models.mdindex 77d4774f0..9ad1dec5d 100644--- a/docs/nvidia-models.md+++ b/docs/nvidia-models.md@@ -32,11 +32,11 @@ Because it is one key for everything, a deployment either has the whole NVIDIA l| --- | --- | --- | --- || **Text → 3D** | `microsoft/trellis` | `api/_providers/nvidia.js`, `api/_lib/forge-tiers.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) | ✅ |-| **Reranking** | `nvidia/rerank-qa-mistral-4b` | `api/_lib/rerank.js` | ✅ |+| **LLM (default lane)** | `nvidia/nemotron-3-super-120b-a12b` (compact rung: `nvidia/nemotron-3.5-lightning-30b-a3b`) | `api/_lib/llm.js`, `api/_lib/chat-models.js` | ✅ |+| **LLM (model garden)** | Nemotron 3 Super 120B / Ultra 550B / 3.5 Lightning 30B, DeepSeek V4 Pro, Kimi K2.6, MiniMax M2.7 | `api/brain/chat.js` | ✅ |+| **Vision / VLM** | `meta/llama-3.2-11b-vision-instruct`, then free OpenRouter `:free` VLM rungs | `api/_lib/vision.js` | ✅ |+| **Embeddings** | `nvidia/nemotron-3-embed-1b` | `api/_lib/embeddings.js` (and `api/agents/_id/embed.js`, which delegates to it) | ✅ |+| **Reranking** | `nvidia/rerank-qa-mistral-4b` (pin verified dead, stage off by default) | `api/_lib/rerank.js` | ✅ || **Content safety** | `nvidia/llama-3.1-nemoguard-8b-content-safety`, `meta/llama-guard-4-12b` | `api/_lib/publish-safety.js` | ✅ || **Text-to-speech** | `magpie-tts-multilingual` (Riva) | `api/_lib/tts-nvidia.js` | ✅ |@@ -86,10 +86,10 @@ NVIDIA NIM hosts 100+ open-weight chat models behind the one key, all OpenAI-com### 3a. The default production lane-**Model:** `nvidia/nemotron-3-super-120b-a12b` (with `nvidia/nemotron-3-nano-30b-a3b` as the compact Nemotron rung)+**Model:** `nvidia/nemotron-3-super-120b-a12b` (with `nvidia/nemotron-3.5-lightning-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). 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.+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, and every NVIDIA-routed id again on 2026-09-10 after a sweep of `GET /v1/models` on the live account found most of them answering `410 Gone`. A dead id is worse than a missing one: a fallback chain treats a 410 like a rate limit and moves on, so nothing logged an outage while each dead entry burned one of the chain's few retry slots. The rungs 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 (the opt-in compact rung moved off `nemotron-3-nano-30b-a3b`, which NIM stopped serving, to `nemotron-3.5-lightning-30b-a3b`), 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.@@ -99,15 +99,15 @@ This lane powers the platform's built-in AI surfaces — chat, embedded site wid| Brain label | Model id | Tier | What it's for || --- | --- | --- | --- |-| Nemotron 3 Super 120B | `nvidia/nemotron-3-super-120b-a12b` | flagship | NVIDIA's flagship Nemotron MoE — strong agentic reasoning |-| Llama-Nemotron Super 49B | `nvidia/llama-3.3-nemotron-super-49b-v1.5` | reasoning | Nemotron reasoning tuned on Llama 3.3 — math, code, planning |-| Nemotron Nano 9B | `nvidia/nvidia-nemotron-nano-9b-v2` | balanced | Compact Nemotron with built-in reasoning — strong quality per token |+| Nemotron 3 Super 120B | `nvidia/nemotron-3-super-120b-a12b` | flagship | NVIDIA's flagship Nemotron MoE, strong agentic reasoning |+| Llama-Nemotron Super 49B | `nvidia/nemotron-3-ultra-550b-a55b` | reasoning | Deepest Nemotron reasoning rung: math, code, planning |+| Nemotron Nano 9B | `nvidia/nemotron-3.5-lightning-30b-a3b` | balanced | Compact Nemotron with built-in reasoning, strong quality per token || DeepSeek V4 Pro | `deepseek-ai/deepseek-v4-pro` | reasoning | Deep reasoning, hosted on NIM || Kimi K2.6 | `moonshotai/kimi-k2.6` | flagship | Moonshot long-context agentic model |-| Llama 4 Maverick | `meta/llama-4-maverick-17b-128e-instruct` | balanced | Meta's 128-expert MoE — fast, multimodal-capable |+| Llama 4 Maverick | `nvidia/nemotron-3-super-120b-a12b` | balanced | Meta's Maverick left the account's catalog; the slot now serves Nemotron 3 Super || 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. 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.+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 three picker labels above are the Brain's own UI strings and were not renamed when the ids under them were re-pinned on 2026-09-10, so the id column is the one to trust. The routing catalog in `chat-models.js` lists `nvidia/nemotron-3-super-120b-a12b`, `nvidia/nemotron-3.5-lightning-30b-a3b`, and `nvidia/nemotron-3-ultra-550b-a55b` as the tool-capable NVIDIA models, and the Brain's own fallback chain appends `nvidia/nemotron-3.5-lightning-30b-a3b` 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.@@ -115,10 +115,10 @@ For anonymous (signed-out) callers, only the genuinely free tiers (the OpenRoute## 4. Vision / VLM — image understanding-**Models (in order):** `nvidia/nemotron-nano-12b-v2-vl` → `meta/llama-3.2-11b-vision-instruct`+**Model on NIM:** `meta/llama-3.2-11b-vision-instruct`**Source:** [api/_lib/vision.js](../api/_lib/vision.js).-Two free NIM vision lanes on the OpenAI-compatible chat host. Nemotron Nano VL leads because it carries the **smallest image-token footprint** (~281 prompt tokens for a small image vs ~1600 for a 90B-class model); the Llama 3.2 11B vision model is a different family, so its failure modes are independent — a true fallback, not a retry. Images pass as an http(s) URL (the model server fetches it) with SSRF validation on the URL before it leaves the box.+One free NIM vision lane on the OpenAI-compatible chat host. `nvidia/nemotron-nano-12b-v2-vl` used to lead it for its small image-token footprint; NVIDIA retired that model on 2026-08-26 and the host now answers every request for it with a hard `410`, so it was removed on 2026-09-08 rather than swapped, because probing the catalog for a replacement free NIM VLM needs a live key. Behind the NIM rung sit free OpenRouter `:free` VLM routes (Gemma 4, Ling 3.0 Flash VL, Nemotron Nano Omni and others), then Cloudflare Workers AI, Vertex Gemini, and the paid OpenAI backstop; the OpenRouter rung was added on 2026-09-09 after NVIDIA, OpenAI, and both Google routes failed in the same request and took every image-judging feature down at once. Only `:free` ids are listed there, because the spend ledger prices OpenRouter by that exact suffix. Images pass as an http(s) URL (the model server fetches it) with SSRF validation on the URL before it leaves the box.**Where it's used:**- **Forge photo pre-check** — before a generation slot is spent, the uploaded photo is screened: a screenshot of text, a cluttered subject-less scene, or a too-dark image gets a heads-up and a fix (with a one-click "Generate anyway").@@ -127,16 +127,18 @@ Two free NIM vision lanes on the OpenAI-compatible chat host. Nemotron Nano VL lAll 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.+The chain is budgeted and remembers what hurt. Each attempt takes whatever remains on the caller's deadline minus a reserve for the next rungs (`laneAttemptTimeout`, never below 3.5 s, reserving for at most two further lanes), so the lane in hand spends the budget nobody else needs yet while every remaining rung keeps its floor. Dividing the deadline evenly instead starved the lane most likely to answer once the chain grew past a handful of rungs, 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-**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`).+**Primary:** `nvidia/nemotron-3-embed-1b` (2048-dim) · **Endpoint:** `integrate.api.nvidia.com/v1/embeddings`+**Source:** [api/_lib/embeddings.js](../api/_lib/embeddings.js) (tag `nvidia/nemotron-3-embed-1b@2048`).-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.+`nv-embedqa-e5-v5` held this slot until NVIDIA ended its life on 2026-08-25. Its tag stays in the registry as `NIM_EMBED_TAG_RETIRED`, resolvable forever so vectors written in that space still read back, but reporting unconfigured so it is never picked for new work. Vectors are stored as `jsonb`, so the dimension change needed no migration.++The default embedder for new vectors: **free with the one key, 2048 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.@@ -147,7 +149,7 @@ The default embedder for new vectors: **free with the one key, 1024 dimensions,**Model:** `nvidia/rerank-qa-mistral-4b` · **Endpoint:** `ai.api.nvidia.com/v1/retrieval/nvidia/reranking`**Source:** [api/_lib/rerank.js](../api/_lib/rerank.js).-Cosine-over-embeddings recall is cheap but coarse. This **cross-encoder reranker** re-scores the top passages so the most relevant context leads. It is **opt-in** (`KNOWLEDGE_RERANK_ENABLED=1` plus the NVIDIA key) and **strictly fail-open** — any rerank error keeps the original cosine ordering. Reranking may improve retrieval but may never break it. Used to refine knowledge-widget answers.+Cosine-over-embeddings recall is cheap but coarse. This **cross-encoder reranker** re-scores the top passages so the most relevant context leads. It is **opt-in** (`KNOWLEDGE_RERANK_ENABLED=1` plus the NVIDIA key) and **strictly fail-open**: any rerank error keeps the original cosine ordering. The 2026-09-10 catalog sweep found this model dead on the account and it is deliberately left pinned: the stage is off in production and fails open by contract, so a pin verified dead beats an unverified guess. Turning the stage on means re-pinning it against a live catalog first. Reranking may improve retrieval but may never break it. Used to refine knowledge-widget answers.---diff --git a/docs/object-library.md b/docs/object-library.mdindex ef307acb7..a116c5ea9 100644--- a/docs/object-library.md+++ b/docs/object-library.md@@ -17,7 +17,7 @@ Objects are props, not agents: opening one in the viewer uses object mode, which## Using the gallery-Each card renders the object live in an auto-rotating `<model-viewer>` (with the pre-rendered thumbnail as the poster) and offers three actions:+Each card shows the pre-rendered thumbnail and offers three actions. A card stays a still image until you dwell on it (or tab into it), at which point that one card upgrades to a live, auto-rotating `<model-viewer>`; at most six stay mounted at a time, and a card with no rendered thumbnail upgrades as soon as it scrolls into view. Sweeping the pointer across a row never starts a download, because the upgrade waits on hover intent rather than the first `pointerover`.| Button | Destination | What you get ||---|---|---|@@ -27,15 +27,16 @@ Each card renders the object live in an auto-rotating `<model-viewer>` (with theGallery controls:-- **Category chips** above the grid filter by category (furniture, lighting, tools, and so on), derived live from the manifest. "All" clears the filter.-- **Search** matches names and tags; press `/` anywhere on the page to focus the search box.+- **Category chips** above the grid filter by category (furniture, lighting, tools, and so on), derived live from the manifest. A source catalog's own `collection:` labels are not browsing categories, so they are excluded from the chips. "All" clears the filter.+- **Search** matches names, tags, and categories; 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).- The whole manifest is fetched once and filtered client-side, so chips, search, and sort are instant.-- 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.+- The grid renders 48 cards at a time behind a **Load more** button, which an `IntersectionObserver` also trips as you approach it. A live region above the grid announces the running tally ("48 of 511 shown") after every chunk. Mounting a viewer per entry is what made this page take 18 seconds to its first interactive card.+- 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, and a failed load names the actual reason beside its retry button.## 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](./character-library.md), 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](./character-library.md) exactly, with `objects` in place of `avatars`.+Public, no authentication, `GET` and `OPTIONS` only (`HEAD` is answered like `GET`). CORS is open (`Access-Control-Allow-Origin: *`), so a browser `fetch` from any origin works: the manifest is a CC0 index with no caller data in it, and the GLBs it points at already load cross-origin through `/cdn/<key>`. That is what lets an embedded [AR Studio](./ar-studio.md) on someone else's site render the object tray, not just the models in it. 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](./character-library.md) exactly, with `objects` in place of `avatars`.### Query parameters@@ -76,6 +77,8 @@ Each entry in `objects`:Before the manifest is first uploaded, the endpoint returns `{ "objects": [], "total": 0 }` rather than an error, so consumers feature-detect by emptiness. A storage outage degrades the same way, but that response carries `Cache-Control: no-store` instead of the 300s edge cache, so the library reappears the moment storage recovers rather than staying empty for the rest of the cache window.+The manifest read itself has a second path before it gets there. `getPublicObjectBuffer()` reads the key over the signed S3 connection first, and on any failure refetches the same key from the public CDN domain, because a CC0 manifest is public data either way. A rejected or rotated storage credential therefore cannot empty the catalog. Only both paths failing produces the empty response, and it rethrows the *signed* error, so a genuine `NoSuchKey` still means "not published yet" rather than a transport fault.+### Example```bashdiff --git a/docs/onboarding-tier.md b/docs/onboarding-tier.mdindex 03a0225c3..1fadf7d63 100644--- a/docs/onboarding-tier.md+++ b/docs/onboarding-tier.md@@ -8,7 +8,7 @@ promise (make a 3D avatar, give it a brain, put it on your site) was competing fattention with a trading terminal.The onboarding tier fixes that without deleting anything. A first-time visitor gets-the **lite** tier: the ~28 destinations and the handful of homepage sections that+the **lite** tier: the ~30 destinations and the handful of homepage sections thatcarry the core journey. Everything else is one click away behind a labelled control,and once a visitor asks for it, it stays open on every page and every visit.@@ -20,9 +20,9 @@ and once a visitor asks for it, it stays open on every page and every visit.| Surface | Lite tier | Full tier || --- | --- | --- |-| Nav menus | Build, Discover, Learn (~28 links) | + Launch (~119 links in all) |+| Nav menus | Build, Discover, Learn (~30 links) | + Launch (~126 links in all) || Homepage | Hero, start path, Forge, embed demo, the three doors, community, pose, AR, showcase | + trading, capabilities grid, token economy, live economy, Oracle, pay-per-call, developer platform, the stack |-| Mobile drawer | the same ~28 destinations in one flat list | all ~119 |+| Mobile drawer | the same ~30 destinations in one flat list | all ~126 |Directly under the homepage hero sits the **start path**: three steps, each with anhonest time estimate, in the order the product actually works.diff --git a/docs/onchain-agents.md b/docs/onchain-agents.mdindex 9dac38cfb..07d619843 100644--- a/docs/onchain-agents.md+++ b/docs/onchain-agents.md@@ -102,7 +102,7 @@ So ~0.05 SOL canaries a handful; **~0.007 × N** covers a fleet of N (≈ 13 SOLTwo layers, both real:- **Off-chain manifest** (`buildAgentManifest`) — a superset of the Metaplex token-metadata standard and `agent-manifest/0.1`: name, image (avatar thumbnail), `animation_url` (the GLB body), `external_url` (the agent's three.ws page), attributes, the platform brand block, and the `$THREE` link. Pinned to **IPFS via Pinata** (`PINATA_JWT`) → falls back to web3.storage → falls back to R2 with a real CIDv1. Never a stub.-- **On-chain Attributes plugin** (`buildAgentOnchainAttributes`) — a curated ~11-pair subset written into the asset account itself: `platform`, `url`, `agent`, `agent_url`, `x`, `github`, `$THREE`, `$THREE_url`, `standard`, `schema`, `created`. Byte-clamped to keep the whole transaction under Solana's 1232-byte limit.+- **On-chain Attributes plugin** (`buildAgentOnchainAttributes`): a curated ~12-pair subset written into the asset account itself: `platform`, `url`, `agent`, `agent_url`, `x`, `github`, `$THREE`, `$THREE_url`, `standard`, `schema`, `skills`, `created` (`agent_url`, `skills` and `created` only when the agent has them). Byte-clamped to keep the whole transaction under Solana's 1232-byte limit.---diff --git a/docs/ops/cron-auth.md b/docs/ops/cron-auth.mdindex b9bfc12d7..768f61bf8 100644--- a/docs/ops/cron-auth.md+++ b/docs/ops/cron-auth.md@@ -49,11 +49,16 @@ so an audience match alone authenticates nobody. The token must carryin `CRON_OIDC_AUDIENCE`. With either var unset the OIDC path is off and only thesecret is accepted.-| Var | Value in production | Effect |+| Var | Value to set | Effect ||---|---|---|| `CRON_OIDC_AUDIENCE` | the Cloud Run service URL | audiences the edge will accept, comma-separated || `CRON_OIDC_SERVICE_ACCOUNT` | `[email protected]` | service-account emails the edge will accept, comma-separated |+Neither var is set on `three-ws-api` today, so the OIDC path is currently off and+the edge accepts only `CRON_SECRET`; the live Cloud Scheduler jobs still+authenticate with `Authorization: Bearer $CRON_SECRET`. The runbook below is the+step that turns the second credential on, and it has not been run yet.+The one case where the edge stands aside is "no credential configured at all"(no `CRON_SECRET`, no OIDC pair), which is a developer's machine: the requestfalls through so `requireCron` owns the single canonical 503. Production alwaysdiff --git a/docs/ops/forge-error-triage.md b/docs/ops/forge-error-triage.mdindex c336b2962..2c8d0f221 100644--- a/docs/ops/forge-error-triage.md+++ b/docs/ops/forge-error-triage.md@@ -22,7 +22,13 @@ and it answers a different question. It looks at a fixed **6 hour** window andreturns `unknown` below **15 attempts**, because it is tuned to page on a burstof failures and must not page on a quiet afternoon. At forge's real volume thatwindow is regularly too small to judge at all, so "is generation healthy?" often-answers `unknown` while a failure class has been recurring all week.+answers `unknown` while a failure class has been recurring all week. The sensor+also carries a stall check (`classifyForgeStall`) that this report cannot: a+failure upstream of the `forge_creations` row writes no rows at all, and a+ledger with nothing in it is exactly what a quiet afternoon looks like here.+`down` with `stalled: true` means generations have stopped *starting*, so read+the rest of the healthz payload (`object_storage` first) before opening this+report at all.Triage needs the other question: over the last week, which class recurs most, onwhich lane, and what does the message actually say? That is this report.@@ -145,6 +151,23 @@ recovery accounting above matters more than the raw count.and the same reaper in `model-hunyuan3d` and `model-triposg`). On NVIDIA it is`NVCF request not found or expired`. Check the recovered count before treatinga spike as user-visible.+- **`out_of_memory`** on a self-hosted lane is usually the GPU, not the prompt.+ Torch's caching allocator holds freed blocks in reserve and nvdiffrast+ allocates outside that cache, so an instance's usable VRAM only ever shrank:+ `model-trellis` served 1,189 generations on 2026-09-06 and then, after a+ restart on 2026-09-09, succeeded at exactly thirteen jobs and failed every+ single one after them with `Cuda error: 2[cudaMalloc(&m_gpuPtr, bytes);]` out+ of `postprocess_mesh`, while its health check kept passing and Cloud Run kept+ routing to it. The worker now hands a job's GPU memory back before it releases+ the inference semaphore, so a *recurring* OOM class on that lane is a new+ fault, not the old one.+- **A lane failing every job it accepts** is the shape to check `/health` for+ rather than the ledger. `model-trellis` retries a failed model load+ (`MODEL_LOAD_ATTEMPTS`, default 4, backing off from+ `MODEL_LOAD_RETRY_BASE_S`), and once that budget is spent the error latches+ and `/health` answers `503 ok:false` with `load_error` and `load_attempts`, so+ the instance is drained and recycled instead of staying resident. A latched+ load used to read as healthy.- **`upstream_5xx`, `rate_limited`, `unauthorized`, `payment_required`** are allvendor-side and resolve on the vendor's dashboard or in the env, not in code.See [production-log-triage.md](production-log-triage.md) for the samediff --git a/docs/ops/home-operations.md b/docs/ops/home-operations.mdindex acea3709a..1563efb54 100644--- a/docs/ops/home-operations.md+++ b/docs/ops/home-operations.md@@ -986,9 +986,15 @@ from home_connectionswhere user_id = '<user id>' and revoked_at is null;```-`status_detail` is written by the runtime on every failed handshake and is meant-to be read verbatim to the user. Then run the correlation query: if they are the-only one, it is their house. The usual causes, in order: the instance is off,+`status_detail` is written by the runtime on every failed handshake, and since+2026-09-10 on every mid-connection transition too: a pooled socket that dies+while checked out now writes `unreachable` from the bridge's own `disconnected`+event, and `connected` again on `reconnected`, so a stopped house stops reading+Live on the card. Only real transitions are written, so a flapping house does not+buy a round trip per event. It is meant to be read verbatim to the user.++Then run the correlation query: if they are the only one, it is their house.+The usual causes, in order: the instance is off,their remote https URL stopped resolving, their reverse proxy certificateexpired, or they are on a LAN-only install and never had a reachable URL (inwhich case they need the three.ws add-on, not a fix).diff --git a/docs/ops/play-store-developer-page.md b/docs/ops/play-store-developer-page.mdindex e21e2b774..e8df321bc 100644--- a/docs/ops/play-store-developer-page.md+++ b/docs/ops/play-store-developer-page.md@@ -8,8 +8,19 @@ hand. Regenerate the images with:npm run build:play-assets```-That runs [`scripts/render-play-assets.mjs`](../../scripts/render-play-assets.mjs)-and writes both files into `public/brand/play/`.+That runs [`scripts/render-play-assets.mjs`](../../scripts/render-play-assets.mjs),+which writes four images to two destinations. The developer-page pair is brand+material and lands in `public/brand/play/`; the store-listing pair+(`icon-512.png`, `feature-1024x500.png`) lands in+`solana-mobile/publish-play/media/`, under the exact filenames+[`solana-mobile/publish-play/config.yaml`](../../solana-mobile/publish-play/config.yaml)+names, so the listing worksheet never points at a file that does not exist. Pass+`--out=<dir>` to send all four to one directory instead, which is what to use+for a throwaway preview:++```bash+node scripts/render-play-assets.mjs --out=/tmp/play+```## What Play asks for, and what to upload@@ -52,8 +63,8 @@ Play rejects an upload outright when a constraint is missed, and the two easyones to miss are both invisible in a preview:- **24-bit, not transparent.** A PNG written by a canvas is always 32-bit RGBA,- so the alpha channel has to be stripped deliberately. Both files are asserted- to be 3-channel before they are written.+ so the alpha channel has to be stripped deliberately. All four files are+ asserted to be 3-channel before they are written.- **1 MB ceiling.** Asserted on the actual byte length, not estimated.Dimensions are asserted too. A wrong file fails in the terminal instead of indiff --git a/docs/ops/search-indexing.md b/docs/ops/search-indexing.mdindex 63a038f87..7a6eb50f3 100644--- a/docs/ops/search-indexing.md+++ b/docs/ops/search-indexing.md@@ -166,15 +166,39 @@ every page under them already carried `<meta name="robots" content="noindex">`.A crawler that is not allowed to fetch the page never sees the noindex, so theURL stays in the index as a bare link. The two directives cancel each other out.-Crawling is what removes them, so those three prefixes are now open in-robots.txt and the `noindex` does the work. `pages/dashboard-next/data-api.html`,-`developers.html` and `billing.html` were missing the tag and now carry it.+Crawling is what removes them, so those three prefixes are now open to+`User-agent: *` in robots.txt and the `noindex` does the work.+`pages/dashboard-next/data-api.html`, `developers.html` and `billing.html` were+missing the tag and now carry it. They stay disallowed for one group only, the+assistants that fetch on behalf of a live user (ChatGPT-User, Claude-User,+Perplexity-User and their siblings), because those do not index and the point+there is to keep a signed-in surface out of an assistant's reach, not out of a+SERP.**Rule: pick one.** `Disallow` keeps a page out of the crawl; `noindex` keeps itout of the index. Never both on the same URL.---+## Truncated Unicode breaks structured data++A page can be served perfectly and still be dropped for a reason that never+shows up as an indexing state. The news archive trimmed a publisher description+to 240 UTF-16 code units with a plain `slice()`. A summary opening with an emoji+got cut between the halves of a surrogate pair, `JSON.stringify` wrote the+surviving half into the story page's JSON-LD as a literal `\ud83d` escape, and+Search Console rejected the page with "Unparsable structured data: truncated+Unicode character" and pulled it from rich results (2026-09-06).++[`api/_lib/safe-text.js`](../../api/_lib/safe-text.js) is the fix: it truncates+on `Intl.Segmenter` grapheme boundaries, so a flag, a skin-tone modifier or a ZWJ+sequence is never halved, and it guarantees well-formed output even when the+input already carried a lone surrogate. Every JSON-LD block, meta tag, embedded+seed and excerpt on the news and SEO paths goes through it, including `esc()` in+`api/_lib/crawler-page.js`, because entity names come from user input. Anything+new that emits JSON-LD or a meta tag from stored text uses it too; do not+hand-roll a `slice()`.+## Soft 404s from SPA shellsA shell that renders "not found" over a `200` is a soft 404. The router cannotdiff --git a/docs/ops/solana-rpc-lanes.md b/docs/ops/solana-rpc-lanes.mdindex c9b68abb5..106342e8d 100644--- a/docs/ops/solana-rpc-lanes.md+++ b/docs/ops/solana-rpc-lanes.md@@ -257,7 +257,11 @@ itself: read these before concluding the tier is dead.blows. A reserve must appear in `SOLANA_RPC_LAST_RESORT_URLS` and nowhere else.- **`ALCHEMY_API_KEY` is not the Solana Alchemy lane.** The Solana URL lives inside`SOLANA_RPC_FALLBACK_URLS`; `ALCHEMY_API_KEY` stays load-bearing for EVM and NFT paths- even when Solana capacity is spent, so do not remove it to "clean up".+ even when Solana capacity is spent, so do not remove it to "clean up". Since 2026-09-09+ the EVM balance read in [api/\_lib/balances.js](../../api/_lib/balances.js) has a keyless+ rung behind it (public EVM RPC for native value, Blockscout for token discovery), so a+ spent Alchemy quota degrades a portfolio instead of answering 503, but the key is still+ the fast path and the only one that covers every chain.- **Update single keys with `--update-env-vars`.** `--set-env-vars` replaces the entireenv set on the service.diff --git a/docs/ops/trading-bot-report.md b/docs/ops/trading-bot-report.mdindex e4f2870ff..b407d4724 100644--- a/docs/ops/trading-bot-report.md+++ b/docs/ops/trading-bot-report.md@@ -40,8 +40,8 @@ Two independent runtimes drive autonomous trading, and the report shows both:| `STARVED` / `SHRUNK` | `walletTradeState()` | Whether the wallet can fund its configured entry size. Decided by `api/_lib/sniper-solvency.js`, which calls `resolveEntrySize()`, **the same sizing rule the executor uses to place or skip a real entry**. Never re-derive these thresholds here: a local copy drifts into calling a wallet tradeable that the executor sits out, which is the exact bug that module was written to catch. `SHRUNK` means it still trades, just below the configured size. || `trigger` | `trigger` | What wakes the bot: `new_mint`, `oracle_crossing`, `graduation_ride`, `intel_confirmed`. || `closed` / `open` / `failed` | `agent_sniper_positions.status` | A `failed` row is an entry that never landed, not a losing trade. The dominant reason is `SIM_FAILED`: `estimateComputeUnits()` in `api/_lib/execution-engine.js` runs a real `simulateTransaction` before broadcast and throws when it reverts. That path never broadcasts, so a `SIM_FAILED` costs **one RPC call and zero lamports**, not gas. Each candidate mint is attempted once, so a high count is filter friction, not a retry loop. |-| `realized PnL` | `realized_pnl_lamports` | Sum over every position the bot has ever held, in SOL. |-| `deployed` | `entry_quote_lamports` | Total SOL that has ever gone through an entry, so PnL reads against the capital that actually worked. |+| `realized PnL` | `realized_pnl_lamports` | Sum over every position the bot has ever held, in SOL. Net of the [three.ws trade fee](../pump-platform-fee.md): the buy fee sits inside the cost basis and the sell fee is subtracted from each closing leg, so a customer-owned bot's PnL is what it actually kept. |+| `deployed` | `entry_quote_lamports` | Total SOL that has ever gone through an entry, fee included, so PnL reads against the capital that actually worked. For a customer-owned bot that is the entry size plus the 1 percent trade fee; platform-owned fleets pay no fee and their two figures are the same. || `open positions … marked` | `last_value_lamports` | The last quote the sweep took for still-open positions. Marked, not realized. || `auto-funded … live` | `sniper_funding_events` where `mode = 'live'` | Real SOL the auto-funder moved into the bot's wallet. || `… simulated` | `sniper_funding_events` where `mode <> 'live'` | Paper funding from a simulate-posture run. **No money moved.** Reported separately because it dwarfs the live figure and would otherwise read as real capital. |diff --git a/docs/ops/wallet-key-migration.md b/docs/ops/wallet-key-migration.mdindex 14cfd0154..f4fe7a571 100644--- a/docs/ops/wallet-key-migration.md+++ b/docs/ops/wallet-key-migration.md@@ -3,6 +3,16 @@Date range: keys introduced 2026-06-19, pool agents created 2026-06-26, migration toCloud Run 2026-07-07, diagnosed + resolved 2026-07-12.+> **Cause corrected 2026-09-16, after this record was written.** The measurement+> behind the diagnosis below did not hold up: every wallet the production API+> wrote in June 2026 opens with today's production key, and wallets kept getting+> sealed long after the migration. The sealing writes came from deployments that+> shared the production database while carrying their own key, not from a key+> the migration dropped. The corrected brief, the evidence, and the recovery path+> are in [stranded-wallets.md](stranded-wallets.md). Read this page as the record+> of what was believed and done at the time; the rotation mechanics, the+> fund-safety guard, and the secret-storage runbook below are all still current.+## What happenedCustodial Solana wallets for the pump.fun launch-pool agents (`launcher_queue`, scope@@ -98,6 +108,17 @@ Never `--set-env-vars` here: it replaces the entire environment set. Covered by`tests/secret-box.test.js` (retired-key read, stacked rotations, and a case proving newwrites never use a retired key).+Step 1 is now load-bearing for a second reason. Since 2026-09-16 `secret-box.js` binds a+database to the key that writes into it: the first encrypt records an HMAC fingerprint of+the key in `app_settings` (`secret_box_write_key`), and any later process holding a+different key is refused with `secret_box_key_mismatch` instead of minting a wallet nobody+can open. A rotation that puts the outgoing key in `WALLET_ENCRYPTION_KEY_PREVIOUS` first+moves that fingerprint forward; a rotation that skips step 1 fails its next custodial write+outright. The fingerprint is one-way, so storing it reveals nothing. If a wallet is already+sealed under a key you have since recovered,+`scripts/recover-sealed-wallets.mjs` re-encrypts it in place under the current key, keeping+the address and moving no funds.+**What this does not do:** it cannot recover the keys already lost. A re-measure on2026-08-01 (`scripts/audit-custodial-key-health.mjs`) found 8 of 565 custodial walletsstill unopenable, holding **0.49 SOL, of which 0.35 SOL is customer money** in two@@ -373,6 +394,10 @@ anybody to reconnect.- `scripts/audit-home-credential-health.mjs`: the same reading for connected homes, whosetokens sit under the same key (see the section above). Exits 3 with no key, 1 when ahome is sealed.+- [Stranded custodial wallets](stranded-wallets.md): the standing owner decision, and+ the corrected cause of the sealing.+- `scripts/recover-sealed-wallets.mjs`: re-encrypt a sealed wallet in place once its+ original key is found.- `scripts/audit-custodial-key-health.mjs`: read-only sweep of every custodial wallet,how many still decrypt, how much SOL sits behind the ones that do not, and whichaddresses they are. Needs `DATABASE_URL` and `WALLET_ENCRYPTION_KEY`; it exits 3 ratherdiff --git a/docs/oracle-trading-mcp-plan.md b/docs/oracle-trading-mcp-plan.mdindex 6b33bfc2f..e749fd7da 100644--- a/docs/oracle-trading-mcp-plan.md+++ b/docs/oracle-trading-mcp-plan.md@@ -1,6 +1,6 @@# Plan: ship Oracle and the autonomous trading agents as MCP servers-**Status:** planned, not started. Written 2026-08-19.+**Status:** planned, not started. Written 2026-08-19; still unstarted at 2026-09-17 (no `packages/oracle-mcp`, no `api/mcp-oracle.js` in the tree). Facts below re-verified 2026-09-17.**Goal:** make [Oracle](https://three.ws/oracle) and the autonomous trading agents first-class,discoverable MCP servers, publish them to the official MCP registry(`registry.modelcontextprotocol.io`), document them, and announce them in one plain-language X post.@@ -15,15 +15,15 @@ tree and the live registry on 2026-08-19, so the plan starts from facts, not assOracle is the best thing we run and almost nobody can find it from an agent client.Its four MCP tools (`oracle_top_plays`, `oracle_coin`, `oracle_arm_watch`, `oracle_watch_status`)-live inside the main `https://three.ws/api/mcp` server, buried among 40+ avatar, model, animation,-sign-language, memory, and market tools. In the registry that server is listed as+live inside the main `https://three.ws/api/mcp` server, buried among 50+ avatar, model, animation,+sign-language, memory, and market tools (55 in `public/mcp-catalog.json` today). In the registry that server is listed as"3D avatars, embeds, glTF tools, agent memory, and on-chain agent identity". An agent looking fora conviction signal on a new launch has no way to find it, and a human browsing the registry hasno reason to click.The same is true of the autonomous side. `oracle_arm_watch` is the single most interesting writetool on the platform (it arms an agent to trade a live conviction stream inside a spend leash), and-it is discoverable only by reading a 40-tool list on an avatar server.+it is discoverable only by reading a 55-tool list on an avatar server.The fix is not new capability. It is **packaging**: two focused servers, named for what they do,listed under their own registry entries.@@ -47,7 +47,7 @@ listed under their own registry entries.| Surface | Location | Registry state ||---|---|---|-| Sniper engine (library + CLI + MCP + x402 API) | `packages/agent-sniper`, `workers/agent-sniper` | `io.github.nirholas/agent-sniper` @ 0.1.5 published; local `server.json` is 0.1.6, so a bump is pending |+| Sniper engine (library + CLI + MCP + x402 API) | `packages/agent-sniper`, `workers/agent-sniper` | `io.github.nirholas/agent-sniper` @ 0.1.6 in the registry; the tree and npm are both at 0.1.7, so a registry bump is still pending || Autopilot control plane | `packages/autopilot-mcp` | `io.github.nirholas/autopilot-mcp` @ 0.2.0 published || Copy-trade follows | `packages/copy-mcp` | published @ 0.1.1 || Signal marketplace | `packages/signals-mcp` | published @ 0.1.1 |@@ -55,8 +55,8 @@ listed under their own registry entries.| Market intel | `packages/intel-mcp`, `packages/kol-mcp` | published || Oracle-armed agent loop | `api/oracle/watch.js`, `api/oracle/action-stream.js`, `api/oracle/agent-stats.js` | **No dedicated server. Only the two tools inside `/api/mcp`.** |-61 distinct servers are already published under the `io.github.nirholas` namespace, so the-publishing path is proven and boring. `scripts/publish-mcp-servers.mjs` (`npm run publish:mcp`)+72 distinct servers are already published under the `io.github.nirholas` namespace (counted against+the live registry on 2026-09-17), so the publishing path is proven and boring. `scripts/publish-mcp-servers.mjs` (`npm run publish:mcp`)handles npm plus registry, idempotently, and skips anything already at the target version.### The publishing machinery (already built, do not rebuild)@@ -90,8 +90,9 @@ Copy the structure of `api/mcp-3d.js` exactly: Streamable HTTP, shared OAuth/x40Registry name `io.github.nirholas/threews-oracle`, URL `https://three.ws/api/mcp-oracle`.Route it in `vercel.json` (both the handler entry and the-`/api/mcp-oracle/.well-known/oauth-protected-resource` route, matching the `/api/mcp` precedent at-`vercel.json:525`), and add the entry to `public/.well-known/mcp.json`.+`/api/mcp-oracle/.well-known/oauth-protected-resource` route, matching the existing+`/api/mcp/.well-known/oauth-protected-resource` → `/api/wk?name=oauth-protected-resource` entry),+and add the entry to `public/.well-known/mcp.json`.**1b. stdio package: `packages/oracle-mcp`**@@ -123,6 +124,13 @@ The two write tools ship on the hosted remote only. The stdio package advertises"available on the hosted server" in its getting-started text rather than shipping a half-wiredauth path locally.+`oracle_arm_watch` has carried a second gate since 2026-09-17: arming a live mainnet watch refuses+with `risk_ack_required` and a signing link unless the account has signed the Terms, the Risk+Disclosure, and the Agent Wallet Agreement (`currentSignatureFor` in+`api/_lib/real-funds-agreement.js`). Devnet and an already-live watch are exempt, and a lookup+failure fails closed. The new server inherits that refusal verbatim; it is not something to+re-implement or soften.+**Honesty requirements, non-negotiable, already enforced by the existing tests in`tests/api/mcp-oracle-tools.test.js`:** a degraded feed or intel store reports as transient, neveras an empty market, and an unknown coin is distinguished from an outage. Any new tool inherits@@ -163,6 +171,10 @@ right posture for a write-heavy, real-money server.move real SOL.- Arming live still routes through the platform's existing owner-confirmation path. This serverdoes not become a way around the spend gate in `CLAUDE.md`.+- `agent_arm` inherits the signed real-funds agreement gate described in Phase 1: an unsigned+ account gets `risk_ack_required` and the signing link, never an armed agent. Every custodial+ money endpoint behind these tools enforces it server-side, so the tool surfaces the refusal+ rather than deciding it.### Phase 3: publish to the registry@@ -181,7 +193,7 @@ npm run smoke:mcp # hit the hosted remotes for realAlso in this phase, because they are one-line fixes that are currently drifted:-- Bump `packages/agent-sniper` to publish 0.1.6 (registry has 0.1.5, the tree has 0.1.6).+- Bump `packages/agent-sniper` in the registry to 0.1.7 (the registry has 0.1.6, the tree and npm have 0.1.7).- Add both new remotes to `public/.well-known/mcp.json` (7 entries today, 8 after Phase 1).- Add both new server keys to the `SERVERS` array in `scripts/publish-mcp-servers.mjs`. A serverthat is not in that array is invisible to the publisher, which is the single easiest way for@@ -200,7 +212,7 @@ Per the documentation rules in `CLAUDE.md`, all of these apply and none are opti- `packages/oracle-mcp/README.md` and `packages/agent-trader-mcp/README.md`: what it does, install,full tool table, one runnable example each. Package README coverage is currently 100% and thisplan must not be what breaks it.-- `docs/mcp.md`: update the server count (it currently says 44) and add both servers to the hosted+- `docs/mcp.md`: update the server count (it currently says 73) and add both servers to the hostedand install-and-run lists.- `docs/oracle.md`: expand the existing "the MCP path" section into a real quickstart with the newserver name and a copy-pasteable client config.diff --git a/docs/overlay-audit.md b/docs/overlay-audit.mdindex 6bfdc01b5..5e5baacfb 100644--- a/docs/overlay-audit.md+++ b/docs/overlay-audit.md@@ -114,11 +114,15 @@ instead, and the stack lifts clear of it:```jswindow.twsCornerStack.reserve('walk-companion', bottom + height);+window.twsCornerStack.reserve('walk-companion', { height, width }); // both axeswindow.twsCornerStack.release('walk-companion'); // on unmount```Reservations are keyed and independent, and the tallest wins, so two of them-never fight. Measure from `getComputedStyle`, not `getBoundingClientRect`: a+never fight. The stack applies them with a `transform`, never by animating+`bottom`/`right`: those are layout properties, and re-laying the stack out on a+re-measure registered as page-wide layout shift even though nothing on the page+had moved. Measure from `getComputedStyle`, not `getBoundingClientRect`: awidget that animates in with a transform reports a short box mid-transition, andthe stack would settle into it.@@ -126,6 +130,16 @@ If the corner stack has not booted yet when your widget mounts, listen once for`tws-corner-stack:ready` and claim then. Load order between these modules is notguaranteed.+### Modals++The stack renders above every page layer, so while a dialog owns the screen its+widgets stay clickable on top of that dialog and swallow whatever control they+cover. A modal opts out by putting `tws-modal-open` (published as+`window.twsCornerStack.MODAL_CLASS`) on `<body>` while it is open and removing it+on close; the stack fades out and stops taking pointer events for as long as the+class is there. Do this for any dialog that covers the corner, not only+full-screen ones.+### The page's own bottom chromeReservations only cover widgets that know the stack exists. They do nothing fordiff --git a/docs/page-performance.md b/docs/page-performance.mdindex 9211076ff..8296422b3 100644--- a/docs/page-performance.md+++ b/docs/page-performance.md@@ -74,7 +74,12 @@ first attention:`attendRotation` promotes `data-src` to `src` the first time the card ishovered, focused or tapped. The poster carries the finished frame in the-meantime, so nothing looks unfinished.+meantime, so nothing looks unfinished. A `data-src` viewer also defers the+`<model-viewer>` element bundle itself: first attention asks+`model-viewer-loader.js` for the element and sets `src` in the same breath, so+the bundle and the GLB arrive together and the card upgrades once. On a page+that already loaded the element the loader is idempotent and resolves without a+request, so a decorative card never builds a WebGL renderer during load.Render the poster with[`scripts/render-glb-poster.mjs`](../scripts/render-glb-poster.mjs), which@@ -163,8 +168,10 @@ flipping `data-theme` and reading a computed style: a full style recalc, twiceper probe. It used to re-probe on any DOM mutation, which on a JS-rendered pagebecame a recalc storm: 8.7 s of main-thread time on `/marketplace` alone, enoughthat Lighthouse gave up on the page. Only a stylesheet can change that verdict,-so only a stylesheet landing or leaving re-probes, coalesced to one probe per-frame.+so only a stylesheet landing or leaving re-probes. The filter is the whole+saving, so the probe itself stays synchronous: `nav.js` injects its stylesheet+long after boot, and a visitor who chose light has to get light in the same turn+the sheet arrives rather than a frame later.---diff --git a/docs/play-hardening.md b/docs/play-hardening.mdindex 892f587ee..50dfc4723 100644--- a/docs/play-hardening.md+++ b/docs/play-hardening.md@@ -111,6 +111,14 @@ The URL rewrite that follows puts the resolved identity back on the address bar,These two methods were *called* on every drop but never *defined*, so a reconnect threw a `TypeError` and ghosts accumulated: two drops in a ten-person world left thirty avatars on screen, twenty of them frozen, with the online count reporting triple the truth. If you rename or move them, update both call sites and [scripts/play-desktop-audit.mjs](../scripts/play-desktop-audit.mjs), which asserts they are callable in a real browser.+### 4a. The join snapshot waits for a listener++**Invariant: the client announces `ready` once its handlers are attached, and the room re-sends the join snapshot.**++Everything `WalkRoom` pushes during `onJoin` (the guest token, the profile, quests, build permissions, the King of the Totem sync) goes out while the client is still inside `await joinRoomWithTimeout`, before a single `onMessage` handler exists. Colyseus drops a message nothing is listening for, so a guest lost the very token section 7 makes their credential and the HUD came up with no purse.++`_announceReady()` in [src/game/community-net.js](../src/game/community-net.js) closes that window. Two details keep it safe and must survive any refactor: it is gated on the room advertising `acceptsReady` on its schema, because an older room build answers an unknown message type by closing the socket with 4002 and would kick every player during a client-before-server deploy; and it runs from the FIRST state sync, not the end of `connect()`, because the flag lives on the schema and reading it earlier finds `undefined`. Every re-sent payload is a full snapshot, so arriving twice is a repaint, never a double grant.+Related: the death overlay hides on a `respawn` notice, but a reconnect re-sends the authoritative profile without any notice. `_applyVitals()` in [src/game/combat-system.js](../src/game/combat-system.js) clears the overlay whenever the server says `hp > 0`, so nobody rejoins a live world stuck behind "You died".## 5. The world frees what it loadsdiff --git a/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md b/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.mdindex d231f443e..877a20113 100644--- a/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md+++ b/docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md@@ -189,8 +189,14 @@ normally against the reduced reserve.| | ||---|---|-| TypeScript SDK | `@pump-fun/[email protected]` |+| TypeScript SDK (PumpSwap) | `@pump-fun/pump-swap-sdk`, pinned in `package.json`; the field landed in 1.19.0 |+| TypeScript SDK (bonding curve) | `@pump-fun/pump-sdk`, on the 2.x line since 2026-09-14 || Rust SDK | `[email protected]` || IDL | `contracts/idl/pump/pump_amm.json`, refreshed via `npm run pump:refresh-idls` |+The exact versions we run last accepted are recorded in+`data/pump-upstream-baseline.json` and re-checked by the upstream watch+([docs/ops/pump-upstream-watch.md](../ops/pump-upstream-watch.md)), so read them+there rather than from a number in this table.+Upstream: <https://github.com/pump-fun/pump-public-docs#pumpswap-update-virtual-quote-reserves>diff --git a/docs/risk-acknowledgment.md b/docs/risk-acknowledgment.mdindex d9aef949a..97b12c5c8 100644--- a/docs/risk-acknowledgment.md+++ b/docs/risk-acknowledgment.md@@ -89,6 +89,15 @@ Rules the helper and its call sites follow:in their own wallet (self-custody launches, swaps, token pay) are gated by thedialog; the platform never holds those keys.+Some money paths are gated on the server only, because they have no+single-click dialog of their own: opening, resuming, depositing into,+redeeming from, owner-trading and fee-claiming a [USDC vault](./vaults.md)+(`vault-open`, `vault-resume`, `vault-deposit`, `vault-redeem`, `vault-trade`,+`vault-claim-fees`), creating or resuming a programmable order+(`order-create`, `order-resume`), and hiring another agent for a paid skill+(`a2a-hire`). Pausing an order, like every other way of turning spending off,+is not gated.+Positive lookups are cached in-process for 10 minutes (signatures are append-onlyand the required version only changes on deploy); negative results are nevercached, so a fresh signature takes effect on the next request.@@ -208,6 +217,7 @@ keeps the sign-in clickwrap record in step with the Terms version.| Oracle arm (live mode only) | `src/arm.js` | `oracle-arm` || Jupiter swap modal | `src/swap-jupiter.js` | `swap` || pump.fun token launch | `src/pump/launch-token-modal.js` | `launch` |+| The `/launch` launchpad: launch a coin, claim creator rewards | `src/launch/launch-page.js` | `launch`, `claim` || Agent-home pump.fun buy/sell | `src/agent-home-pumpfun.js` | `pump-trade` || pump.fun x402 access payment | `src/pump/pump-modals.js` | `x402-pay` || Skill purchase modal | `src/payment-modal.js` | `skill-purchase` |@@ -215,7 +225,7 @@ keeps the sign-in clickwrap record in step with the Terms version.| Forge pay-per-generation | `src/forge-pay.js` | `forge-pay` || Add funds / Coinbase onramp | `src/shared/add-funds.js` | `onramp` || Drop-in x402 modal (incl. merchant embeds) | `public/x402.js` | `x402-pay` |-| Review and sign page | `public/legal/agreements.html` | `agreements-page` |+| Review and sign page | `public/legal/agreements.js`, loaded as a module by `public/legal/agreements.html` | `agreements-page` |If you add a surface, add its row here and its gate call in the code, and if itsigns with a custodial key, call `requireRealFundsAgreement` in its handler: alldiff --git a/docs/seed-quality.md b/docs/seed-quality.mdindex 6f1e368f1..117f20755 100644--- a/docs/seed-quality.md+++ b/docs/seed-quality.md@@ -161,9 +161,9 @@ judge prompt changes, because **an accept rate is only comparable within one gatversion.** Comparing last week's 62% against today's under different thresholdsis meaningless.-## Two transports, one gate+## Three transports, one gate-The gate runs from two places with different credentials, so the model call is+The gate runs from places with different credentials, so the model call isbehind a transport interface. The decision logic is identical either way, whichis the point: the bar cannot drift between how an asset arrives.@@ -171,6 +171,21 @@ is the point: the bar cannot drift between how an asset arrives.| --- | --- | --- | --- || `inProcessTransport()` | Cloud Run, GCP service account attached | [`render-clip.js`](../api/_lib/render-clip.js) in process | Vertex Gemini direct || `remoteTransport({ origin })` | A workstation with no GCP credentials | `POST /api/render/avatar-clip` | `POST /api/vision` |+| `localJudgeTransport({ origin })` | A workstation measuring a vision-chain fix before it deploys | `POST /api/render/avatar-clip` | `describeImage()` from [`vision.js`](../api/_lib/vision.js) in this process |++`remoteTransport` and `localJudgeTransport` share one body (`buildTransport`) and+differ only in which process calls the model, so their accept rates stay+comparable. Both ask for the verdict through `askJson`, which gives a model that+replied in prose exactly **one** more attempt with the format instruction+restated last. That retry never relaxes the verdict, only the format: a second+prose reply still fails. It exists because the free vision rungs occasionally+open with "The image shows...", and treating that as an infrastructure failure+recorded the asset as ungated and re-spent GPU time on the same prompt at the+next resume.++The bulk batch runner is [`scripts/gcp/seed-avatars.mjs`](../scripts/gcp/seed-avatars.mjs).+It has no 70 s function wall, so unlike the cron it runs **both** stages; pass+`--judge=local` to point its judge at `localJudgeTransport`.## Using it@@ -227,6 +242,33 @@ A verdict looks like this:Passing no `transport` runs stage 1 alone. That is not a degraded mode: it is thecron's default, and it is a complete, meaningful verdict.+## The rig stage, after the gate++A verdict decides whether an asset is published. `SEED_CRON_RIG` decides what is+published: a rigged avatar or a static mesh. It has been **on by default since+2026-09-09**, after an audit found that zero of the 17,349 published seed avatars+had ever been rigged, because the stage was opt-in and nothing opted in. Every+catalog avatar was animating through the retarget fallback rather than its own+skeleton.++Not every accepted mesh is sent. `riggableShape()` in+[`forge-seed-cron.js`](../api/cron/forge-seed-cron.js) asks a different question+from the gate: not "is this worth publishing" but "does binding a humanoid rig+to it make it better or worse". It reads `thinAxis` and `planar`, which the mesh+stage already records. glTF is Y-up, so a mesh whose *thinnest* extent is Y is+lying down or standing in a slab, and the auto-rigger skins the slab along with+the figure: the first clip that moves the legs drags it across the scene. That is+not hypothetical. A seeded mesh (1.99 x 0.69 x 1.99) rigged cleanly by every+structural measure, 52-joint mixamorig skeleton and unit inverse binds, and then+shredded on screen the moment the idle clip played, while the same mesh published+static rendered correctly.++Every failure path keeps the asset. A refused shape, a rig fault, or a rig that+stops answering past `RIG_STALL_MS` (45 minutes) publishes the gated keeper+**static** rather than losing it, which is exactly what every seed avatar was+before the stage turned on. The verdict is now written onto the keeper row as+well as the reject, so a published entry carries the gate that let it through.+## ConfigurationGate thresholds (read at import, so a change needs a restart):@@ -248,7 +290,7 @@ with no redeploy):| `SEED_CRON_MAX_PENDING` | 3 x batch | In-flight ceiling || `SEED_CRON_VISION` | off | Enables stage 2 inside the cron || `SEED_CRON_VISION_MS` | 20,000 | Wall-clock budget for stage 2 |-| `SEED_CRON_RIG` | off | Auto-rigs accepted avatars before publishing |+| `SEED_CRON_RIG` | **on** | Auto-rigs accepted avatars before publishing (`0` to publish static). Only shapes `riggableShape()` accepts are sent |### Why stage 2 is off by default in the crondiff --git a/docs/site-performance.md b/docs/site-performance.mdindex 8c51e3a14..05d1e598c 100644--- a/docs/site-performance.md+++ b/docs/site-performance.md@@ -276,7 +276,7 @@ Verified in a browser against the dev server: `/create` and `/forge` still auto-The rule above was written about sections. The most expensive violation of it was not a section at all: it was the decorative robot in the site footer, and it was costing more than everything the rule had already caught.-[public/footer.js](../public/footer.js) injects `/footer.html` into any page holding `<div id="footer-container">`, which is roughly 175 pages. That markup contains `#footer-bot-canvas`, and the injector booted its renderer immediately, at `DOMContentLoaded`, down one of two branches:+[public/footer.js](../public/footer.js) injects `/footer.html` into any page holding `<div id="footer-container">`, which was roughly 175 pages when this rule was written and is 269 HTML files under `pages/` and `public/` as of 2026-09-17 (`grep -rl footer-container pages/ public/ | wc -l`). It only ever grows, which is the point of the rule. That markup contains `#footer-bot-canvas`, and the injector booted its renderer immediately, at `DOMContentLoaded`, down one of two branches:- A page carrying `<meta name="has-three-bundle">` (every Vite-built page) loaded `/footer-bot.js`, which builds a `WebGLRenderer`, claims a context off the shared budget in [src/webgl-budget.js](../src/webgl-budget.js), and loads `robotexpressive.glb`.- A plain HTML page (login, register, the dashboard, `/docs`, `/discover`) instead pulled **`model-viewer` from `ajax.googleapis.com`, a second complete 3D engine**, plus the meshopt shim and the same GLB.@@ -468,7 +468,7 @@ Each of these is the largest remaining number on the page it belongs to, and eac**`/forge` showcase thumbnails are full-size renders.** Twelve images from `pub-*.r2.dev` account for **6,273 KiB of the page's 8,339 KiB**, averaging 520 KB each. They are the 768x768 PNGs that [api/\_lib/forge-thumbs.js](../api/_lib/forge-thumbs.js) generates (`THUMB_SIZE = 768`), painted into a 200px-tall box. `loading="lazy"` and `decoding="async"` are already set per rule 5, so this is not a scheduling problem, it is a format and size problem: the same renders as WebP at a display-appropriate size are roughly a tenth of the bytes. The fix has to change the generator, re-run the backfill cron over existing rows, and handle the `forge/thumb/<id>.png` key extension that `forgeThumbKeyFor()` and the stored `preview_image_url` values both encode. One outlier in the same trace is a data-freshness artifact rather than a bug: a 2,358 KiB `forge/<clientKey>/<id>.png` is the untouched original for a row the backfill has not reached yet.-**The brand mark is an 85 KB SVG rendered at 22 pixels.** `public/three.svg` and the byte-identical `public/favicon.svg` are 85,257-byte SVGs wrapping two 800x436 PNGs behind `feColorMatrix` filters. They are referenced from 171 files, cost 62 KiB over the wire per page, and no call site in the repo renders the mark above 64 CSS px. Re-encoding the embedded rasters at exactly half resolution (800 to 400, lanczos3, no palette quantization) takes the file to 36,913 bytes and is visually indistinguishable at every size the site uses, with a maximum channel delta of 4 at 22px and 10 at 64px. It is not free above that: at 192px, which some platforms use for an SVG favicon, the delta reaches 105. Fractional downscales are much worse than the exact half (320px wide measured a delta of 78 at 22px), so this is a brand-asset decision with a measured cost attached, not a mechanical resize, and it needs the owner rather than a sweep.+**The brand mark is an 85 KB SVG rendered at 22 pixels.** `public/three.svg` and the byte-identical `public/favicon.svg` are 85,257-byte SVGs wrapping two 800x436 PNGs behind `feColorMatrix` filters. They are referenced from 545 files as of 2026-09-17 (446 of them HTML: `grep -rl '/three\.svg\|/favicon\.svg' pages/ public/ src/ | wc -l`, up from 171 when this item was first measured), cost 62 KiB over the wire per page, and no call site in the repo renders the mark above 64 CSS px. Re-encoding the embedded rasters at exactly half resolution (800 to 400, lanczos3, no palette quantization) takes the file to 36,913 bytes and is visually indistinguishable at every size the site uses, with a maximum channel delta of 4 at 22px and 10 at 64px. It is not free above that: at 192px, which some platforms use for an SVG favicon, the delta reaches 105. Fractional downscales are much worse than the exact half (320px wide measured a delta of 78 at 22px), so this is a brand-asset decision with a measured cost attached, not a mechanical resize, and it needs the owner rather than a sweep.**`/marketplace`'s hero was the site's worst CLS, and is closed as of 2026-09-08.**Not through the GLB budget guessed at below, which is still worth doing: throughdiff --git a/docs/smart-home.md b/docs/smart-home.mdindex 497e24d50..bdc7d9a7b 100644--- a/docs/smart-home.md+++ b/docs/smart-home.md@@ -252,7 +252,7 @@ below exists, and anything that does not exist says so.| The `/api/home/*` surface: REST, SSE stream, the error contract | [`api/home/`](../api/home) || Agent tools and the confirmation protocol | [`api/_lib/home/tools.js`](../api/_lib/home/tools.js), [`confirm.js`](../api/_lib/home/confirm.js), wired into `api/chat.js` and `api/_mcp/tools/home.js` || The connect flow and the household page | `/smart-home` ([`pages/smart-home.html`](../pages/smart-home.html), [`src/home/`](../src/home)) |-| The live 3D home | [`src/home/scene-render.js`](../src/home/scene-render.js), [`scene-model.js`](../src/home/scene-model.js) |+| The live 3D home, with the visitor's own agent standing in it (the platform body until their active-agent record arrives, and again if they have no published avatar) | [`src/home/scene-render.js`](../src/home/scene-render.js), [`scene-model.js`](../src/home/scene-model.js), [docs/home-scene.md](home-scene.md) || Households: roles, per-member scopes, invites | [`api/_lib/home/members.js`](../api/_lib/home/members.js), [docs/home-households.md](home-households.md) || Privacy, retention, export and deletion | [`api/_lib/home/privacy.js`](../api/_lib/home/privacy.js), [docs/home-privacy.md](home-privacy.md) || The dial-out relay for LAN-only houses | [`services/home-relay/`](../services/home-relay/README.md) plus [`home-assistant-integration/`](../home-assistant-integration) |@@ -329,6 +329,14 @@ Everything a house supplies (a label, an entity id, an area name) is rendered wi`textContent`. These are strings a stranger or a compromised integration can influence, theyflow into a page and into a model prompt, and there is a physical actuator on the other end.+**Every reader-facing string on this surface is translated, and none of the house's own words+are.** Connect, the manage panel, the floorplan editor, the live house and the voice panel all+assemble their copy through [`src/home/i18n-home.js`](../src/home/i18n-home.js), so a refusal, a+confirmation or the age of a reading arrives in the reader's own language. A room name, an area+name, a scene name and a device name are passed as interpolated values and never as part of a+translatable string, because they are the user's words and nobody's to machine-translate. The+rule and the key-extraction command are in [i18n.md](i18n.md).+### Not shipped- **Matter direct control.** Built as a throwaway kernel, measured, and deliberately not kept.diff --git a/docs/social-layer.md b/docs/social-layer.mdindex c39cf45dd..1ec989193 100644--- a/docs/social-layer.md+++ b/docs/social-layer.md@@ -30,9 +30,10 @@ How they interconnect:`followers` leaderboard metric.- **Every feed item links to a portfolio.** Feed cards deep-link to`/u/:username`, where the same records render as that creator's portfolio.-- **Creating anything advances your streak.** Forging a model, saving a world,- or walking while signed in calls the streak engine, which in turn awards the- badges shown on `/rankings` and your profile.+- **Showing up advances your streak.** Forging a model, saving a world,+ restyling, walking, or landing a confirmed on-chain trade while signed in+ calls the streak engine, which in turn awards the badges shown on+ `/rankings` and your profile.---@@ -171,7 +172,11 @@ their own work.The streak engine ([api/_lib/streaks.js](../api/_lib/streaks.js),`recordDailyActivity()`) is called from sign-in, forge saves, diorama saves,-and walk metrics, and writes `user_streaks` / `user_badges`. A daily rollup+restyle saves, walk metrics, and a confirmed on-chain trade (both legs of+[api/pump/[action].js](../api/pump/%5Baction%5D.js), fire-and-forget so the+streak can never delay or fail the trade that earned it), and writes+`user_streaks` / `user_badges`. The upsert is idempotent per UTC day, so a+busy session still counts once: the streak measures showing up, not volume. A daily rollupcron ([api/cron/leaderboard-rollup.js](../api/cron/leaderboard-rollup.js))sweeps badge awards. Badges and streaks also render on profile pages.diff --git a/docs/sonar.md b/docs/sonar.mdindex f7d46c217..51d902b7c 100644--- a/docs/sonar.md+++ b/docs/sonar.md@@ -52,6 +52,8 @@ sensor.stop();Methods: `start()`, `stop()`, `setTone(hz)`, `setAmplitude(0..1)`, `recalibrate()`.+`start()` is not instant: it awaits the microphone prompt and then measures a carrier against this machine's own speakers, about a second together. A `stop()` that lands inside that window wins. The late-resolving start tears itself down instead of arming, releasing the microphone track and the carrier, which is what puts the browser's recording indicator out.+Why `autoTone` exists: laptop speakers roll off hard near the top of their range, and every model rolls off somewhere different. A carrier the speakers cannot actually project reads exactly like a room with nothing moving in it, which is indistinguishable from a broken sensor. Measuring first turns a mystery into a number.### The `Reading`@@ -158,6 +160,12 @@ so an embed that never uses it pays nothing for the capability. The attribute,the methods and the event detail are specified in[Web component](./web-component.md#hand-control-no-camera).+[`examples/sonar-hand-control.html`](../examples/sonar-hand-control.html) is the+runnable version of both halves: the built-in response on the left, and on the+right the same `sonar-gesture` events taken over with `preventDefault()` to move+the page's own cards while the agent stays put. Open it at+`http://localhost:3000/examples/sonar-hand-control.html`.+---## The shared controller@@ -180,7 +188,7 @@ await sonar.start();| Member | Purpose || --- | --- |-| `start()` / `stop()` | Open and release the microphone. `stop()` is safe when nothing is running. |+| `start()` / `stop()` | Open and release the microphone. `stop()` is safe when nothing is running, and safe mid-`start()`: it supersedes a start still waiting on the microphone rather than letting it arm behind the viewer's back. || `setMode(mode)` | `'swipe'`, `'push'`, `'lift'` or `'all'`. Drops the stroke in flight, so a half-formed gesture cannot complete under the new mapping. || `setReversed(gesture, on)` | Flip a gesture's direction. `'lift'` reverses through the motion itself, so a held turn stops rather than snapping the other way. || `recalibrate()` | Re-measure the still room without restarting the microphone. |diff --git a/docs/talking-avatar-video.md b/docs/talking-avatar-video.mdindex 163acf5ea..ada3ea30f 100644--- a/docs/talking-avatar-video.md+++ b/docs/talking-avatar-video.md@@ -17,12 +17,12 @@ The page ([`pages/create/video.html`](../pages/create/video.html)) loads [`src/c1. **Auth gate.** On load it checks `GET /api/auth/me`; if you are not signed in it redirects to `/login?next=%2Fcreate%2Fvideo`.2. **Availability probe.** In parallel it calls `GET /api/avatar/video-generate`, which answers `{ available, reason, free_generations, accepts }` without submitting anything. When the GPU worker is not configured on the deployment the page raises a "Video rendering is offline" banner and keeps Generate disabled, so nobody is walked through an upload that can only end in a `503`. A probe that itself fails is treated as inconclusive: generation stays enabled and the real POST reports what happened.-3. **Pick an avatar.** It calls `GET /api/avatars` and renders your avatar library into a thumbnail bar of real `<button>` elements, auto-selecting the first. The selected GLB is shown in a `<model-viewer>`. Private avatars resolve their GLB lazily through `GET /api/avatars/:id` (a short-lived signed URL). Three distinct outcomes: avatars found (thumbnails), none yet (an empty state linking to `/create`), and the list call failing (an error row with a Retry that refetches). The last two show `/avatars/default.glb` in the viewer purely so the panel is not a blank box; it is never a generation source, and Generate stays disabled with a hint saying what is missing.+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`, which hands a browser the same-origin `/api/avatars/:id/glb` proxy rather than a presigned storage URL, so the load enforces the same owner-only rule, reports a storage fault legibly instead of as an opaque CORS error, and does not expire out from under a long-open tab. 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`](./api-reference.md), 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.+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 }`. The submit goes through the shared upstream client on a `longcat-worker` circuit breaker with a 60 s deadline and **no** retry, because a retried submit would start a second GPU job.+8. **Poll.** The client polls `GET /api/avatar/video-status?job_id=...` every 5 seconds (20-minute safety timeout). A job read is idempotent, so server-side it rides the same breaker with a 10 s deadline and up to three attempts. 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."## Walkthroughdiff --git a/docs/terminal.md b/docs/terminal.mdindex f6989e7a4..bc5d11c77 100644--- a/docs/terminal.md+++ b/docs/terminal.md@@ -15,7 +15,7 @@ Early pump.fun trading punishes context-switching. The launch is on one tab, theThe page mounts `mountMissionControl` from `src/mission-control/index.js` and lays out three panes:- **Feed (left).** Three switchable sources. `live` is the new-mint and graduation firehose over Server-Sent Events (`/api/pump/trades-stream`). `signals` is the Coin Intelligence Engine's scored feed (`/api/pump/intel?view=feed`), each coin carrying a 0 to 100 `quality_score`, a verdict, and risk flags. `radar` is the pre-launch precursor stream (`/api/sniper/radar`).-- **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.+- **Focus (center).** The selected coin's identity and market state (`/api/pump/coin`), its candlestick chart (`/api/pump/price-history`, Birdeye then GeckoTerminal then pump.fun's own bonding-curve candles, with 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.diff --git a/docs/timeline.md b/docs/timeline.mdindex 0d1f992d8..80c364f3f 100644--- a/docs/timeline.md+++ b/docs/timeline.md@@ -78,15 +78,19 @@ Around both modes:- **Reduced motion**: no auto-rotate, camera moves become effectivelyinstant, and auto-play steps briskly instead of gliding.- **Loading and errors**: a spinner while the data loads; a failed fetch- shows a designed error state with a Retry button.+ shows a designed error state with a Retry button, and a dataset that parses+ but holds no events says so ("No milestones have been published yet")+ instead of blaming the connection.## Adding a milestoneAppend an object to the `events` array in[`data/timeline.json`](../data/timeline.json), keeping the array inchronological order (markers are laid out in array order, not re-sorted).-There is no build step: the file is fetched at runtime from-`/data/timeline.json`.+The page fetches `/data/timeline.json` at runtime, so the only build step is+the copy: the `copy-timeline-data` hook in+[`vite.config.js`](../vite.config.js) writes the file into `dist/data/` and+`npm run check:dist` fails a build that lacks it.```json{diff --git a/docs/tutorials/pay-for-x402-service.md b/docs/tutorials/pay-for-x402-service.mdindex fd2b32025..1a14328f9 100644--- a/docs/tutorials/pay-for-x402-service.md+++ b/docs/tutorials/pay-for-x402-service.md@@ -75,9 +75,11 @@ Find an HTTP service you want and click **Try it** on its card.1. The drop-in payment modal opens, having already re-fetched the live 402 challenge to confirm the current price (prices can change; the card is a cached hint, the modal is the source of truth).2. The modal shows the **price**, the **network**, and **who you're paying** — the on-chain `payTo` address, linked to a block explorer so you can verify the recipient before committing.-3. Pick your wallet. The modal only offers wallets that match a network in the challenge's `accepts` and are actually detected in your browser; undetected ones render disabled with an "install" hint. Signed-in users with funded agents also see a **"Your agents"** group at the top; picking one skips the wallet popup entirely and pays from the agent's own USDC under its spend limits.-4. Approve the payment in your wallet. Before prompting you, the modal does a fail-open balance pre-check — if it can positively read that your wallet is short, it shows an insufficient-funds state with the exact shortfall and an explorer link, instead of letting you sign a doomed transaction.-5. The platform settles on-chain and retries the call. The card's receipt area fills in with the result and a link to the on-chain transaction.+3. If the resource is priced in more than one token on the same network, a **token chooser** appears above the wallet list with each option's real price, so you compare (say) 0.001 USDC against 10 THREE before signing. three.ws quotes USDC and `$THREE` on its own paid endpoints; the server's preferred token is first and selected by default. Agent wallets settle Solana USDC only, so on a non-USDC token they say so rather than disappearing.+4. Pick your wallet. The modal only offers wallets that match a network in the challenge's `accepts` and are actually detected in your browser; undetected ones render disabled with an "install" hint. Signed-in users with funded agents also see a **"Your agents"** group at the top; picking one skips the wallet popup entirely and pays from the agent's own USDC under its spend limits.+5. On your first payment the modal asks you to sign the three.ws real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement) at [/legal/agreements](/legal/agreements). It is once per account, and declining stops the payment. The server enforces the same signature on the agent-wallet path, which answers `403 risk_ack_required` without it.+6. Approve the payment in your wallet. Before prompting you, the modal does a fail-open balance pre-check: if it can positively read that your wallet is short, it shows an insufficient-funds state with the exact shortfall and an explorer link, instead of letting you sign a doomed transaction.+7. The platform settles on-chain and retries the call. The card's receipt area fills in with the result and a link to the on-chain transaction.What you signed is exactly what the challenge declared — the modal never invents an amount or a recipient. If the seller configured optional charity / round-up giving on a Solana checkout, you'll see a pre-checked, opt-out box that rides the *same* transaction, so you still pay once.@@ -115,6 +117,7 @@ Read it like a receipt-in-advance:- **`amount`** is in atomic units of **`asset`**. With `decimals: 6`, `"1000"` is $0.001. (Spec-strict sellers may name this field `maxAmountRequired`; the client coerces both to `amount`.)- **`network`** tells you which wallet you need. `solana` / `solana:*` → Phantom/Solflare; `eip155:8453` → Base; other `eip155:*` are the EVM L2s in `EVM_NETWORKS` (`public/x402-pay-core.js`).- **`payTo`** is exactly where your USDC goes. Nothing else moves.+- **`extra.feePayer`** is the sponsor that co-signs the Solana transaction so your SOL is untouched. It is optional: an accept with no `feePayer` is the **self-pay** contract, where you cover the network fee yourself. The modal says so on the approve step ("you cover the network fee on this one") rather than letting the wallet popup be the first you hear of it.- **`maxTimeoutSeconds`** bounds how long your signed authorization is valid — your one safety net against a stale payment lingering.A single endpoint can list several `accepts` (e.g. Base *and* Solana). You — or your wallet — pick whichever network you hold funds on.@@ -219,6 +222,7 @@ If the result looks wrong but you were charged, note: x402 has **single-shot, no- **"Payment module failed to load (x402.js)"** on a Bazaar card — the drop-in script 404'd or didn't evaluate, so `window.X402` is undefined. Reload the page; check the network tab for the `/x402.js` request.- **Wallet button is disabled** — that wallet isn't detected, or no `accept` matches its network. Install the extension (Phantom for Solana, MetaMask/Coinbase for Base) and reload, or pick the other rail.- **"Not enough USDC — you need X but your wallet holds Y"** — the balance pre-check caught a shortfall before you signed. Top up the wallet on the shown network (the error links your address on the explorer) and retry. The check is fail-open: if your balance can't be read, payment still proceeds.+- **"Payments are temporarily paused while we top up the wallet that settles them"**: a `503 settlement_unavailable`, the sponsor wallet is under its SOL reserve or the fee budget is spent. Nothing was charged and the error is marked retryable; try again shortly.- **"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.@@ -238,7 +242,7 @@ You learned four ways to consume an x402 paid service:- **`window.X402.pay`** — pay for any endpoint from your own code; resolves with the result plus an on-chain receipt, with a `networks` allowlist to pin the rail.- **The Endpoint Shopper** ([/shopper](/shopper)) — describe a task and a budget; an agent discovers, pays for, and synthesizes results from Bazaar endpoints autonomously.-The throughline: discovery and payment are decoupled, the 402 challenge is the single source of truth for price and recipient, every payment settles on-chain in USDC, and one module (`public/x402.js`) drives every surface.+The throughline: discovery and payment are decoupled, the 402 challenge is the single source of truth for price, token, and recipient, every payment settles on-chain in the asset you picked (USDC, or `$THREE` where a three.ws endpoint quotes it), and one module (`public/x402.js`) drives every surface.**Use it from your own project (npm)**diff --git a/docs/tutorials/self-host-agent-backend.md b/docs/tutorials/self-host-agent-backend.mdindex bd2878b04..9cbced55d 100644--- a/docs/tutorials/self-host-agent-backend.md+++ b/docs/tutorials/self-host-agent-backend.md@@ -42,7 +42,7 @@ The platform is intentionally composed of small, independently deployable servic**Workers (`workers/`).** Everything that doesn't fit in a serverless function. Two distinct kinds live here:-- **The Pump.fun MCP worker** (`workers/pump-fun-mcp/`), the one Cloudflare Worker in the tree. It maintains live websocket connections to the Pump.fun program, which Vercel functions can't hold cheaply.+- **The Pump.fun MCP worker** (`workers/pump-fun-mcp/`), the one Cloudflare Worker under `workers/`. It maintains live websocket connections to the Pump.fun program, which Vercel functions can't hold cheaply.- **GPU model workers** (`workers/model-trellis/`, `workers/rig/`, `workers/remesh/`, and about two dozen more), containers that run 3D generation, rigging, and mesh processing. Each deploys from its own `cloudbuild.yaml` and is only needed if you want the Forge feature it backs.Model-provider traffic does *not* go through a worker: Anthropic and OpenAI are called directly from the serverless functions, with the keys held in the deployment env.@@ -216,7 +216,17 @@ Do **not** commit `.env.development`. It's in `.gitignore` already; double-checknpm run dev```-This boots Vite on port 3000 with the API functions proxied through Vercel's local dev (the project uses Vite's dev server alongside Vercel's function emulator via `vercel dev`-style integration baked into the dev script).+`npm run dev` is `vite --port 3000`. Vite serves the front-end, and every `/api/*` request is **proxied** to `DEV_API_PROXY`, which defaults to `https://three.ws` (see the proxy block in `vite.config.js`). That default is what makes a front-end-only change easy, and it is exactly what you do not want here: it would exercise the hosted platform's database, not the one you just provisioned.++So run your own backend beside it. The repo's server is the same Express container production runs, and it reads your `api/` handlers and the `vercel.json` route table directly:++```bash+# Terminal 1: your API, on :8080+node --env-file=.env.development server/index.mjs++# Terminal 2: the front-end, pointed at it+DEV_API_PROXY=http://localhost:8080 npm run dev+```In another terminal, sanity-check the API:@@ -242,7 +252,7 @@ If the avatar loads and you can send a chat message that gets a real model respo**There is no LLM proxy worker to deploy.** Model traffic is served by the platform's own serverless functions: `api/chat.js` and `api/brain/chat.js` route through `api/_lib/llm.js` and `api/llm/anthropic.js`, reading `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from the deployment env. Keys stay server-side, rate limiting is enforced by `api/_lib/rate-limit.js` (Step 13), and streaming is handled in the function. Setting those two keys in Step 5 is all the wiring the chat path needs, so this step is optional.-The one Cloudflare worker in the tree is the Pump.fun MCP worker, which exists because Vercel functions cannot hold long-lived websockets cheaply. Deploy it only if you want the Pump.fun live feed:+The one Cloudflare worker under `workers/` is the Pump.fun MCP worker, which exists because Vercel functions cannot hold long-lived websockets cheaply. Deploy it only if you want the Pump.fun live feed:```bashcd workers/pump-fun-mcp@@ -281,7 +291,7 @@ This builds:- The `<agent-3d>` embed bundle into `dist-lib/agent-3d.js` (ES module; `npm run build:lib:full` adds the UMD build)- The chat sub-app into `dist/chat/` (via `npm run build:chat`)-Look at `dist/`. There should be an `index.html`, hashed bundles, and the various sub-apps, with the embed bundle in `dist-lib/`. Nothing about the API origin is baked in at build time, so the same `dist/` is valid on preview and production alike; the bundle resolves its origin at runtime (Step 11). The handful of `VITE_*` vars that *are* read at build time are third-party client IDs (`VITE_PRIVY_APP_ID`, `VITE_WALLETCONNECT_PROJECT_ID`, `VITE_AVATURN_DEVELOPER_ID`), and each only gates the feature it belongs to. Set the ones whose features you want before re-running the build.+Look at `dist/`. There should be an `index.html`, hashed bundles, and the various sub-apps, with the embed bundle in `dist-lib/`. Nothing about the API origin is baked in at build time, so the same `dist/` is valid on preview and production alike; the bundle resolves its origin at runtime (Step 11). The handful of `VITE_*` vars that *are* read at build time are third-party client IDs (`VITE_PRIVY_APP_ID`, `VITE_WALLETCONNECT_PROJECT_ID`) plus `VITE_CHARACTER_STUDIO_URL`, and each only gates the feature it belongs to. Set the ones whose features you want before re-running the build.---diff --git a/docs/tutorials/write-a-guard.md b/docs/tutorials/write-a-guard.mdindex 6604e106c..1b4777679 100644--- a/docs/tutorials/write-a-guard.md+++ b/docs/tutorials/write-a-guard.md@@ -163,11 +163,14 @@ That message is the point of the whole registry. Documentation drifts from reali### Which stage?+The six stage ids `data/guards.json` accepts, and what each is for:+| Stage | Use it when | Cost budget ||---|---|---|| `prebuild` | The guard checks something the build itself generates. | Under a second. || `gate` | Offline, deterministic, no credentials. Most guards belong here. | A few seconds. || `build:gcp` | It can only judge a finished artifact, like `dist/`. | Seconds. |+| `deploy:submit` | It has to see the finished artifact and the live environment it is about to ship over (a pending migration, the real upload set). | Seconds. || `pre-push` | It judges commit content and must not be skippable. | Under a second. || `manual` | It needs a browser, live credentials, or the network. | Any. |diff --git a/docs/user-wallet.md b/docs/user-wallet.mdindex 69f15cfa7..1e7f380c7 100644--- a/docs/user-wallet.md+++ b/docs/user-wallet.md@@ -14,8 +14,8 @@ If you just want to use your wallet rather than script it, **[/wallet](https://tThree things about that page are worth knowing before you use it:-- **Depositing is scan-to-fund.** The **Add funds** sheet (`src/wallet-deposit.js`) renders a payment-request QR, not a bare address: a Solana Pay URI (`solana:<addr>?amount=&spl-token=`) or, for Base USDC, an EIP-681 transfer link, so a scanning wallet opens with the recipient, token, and amount pre-filled. While the sheet is open, a watcher re-reads the wallet's real balances against a baseline and announces the exact on-chain delta the moment the deposit lands; it backs off over time, suspends while the tab is hidden, and gives up rather than polling forever.-- **Moving money out is two-step by design.** When you submit the send form or the fund-agent form, the page does not sign anything. It calls the route with `simulate: true`, which runs the real balance, rent, and fee checks on the server and returns what the transfer would actually cost. Only after you read back the amount, recipient, asset, and network, and press **Confirm and send**, does anything get signed and broadcast. A transfer cannot be reversed, so nothing leaves your wallet without you seeing the final numbers.+- **Depositing is scan-to-fund, after you sign.** The address is revealed only once the real-funds agreements are signed; the first **Add funds** press opens the signing dialog, and declining it means the sheet never opens. The **Add funds** sheet (`src/wallet-deposit.js`) renders a payment-request QR, not a bare address: a Solana Pay URI (`solana:<addr>?amount=&spl-token=`) or, for Base USDC, an EIP-681 transfer link, so a scanning wallet opens with the recipient, token, and amount pre-filled. While the sheet is open, a watcher re-reads the wallet's real balances against a baseline and announces the exact on-chain delta the moment the deposit lands; it backs off over time, suspends while the tab is hidden, and gives up rather than polling forever.+- **Moving money out is two-step by design.** When you submit the send form or the fund-agent form, the page does not sign anything. It calls the route with `simulate: true`, which runs the real balance, rent, and fee checks on the server and returns what the transfer would actually cost. Only after you read back the amount, recipient, asset, and network, and press **Confirm and send**, does anything get signed and broadcast, and that press prompts the real-funds agreements first if they are not already signed. A transfer cannot be reversed, so nothing leaves your wallet without you seeing the final numbers.- **It is the same API documented below.** The page has no privileged path: it is a session-authenticated client over these four endpoints, so anything it can do, the `curl` examples on this page can do too.Page code: `pages/wallet.html`, `src/master-wallet.js` (controller), `src/wallet-api.js` (the client), `src/wallet-deposit.js` (the deposit sheet), `public/master-wallet.css`. Not to be confused with `src/wallet.js`, which connects an **external** wallet such as Phantom and has nothing to do with the custodial master wallet.@@ -40,6 +40,7 @@ Funds flow one way through the platform's plumbing: master wallet to agent walle## Auth model: session plus CSRF- Every route requires a signed-in **session cookie**. Without one: `401 unauthorized`. There is no bearer or API-key path on these four routes, unlike most of the API.+- Every write that moves funds additionally requires that your account has **signed the real-funds agreements** (Terms of Service, Risk Disclosure, Agent Wallet Agreement). Without a current signature the route answers `403 risk_ack_required` and nothing is sent; sign once at [/legal/agreements](https://three.ws/legal/agreements). A `simulate: true` preview is exempt, as is reading. See [risk-acknowledgment.md](risk-acknowledgment.md).- 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.@@ -172,7 +173,7 @@ curl -sX POST https://three.ws/api/user/wallet/send \`usd_value` is populated for SOL (from the price feed) and for USDC (one to one); for any other mint it is `null`. Send is mainnet only.-Error shapes worth handling: `404 not_found` (no master wallet yet), `400 invalid_destination`, `400 invalid_amount`, `400 invalid_asset`, `400 insufficient_balance`, `400 insufficient_sol_for_fees`, `502 rpc_error` (balance or blockhash read failed, nothing signed), `502 send_failed` (the network rejected the transaction), `429` when the 5-per-day ceiling is spent.+Error shapes worth handling: `403 risk_ack_required` (the agreements are unsigned; nothing was sent), `404 not_found` (no master wallet yet), `400 invalid_destination`, `400 invalid_amount`, `400 invalid_asset`, `400 insufficient_balance`, `400 insufficient_sol_for_fees`, `502 rpc_error` (balance or blockhash read failed, nothing signed), `502 send_failed` (the network rejected the transaction), `429` when the 5-per-day ceiling is spent.## Funding an agent from the master wallet (this spends real funds)@@ -258,7 +259,7 @@ Two routes move real funds, irreversibly, the moment they return success:| `POST /api/user/wallet/send` | SOL or any SPL token, to **any address you name**. No allowlist. || `POST /api/user/wallet/fund-agent` | USDC or SOL, to **an agent you own**. |-As coded, the server-side protections are: a signed-in session (no API key can reach these), a single-use CSRF token per call, a hard ceiling of 5 outbound transactions per user per day, on-curve destination validation, and rent and fee reserves that prevent a sweep from bricking the account. That is the entire list. **There is no per-transaction cap, no daily USD cap, no destination allowlist, no freeze switch, no approval step, and no undo.** `simulate: true` on `send` and `fund-agent` is a preview, not a confirmation gate: a plain call skips it entirely.+As coded, the server-side protections are: a signed-in session (no API key can reach these), a signed set of real-funds agreements on the account, a single-use CSRF token per call, a hard ceiling of 5 outbound transactions per user per day, on-curve destination validation, and rent and fee reserves that prevent a sweep from bricking the account. That is the entire list. **There is no per-transaction cap, no daily USD cap, no destination allowlist, no freeze switch, no approval step, and no undo.** `simulate: true` on `send` and `fund-agent` is a preview, not a confirmation gate: a plain call skips it entirely.So the confirmation has to come from your client, before the call:diff --git a/docs/ux-flows/01-onboarding-creation.md b/docs/ux-flows/01-onboarding-creation.mdindex 62fe2002f..89f361859 100644--- a/docs/ux-flows/01-onboarding-creation.md+++ b/docs/ux-flows/01-onboarding-creation.md@@ -29,14 +29,14 @@---### Avatar Method Picker — `/create`-- **Source:** `pages/create.html` + `src/create.js` (imports `src/account.js`, `src/avatar-creator.js`, `src/guest-avatar.js`, `src/shared/template-picker.js`, `src/shared/crypto-optional.js`, `src/wallet-auth.js` inline)+- **Source:** `pages/create.html` + `src/create.js` (imports `src/account.js`, `src/avatar-creator.js`, `src/guest-avatar.js`, `src/shared/template-picker.js`, `src/shared/attended-rotation.js`, `src/shared/share-target.js`, `src/shared/wizard-return.js`; the page also loads `src/shared/crypto-optional.js` and `src/wallet-auth.js` as their own module scripts)- **Entry point:** Nav/landing CTA; reached from `/start` Step 1 "Editor" with `?wizard=1&next=`. Also handles `?fork=<avatarId>` deep-links (remix an existing avatar).- **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`.+ 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`. Under the hub, a footer line points a returning creator at everything they have already made (`/mine`, "My creations") and at `/play` for live token worlds. The avatar method cards live below at `#avatar-options`.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`).+ 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`). The recommended base-editor card is the page's only 3D preview and it is fully deferred: the card paints a poster image, and both the `model-viewer` element bundle and the model itself arrive on the first hover, focus or tap (`src/shared/attended-rotation.js`), so a visit that never touches the card pays for neither. Below the cards, a footnote sends "need a model to upload" to `/avatar-studio` or `/forge`, and "bringing an avatar from another platform" to `/import/rpm`.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).@@ -103,7 +103,7 @@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** (`/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`).+ 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`), Create another (`/create-agent`), and View my profile (`/profile`); a "Take it further" row carries Give it a voice (`/voice`), Embed it anywhere (`/studio?model=<avatar_model_url>`), Put it in a world (`/play`) and Launch its token (`/launchpad`). A line under the buttons tells the creator where the agent lives from now on: "Need it later? It is always waiting under My creations in the menu.", linking `/mine`.- **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 (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`.@@ -138,7 +138,7 @@- **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. 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.+ 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. Those checks can no longer strand the capture: every wait on a MediaPipe model is capped at 15 s by `withVisionDeadline` (`src/shared/mediapipe-assets.js`), past which the unrefined photo is submitted and the build proceeds, and a face count of `null` now means "no detector loaded" rather than "no face", so an unreachable model never accuses a good selfie of having no face in it. 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 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".@@ -146,7 +146,7 @@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 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.+- **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; the host probe is shared across callers and only a definitive "not there" answer demotes our own copy, since a probe that merely timed out used to hand the load to a CDN on every real page load); 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; 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).@@ -184,7 +184,7 @@- **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`; `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.+- **Empty / error states:** `showError(...)` for load failures; 401 → login redirect with return. The library picker no longer dead-ends on a failed grid: `avatar-gallery-picker.js` renders a `role="alert"` card ("Could not load avatars") that distinguishes a request that never reached three.ws from a service error and offers "Try again", which re-renders skeletons and reloads the page of avatars.- **Step count:** 1 required (navigate → editor); the editor itself is open-ended.---diff --git a/docs/ux-flows/02-forge-text-to-3d.md b/docs/ux-flows/02-forge-text-to-3d.mdindex 7181765a3..bd16e5e73 100644--- a/docs/ux-flows/02-forge-text-to-3d.md+++ b/docs/ux-flows/02-forge-text-to-3d.md@@ -18,7 +18,7 @@ Routing facts (from `vercel.json`):- **Source:**- `pages/forge.html` (~4200 lines: full composer/stage markup + styles)- `src/forge.js` (~3300 lines: main controller, catalog, engine/tier selection, job submit, polling, result, gating; imports `src/forge-timeline.js` for the generation stage timeline and `src/forge-compare.js` for side-by-side compare)- - `src/forge-prompt-studio.js` (Surprise-me + prompt coach; prompts come from the slot-grammar generator `src/forge-prompt-gen.js`), `src/forge-enhance.js` (AI prompt rewrite → `/api/forge-enhance`), `src/forge-directed-prompt.js` (reveals the server's art-director rewrite from the `directed_prompt` response field)+ - `src/forge-prompt-studio.js` (Surprise-me + prompt coach; prompts come from the slot-grammar generator `src/forge-prompt-gen.js`), `src/forge-enhance.js` (AI prompt rewrite → `/api/forge-enhance`), `src/forge-directed-prompt.js` (reveals the server's art-director rewrite from the `directed_prompt` response field, with copy, "use as my prompt", and a one-click "Try a variation" that re-fires the generation on the unchanged brief, since the director and the reference painter are stochastic and resolve it differently each run)- `src/forge-dropzone.js` (paste/drop image handling), `src/forge-reveal.js` (WebGL "materialize" dissolve overlay), `src/forge-wait.js` (rotating craft tips while generating)- `src/forge-refine.js` (in-browser geometry refine, no API), `src/forge-stylize.js` (→ `/api/forge-stylize`), `src/forge-optimize.js` (→ `/api/forge-remesh`), `src/forge-gameready.js` (→ `/api/forge-gameready`)- `src/forge-rig.js` (auto-rig → `POST /api/forge?action=rig`), `src/forge-materials.js` (PBR material restyle → `POST /api/material-studio?action=restyle`), `src/forge-conversational-refine.js` (free-text shape iteration → `POST /api/forge-iterate`), `src/forge-more-like-this.js` (one-tap material/finish variation chips), `src/forge-segment.js`@@ -33,18 +33,18 @@ 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 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.+ 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`; its empty-prompt message is shipped inline in `forge.html` and marked `data-no-i18n`, because an empty span that filled in on boot wrapped onto its own line and pushed the tiles, composer and chips down 38px), 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 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`.- 10. **Generating state**: a named stage timeline (`#gen-stages`, rendered by `forge-timeline.js`) animates; every row and state change is driven by a real `/api/forge` signal, so the lane decides which stages exist (a no-reference-image engine never shows one). Below it: an honest elapsed-vs-typical progress bar (asymptotic, never fakes 100%, recolors amber past the catalog ETA), a "feel free to leave this page" hint, and a **Cancel** button. When the API reports `cold_start` for a scale-to-zero self-hosted GPU lane, a "Waking up a GPU" warming card appears and is dismissed by the first real running poll, never by a timer (a keep-warm cron, `/api/cron/gpu-keepwarm`, holds allowlisted GPU workers open during peak hours). While waiting, `forge-wait.js` rotates curated craft tips. When the submit response returns a `preview_image_url`, the reference image paints into the preview pane.- 11. If the engine is the synchronous free draft lane, the POST returns the finished `glb_url` directly; otherwise `forge.js` polls `GET /api/forge?job=<id>` every interval until `status:"done"` (with `glb_url`), `failed`, or timeout.- 12. On done: `showResult()` sets the `<model-viewer src>`, plays the WebGL **materialize** reveal (`forge-reveal.js`, skipped under reduced-motion), shows the result bar, wires the **Download GLB** anchor, and (if `creation_id`) shows a "Saved ✓" auto-save chip. Geometry-first/sketch results with no reference image get a captured **poster** frame (`POST /api/forge-poster`).+ 10. **Generating state**: a named stage timeline (`#gen-stages`, rendered by `forge-timeline.js`) animates; every row and state change is driven by a real `/api/forge` signal, so the lane decides which stages exist (a no-reference-image engine never shows one). Below it: an honest elapsed-vs-typical progress bar (asymptotic, never fakes 100%, recolors amber past the catalog ETA), a "feel free to leave this page" hint, and a **Cancel** button. When the API reports `cold_start` for a scale-to-zero self-hosted GPU lane, a "Waking up a GPU" warming card appears and is dismissed by the first real running poll, never by a timer (a keep-warm cron, `/api/cron/gpu-keepwarm`, holds allowlisted GPU workers open during peak hours; every routed scale-to-zero lane is registered there, including `hunyuan3d`, the High image tier's default engine and the fleet's longest spin-up at 75 s, though it stays off by default because the region's L4 grant is already spoken for). While waiting, `forge-wait.js` rotates curated craft tips. The reference image no longer waits for the job id: the page mints a trace id, sends it with the submit, and polls `GET /api/forge?progress=<traceId>` while its own POST is still open, so the director's rewrite, the reference view and the extra view count paint as the server passes each real milestone (`api/_lib/forge-progress.js` writes the crumbs). It is fail-open, with no timers and no guessed crumbs: without a trace id, or on a deployment that does not serve the channel, the submit response's own `preview_image_url` still paints the reference pane a moment later.+ 11. If the engine is the synchronous free draft lane, the POST returns the finished `glb_url` directly; otherwise `forge.js` polls `GET /api/forge?job=<id>` every interval until `status:"done"` (with `glb_url`), `failed`, or timeout. The loop is built on `src/shared/resilient-poll.js`, so a backgrounded phone tab, a dropped radio, or the odd edge `502` is retried and woken on visibility rather than read as a dead job, with the give-up budget counted in attempts.+ 12. On done: `showResult()` sets the `<model-viewer src>`, plays the WebGL **materialize** reveal (`forge-reveal.js`, skipped under reduced-motion), shows the result bar, wires the **Download GLB** anchor, and (if `creation_id`) shows a "Saved ✓" auto-save chip. Under `prefers-reduced-motion` the result viewer drops `auto-rotate` (camera controls stay, so the model is still fully inspectable by drag, pinch and arrow key), and the "Nice model. What now?" handoff card retracts on its own instead of sitting over the result bar's own next-step buttons. The result action row carries seventeen tools and wraps, so every one of them stays clickable at 320px. Geometry-first/sketch results with no reference image get a captured **poster** frame (`POST /api/forge-poster`).13. (optional) User rates the model: **👍 Keep / 👎 Discard** (verdict) → `POST /api/forge-feedback`; or tags a category (Avatar/Creature/Item/Accessory/Scene/Vehicle) → `POST /api/forge-categorize`. (Data flywheel.)- 14. (optional) **Refine → <next tier>** — re-runs the exact same prompt/views one quality tier higher (re-enters step 9). Shown only when a higher tier exists and the job is re-runnable.+ 14. (optional) **Refine → <next tier>**: re-runs the exact same prompt/views one quality tier higher (re-enters step 9). Shown only when a higher tier exists and the job is re-runnable. Every user-initiated generation is stamped with a random seed that rides on the stored job, and Refine, Retry, "Generate anyway" and an automatic lane hop all replay it, so Refine returns *this* model at higher quality instead of a different object; only a fresh submit (and "Make another") mints a new seed.15. (optional) **Refine** panel (`forge-refine.js`) — instant in-browser geometry passes (weld/smooth/relax/decimate/subdivide), non-destructive, no API call, no rate limit. Download the refined GLB.16. (optional) **Iterate** (`forge-conversational-refine.js`): a free-text instruction against the model on screen ("make the helmet red", "add a cape") via `POST /api/forge-iterate` (polled). The only post-result action that changes the model's shape from natural language; same core as the MCP `refine_model` tool.17. (optional) **Stylize** (`forge-stylize.js`): voxels/bricks/lattice/low-poly geometric filters via `POST /api/forge-stylize` (worker job, polled), with a resolution slider, download, and revert.@@ -53,7 +53,7 @@ Routing facts (from `vercel.json`):20. (optional) **Optimize topology** (`forge-optimize.js`): tri/quad/low-poly remesh via `POST /api/forge-remesh` (polled).21. (optional) **Game-Ready** (`forge-gameready.js`): retopologize to a poly budget and export a textured GLB + FBX for Unity/Unreal via `POST /api/forge-gameready` (polled), with budget slider + wireframe preview. Gated on the same $THREE hold-or-pay model as High tier: the panel resolves the viewer's real entitlement first (a signed-in holding or a connected wallet, via `getAccess`/`attachTierPass`), a verified holder exports free, and a non-holder gets a server-quoted pay-per-export price in $THREE.22. (optional) **Split into parts** → links to `/segment?mesh=<glb>` (Parts Studio). **Compose** → `/compose?glb=<glb>` (Scene Composer / attach to avatar). **Place IRL** → `/irl?avatar=<glb>` (anchor the model in a real room).- 23. (optional) **Export** (`forge-export.js`): in-browser convert to OBJ / STL / PLY / USDZ (lazy three.js exporters, no upload).+ 23. (optional) **Export** (`forge-export.js`): the download split-button's format menu carries seven formats. OBJ / STL / PLY / USDZ convert in the browser (lazy three.js exporters, no upload); **FBX** and **3MF** have no browser exporter and are converted server-side by the remesh worker (`POST /api/forge-remesh` with `operation:"convert"`), which re-containers the mesh without touching geometry so a rigged model keeps its skeleton. A server format is a real polled job: it reports queued/converting, relays the converter's own reason on failure, and leaves a download-again link for a minute; starting a new generation retires a conversion still polling for the previous model.24. (optional) **Reel** (`forge-reel.js`): fully client-side cinematic capture of the model into a looping video (MP4 or WebM), a hero still, and a transparent-PNG cutout; no upload, no worker.25. (optional) **Embed** (`forge-embed-panel.js`): generate an embeddable web-component snippet for the model.26. (optional) **View in AR** (`forge-ar.js`) / model-viewer's `ar` (webxr/scene-viewer/quick-look): place the model in the room. The AR panel also links to the multi-model **AR Studio** (`/ar/studio?src=<glb>`).@@ -74,7 +74,7 @@ Routing facts (from `vercel.json`):- Submit/poll: `POST /api/forge`, `GET /api/forge?job=<id>`- Uploads: `POST /api/forge-upload` (presign) + `PUT` object storage- Flywheel: `POST /api/forge-feedback`, `POST /api/forge-categorize`, `POST /api/forge-poster`- - Galleries: `GET /api/forge-gallery?limit=24` (your creations), `GET /api/forge-gallery?scope=community&limit=24` (showcase, plus `&sort=` for the Forge-Off board), `POST /api/forge-vote` (showcase upvotes), `GET /api/forge-creation?id=` (share open), `DELETE /api/forge-creation?id=` (each "Your creations" card carries a two-tap arm-then-confirm delete, scoped to the owning `x-forge-client`; it erases the stored GLB, preview, and every recorded source photo upload, so an image-to-3D run's reference pictures leave object storage with it)+ - Galleries: `GET /api/forge-gallery?limit=24` (your creations), `GET /api/forge-gallery?scope=community&limit=24` (showcase, plus `&sort=` for the Forge-Off board), `POST /api/forge-vote` (showcase upvotes), `GET /api/forge-creation?id=` (share open); gallery and showcase card previews are requested through `resizedImageUrl()` (`src/shared/image-url.js` → `/api/img`), which asks for a 480px-wide server-resized WebP tile (20 to 40 KB) instead of the full-resolution render; same-origin, `data:` and `blob:` sources are passed through untouched. `DELETE /api/forge-creation?id=` (each "Your creations" card carries a two-tap arm-then-confirm delete, scoped to the owning `x-forge-client`; it erases the stored GLB, preview, and every recorded source photo upload, so an image-to-3D run's reference pictures leave object storage with it)- Post-processing jobs: `POST /api/forge-stylize`, `POST /api/forge-remesh`, `POST /api/forge-gameready`, `POST /api/forge-enhance`, `POST /api/forge-iterate` (all polled by `?job=`); `POST /api/forge?action=rig` (auto-rig, polled by `GET /api/forge?job=`); `POST /api/material-studio?action=restyle` (synchronous)- Payment: `forge-pay.js` → `src/token-pay.js` → `/api/token/quote` + `/api/token/settle` ($THREE)- Access/tier pass: `/api/three/access` (read) + tier-pass mint (referenced via `attachTierPass`/`getTierPass`)@@ -92,7 +92,7 @@ Routing facts (from `vercel.json`):- `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; 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).+ - Upload errors: per-slot states (503 uploads unavailable, 429 rate-limited, too-large/empty/wrong-type, network). `POST /api/forge-upload` now asks whether storage will *accept* the bytes (`objectStorageUsable()`, a cached signed one-key list) rather than whether the credential vars merely exist, so a rotated or whitespace-only R2 token answers `503 storage_unavailable` (or `503 unconfigured`, which falls the page back to accepting a public image URL) instead of handing out a signed URL whose CORS-less `403 SignatureDoesNotMatch` the browser could only report as "Network error during upload".- 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).@@ -135,7 +135,7 @@ Routing facts (from `vercel.json`):### 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). 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.+- **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. The server no longer ships that shell empty: `server/crawler-body.mjs` renders the same markdown into the response body (leading title stripped, since the hero already owns the `h1`), and the client replaces the root wholesale on load, so a crawler that never runs the fetch still reads the whole tutorial instead of the shell's "Tutorial not found" fallback. 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):**diff --git a/docs/ux-flows/03-3d-editing-viewer.md b/docs/ux-flows/03-3d-editing-viewer.mdindex 8c1975562..d80508454 100644--- a/docs/ux-flows/03-3d-editing-viewer.md+++ b/docs/ux-flows/03-3d-editing-viewer.md@@ -18,28 +18,28 @@ Routing summary (from `vite.config.js`):---### Scene Studio — `/scene`-- **Source:** `pages/scene.html`, `src/scene-studio/main.js`, vendored editor under `src/scene-studio/vendor/js/` (`Editor.js`, `Viewport.js`, `Menubar.*.js`, `Sidebar.*.js`, commands), `src/scene-studio/studio.css`, `src/shared/scene-handoff.js`.-- **Entry point:** `pages/scene.html` loads the CodeMirror/Draco vendor `<script>` chain, then `<script type="module" src="/src/scene-studio/main.js">` (scene.html:84). `main.js` constructs the vendored `Editor`, mounts Viewport/Toolbar/Script/Player/Sidebar/Menubar/Resizer/Animation panels into `#studio-app`, exposes `window.editor`/`window.THREE`, and inits IndexedDB-backed autosave/storage (`editor.storage.init`, main.js:36-144). The surface is dark-locked (`data-theme='dark'` re-pinned, main.js:11).-- **Prerequisites / gates:** None. No auth, no wallet, no $THREE gate. Works fully anonymously; an empty default scene loads immediately. State persists locally via `editor.storage` (autosave to IndexedDB, debounced ~1s, main.js:111-143).+- **Source:** `pages/scene.html`, `src/scene-studio/main.js`, vendored editor under `src/scene-studio/vendor/js/` (`Editor.js`, `Viewport.js`, `Menubar.*.js`, `Sidebar.*.js`, commands), `src/scene-studio/studio.css`, plus the sibling modules that layer three.ws behavior over the vendored editor without editing `vendor/**`: `src/scene-studio/loader.js` (the decoder-wired GLB add), `actions.js` (Import from Forge / Export presets / Share), `empty-state.js` (first-run overlay), `toolbar-a11y.js` (accessible names for the transform and animation transport buttons), and `src/shared/scene-handoff.js`.+- **Entry point:** `pages/scene.html` loads the CodeMirror/Draco vendor `<script>` chain, then `<script type="module" src="/src/scene-studio/main.js">` (scene.html:88). `main.js` constructs the vendored `Editor` (main.js:41), mounts Viewport/Toolbar/Script/Player/Sidebar/Menubar/Resizer/Animation panels into `#studio-app`, mounts the three.ws action bar, a11y labels and empty state over them (main.js:77-87), exposes `window.editor`/`window.THREE`, and inits IndexedDB-backed autosave/storage (`editor.storage.init`, main.js:108-163). The surface is dark-locked (`data-theme='dark'` re-pinned, main.js:11).+- **Prerequisites / gates:** None. No auth, no wallet, no $THREE gate. Works fully anonymously; an empty default scene loads immediately. State persists locally via `editor.storage` (autosave to IndexedDB, debounced ~1s, main.js:132-162).- **Steps (N):**- 1. Arrive at `/scene`. Editor mounts; prior autosaved scene restored from IndexedDB, or `sceneEnvironmentChanged('Default')` fires for a fresh scene (main.js:89-97).- 2. (optional, deep-link) Arrive via `/scene?model=<glb_url>&name=<label>` (hand-off from Forge/Parts). `importModelFromQuery()` validates the URL is `https://` or same-origin relative, fetches the GLB, parses it with the Draco/KTX2/Meshopt-wired GLTFLoader, adds it via `AddObjectCommand`, selects it, and strips the query from the address bar (main.js:186-206).- 3. (optional, deep-link) Arrive via `/scene?handoff=1` (hand-off from Animation Studio `/pose`). `importHandoffAnimation()` reads the baked GLB from IndexedDB via `takeSceneHandoff()`, adds it, and attaches a `Play Animation` player script so the embedded clip plays live and records to video (main.js:208-251).- 4. Import a model: drag a GLB/glTF (or a folder of glTF+textures) anywhere on the page → `drop` handler routes to `editor.loader.loadItemList`/`loadFiles` (main.js:255-271); or use **File ▸ Import** file picker (`Menubar.File.js`:185-211).+ 1. Arrive at `/scene`. Editor mounts; prior autosaved scene restored from IndexedDB, or `sceneEnvironmentChanged('Default')` fires for a fresh scene (main.js:110-115). A fresh scene is no longer a silent black grid: the first-run overlay (`empty-state.js`) names the three ways to start (drag a `.glb`/`.gltf`, pick a primitive from **Add**, or pull in a model you already generated) and retires itself the moment the scene holds anything, a restored autosave included. The transform toolbar is lifted above that card in `studio.css`, because the vendored `#toolbar` leaves `z-index` at `auto` and on a phone-height viewport it parks inside the band the overlay covers.+ 2. (optional, deep-link) Arrive via `/scene?model=<glb_url>&name=<label>` (hand-off from Forge/Parts). `importModelFromQuery()` validates the URL is `https://` or same-origin relative, fetches the GLB, parses it with the Draco/KTX2/Meshopt-wired GLTFLoader (`loader.js`), adds it via `AddObjectCommand`, selects it, and strips the query from the address bar (main.js:178-202).+ 3. (optional, deep-link) Arrive via `/scene?handoff=1` (hand-off from Animation Studio `/pose`). `importHandoffAnimation()` reads the baked GLB from IndexedDB via `takeSceneHandoff()`, adds it, and attaches a `Play Animation` player script so the embedded clip plays live and records to video (main.js:225-251).+ 4. Import a model: drag a GLB/glTF (or a folder of glTF+textures) anywhere on the page → `drop` handler routes to `editor.loader.loadItemList`/`loadFiles` (main.js:260-273); or use **File ▸ Import** file picker (`Menubar.File.js`); or **Import from Forge** on the three.ws action bar, which takes a GLB URL in a shared `<dialog>` that validates the link inline rather than a native `prompt()` (`actions.js`).5. Add primitives/lights/cameras via the **Add** menu (`Menubar.Add.js`); add scripts via **Script** panel (CodeMirror).6. Select an object in the Viewport or the Outliner (Sidebar). The transform gizmo attaches.7. Transform with the gizmo — translate / rotate / scale (Toolbar mode buttons + Viewport `TransformControls`).8. Edit properties in the Sidebar: object transform, **Geometry**, **Material** (color/maps/roughness/metalness/etc.), **Scene** (background, environment, fog), per-light settings.9. (optional) Edit a script in the Script panel; (optional) press **Play** (`Player`) to run scene scripts/animations live.- 10. (optional) Keyframe/inspect animations in the Animation panel (timeline at bottom; `animationPanelChanged` resizes Viewport, main.js:70-85).+ 10. (optional) Keyframe/inspect animations in the Animation panel (timeline at bottom; `animationPanelChanged` resizes Viewport, main.js:90-104; the play/pause/stop transport is given accessible names and pressed state by `toolbar-a11y.js`).11. (optional) **File ▸ New** (empty / templates) to reset; undo/redo via the command history.- 12. Export via **File ▸ Export** submenu: GLB, GLTF, OBJ, PLY (ASCII/binary), STL (ASCII/binary), USDZ, DRC/Draco (`Menubar.File.js`:212-435). A download is triggered (e.g. `scene.glb`, `scene.gltf`).+ 12. Export via **File ▸ Export** submenu: GLB, GLTF, OBJ, PLY (ASCII/binary), STL (ASCII/binary), USDZ, DRC/Draco (`Menubar.File.js`). A download is triggered (e.g. `scene.glb`, `scene.gltf`). The action bar's **Export presets** ("Web GLB", "AR bundle (USDZ)") are one click for the same two exports, and **Share / Embed** uploads the scene as a GLB and opens the platform's embed panel (iframe / web component / `<agent-3d>` snippet). The bar docks beside the sidebar and follows it as it is dragged, instead of sitting on top of the Scene/Project/Settings tabs.13. (optional) **File ▸ Export Project** saves the editor scene as a `.json` project; **File ▸ Open** re-imports a `.json` project (`Menubar.File.js`:91-185).14. (optional) **Render** menu → render an image or video of the scene via `APP.Player` (`Menubar.Render.js`).-- **Decision points / branches:** Fresh scene vs restored autosave (main.js:89-104). Deep-link arrival (`?model=` add, `?handoff=1` animation import) vs plain manual import. `#file=<url>` hash → prompts to open a remote `.json` project, replacing the scene (main.js:286-299). Drag of a folder (`DataTransferItemList`) vs single files.-- **External calls / dependencies:** `fetch(modelUrl)` for `?model=` deep-link GLB (main.js:195); IndexedDB via `editor.storage` (autosave) and `src/shared/scene-handoff.js` (`takeSceneHandoff`, DB `three-ws-scene-handoff`); Draco decoder at `/three/draco/gltf/` (shared with the main app), KTX2 transcoder at `/scene-studio/basis/` (main.js:163-165); local CodeMirror/esprima/acorn/tern vendor libs. Imports: glTF/GLB (+ companion textures), `.json` editor projects. Exports: GLB, GLTF, OBJ, PLY, STL, USDZ, DRC, JSON project, rendered image/video. No platform API calls.+- **Decision points / branches:** Fresh scene vs restored autosave (main.js:109-118). Deep-link arrival (`?model=` add, `?handoff=1` animation import) vs plain manual import. `#file=<url>` hash → prompts to open a remote `.json` project, replacing the scene (main.js:285-299). Drag of a folder (`DataTransferItemList`) vs single files.+- **External calls / dependencies:** `fetch(modelUrl)` for `?model=` deep-link GLB (main.js:187); IndexedDB via `editor.storage` (autosave) and `src/shared/scene-handoff.js` (`takeSceneHandoff`, DB `three-ws-scene-handoff`); Draco decoder at `/three/draco/gltf/` (shared with the main app), KTX2 transcoder at `/scene-studio/basis/` (both wired in `loader.js`); local CodeMirror/esprima/acorn/tern vendor libs. Imports: glTF/GLB (+ companion textures), `.json` editor projects. Exports: GLB, GLTF, OBJ, PLY, STL, USDZ, DRC, JSON project, rendered image/video. No platform API calls.- **Success state:** Imported/transformed objects appear in the Viewport + Outliner; autosave indicator (`savingStarted`/`savingFinished`) confirms persistence; export triggers a file download.-- **Empty / error states:** Empty default scene with grid + default environment when no autosave exists. `?model=` fetch failure → `alert('Could not load the handed-off model … drag the GLB file into the editor instead.')` (main.js:204). `?handoff=1` IndexedDB unavailable → silently no-ops; load failure → `alert('Could not load the animation … Try Export GLB on /pose and drag the file in instead.')` (main.js:248-249). No-GLB-in-drop handled by the vendored loader.+- **Empty / error states:** A fresh scene shows the grid, the default environment, and the first-run card telling the visitor how to start (see step 1). Failures report through the shared toast (`src/shared/toast.js`), not a native `alert()`: `?model=` fetch failure → "Could not load the handed-off model: … Download the GLB and drag the file into the editor instead." (main.js:196-200); `?handoff=1` IndexedDB unavailable → silently no-ops, load failure → "Could not load the animation from the Animation Studio: … Try Export GLB on /pose and drag the file in instead." (main.js:245-249). No-GLB-in-drop handled by the vendored loader.- **Step count:** ~7 required (arrive → import → select → transform → edit material → edit scene → export) + ~7 optional (deep-link arrival, primitives/lights, scripts, Play, animation timeline, project save/open, render).---@@ -81,7 +81,7 @@ Routing summary (from `vite.config.js`):5. Pose with FK (default mode): rotate gizmo on the selected bone + X/Y/Z rotation sliders + "Reset this bone" (`renderControlsPanel`, 640-696).6. (optional) Pose with IK: toggle IK (top bar or **I** key; disabled if the rig exposes no limb chains) and drag a glowing cyan hand/foot handle → `rig.solveIK` (pose-studio.js:585-630). FK and IK are mutually exclusive.7. (optional) Apply a preset pose from the grouped grid (Standing/Action/Sitting/Expressive, `poseFromMannequinPreset`, pose-studio.js:734-758).- 8. (optional, rigged GLB only) Apply a curated motion clip or AI-generate one: `AnimationLibrary` cards from `/animations/manifest.json` retarget+play live; text box POSTs `/api/forge-motion` and polls for the clip (animation-library.js:27, 102, 541-560).+ 8. (optional, rigged GLB only) Apply a curated motion clip or AI-generate one: `AnimationLibrary` cards from `/animations/manifest.json` retarget+play live; a clip the curated manifest does not carry (an `mx-*` name deep-linked from the `/animations` gallery) is resolved one at a time through `GET /api/animations/library?name=<name>` rather than by downloading the whole multi-megabyte catalog (`_lookupFullLibrary`, animation-library.js:163-172); the text box POSTs `/api/forge-motion` and polls for the clip. That endpoint has exactly one backend, the self-hosted text2motion GPU worker behind `GCP_TEXT2MOTION_URL` (no vendor fallback, so an unset URL is an honest `503`), and it meters against the free-lane rate bucket rather than the paid one.9. Keyframe the timeline: pose, then **Add keyframe** / **K** (`captureKeyframe`, 1262-1273); drag diamonds to retime, set per-key easing, set name/duration/FPS/loop (pose-studio.js:1275-1394).10. Scrub / play: drag the track or arrow keys; transport play/pause (Space), stop, jump start/end (Home/End), loop toggle. Playback slerp-interpolates poses via `sampleAtTime` (pose-animation.js:136).11. (optional) Import a pose JSON (`#pose-import-json`) → applies a single static pose (pose-studio.js:917-934).@@ -89,7 +89,7 @@ Routing summary (from `vite.config.js`):- **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`; 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.+- **Empty / error states:** Timeline `#tl-empty` "Pose the figure, then press K…" until a keyframe exists, with the ruler's tick labels faded out while it shows (`#tl-track[data-empty='true']`), since an empty timeline has nothing to measure and the ticks only competed with the hint; 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).---@@ -135,7 +135,7 @@ Routing summary (from `vite.config.js`):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.+- **Decision points / branches:** Route mode dispatch (app.js:288-394): kiosk/embedChat (chromeless), `/deploy` (RegisterUI wizard), `/showcase` (the ERC-8004 directory: every indexed on-chain agent that carries a 3D glTF body, rendered by `src/erc8004/showcase.js`; like `/deploy` it demotes the shell's wordmark `h1` so the page has one real heading, and upgrades the legacy flex footer to the horizon footer, which is what used to drag the document sideways at 320px), 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", 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`.diff --git a/docs/ux-flows/04-embed-widget-studio.md b/docs/ux-flows/04-embed-widget-studio.mdindex c8776df0b..ac03dcbc3 100644--- a/docs/ux-flows/04-embed-widget-studio.md+++ b/docs/ux-flows/04-embed-widget-studio.md@@ -24,7 +24,7 @@ Routing recap (from `vercel.json`):### Widget Studio — `/studio`- **Source:** `public/studio/index.html`, `public/studio/studio.js`, `public/studio/studio.css`, `public/studio/launch-panel.js`, `public/studio/knowledge-panel.js`. Preview iframe loads `/widget` (slim `src/app.js` shell). APIs: `/api/auth/me`, `/api/avatars`, `/api/avatars/public`, `/api/avatars/:id`, `/api/widgets`.- **Entry point:** Direct nav to `/studio`; "Create yours" / "Open the Studio" CTAs on `/widgets`; "Open Studio →" on `/features/studio`; "Open in Studio" links from gallery cards (`/studio?template=<id>`); the "Configure in wizard" links on avatar/agent pages and the dashboard; deep links `?edit=<id>`, `?type=<type>`, `?model=<url>`, `?avatar=<id>`, plus the inherited embed-editor form `?mode=static|idle|walking|chat` with `?avatar=`, `?controls=`, `?env=`, `?bg=`, `?width=`, `?height=`, `?autoplay=`, `?speed=`, `?ground=`, `?gestures=`, `?badge=`. Those same names are written back into `location.search` as you edit a URL-baked widget, so a configured studio URL is itself a shareable artifact.-- **Prerequisites / gates:** None to try, and for two widget types, none to finish. A built-in **demo avatar (CZ, `/avatars/cz.glb`)** is preloaded so an anonymous visitor can configure and preview. The **walking-avatar** and **agent-chat** types bake their whole configuration into the embed URL, so a signed-out visitor can configure, generate and copy a working snippet with no account and no database row (the modal hides the `/w/<id>` share URL and the script-tag snippet, which do need one, and says what signing in adds). Every other type stores config server-side, so **saving a draft or embedding with them requires sign-in** (`/login?next=/studio`) and an owned/public avatar. The demo avatar can generate an embed (pointing at a baked demo fixture, e.g. `wdgt_demo_talking`) but cannot save. No $THREE gate. ⚡ Launch tab can optionally launch the agent's coin via `launch-panel.js` (lane toggle: pump.fun or the three.ws curve; oversized token images are downscaled in-browser instead of rejected).+- **Prerequisites / gates:** None to try, and for two widget types, none to finish. A built-in **demo avatar (CZ, `/avatars/cz.glb`)** is preloaded so an anonymous visitor can configure and preview. The **walking-avatar** and **agent-chat** types bake their whole configuration into the embed URL, so a signed-out visitor can configure, generate and copy a working snippet with no account and no database row (the modal hides the `/w/<id>` share URL and the script-tag snippet, which do need one, and says what signing in adds). Every other type stores config server-side, so **saving a draft or embedding with them requires sign-in** (`/login?next=/studio`) and an owned/public avatar. The demo avatar can generate an embed (pointing at a baked demo fixture, e.g. `wdgt_demo_talking`) but cannot save. No $THREE gate. ⚡ Launch tab can optionally launch the agent's coin via `launch-panel.js` (lane toggle: pump.fun or the three.ws curve; oversized token images are downscaled in-browser instead of rejected). The coin-type radio group offers agent / regular / mayhem / USDC / holder-reward / open-source-reward, and a `?reward=` deep link carried in from Launch Studio (`{platform,login}` or `{address}`) pre-fills the creator-fee recipient and is passed through to the Fees & rewards step, so the routing a recipe promised is what the coin ships with. Targets the wizard has no create-time control over are not offered at all.- **Steps (10):**1. Page boots → `fetchMe()` (`/api/auth/me`) resolves user; user menu renders (signed-out shows "Sign in"); 3-column layout unhides.2. System renders the **widget-type grid** (11 ready types: turntable, animation-gallery, talking-agent, passport, hotspot-tour, pumpfun-feed, kol-trades, live-trades-canvas, bonding-curve, walking-avatar, agent-chat) and **avatar list** (`loadAvatars()` → demo avatar + `/api/avatars?limit=100` for signed-in users, with skeleton cards while loading).@@ -44,7 +44,7 @@ Routing recap (from `vercel.json`):- 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). 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`).+- **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 11 are `ready`).- **Step count:** 10 required (+5 optional)---@@ -117,12 +117,12 @@ Routing recap (from `vercel.json`):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 ↗** → `/studio?…` in a new tab (an agent opens the Agent Chat widget type, an avatar opens the walking-avatar embed).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.+ 4. Paste the iframe or `<agent-3d>` snippet on any third-party site → the agent renders inline. `/agents/<id>/embed` serves `pages/agent-embed.html`, whose inline module mounts `src/viewer.js` + `src/agent-identity.js` / `agent-avatar.js` / `agent-protocol.js` / `embed-action-bridge.js` and speaks the frozen `agent:*` v1 postMessage bridge (`agent:hello` → `agent:ready`, `agent:action`, `agent:ping`/`agent:pong`, every payload carrying `agentId` so a host page with several frames can route them); it also honors the owner's embed policy and refuses to render when `surfaces.iframe` is off. The avatar-only targets (`/embed/avatar/<handle>`, `/a-embed.html`) run `src/avatar-embed.js` and its separate `v1.avatar.*` bridge. Done.- **Decision points / branches:**- 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).+- **External calls / dependencies:** `/agents/<id>/embed` and `/agents/<id>?embed=1` (final), `/dist-lib/agent-3d.js` (web component), the agent's GLB URL, `/studio?mode=chat&avatar=<agentId>` or `/studio?avatar=<avatarId>` (the wizard link, since the Widget Studio absorbed the standalone `/embed` editor and reads the same parameter names), `/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)@@ -144,7 +144,7 @@ Routing recap (from `vercel.json`):- **Entry point:** `/avatar-studio` or `/create/studio` (create from `default.glb`); `?edit=<id>` reloads a saved avatar.- **Prerequisites / gates:** Anyone can build/preview from the base template. **Saving requires sign-in** (so it persists to the account). No $THREE gate. This is the *upstream* builder — the avatar it produces becomes selectable in Widget Studio and embeddable via the SharePanel/embed modals.- **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).+ 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 whose switcher chip advertises 300+ sliders, matching the 306 identity morphs the base now bakes); 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 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.@@ -162,5 +162,8 @@ Routing recap (from `vercel.json`):## Cross-flow notes- **`/widget` shell** is the shared render surface: Studio + gallery previews and the `/embed.js` script-tag embed all point at `/widget#widget=<id>&kiosk=true`.- **`embed.js`** (`public/embed.js`) is the script-tag loader: reads `data-widget` / `data-widget-url`, `data-width/height/radius/border`, `data-reveal`, `data-poster`, `data-priority`, `data-motion`, mounts a sandboxed iframe at the script position, and supports multiple embeds per page.-- **Web component `<agent-3d>`** (`/dist-lib/agent-3d.js`) is the first-class embedding primitive surfaced by SharePanel and AgentEmbedModal; it observes `agent-id`, `background`, `name-plate` attributes.-- **avatar-embed runtime** (`src/avatar-embed.js`) backs `/embed/avatar/<handle>`, `/a-embed.html`, and the agent embed; exposes the `v1.avatar.*` postMessage bridge (speak, emote, morphs, lookAt, mocap, idle, hotkeys, mic, state) plus third-party-compatible event aliases and a same-origin BroadcastChannel control surface.+- **Web component `<agent-3d>`** (`/dist-lib/agent-3d.js`, authored in `src/element.js`) is the first-class embedding primitive surfaced by SharePanel and AgentEmbedModal; its observed attributes include `src`, `agent-id`, `avatar-id`, `mode`, `background`, `name-plate`, `avatar-chat`, `avatar-walk` and `sonar`. `sonar` only *permits* acoustic hand control: nothing opens a microphone or emits the ultrasonic carrier until the host page calls `startSonar()` behind a real user gesture, and the sensing modules under `src/sonar/` are imported on that first call, so an embed that never calls it ships none of them. Each recognised gesture fires a cancelable `sonar-gesture` event, so a host page can `preventDefault()` and drive its own surface instead of the default (sweep steps the gesture cast, push dollies the camera, a held lift turns it). Removing the attribute stops a live session.+- **avatar-embed runtime** (`src/avatar-embed.js`) backs `/embed/avatar/<handle>` and `/a-embed.html` (the agent embed at `/agents/<id>/embed` is a separate page, see above); exposes the `v1.avatar.*` postMessage bridge (speak, emote, morphs, lookAt, mocap, idle, hotkeys, mic, state) plus third-party-compatible event aliases and a same-origin BroadcastChannel control surface. Three things it does that an embedder feels directly:+ - **A stored avatar always renders through the same-origin proxy `/api/avatars/<id>/glb`**, never the `url` the API hands back. That URL is a presigned `r2.cloudflarestorage.com` read for a private avatar and the public `r2.dev` domain for a shared one; the first sends no `access-control-allow-origin` at all and the second allows only the three.ws origin, so GLTFLoader was CORS-blocked on a dev server, a preview host, or any embedding page on another domain. The proxy carries the session cookie through the permission gate and falls back to the public bucket when the signed read is refused. The optimization lane (`?lod=`, `?textureSize=`, `?morphs=`, `?draco=1`) takes the id and only for a public or unlisted avatar; a private one stays on the unoptimized proxy rather than 404ing.+ - **A load failure reads as a sentence, not a transport string.** `src/shared/viewer-error-text.js` maps the failures a visitor can hit onto plain language ("This avatar is private. Sign in with the account that owns it.", "The avatar service is unavailable. Refresh to try again.", "Connection lost. Check your network and refresh.", "This avatar's 3D file could not be read."); the raw rejection goes to the console for whoever is debugging the embed.+ - **`?animation=` / `?anim=` / `?pose=` resolves a full-library clip one at a time.** A UUID or `user:` id plays through `playAnimationById`, a name in the curated `/animations/manifest.json` crossfades straight in, and anything else is fetched with `GET /api/animations/library?name=<name>` and appended as a single def, instead of pulling the over-a-megabyte full catalog to find one entry.diff --git a/docs/ux-flows/05-discovery-social.md b/docs/ux-flows/05-discovery-social.mdindex d2461d07a..5ced31e65 100644--- a/docs/ux-flows/05-discovery-social.md+++ b/docs/ux-flows/05-discovery-social.md@@ -13,6 +13,7 @@ Routing recap (from `vercel.json`):| `/community` | `pages/community.html` | inline live-activity module in page || `/walk` | `pages/walk.html` | `src/walk.js` (+ `src/community/coin-world-boot.js`) || `/irl` | `pages/irl.html` | `src/irl.js` (+ `src/irl/*`, `src/irl-net.js`) |+| `/irl/sign` | `pages/irl-sign.html` | `src/irl-sign.js` || `/irl-privacy` | `pages/irl-privacy.html` | (static content) || `/reputation` | `public/reputation/index.html` | `public/reputation/reputation.js` || `/lookup` | `public/lookup.html` | inline module in page |@@ -36,7 +37,7 @@ Routing recap (from `vercel.json`):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 → 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.+- **External calls / dependencies:** `GET /api/explore`, `GET /api/auth/me`, `/api/discover-detail` (detail nav), the `model-viewer` element bundle (no longer a script tag on every visit: `src/shared/model-viewer-loader.js` requests it, with its CDN failover chain, only once a card carrying a GLB comes within a screen of the viewport), clipboard API.- **Success state:** Grid of agent cards with live/static thumbnails + totals line; deep-linkable filtered view via `replaceState`.- **Empty / error states:** Filtered-empty → "No agents match these filters yet" + Clear filters button. Unfiltered-empty → "No agents indexed yet… forge a 3D model." Fetch error → inline error with Retry button.- **Step count:** 2 required (+6 optional)@@ -69,7 +70,7 @@ Routing recap (from `vercel.json`):- **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; only clips whose manifest entry carries a `thumb` get a thumbnail request, the rest show the icon placeholder without a doomed fetch).+ 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`, loaded on demand from the R2 CDN one bounded 1000-clip page at a time: a first paint costs exactly one page plus `?facets=1`, a half-kilobyte response that carries the catalog's true size and per-category counts so the hero line and the filter chips read exact from the start; further pages are fetched only when the reader reaches the end of the grid, and searching, filtering or re-sorting drains the remaining pages in the background because those run client-side over every clip. 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).@@ -106,7 +107,7 @@ Routing recap (from `vercel.json`):- **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; 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.+ 3. (optional) User clicks a channel card: Agent Spotlight (`/spotlight`, the community showcase), Follow on X (`@trythreews`), GitHub (`nirholas/three.ws`), Contributors (`/contributors`, the thank-you roll), 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, t.me, IBM Community), mailto, clipboard API, footer newsletter script.@@ -125,19 +126,19 @@ 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 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.+ 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 (broadcast bubble; Enter also opens it, but only from the scene: Enter now belongs to whatever owns it, so a focused HUD button, link, input or summary keeps the key), 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.- **Success state:** Avatar driven smoothly around the world (joystick/WASD), camera follows; optionally on the real floor via AR; remote players + chat visible if multiplayer connected.-- **Empty / error states:** Avatar load fail → error pill + "try the default avatar". Camera API absent → AR button disabled w/ tooltip. Camera denied → sticky "camera permission denied". Physics WASM fail → silent legacy fallback. Multiplayer offline → "unavailable", solo play continues. Recording unsupported → status error. Avatar picker w/o auth → "Sign in to use your avatars".+- **Empty / error states:** Avatar load fail → error pill + "try the default avatar". Camera API absent → AR button disabled w/ tooltip. Camera denied → sticky "camera permission denied". Physics WASM fail → silent legacy fallback. Multiplayer offline → "unavailable", solo play continues. Recording unsupported → status error. Avatar picker on 401/403 → "Sign in to use your avatars" with a `/login` link; any other picker failure (5xx, offline, a parse error) → "Could not load your avatars." with a Try again button, because telling a signed-in walker to sign in is both wrong and unactionable.- **Step count:** 3 required (load, move, orbit) (+ ~12 optional)---### IRL — `/irl`-- **Source:** `pages/irl.html` (WebGL-gate inline boot), `src/irl.js`, `src/irl/*` (`onboarding.js`, `floor-anchor.js`, `room-anchor.js`, `room-session.js`, `room-mode.js`, `tap-pick.js`, `gps-lifecycle.js`, `discovery.js`, `privacy-center.js`, `proximity-band.js`, `proximity-cue.js`, `sensor-fusion.js`, `share-frame.js`, `map-place.js`, `marker-mode.js` + `marker-anchor.js`/`marker-pose.js`/`qr-detect.js` (QR-marker indoor colocalization), `camera-fov.js`, `load-queue.js`, `perf-budget.js`, `pin-celebration.js`, `pin-idle.js`, and more), `src/ar/*` (`pinch-scale.js`, `quick-look.js`, `quicklook-banner.js`, `placement-capability.js`, `depth-occlusion.js`, `estimated-lighting.js`), `src/irl-net.js`-- **Entry point:** `pages/irl.html` runs an inline WebGL-support check; if supported it `import('/src/irl.js')`, else it renders a designed "This device can't run IRL AR" state with "Browse agents"/"Open marketplace" actions. URL param `?avatar=` chooses the placed agent.+- **Source:** `pages/irl.html` (WebGL-gate inline boot), `src/irl.js`, `src/irl/*` (`onboarding.js`, `floor-anchor.js`, `room-anchor.js`, `room-session.js`, `room-mode.js`, `tap-pick.js`, `gps-lifecycle.js`, `discovery.js`, `privacy-center.js`, `proximity-band.js`, `proximity-cue.js`, `sensor-fusion.js`, `share-frame.js`, `map-place.js`, `marker-mode.js` + `marker-anchor.js`/`marker-pose.js`/`qr-detect.js` (QR-marker indoor colocalization), `camera-fov.js`, `load-queue.js`, `perf-budget.js`, `pin-celebration.js`, `pin-idle.js`, `pin-talk.js` (the live conversation inside the inspect sheet), `pin-ar.js` (pure AR-lane routing), `visit-link.js` + `visit-banner.js` (the `?pin=` visit link and its "you're here to meet" banner), and more), `src/ar/*` (`pinch-scale.js`, `quick-look.js`, `quicklook-banner.js`, `placement-capability.js`, `depth-occlusion.js`, `estimated-lighting.js`), `src/irl-net.js`+- **Entry point:** `pages/irl.html` runs an inline WebGL-support check; if supported it `import('/src/irl.js')`, else it renders a designed "This device can't run IRL AR" state with "Browse agents"/"Open marketplace" actions. URL param `?avatar=` chooses the placed agent; `?pin=<id>` is the scannable **visit link** (what the printable sign at `/irl/sign?pin=<id>` encodes as a QR), and `parseVisitTarget` hands it to `mountVisitBanner`, which names the agent the visitor came to meet from the coordinate-free public agent card and steps aside the moment the presence-gated nearby read returns that pin.- **Prerequisites / gates:** No auth, no wallet (anonymous `irl_device_token` in localStorage). **WebGL** required (hard gate at HTML load). Requested progressively via `onboarding.ensurePermission(...)`: **camera** (`getUserMedia`) on first "Camera AR" tap; **motion** (`DeviceOrientationEvent.requestPermission` on iOS 13+) when locking; **geolocation** (`navigator.geolocation.watchPosition`, enableHighAccuracy) when locking/discovering. None are hard blockers — each has a designed fallback.- **Steps (7 required + optional):**1. Page loads (WebGL OK) → Three.js scene + default/`?avatar=` GLB; device token restored; onboarding/discovery initialized; subtitle "Turn on Camera AR, then tap Pin here to anchor your agent." Discovery empty-state CTA visible.@@ -145,18 +146,34 @@ Routing recap (from `vercel.json`):3. User taps **Pin here** → `setLocked(true)` requests **location** (`watchPosition`) and **motion** (iOS `DeviceOrientationEvent.requestPermission`), waits briefly for a compass sample, captures the gyro lock pose; if GPS not yet ready shows "Getting your location…".4. On first GPS fix → anchors the pin, begins 10s nearby polling, joins the IrlNet presence room (Colyseus, optional).5. User aims at the floor spot and **taps the canvas** → optional caption → Confirm → `commitPin()` → `POST /api/irl/pins` with `{ lat, lng, heading, caption, avatarUrl, avatarName, deviceToken, agentId, anchor: { yawDeg, source: 'gyro-gps'… } }`.- 6. System polls `GET /api/irl/pins?lat=&lng=&radius=60` every 10s; nearby agents spawn (LOD: dot → impostor → full mesh), name labels + confidence rings render; crossing the ~40m ENTER band fires the proximity-arrival cue (haptic + chime + directional glow). Tapping a nearby agent opens a bottom sheet → "View" (`GET /api/irl/agent-card`), "Pay" ($THREE x402), "Message"; interactions `POST /api/irl/interactions`. A `pay` is the one interaction that names money, so it is never taken on the caller's word: it must carry a well-formed on-chain signature paying an allow-listed mint, it is de-duped globally by that signature, and the transaction is verified on-chain (exists, succeeded, moved at least the amount claimed, and credited one of the agent's own payout wallets when any are on record). A settlement the RPC cannot see yet lands with `verified_at` null, counting for nothing and notifying nobody until `api/cron/settlement-verify.js` proves or discards it.+ 6. System polls `GET /api/irl/pins?lat=&lng=&radius=60` every 10s; nearby agents spawn (LOD: dot → impostor → full mesh), name labels + confidence rings render; crossing the ~40m ENTER band fires the proximity-arrival cue (haptic + chime + directional glow). Tapping a nearby agent opens a bottom sheet (`GET /api/irl/agent-card`) that leads with **Talk** and **View in AR**, then "Pay via x402", "View profile" and a message form; interactions `POST /api/irl/interactions` (`view` / `tap` / `message` / `pay` / `talk`). **Talk** (`src/irl/pin-talk.js`) opens a live spoken conversation with that agent in the sheet, streaming `/api/chat` in the agent's persona (an anonymous pin speaks from its `system_prompt`, never a fabricated agentId) and logging exactly one `talk` interaction per conversation, which ends when the sheet closes. **View in AR** stands ANY discovered agent, not just the viewer's own, on the visitor's real floor, routed per device (`src/irl/pin-ar.js`): iOS bakes the pin's GLB to an animated USDZ for ARKit Quick Look with a "Talk to <name>" banner whose tap reopens the sheet with the conversation live, a WebXR device enters the same hit-test session view-only with that pin's model, and anything else opens the device-aware `/api/ar` launcher in a new tab. A `pay` is the one interaction that names money, so it is never taken on the caller's word: it must carry a well-formed on-chain signature paying an allow-listed mint, it is de-duped globally by that signature, and the transaction is verified on-chain (exists, succeeded, moved at least the amount claimed, and credited one of the agent's own payout wallets when any are on record). A settlement the RPC cannot see yet lands with `verified_at` null, counting for nothing and notifying nobody until `api/cron/settlement-verify.js` proves or discards it.7. **Payoff:** The user's chosen agent is anchored and visible in AR on the real floor, persisted for nearby users to discover; the user can also discover and interact with other agents pinned around them.8. (optional alt placement) **Place in AR** (WebXR, Android Chrome) now fronts the dock's secondary row on AR-capable devices: `XRSession.requestSession('immersive-ar')` hit-test → `POST /api/irl/pins` with `anchor.quat` + shared room frame; a two-finger pinch resizes the agent (0.25x to 4x, `src/ar/pinch-scale.js`) and the chosen size persists (`anchor.scale` on POST, owner-gated `PATCH {id, scale}` after placement; every viewer renders the owner's size). Camera-mode AR gets the same pinch-to-resize without WebXR. iOS Safari → AR Quick Look (USDZ) with an in-AR "Pin it here for people nearby" banner whose tap lands back on `/irl` with Pin here pulsing. **Anchor to a marker** (indoor, no GPS/compass): scan or print a QR marker; once locked it becomes a shared origin, so "Place here" anchors the agent relative to the marker for anyone who scans the same one. **Place on map** (privacy-first): Leaflet picker → `commitMapPin()` `POST /api/irl/pins source:'map'`.9. (optional) Privacy center (`openPrivacyCenter`): geolocation precision Exact vs Nearby, "Appear nearby" ghost toggle. Share button flattens camera + canvas to PNG. "My pins" sheet → `GET /api/irl/pins/mine`, map + list, `DELETE /api/irl/pins?id=` or `?all=1`. Calibrate / refine-on-floor → `PATCH /api/irl/pins`.-- **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.+- **Decision points / branches:** WebGL supported vs fatal overlay; arrived on a visit link (`?pin=`, banner naming the agent → searching / no-gps / gone / found) vs a cold open; placement path (gyro-GPS / WebXR floor / iOS Quick Look / QR marker / map); View-in-AR lane for a discovered pin (Quick Look / WebXR view-only / `/api/ar` launcher); 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`, `POST /api/chat` (Talk), `/api/ar` (AR launcher lane). 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; 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)---+### Printable IRL Sign - `/irl/sign`+- **Source:** `pages/irl-sign.html`, `src/irl-sign.js`, `src/irl/visit-link.js` (`normalizePinId`, `buildVisitUrl`), `src/erc8004/qr.js` (`renderQRToSVG`), `GET /api/irl/agent-card`+- **Entry point:** `main()` runs on import and reads `?pin=<id>`. Reached from the placements dashboard's "Visit link" modal ("Print a sign"), never from a nav link.+- **Prerequisites / gates:** None. The page is deliberately **coordinate-free**: the pin id resolves only to who lives at the spot, so a sign taped in public never leaks where it hangs.+- **Steps (3):**+ 1. Owner opens `/irl/sign?pin=<id>`. System fetches `GET /api/irl/agent-card?pin=<id>` and renders the sheet: agent name, thumbnail (a broken image degrades to a ✦ glyph), bio, and an SVG QR of the visit link `/irl?pin=<id>` with the URL printed beneath it.+ 2. (optional) Owner switches layout (landscape sheet vs poster, remembered in `localStorage`) or clicks "Copy visit link".+ 3. **Payoff:** "Print" calls `window.print()` and the owner tapes the sign where the agent stands; a passer-by scans the QR, lands on `/irl?pin=<id>`, and the visit banner tells them who they came to meet until the agent itself resolves through the presence-gated nearby read.+- **Decision points / branches:** `?pin=` present vs missing; card found vs 404 (placement no longer active) vs fetch failure; thumbnail present vs glyph; landscape vs poster layout.+- **External calls / dependencies:** `GET /api/irl/agent-card`, clipboard API, `window.print()`, `localStorage` (layout only).+- **Success state:** A printable, coordinate-free sign whose QR opens the agent's visit link.+- **Empty / error states:** No `?pin=` → "Which agent is this sign for?" with "Open my placements" (`/dashboard/irl-placements`). 404 → "This placement is no longer active" with "Open IRL". Fetch failure → "Couldn't load this agent" with "Open the visit link", since the link itself still works.+- **Step count:** 2 required (+1 optional)++---+### IRL Location Privacy — `/irl-privacy`- **Source:** `pages/irl-privacy.html` (static content), `nav.js`, `footer.js`- **Entry point:** Static page load. Read-only policy/explainer page.@@ -179,8 +196,8 @@ Routing recap (from `vercel.json`):- **Steps (6):**1. User lands on `/reputation`. With no `?address`, system renders the search form (address / ENS input, chain select, example chips).2. User enters an address or ENS name (or clicks an example chip), submits → navigates to `?address=…&chain=…`.- 3. System resolves ENS if needed (public RPC), then fetches attestations via EASScan GraphQL (`fetchAttestations`) and the ERC-8004 on-chain reputation (`getReputation`) for the resolved address/chain.- 4. System renders the profile: aggregate score bar (color-coded), star ratings, tabbed review list (all / by category), copy-address + copy-share-link buttons.+ 3. System resolves ENS if needed (public RPC), then fetches attestations via EASScan GraphQL (`fetchAttestations`, walking the index 100 rows at a time up to 500 so a heavily attested address gets its real count rather than one page's worth) and the ERC-8004 on-chain reputation (`getReputation`) for the resolved address/chain.+ 4. System renders the profile: aggregate score bar (color-coded), star ratings, a tabbed review list (All / Scored / With comments, each tab carrying a badge count scored through the same predicate that filters the list, so a badge never disagrees with what it opens) paged 30 at a time behind a "Show N more" button with a running "Showing X of Y", copy-address + copy-share-link buttons. Hitting the 500-attestation ceiling renders the headline count as `N+` with a note linking the full index on EASScan.5. (optional) **Write a review:** click "Connect wallet to review" → `eth_requestAccounts`; pick a star score + comment; click "Sign & submit review" → switches/adds the write chain (`wallet_switchEthereumChain` / `wallet_addEthereumChain`), encodes the `address agent, uint8 score, string comment` schema, and calls `EAS.attest(...)`.6. **Payoff:** Transaction confirms → success card with "View transaction" (block explorer) + "View attestation" (EASScan) links; the on-chain review is now part of the agent's reputation.- **Decision points / branches:** address vs ENS vs legacy `agent=N:M` (→ `renderLegacyAgent`, resolves owner then redirects); supported EAS chain vs unsupported; wallet present vs absent; correct write chain vs needs switch/add; user-rejected tx vs failure.@@ -216,7 +233,7 @@ Routing recap (from `vercel.json`):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 (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`.+ 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`, `/marketplace`, and Community Spotlight (`/spotlight`).- **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.@@ -226,18 +243,18 @@ Routing recap (from `vercel.json`):---### My Agents — `/my-agents`-- **Source:** `public/my-agents/index.html` (inline module), `public/my-agents/my-agents.{js,css}`, `/api/agents`+- **Source:** `public/my-agents/index.html` (the live page: inline module + inline styles), `/api/agents`. (`public/my-agents/my-agents.{js,css}` still sit beside it but the page does not load them.)- **Entry point:** Inline module runs `load()` on load.- **Prerequisites / gates:** **Auth required** — `GET /api/agents` returning 401 renders a sign-in gate.- **Steps (4):**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.+ 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. The hero also carries a standing line to `/mine` ("My creations"), where agents, avatars and forged models sit in one grid.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.-- **Empty / error states:** 401 → sign-in gate; connection error → "Connection error — Check your network"; non-OK → "Failed to load agents"; zero agents → "No agents yet" + Create CTA.+- **Empty / error states:** 401 → sign-in gate. Every other failure lands in one designed `role="alert"` state that names a cause and offers a **Try again** button: a fetch that never reached us → "Connection error" / "Your browser could not reach three.ws."; a 5xx → "We could not load your agents" / "The agents service is having trouble right now. Your agents are safe."; any other non-OK status → the same title naming the status code. Zero agents → "No agents yet" + Create CTA. Interactive elements carry focus rings and the page honors `prefers-reduced-motion`.- **Step count:** 3 required (+1 optional, e.g. Deploy)---diff --git a/docs/ux-flows/06-marketplace-skills.md b/docs/ux-flows/06-marketplace-skills.mdindex 31f96c013..0fae6dd10 100644--- a/docs/ux-flows/06-marketplace-skills.md+++ b/docs/ux-flows/06-marketplace-skills.md@@ -79,7 +79,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g11. **Branch — verification outcomes:** `confirmed` → success; `409 transfer_mismatch` (status `tipped` when a smaller-but-real transfer landed); `410 purchase_expired` for a stale pending row.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).+- **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). Because that rail spends from a wallet three.ws custodies, it also calls `requireRealFundsAgreement()` (`api/_lib/real-funds-agreement.js`): an account with no current signature on the Terms of Service, Risk Disclosure and Agent Wallet Agreement gets `403 risk_ack_required` naming `/legal/agreements`, over session and API key alike, and nothing is sent. Devnet is exempt. The buyer-signs-in-their-own-wallet path is not gated there; the embed widget asks for the signature client-side first (`ensureRiskAck({ context: 'skill-purchase' })` in `src/payment-modal.js`).- **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.@@ -90,11 +90,11 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g### Whole-asset purchase (avatar / agent / plugin) — buy flow via `/api/marketplace/buy-asset`- **Source:** client `src/marketplace.js` (`openAssetPurchaseFlow()` ~L6890, `createPendingAssetPurchase()` ~L6929, `pollAssetConfirm()` ~L6936; shared engine `src/shared/skill-purchase.js`). Backend `api/marketplace/buy-asset.js` (Solana Pay `findReference`/`validateTransfer`, gasless sponsorship, EVM/USDC fallback via `_lib/evm-payment-verify.js`, receipts + notifications).- **Entry point:** "Buy now with USDC" on an avatar modal / agent detail / plugin card.-- **Prerequisites / gates:** Auth + CSRF + rate limit; asset must have an active `asset_prices` row; seller must have a configured payout wallet for the chain (else `412 creator_wallet_missing`); buyer must not be the owner (else `400 self_purchase`); connected wallet with sufficient balance.+- **Prerequisites / gates:** Auth + CSRF + rate limit; paying from an agent's custodial wallet additionally requires a current signature on the three real-funds agreements (`requireRealFundsAgreement()`, `403 risk_ack_required` → sign at `/legal/agreements`; devnet exempt); asset must have an active `asset_prices` row; seller must have a configured payout wallet for the chain (else `412 creator_wallet_missing`); buyer must not be the owner (else `400 self_purchase`); connected wallet with sufficient balance.- **Steps (N):**1. User clicks "Buy now" → `openAssetPurchaseFlow({ item_type, item_id, label, price })` opens the payment modal in `mode='asset'`.2. (optional) Connect wallet if not connected. For signed-in users the modal also prepends a "Pay from an agent's own wallet, no popup" block (up to 4 owned agents with live USDC balances, from `/api/x402-pay?agents=1`; underfunded agents are disabled).- 3. User confirms → POST `/api/marketplace/buy-asset` `{ item_type, item_id, [buyer_public_key] }`. **Agent-wallet branch:** picking an agent instead POSTs `{ item_type, item_id, agent_id }`; the server verifies ownership, enforces the agent's daily purchase cap (`agent_identities.meta.auto_purchase_daily_limit_usdc`, summed across skill AND asset purchases by `api/_lib/agent-purchase.js`; exceeding it returns `402 spend_cap_exceeded`), signs from the agent's custodial wallet, validates the transfer on-chain, and grants in one round trip (no prepare → sign → confirm dance).+ 3. User confirms → POST `/api/marketplace/buy-asset` `{ item_type, item_id, [buyer_public_key] }`. **Agent-wallet branch:** picking an agent instead POSTs `{ item_type, item_id, agent_id }`; the server verifies ownership, requires the signed real-funds agreements, enforces the agent's daily purchase cap (`agent_identities.meta.auto_purchase_daily_limit_usdc`, summed across skill AND asset purchases by `api/_lib/agent-purchase.js`; exceeding it returns `402 spend_cap_exceeded`), signs from the agent's custodial wallet, validates the transfer on-chain, and grants in one round trip (no prepare → sign → confirm dance).4. Server validates price/seller/payout; **already-owned** confirmed purchase short-circuits with `already_owned: true`; otherwise reuses or inserts a pending `asset_purchases` row (30-min expiry) and returns `{ reference, recipient, amount, currency_mint, chain, mint_decimals }` (+ gasless block when applicable).5. **Branch — already owned:** modal jumps to the success screen, skips payment.6. Client builds + signs the full-amount SPL transfer (single leg, no platform fee) with the reference key; user approves in wallet.@@ -104,7 +104,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g- **Decision points / branches:** chain = Solana vs EVM (EVM confirm requires a submitted `tx_hash`, verified via `verifyEvmUsdcPayment` on Base; short transfer = `tipped` 409); browser wallet (gasless vs buyer-pays) vs agent custodial wallet (server-signed, capped); already-owned; mismatch (tipped) vs expired (410).- **External calls / dependencies:** `POST /api/marketplace/buy-asset` (+ `/:ref` status, `/:ref/confirm`), Solana RPC w/ fallback, `@solana/pay`, EVM USDC verifier, `insertNotification`, receipt HMAC signing.- **Success state:** Asset confirmed and owned; receipt stored; both parties notified; CTA into the relevant dashboard; surfaced in `/collection`.-- **Empty / error states:** `404 not for sale`, `412 creator_wallet_missing`, `400 self_purchase`, `409 transfer_mismatch` (tipped), `410 purchase_expired`; client retry/re-verify identical to the skill flow.+- **Empty / error states:** `404 not for sale`, `412 creator_wallet_missing`, `400 self_purchase`, `403 risk_ack_required` (agent-wallet branch, unsigned account), `503 agreement_check_unavailable` (the signature lookup failed, so nothing was sent), `409 transfer_mismatch` (tipped), `410 purchase_expired`; client retry/re-verify identical to the skill flow.- **Step count:** 7 required (+2 optional)---@@ -205,7 +205,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g## Notes- `/marketplace/agents/:id` and `/marketplace/avatars/:id` are **301 redirects** to the canonical `/agents/:id` and `/avatars/:id` pages (vercel.json). Within the SPA, the same paths render inline via `loadDetail()`/`loadAvatarDetail()` before a hard navigation would redirect; `marketplace-detail.js` powers both the SPA detail and the canonical pages.-- Two distinct purchase rails: **individual skills** (`/api/marketplace/purchase`, splits creator + platform fee, records `agent_revenue_events`) vs **whole assets** (`/api/marketplace/buy-asset`, single full-amount leg, no fee, EVM/USDC fallback). The embed widget (`payment-modal.js`) only drives the skill rail. Both rails also have an **agent-payer** variant (`/api/marketplace/purchase-as-agent`, and `buy-asset` with `agent_id`) where the server signs from an owned agent's custodial wallet under one shared daily spend cap (`api/_lib/agent-purchase.js`).+- Two distinct purchase rails: **individual skills** (`/api/marketplace/purchase`, splits creator + platform fee, records `agent_revenue_events`) vs **whole assets** (`/api/marketplace/buy-asset`, single full-amount leg, no fee, EVM/USDC fallback). The embed widget (`payment-modal.js`) only drives the skill rail. Both rails also have an **agent-payer** variant (`/api/marketplace/purchase-as-agent`, and `buy-asset` with `agent_id`) where the server signs from an owned agent's custodial wallet under one shared daily spend cap (`api/_lib/agent-purchase.js`) and behind the signed real-funds agreements (`api/_lib/real-funds-agreement.js`, documented in `docs/risk-acknowledgment.md`).- "Skills marketplace" (`/skills`, `/api/skills/*`) sells community tool packs — **install is free, payment is per-call via x402** — which is a different mechanism from the skill *unlock* purchase on an agent's detail page (`/api/marketplace/purchase`). Both can show under a user's owned items.- `src/marketplace-lobby.js` is not URL-routed; it's a Three.js scene mounted into the hero canvas with an `onSelect` callback back to `marketplace.js`.- Source coverage: all referenced files were located and read. No missing sources. Line numbers for `marketplace.js` are approximate anchors from a structural read of the 8.9k-line file, not exact-verified per line.diff --git a/docs/ux-flows/07-crypto-trading-analytics.md b/docs/ux-flows/07-crypto-trading-analytics.mdindex b19725483..1651e17ce 100644--- a/docs/ux-flows/07-crypto-trading-analytics.md+++ b/docs/ux-flows/07-crypto-trading-analytics.md@@ -24,11 +24,11 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up6. (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." 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.+ 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. The move INTO live-armed also requires a current signature on the three real-funds agreements (`requireRealFundsAgreement()`, `403 risk_ack_required` pointing at `/legal/agreements`); re-saving a watch that is already live-armed, simulate mode, disarming, and devnet all stay open.- **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; 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".+- **Empty / error states:** "Oracle is warming up" (backend not live); "No launches clear your filters" + Reset; the symbol search answers in the dropdown rather than closing it, quoting the query back ("No scored coin matches “<q>”. Oracle only searches launches it has scored.") on a miss and "Search is unavailable right now. Try again in a moment." on an outage, and a stale response can no longer overwrite a query the reader has moved on from; 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).---@@ -77,7 +77,7 @@ 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. 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.+ 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 (`src/mission-control/chart.js`, `GET /api/pump/price-history` over Birdeye, then GeckoTerminal, then pump.fun OHLCV; a single candle is already a chart, so a coin minutes old draws and grows from the live stream, and a coin that has never traded says "No market yet" instead of blaming the interval), 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.@@ -120,9 +120,10 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up3. (optional) Filter by category chips (meme/ai/tech/…) → URL + reload.4. (optional) Min-quality slider → reload on change.5. (optional) Watch toggle per coin → `ld_watchlist`.+ 5b. (optional) **Fork** (mainnet cards only) → `openFork()` from `src/fork-trade.js` lazily pulls the Solana + pump SDKs (the button holds a busy state for that fetch instead of sitting inert) and opens the real pump.fun trade panel (`src/game/coin-buy.js`) pre-filled with that mint; the user's own wallet signs, nothing is custodied or auto-executed. An inbound `?fork=<mint>&fork_size=<sol>` link opens the same panel on arrival, with the size clamped to `MAX_FORK_SOL` (10 SOL) because it arrives from a link a stranger wrote. Any open modal sets `tws-modal-open` on `<body>` so the shared corner stack stops covering its controls.6. (optional) Click a coin card → detail drawer → `GET /api/pump/coin-intel?mint=<mint>&wallets=1` (single-coin wallet breakdown). Each mainnet card's "Full intel →" action and the drawer's "Open full page" link go straight to the coin's full intelligence page at `/oracle/coin/<mint>`; devnet coins have no page, so their button keeps opening the drawer.-- **Decision points / branches:** category × quality filters; risk-flag pills (bundle_launch, dev_dumped, single_whale, low_diversity, fresh_wallet_swarm, sell_pressure, sniped) with danger/warn tones; drawer open/closed.-- **External calls / dependencies:** `GET /api/pump/coin-intel` (list) and `?mint=&wallets=1` (detail); `/api/img` for logos.+- **Decision points / branches:** mainnet (Fork offered) vs devnet (read-only); category × quality filters; risk-flag pills (bundle_launch, dev_dumped, single_whale, low_diversity, fresh_wallet_swarm, sell_pressure, sniped) with danger/warn tones; drawer open/closed.+- **External calls / dependencies:** `GET /api/pump/coin-intel` (list) and `?mint=&wallets=1` (detail); `/api/img` for logos; `src/fork-trade.js` → `src/game/coin-buy.js` (lazy Solana + pump SDKs) for Fork.- **Success state:** live launch-intelligence feed; every number traces to an observed on-chain trade.- **Empty / error states:** "not measured" for null signals; empty/loosen-filters guidance; image fallback to seeded identicon.- **Step count:** 1 required (arrive → live feed) + ~5 optional (filters, watch, inspect).@@ -160,7 +161,7 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up4. (optional) Connect wallet → `wallet:changed` → `POST /api/wallet/balances` renders SOL + top-10 holdings.5. (optional) Default tab: inspect monitor stat cards, featured agent, network health, market chart (`chart:tokenChange` → fetch candles), high-conviction Oracle panel, live-feed preview.6. (optional) **Live Feed** tab: pause + filter (Launches/Trades/Whales/Graduations/Claims) the rAF-batched WS feed.- 7. (optional) **Token Scanner**: enter mint → scan for risk/honeypot.+ 7. (optional) **Token Scanner**: enter mint → scan for risk/honeypot. Every RPC call is timed out (some providers accept `getTokenLargestAccounts` and never answer), and the button plus a persistent status line carry the busy state so a failed scan cannot read as one that was never run: a timeout is distinguishable from an unreachable endpoint in both the toast and the RPC badge, an address with no account on mainnet says exactly that, and a failure tells the reader to press Scan again.8. (optional) **Quote Engine**: buy/sell quote forms.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).@@ -200,17 +201,36 @@ coin-intel, pump-visualizer and pump-live: adding a coin on any surface shows up- **Entry point:** nav; share links.- **Prerequisites / gates:** None — public, IP rate-limited only; CORS `*`.- **Steps (N):**- 1. Arrive → inline module reads `ld_watchlist`, renders 6 skeletons, calls `refresh()`; auto-refresh every 20s (pauses when tab hidden).+ 1. Arrive → inline module reads `ld_watchlist`, renders 6 skeletons, calls `refresh()`; auto-refresh every 20s (pauses when tab hidden). `?wallet=<addr>` or `?mint=<addr>` (base58) opens that drawer straight away, so a wallet cited elsewhere on the platform lands on its track record instead of an unfiltered board.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 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`.+ 4. (optional) Watch toggle per coin → `ld_watchlist`; **Fork this trade** on a card or in the coin drawer opens the real pump.fun trade panel for that mint (`src/fork-trade.js` → `src/game/coin-buy.js`), signed by the visitor's own wallet, which is where the page's "proven wallets are in this coin" claim becomes an action.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". 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).+- **Step count:** 1 required (arrive → feed) + ~5 optional (tab, watch, inspect coin/wallet, fork).++---++### Fade Radar - `/fade`+- **Source:** `pages/fade.html`, `src/fade-radar.js`; backend `api/pump/fade.js` → `api/_lib/fade-radar.js`; reference doc `docs/fade-radar.md`+- **Entry point:** direct URL / `/sitemap`; the hero cross-links `/smart-money`, and the Smart Money Radar's wallet links come back the other way. Deep-linkable via `?view=coins|wallets`, `?hours=1|6|24|72`, `?active=24|168|0` (written with `replaceState`).+- **Prerequisites / gates:** None: public, IP rate-limited. The page **spends nothing and signs nothing**: on a bonding curve the only tradeable form of a fade is not buying, so every action is a link out.+- **Steps (N):**+ 1. Arrive → `readUrl()` restores view/window, `loadStrip()` and `loadBoard()` run together against skeletons.+ 2. System: `GET /api/pump/fade?calibration=1` paints the verdict strip first, because it is the reason to believe anything below it: per band (Clear / Caution / Avoid) the share of coins that went on to win, the sample size, the lift over baseline, and the out-of-sample note (`getFadeCalibration` builds the reverse-indicator cohort from the earlier half of labelled history and grades it on the later half).+ 3. System: `GET /api/pump/fade?hours=<window>&limit=40` renders the coin board (coin, fade score, verdict pill, reverse/buyers, reverse share of SOL, observed buy SOL, launched-ago, pump.fun link), heaviest share first. A **reverse indicator** is a wallet observed buying at least five coins whose outcome is known, with zero winners among them.+ 4. (optional) Switch to **Reverse indicators** → `GET /api/pump/fade?wallets=1&limit=40&min_judged=8&active_hours=<active>` renders the wallet board (address + labels, judged buys, winners, losers, last seen, "Track record" → `/smart-money?wallet=<addr>`). The window control swaps to the last-active filter.+ 5. (optional) Change window (1h / 6h / 24h / 3d) or last-active (24h / 7d / All time) → URL synced, board reloads; a superseded request cannot paint over a newer one.+ 6. **Payoff:** Click a coin symbol → its full intelligence page `/oracle/coin/<mint>`; or a wallet → Solscan / its Smart Money track record.+- **Decision points / branches:** coin board vs reverse-indicator board (each with its own filter and its own empty copy); calibration computed vs still being computed (the strip says so and the board stays live either way).+- **External calls / dependencies:** `GET /api/pump/fade` (`?calibration=1`, `?hours=`, `?wallets=1`, `?mint=`), reading the same `smart_wallet_reputation` graph the trade firewall and the sniper scorer use, so it needs no cron of its own.+- **Success state:** every recent launch ranked by how much of its buy side has never once been right, under measured odds rather than an asserted label.+- **Empty / error states:** coin board empty → "Nothing to fade in <window>" (named as the good outcome) with "Open the Smart Money Radar"; wallet board empty → "No reverse indicator has traded <window>" with the same link; fetch failure → "The board could not be loaded" naming what the server answered, with Try again.+- **Step count:** 2 required (arrive → strip + board) + ~3 optional (view, window, drill-in).---diff --git a/docs/ux-flows/08-coin-launch-wallets.md b/docs/ux-flows/08-coin-launch-wallets.mdindex d285d7714..b0dbbffd9 100644--- a/docs/ux-flows/08-coin-launch-wallets.md+++ b/docs/ux-flows/08-coin-launch-wallets.md@@ -13,66 +13,57 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.---### Launch a Coin — `/launch`-- **Source:** `pages/launch.html` (inline module imports `/launch/launch.js`) → `public/launch/launch.js` (`mountLaunchCoin`) → `public/studio/launch-panel.js` (`mountLaunchPanel`, the real flow) → `public/studio/fees-panel.js` (`mountFeesPanel`, post-launch). Vanity stamp: `src/solana/vanity/grinder.js` + `src/solana/vanity/brand.js` (`THREE_WS_VANITY`).-- **Entry point:** `#launch-root` mounts a two-column shell: agent picker (left, `launch.js`) + launch panel (right, `launch-panel.js`).+- **Source:** `pages/launch.html` → `src/launch/launch-page.js` (the whole flow), with the pure form/cost logic in `src/launch/launch-model.js`, wallet connect/link/sign in `src/launch/launch-wallet.js`, styles in `src/launch/launch-page.css`. A Launch Studio recipe link (`?reward=`) mounts `public/studio/launch-panel.js` instead, because the fee-split handoff lives there. Reference doc: [the /launch launchpad](../launchpad.md).+- **Entry point:** `#launch-app` mounts two tabs, **Create** and **My coins**. Create is a four-card form (link an agent, coin details, image, launch settings) beside a rail holding the live preview, the cost panel, the wallet card and the Launch button.- **Prerequisites / gates:**- - Account/session required to actually launch (`GET /api/auth/me`). Signed-out users see the guided empty state; the launch button reads "Sign in to launch."- - A non-demo agent/avatar must be selected (panel refuses `__demo__`).- - Wallet source: either a connected Solana wallet (Phantom/Backpack/Solflare/backpack) that is SIWS-**linked** to the account, OR a custodial agent wallet.- - SOL balance ≥ estimated cost (`PUMP_BASE_COST` 0.022 SOL + initial buy). USDC coin type debits the buy from the wallet's USDC ATA instead of SOL.+ - Account/session required to launch (`GET /api/auth/me`). Signed out, the agent card offers Sign in / Create an agent and the button reads "Sign in to launch."+ - One of the account's 3D agents must be selected; the coin is linked to it and its page becomes the coin's website.+ - Signer: either an injected Solana wallet (Phantom/Solflare/Backpack) linked to the account, or the agent's custodial wallet.+ - Balance: the create cost and rent (about 0.022 SOL) plus the dev buy and the **1% three.ws launch fee** on that dev buy. A USDC-paired coin pays the dev buy and fee in USDC and still needs the SOL for rent and network fees.+ - The real-funds agreements must be signed (`ensureRiskAck`, context `launch`) before anything is built. Every launch here is mainnet.- **Steps (N):**- 1. Page boots: `fetchMe()` then `fetchAvatars()` (`GET /api/avatars?limit=100`). Picker shows 3 shimmer skeletons while loading.- 2. Picker renders agent cards; `?avatar=<id|slug>` deep link is honored, else the first agent is auto-selected. Panel pre-fills name/symbol/description from the avatar.- 3. Panel auto-checks for an existing mint for the selected agent (`GET /api/pump/by-agent?agent_id=|avatar_id=`). If one exists, it shows the "Token already launched" card with stats + Fees & rewards panel (skip to step 16) unless the user clicks "Launch a new token."- 4. (optional) User edits the **token image**: click/drag-drop an image file, or "📸 Use 3D view" to snapshot the preview canvas (only when a preview viewer is present, i.e. studio mount). Files over ~3 MB are downscaled in the browser (1024px max, PNG then JPEG fallback) instead of rejected; only an unshrinkable image errors ("Could not shrink that image under 4 MB").- 5. User edits **name** (≤32 chars), **symbol** (≤10 codepoints, any chars incl. emoji; auto-derived from name until edited), **description** (≤500).- 5b. User picks a **launch lane**: pump.fun (default, the reach lane) or the **three.ws native bonding curve** (the economics lane). The native toggle only renders when `GET /api/native-launch/config` returns a pinned curve config for the network; its fee split and graduation target are rendered from that server config. The native lane is SOL-quoted, takes the base fields only (no coin variants, no buyback binding), and forces the connected-wallet signer (no custodial path yet).- 6. User picks a **coin type** (pump.fun lane): Regular / Mayhem / Agent (default, buyback-bound) / USDC / Reward.- 7. (optional, Agent/USDC only) User sets the **buyback share** slider (0–50%, `buybackBps` 0–5000).- 8. (optional) User sets an **initial buy** (SOL, max 50; or USDC, max 1,000,000). Live cost line in the wallet bar updates as they type.- 9. User picks **wallet source** via the tab toggle: "Connected wallet" or "Agent wallet (custodial · server-signed)."- 10a. **Connected-wallet path:** if no wallet detected → "Install Phantom" opens phantom.app. If detected but not connected → "Connect" calls `wallet.connect()`. Balance polls every 30s via `/api/solana-rpc`. (optional) "Deposit" opens a modal with a Solana Pay QR + copyable address.- 10b. If the connected wallet is not SIWS-linked → "Link wallet" button runs the link ceremony: `POST /api/auth/wallets/nonce-solana` → `provider.signMessage` → `POST /api/auth/wallets/link-solana`. A 409 (`address_in_use`) flips to a "Transfer wallet to this account" confirmation that re-signs with `takeover:true`.- 10c. **Agent-wallet path:** `POST /api/pump/agent-wallet` provisions/resolves the custodial wallet, returns address + lamports/sol. (optional) "Fund" opens a deposit modal (QR + address); balance polls every 30s.- 11. User clicks **Launch $SYMBOL**. The button's `data-action` routes: sign-in / focus-first-missing-field / connect / link / agent-fund / agent-retry / launch.- 12. **Build metadata** (both paths): phase `building` — if image present, `fileToDataUrl`, then `POST /api/pump/build-metadata` → `metadata_url` (cached by name|symbol|desc|hasImage key).- 13a. **Connected-wallet launch:** phase `stamping`: client grinds the `3ws` mint keypair via `grindVanity(THREE_WS_VANITY)` with live k/s + ETA progress. Then phase `signing` → `POST /api/pump/launch-prep` (pump.fun lane; sends `wallet_address`, `mint_address` = ground pubkey, coin_type, buyback_bps, buy-in, network=mainnet) or `POST /api/native-launch/launch-prep` (native lane; base fields + `sol_buy_in` only) → returns `tx_base64` + `prep_id`. Deserialize `VersionedTransaction`, `wallet.signTransaction`, then co-sign with the ground mint keypair.- 13b. Phase `confirming`: `conn.sendRawTransaction(skipPreflight:false)` over `/api/solana-rpc`, then `pollConfirmation` (75s, 2s interval). On confirm → `finalizeConfirm`: `POST /api/pump/launch-confirm` (or `/api/native-launch/launch-confirm` on the native lane) with `prep_id` + `tx_signature` → echoes `pump_agent_mint.mint`.- 14a. **Agent-wallet launch:** phase `stamping` (server stamps `3ws`), then phase `confirming` → `POST /api/pump/launch-agent` (server signs + submits with the custodial key, ~10s) → returns `mint`. Agent balance refreshes.- 15. Phase `success` — success card shows the stamped mint (with the `3ws` mark visually emphasized), "✓ three.ws coin" badge, links to pump.fun / Solscan / the agent page, "Copy launch announcement," and "Launch another token."- 16. (existing-token branch) Fees & rewards panel mounts against the mint for claim/delegation management.+ 1. Boot: `GET /api/pump/launch-config` (live launch-fee bps, create-cost estimate, whether Solana transaction v1 is active) alongside `GET /api/auth/me` and `GET /api/avatars?limit=100`. Agent cards shimmer while loading. Deep-link params prefill: `?avatar=`, `?name=`, `?symbol=`, `?description=`, `?initialBuy=`, `?image=`, `?imageSession=1`, `?tab=coins`.+ 2. Pick the agent from an arrow-key navigable radio grid (a search box appears once the account has more than eight agents). The preview rail renders that agent and the coin card as you type.+ 3. Coin details: name (32 chars), ticker (2 to 10 letters or digits, suggested from the name until edited), optional description (500), optional website / X / Telegram behind a disclosure.+ 4. (optional) Image: defaults to the agent's portrait. Upload or drop a PNG, JPG, GIF or WebP up to 4 MB; a larger file is downscaled to 1024 px in the browser rather than rejected.+ 5. Launch settings: **Launch from** your wallet or the agent's wallet; **Pair with** SOL or USDC; **Creator rewards go to** the creator or holders; optional **dev buy** with presets; **Mayhem mode**; and, under a disclosure, the **transaction format** (Auto / v0 / v1).+ 6. The cost panel updates on every keystroke: create + rent, dev buy, a `three.ws fee` row at the live rate, and the total. The checklist beneath it lists whatever still blocks the launch, each item focusing its field when clicked.+ 7. Click **Launch $TICKER**. The button routes in order: sign in, connect a wallet, fix the first blocking field, then launch. `ensureRiskAck` runs last before any request.+ 8. **Connected-wallet launch** opens a step dialog: `POST /api/pump/build-metadata` (image + metadata pinned and linked to the agent) → `POST /api/pump/launch-prep`, which grinds the `3ws` mint mark server-side, pre-signs the mint, puts the fee in the same transaction and reports the version and byte count → one wallet signature, broadcast through `/api/solana-rpc` → confirmation polled for 75 s → `POST /api/pump/launch-confirm` records it (retried while the confirming RPC is a slot ahead and answers `tx_not_found`).+ 9. **Agent-wallet launch** is two steps: metadata, then `POST /api/pump/launch-agent`, which signs, sends and confirms with the custodial key. No wallet prompt.+ 10. Success card: "$TICKER is live" with the coin image, the mint and Copy CA, and links to the coin page (`/launches/<mint>`), pump.fun, the agent page, the transaction on Solscan, a prefilled Share on X post, and Launch another.+ 11. (optional) **My coins** tab: `GET /api/pump/my-coins` groups your coins by the wallet that earns their rewards and reads the live unclaimed balance per quote mint. Claim runs `POST /api/pump/collect-creator-fee-prep` (your wallet signs, `all_quotes: true`) or `POST /api/pump/collect-creator-fee-agent` (the agent wallet signs server-side), each behind its own `ensureRiskAck` (context `claim`).- **Decision points / branches:**- - Existing mint found → existing-token card vs. "force new."- - Launch lane: pump.fun (default; coin types + custodial path available) vs. three.ws native curve (only offered when a curve config is deployed for the network; connected-wallet signer only; base fields only).- - Coin type: Regular / Mayhem (high-volatility, no buyback) / Agent (SOL buyback+burn) / USDC (stablecoin-paired agent) / Reward (delegated creator fees; launches as a plain coin, fees split post-graduation). USDC & Reward both remap server-side (`coin_type: 'agent'` / `'regular'`).- - 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: `@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)+ - Launch from your wallet (you sign, you claim the rewards) vs the agent's wallet (it signs and earns).+ - SOL vs USDC pairing; creator vs holder rewards (holder rewards and Mayhem mode exclude each other and each disables the other control).+ - Transaction format: Auto picks the smallest that fits, v0 signs everywhere, v1 is offered only while the feature is active and the connected wallet advertises it through Wallet Standard.+ - Connecting a wallet that is linked to another account surfaces a "Move wallet here" takeover that re-signs the link with `takeover: true`.+ - Confirmation still pending after 75 s: the dialog keeps the signature, links it on Solscan and offers "Check again" rather than declaring failure.+ - A `?reward=` recipe link mounts the studio launch panel instead of this flow.+- **External calls / dependencies:** `/api/pump/launch-config`, `/api/auth/me`, `/api/avatars`, `/api/pump/build-metadata`, `/api/pump/launch-prep`, `/api/pump/launch-confirm`, `/api/pump/launch-agent`, `/api/pump/agent-wallet`, `/api/pump/my-coins`, `/api/pump/collect-creator-fee-prep`, `/api/pump/collect-creator-fee-agent`, `/api/auth/wallets` (+ `/nonce-solana`, `/link-solana`), `/api/solana-rpc`. External: the pump.fun program (mint target), Solscan (links), x.com (share intent).+- **Success state:** the live-coin dialog above, plus the coin appearing on `/launches` and its own `/launches/<mint>` page, and its creator rewards accruing under My coins.+- **Empty / error states:** agent list loading skeletons, load failure with Try again ("Nothing was launched"), signed-out and no-agent empty states with their own CTAs; per-field counters and the blocker checklist; wallet card states for not installed / connect / connecting / conflicting account / connected (with a v0 or v1 badge) and the agent wallet's loading, error-with-retry and balance-unavailable forms; a blocking "needs ~X more SOL" line; in-dialog step errors written by `friendlyLaunchError` (cancelled signature, insufficient funds, unlinked wallet, expired session, rate limit, expired blockhash, unreachable RPC) with Close and Try again; the pending-confirmation recheck; a warning when the coin launched but the separate fee transfer did not (nothing was charged); My coins load error with retry and a "No coins yet" empty state.+- **Step count:** 5 required (+5 optional)---### Launch Feed — `/launches` (and `/launches/:mint` detail)- **Source:** `pages/launches.html` → `src/launches.js`. Imports `src/pump/coin-status-card.js` (`mountCoinStatus`), `src/shared/agent-wallet-chip.js` (`walletChipEl`).-- **Entry point:** `#lx-feed` (card grid), hero stats, network/oracle filter buttons, marquee ticker, ambient particle canvas.+- **Entry point:** `#lx-feed` (card grid), hero stats, network filter buttons, marquee ticker, ambient particle canvas.- **Prerequisites / gates:** None — fully public, read-only.- **Steps (N):**- 1. Boot reads URL params: `network` (mainnet|devnet), `agent_id` (UUID), `oracle_tier` (prime|strong|lean). Starts the particle field; renders 8 skeletons.- 2. `loadPage()` → `GET /api/pump/launches?network=&offset=&limit=24[&agent_id=&min_tier=]`. Registry rows render immediately as cards.- 3. Per mainnet card, `mountCoinStatus` fetches `GET /api/pump/coin?mint=` and streams price / logo / market cap / graduation over the seeded identicon placeholder. Devnet cards show a static identity line.- 4. After each page, `enrichCardsWithOracle` batch-fetches `GET /api/oracle/batch?mints=…&network=mainnet` (≤20/req) and paints a conviction tier badge.- 5. (optional) User toggles **network**, picks an **Oracle tier**, or applies an **agent filter** (chip resolved via `GET /api/agents/:id`) — each resets and reloads the feed; URL is kept in sync.- 6. (optional) User clicks **Load more** (offset paginates) or stars a coin (localStorage `ld_watchlist`).- 7. Live refresh every 60s re-checks page zero and prepends genuinely new launches.- 8. (optional) Per card: open coin detail (`/launches/:mint`), pump.fun, 3D view (`/coin3d?mint=`), 3D world (`/communities/:mint`), or the launching agent's profile.+ 1. Boot reads URL params: `network` (mainnet|devnet) and `agent_id` (UUID). Starts the particle field; renders 8 skeletons.+ 2. `loadPage()` → `GET /api/pump/launches?network=&offset=&limit=24[&agent_id=]`. Registry rows render immediately as cards.+ 3. Per mainnet card, `mountCoinStatus` fetches `GET /api/pump/coin?mint=` and streams price / logo / market cap / graduation over the seeded identicon placeholder. Devnet cards show a static identity line. The feed stays neutral: it scores nobody's coin, so no conviction tier is painted here (`oracle: false`).+ 4. (optional) User toggles **network** or applies an **agent filter** (chip resolved via `GET /api/agents/:id`); each resets and reloads the feed, and the URL is kept in sync.+ 5. (optional) User clicks **Load more** (offset paginates) or stars a coin (localStorage `ld_watchlist`).+ 6. Live refresh every 60s re-checks page zero and prepends genuinely new launches.+ 7. (optional) Per card: open coin detail (`/launches/:mint`), pump.fun, 3D view (`/coin3d?mint=`), 3D world (`/communities/:mint`), or the launching agent's profile.- **Decision points / branches:** mainnet vs devnet (devnet → Explorer link, no market data); filtered vs. unfiltered empty state; watchlist toggle.-- **External calls / dependencies:** `/api/pump/launches`, `/api/pump/coin`, `/api/oracle/batch`, `/api/agents/:id`. External: pump.fun, Solscan, Solana explorer (links).+- **External calls / dependencies:** `/api/pump/launches`, `/api/pump/coin`, `/api/agents/:id`. External: pump.fun, Solscan, Solana explorer (links).- **Success state:** populated card grid with live market data, ticker, hero stats (count / latest / network).- **Empty / error states:** "No launches yet" (with Create-agent / Forge CTAs) or "No matching launches" (Clear-filters) for filtered views; devnet-specific copy; `renderError` with Retry; per-card identicon fallback when pump.fun art is missing.-- **Step count:** 4 required (+4 optional)+- **Step count:** 3 required (+3 optional)---@@ -264,7 +255,7 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.## Source-coverage notes- All routes resolved and traced to real source. No missing source.-- `/launch` HTML loads its module by URL (`/launch/launch.js`) — the real source is `public/launch/launch.js`; the launch engine is `public/studio/launch-panel.js` (shared with `/studio` and the avatar page).+- `/launch` is a bundled page: `pages/launch.html` loads `src/launch/launch-page.js`, which owns the flow. `public/studio/launch-panel.js` is still the engine behind `/studio`, the avatar page, and any `/launch?reward=` recipe link.- `/vanity-wallet`, `/eth-vanity`, `/evm-wallet`, `/threews/claim`, `/three-live`, `/avatar-wallet-chat` are served from prebuilt HTML (`public/*.html` or `pages/*.html`) with self-contained inline modules; their crypto workers live under `src/solana/vanity/` and `src/eth/vanity/`.- `/threews/claim` rewrites to `threews-claim.html` (no `pages/threews/` dir).- `src/agent-eth-vanity-card.js` and `src/agent-vanity-grinder.js` are the embedded-card variants of the standalone vanity tools, mounted on agent home/dashboard pages rather than the standalone routes above.diff --git a/docs/ux-flows/11-account-dashboard.md b/docs/ux-flows/11-account-dashboard.mdindex 1a4c72982..72e5ec557 100644--- a/docs/ux-flows/11-account-dashboard.md+++ b/docs/ux-flows/11-account-dashboard.md@@ -23,7 +23,8 @@ Shared auth concepts:- **Session:** a `__Host-sid` cookie minted server-side by `createSession()`, identical across email/password, SIWE (EVM), SIWS (Solana), Privy, and SAML.- **Post-auth redirect:** `?next=` query param → `sessionStorage.login_redirect` → default (`/dashboard` for login, `/create` for register). On `/login`, an already-authenticated visitor is bounced to `next` via a `GET /api/auth/me` probe on load. The value is sanitized by a shared `safeNext` helper: anything that is not a single-leading-slash same-site path (protocol-relative `//host`, backslashes, control characters) is silently discarded and the default is used, so a crafted external `?next=` can no longer navigate off-site.- **Auth hint:** every successful auth writes `localStorage['3dagent:auth-hint']` so other surfaces render a logged-in chrome optimistically.-- **Terms clickwrap (ToS v2):** every auth surface asserts Terms acceptance. `/register` has a required checkbox; `/login` and the Privy/wallet paths use notice-style clickwrap ("By signing in... you agree to the Terms of Service and Privacy Policy") and send `tosAccepted: true`; the Privy SIWE message statement itself carries the agreement text. The server records `users.tos_accepted_version`/`tos_accepted_at` plus an append-only `audit_log` row (`api/_lib/legal.js`, `TOS_VERSION = 2`) and re-stamps on login.+- **Terms clickwrap (ToS v3):** every auth surface asserts Terms acceptance. `/register` has a required checkbox; `/login` and the Privy/wallet paths use notice-style clickwrap ("By signing in... you agree to the Terms of Service and Privacy Policy") and send `tosAccepted: true`; the Privy SIWE message statement itself carries the agreement text. The server records `users.tos_accepted_version`/`tos_accepted_at` plus an append-only `audit_log` row (`api/_lib/legal.js`, `TOS_VERSION = 3`) and re-stamps on login.+- **Real-funds agreements (separate from sign-up):** signing up does not unlock money movement. Before a real-funds action (an armed sniper or Oracle watch, a custodial agent purchase, an x402 payment, a withdrawal) and before an agent wallet's deposit address is revealed, the account must separately sign three documents together at `/legal/agreements`: the Terms of Service (`/legal/tos`), the Risk Disclosure (`/legal/risk`), and the Agent Wallet Agreement (`/legal/agent-wallet`). Signatures are typed-name e-signatures recorded append-only in `legal_signatures`; the dialog is `public/risk-ack.js` posting to `/api/legal/risk-ack`, and every money-moving endpoint enforces it server-side through `requireRealFundsAgreement()` (`api/_lib/real-funds-agreement.js`), answering `403 risk_ack_required` over session and API key alike. Devnet is exempt. See [risk-acknowledgment.md](../risk-acknowledgment.md).---@@ -196,4 +197,4 @@ Shared auth concepts:- **No login/register modal:** auth is full-page (`/login`, `/register`). Other surfaces trigger it by redirect (`requireAuth()` in `src/auth/email-auth.js`, `requireUser()` in `src/dashboard-next/api.js`), preserving the origin via `?return=`/`?next=`. The dashboard chrome itself is gated, not the marketing pages.- **Two settings surfaces, intentionally separate:** `/settings` = identity/security/connections/danger (profile hub); `/dashboard/settings` = app/dashboard preferences (theme, sessions, notifications, network, storage/LLM meters, export). They share only the concept of "sessions" (each with its own UI and revoke calls).-- **Heavy 301 consolidation:** `/dashboard-classic/*` and many legacy `/dashboard/*` slugs (wallets, sessions, actions, memory, strategy, voice, sns, delegation, x402, storage, usage, agent-pumpfun) redirect to the canonical `/dashboard/*` pages in `vercel.json`. The Vite dev middleware mirrors only the `/dashboard-classic/*` family; the bare legacy slugs 301 in prod but have no dev equivalent.+- **Heavy 301 consolidation:** `/dashboard-classic/*` and many legacy `/dashboard/*` slugs (wallets, sessions, actions, memory, strategy, voice, sns, delegation, storage, usage, agent-pumpfun) redirect to the canonical `/dashboard/*` pages in `vercel.json`. `/dashboard/x402` is not one of them: it is its own page, served from `public/dashboard/x402.html`. The Vite dev middleware mirrors only the `/dashboard-classic/*` family; the bare legacy slugs 301 in prod but have no dev equivalent.diff --git a/docs/ux-flows/12-home-and-content.md b/docs/ux-flows/12-home-and-content.mdindex 28f8b6f2b..2b79cf112 100644--- a/docs/ux-flows/12-home-and-content.md+++ b/docs/ux-flows/12-home-and-content.md@@ -17,7 +17,7 @@ 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 (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.+- **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. The hero avatar is not simply the first curated entry: `src/home-live-agents.js` reads each candidate's `size_bytes` from one `GET /api/avatars/featured` response and picks the richest model inside a 2.5 MB budget (the smallest when nothing fits), because the hero GLB is fetched, parsed and uploaded to the GPU while the page is still trying to become interactive.- **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`.@@ -51,12 +51,12 @@ viewers), all confirmed against source.- **Embedded interactive widgets (in-page, no navigation required):**- **Hero agent**: live `<agent-3d>` + 7 animation chips + the hero forge bar.- **Playground (`#embed`)**: editable embed-code textarea (HTML/React/Vue tabs), mode chips (inline/widget), background chips plus a custom color picker (`#pg-color-trigger`/`#pg-color-hex`), an avatar row (`#pg-avatars`), feature toggles (responsive/nameplate/chat/eager), live `<agent-3d>` preview, 7 animation test chips (idle/wave/dance/capoeira/jump/thriller/celebrate), copy-code button.- - **Mini Forge (`#home-forge`, `src/home-forge.js`)**: real text-to-3D, now directly under the hero: prompt bar with typewriter suggestions (Tab to accept), example chips, POST `/api/forge` (tier `standard`, `backend: null` so the server's health-aware router picks the lane), poll `GET /api/forge?job=…`, live `<model-viewer>` result, session history rail (localStorage `forge:home:history`; a separate `forge:home:count` drives milestone nudges as the device's collection grows), result toolbar of 7 controls (auto-rotate toggle, Variation, Scene Studio → `/scene?model=…`, Embed sheet, Copy share link, GLB download, Clear), and an embed sheet (iframe/web-component snippets, size presets, copy, standalone link). Share copies a real OG-unfurling permalink `/forge/share/<creation_id>` for fresh forges, or a remix link `/?prompt=<encoded>&remix=1` for history-restored results; arriving with `?prompt=`/`&remix=1` auto-forges on load (the module boots eagerly when the URL carries a prompt). An "Options" disclosure (`src/home-forge-controls.js`) adds quality tiers (draft/standard/high, high gated behind $THREE holding), a live engine picker fed by `/api/forge?catalog` + `?health`, aspect ratio, and BYOK keys. Cancel/retry wired. Honest elapsed timer only.+ - **Mini Forge (`#home-forge`, `src/home-forge.js`)**: real text-to-3D, now directly under the hero: prompt bar with typewriter suggestions (Tab to accept), example chips, POST `/api/forge` (tier `standard`, `backend: null` so the server's health-aware router picks the lane), poll `GET /api/forge?job=…`, live `<model-viewer>` result, session history rail (localStorage `forge:home:history`; a separate `forge:home:count` drives milestone nudges as the device's collection grows), result toolbar of 7 controls (auto-rotate toggle, Variation, Scene Studio → `/scene?model=…`, Embed sheet, Copy share link, GLB download, Clear), and an embed sheet (iframe/web-component snippets, size presets, copy, standalone link). Share copies a real OG-unfurling permalink `/forge/share/<creation_id>` for fresh forges, or a remix link `/?prompt=<encoded>&remix=1` for history-restored results; arriving with `?prompt=`/`&remix=1` auto-forges on load (the module boots eagerly when the URL carries a prompt). An "Options" disclosure (`src/home-forge-controls.js`) adds quality tiers (draft/standard/high, high gated behind $THREE holding), a live engine picker fed by `/api/forge?catalog` + `?health`, aspect ratio, and BYOK keys. Cancel/retry wired. Honest elapsed timer only, plus a warming line while a scale-to-zero GPU lane boots: the poll frame carries `cold_start` and the lane's real boot budget, so `coldStartLabel()` (`src/shared/forge-frames.js`) says "Waking up a GPU: about Ns of boot left" instead of implying a slow render, the numbers come off the payload rather than a local clock, and the line clears on the first real "running" poll.- **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). 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.+ - **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 (the pulsing live chip is earned, not assumed: it needs the newest model in the list to be under six hours old, read off the timestamps rather than arrival order, so a stalled generation pipeline stops the chip instead of pulsing over two-day-old work), 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.@@ -64,6 +64,7 @@ viewers), all confirmed against source.- **Empty / error states:**- Mini Forge: 503/`unconfigured` → "The generator is offline right now" (with a try-again-in-a-bit tail); 429/`rate_limited` → "The forge is busy. Try again in about N seconds."; poll timeout → "Generation timed out" plus a try-a-simpler-single-subject-prompt hint; a high-tier request without the $THREE hold gets its own gate message; viewer load failure surfaced; explicit error state with **Try again** (re-runs `lastPrompt`) and **Cancel**.- API-fed sections (Oracle, Community Forge, Showcase) degrade gracefully if their fetch fails (sections render empty rather than break the page).+ - Hero avatar: a slow load adds a "Still loading the live agent" line with a Retry button; an outright failure lays a "The live preview couldn't load right now." card with Retry over the stage rather than wiping it, because disposing a mid-boot WebGL context is synchronous and cost more than the failure it was handling. A CDN failure that leaves `<agent-3d>` undefined falls into the same designed card instead of a silent black stage.- Reduced-motion respected throughout (typewriter, parallax, scanline disabled).- Clipboard blocked → fallback hidden input + `execCommand('copy')` with "Press ⌘/Ctrl-C" toast.- **Step count:** ~3 required to leave via a CTA (land → optional browse → click) **(+ many optional)**: the page exposes ~40 distinct CTAs and ~13 self-contained interactive widgets, each an optional sub-flow.@@ -81,8 +82,8 @@ viewers), all confirmed against source.### Features (index) — `/features`- **Source:** `pages/features.html` (static + 3D widgets; `/footer-newsletter.js`).- **Entry point:** `vercel.json` `/features → /features.html`. (Subpages `/features/*` covered elsewhere.)-- **Steps (7):** 1) Hero "Core" vs "Optional" pill nav scrolls to `#core`/`#optional`. 2) Animation showcase: ~31 pills swap a live `<model-viewer>` `src` (`/animations/*.glb`) with a "Now Playing" label. 3) Browse the **"New on three.ws"** strip (`#featNewGrid`): populated at runtime from `GET /changelog.json`, filtered to launches/feature-tagged entries, deduped, 6 newest rendered as cards (kind tag, date, title, summary) linking to the entry's page or `/changelog/<slug>`; skeletons while loading, and a fallback link to `/changelog` on fetch failure. 4) Copy embed snippet (`#embedCopyBtn` → clipboard, "Copied!" 2s). 5) Scroll-reveal cascade (IntersectionObserver). 6) Interact with multiple embedded `<model-viewer>` demos. 7) Newsletter signup (footer `data-newsletter-form` → `POST /api/newsletter/subscribe`).-- **Notes:** The only content fetch is `/changelog.json` for the newest strip; copy button + animation picker + newsletter form are the other real interactions.+- **Steps (7):** 1) Hero "Core" vs "Optional" pill nav scrolls to `#core`/`#optional`. 2) Animation showcase: ~31 pills swap a live `<model-viewer>` `src` (`/animations/*.glb`) with a "Now Playing" label. 3) Browse the **"New on three.ws"** strip (`#featNewGrid`): populated at runtime from `GET /changelog-recent.json` (the newest 150 entries; the full `/changelog.json` is the fallback when that file is missing), filtered to launches/feature-tagged entries, deduped, 6 newest rendered as cards (kind tag, date, title, summary) linking to the entry's page or `/changelog/<slug>`; skeletons while loading, and a fallback link to `/changelog` on fetch failure. 4) Copy embed snippet (`#embedCopyBtn` → clipboard, "Copied!" 2s). 5) Scroll-reveal cascade (IntersectionObserver). 6) Interact with multiple embedded `<model-viewer>` demos. 7) Newsletter signup (footer `data-newsletter-form` → `POST /api/newsletter/subscribe`).+- **Notes:** The only content fetch is the changelog feed for the newest strip; copy button + animation picker + newsletter form are the other real interactions.### Status — `/status`- **Source:** `pages/status.html` (dynamic).@@ -98,7 +99,7 @@ viewers), all confirmed against source.- **Source:** `pages/glossary.html` + `src/glossary/page.js`; term data inline in `public/glossary.js` (`window.twsGlossary.terms`, injected site-wide by `nav.js`).- **Entry point:** `vercel.json` `/glossary → /glossary.html`.- **Steps (4):** 1) Type in `#glos-q` search (rAF-debounced `applyFilter`, case-insensitive, filters cards). 2) Result count updates (`#glos-count` aria-live: "X terms" / "Y of X terms" / "No terms match '…'"). 3) Deep-link `#<term>` scrolls + flash-highlights a card (`highlightFromHash`). 4) Read a term card.-- **Notes:** No external API; terms are a static inline object (36 terms: usdc, sol, solana, evm, wallet, x402, pay-per-call, on-chain, mint, bonding curve, pump.fun, gas, mainnet, testnet, base, nft, ipfs, mcp, a2a, erc-8004, agent reputation, identity registry, reputation registry, validation registry, attestation, vouch, stake, sybil attack, metaplex core, agenc, trust grade, memo attestation, graduation, skills, brain, rig). page.js polls up to 6s for the injected glossary data (self-injecting `/glossary.js` if nav.js didn't).+- **Notes:** No external API; terms are a static inline object (36 terms: usdc, sol, solana, evm, wallet, x402, pay-per-call, on-chain, mint, bonding curve, pump.fun, gas, mainnet, testnet, base, nft, ipfs, mcp, a2a, erc-8004, agent reputation, identity registry, reputation registry, validation registry, attestation, vouch, stake, sybil attack, metaplex core, agenc, trust grade, memo attestation, graduation, skills, brain, rig). page.js polls up to 6s for the injected glossary data (self-injecting `/glossary.js` if nav.js didn't). Site-wide, the same script auto-underlines the first occurrence of each term and shows a tooltip; a page marks a subtree `[data-no-glossary]` to keep the scanner out of it (raw on-chain payloads, truncated labels), and the tooltip no longer puts tab stops inside `aria-hidden` content.### Support — `/support`- **Source:** `pages/support.html` (static).@@ -112,27 +113,30 @@ viewers), all confirmed against source.- **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`-- **Source:** `public/legal/index.html` (hub) plus one hand-authored static file per document: `privacy.html`, `tos.html`, `eula.html`, `content-policy.html`, `risk.html`, and `aws-marketplace-eula.html`.-- **Entry point:** `vercel.json` maps each with an optional trailing slash: `/legal/? → /legal/index.html`, `/legal/privacy/?`, `/legal/tos/?`, `/legal/eula/?`, `/legal/content-policy/?`, `/legal/risk/?`. `aws-marketplace-eula` has **no extensionless route**; the hub links it as `/legal/aws-marketplace-eula.html`, which resolves through the filesystem phase.-- **Steps (2):** 1) Land on the hub (h1 "Legal", three groups: Policies, Reporting something, Publishers) and pick a document. 2) Read it; follow cross-links (the documents reference each other, the hub links `/docs/news-rights`, and every page ends in `mailto:` contacts: legal@, privacy@, abuse@, dmca@, [email protected]).-- **The six documents:**+### Legal hub and policy documents - `/legal`, `/legal/privacy`, `/legal/tos`, `/legal/eula`, `/legal/content-policy`, `/legal/risk`, `/legal/agent-wallet`, `/legal/agreements`, `/legal/nvidia-ngc-eula`+- **Source:** `public/legal/index.html` (hub) plus one hand-authored static file per document: `privacy.html`, `tos.html`, `eula.html`, `content-policy.html`, `risk.html`, `agent-wallet.html`, `nvidia-ngc-eula.html`, and `aws-marketplace-eula.html`. The one non-static page is `agreements.html` + `public/legal/agreements.js`, the signing and review surface.+- **Entry point:** `vercel.json` maps each with an optional trailing slash: `/legal/? → /legal/index.html`, `/legal/privacy/?`, `/legal/tos/?`, `/legal/eula/?`, `/legal/content-policy/?`, `/legal/risk/?`, `/legal/agent-wallet/?`, `/legal/agreements/?`, `/legal/nvidia-ngc-eula/?`. `aws-marketplace-eula` has **no extensionless route**; the hub links it as `/legal/aws-marketplace-eula.html`, which resolves through the filesystem phase.+- **Steps (2):** 1) Land on the hub (h1 "Legal", three groups: Policies, Reporting something, Publishers) and pick a document. Real-Funds Agreements leads the Policies group, badged "Required before any real-funds action". 2) Read it; follow cross-links (the documents reference each other, the hub links `/docs/news-rights`, and every page ends in `mailto:` contacts: legal@, privacy@, abuse@, dmca@, [email protected]).+- **The documents:**| Path | Effective | Shape ||---|---|---|- | `/legal/privacy` | 2026-07-16, v2 | 16 h2 sections (through MCP Connectors / AI Processing, Free 3D Actions, Changes, Contact) |- | `/legal/tos` | 2026-07-16, v2 | 20 numbered sections (through Dispute Resolution with arbitration + class-action waiver, Governing Law, Termination, Changes, Miscellaneous, Contact) |- | `/legal/eula` | 2026-05-30, v1 | 16 numbered sections (License Grant, Restrictions, IP, Camera & Device Permissions, Customer Content, Blockchain & On-Chain Transactions, Third-Party Services, Confidentiality, warranties, liability, indemnification, term, export, governing law, entire agreement, contact) |+ | `/legal/privacy` | 2026-09-11, v3 | 17 h2 sections (through MCP Connectors / AI Processing, Free 3D Actions, Connected Homes, Changes, Contact) |+ | `/legal/tos` | 2026-09-17, v3 | 20 numbered sections; section 8 now covers Real-Funds Features, Agent Wallets and the Risk Disclosure together, and incorporates the Agent Wallet Agreement by reference |+ | `/legal/risk` | 2026-09-17, v2 | 10 numbered sections covering every real-funds surface (agent wallets, trading, sniping, autopilot, launches, swaps, withdrawals, x402, fiat onramps) |+ | `/legal/agent-wallet` | 2026-09-17, v1 | 17 numbered sections (custody, deposits at the depositor's own risk, no guaranteed withdrawal or recovery, no liability for loss, electronic signature and records) |+ | `/legal/eula` | 2026-07-14 | 16 numbered sections (License Grant, Restrictions, IP, Camera & Device Permissions, Customer Content, Blockchain & On-Chain Transactions, Third-Party Services, Confidentiality, warranties, liability, indemnification, term, export, governing law, entire agreement, contact) || `/legal/content-policy` | 2026-06-21 | 10 numbered sections (Scope, ownership warranty, Prohibited content, Agents/personas/AI output, Tokens & financial content, Marketplace & monetisation, Embedded agents, Reporting & enforcement, Changes, Contact) |- | `/legal/risk` | 2026-07-03 | 10 numbered sections covering every real-funds surface (agent wallets, trading, sniping, autopilot, launches, swaps, withdrawals, x402, fiat onramps) |+ | `/legal/nvidia-ngc-eula` | 2026-09-02 | License terms for the three.ws container images distributed through the NVIDIA NGC catalog || `/legal/aws-marketplace-eula.html` | static | AWS Marketplace standard EULA; reachable only from the hub |-- **Notes:** No TOC, no anchors, no API. The pages run the standard chrome (theme boot, `/nav.js`, `/footer.js`, `/i18n.js` runtime translation; most also load `/brand.js`) but every legal body is hand-authored static HTML. **`/legal/risk` is the one document wired into product flow:** section 9 documents that acceptance is versioned and recorded once per browser before a user's first real-funds action, that a material revision bumps the version and re-prompts, and that declining leaves the account usable for everything except real-funds actions. Treat that page as the human-readable spec for the acknowledgment gate, not as inert copy.+- **Real-Funds Agreements - `/legal/agreements`:** the only interactive page in this family. `public/legal/agreements.js` imports the canonical gate from `/risk-ack.js`, lists each document with its version, and fetches `GET /api/legal/risk-ack?history=1` to render one of four states: **Signed** (name + date, "real-funds features are unlocked"), **Signature required** (three.ws refuses real-funds actions from the account, app and API alike, until it is signed), **Not signed in** (sign in to attach the signature to the account, or "Sign without an account" to cover this browser only, which is what funding someone else's agent needs), and **Signed in this browser** (a browser-only signature that still needs one account-level signing). A signature history table lists each row's date, typed name, version (superseded marked as such) and the surface it was taken from. A failed status fetch renders "We could not load your agreement status." with a working Try again; existing signatures are unaffected.+- **Notes:** No TOC, no anchors, no API on the static documents. They run the standard chrome (theme boot, `/nav.js`, `/footer.js`, `/i18n.js` runtime translation; most also load `/brand.js`) but every legal body is hand-authored static HTML. **`/legal/risk` is wired into product flow:** section 9 documents that before a first real-funds action, and before an agent wallet's deposit address is shown, the visitor signs the Risk Disclosure, the Terms of Service and the Agent Wallet Agreement together by confirming each one and typing their name; that the signature record holds the typed name, the document versions, a fingerprint of the text signed, the time, the feature, the IP and the user agent; that a material revision bumps the version and re-prompts; and that declining leaves the account usable for everything except real-funds actions. Treat that page and `/legal/agent-wallet` as the human-readable spec for the gate, not as inert copy.### Tutorials index — `/tutorials`-- **Source:** `pages/tutorials.html` (client-rendered from `public/tutorials-manifest.js` → `window.TUTORIALS`, 69 entries, 3 tiers).+- **Source:** `pages/tutorials.html` (client-rendered from `public/tutorials-manifest.js` → `window.TUTORIALS`, 70 entries today, 3 tiers; count them from the manifest rather than trusting a number here).- **Entry point:** `vercel.json` `/tutorials → /tutorials.html`.-- **Steps (4):** 1) Use hero jump-links (`.tut-jump`, 3 tiers) to scroll. 2) Browse 69 tutorial cards (Easy 21 / Middle 25 / Advanced 23), grouped with section headers. 3) Click a card → `/tutorials/<slug>`. 4) Bottom CTA: "Open docs →" → `/docs`; "Read source on GitHub" (new tab).+- **Steps (4):** 1) Use hero jump-links (`.tut-jump`, 3 tiers) to scroll. 2) Browse the tutorial cards (Easy 21 / Middle 26 / Advanced 23 today), grouped with section headers. 3) Click a card → `/tutorials/<slug>`. 4) Bottom CTA: "Open docs →" → `/docs`; "Read source on GitHub" (new tab).- **Notes:** Dynamic render from the manifest `<script>`, no fetch. Hover: translateY + accent-bar.### Tutorial article template — `/tutorials/prompts-for-3d`, `/tutorials/generate-3d-api`@@ -141,6 +145,7 @@ 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.+- **Crawlers see a complete page, not the shell.** Because the content is fetched client-side, the submitted URLs used to carry no text, and this shell's static fallback read "Tutorial not found" under a blank `<h1>`, so a crawler that did not run the fetch banked a not-found page under a real URL. `server/crawler-body.mjs` now renders the same markdown into the shell server-side (the `/walkthroughs/<slug>` player gets the same treatment from `data/walkthroughs.json`), and the client replaces its root wholesale on load; both sides strip the markdown's leading title, which the hero already owns.- **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).@@ -177,15 +182,15 @@ viewers), all confirmed against source.- **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.### Changelog - `/changelog`, `/changelog/<slug>`-- **Source:** `public/changelog/index.html` (list) and `public/changelog/entry/index.html` (detail). Both are client-rendered from the generated feed; `data/changelog.json` is the authored source and `npm run build:pages` regenerates `public/changelog.json`, `public/changelog.xml`, and `CHANGELOG.md` from it.+- **Source:** `public/changelog/index.html` (list) and `public/changelog/entry/index.html` (detail). Both are client-rendered from the generated feed; `data/changelog.json` is the authored source and `npm run build:pages` regenerates `public/changelog.json`, `public/changelog-recent.json` (the newest 150 entries in the same envelope, plus `total` and `complete`), `public/changelog.xml`, and `CHANGELOG.md` from it.- **Entry point:** `vercel.json` `/changelog → /changelog/index.html`, `/changelog/([^.]+) → /changelog/entry/index.html` (one shell serves every entry; the slug is read from the URL), plus `/changelog.json` and `/changelog.xml` for the feeds.- **Prerequisites / gates:** None. Public, no auth.-- **Steps (4):** 1) Land: `GET /changelog.json`, entries grouped by date newest-first, each day headed by its formatted date and badged **new** when it is inside the 14-day `RECENT_DAYS` window. 2) Filter with the chip row (`all`, `launch`, `feature`, `improvement`, `fix`, `sdk`, `security`, `infra`, `docs`; `aria-pressed` tracks the active chip, and a `launch` entry also renders the page path it shipped). 3) Click an entry card → `/changelog/<date>-<slugified-title>`. 4) On the detail page the same feed is re-fetched and the entry matched by re-deriving that slug, then rendered with a Share row (X intent link + a copy-link button).-- **External calls:** `GET /changelog.json` (both pages).+- **Steps (4):** 1) Land: first paint reads `GET /changelog-recent.json`, entries grouped by date newest-first, each day headed by its formatted date and badged **new** when it is inside the 14-day `RECENT_DAYS` window. The full history is not downloaded to paint the page (`/changelog.json` is every launch since the site existed and grows forever); it is fetched once, on demand, when the reader clicks **Show older updates** or picks a filter that needs to look past the window, and a failed upgrade leaves the 150-entry window on screen instead of erroring. A missing `changelog-recent.json` (an older deploy, a cached shell) falls straight back to the full feed. 2) Filter with the chip row (`all`, `launch`, `feature`, `improvement`, `fix`, `sdk`, `security`, `infra`, `docs`; `aria-pressed` tracks the active chip, and a `launch` entry also renders the page path it shipped). 3) Click an entry card → `/changelog/<date>-<slugified-title>`. 4) On the detail page the recent window is tried first and the full feed only if the slug is not in it, matched by re-deriving that slug, then rendered with a Share row (X intent link + a copy-link button).+- **External calls:** `GET /changelog-recent.json` then, on demand, `GET /changelog.json` (both pages).- **Success state:** Filtered, dated list of shipped work; an entry page a holder can link to directly.- **Empty / error states:** A filter matching nothing renders a "nothing here for this filter yet, try another one" line rather than a blank column; a failed feed fetch renders an error that links the raw `/changelog.json`; an unmatched slug renders "Entry not found." with a back link to `/changelog`.- **Step count:** 1 required (read) (+3 optional: filter, open an entry, share).-- **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.+- **Notes:** `/changelog.json` is unchanged and stays the documented public feed; the recent window is a paint optimisation, not a new contract. 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 112 static article files `public/news/<slug>.html`.@@ -200,10 +205,10 @@ viewers), all confirmed against source.### Press kit - `/press`- **Source:** `pages/press/index.html` (static; `vercel.json` `/press → /press/index.html`).- **Entry point:** `/press`. Written for journalists: every asset is downloadable without asking permission.-- **Steps (5):** 1) Download the whole kit (`/brand/three-ws-press-kit.zip`). 2) Grab individual marks from **The marks** (`#prs-marks`): mark PNG, lockup on dark, lockup on light, stacked on dark, stacked on light, and the PWA icon SVG, each an anchor with `download`. 3) **OpenAI Partner Network** (`#prs-openai`): two announcement social cards plus a link to `/openai`. 4) **Boilerplate** (`#prs-boiler`): four copy buttons, one delegated click listener, label flips "Copy" to "Copied" for 1600 ms. 5) **Fast facts** (`#prs-facts-h`) table and **Contact** (`#prs-contact-h`), linking `/partners`, `/changelog`, GitHub, and X.+- **Steps (5):** 1) Download the whole kit (`/brand/three-ws-press-kit.zip`). 2) Grab individual marks from **The marks** (`#prs-marks`): mark PNG, lockup on dark, lockup on light, stacked on dark, stacked on light, and the PWA icon SVG, each an anchor with `download`; the quoted pixel dimensions live in `data-dims` spans that `scripts/render-brand-assets.mjs` rewrites from each PNG's own header when it regenerates the assets, so they cannot go stale against the files. 3) **OpenAI Partner Network** (`#prs-openai`): two announcement social cards plus a link to `/openai`. 4) **Boilerplate** (`#prs-boiler`): four copy buttons, one delegated click listener, label flips "Copy" to "Copied" for 1600 ms, with the same hover and press feedback as the download links. 5) **Fast facts** (`#prs-facts-h`) table and **Contact** (`#prs-contact-h`), linking `/partners`, `/changelog`, GitHub, and X.- **External calls:** None. Static assets served from `/brand/*` and `/partners/openai/*`.- **Success state:** A writer leaves with correct marks, current boilerplate, and a contact address.-- **Empty / error states:** N/A (static). **Known gap:** the copy handler returns early when `navigator.clipboard` is unavailable, so on a blocked-clipboard browser the button silently does nothing; `/support` handles the same case with a `execCommand('copy')` fallback and a toast.+- **Empty / error states:** N/A (static). A blocked or absent clipboard no longer dead-ends: the handler selects the boilerplate passage and flips the label to "Selected, press Cmd+C" / "Ctrl+C" (or "Copy by hand" when even the selection fails), which closes the gap this page used to have against `/support`.- **Step count:** 1 required (download or copy something) (+4 optional).---diff --git a/docs/vaults.md b/docs/vaults.mdindex abb4de8be..07484cc65 100644--- a/docs/vaults.md+++ b/docs/vaults.md@@ -32,6 +32,8 @@ Every write accepts either form of credential: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.+Every write additionally requires the caller's account to have signed the real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement). Opening a vault, resuming a paused one, depositing, redeeming, owner-trading and claiming fees each call `requireRealFundsAgreement` before anything is built, so an unsigned account gets `403 risk_ack_required` with a `sign_url`, over a session and an API key alike, and nothing moves. Signing once at [/legal/agreements](https://three.ws/legal/agreements) covers all of them; devnet is exempt, and no `GET` is ever gated. See [risk-acknowledgment.md](risk-acknowledgment.md).+The examples below use an API key in `$API_KEY`.## Opening a vaultdiff --git a/docs/walk-leaderboard.md b/docs/walk-leaderboard.mdindex b31fe1441..78d58608f 100644--- a/docs/walk-leaderboard.md+++ b/docs/walk-leaderboard.md@@ -97,7 +97,7 @@ The same batch also carries any achievement thresholds the runtime crossed this### What feeds the board today-Only the walk runtime in [src/walk.js](../src/walk.js) flushes metrics, so the board is fed by the pages that load it: `/temporary` (including the `/wk/:avatar` short link, which redirects there) and `/marketplace-walk`. The chrome-less embed runtime, [src/walk-embed.js](../src/walk-embed.js), is a deliberate fork of the same engine for iframes and does not currently flush, so `/walk/app` and the iframe embeds on the `/walk` landing page do not accrue leaderboard distance.+Only the walk runtime in [src/walk.js](../src/walk.js) flushes metrics, so the board is fed by the pages that load it: `/temporary` (including the `/wk/:avatar` short link, which redirects there) and `/marketplace-walk`. The chrome-less embed runtime, [src/walk-embed.js](../src/walk-embed.js), is a deliberate fork of the same engine for iframes and does not currently flush, so `/walk/app`, the iframe embeds on the `/walk` landing page, and `/pocket` (the handheld console whose screen is a `/walk-embed` iframe) do not accrue leaderboard distance.---diff --git a/docs/x402-distribution.md b/docs/x402-distribution.mdindex 9e5cb7ab8..81311bc32 100644--- a/docs/x402-distribution.md+++ b/docs/x402-distribution.md@@ -101,10 +101,13 @@ search results after 30 days without a settle**.`npx -y @agentcash/discovery@latest discover https://three.ws`, and a singleroute with`npx -y @agentcash/discovery@latest check https://three.ws/api/x402/crypto-intel`.- `check` reads the OpenAPI spec, so pass a route the spec actually carries (the- `/api/v1/x/*` proxy lane, `/api/mcp`, and the paid routes enumerated in- `openapi-json.js`); a route outside it answers `L3_NOT_FOUND` even though its- live 402 challenge is perfectly valid.+ `check` reads the OpenAPI spec, so pass a route the spec actually carries.+ Since 2026-09-02 that is every live, non-free service in the catalog: the spec+ projects each one into a paid operation (`catalogPaidPaths()`), so a new paid+ endpoint is listable the moment its descriptor lands, and hand-authored+ operations still win where they are richer. Routes outside the spec (anything+ not in the catalog, the `/api/v1/x/*` proxy lane and `/api/mcp` aside) still+ answer `L3_NOT_FOUND` even though their live 402 challenge is perfectly valid.- **Critical invariant — the `PAYMENT-REQUIRED` header carries the bazaarblock.** AgentCash's probe reads the 402 challenge from the `PAYMENT-REQUIRED`**response header** in preference to the JSON body, and checks